Home

Awesome

node-sass-utils

This package provides helpers for working with the Sass values that node-sass passes to javascript functions that are exposed as sass functions.

Because the dart-sass (aka sass on npm) implementation mostly adheres to the node-sass implementation, this package has been tested to work with both.

Basic Usage

var sass = require("node-sass");
var sassUtils = require("node-sass-utils")(sass);

// standard invocation: methods on the sassUtils object
function mySassFunction(arg1) {
  console.log(sassUtils.sassString(arg1));
  return arg1;
}

The sassUtils object provides many useful helper methods.

Many of the Sass Utility functions are more naturally instance methods of the sass types. The sass utilities can infect the Sass types.

var sass = require("node-sass");
var sassUtils = require("node-sass-utils")(sass);

sassUtils.infect();

function mySassFunction(arg1) {
  console.log(arg1.sassString());
  return arg1;
}

However library authors really should not mess around with core objects. If you really need to, you can disinfect the sass types:

var sass = require("node-sass");
var sassUtils = require("node-sass-utils")(sass);

function mySassFunction(arg1) {
  sassUtils.infect();
  console.log(arg1.sassString());
  sassUtils.disinfect();
  return arg1;
}

API

sassUtils.assertType(value, typeName)

Raises an error unless the sass value is not of the type specified. The type should be a javascript string as would be returned by sassUtils.typeOf.

sassUtils.isFalsy(value)

Returns true if the value is a sass null or boolean false.

sassUtils.isNull(value)

Returns true if the value is a sass null.

sassUtils.sassString(value)

Returns a javascript string that is the sass value as represented in a Sass file.

sassUtils.typeOf(value)

Returns a javascript string that is the sass type name of value (as returned by the sass type-of. One of the following: "bool", "color", "list", "map", "null", "number", "string"

sassUtils.typeOfConstructor(constructor)

Like sassUtils.typeOf except it takes a sass value constructor (sass.types.Xyz or sassValue.constructor) instead of a sass value itself.

sassUtils.unquote(value)

Returns a new sass string after unquoting it. Returns a sass null if passed a sass null. All other types raise an error.

sassUtils.isEmptyMap(value)

Returns true if the value is an empty map or an empty list.

sassUtils.handleEmptyMap(value)

Returns an empty map if passed an empty list. Otherwise, returns the value passed in.

sassUtils.castToSass(jsValue)

Returns a corresponding sass value for the given javascript value.

sassUtils.castToJs(jsValue)

The following Sass types can be coerced:

class SassDimension

Properties:

Constructor:

- new SassDimension(10, "px"): Most commonly there is just a single unit in the numerator.

Methods:

new sassUtils.SassJsMap([sassMap])

Returns a new javascript Map that is capable of maping sass objects as keys to sass objects as values. The API of a sass map is identical to the Javascript Map builtin type.

Additional Methods:

Coercion:

A sassJsMap provides a coerce property that automatically coerces arguments and their return values.

The following Sass types can be coerced:

Note: It is highly discouraged to use SassJsMap values as a key in another map. The behavior is very unpredictable if the map is mutated.

Usage Example:

var sass = require("node-sass");
var someSassColorLibrary = require("some-color-library");
var sassUtils = require("node-sass-utils")(sass);
function someCustomSassFunction(sassMap) {
  var map = new sassUtils.SassJsMap();
  var color = map.get(new sass.types.String("color"));
  map.set(new sass.types.String("background-color"),
          someSassColorLibrary.darken(color, 0.20))
  return map.toSassMap();
}

Instance API

These methods are only available after calling sassUtils.infect(sass.types).

isFalsy()

Returns true if the instance is a sass null or boolean false.

isNull()

Returns true if the instance is a sass null.

sassString()

Returns a javascript string that is the instance as represented in a Sass file.

Installation

$ npm install --save node-sass-utils