1 | // Type definitions for ejs 3.0
|
2 | // Project: http://ejs.co/, https://github.com/mde/ejs
|
3 | // Definitions by: Ben Liddicott <https://github.com/benliddicott>
|
4 | // ExE Boss <https://github.com/ExE-Boss>
|
5 | // Piotr Błażejewicz <https://github.com/peterblazejewicz>
|
6 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
7 | // TypeScript Version: 2.4
|
8 |
|
9 | export as namespace ejs;
|
10 |
|
11 | /**
|
12 | * Version of EJS.
|
13 | */
|
14 | export const VERSION: string;
|
15 |
|
16 | /**
|
17 | * Name for detection of EJS.
|
18 | */
|
19 | export const name: 'ejs';
|
20 |
|
21 | /**
|
22 | * Get the path to the included file from the parent file path and the
|
23 | * specified path.
|
24 | *
|
25 | * @param name specified path
|
26 | * @param filename parent file path
|
27 | * @param isDir whether the parent file path is a directory
|
28 | */
|
29 | export function resolveInclude(name: string, filename: string, isDir?: boolean): string;
|
30 |
|
31 | /**
|
32 | * Compile the given `str` of ejs into a template function.
|
33 | */
|
34 | export function compile(template: string, opts: Options & { async: true; client?: false | undefined }): AsyncTemplateFunction;
|
35 | export function compile(template: string, opts: Options & { async: true; client: true }): AsyncClientFunction;
|
36 | export function compile(template: string, opts?: Options & { async?: false | undefined; client?: false | undefined }): TemplateFunction;
|
37 | export function compile(template: string, opts?: Options & { async?: false | undefined; client: true }): ClientFunction;
|
38 | export function compile(template: string, opts?: Options): TemplateFunction | AsyncTemplateFunction;
|
39 |
|
40 | /**
|
41 | * Render the given `template` of ejs.
|
42 | *
|
43 | * If you would like to include options but not data, you need to explicitly
|
44 | * call this function with `data` being an empty object or `null`.
|
45 | */
|
46 | export function render(template: string, data?: Data, opts?: Options & { async: false }): string;
|
47 | export function render(template: string, data: Data | undefined, opts: Options & { async: true }): Promise<string>;
|
48 | export function render(template: string, data: Data | undefined, opts: Options & { async?: never | undefined }): string;
|
49 | export function render(template: string, data?: Data, opts?: Options): string | Promise<string>;
|
50 |
|
51 | /**
|
52 | * Callback for receiving data from `renderFile`.
|
53 | *
|
54 | * @param err error, if any resulted from the rendering process
|
55 | * @param str output string, is `undefined` if there is an error
|
56 | */
|
57 | export type RenderFileCallback<T> = (err: Error | null, str: string) => T;
|
58 |
|
59 | /**
|
60 | * Render an EJS file at the given `path` and callback `cb(err, str)`.
|
61 | *
|
62 | * If you would like to include options but not data, you need to explicitly
|
63 | * call this function with `data` being an empty object or `null`.
|
64 | */
|
65 | export function renderFile<T>(path: string, cb: RenderFileCallback<T>): T;
|
66 | export function renderFile<T>(path: string, data: Data, cb: RenderFileCallback<T>): T;
|
67 | export function renderFile<T>(path: string, data: Data, opts: Options, cb: RenderFileCallback<T>): T;
|
68 | export function renderFile(path: string, data?: Data, opts?: Options): Promise<string>;
|
69 |
|
70 | /**
|
71 | * Clear intermediate JavaScript cache. Calls {@link Cache#reset}.
|
72 | */
|
73 | export function clearCache(): void;
|
74 |
|
75 | /**
|
76 | * EJS template function cache. This can be a LRU object from lru-cache
|
77 | * NPM module. By default, it is `utils.cache`, a simple in-process
|
78 | * cache that grows continuously.
|
79 | */
|
80 | export let cache: Cache;
|
81 |
|
82 | /**
|
83 | * Custom file loader. Useful for template preprocessing or restricting access
|
84 | * to a certain part of the filesystem.
|
85 | *
|
86 | * @param path the path of the file to be read
|
87 | * @return the contents of the file as a string or object that implements the toString() method
|
88 | *
|
89 | * @default fs.readFileSync
|
90 | */
|
91 | export type fileLoader = (path: string) => string | { toString(): string };
|
92 | export let fileLoader: fileLoader;
|
93 |
|
94 | /**
|
95 | * Name of the object containing the locals.
|
96 | *
|
97 | * This variable is overridden by {@link Options}`.localsName` if it is not
|
98 | * `undefined`.
|
99 | *
|
100 | * @default 'locals'
|
101 | */
|
102 | export let localsName: string;
|
103 |
|
104 | /**
|
105 | * The opening delimiter for all statements. This allows you to clearly delinate
|
106 | * the difference between template code and existing delimiters. (It is recommended
|
107 | * to synchronize this with the closeDelimiter property.)
|
108 | *
|
109 | * @default '<'
|
110 | */
|
111 | export let openDelimiter: string;
|
112 |
|
113 | /**
|
114 | * The closing delimiter for all statements. This allows to to clearly delinate
|
115 | * the difference between template code and existing delimiters. (It is recommended
|
116 | * to synchronize this with the openDelimiter property.)
|
117 | *
|
118 | * @default '>'
|
119 | */
|
120 | export let closeDelimiter: string;
|
121 |
|
122 | /**
|
123 | * The delimiter used in template compilation.
|
124 | *
|
125 | * @default '%'
|
126 | */
|
127 | export let delimiter: string | undefined;
|
128 |
|
129 | /**
|
130 | * Promise implementation -- defaults to the native implementation if available
|
131 | * This is mostly just for testability
|
132 | *
|
133 | * @default Promise
|
134 | */
|
135 | export let promiseImpl: PromiseConstructorLike | undefined;
|
136 |
|
137 | /**
|
138 | * Escape characters reserved in XML.
|
139 | *
|
140 | * This is simply an export of `utils.escapeXML`.
|
141 | *
|
142 | * If `markup` is `undefined` or `null`, the empty string is returned.
|
143 | */
|
144 | export function escapeXML(markup?: any): string;
|
145 |
|
146 | export class Template {
|
147 | /**
|
148 | * The EJS template source text.
|
149 | */
|
150 | readonly templateText: string;
|
151 |
|
152 | /**
|
153 | * The compiled JavaScript function source, or the empty string
|
154 | * if the template hasn't been compiled yet.
|
155 | */
|
156 | readonly source: string;
|
157 |
|
158 | constructor(text: string, opts?: Options);
|
159 |
|
160 | /**
|
161 | * Compiles the EJS template.
|
162 | */
|
163 | compile(): TemplateFunction | AsyncTemplateFunction | ClientFunction | AsyncClientFunction;
|
164 | }
|
165 |
|
166 | export namespace Template {
|
167 | enum modes {
|
168 | EVAL = 'eval',
|
169 | ESCAPED = 'escaped',
|
170 | RAW = 'raw',
|
171 | COMMENT = 'comment',
|
172 | LITERAL = 'literal',
|
173 | }
|
174 | }
|
175 |
|
176 | export interface Data {
|
177 | [name: string]: any;
|
178 | }
|
179 |
|
180 | /**
|
181 | * This type of function is returned from `compile`, when
|
182 | * `Options.client` is false.
|
183 | *
|
184 | * @param data an object of data to be passed into the template.
|
185 | * @return Return type depends on `Options.async`.
|
186 | */
|
187 | export type TemplateFunction = (data?: Data) => string;
|
188 |
|
189 | /**
|
190 | * This type of function is returned from `compile`, when
|
191 | * `Options.client` is false.
|
192 | *
|
193 | * @param data an object of data to be passed into the template.
|
194 | * @return Return type depends on `Options.async`.
|
195 | */
|
196 | export type AsyncTemplateFunction = (data?: Data) => Promise<string>;
|
197 |
|
198 | /**
|
199 | * This type of function is returned from `compile`, when
|
200 | * `Options.client` is true.
|
201 | *
|
202 | *
|
203 | * This is also used internally to generate a `TemplateFunction`.
|
204 | *
|
205 | * @param locals an object of data to be passed into the template.
|
206 | * The name of this variable is adjustable through `localsName`.
|
207 | *
|
208 | * @param escape callback used to escape variables
|
209 | * @param include callback used to include files at runtime with `include()`
|
210 | * @param rethrow callback used to handle and rethrow errors
|
211 | *
|
212 | * @return Return type depends on `Options.async`.
|
213 | */
|
214 | export type ClientFunction = (
|
215 | locals?: Data,
|
216 | escape?: EscapeCallback,
|
217 | include?: IncludeCallback,
|
218 | rethrow?: RethrowCallback,
|
219 | ) => string;
|
220 |
|
221 | /**
|
222 | * This type of function is returned from `compile`, when
|
223 | * `Options.client` is true.
|
224 | *
|
225 | *
|
226 | * This is also used internally to generate a `TemplateFunction`.
|
227 | *
|
228 | * @param locals an object of data to be passed into the template.
|
229 | * The name of this variable is adjustable through `localsName`.
|
230 | *
|
231 | * @param escape callback used to escape variables
|
232 | * @param include callback used to include files at runtime with `include()`
|
233 | * @param rethrow callback used to handle and rethrow errors
|
234 | *
|
235 | * @return Return type depends on `Options.async`.
|
236 | */
|
237 | export type AsyncClientFunction = (
|
238 | locals?: Data,
|
239 | escape?: EscapeCallback,
|
240 | include?: IncludeCallback,
|
241 | rethrow?: RethrowCallback,
|
242 | ) => Promise<string>;
|
243 |
|
244 | /**
|
245 | * Escapes a string using HTML/XML escaping rules.
|
246 | *
|
247 | * Returns the empty string for `null` or `undefined`.
|
248 | *
|
249 | * @param markup Input string
|
250 | * @return Escaped string
|
251 | */
|
252 | export type EscapeCallback = (markup?: any) => string;
|
253 |
|
254 | /**
|
255 | * This type of callback is used when `Options.compileDebug`
|
256 | * is `true`, and an error in the template is thrown.
|
257 | *
|
258 | * By default it is used to rethrow an error in a better-formatted way.
|
259 | *
|
260 | * @param err Error object
|
261 | * @param str full EJS source
|
262 | * @param filename file name of the EJS source
|
263 | * @param lineno line number of the error
|
264 | */
|
265 | export type RethrowCallback = (
|
266 | err: Error,
|
267 | str: string,
|
268 | filename: string | null | undefined,
|
269 | lineno: number,
|
270 | esc: EscapeCallback,
|
271 | ) => never;
|
272 |
|
273 | /**
|
274 | * The callback called by `ClientFunction` to include files at runtime with `include()`
|
275 | *
|
276 | * @param path Path to be included
|
277 | * @param data Data passed to the template
|
278 | * @return Contents of the file requested
|
279 | */
|
280 | export type IncludeCallback = (path: string, data?: Data) => string;
|
281 |
|
282 | export interface Options {
|
283 | /**
|
284 | * Log the generated JavaScript source for the EJS template to the console.
|
285 | *
|
286 | * @default false
|
287 | */
|
288 | debug?: boolean | undefined;
|
289 |
|
290 | /**
|
291 | * Include additional runtime debugging information in generated template
|
292 | * functions.
|
293 | *
|
294 | * @default true
|
295 | */
|
296 | compileDebug?: boolean | undefined;
|
297 |
|
298 | /**
|
299 | * Whether or not to use `with () {}` construct in the generated template
|
300 | * functions. If set to `false`, data is still accessible through the object
|
301 | * whose name is specified by `ejs.localsName` (defaults to `locals`).
|
302 | *
|
303 | * @default true
|
304 | */
|
305 | _with?: boolean | undefined;
|
306 |
|
307 | /**
|
308 | * Whether to run in strict mode or not.
|
309 | * Enforces `_with=false`.
|
310 | *
|
311 | * @default false
|
312 | */
|
313 | strict?: boolean | undefined;
|
314 |
|
315 | /**
|
316 | * An array of local variables that are always destructured from `localsName`,
|
317 | * available even in strict mode.
|
318 | *
|
319 | * @default []
|
320 | */
|
321 | destructuredLocals?: string[] | undefined;
|
322 |
|
323 | /**
|
324 | * Remove all safe-to-remove whitespace, including leading and trailing
|
325 | * whitespace. It also enables a safer version of `-%>` line slurping for all
|
326 | * scriptlet tags (it does not strip new lines of tags in the middle of a
|
327 | * line).
|
328 | *
|
329 | * @default false
|
330 | */
|
331 | rmWhitespace?: boolean | undefined;
|
332 |
|
333 | /**
|
334 | * Whether or not to compile a `ClientFunction` that can be rendered
|
335 | * in the browser without depending on ejs.js. Otherwise, a `TemplateFunction`
|
336 | * will be compiled.
|
337 | *
|
338 | * @default false
|
339 | */
|
340 | client?: boolean | undefined;
|
341 |
|
342 | /**
|
343 | * The escaping function used with `<%=` construct. It is used in rendering
|
344 | * and is `.toString()`ed in the generation of client functions.
|
345 | *
|
346 | * @default ejs.escapeXML
|
347 | */
|
348 | escape?: EscapeCallback | undefined;
|
349 |
|
350 | /**
|
351 | * The filename of the template. Required for inclusion and caching unless
|
352 | * you are using `renderFile`. Also used for error reporting.
|
353 | *
|
354 | * @default undefined
|
355 | */
|
356 | filename?: string | undefined;
|
357 |
|
358 | /**
|
359 | * The path to the project root. When this is set, absolute paths for includes
|
360 | * (/filename.ejs) will be relative to the project root.
|
361 | *
|
362 | * @default undefined
|
363 | */
|
364 | root?: string | undefined;
|
365 |
|
366 | /**
|
367 | * The opening delimiter for all statements. This allows you to clearly delinate
|
368 | * the difference between template code and existing delimiters. (It is recommended
|
369 | * to synchronize this with the closeDelimiter property.)
|
370 | *
|
371 | * @default ejs.openDelimiter
|
372 | */
|
373 | openDelimiter?: string | undefined;
|
374 |
|
375 | /**
|
376 | * The closing delimiter for all statements. This allows to to clearly delinate
|
377 | * the difference between template code and existing delimiters. (It is recommended
|
378 | * to synchronize this with the openDelimiter property.)
|
379 | *
|
380 | * @default ejs.closeDelimiter
|
381 | */
|
382 | closeDelimiter?: string | undefined;
|
383 |
|
384 | /**
|
385 | * Character to use with angle brackets for open/close
|
386 | * @default '%'
|
387 | */
|
388 | delimiter?: string | undefined;
|
389 |
|
390 | /**
|
391 | * Whether or not to enable caching of template functions. Beware that
|
392 | * the options of compilation are not checked as being the same, so
|
393 | * special handling is required if, for example, you want to cache client
|
394 | * and regular functions of the same file.
|
395 | *
|
396 | * Requires `filename` to be set. Only works with rendering function.
|
397 | *
|
398 | * @default false
|
399 | */
|
400 | cache?: boolean | undefined;
|
401 |
|
402 | /**
|
403 | * The Object to which `this` is set during rendering.
|
404 | *
|
405 | * @default this
|
406 | */
|
407 | context?: any;
|
408 |
|
409 | /**
|
410 | * Whether or not to create an async function instead of a regular function.
|
411 | * This requires language support.
|
412 | *
|
413 | * @default false
|
414 | */
|
415 | async?: boolean | undefined;
|
416 |
|
417 | /**
|
418 | * Make sure to set this to 'false' in order to skip UglifyJS parsing,
|
419 | * when using ES6 features (`const`, etc) as UglifyJS doesn't understand them.
|
420 | * @default true
|
421 | */
|
422 | beautify?: boolean | undefined;
|
423 |
|
424 | /**
|
425 | * Name to use for the object storing local variables when not using `with` or destructuring.
|
426 | *
|
427 | * @default ejs.localsName
|
428 | */
|
429 | localsName?: string | undefined;
|
430 |
|
431 | /** Set to a string (e.g., 'echo' or 'print') for a function to print output inside scriptlet tags. */
|
432 | outputFunctionName?: string | undefined;
|
433 |
|
434 | /**
|
435 | * An array of paths to use when resolving includes with relative paths
|
436 | */
|
437 | views?: string[] | undefined;
|
438 | }
|
439 |
|
440 | export interface Cache {
|
441 | /**
|
442 | * Cache the intermediate JavaScript function for a template.
|
443 | *
|
444 | * @param key key for caching
|
445 | * @param val cached function
|
446 | */
|
447 | set(key: string, val: TemplateFunction): void;
|
448 |
|
449 | /**
|
450 | * Get the cached intermediate JavaScript function for a template.
|
451 | *
|
452 | * @param key key for caching
|
453 | */
|
454 | get(key: string): TemplateFunction | undefined;
|
455 |
|
456 | /**
|
457 | * Clear the entire cache.
|
458 | */
|
459 | reset(): void;
|
460 | }
|