0
# Sass Type System
1

2
Complete type system for creating and manipulating Sass values in custom functions, providing JavaScript interfaces for all Sass data types including colors, numbers, strings, lists, and maps.
3

4
## Core Imports
5

6
```javascript
7
const sass = require("node-sass");
8
```
9

10
Access types via:
11

12
```javascript
13
const { types } = sass;
14
// or
15
const types = sass.types;
16
```
17

18
## Capabilities
19

20
### Boolean Type
21

22
Represents Sass boolean values with singleton instances for true and false.
23

24
```javascript { .api }
25
/**
26
 * Create or get Sass boolean value (call syntax only, new throws TypeError)
27
 * @param value - JavaScript boolean value
28
 * @returns Singleton TRUE or FALSE instance
29
 */
30
function Boolean(value);                // Call syntax only
31

32
// Singleton constants
33
Boolean.TRUE;                       // Sass true singleton
34
Boolean.FALSE;                      // Sass false singleton
35

36
// Instance methods
37
getValue();                         // Returns JavaScript boolean
38
```
39

40
**Singleton Access:**
41

42
The Boolean type provides singleton instances for true and false values:
43

44
```javascript { .api }
45
// Available singleton constants
46
sass.types.Boolean.TRUE;            // Sass true singleton
47
sass.types.Boolean.FALSE;           // Sass false singleton
48

49
// Also available as direct module exports
50
sass.TRUE;                          // Same as sass.types.Boolean.TRUE
51
sass.FALSE;                         // Same as sass.types.Boolean.FALSE
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const sass = require("node-sass");
58

59
// Get boolean singletons (multiple ways)
60
const sassTrue1 = sass.types.Boolean(true);
61
const sassTrue2 = sass.types.Boolean.TRUE;
62
const sassTrue3 = sass.TRUE;  // Direct export
63

64
const sassFalse1 = sass.types.Boolean(false);
65
const sassFalse2 = sass.types.Boolean.FALSE;
66
const sassFalse3 = sass.FALSE;  // Direct export
67

68
// All TRUE variants are the same singleton
69
console.log(sassTrue1 === sassTrue2);  // true
70
console.log(sassTrue2 === sassTrue3);  // true
71

72
// Check values
73
console.log(sassTrue1.getValue());   // true
74
console.log(sassFalse1.getValue());  // false
75

76
// Use in custom functions
77
sass.render({
78
  data: ".test { display: if(is-mobile(), block, none); }",
79
  functions: {
80
    "is-mobile()": function(done) {
81
      const isMobile = false; // Example condition
82
      done(sass.types.Boolean(isMobile));
83
    }
84
  }
85
});
86
```
87

88
### Color Type
89

90
Represents Sass color values with RGBA components.
91

92
```javascript { .api }
93
/**
94
 * Create Sass color value
95
 * Supports 0, 1, 3, or 4 arguments (not 2)
96
 * @param r - Red component (0-255), default 0
97
 * @param g - Green component (0-255), default 0  
98
 * @param b - Blue component (0-255), default 0
99
 * @param a - Alpha component (0-1), default 1
100
 */
101
function Color();                       // Black (0,0,0,1)
102
function Color(b);                      // (0,0,b,0) 
103
function Color(r, g, b);                // RGB with alpha=1
104
function Color(r, g, b, a);             // Full RGBA
105

106
// Instance methods
107
getR();                             // Get red component (0-255)
108
getG();                             // Get green component (0-255)
109
getB();                             // Get blue component (0-255)
110
getA();                             // Get alpha component (0-1)
111
setR(value);                        // Set red component
112
setG(value);                        // Set green component
113
setB(value);                        // Set blue component
114
setA(value);                        // Set alpha component
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
const sass = require("node-sass");
121

122
// Create colors
123
const red = new sass.types.Color(255, 0, 0);      // Pure red
124
const blue = new sass.types.Color(0, 0, 255, 0.5); // Semi-transparent blue
125
const black = new sass.types.Color();              // Default black
126

127
// Manipulate colors
128
const color = new sass.types.Color(100, 150, 200);
129
console.log(color.getR());          // 100
130
color.setA(0.8);                    // Set alpha to 80%
131

132
// Use in custom functions
133
sass.render({
134
  data: ".test { color: lighten-color(#333, 0.2); }",
135
  functions: {
136
    "lighten-color($color, $amount)": function(color, amount, done) {
137
      const r = Math.min(255, color.getR() + (amount.getValue() * 255));
138
      const g = Math.min(255, color.getG() + (amount.getValue() * 255));
139
      const b = Math.min(255, color.getB() + (amount.getValue() * 255));
140
      
141
      const lightened = new sass.types.Color(r, g, b, color.getA());
142
      done(lightened);
143
    }
144
  }
145
});
146
```
147

148
### Error Type
149

150
Represents Sass error values for custom function error handling.
151

152
```javascript { .api }
153
/**
154
 * Create Sass error value
155
 * @param message - Error message string
156
 */
157
function Error(message);
158
```
159

160
**Usage Example:**
161

162
```javascript
163
sass.render({
164
  data: ".test { width: validate-size(invalid); }",
165
  functions: {
166
    "validate-size($value)": function(value, done) {
167
      if (value instanceof sass.types.Number) {
168
        done(value);
169
      } else {
170
        done(new sass.types.Error("Expected a number"));
171
      }
172
    }
173
  }
174
});
175
```
176

177
### List Type
178

179
Represents Sass list values with configurable separators.
180

181
```javascript { .api }
182
/**
183
 * Create Sass list value
184
 * @param length - Initial list length, default 0
185
 * @param separator - true for comma, false for space, default true
186
 */
187
function List(length?, separator?);
188

189
// Instance methods
190
getLength();                        // Get list length
191
getSeparator();                     // Get separator (true=comma, false=space)
192
setSeparator(separator);            // Set separator (boolean: true=comma, false=space)
193
getValue(index);                    // Get value at index (0-based)
194
setValue(index, value);             // Set value at index
195
```
196

197
**Usage Examples:**
198

199
```javascript
200
const sass = require("node-sass");
201

202
// Create lists
203
const spaceList = new sass.types.List(3, false);  // Space-separated
204
const commaList = new sass.types.List(2, true);   // Comma-separated
205

206
// Populate list
207
spaceList.setValue(0, new sass.types.Number(10, "px"));
208
spaceList.setValue(1, new sass.types.Number(20, "px"));
209
spaceList.setValue(2, new sass.types.Number(30, "px"));
210

211
// Use in custom functions
212
sass.render({
213
  data: ".test { margin: create-spacing(10px, 5px); }",
214
  functions: {
215
    "create-spacing($top, $side)": function(top, side, done) {
216
      const list = new sass.types.List(4, false); // Space-separated
217
      list.setValue(0, top);                       // top
218
      list.setValue(1, side);                      // right
219
      list.setValue(2, top);                       // bottom
220
      list.setValue(3, side);                      // left
221
      done(list);
222
    }
223
  }
224
});
225
```
226

227
### Map Type
228

229
Represents Sass map values (key-value pairs).
230

231
```javascript { .api }
232
/**
233
 * Create Sass map value
234
 * @param length - Initial map length, default 0
235
 */
236
function Map(length?);
237

238
// Instance methods
239
getLength();                        // Get map length
240
getKey(index);                      // Get key at index (0-based)
241
getValue(index);                    // Get value at index
242
setKey(index, key);                 // Set key at index
243
setValue(index, value);             // Set value at index
244
```
245

246
**Usage Examples:**
247

248
```javascript
249
const sass = require("node-sass");
250

251
// Create and populate map
252
const breakpoints = new sass.types.Map(3);
253

254
// Set key-value pairs
255
breakpoints.setKey(0, new sass.types.String("mobile"));
256
breakpoints.setValue(0, new sass.types.Number(480, "px"));
257

258
breakpoints.setKey(1, new sass.types.String("tablet"));
259
breakpoints.setValue(1, new sass.types.Number(768, "px"));
260

261
breakpoints.setKey(2, new sass.types.String("desktop"));
262
breakpoints.setValue(2, new sass.types.Number(1024, "px"));
263

264
// Use in custom functions
265
sass.render({
266
  data: ".test { width: map-get-breakpoint('tablet'); }",
267
  functions: {
268
    "map-get-breakpoint($key)": function(key, done) {
269
      // Search through a predefined map
270
      const breakpoints = new sass.types.Map(2);
271
      breakpoints.setKey(0, new sass.types.String("mobile"));
272
      breakpoints.setValue(0, new sass.types.Number(480, "px"));
273
      breakpoints.setKey(1, new sass.types.String("tablet"));
274
      breakpoints.setValue(1, new sass.types.Number(768, "px"));
275
      
276
      for (let i = 0; i < breakpoints.getLength(); i++) {
277
        if (breakpoints.getKey(i).getValue() === key.getValue()) {
278
          done(breakpoints.getValue(i));
279
          return;
280
        }
281
      }
282
      
283
      done(sass.types.Null());
284
    }
285
  }
286
});
287
```
288

289
### Null Type
290

291
Represents Sass null values.
292

293
```javascript { .api }
294
/**
295
 * Get Sass null singleton (call syntax only, new throws TypeError)
296
 * @returns Null singleton instance
297
 */
298
function Null();                        // Call syntax only
299

300
// Singleton constant
301
Null.NULL;                          // Sass null singleton
302
```
303

304
**Singleton Access:**
305

306
The Null type provides a singleton instance:
307

308
```javascript { .api }
309
// Available singleton constant
310
sass.types.Null.NULL;               // Sass null singleton
311

312
// Also available as direct module export
313
sass.NULL;                          // Same as sass.types.Null.NULL
314
```
315

316
**Usage Example:**
317

318
```javascript
319
const sass = require("node-sass");
320

321
// Return null from custom functions (multiple ways)
322
sass.render({
323
  data: ".test { color: optional-value(); }",
324
  functions: {
325
    "optional-value()": function(done) {
326
      const hasValue = false; // Some condition
327
      if (hasValue) {
328
        done(new sass.types.Color(255, 0, 0));
329
      } else {
330
        // All of these are equivalent
331
        done(sass.types.Null());
332
        // done(sass.types.Null.NULL);
333
        // done(sass.NULL);
334
      }
335
    }
336
  }
337
});
338
```
339

340
### Number Type
341

342
Represents Sass numeric values with optional units.
343

344
```javascript { .api }
345
/**
346
 * Create Sass number value
347
 * @param value - Numeric value, default 0
348
 * @param unit - Unit string (e.g., "px", "em", "%"), default ""
349
 */
350
function Number(value?, unit?);
351

352
// Instance methods
353
getValue();                         // Get numeric value
354
setValue(value);                    // Set numeric value
355
getUnit();                          // Get unit string
356
setUnit(unit);                      // Set unit string
357
```
358

359
**Usage Examples:**
360

361
```javascript
362
const sass = require("node-sass");
363

364
// Create numbers
365
const pixels = new sass.types.Number(16, "px");
366
const percent = new sass.types.Number(50, "%");
367
const unitless = new sass.types.Number(1.5);
368

369
// Manipulate numbers
370
console.log(pixels.getValue());     // 16
371
console.log(pixels.getUnit());      // "px"
372
pixels.setValue(20);
373
pixels.setUnit("em");
374

375
// Use in custom functions
376
sass.render({
377
  data: ".test { font-size: scale-font(16px, 1.2); }",
378
  functions: {
379
    "scale-font($base, $ratio)": function(base, ratio, done) {
380
      const scaledValue = base.getValue() * ratio.getValue();
381
      const result = new sass.types.Number(scaledValue, base.getUnit());
382
      done(result);
383
    }
384
  }
385
});
386
```
387

388
### String Type
389

390
Represents Sass string values.
391

392
```javascript { .api }
393
/**
394
 * Create Sass string value
395
 * @param value - String value, default ""
396
 */
397
function String(value?);
398

399
// Instance methods
400
getValue();                         // Get string value
401
setValue(value);                    // Set string value
402
```
403

404
**Usage Examples:**
405

406
```javascript
407
const sass = require("node-sass");
408

409
// Create strings
410
const className = new sass.types.String("header");
411
const empty = new sass.types.String();
412

413
// Manipulate strings
414
console.log(className.getValue());  // "header"
415
className.setValue("footer");
416

417
// Use in custom functions
418
sass.render({
419
  data: '.test { content: quote-string("Hello World"); }',
420
  functions: {
421
    "quote-string($str)": function(str, done) {
422
      const quoted = new sass.types.String('"' + str.getValue() + '"');
423
      done(quoted);
424
    }
425
  }
426
});
427
```
428

429
## Type Checking and Conversion
430

431
```javascript
432
// Check type instances
433
function isType(value, Type) {
434
  return value instanceof sass.types[Type];
435
}
436

437
// Example type checking in custom functions
438
sass.render({
439
  data: ".test { result: process-value(16px); }",
440
  functions: {
441
    "process-value($value)": function(value, done) {
442
      if (value instanceof sass.types.Number) {
443
        // Handle number
444
        done(new sass.types.String("number: " + value.getValue()));
445
      } else if (value instanceof sass.types.String) {
446
        // Handle string
447
        done(new sass.types.String("string: " + value.getValue()));
448
      } else {
449
        done(new sass.types.Error("Unexpected type"));
450
      }
451
    }
452
  }
453
});
454
```