@localnerve/sass-asset-functions 6.9.0 → 6.10.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Sass Asset Functions Change Log
 
+## 6.10.0
+  * added `lookup` function, arbitrary `data` option
+
 ## 6.9.0
   * sass 1.86.0
   * image-size 2.0.1

package/README.md

@@ -33,6 +33,7 @@ This module provides some of the asset functions that came with [Compass](http:/
 - `font-url($filename: null, $only-path: false)`
 - `font-files($filenames...)`
 - `inline-image($filename: null, $mime-type: null)`
+- `lookup($keys...)`
 
 ## Usage
 
@@ -75,6 +76,7 @@ All options are optional.
 | `http_fonts_path` | String | The path to images as seen from the web (nothing to do with http). Defaults to `/fonts` |
 | `asset_cache_buster` | Function | Signature (http_path, real_path, callback(new_url)). Supply to perform url transform for `image-url` or `font-url`, presumably for asset cache busting, but useful for any change to the url path (before fragment) |
 | `asset_host` | Function | Signature (http_path, callback(new_url)). Supply to perform url transform for `image-url` or `font-url`, presumably to define an asset host, but useful for any change to the url before the path |
+| `data` | Object | An object of arbitrary data to reference at build-time. Defaults to `(empty)` |
 
 ### Examples
 
@@ -85,7 +87,8 @@ You can specify the paths to your resources using the following options (shown w
   images_path: 'public/images', // local directory
   fonts_path: 'public/fonts',
   http_images_path: '/images', // web path
-  http_fonts_path: '/fonts'
+  http_fonts_path: '/fonts',
+  data: {}
 }
 ```
 
@@ -118,6 +121,57 @@ const result = sass.compile(scss_filename, {
 });
 ```
 
+#### `lookup`: a function to use arbitrary data in sass stylesheets
+
+This function retrieves arbitrary build-time data for reference in stylesheet compilation. Could be an asset name, prefix, or could be a whole list or map of things. Here's the list of javascript type mappings (everything else returns SassNull):
+  * Boolean => SassBoolean
+  * Number => SassNumber
+  * String => SassString
+  * Array => SassList
+  * Set => SassList
+  * Object => SassMap
+  * Map => SassMap
+
+```js
+const result = sass.compile(scss_filename, {
+  functions: assetFunctions({
+    data: {
+      'hero-image-names': {
+        big: 'hero-1920x300.webp',
+        medium: 'hero-1440x300.webp',
+        small: 'hero-1024x300.webp'
+      },
+      nested: {
+        process: true,
+        'process-map': {
+          one: 'one',
+          two: 'two'
+        }
+      }
+    }
+  })
+});
+```
+
+```scss
+$hero-images: lookup('hero-image-names');
+@each $key, $val in $hero-images {
+  .hero-image-#{$key} {
+    background-image: image-url($val);
+  }
+}
+
+$nested-process: lookup('nested', 'process');
+$nested-data: lookup('nested', 'process-map');
+@if $nested-process {
+  @each $key, $val in $nested-data {
+    .process-#{$key} {
+      content: '#{$val}';
+    }
+  }
+}
+```
+
 #### `asset_host`: a function which completes with a string used as asset host.
 
 ```js
@@ -148,7 +202,7 @@ const result = sass.compile(scss_filename, {
 });
 ```
 
-##### A more advanced example:
+##### A more advanced example of `asset_cache_buster`:
 
 Here we include the file's  hexdigest in the path, using the [`hexdigest`](https://github.com/koenpunt/node-hexdigest) module.
 

package/cjs/lib/legacyAPI.cjs

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = legacyAPI;
+var _types = require("./types.cjs");
 /**
  * Custom Functions for sass Legacy JS API.
  * 
@@ -57,6 +58,18 @@ function legacyAPI(sass, processor) {
         }
         done(list);
       });
+    },
+    'lookup($keys...)': (list, done) => {
+      let len = list.getLength(),
+        i = 0;
+      const keys = [];
+      for (; i < len; ++i) {
+        keys[i] = list.getValue(i).getValue();
+      }
+      processor.lookup(keys, value => {
+        const result = (0, _types.convertToSassTypesLegacy)(sass, value);
+        done(result);
+      });
     }
   };
 }

package/cjs/lib/modernAPIAsync.cjs

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = modernAPIAsync;
+var _types = require("./types.cjs");
 /**
  * Custom Functions for asynchronous, sass modern JS API (compileAsync).
  * 
@@ -105,6 +106,24 @@ function modernAPIAsync(sass, processor) {
           reject(err);
         }
       });
+    },
+    'lookup($keys...)': args => {
+      return new Promise((resolve, reject) => {
+        try {
+          const input = args[0].asList;
+          const keys = [];
+          for (let i = 0; i < input.size; ++i) {
+            keys[i] = input.get(i).assertString().text;
+          }
+          let result = sass.sassNull;
+          processor.lookup(keys, value => {
+            result = (0, _types.convertToSassTypesModern)(sass, value);
+            resolve(result);
+          });
+        } catch (err) {
+          reject(err);
+        }
+      });
     }
   };
 }

package/cjs/lib/modernAPISync.cjs

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = modernAPISync;
+var _types = require("./types.cjs");
 /**
  * Custom Functions for synchronous, sass modern JS API (compile).
  * 
@@ -79,6 +80,18 @@ function modernAPISync(sass, processor) {
         }
       });
       return new sass.SassList(result);
+    },
+    'lookup($keys...)': args => {
+      const input = args[0].asList;
+      const keys = [];
+      for (let i = 0; i < input.size; ++i) {
+        keys[i] = input.get(i).assertString().text;
+      }
+      let result = sass.sassNull;
+      processor.lookup(keys, value => {
+        result = (0, _types.convertToSassTypesModern)(sass, value);
+      });
+      return result;
     }
   };
 }

package/cjs/lib/processor.cjs

@@ -37,7 +37,12 @@ const FONT_TYPES = {
 };
 class Processor {
   constructor(options) {
-    this.options = options;
+    this.options = {
+      ...{
+        data: {}
+      },
+      ...options
+    };
     const {
       images_path = defaultPaths.images_path,
       fonts_path = defaultPaths.fonts_path,
@@ -191,5 +196,12 @@ class Processor {
       this.font_url(file, complete(i, type));
     }
   }
+  lookup(keys, done) {
+    let data = this.options.data;
+    for (let key of keys) {
+      data = data[key];
+    }
+    done(data !== this.options.data ? data : null);
+  }
 }
 exports.default = Processor;

package/cjs/lib/types.cjs

@@ -0,0 +1,123 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.convertToSassTypesLegacy = convertToSassTypesLegacy;
+exports.convertToSassTypesModern = convertToSassTypesModern;
+var _immutable = require("immutable");
+/**
+ * Convert javascript types to sass types.
+ * 
+ * Supported Mappings:
+ * Boolean => Sass.Boolean
+ * Number => Sass.Number
+ * String => Sass.String
+ * Array => Sass.List
+ * Set => Sass.List
+ * Object => Sass.Map
+ * Map => Sass.Map
+ * BigInt => Sass.Null
+ * Function => Sass.Null
+ * Null => Sass.Null
+ * Undefined => Sass.Null
+ * Symbol => Sass.Null
+ * AnythingElse => Sass.Null
+ * 
+ * Copyright (c) 2023-2025 Alex Grant (@localnerve), LocalNerve LLC
+ * Licensed under the MIT license.
+ */
+
+/**
+ * Convert a javascript value to a sass value of corresponding type.
+ * Modern Sass version.
+ * 
+ * @param {Sass} sass - Sass javascript API
+ * @param {*} value - A javascript value
+ * @returns {SassType} - A Sass typed value for the given javascript value
+ */
+function convertToSassTypesModern(sass, value) {
+  switch (typeof value) {
+    case 'boolean':
+      return value ? sass.sassTrue : sass.sassFalse;
+    case 'number':
+      return new sass.SassNumber(value);
+    case 'string':
+      return new sass.SassString(value, {
+        quotes: false
+      });
+    case 'object':
+      if (value === null) {
+        return sass.sassNull;
+      } else if (Array.isArray(value)) {
+        const sassArray = [];
+        for (let i = 0; i < value.length; ++i) {
+          sassArray[i] = convertToSassTypesModern(sass, value[i]);
+        }
+        return new sass.SassList(sassArray);
+      } else if (value instanceof Set) {
+        let i = 0;
+        const sassArray = [];
+        for (const item of value) {
+          sassArray[i++] = convertToSassTypesModern(sass, item);
+        }
+        return new sass.SassList(sassArray);
+      } else {
+        const sassArray = [];
+        const obj = value instanceof Map ? Object.fromEntries(value) : value;
+        for (const [key, val] of Object.entries(obj)) {
+          sassArray.push([convertToSassTypesModern(sass, key), convertToSassTypesModern(sass, val)]);
+        }
+        return new sass.SassMap(new _immutable.OrderedMap(sassArray));
+      }
+    default:
+      return sass.sassNull;
+  }
+}
+
+/**
+ * Convert a javascript value to a sass value of corresponding type.
+ * Legacy Sass version.
+ * 
+ * @param {Sass} sass - Sass javascript API
+ * @param {*} value - A javascript value
+ * @returns {SassType} - A Sass typed value for the given javascript value
+ */
+function convertToSassTypesLegacy(sass, value) {
+  switch (typeof value) {
+    case 'boolean':
+      return value ? sass.types.Boolean.TRUE : sass.types.Boolean.FALSE;
+    case 'number':
+      return new sass.types.Number(value);
+    case 'string':
+      return new sass.types.String(value);
+    case 'object':
+      if (value === null) {
+        return sass.types.Null.NULL;
+      } else if (Array.isArray(value)) {
+        const list = new sass.types.List(value.length);
+        for (let i = 0; i < value.length; ++i) {
+          list.setValue(i, convertToSassTypesLegacy(sass, value[i]));
+        }
+        return list;
+      } else if (value instanceof Set) {
+        const list = new sass.types.List(value.size);
+        let i = 0;
+        for (let val of value) {
+          list.setValue(i++, convertToSassTypesLegacy(sass, val));
+        }
+        return list;
+      } else {
+        const obj = value instanceof Map ? Object.fromEntries(value) : value;
+        const map = new sass.types.Map(Object.keys(obj).length);
+        let i = 0;
+        for (const [key, val] of Object.entries(obj)) {
+          map.setKey(i, convertToSassTypesLegacy(sass, key));
+          map.setValue(i++, convertToSassTypesLegacy(sass, val));
+        }
+        return map;
+      }
+    default:
+      return sass.types.Null.NULL;
+  }
+}

package/lib/legacyAPI.js

@@ -4,6 +4,7 @@
  * Copyright (c) 2023-2025 Alex Grant (@localnerve), LocalNerve LLC
  * Licensed under the MIT license.
  */
+import { convertToSassTypesLegacy } from "./types.js";
 
 export default function legacyAPI (sass, processor) {
   return {
@@ -51,6 +52,18 @@ export default function legacyAPI (sass, processor) {
         }
         done(list);
       });
+    },
+    'lookup($keys...)': (list, done) => {
+      let len = list.getLength(), i = 0;
+      const keys = [];
+      for(; i < len; ++i) {
+        keys[i] = list.getValue(i).getValue();
+      }
+
+      processor.lookup(keys, value => {
+        const result = convertToSassTypesLegacy(sass, value);
+        done(result);
+      });
     }
   };
 }

package/lib/modernAPIAsync.js

@@ -4,6 +4,7 @@
  * Copyright (c) 2023-2025 Alex Grant (@localnerve), LocalNerve LLC
  * Licensed under the MIT license.
  */
+import { convertToSassTypesModern } from "./types.js";
 
 export default function modernAPIAsync (sass, processor) {
   return {
@@ -91,6 +92,24 @@ export default function modernAPIAsync (sass, processor) {
           reject(err);
         }
       });
+    },
+    'lookup($keys...)': args => {
+      return new Promise((resolve, reject) => {
+        try {
+          const input = args[0].asList;
+          const keys = [];
+          for (let i = 0; i < input.size; ++i) {
+            keys[i] = input.get(i).assertString().text;
+          }
+          let result = sass.sassNull;
+          processor.lookup(keys, value => {
+            result = convertToSassTypesModern(sass, value);
+            resolve(result);
+          });
+        } catch (err) {
+          reject(err);
+        }
+      });
     }
   };
 }

package/lib/modernAPISync.js

@@ -5,6 +5,8 @@
  * Licensed under the MIT license.
  */
 
+import { convertToSassTypesModern } from './types.js';
+
 export default function modernAPISync (sass, processor) {
   return {
     'image-url($filename, $only_path: false)': args => {
@@ -65,6 +67,18 @@ export default function modernAPISync (sass, processor) {
         }
       });
       return new sass.SassList(result);
+    },
+    'lookup($keys...)': args => {
+      const input = args[0].asList;
+      const keys = [];
+      for (let i = 0; i < input.size; ++i) {
+        keys[i] = input.get(i).assertString().text;
+      }
+      let result = sass.sassNull;
+      processor.lookup(keys, value => {
+        result = convertToSassTypesModern(sass, value);
+      });
+      return result;
     }
   };
 }

package/lib/processor.js

@@ -30,7 +30,7 @@ const FONT_TYPES = {
 
 export default class Processor {
   constructor (options) {
-    this.options = options;
+    this.options = { ...{ data: {} }, ...options };
     const {
       images_path = defaultPaths.images_path,
       fonts_path = defaultPaths.fonts_path,
@@ -202,4 +202,13 @@ export default class Processor {
       this.font_url(file, complete(i, type));
     }
   }
+
+  lookup (keys, done) {
+    let data = this.options.data;
+    for (let key of keys) {
+      data = data[key];
+    }
+
+    done(data !== this.options.data ? data : null);
+  }
 }

package/lib/types.js

@@ -0,0 +1,117 @@
+/**
+ * Convert javascript types to sass types.
+ * 
+ * Supported Mappings:
+ * Boolean => Sass.Boolean
+ * Number => Sass.Number
+ * String => Sass.String
+ * Array => Sass.List
+ * Set => Sass.List
+ * Object => Sass.Map
+ * Map => Sass.Map
+ * BigInt => Sass.Null
+ * Function => Sass.Null
+ * Null => Sass.Null
+ * Undefined => Sass.Null
+ * Symbol => Sass.Null
+ * AnythingElse => Sass.Null
+ * 
+ * Copyright (c) 2023-2025 Alex Grant (@localnerve), LocalNerve LLC
+ * Licensed under the MIT license.
+ */
+import { OrderedMap } from 'immutable';
+
+/**
+ * Convert a javascript value to a sass value of corresponding type.
+ * Modern Sass version.
+ * 
+ * @param {Sass} sass - Sass javascript API
+ * @param {*} value - A javascript value
+ * @returns {SassType} - A Sass typed value for the given javascript value
+ */
+export function convertToSassTypesModern (sass, value) {
+  switch (typeof value) {
+    case 'boolean':
+      return value ? sass.sassTrue : sass.sassFalse;
+    case 'number':
+      return new sass.SassNumber(value);
+    case 'string':
+      return new sass.SassString(value, { quotes: false });
+    case 'object':
+      if (value === null) {
+        return sass.sassNull;
+      } else if (Array.isArray(value)) {
+        const sassArray = [];
+        for (let i = 0; i < value.length; ++i) {
+          sassArray[i] = convertToSassTypesModern(sass, value[i]);
+        }
+        return new sass.SassList(sassArray);
+      } else if (value instanceof Set) {
+        let i = 0;
+        const sassArray = [];
+        for (const item of value) {
+          sassArray[i++] = convertToSassTypesModern(sass, item);
+        }
+        return new sass.SassList(sassArray);
+      } else {
+        const sassArray = [];
+        const obj = value instanceof Map ? Object.fromEntries(value) : value;
+        for (const [key, val] of Object.entries(obj)) {
+          sassArray.push([
+            convertToSassTypesModern(sass, key),
+            convertToSassTypesModern(sass, val)
+          ]);
+        }
+        return new sass.SassMap(new OrderedMap(sassArray));
+      }
+    default:
+      return sass.sassNull;
+  }
+}
+
+/**
+ * Convert a javascript value to a sass value of corresponding type.
+ * Legacy Sass version.
+ * 
+ * @param {Sass} sass - Sass javascript API
+ * @param {*} value - A javascript value
+ * @returns {SassType} - A Sass typed value for the given javascript value
+ */
+export function convertToSassTypesLegacy (sass, value) {
+  switch (typeof value) {
+    case 'boolean':
+      return value ? sass.types.Boolean.TRUE : sass.types.Boolean.FALSE;
+    case 'number':
+      return new sass.types.Number(value);
+    case 'string':
+      return new sass.types.String(value);
+    case 'object':
+      if (value === null) {
+        return sass.types.Null.NULL;
+      } else if (Array.isArray(value)) {
+        const list = new sass.types.List(value.length);
+        for (let i = 0; i < value.length; ++i) {
+          list.setValue(i, convertToSassTypesLegacy(sass, value[i]));
+        }
+        return list;
+      } else if (value instanceof Set) {
+        const list = new sass.types.List(value.size);
+        let i = 0;
+        for (let val of value) {
+          list.setValue(i++, convertToSassTypesLegacy(sass, val));
+        }
+        return list;
+      } else {
+        const obj = value instanceof Map ? Object.fromEntries(value) : value;
+        const map = new sass.types.Map(Object.keys(obj).length);
+        let i = 0;
+        for (const [key, val] of Object.entries(obj)) {
+          map.setKey(i, convertToSassTypesLegacy(sass, key));
+          map.setValue(i++, convertToSassTypesLegacy(sass, val));
+        }
+        return map;
+      }
+    default:
+      return sass.types.Null.NULL;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localnerve/sass-asset-functions",
-  "version": "6.9.0",
+  "version": "6.10.0-rc.2",
   "description": "compass-style asset functions for dart-sass or other sass compilers",
   "main": "index.js",
   "exports": {
@@ -34,7 +34,8 @@
     "image-width",
     "image-height",
     "font-url",
-    "font-files"
+    "font-files",
+    "lookup"
   ],
   "author": "Alex Grant <alex@localnerve.com>",
   "maintainers": [
@@ -51,6 +52,7 @@
   "homepage": "https://github.com/localnerve/sass-asset-functions",
   "dependencies": {
     "image-size": "^2.0.1",
+    "immutable": "^5.0.3",
     "mime-types": "^2.1.35",
     "sass": "^1.86.0"
   },