Registry / serialization / node-sass-utils

node-sass-utils

JSON →
library1.1.3jsnpmunverified

node-sass-utils provides a collection of helper functions designed to simplify working with Sass values within JavaScript functions exposed to `node-sass` (and `dart-sass`, aka `sass` on npm). It addresses the complexity of handling Sass data types (like strings, numbers, booleans, lists, and maps) in a JavaScript environment. The library is currently at version 1.1.3. While its primary integration point was `node-sass`, it has been tested and confirmed to work with `dart-sass`, providing a bridge for utility functions regardless of the underlying Sass compiler implementation. This allows developers to write more robust and type-safe custom Sass functions in JavaScript. Key differentiators include methods for type assertion (`assertType`), type checking (`typeOf`, `isNull`, `isFalsy`), string manipulation (`sassString`, `unquote`), and crucial type casting utilities (`castToSass`, `castToJs`) for seamless data exchange between JavaScript and Sass. It is important to note its CommonJS module format and the specific initialization pattern requiring the Sass object.

serialization
npm install node-sass-utils
github ↗package ↗
INSTALL
IMPORT
SIG · NODE-SASS-UTILS
N
node-sass-utils
serializationjavascriptv1.1.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sassUtils
✓ const sass = require('sass'); const sassUtils = require('node-sass-utils')(sass);
✗ import sassUtils from 'node-sass-utils'; const sassUtils = require('node-sass-utils');
The package exports a function that must be immediately invoked with the `sass` object (either from `node-sass` or `sass`/`dart-sass`) to return the utility object. This is a CommonJS-style export.
SassDimension
✓ const sass = require('sass'); const sassUtils = require('node-sass-utils')(sass); const { SassDimension } = sassUtils;
✗ import { SassDimension } from 'node-sass-utils';
`SassDimension` is a class exposed as a property on the `sassUtils` object after it has been initialized, not a direct named export from the package.
castToSass
✓ const sass = require('sass'); const sassUtils = require('node-sass-utils')(sass); const { castToSass } = sassUtils;
✗ import { castToSass } from 'node-sass-utils';
All utility methods like `castToSass` are properties of the `sassUtils` object returned by the initial function call.

This example demonstrates initializing `node-sass-utils` with the `sass` (Dart Sass) compiler, using `assertType` for validation, `castToJs` to convert Sass types to JavaScript, `unquote` for string manipulation, and `castToSass` to convert JavaScript values back to Sass types within a custom Sass function.

const sass = require("sass"); // Using 'sass' (Dart Sass) for modern usage const sassUtils = require("node-sass-utils")(sass); function mySassFunction(colorValue, stringValue) { sassUtils.assertType(colorValue, "color"); const jsColor = sassUtils.castToJs(colorValue); // Convert Sass Color to JS representation console.log(`Received Sass Color (JS): ${jsColor}`); const unquotedString = sassUtils.unquote(stringValue); // Unquote the Sass string console.log(`Unquoted Sass String: "${sassUtils.sassString(unquotedString)}"`); const jsNumber = 42; const sassNumber = sassUtils.castToSass(jsNumber); // Cast JS number to Sass number return sass.types.List([sassNumber, unquotedString, colorValue], sass.types.List.SEPARATOR_SPACE); } sass.render({ data: ` @function my-func($color, $str) { @return my-func($color, $str); } $result: my-func(#f0f, "hello world"); div { content: inspect($result); } `, functions: { "my-func($color, $str)": mySassFunction } }, (err, result) => { if (err) { console.error("Sass compilation error:", err); } else { console.log("Compiled CSS:\n", result.css.toString()); } });
Debug
Known issues
breakingThe package's traditional primary dependency, `node-sass`, is largely superseded by `sass` (Dart Sass) for modern projects. While `node-sass-utils` is compatible with `sass`, direct `node-sass` usage is discouraged due to slower development and potential dependency issues (e.g., Python build tools for compilation).
fix
Update your project to use `sass` (Dart Sass) instead of `node-sass` (`npm install sass`). Pass the `sass` object from `require('sass')` to `node-sass-utils`.
affects: >=1.0.0
gotchaUsing the `sassUtils.infect()` method modifies global Sass type prototypes, which can lead to conflicts, unexpected behavior, or difficulty debugging in larger projects or when integrating with other Sass-related libraries. This is generally considered bad practice.
fix
Avoid `sassUtils.infect()`. Prefer calling utility methods directly on the `sassUtils` object (e.g., `sassUtils.sassString(value)` instead of `value.sassString()`). If absolutely necessary for a localized scope, ensure `sassUtils.disinfect()` is called immediately after use.
affects: >=1.0.0
gotchaThe `node-sass-utils` package exports a function that must be immediately invoked with the `sass` object. Incorrectly importing or initializing the package will result in errors like `TypeError: require(...) is not a function` or `TypeError: sassUtils.xxx is not a function` because `sassUtils` will not be the expected object.
fix
Always initialize the utility by passing the `sass` object: `const sass = require('sass'); const sassUtils = require('node-sass-utils')(sass);`. Ensure `sass` itself is properly imported from either `node-sass` or `sass`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: require(...) is not a function
The `node-sass-utils` package's main export is a function that *must* be called with the `sass` object, not directly assigned.
fix
Initialize correctly: `const sass = require('sass'); const sassUtils = require('node-sass-utils')(sass);`
Error: "Expected a <type>, but got a <another-type>."
This error typically originates from `sassUtils.assertType(value, typeName)` being called within a custom Sass function, indicating that a Sass value of an unexpected type was passed.
fix
Review the Sass function call and the JavaScript function's expected argument types. Use `sassUtils.typeOf(value)` to inspect the actual type received and adjust either the Sass source or the JavaScript logic to ensure type compatibility.
TypeError: Sass value is not a string. Cannot unquote.
The `sassUtils.unquote` function was called with a Sass value that is not a string or a Sass `null` type, which are the only types it accepts.
fix
Ensure that the value passed to `unquote` is explicitly a Sass string or `null`. Use `sassUtils.typeOf` to verify the input type before calling `unquote`.
Upgrade
Version history
1.1.3latest on npm
Audit
Dependencies
sassrequiredRequired to provide the `sass` object (specifically `sass.types`) which `node-sass-utils` operates on. `node-sass` can also be used, but `sass` (Dart Sass) is recommended.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/sass-eyeglass/node-sass-utils ↗
packagehttps://www.npmjs.com/package/node-sass-utils ↗
node-sass-utils — npm install node-sass-utils · libregistry