1 | // Type definitions for common-tags 1.8
|
2 | // Project: https://github.com/declandewet/common-tags
|
3 | // Definitions by: Viktor Zozuliak <https://github.com/zuzusik>
|
4 | // Paul Wang <https://github.com/tzupengwang>
|
5 | // BendingBender <https://github.com/BendingBender>
|
6 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
7 | // TypeScript Version: 2.3
|
8 |
|
9 | export as namespace commonTags;
|
10 |
|
11 | export type JSTag = (literals: TemplateStringsArray, ...placeholders: any[]) => string;
|
12 |
|
13 | export interface TemplateTag {
|
14 | (str: string): string;
|
15 | (tag: JSTag): TemplateTag;
|
16 | (literals: TemplateStringsArray, ...placeholders: any[]): string;
|
17 | }
|
18 |
|
19 | /**
|
20 | * You'll often find that you might want to include an array in a template.
|
21 | * Typically, doing something like `${array.join(', ')}` would work - but what if you're printing a list of items
|
22 | * in an HTML template and want to maintain the indentation? You'd have to count the spaces manually and include
|
23 | * them in the `.join()` call - which is a bit ugly for my taste.
|
24 | * This tag properly indents arrays, as well as newline characters in string substitutions,
|
25 | * by converting them to an array split by newline and re-using the same array inclusion logic.
|
26 | */
|
27 | export const html: TemplateTag;
|
28 |
|
29 | /**
|
30 | * alias for `html`
|
31 | */
|
32 | export const codeBlock: TemplateTag;
|
33 |
|
34 | /**
|
35 | * alias for `html`
|
36 | */
|
37 | export const source: TemplateTag;
|
38 |
|
39 | /**
|
40 | * A tag very similar to `html` but it does safe HTML escaping for strings coming from substitutions.
|
41 | * When combined with regular `html` tag, you can do basic HTML templating that is safe from
|
42 | * XSS (Cross-Site Scripting) attacks.
|
43 | */
|
44 | export const safeHtml: TemplateTag;
|
45 |
|
46 | /**
|
47 | * Allows you to keep your single-line strings under 80 characters without resorting to crazy string concatenation.
|
48 | */
|
49 | export const oneLine: TemplateTag;
|
50 |
|
51 | /**
|
52 | * Allows you to keep your single-line strings under 80 characters while trimming the new lines.
|
53 | */
|
54 | export const oneLineTrim: TemplateTag;
|
55 |
|
56 | /**
|
57 | * If you want to strip the initial indentation from the beginning of each line in a multiline string.
|
58 | * Important note: this tag will not indent multiline strings coming from the substitutions.
|
59 | * If you want that behavior, use the `html` tag (aliases: `source`, `codeBlock`).
|
60 | */
|
61 | export const stripIndent: TemplateTag;
|
62 |
|
63 | /**
|
64 | * If you want to strip *all* of the indentation from the beginning of each line in a multiline string.
|
65 | */
|
66 | export const stripIndents: TemplateTag;
|
67 |
|
68 | /**
|
69 | * Allows you to inline an array substitution as a list.
|
70 | */
|
71 | export const inlineLists: TemplateTag;
|
72 |
|
73 | /**
|
74 | * Allows you to inline an array substitution as a list, rendered out on a single line.
|
75 | */
|
76 | export const oneLineInlineLists: TemplateTag;
|
77 |
|
78 | /**
|
79 | * Allows you to inline an array substitution as a comma-separated list.
|
80 | */
|
81 | export const commaLists: TemplateTag;
|
82 |
|
83 | /**
|
84 | * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or".
|
85 | */
|
86 | export const commaListsOr: TemplateTag;
|
87 |
|
88 | /**
|
89 | * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and".
|
90 | */
|
91 | export const commaListsAnd: TemplateTag;
|
92 |
|
93 | /**
|
94 | * Allows you to inline an array substitution as a comma-separated list, and is rendered out on to a single line.
|
95 | */
|
96 | export const oneLineCommaLists: TemplateTag;
|
97 |
|
98 | /**
|
99 | * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or", and is rendered out on to a single line.
|
100 | */
|
101 | export const oneLineCommaListsOr: TemplateTag;
|
102 |
|
103 | /**
|
104 | * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and", and is rendered out on to a single line.
|
105 | */
|
106 | export const oneLineCommaListsAnd: TemplateTag;
|
107 |
|
108 | /**
|
109 | * A no-op tag that might come in useful in some scenarios, e.g. mocking.
|
110 | */
|
111 | export const id: TemplateTag;
|
112 |
|
113 | export interface TemplateTransformer<TCtx = { [key: string]: any }> {
|
114 | /**
|
115 | * Called before everything else.
|
116 | * The result of this hook will be passed to other hooks as `context`.
|
117 | * If omitted, `context` will be an empty object.
|
118 | */
|
119 | getInitialContext?: () => TCtx;
|
120 | /**
|
121 | * Called when the tag encounters a string.
|
122 | * (a string is whatever's not inside "${}" in your template literal)
|
123 | * `str` is the value of the current string
|
124 | */
|
125 | onString?: (str: string, context: TCtx) => string;
|
126 | /**
|
127 | * Called when the tag encounters a substitution.
|
128 | * (a substitution is whatever's inside "${}" in your template literal)
|
129 | * `substitution` is the value of the current substitution
|
130 | * `resultSoFar` is the end result up to the point of this substitution
|
131 | */
|
132 | onSubstitution?: (substitution: string, resultSoFar: string, context: TCtx) => string;
|
133 | /**
|
134 | * Called when all substitutions have been parsed
|
135 | * `endResult` is the final value.
|
136 | */
|
137 | onEndResult?: (endResult: string, context: TCtx) => string;
|
138 | }
|
139 |
|
140 | export type PluginFunction = (oldValue: string, newValue: string) => TemplateTransformer<any>;
|
141 |
|
142 | /**
|
143 | * New Tag factory
|
144 | */
|
145 | export function createTag(transformers?: Array<TemplateTransformer<any>>): TemplateTag;
|
146 | export function createTag(...transformers: Array<TemplateTransformer<any>>): TemplateTag;
|
147 | export function createTag(...pluginFunctions: PluginFunction[]): TemplateTag;
|
148 |
|
149 | export const TemplateTag: {
|
150 | /**
|
151 | * New Tag Constructor
|
152 | * @deprecated
|
153 | */
|
154 | new (transformers?: Array<TemplateTransformer<any>>): TemplateTag;
|
155 | new (...transformers: Array<TemplateTransformer<any>>): TemplateTag;
|
156 | new (...pluginFunctions: PluginFunction[]): TemplateTag;
|
157 | };
|
158 |
|
159 | /**
|
160 | * TemplateTag transformer that trims whitespace on the end result of a tagged template
|
161 | * @param [side=''] The side of the string to trim. Can be 'start' or 'end' (alternatively 'left' or 'right')
|
162 | * @return a TemplateTag transformer
|
163 | */
|
164 | export function trimResultTransformer(
|
165 | side?: 'start' | 'end' | 'left' | 'right' | ''
|
166 | ): TemplateTransformer;
|
167 |
|
168 | /**
|
169 | * strips indentation from a template literal
|
170 | * @param [type='initial'] whether to remove all indentation or just leading indentation. can be 'all' or 'initial'
|
171 | * @return a TemplateTag transformer
|
172 | */
|
173 | export function stripIndentTransformer(type?: 'initial' | 'all'): TemplateTransformer;
|
174 |
|
175 | /**
|
176 | * Replaces a value or pattern in the end result with a new value.
|
177 | * @param replaceWhat the value or pattern that should be replaced
|
178 | * @param replaceWith the replacement value
|
179 | * @return a TemplateTag transformer
|
180 | */
|
181 | export function replaceResultTransformer(
|
182 | replaceWhat: string | RegExp,
|
183 | replaceWith: string | ((substring: string, ...args: any[]) => string)
|
184 | ): TemplateTransformer;
|
185 |
|
186 | /**
|
187 | * Replaces the result of all substitutions (results of calling ${ ... }) with a new value.
|
188 | * Same as for `replaceResultTransformer`, replaceWhat can be a string or regular expression and replaceWith is the new value.
|
189 | */
|
190 | export function replaceSubstitutionTransformer(
|
191 | replaceWhat: string | RegExp,
|
192 | replaceWith: string | ((substring: string, ...args: any[]) => string)
|
193 | ): TemplateTransformer;
|
194 |
|
195 | /**
|
196 | * Replaces the result of all strings (what's not in ${ ... }) with a new value.
|
197 | * Same as for `replaceResultTransformer`, replaceWhat can be a string or regular expression and replaceWith is the new value.
|
198 | */
|
199 | export function replaceStringTransformer(
|
200 | replaceWhat: string | RegExp,
|
201 | replaceWith: string | ((substring: string, ...args: any[]) => string)
|
202 | ): TemplateTransformer;
|
203 |
|
204 | /**
|
205 | * Converts an array substitution to a string containing a list
|
206 | * @param [opts.separator=''] what to separate each item with (always followed by a space)
|
207 | * @param [opts.conjunction=''] replace the last separator with this value
|
208 | * @param [opts.serial=false] should the separator be included before the conjunction? As in the case of serial/oxford commas
|
209 | * @return a TemplateTag transformer
|
210 | */
|
211 | export function inlineArrayTransformer(opts?: {
|
212 | separator?: string;
|
213 | conjunction?: string;
|
214 | serial?: boolean;
|
215 | }): TemplateTransformer;
|
216 |
|
217 | /**
|
218 | * Splits a string substitution into an array by the provided splitBy substring, only if the string contains the splitBy substring.
|
219 | */
|
220 | export function splitStringTransformer(splitBy: string): TemplateTransformer;
|