sass-func 1.0.0

package/README.md

@@ -0,0 +1,270 @@
+# sass-func
+
+A collection of Sass utility functions for [lists](#module-list), [strings](#module-string), [numbers](#module-number), and [meta](#module-meta) utilities, inspired by familiar JS APIs. No dependencies beyond the Sass built-in modules. Where behaviour differs from a JS counterpart, the difference is noted.
+
+---
+
+## Installation
+
+```sh
+npm install sass-func
+```
+
+> Requires `sass >= 1.33.0` or `sass-embedded >= 1.33.0` — install one, not both. `sass-embedded` is recommended: it wraps a native Dart binary and is typically 20–30% faster to compile than the pure-JS `sass` package.
+
+---
+
+## Modules
+
+| Module              | Import path                         | Description                                              |
+| ------------------- | ----------------------------------- | -------------------------------------------------------- |
+| [`list`](#module-list)     | [`sass-func/list`](./list.scss)     | Functions for creating, transforming, and querying lists |
+| [`meta`](#module-meta)     | [`sass-func/meta`](./meta.scss)     | Functions for type inspection and emptiness checking     |
+| [`number`](#module-number) | [`sass-func/number`](./number.scss) | Functions for unit conversion and numeric operations     |
+| [`string`](#module-string) | [`sass-func/string`](./string.scss) | Functions for string transformation and parsing          |
+
+---
+
+## Module: List
+
+```scss
+@use 'sass-func/list' as l;
+```
+
+### `concat($lists...)`
+
+Concatenates zero or more lists into a single flat list.
+
+```scss
+l.concat((a, b), (c, d))  // → a, b, c, d
+l.concat()                // → ()
+```
+
+### `flat($list, $depth: null)`
+
+Recursively flattens nested lists. Pass `$depth` to limit how many levels deep the flattening goes; omit it (or pass `null`) for unlimited depth. Similar to `Array.prototype.flat(depth)`.
+
+> **Default depth differs:** Sass defaults to `null` (unlimited flattening); JS defaults to `1`.
+
+```scss
+l.flat((a, (b, (c, d))))        // → a, b, c, d
+l.flat((a, (b, (c, d))), 1)     // → a, b, (c, d)
+```
+
+### `includes($list, $value)`
+
+Returns `true` if `$value` is present in `$list`, `false` otherwise. Similar to `Array.prototype.includes(value)`.
+
+```scss
+l.includes((a, b, c), b)   // → true
+l.includes((a, b, c), z)   // → false
+```
+
+### `join($list, $separator: ', ')`
+
+Serializes a list into a string, inserting `$separator` between elements. Similar to `Array.prototype.join(separator)`.
+
+> **Default separator differs:** Sass defaults to `', '` (comma + space); JS defaults to `','` (comma only).
+
+```scss
+l.join((a, b, c))          // → 'a, b, c'
+l.join((a, b, c), ' | ')   // → 'a | b | c'
+```
+
+### `push($list, $val, $separator: comma)`
+
+Appends `$val` to the end of `$list`. `$separator` controls the resulting list's separator: `comma`, `space`, `slash`, or `auto`. Similar to `Array.prototype.push(val)` — unlike JS, this returns a new list rather than mutating in place.
+
+```scss
+l.push((a, b), c)   // → a, b, c
+```
+
+### `slice($list, $start: null, $end: null)`
+
+Returns the sublist from index `$start` to `$end` (1-based, inclusive). Omitting either bound defaults to the start or end of the list. Similar to `Array.prototype.slice(start, end)`.
+
+> **Index base and bounds differ:** Sass uses 1-based indices with an inclusive end; JS uses 0-based indices with an exclusive end. `slice(list, 2, 3)` returns elements 2 and 3; the JS equivalent would be `array.slice(1, 3)`.
+
+```scss
+l.slice((a, b, c, d), 2, 3)   // → b, c
+l.slice((a, b, c, d), 3)       // → c, d
+```
+
+### `sort($list, $desc: false)`
+
+Sorts a list alphabetically (case-insensitive). Numbers sort by value. Pass `$desc: true` for descending order. Similar to `Array.prototype.sort()`.
+
+> **Intentional differences:** Numbers sort by value (JS sorts lexicographically by default, so `[10, 2, 1].sort()` → `[1, 10, 2]` in JS). Sorting is also case-insensitive; JS is case-sensitive by default.
+
+```scss
+l.sort((c, a, b))               // → a, b, c
+l.sort((c, a, b), $desc: true)  // → c, b, a
+l.sort((3, 1, 2))               // → 1, 2, 3
+```
+
+---
+
+## Module: Meta
+
+```scss
+@use 'sass-func/meta' as m;
+```
+
+### `is-empty($value, $depth: 0)`
+
+Returns `true` if `$value` is empty. Covers `null`, blank strings, empty lists, and empty maps. Pass `$depth > 0` or `null` to also check nested structures. Similar to `_.isEmpty(value)` (lodash) — extended with configurable recursion depth.
+
+> **Whitespace strings:** A string containing only spaces (e.g. `'   '`) is considered empty. JS `_.isEmpty('   ')` returns `false`.
+
+```scss
+m.is-empty(null)                   // → true
+m.is-empty('')                     // → true
+m.is-empty('   ')                  // → true  (whitespace-only)
+m.is-empty(())                     // → true
+m.is-empty((a: ()))                // → false  (shallow)
+m.is-empty((a: ()), $depth: 1)     // → true   (checks nested)
+```
+
+### `is-type($value, $types)`
+
+Returns `true` if `$value`'s type is in the `$types` list.
+
+```scss
+m.is-type(1rem, ('number', 'string'))   // → true
+m.is-type(true, ('number', 'string'))   // → false
+```
+
+### `type-of($value)`
+
+Returns the Sass type name of any value. A thin wrapper over `meta.type-of` — included for consistent import paths within this package. Similar to `typeof value` — returns Sass-specific type names (`'number'`, `'string'`, `'map'`, `'list'`, `'color'`, `'bool'`, `'null'`).
+
+```scss
+m.type-of(1px)         // → 'number'
+m.type-of('hello')     // → 'string'
+m.type-of((a, b))      // → 'list'
+m.type-of((a: 1))      // → 'map'
+```
+
+---
+
+## Module: Number
+
+```scss
+@use 'sass-func/number' as n;
+```
+
+### `$SUPPORTED_LENGTH_UNITS`
+
+A list of the CSS length units supported by `add-unit` and `convert-unit`:
+
+```
+px, rem, em, cm, mm, Q, in, pc, pt
+```
+
+### `add-unit($number, $unit)`
+
+Attaches a CSS length unit to a unitless number.
+
+```scss
+n.add-unit(16, 'px')    // → 16px
+n.add-unit(1, 'rem')    // → 1rem
+```
+
+### `convert-unit($number, $from-unit, $to-unit)`
+
+Converts a number from one CSS length unit to another.
+
+```scss
+n.convert-unit(16px, 'px', 'rem')    // → 1rem
+n.convert-unit(1in, 'in', 'px')      // → 96px
+```
+
+### `resolve-index($index, $length)`
+
+Resolves a positive or negative integer index to a 1-based index within a collection of `$length`. Returns `null` if out of bounds. Negative indices count from the end, matching Python and modern JS convention.
+
+> **1-based output:** Returns a 1-based index, matching Sass's index convention. Negative indices resolve relative to the end — `-1` on a length-5 list returns `5` (the last position), not `4`.
+
+```scss
+n.resolve-index(2, 5)    // → 2
+n.resolve-index(-1, 5)   // → 5
+n.resolve-index(0, 5)    // → null
+n.resolve-index(6, 5)    // → null
+```
+
+### `to-fixed($number, $digits: 0)`
+
+Rounds a number to `$digits` decimal places. Similar to `Number.prototype.toFixed(digits)` — returns a number, not a string.
+
+```scss
+n.to-fixed(3.14159, 2)   // → 3.14
+n.to-fixed(1.5)           // → 2
+```
+
+---
+
+## Module: String
+
+```scss
+@use 'sass-func/string' as s;
+```
+
+### `capitalize($string)`
+
+Capitalizes the first character and lowercases the rest. Similar to `_.capitalize(string)` (lodash).
+
+> **Input is trimmed first:** Leading and trailing spaces are stripped before capitalizing. JS lodash preserves them.
+
+```scss
+s.capitalize('hello world')   // → 'Hello world'
+s.capitalize('HELLO')         // → 'Hello'
+```
+
+### `replace-all($string, $pattern, $replacement: '')`
+
+Replaces every occurrence of `$pattern` in `$string` with `$replacement`. Defaults to deletion if `$replacement` is omitted. Similar to `String.prototype.replaceAll(pattern, replacement)`.
+
+```scss
+s.replace-all('foo bar foo', 'foo', 'baz')   // → 'baz bar baz'
+s.replace-all('a--b--c', '--')               // → 'abc'
+```
+
+### `slugify($string)`
+
+Converts a string to a URL-safe slug: lowercased, spaces replaced with hyphens, special characters removed. Similar to `_.kebabCase(string)` (lodash) — with stricter special-character removal.
+
+```scss
+s.slugify('Hello World!')     // → 'hello-world'
+s.slugify('Font Size (lg)')   // → 'font-size-lg'
+```
+
+### `split($string, $separator: null)`
+
+Splits a string into a list using `$separator`. An empty string splits into individual characters. `null` returns the string wrapped in a single-element list. Similar to `String.prototype.split(separator)`.
+
+```scss
+s.split('a,b,c', ',')   // → a, b, c
+s.split('abc', '')       // → a, b, c
+s.split('abc')           // → 'abc'
+```
+
+### `trim($string)`
+
+Removes leading and trailing whitespace. Similar to `String.prototype.trim()`.
+
+> **Space characters only:** Strips the space character `' '`. JS strips all whitespace (`\t`, `\n`, `\r`, etc.) — Sass has no native regex equivalent for this.
+
+```scss
+s.trim('  hello  ')   // → 'hello'
+```
+
+### `upper-snake-case($string)`
+
+Converts a string to `UPPER_SNAKE_CASE` by replacing hyphens and spaces with underscores.
+
+```scss
+s.upper-snake-case('font-size')    // → 'FONT_SIZE'
+s.upper-snake-case('my variable')  // → 'MY_VARIABLE'
+```
+
+[Back to top](#sass-func)

package/list.scss

@@ -0,0 +1,229 @@
+@use 'sass:list';
+@use 'sass:meta';
+@use 'sass:math';
+@use 'sass:string';
+
+// PUBLIC API ──────────────────────────────────────────────────────────────────
+
+/// Concatenate zero or more lists into a single flat list
+/// @param {ArgList} $lists... - Zero or more lists to concatenate
+/// @return {List} A single flat list containing all elements
+@function concat($lists...) {
+  $result: ();
+  @each $list in $lists {
+    $result: list.join($result, $list, $separator: auto, $bracketed: auto);
+  }
+  @return $result;
+}
+
+/// Recursively flatten nested lists to $depth levels deep, or fully if null
+/// @param {List | ArgList} $list - The list to flatten
+/// @param {Number | Null} $depth [null] - Flattening depth; null means unlimited
+/// @return {List} Flattened list
+@function flat($list, $depth: null) {
+  @if not list.index(('list', 'arglist'), meta.type-of($list)) {
+    @error '$list: #{meta.inspect($list)} is not a list or arglist.';
+  } @else if $depth != null and meta.type-of($depth) != 'number' {
+    @error '$depth: #{meta.inspect($depth)} is not a number or null.';
+  }
+
+  // Depth limit reached — return the list as-is
+  @if $depth == 0 {
+    @return $list;
+  }
+
+  $result: ();
+  @each $element in $list {
+    @if meta.type-of($element) != 'list' {
+      $result: push($result, $element);
+    } @else if $depth == 1 {
+      // Depth of 1 — inline sub-list elements directly without recursing
+      @each $sub-element in $element {
+        $result: push($result, $sub-element);
+      }
+    } @else {
+      // Recurse with decremented depth, or null for unlimited
+      $next-depth: null;
+      @if $depth == null {
+        $next-depth: null;
+      } @else {
+        $next-depth: $depth - 1;
+      }
+      $sub-list: flat($element, $next-depth);
+      @each $sub-element in $sub-list {
+        $result: push($result, $sub-element);
+      }
+    }
+  }
+  @return $result;
+}
+
+/// Check whether $value is present in $list
+/// @param {List} $list - The list to search
+/// @param {*} $value - The value to look for
+/// @return {Bool} `true` if found, `false` otherwise
+@function includes($list, $value) {
+  @return list.index($list, $value) != null;
+}
+
+/// Serialize $list elements into a string with $separator between each
+/// @param {List | ArgList} $list - The list to join
+/// @param {String} $separator [', '] - String inserted between elements
+/// @return {String} Joined string
+@function join($list, $separator: ', ') {
+  @if not list.index(('list', 'arglist'), meta.type-of($list)) {
+    @error '$list: #{meta.inspect($list)} is not a list or arglist.';
+  } @else if meta.type-of($separator) != 'string' {
+    @error '$separator: #{meta.inspect($separator)} is not a string.';
+  }
+
+  $result: '';
+  @each $element in $list {
+    @if $result == '' {
+      $result: $element;
+    } @else {
+      $result: $result + $separator + $element;
+    }
+  }
+  @return $result;
+}
+
+/// Append $val to the end of $list
+/// @param {List} $list - The list to append to
+/// @param {*} $val - The value to append
+/// @param {String} $separator [comma] - List separator; `comma`, `space`, `slash`, or `auto`
+/// @return {List} New list with $val appended
+@function push($list, $val, $separator: comma) {
+  $allowed-separators: (comma, space, slash, auto);
+  @if list.index($allowed-separators, $separator) == null {
+    @error '$separator: Must be "space", "comma", "slash", or "auto".';
+  }
+
+  // Override separator for empty lists to prevent trailing-comma artifacts
+  @if list.length($list) == 0 {
+    $separator: space;
+  }
+
+  @return list.append($list, $val, $separator: $separator);
+}
+
+/// Return the sublist of $list from $start to $end (1-based, inclusive)
+/// @param {List | ArgList} $list - The list to slice
+/// @param {Number | Null} $start [null] - Start index; defaults to 1
+/// @param {Number | Null} $end [null] - End index; defaults to list length
+/// @return {List} Extracted sublist
+@function slice($list, $start: null, $end: null) {
+  @if not list.index(('list', 'arglist'), meta.type-of($list)) {
+    @error '$list: #{meta.inspect($list)} is not a list or arglist.';
+  } @else if $start != null and meta.type-of($start) != 'number' {
+    @error '$start: #{meta.inspect($start)} is not a number or null.';
+  } @else if $end != null and meta.type-of($end) != 'number' {
+    @error '$end: #{meta.inspect($end)} is not a number or null.';
+  }
+
+  $length: list.length($list);
+
+  // Default to full-list bounds when not specified
+  @if $start == null {
+    $start: 1;
+  }
+  @if $end == null {
+    $end: $length;
+  }
+
+  // Clamp bounds to the valid index range of the list
+  $start: math.round(math.max(1, math.min($start, $length)));
+  @if $end < 1 {
+    $end: 0;
+  } @else {
+    $end: math.round(math.min($end, $length));
+  }
+
+  // Inverted range means no elements to extract
+  @if $end < $start {
+    @return ();
+  }
+
+  $result: ();
+  @for $i from $start through $end {
+    $result: push($result, list.nth($list, $i));
+  }
+  @return $result;
+}
+
+/// Sort $list alphabetically — case-insensitive. Numbers sort by value.
+/// @param {List | ArgList} $list - The list to sort
+/// @param {Bool} $desc [false] - Pass `true` for descending order
+/// @return {List} Sorted list
+@function sort($list, $desc: false) {
+  @if not list.index(('list', 'arglist'), meta.type-of($list)) {
+    @error '$list: #{meta.inspect($list)} is not a list or arglist.';
+  } @else if meta.type-of($desc) != 'bool' {
+    @error '$desc: #{meta.inspect($desc)} is not a bool.';
+  }
+
+  $n: list.length($list);
+  @if $n <= 1 {
+    @return $list;
+  }
+
+  // Character weight map — unknown chars (e.g. digits) fall back to 999 and sort to the end
+  $chars: 'abcdefghijklmnopqrstuvwxyz-';
+
+  // Middle-element pivot minimises worst-case depth on already-sorted input
+  $pivot: list.nth($list, math.ceil(math.div($n, 2)));
+  $pivot-lower: string.to-lower-case('#{$pivot}'); // Hoisted — shared by every item comparison
+
+  // 3-way partition buckets
+  $less: ();
+  $equal: ();
+  $greater: ();
+
+  // Partition: each item lands in exactly one bucket relative to the pivot
+  @each $item in $list {
+    @if $item == $pivot {
+      $equal: list.append($equal, $item);
+    } @else {
+      $is-less: null; // null = no decision yet
+
+      // Numbers compare by value — string coercion would give wrong order (e.g. '10' < '9')
+      @if meta.type-of($item) == 'number' and meta.type-of($pivot) == 'number' {
+        $is-less: $item < $pivot;
+      } @else {
+        // Walk characters until a difference is found, then exit immediately
+        $a: string.to-lower-case('#{$item}');
+        $b: $pivot-lower;
+        $len-a: string.length($a);
+        $len-b: string.length($b);
+        $min-len: math.min($len-a, $len-b);
+        $i: 1;
+
+        @while $i <= $min-len and $is-less == null {
+          $ca: string.slice($a, $i, $i);
+          $cb: string.slice($b, $i, $i);
+          @if $ca != $cb {
+            $is-less: (string.index($chars, $ca) or 999) < (string.index($chars, $cb) or 999);
+          }
+          $i: $i + 1;
+        }
+
+        // Equal prefix — shorter string sorts first
+        @if $is-less == null {
+          $is-less: $len-a < $len-b;
+        }
+      }
+
+      @if $is-less {
+        $less: list.append($less, $item);
+      } @else {
+        $greater: list.append($greater, $item);
+      }
+    }
+  }
+
+  // Recurse on each partition, then join — flip less/greater order for descending
+  @if $desc {
+    @return list.join(list.join(sort($greater, $desc), $equal), sort($less, $desc));
+  }
+  @return list.join(list.join(sort($less, $desc), $equal), sort($greater, $desc));
+}

package/meta.scss

@@ -0,0 +1,72 @@
+@use 'sass:meta';
+@use 'sass:list';
+@use 'sass:map';
+@use './string' as s;
+
+// PUBLIC API ──────────────────────────────────────────────────────────────────
+
+/// Return the Sass type name of $value
+/// @param {*} $value - Any Sass value
+/// @return {String} Type name, e.g. `'number'`, `'string'`, `'map'`, `'list'`
+@function type-of($value) {
+  @return meta.type-of($value);
+}
+
+/// Check whether $value's type is one of the types in $types
+/// @param {*} $value - The value to check
+/// @param {List} $types - Allowed type names to match against
+/// @return {Bool} `true` if $value's type is in $types, `false` otherwise
+@function is-type($value, $types) {
+  @return list.index($types, meta.type-of($value)) != null;
+}
+
+/// Check whether $value is empty — pass $depth > 0 to also inspect nested structures
+/// @param {*} $value - The value to check
+/// @param {Number | Null} $depth [0] - Recursion depth; 0 = shallow only, null = unlimited
+/// @return {Bool} `true` if empty at the given depth, `false` otherwise
+@function is-empty($value, $depth: 0) {
+  @if $depth != null and meta.type-of($depth) != 'number' {
+    @error '$depth: #{meta.inspect($depth)} is not a number or null.';
+  }
+
+  $type: meta.type-of($value);
+
+  // Shallow emptiness — null, blank strings, and zero-length collections
+  @if $value == null {
+    @return true;
+  } @else if $type == 'string' and s.trim($value) == '' {
+    @return true;
+  } @else if list.index(('list', 'arglist'), $type) and list.length($value) == 0 {
+    @return true;
+  } @else if $type == 'map' and list.length(map.keys($value)) == 0 {
+    @return true;
+  }
+
+  // No recursion requested — value passed shallow checks, treat as non-empty
+  @if $depth == 0 {
+    @return false;
+  }
+
+  // Decrement depth for the next level, or carry null for unlimited recursion
+  $next-depth: null;
+  @if $depth != null {
+    $next-depth: $depth - 1;
+  }
+
+  @if list.index(('list', 'arglist'), $type) {
+    // Recurse into list and arglist elements
+    @each $element in $value {
+      @if is-empty($element, $next-depth) {
+        @return true;
+      }
+    }
+  } @else if $type == 'map' {
+    // Recurse into map keys and values
+    @each $k, $v in $value {
+      @if is-empty($k, $next-depth) or is-empty($v, $next-depth) {
+        @return true;
+      }
+    }
+  }
+  @return false;
+}

package/number.scss

@@ -0,0 +1,159 @@
+@use 'sass:meta';
+@use 'sass:math';
+@use 'sass:map';
+
+// CONFIG ──────────────────────────────────────────────────────────────────────
+
+// Pixel equivalents for each supported CSS length unit (used as conversion pivot)
+$_LENGTH_UNIT_PX_RATIOS: (
+  'px': 1,
+  'rem': 16,
+  'em': 16,
+  'cm': math.div(96, 2.54),
+  'mm': math.div(96, 25.4),
+  'Q': math.div(96, 101.6),
+  'in': 96,
+  'pc': math.div(96, 6),
+  'pt': math.div(96, 72),
+);
+
+// DERIVED ─────────────────────────────────────────────────────────────────────
+
+// Expose supported units publicly
+$SUPPORTED_LENGTH_UNITS: map.keys($_LENGTH_UNIT_PX_RATIOS);
+
+// PUBLIC API ──────────────────────────────────────────────────────────────────
+
+/// Attach a CSS length unit to a unitless number
+/// @param {Number} $number - A unitless number
+/// @param {String} $unit - Target unit; see `$SUPPORTED_LENGTH_UNITS`
+/// @return {Number} Number with the specified unit attached
+@function add-unit($number, $unit) {
+  @if meta.type-of($number) != 'number' {
+    @error '$number: #{meta.inspect($number)} is not a number.';
+  } @else if meta.type-of($unit) != 'string' {
+    @error '$unit: #{meta.inspect($unit)} is not a string.';
+  } @else if not math.is-unitless($number) {
+    @error '$number: #{meta.inspect($number)} is not a unitless number.';
+  } @else if not map.has-key($_LENGTH_UNIT_PX_RATIOS, $unit) {
+    @error '$unit: Must be "px", "rem", "em", "cm", "mm", "Q", "in", "pc", or "pt".';
+  }
+
+  @if $unit == 'px' {
+    @return $number * 1px;
+  } @else if $unit == 'rem' {
+    @return $number * 1rem;
+  } @else if $unit == 'em' {
+    @return $number * 1em;
+  } @else if $unit == 'cm' {
+    @return $number * 1cm;
+  } @else if $unit == 'mm' {
+    @return $number * 1mm;
+  } @else if $unit == 'Q' {
+    @return $number * 1Q;
+  } @else if $unit == 'in' {
+    @return $number * 1in;
+  } @else if $unit == 'pc' {
+    @return $number * 1pc;
+  } @else if $unit == 'pt' {
+    @return $number * 1pt;
+  }
+}
+
+/// Convert a number from one CSS length unit to another
+/// @param {Number} $number - Unitless number, or a number whose unit matches $from-unit
+/// @param {String} $from-unit - Source unit; see `$SUPPORTED_LENGTH_UNITS`
+/// @param {String} $to-unit - Target unit; see `$SUPPORTED_LENGTH_UNITS`
+/// @return {Number} Converted number with the target unit attached
+@function convert-unit($number, $from-unit, $to-unit) {
+  @if meta.type-of($number) != 'number' {
+    @error '$number: #{meta.inspect($number)} is not a number.';
+  } @else if meta.type-of($from-unit) != 'string' {
+    @error '$from-unit: #{meta.inspect($from-unit)} is not a string.';
+  } @else if meta.type-of($to-unit) != 'string' {
+    @error '$to-unit: #{meta.inspect($to-unit)} is not a string.';
+  } @else if not map.has-key($_LENGTH_UNIT_PX_RATIOS, $from-unit) {
+    @error '$from-unit: Must be "px", "rem", "em", "cm", "mm", "Q", "in", "pc", or "pt".';
+  } @else if not map.has-key($_LENGTH_UNIT_PX_RATIOS, $to-unit) {
+    @error '$to-unit: Must be "px", "rem", "em", "cm", "mm", "Q", "in", "pc", or "pt".';
+  } @else if not math.is-unitless($number) and math.unit($number) != $from-unit {
+    @error '$number: Must be unitless or use unit "#{$from-unit}".';
+  }
+
+  @if $from-unit == $to-unit {
+    @return $number;
+  }
+
+  $n: math.div($number, $number * 0 + 1); // strip unit
+  $result: math.div(
+    $n * map.get($_LENGTH_UNIT_PX_RATIOS, $from-unit),
+    map.get($_LENGTH_UNIT_PX_RATIOS, $to-unit)
+  );
+
+  @if $to-unit == 'px' {
+    @return $result * 1px;
+  } @else if $to-unit == 'rem' {
+    @return $result * 1rem;
+  } @else if $to-unit == 'em' {
+    @return $result * 1em;
+  } @else if $to-unit == 'cm' {
+    @return $result * 1cm;
+  } @else if $to-unit == 'mm' {
+    @return $result * 1mm;
+  } @else if $to-unit == 'Q' {
+    @return $result * 1Q;
+  } @else if $to-unit == 'in' {
+    @return $result * 1in;
+  } @else if $to-unit == 'pc' {
+    @return $result * 1pc;
+  } @else if $to-unit == 'pt' {
+    @return $result * 1pt;
+  }
+}
+
+/// Resolve a relative index (positive or negative) to a valid 1-based index
+/// @param {Number} $index - Positive or negative integer index
+/// @param {Number} $length - Length of the collection
+/// @return {Number | Null} 1-based index, or `null` if out of bounds
+@function resolve-index($index, $length) {
+  @if meta.type-of($index) != 'number' {
+    @error '$index: #{meta.inspect($index)} is not a number.';
+  } @else if meta.type-of($length) != 'number' {
+    @error '$length: #{meta.inspect($length)} is not a number.';
+  }
+
+  // Snap fractional inputs to the nearest whole position
+  $index: math.round($index);
+
+  // Translate negative indices from the end of the range
+  @if $index < 0 {
+    $index: $length + $index + 1;
+  }
+
+  // Signal out-of-bounds by returning null rather than throwing
+  @if $index < 1 or $index > $length {
+    @return null;
+  } @else {
+    @return $index;
+  }
+}
+
+/// Round a number to a fixed number of decimal places
+/// @param {Number} $number - Number to round
+/// @param {Number} $digits [0] - Decimal places to keep (>= 0); fractional values are floored
+/// @return {Number} Rounded number
+@function to-fixed($number, $digits: 0) {
+  @if meta.type-of($number) != 'number' {
+    @error '$number: #{meta.inspect($number)} is not a number.';
+  } @else if meta.type-of($digits) != 'number' {
+    @error '$digits: #{meta.inspect($digits)} is not a number.';
+  } @else if not math.is-unitless($digits) {
+    @error '$digits: #{meta.inspect($digits)} is not a unitless number.';
+  } @else if $digits < 0 {
+    @error '$digits: Must be 0 or greater.';
+  }
+
+  $digits: math.floor($digits);
+  $factor: math.pow(10, $digits);
+  @return math.div(math.round($number * $factor), $factor);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "sass-func",
+  "version": "1.0.0",
+  "description": "A collection of Sass utility functions for lists, strings, numbers, and meta — inspired by familiar JS APIs.",
+  "keywords": [
+    "sass",
+    "scss",
+    "functions",
+    "utilities",
+    "helpers",
+    "list",
+    "string",
+    "number",
+    "meta"
+  ],
+  "homepage": "https://github.com/nicholasgillespie/sass-func#readme",
+  "license": "MIT",
+  "author": "Nicholas Gillespie (https://github.com/nicholasgillespie)",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/nicholasgillespie"
+  },
+  "files": [
+    "list.scss",
+    "meta.scss",
+    "number.scss",
+    "string.scss",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicholasgillespie/sass-func.git"
+  },
+  "peerDependencies": {
+    "sass": ">=1.33.0",
+    "sass-embedded": ">=1.33.0"
+  },
+  "peerDependenciesMeta": {
+    "sass": {
+      "optional": true
+    },
+    "sass-embedded": {
+      "optional": true
+    }
+  }
+}

package/string.scss

@@ -0,0 +1,145 @@
+@use 'sass:meta';
+@use 'sass:string';
+@use 'sass:list';
+
+// PUBLIC API ──────────────────────────────────────────────────────────────────
+
+/// Capitalize first letter of $string and lowercase the remainder
+/// @param {String} $string - Input string
+/// @return {String} Capitalized string
+@function capitalize($string) {
+  @if meta.type-of($string) != 'string' {
+    @error '$string: #{meta.inspect($string)} is not a string.';
+  }
+  $string: trim($string);
+  @if string.length($string) == 0 {
+    @return '';
+  }
+  $first: string.slice($string, 1, 1);
+  $rest: string.slice($string, 2);
+  @return string.to-upper-case($first) + string.to-lower-case($rest);
+}
+
+/// Replace all occurrences of $pattern with $replacement in $string
+/// @param {String} $string - Input string
+/// @param {String} $pattern - Substring to find
+/// @param {String} $replacement [''] - Replacement string
+/// @return {String} String with all $pattern occurrences replaced
+@function replace-all($string, $pattern, $replacement: '') {
+  @if meta.type-of($string) != 'string' {
+    @error '$string: #{meta.inspect($string)} is not a string.';
+  } @else if meta.type-of($pattern) != 'string' {
+    @error '$pattern: #{meta.inspect($pattern)} is not a string.';
+  } @else if meta.type-of($replacement) != 'string' {
+    @error '$replacement: #{meta.inspect($replacement)} is not a string.';
+  }
+
+  // Empty pattern would cause infinite recursion — return early
+  @if $pattern == '' {
+    @return $string;
+  }
+
+  $index: string.index($string, $pattern);
+  @if $index {
+    @return string.slice($string, 1, $index - 1) + $replacement +
+      replace-all(string.slice($string, $index + string.length($pattern)), $pattern, $replacement);
+  }
+  @return $string;
+}
+
+/// Convert $string to URL-safe slug format (lowercase, hyphens, no special chars)
+/// @param {String} $string - Input string
+/// @return {String} URL-safe slug
+@function slugify($string) {
+  @if meta.type-of($string) != 'string' {
+    @error '$string: #{meta.inspect($string)} is not a string.';
+  }
+
+  $lower: string.to-lower-case($string);
+  $result: '';
+  $disallowed-characters: '\'"!@#$%^&*()+=[]{}|;:,.<>?/`~';
+
+  // Walk each character, keeping only allowed ones
+  @for $i from 1 through string.length($lower) {
+    $character: string.slice($lower, $i, $i);
+    @if not string.index($disallowed-characters, $character) {
+      $result: $result + $character;
+    }
+  }
+
+  @return replace-all(trim($result), ' ', '-');
+}
+
+/// Split $string into a list using $separator
+/// @param {String} $string - Input string
+/// @param {String | Null} $separator [null] - Delimiter; '' splits per char, null wraps in a list
+/// @return {List} List of string segments
+@function split($string, $separator: null) {
+  @if meta.type-of($string) != 'string' {
+    @error '$string: #{meta.inspect($string)} is not a string.';
+  }
+
+  // Null separator — return the string wrapped in a single-element list
+  @if $separator == null {
+    @return list.append((), $string, space);
+  }
+  @if meta.type-of($separator) != 'string' {
+    @error '$separator: #{meta.inspect($separator)} is not a string or null.';
+  }
+
+  $result: ();
+
+  // Empty separator — split into individual characters
+  @if $separator == '' {
+    @for $i from 1 through string.length($string) {
+      $result: list.append($result, string.slice($string, $i, $i), comma);
+    }
+    @return $result;
+  }
+
+  $sep-length: string.length($separator);
+  $index: string.index($string, $separator);
+
+  // Iteratively slice at each separator match, accumulating parts
+  @while $index {
+    $part: string.slice($string, 1, $index - 1);
+    $result: list.append($result, $part, comma);
+    $string: string.slice($string, $index + $sep-length);
+    $index: string.index($string, $separator);
+  }
+
+  @return list.append($result, $string, comma);
+}
+
+/// Remove leading and trailing whitespace from $string
+/// @param {String} $string - Input string
+/// @return {String} Trimmed string
+@function trim($string) {
+  @if meta.type-of($string) != 'string' {
+    @error '$string: #{meta.inspect($string)} is not a string.';
+  }
+
+  $start: 1;
+  $end: string.length($string);
+  @while $start <= $end and string.slice($string, $start, $start) == ' ' {
+    $start: $start + 1;
+  }
+  @while $end >= $start and string.slice($string, $end, $end) == ' ' {
+    $end: $end - 1;
+  }
+  @return string.slice($string, $start, $end);
+}
+
+/// Convert $string to UPPER_SNAKE_CASE by replacing hyphens and spaces with underscores
+/// @param {String} $string - Input string
+/// @return {String} UPPER_SNAKE_CASE string
+@function upper-snake-case($string) {
+  @if meta.type-of($string) != 'string' {
+    @error '$string: #{meta.inspect($string)} is not a string.';
+  }
+
+  $string: trim($string);
+  $result: replace-all($string, '-', '_');
+  $result: replace-all($result, ' ', '_');
+  @return string.to-upper-case($result);
+}