0
# Utilities & Type System
1

2
Comprehensive utility functions for path handling, value coercion, type checking, and development support including file lookup, type assertions, and object manipulation.
3

4
## Capabilities
5

6
### Path Utilities
7

8
Functions for file system path operations and file discovery.
9

10
```javascript { .api }
11
/**
12
 * Lookup file in include paths
13
 * @param {string} path - File path to find
14
 * @param {string[]} paths - Array of search paths
15
 * @param {string} ignore - File extension to ignore
16
 * @returns {string|null} Found file path or null
17
 */
18
function lookup(path, paths, ignore);
19

20
/**
21
 * Find file in include paths (similar to lookup)
22
 * @param {string} path - File path to find
23
 * @param {string[]} paths - Array of search paths
24
 * @param {string} ignore - File extension to ignore
25
 * @returns {string|null} Found file path or null
26
 */
27
function find(path, paths, ignore);
28

29
/**
30
 * Lookup index file in directory
31
 * @param {string} path - Directory path
32
 * @param {string[]} paths - Array of search paths
33
 * @param {string} filename - Index filename (default: 'index')
34
 * @returns {string|null} Found index file path or null
35
 */
36
function lookupIndex(path, paths, filename);
37

38
/**
39
 * Get absolute path
40
 * @param {string} path - Path to make absolute
41
 * @returns {string} Absolute path
42
 */
43
function absolute(path);
44

45
/**
46
 * Join path components
47
 * @param {string} base - Base path
48
 * @param {string} path - Path to join
49
 * @returns {string} Joined path
50
 */
51
function join(base, path);
52

53
/**
54
 * Get directory name from path
55
 * @param {string} path - File path
56
 * @returns {string} Directory path
57
 */
58
function dirname(path);
59

60
/**
61
 * Get base filename from path
62
 * @param {string} path - File path
63
 * @param {string} ext - Extension to remove
64
 * @returns {string} Base filename
65
 */
66
function basename(path, ext);
67

68
/**
69
 * Get file extension
70
 * @param {string} path - File path
71
 * @returns {string} File extension
72
 */
73
function extname(path);
74

75
/**
76
 * Get relative path from one path to another
77
 * @param {string} from - Source path
78
 * @param {string} to - Target path
79
 * @returns {string} Relative path
80
 */
81
function relative(from, to);
82
```
83

84
### Value Utilities
85

86
Functions for working with Stylus values and expressions.
87

88
```javascript { .api }
89
/**
90
 * Coerce two values to same type for operations
91
 * @param {Node} left - Left operand
92
 * @param {Node} right - Right operand
93
 * @returns {Array} Array of coerced values [left, right]
94
 */
95
function coerce(left, right);
96

97
/**
98
 * Unwrap expression to get inner value
99
 * @param {Node} expr - Expression to unwrap
100
 * @returns {Node} Unwrapped value
101
 */
102
function unwrap(expr);
103

104
/**
105
 * Get function parameter names
106
 * @param {Function} fn - Function to analyze
107
 * @returns {string[]} Array of parameter names
108
 */
109
function params(fn);
110

111
/**
112
 * Merge two objects
113
 * @param {object} a - First object
114
 * @param {object} b - Second object
115
 * @returns {object} Merged object
116
 */
117
function merge(a, b);
118

119
/**
120
 * Clone an object
121
 * @param {object} obj - Object to clone
122
 * @returns {object} Cloned object
123
 */
124
function clone(obj);
125
```
126

127
### Type Checking and Assertions
128

129
Functions for validating node types and values.
130

131
```javascript { .api }
132
/**
133
 * Assert that node exists (not null/undefined)
134
 * @param {Node} node - Node to check
135
 * @param {string} name - Parameter name for error
136
 * @throws {TypeError} If node is null/undefined
137
 */
138
function assertPresent(node, name);
139

140
/**
141
 * Assert that node is a string
142
 * @param {Node} node - Node to check
143
 * @param {string} name - Parameter name for error
144
 * @returns {String} String node
145
 * @throws {TypeError} If not a string
146
 */
147
function assertString(node, name);
148

149
/**
150
 * Assert that node is a color
151
 * @param {Node} node - Node to check
152
 * @param {string} name - Parameter name for error
153
 * @returns {RGBA} Color node
154
 * @throws {TypeError} If not a color
155
 */
156
function assertColor(node, name);
157

158
/**
159
 * Assert that node is a boolean
160
 * @param {Node} node - Node to check
161
 * @param {string} name - Parameter name for error
162
 * @returns {Boolean} Boolean node
163
 * @throws {TypeError} If not a boolean
164
 */
165
function assertBoolean(node, name);
166

167
/**
168
 * Assert that node is a specific type
169
 * @param {Node} node - Node to check
170
 * @param {string} type - Expected type name
171
 * @param {string} name - Parameter name for error
172
 * @returns {Node} Typed node
173
 * @throws {TypeError} If not the expected type
174
 */
175
function assertType(node, type, name);
176
```
177

178
### Visitor Classes
179

180
Classes for traversing and manipulating AST nodes.
181

182
```javascript { .api }
183
/**
184
 * Base visitor class for AST traversal
185
 */
186
class Visitor {
187
  constructor(root);
188
  
189
  /**
190
   * Visit a node based on its type
191
   * @param {Node} node - Node to visit
192
   * @returns {Node} Visited node
193
   */
194
  visit(node);
195
  
196
  /**
197
   * Visit a generic node
198
   * @param {Node} node - Node to visit
199
   * @returns {Node} Visited node
200
   */
201
  visitNode(node);
202
}
203

204
/**
205
 * Evaluator for executing Stylus AST
206
 */
207
class Evaluator extends Visitor {
208
  constructor(root, options);
209
  
210
  /**
211
   * Evaluate the AST
212
   * @returns {Node} Evaluated result
213
   */
214
  evaluate();
215
  
216
  /**
217
   * Visit and evaluate specific node types
218
   * @param {Node} node - Node to evaluate
219
   * @returns {Node} Evaluated result
220
   */
221
  visitRule(node);
222
  visitProperty(node);
223
  visitExpression(node);
224
  visitBinOp(node);
225
  visitFunction(node);
226
  visitCall(node);
227
  visitIf(node);
228
  visitEach(node);
229
  visitFor(node);
230
}
231

232
/**
233
 * Compiler for generating CSS from evaluated AST
234
 */
235
class Compiler extends Visitor {
236
  constructor(root, options);
237
  
238
  /**
239
   * Compile AST to CSS string
240
   * @returns {string} Generated CSS
241
   */
242
  compile();
243
  
244
  /**
245
   * Visit and compile specific node types
246
   * @param {Node} node - Node to compile
247
   * @returns {string} CSS fragment
248
   */
249
  visitRule(node);
250
  visitProperty(node);
251
  visitMedia(node);
252
  visitKeyframes(node);
253
  visitComment(node);
254
}
255

256
/**
257
 * Normalizer for AST preprocessing
258
 */
259
class Normalizer extends Visitor {
260
  constructor(root, options);
261
  
262
  /**
263
   * Normalize the AST
264
   * @returns {Node} Normalized AST
265
   */
266
  normalize();
267
  
268
  /**
269
   * Visit and normalize specific node types
270
   * @param {Node} node - Node to normalize
271
   * @returns {Node} Normalized node
272
   */
273
  visitRule(node);
274
  visitProperty(node);
275
  visitSelector(node);
276
  visitExpression(node);
277
}
278
```
279

280
## Usage Examples
281

282
```javascript
283
const stylus = require('stylus');
284
const utils = stylus.utils;
285

286
// Path utilities
287
const paths = ['./styles', './node_modules'];
288
const foundFile = utils.lookup('variables.styl', paths);
289
const absolutePath = utils.absolute('./styles/main.styl');
290
const joined = utils.join('/styles', 'components.styl');
291

292
// Value utilities
293
const { nodes } = stylus;
294
const expr1 = new nodes.Unit(10, 'px');
295
const expr2 = new nodes.Unit(5, 'em');
296
const [coerced1, coerced2] = utils.coerce(expr1, expr2);
297

298
// Type checking
299
function customFunction(color, amount) {
300
  utils.assertColor(color, 'color');
301
  utils.assertType(amount, 'unit', 'amount');
302
  
303
  // Function logic here
304
  return new nodes.RGBA(255, 0, 0, 1);
305
}
306

307
// Visitor pattern
308
const evaluator = new stylus.Evaluator(ast);
309
const result = evaluator.evaluate();
310

311
const compiler = new stylus.Compiler(result);
312
const css = compiler.compile();
313
```
314

315
## Types
316

317
```javascript { .api }
318
// Visitor options
319
interface VisitorOptions {
320
  /** Include imported files */
321
  imports?: string[];
322
  /** Custom functions */
323
  functions?: object;
324
  /** Global variables */
325
  globals?: object;
326
  /** Compress output */
327
  compress?: boolean;
328
  /** Source filename */
329
  filename?: string;
330
}
331

332
// Evaluator-specific options
333
interface EvaluatorOptions extends VisitorOptions {
334
  /** Warn on undefined variables */
335
  warn?: boolean;
336
  /** Resolve URLs */
337
  resolveURL?: boolean;
338
  /** Include CSS imports */
339
  includeCSS?: boolean;
340
}
341

342
// Compiler-specific options
343
interface CompilerOptions extends VisitorOptions {
344
  /** Include line numbers */
345
  linenos?: boolean;
346
  /** Firebug debug info */
347
  firebug?: boolean;
348
  /** Indent string */
349
  indent?: string;
350
  /** Generate source map */
351
  sourcemap?: boolean;
352
}
353
```