@gesslar/sassy 0.20.2 → 0.21.1

package/src/Data.js

@@ -59,7 +59,10 @@ export default class Data {
    *
    * @type {string[]}
    */
-  static dataTypes = Object.freeze([...Data.primitives, ...Data.constructors.map(c => c.toLowerCase())])
+  static dataTypes = Object.freeze([
+    ...Data.primitives,
+    ...Data.constructors.map(c => c.toLowerCase())
+  ])
 
   /**
    * Array of type names that can be checked for emptiness.
@@ -155,12 +158,13 @@ export default class Data {
    *
    * @param {Array} arr - The array to pad.
    * @param {number} length - The length to pad the array to.
-   * @param {any} value - The value to pad the array with.
+   * @param {unknown} value - The value to pad the array with.
    * @param {number} position - The position to pad the array at.
    * @returns {Array} The padded array.
    */
   static arrayPad(arr, length, value, position = 0) {
     const diff = length - arr.length
+
     if(diff <= 0)
       return arr
 
@@ -199,8 +203,8 @@ export default class Data {
   /**
    * Allocates an object from a source array and a spec array or function.
    *
-   * @param {any} source The source array
-   * @param {any|Function} spec The spec array or function
+   * @param {unknown} source The source array
+   * @param {Array|function(unknown): unknown} spec The spec array or function
    * @returns {Promise<object>} The allocated object
    */
   static async allocateObject(source, spec) {
@@ -250,7 +254,7 @@ export default class Data {
    * Maps an object using a transformer function
    *
    * @param {object} original The original object
-   * @param {Function} transformer The transformer function
+   * @param {function(unknown): unknown} transformer The transformer function
    * @param {boolean} mutate Whether to mutate the original object
    * @returns {Promise<object>} The mapped object
    */
@@ -294,13 +298,15 @@ export default class Data {
   /**
    * Checks if a value is of a specified type
    *
-   * @param {any} value The value to check
+   * @param {unknown} value The value to check
    * @param {string|TypeSpec} type The type to check for
    * @param {object} options Additional options for checking
    * @returns {boolean} Whether the value is of the specified type
    */
   static isType(value, type, options = {}) {
-    const typeSpec = type instanceof TypeSpec ? type : Data.newTypeSpec(type, options)
+    const typeSpec = type instanceof TypeSpec
+      ? type
+      : Data.newTypeSpec(type, options)
 
     return typeSpec.match(value, options)
   }
@@ -320,7 +326,7 @@ export default class Data {
    * function does not parse the type string, and only checks for primitive
    * or constructor types.
    *
-   * @param {any} value - The value to check
+   * @param {unknown} value - The value to check
    * @param {string} type - The type to check for
    * @returns {boolean} Whether the value is of the specified type
    */
@@ -359,7 +365,7 @@ export default class Data {
   /**
    * Returns the type of a value, whether it be a primitive, object, or function.
    *
-   * @param {any} value - The value to check
+   * @param {unknown} value - The value to check
    * @returns {string} The type of the value
    */
   static typeOf(value) {
@@ -369,7 +375,7 @@ export default class Data {
   /**
    * Checks a value is undefined or null.
    *
-   * @param {any} value The value to check
+   * @param {unknown} value The value to check
    * @returns {boolean} Whether the value is undefined or null
    */
   static isNothing(value) {
@@ -380,7 +386,7 @@ export default class Data {
    * Checks if a value is empty. This function is used to check if an object,
    * array, or string is empty. Null and undefined values are considered empty.
    *
-   * @param {any} value The value to check
+   * @param {unknown} value The value to check
    * @param {boolean} checkForNothing Whether to check for null or undefined
    *                                  values
    * @returns {boolean} Whether the value is empty
@@ -423,7 +429,7 @@ export default class Data {
       const value = obj[name]
 
       // Recursively freeze nested objects
-      if(value && typeof value === "object")
+      if(typeof value === "object" && value !== null)
         Data.deepFreezeObject(value)
     }
 
@@ -442,8 +448,10 @@ export default class Data {
   static assureObjectPath(obj, keys) {
     let current = obj  // a moving reference to internal objects within obj
     const len = keys.length
+
     for(let i = 0; i < len; i++) {
       const elem = keys[i]
+
       if(!current[elem])
         current[elem] = {}
 
@@ -459,8 +467,8 @@ export default class Data {
    * the structure if it does not exist.
    *
    * @param {object} obj - The target object to set the value in
-   * @param {string[]} keys - Array of keys representing the path to the target property
-   * @param {*} value - The value to set at the target location
+   * @param {Array<string>} keys - Array of keys representing the path to the target property
+   * @param {unknown} value - The value to set at the target location
    */
   static setNestedValue(obj, keys, value) {
     const nested = Data.assureObjectPath(obj, keys.slice(0, -1))
@@ -475,7 +483,8 @@ export default class Data {
    * @returns {object} The merged object
    */
   static mergeObject(...sources) {
-    const isObject = obj => obj && typeof obj === "object" && !Array.isArray(obj)
+    const isObject = obj => typeof obj === "object" && obj !== null && !Array.isArray(obj)
+
     return sources.reduce((acc, obj) => {
       if(!isObject(obj))
         return acc
@@ -512,11 +521,12 @@ export default class Data {
    * Applies the predicate to all items in parallel and returns filtered results.
    *
    * @param {Array} arr - The array to filter
-   * @param {Function} predicate - Async predicate function that returns a promise resolving to boolean
+   * @param {function(unknown): Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
    * @returns {Promise<Array>} Promise resolving to the filtered array
    */
   static async asyncFilter(arr, predicate) {
     const results = await Promise.all(arr.map(predicate))
+
     return arr.filter((_, index) => results[index])
   }
 

package/src/Evaluator.js

@@ -56,6 +56,37 @@ export default class Evaluator {
    */
   static func = /(?<captured>(?<func>\w+)\((?<args>[^()]+)\))/
 
+  /**
+   * Extracts a variable name from a string containing variable syntax.
+   * Supports $(var), $var, and ${var} patterns.
+   *
+   * @param {string} [str] - String that may contain a variable reference
+   * @returns {string|null} The variable name or null if none found
+   */
+  static extractVariableName(str="") {
+    const {none, parens, braces} = Evaluator.sub.exec(str)?.groups ?? {}
+
+    return none || parens || braces || null
+  }
+
+  /**
+   * Extracts function name and arguments from a string containing function syntax.
+   * Supports functionName(args) patterns.
+   *
+   * @param {string} [str] - String that may contain a function call
+   * @returns {{func:string, args:string}|null} Object with {func, args} or null if none found
+   */
+  static extractFunctionCall(str="") {
+    const match = Evaluator.func.exec(str)
+
+    if(!match?.groups)
+      return null
+
+    const {func, args} = match.groups
+
+    return {func, args}
+  }
+
   #pool = new ThemePool()
   get pool() {
     return this.#pool
@@ -80,19 +111,34 @@ export default class Evaluator {
    *  - Input array is mutated in-place (`value` fields change).
    *  - No return value. Evident by the absence of a return statement.
    *
-   * @param {Array<{flatPath:string,value:any}>} decomposed - Variable entries to resolve.
+   * @param {Array<{flatPath:string,value:unknown}>} decomposed - Variable entries to resolve.
+   * @example
+   * // Example decomposed input with variables and theme references
+   * const evaluator = new Evaluator();
+   * const decomposed = [
+   *   { flatPath: 'vars.primary', value: '#3366cc' },
+   *   { flatPath: 'theme.colors.background', value: '$(vars.primary)' },
+   *   { flatPath: 'theme.colors.accent', value: 'lighten($(vars.primary), 20)' }
+   * ];
+   * evaluator.evaluate(decomposed);
+   * // After evaluation, values are resolved:
+   * // decomposed[1].value === '#3366cc'
+   * // decomposed[2].value === '#5588dd' (lightened color)
    */
   evaluate(decomposed) {
     let it = 0
+
     do {
       decomposed.forEach(item => {
         const trail = new Array()
 
         if(typeof item.value === "string") {
           const raw = item.value
+
           item.value = this.#evaluateValue(trail, item.flatPath, raw)
           // Keep lookup in sync with latest resolved value for chained deps.
           const token = this.#pool.findToken(item.flatPath)
+
           this.#pool.resolve(item.flatPath, item.value)
           this.#pool.rawResolve(raw, item.value)
 
@@ -137,7 +183,7 @@ export default class Evaluator {
    * @param {string} parentTokenKeyString - Key string for parent token.
    * @param {string} value - Raw tokenised string to resolve.
    * @returns {string?} Fully resolved string.
-   * @throws If we've reached maximum iterations.
+   * @throws {Sass} If we've reached maximum iterations.
    */
   #evaluateValue(trail, parentTokenKeyString, value) {
     let it = 0
@@ -194,6 +240,7 @@ export default class Evaluator {
 
     // Check if this is a color function (like oklch, rgb, hsl, etc.)
     const parsedColor = parse(value)
+
     if(parsedColor) {
       token.setParsedColor(parsedColor)
     }
@@ -225,8 +272,8 @@ export default class Evaluator {
    * @returns {ThemeToken|null} The resolved token or null.
    */
   #resolveVariable(value) {
-    const {captured,none,parens,braces} = Evaluator.sub.exec(value).groups
-    const work = none ?? parens ?? braces
+    const {captured} = Evaluator.sub.exec(value).groups
+    const work = Evaluator.extractVariableName(value)
     const existing = this.#pool.findToken(work)
 
     if(!existing)
@@ -249,13 +296,19 @@ export default class Evaluator {
    * @returns {ThemeToken|null} The resolved token or null.
    */
   #resolveFunction(value) {
-    const {captured,func,args} = Evaluator.func.exec(value).groups
+    const {captured} = Evaluator.func.exec(value).groups
+    const result = Evaluator.extractFunctionCall(value)
+
+    if(!result)
+      return null
+
+    const {func, args} = result
     const split = args?.split(",").map(a => a.trim()) ?? []
 
     // Look up source tokens for arguments to preserve color space
     const sourceTokens = split.map(arg => {
       return this.#pool.findToken(arg) ||
-             this.#pool.getTokens?.get?.(arg) ||
+             this.#pool.getTokens()?.get?.(arg) ||
              null
     })
 
@@ -336,7 +389,7 @@ export default class Evaluator {
    * Predicate: does this item's value still contain variable or function tokens?
    *
    * @private
-   * @param {{value:any}} item - Entry to test.
+   * @param {{value:unknown}} item - Entry to test.
    * @returns {boolean} True if token patterns present.
    */
   #tokenCheck(item) {

package/src/File.js

@@ -39,6 +39,7 @@ export default class File {
       return url.pathToFileURL(pathName).href
     } catch(e) {
       void e // stfu linter
+
       return pathName
     }
   }
@@ -52,6 +53,7 @@ export default class File {
   static async canReadFile(file) {
     try {
       await fs.access(file.path, fs.constants.R_OK)
+
       return true
     } catch(_) {
       return false
@@ -67,6 +69,7 @@ export default class File {
   static async canWriteFile(file) {
     try {
       await fs.access(file.path, fs.constants.W_OK)
+
       return true
     } catch(_error) {
       return false
@@ -82,6 +85,7 @@ export default class File {
   static async fileExists(file) {
     try {
       await fs.access(file.path, fs.constants.R_OK)
+
       return true
     } catch(_) {
       return false
@@ -97,6 +101,7 @@ export default class File {
   static async fileSize(file) {
     try {
       const stat = await fs.stat(file.path)
+
       return stat.size
     } catch(_) {
       return null
@@ -113,6 +118,7 @@ export default class File {
   static async fileModified(file) {
     try {
       const stat = await fs.stat(file.path)
+
       return stat.mtime
     } catch(_) {
       return null
@@ -179,8 +185,13 @@ export default class File {
    */
   static async getFiles(glob) {
     Valid.assert(
-      ((typeof glob === "string" && glob.length > 0) ||
-       (Array.isArray(glob) && Data.uniformStringArray(glob) && glob.length > 0)),
+      (
+        (typeof glob === "string" && glob.length > 0) ||
+        (
+          Array.isArray(glob) && Data.uniformStringArray(glob) &&
+          glob.length > 0
+        )
+      ),
       "glob must be a non-empty string or array of strings.",
       1
     )
@@ -225,6 +236,7 @@ export default class File {
       found.map(async dirent => {
         const fullPath = path.join(directory, dirent.name)
         const stat = await fs.stat(fullPath)
+
         return {dirent, stat, fullPath}
       }),
     )