0
# Dustjs-LinkedIn
1

2
Dustjs-LinkedIn is an asynchronous JavaScript templating system designed for both browser and server-side environments. It provides a comprehensive templating syntax with compiled templates for high performance, supports streaming output, and includes features like conditional logic, loops, partials, helpers, and filters. This package is LinkedIn's actively maintained fork of the original Dust.js project.
3

4
## Package Information
5

6
- **Package Name**: dustjs-linkedin
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install dustjs-linkedin`
10

11
## Core Imports
12

13
```javascript
14
const dust = require('dustjs-linkedin');
15
```
16

17
For browser environments:
18

19
```html
20
<script src="node_modules/dustjs-linkedin/lib/dust.js"></script>
21
```
22

23
With full compiler support:
24

25
```javascript
26
const dust = require('dustjs-linkedin');
27
// Includes: dust (core), dust.compile, dust.parse
28
```
29

30
## Basic Usage
31

32
```javascript
33
const dust = require('dustjs-linkedin');
34

35
// Compile and register a template
36
const source = "Hello {name}! You have {count} {count eq 1 ? 'message' : 'messages'}.";
37
const compiled = dust.compile(source, 'greeting');
38
dust.loadSource(compiled);
39

40
// Render with data
41
dust.render('greeting', { name: 'John', count: 5 }, (err, output) => {
42
  if (err) throw err;
43
  console.log(output); // "Hello John! You have 5 messages."
44
});
45

46
// Stream rendering
47
dust.stream('greeting', { name: 'Jane', count: 1 })
48
  .on('data', chunk => process.stdout.write(chunk))
49
  .on('end', () => console.log('\nDone!'));
50
  // Output: "Hello Jane! You have 1 message."
51
```
52

53
## Architecture
54

55
Dustjs-LinkedIn is built around several key components:
56

57
- **Core Runtime**: Template execution engine with context system and streaming support
58
- **Template Compiler**: Converts Dust template syntax into executable JavaScript functions
59
- **Template Parser**: Parses template source into Abstract Syntax Tree using PEG.js
60
- **Helper System**: Extensible helper functions for complex template logic
61
- **Filter System**: Built-in and extensible filters for data transformation
62
- **CLI Tools**: Command-line compiler (`dustc`) for pre-compiling templates
63
- **Context System**: Stack-based data resolution with scoping and inheritance
64

65
## Configuration
66

67
```javascript { .api }
68
interface DustConfig {
69
  whitespace: boolean;    // Preserve whitespace in templates
70
  amd: boolean;          // Register templates as AMD modules
71
  cjs: boolean;          // Register templates as CommonJS modules
72
  cache: boolean;        // Enable template caching
73
}
74

75
const dust = {
76
  config: DustConfig;
77
  version: string;       // Current version: "3.0.1"
78
  cache: { [templateName: string]: TemplateFunction };
79
  helpers: { [helperName: string]: HelperFunction };
80
  filters: FiltersObject;
81
  debugLevel: string;    // 'NONE' | 'ERROR' | 'WARN' | 'INFO' | 'DEBUG'
82
  onLoad?: OnLoadFunction;
83
};
84
```
85

86
## Capabilities
87

88
### Template Rendering
89

90
Core template rendering functionality with callback and streaming support. Provides synchronous compilation with asynchronous rendering for optimal performance.
91

92
```javascript { .api }
93
function render(nameOrTemplate: string | TemplateFunction, context: any, callback: (err: Error | null, output?: string) => void): void;
94
function stream(nameOrTemplate: string | TemplateFunction, context: any): DustStream;
95
function register(name: string, compiledTemplate: TemplateFunction): void;
96
function loadSource(source: string): TemplateFunction;
97
```
98

99
[Template Rendering](./rendering.md)
100

101
### Template Compilation
102

103
Template compilation system that converts Dust template syntax into executable JavaScript. Includes source compilation, function compilation, and template registration.
104

105
```javascript { .api }
106
function compile(source: string, name?: string): string;
107
function compileFn(source: string, name?: string): TemplateFunction;
108
function loadSource(source: string): TemplateFunction;
109
```
110

111
[Template Compilation](./compilation.md)
112

113
### Template Parsing
114

115
Template parsing functionality that converts template source code into Abstract Syntax Trees using PEG.js generated parser.
116

117
```javascript { .api }
118
function parse(source: string): ASTNode;
119
```
120

121
[Template Parsing](./parsing.md)
122

123
### Context System
124

125
Stack-based context system for data resolution with scoping, inheritance, and block management.
126

127
```javascript { .api }
128
function context(global: any, options?: ContextOptions): Context;
129
function makeBase(global: any, options?: ContextOptions): Context;
130
```
131

132
[Context System](./context.md)
133

134
### Helper System
135

136
Extensible helper system for implementing complex template logic and custom functionality.
137

138
```javascript { .api }
139
const helpers: { [name: string]: HelperFunction };
140

141
type HelperFunction = (
142
  chunk: Chunk,
143
  context: Context,
144
  bodies: Bodies,
145
  params: Params
146
) => Chunk;
147
```
148

149
[Helper System](./helpers.md)
150

151
### Filter System
152

153
Built-in and extensible filtering system for data transformation with automatic escaping support.
154

155
```javascript { .api }
156
const filters: {
157
  h: (value: any) => string;      // HTML escape
158
  j: (value: any) => string;      // JavaScript string escape
159
  u: (value: any) => string;      // URL encode
160
  uc: (value: any) => string;     // URL component encode
161
  js: (value: any) => string;     // JSON stringify
162
  jp: (value: any) => any;        // JSON parse
163
};
164
```
165

166
[Filter System](./filters.md)
167

168
### Command Line Interface
169

170
Command-line tools for template compilation, watching, and build integration.
171

172
```bash { .api }
173
dustc [options] [path1 [path2 path3...]]
174

175
Options:
176
  -n, --name       Template name for single file
177
  -o, --output     Output file for concatenation
178
  -s, --split      Separate output files per input
179
  --pwd           Base directory for template names
180
  -w, --whitespace Preserve whitespace
181
  -a, --amd       Output AMD modules
182
  --cjs           Output CommonJS modules
183
  --watch         Watch files for changes
184
```
185

186
[Command Line Interface](./cli.md)
187

188
### Utility Functions
189

190
Core utility functions for type checking, validation, and debugging support.
191

192
```javascript { .api }
193
function isEmpty(value: any): boolean;           // Test if value is "dust empty"
194
function isEmptyObject(obj: any): boolean;       // Test if object is empty
195
function isArray(arr: any): boolean;             // Test if value is an array
196
function isTemplateFn(elem: any): boolean;       // Test if value is template function
197
function isThenable(elem: any): boolean;         // Test if value is promise-like
198
function isStreamable(elem: any): boolean;       // Test if value is streamable
199
function isContext(obj: any): boolean;           // Test if value is Context instance
200
function log(message: string | Error, type?: string): void;  // Logging function
201
function nextTick(callback: Function): void;     // Async execution utility
202
```
203

204
### Security Functions
205

206
Security-focused escaping functions for safe output generation.
207

208
```javascript { .api }
209
function escapeHtml(s: any): string;             // HTML entity escaping
210
function escapeJs(s: string): string;            // JavaScript string escaping
211
function escapeJSON(o: any): string;             // JSON escaping
212
function filter(string: any, auto: string | null, filters: string[], context: Context): string;
213
```
214

215
## Global Types
216

217
```javascript { .api }
218
interface TemplateFunction {
219
  (chunk: Chunk, context: Context): Chunk;
220
  __dustBody: true;
221
  templateName?: string;
222
}
223

224
interface DustStream {
225
  on(event: 'data', callback: (chunk: string) => void): DustStream;
226
  on(event: 'error', callback: (error: Error) => void): DustStream;
227
  on(event: 'end', callback: () => void): DustStream;
228
  emit(type: string, data?: any): boolean;
229
  pipe(writable: any): any;
230
}
231

232
interface Context {
233
  get(path: string | string[], cur?: boolean): any;
234
  push(head: any, idx?: number, len?: number): Context;
235
  pop(): any;
236
  current(): any;
237
  rebase(head: any): Context;
238
  clone(): Context;
239
  getBlock(key: string | Function): Function | boolean;
240
  shiftBlocks(locals: any): Context;
241
  resolve(body: Function): string;
242
  getTemplateName(): string;
243
}
244

245
interface ContextStatic {
246
  wrap(context: any, name?: string): Context;
247
}
248

249
interface Chunk {
250
  write(data: string): Chunk;
251
  end(data?: string): Chunk;
252
  render(body: any, context: Context): Chunk;
253
  map(callback: (chunk: Chunk) => any): Chunk;
254
  tap(tap: Function): Chunk;
255
  untap(): Chunk;
256
  reference(elem: any, context: Context, auto?: string, filters?: string[]): Chunk;
257
  section(elem: any, context: Context, bodies: Bodies, params?: Params): Chunk;
258
  exists(elem: any, context: Context, bodies: Bodies): Chunk;
259
  notexists(elem: any, context: Context, bodies: Bodies): Chunk;
260
  block(elem: Function, context: Context, bodies: Bodies): Chunk;
261
  partial(elem: string | Function, context: Context, partialContext?: Context, params?: Params): Chunk;
262
  helper(name: string, context: Context, bodies: Bodies, params?: Params, auto?: string): Chunk;
263
  await(thenable: any, context: Context, bodies: Bodies, auto?: string, filters?: string[]): Chunk;
264
  stream(stream: any, context: Context, bodies: Bodies, auto?: string, filters?: string[]): Chunk;
265
  capture(body: Function, context: Context, callback: (output: string, chunk: Chunk) => any): Chunk;
266
  setError(err: Error): Chunk;
267
}
268

269
interface Bodies {
270
  block?: TemplateFunction;
271
  else?: TemplateFunction;
272
}
273

274
interface Params {
275
  [key: string]: any;
276
}
277

278
interface ContextOptions {
279
  [key: string]: any;
280
}
281

282
interface ASTNode {
283
  [0]: string;  // Node type
284
  [1]?: any;    // Node attributes
285
  [2]?: ASTNode[];  // Child nodes
286
}
287

288
interface FiltersObject {
289
  h: (value: any) => string;      // HTML escape
290
  j: (value: any) => string;      // JavaScript string escape
291
  u: (value: any) => string;      // URL encode
292
  uc: (value: any) => string;     // URL component encode
293
  js: (value: any) => string;     // JSON stringify
294
  jp: (value: any) => any;        // JSON parse
295
  [filterName: string]: (value: any) => any;
296
}
297

298
type OnLoadFunction = (
299
  name: string,
300
  callback: (err: Error | null, template?: string | TemplateFunction) => void
301
) => void | (
302
  name: string,
303
  options: any,
304
  callback: (err: Error | null, template?: string | TemplateFunction) => void
305
) => void;
306
```