sass-error

Sass utility functions for building error messages — per the Error Message Specification.

Message Format

As defined by the specification, every error message is a single structured string composed of a machine-readable code and a human-readable message.

[CODE] <EntityType> "<EntityName>" [@ <Path>]: <Issue> → <Action> [context: ...]

Example

[TOKEN_TIER_VALUE] Token "font-weight" @ settings > tier: Invalid value "random" → Allowed: primitive | semantic | component

Note: See the Error Message Specification for a step-by-step guide on how to construct error messages.

Installation

npm install sass-error sass-funcs

Requires sass or sass-embedded >= 1.33.0 — install one, not both (sass-embedded recommended). Also requires sass-funcs.

Configuration

All constants are configurable via @use ... with (...):

@use 'sass-error' as e with (
  $PATH_SEPARATOR: '/',
  $EXPECTED_LIMIT: 3,
  $EXPECTED_MORE_LABEL: 'plus'
);

| Variable | Default | Description | | ---------------------- | -------- | ------------------------------------------ | | $PATH_PREFIX | ' @ ' | Prefix before the path string | | $PATH_SEPARATOR | ' > ' | Separator between path segments | | $PATH_ID_PLACEHOLDER | '<id>' | Placeholder when the key itself is invalid | | $EXPECTED_LIMIT | 5 | Max values shown before truncating | | $EXPECTED_SEPARATOR | ' \| ' | Separator between values | | $EXPECTED_MORE_LABEL | 'more' | Label for the remaining count |

Module: Error

@use 'sass-error' as e;

| Function | Description | | --------------------------------------------------- | ---------------------------------------------- | | path | Builds a formatted path string from segments | | received | Renders a received value as a string | | expected | Formats expected values into a readable string |

e.path($path, $is-id-error, $separator)

Builds a formatted path string from path segments for use in error messages.

| Parameter | Type | Default | Description | | -------------- | ---------------- | ----------------- | ----------------------------------------------------- | | $path | List \| String | | Path segments, or a single value normalised to a list | | $is-id-error | Bool | false | Replaces the last segment with <id> when true | | $separator | String | $PATH_SEPARATOR | Separator placed between path segments |

Returns String — path string prefixed with $PATH_PREFIX, or '' if path is empty.

e.path(('settings', 'tier'))           // → ' @ settings > tier'
e.path(('values', 'core', ''), true)   // → ' @ values > core > <id>'
e.path(())                             // → ''

e.received($value, $quote-empty)

Renders a received value as a string for use in error messages.

| Parameter | Type | Default | Description | | -------------- | ------ | ------- | ----------------------------------------------------------------- | | $value | * | | Value to render | | $quote-empty | Bool | false | Wraps empty or whitespace-only strings in double quotes when true |

Returns String — strings returned as-is, non-empty lists wrapped in parens, all others inspected.

e.received('hello')      // → 'hello'
e.received(42)           // → '42'
e.received((a, b, c))    // → '(a, b, c)'
e.received('', true)     // → '""'

e.expected($items, $extra, $limit, $separator)

Formats a list of expected values into a readable string for error messages.

| Parameter | Type | Default | Description | | ------------ | --------------------------------------------------- | --------------------- | -------------------------------------------------------- | | $items | List \| String | | Expected values; normalised to a list if a single value | | $extra | String \| Number \| Bool \| Color \| List \| Null | null | Additional value(s) appended after the main list | | $limit | Number \| Null | $EXPECTED_LIMIT | Max items shown before truncating with a remaining count | | $separator | String | $EXPECTED_SEPARATOR | Separator placed between values |

Returns String — joined expected string, truncated to $limit items if the count is exceeded.

e.expected(('foo', 'bar', 'baz'))                       // → 'foo | bar | baz'
e.expected(('a', 'b', 'c', 'd', 'e', 'f'), $limit: 3)   // → 'a | b | c | ... 3 more'
e.expected(('foo', 'bar'), $extra: 'baz')               // → 'foo | bar | baz'

Migration

v1 → v2

• print() renamed to received()
• options() renamed to expected()
• $ERROR_LABEL_ENTRY, $ERROR_LABEL_FIELD, $ERROR_ENTRY_LABELS removed — moved to sass-valid

Back to top