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