@gesslar/toolkit 5.0.1 → 5.1.0

package/README.md

@@ -47,7 +47,6 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | Valid | Validation and assertion methods |
 | Watcher | File and directory change watcher with debounce protection |
 
-
 ## Installation
 
 ```shell
@@ -151,7 +150,7 @@ Sincerely, Senator Yabba of the Dabba (Doo)
 
 ## License
 
-`@gesslar/toolkit` is released into the public domain under the [0BSD](LICENSE.txt).
+`@gesslar/toolkit` is released under the [0BSD](LICENSE.txt).
 
 This package includes or depends on third-party components under their own
 licenses:

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "5.0.1",
+  "version": "5.1.0",
   "license": "0BSD",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -83,7 +83,7 @@
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^2.4.0",
+    "@gesslar/uglier": "^2.4.1",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "eslint": "^10.2.0",
     "happy-dom": "^20.8.9",

package/src/browser/lib/TypeSpec.js

@@ -193,7 +193,7 @@ export default class TypeSpec {
       // Handle non-array values
       if(!isArray && !allowedArray) {
         if(valueType === allowedType)
-          return allowEmpty || !empty
+          return Data.isBaseType(value, allowedType) && (allowEmpty || !empty)
 
         if(valueType === "Null" || valueType === "Undefined")
           return false

package/src/browser/lib/Valid.js

@@ -9,21 +9,36 @@ import Sass from "./Sass.js"
 import Data from "./Data.js"
 import Collection from "./Collection.js"
 
+/**
+ * Options for type validation methods.
+ *
+ * @typedef {object} TypeValidationOptions
+ * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+ */
+
 /**
  * Validation utility class providing type checking and assertion methods.
  */
 export default class Valid {
+  /** @type {typeof Sass} */
+  static _Sass = Sass
+
   /**
    * Validates a value against a type. Uses Data.isType.
    *
    * @param {unknown} value - The value to validate
    * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-   * @param {object} [options] - Additional options for validation.
+   * @param {TypeValidationOptions} [options] - Additional options for validation.
    */
   static type(value, type, options) {
-    Valid.assert(
+    const expected = [type]
+
+    if(options?.allowEmpty !== true)
+      expected.push("[no empty values]")
+
+    this.assert(
       Data.isType(value, type, options),
-      `Invalid type. Expected ${type}, got ${Data.typeOf(value)}`
+      `Invalid type. Expected ${expected.join(" ")}, got ${Data.typeOf(value)}`
     )
   }
 
@@ -37,23 +52,20 @@ export default class Valid {
    *                         met (optional)
    */
   static assert(condition, message, arg = null) {
-    if(!Data.isType(condition, "boolean")) {
-      throw Sass.new(`Condition must be a boolean, got ${condition}`)
-    }
+    if(!Data.isType(condition, "boolean"))
+      throw this._Sass.new(`Condition must be a boolean, got ${condition}`)
 
-    if(!Data.isType(message, "string")) {
-      throw Sass.new(`Message must be a string, got ${message}`)
-    }
+    if(!Data.isType(message, "string"))
+      throw this._Sass.new(`Message must be a string, got ${message}`)
 
-    if(!(arg === null || arg === undefined || typeof arg === "number")) {
-      throw Sass.new(`Arg must be a number, got ${arg}`)
-    }
+    if(!(arg === null || arg === undefined || typeof arg === "number"))
+      throw this._Sass.new(`Arg must be a number, got ${arg}`)
 
     if(!condition)
-      throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
+      throw this._Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
   }
 
-  static #restrictedProto = ["__proto__", "constructor", "prototype"]
+  static #restrictedProto = Object.freeze(["__proto__", "constructor", "prototype"])
 
   /**
    * Protects against prototype pollution by checking keys for dangerous property names.
@@ -63,11 +75,11 @@ export default class Valid {
    * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
    */
   static prototypePollutionProtection(keys) {
-    Valid.type(keys, "String[]")
+    this.type(keys, "String[]")
 
-    const oopsIDidItAgain = Collection.intersection(this.#restrictedProto, keys)
+    const oopsIDidItAgain = Collection.intersection(Valid.#restrictedProto, keys)
 
-    Valid.assert(
+    this.assert(
       oopsIDidItAgain.length === 0,
       `We don't pee in your pool, don't pollute ours with your ${String(oopsIDidItAgain)}`
     )

package/src/node/lib/Cache.js

@@ -1,4 +1,4 @@
-import Valid from "../../browser/lib/Valid.js"
+import Valid from "./Valid.js"
 import Data from "./Data.js"
 import Sass from "./Sass.js"
 

package/src/node/lib/Valid.js

@@ -2,85 +2,17 @@
  * @file Valid.js
  *
  * Node-flavoured validation utilities that throw the Node Sass error type.
- * Mirrors the browser Valid API so browser and Node callers behave the same.
+ * Extends the browser Valid, swapping in the Node Sass for richer reporting.
  */
 
+import BrowserValid from "../../browser/lib/Valid.js"
 import Sass from "./Sass.js"
-import Data from "../../browser/lib/Data.js"
-import Collection from "../../browser/lib/Collection.js"
-
-/**
- * Options for type validation methods.
- *
- * @typedef {object} TypeValidationOptions
- * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
- */
 
 /**
  * Validation utility class providing type checking and assertion methods.
+ * Inherits all behaviour from browser Valid; only the Sass class differs.
  */
-export default class Valid {
-  static #restrictedProto = ["__proto__", "constructor", "prototype"]
-
-  /**
-   * Validates a value against a type. Uses Data.isType.
-   *
-   * @param {unknown} value - The value to validate
-   * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-   * @param {TypeValidationOptions} [options] - Additional options for validation.
-   */
-  static type(value, type, options) {
-    const expected = [type]
-
-    if(options?.allowEmpty !== true)
-      expected.push("[no empty values]")
-
-    Valid.assert(
-      Data.isType(value, type, options),
-      `Invalid type. Expected ${expected.join(" ")}, got ${Data.typeOf(value)}`
-    )
-  }
-
-  /**
-   * Asserts a condition
-   *
-   * @param {boolean} condition - The condition to assert
-   * @param {string} message - The message to display if the condition is not
-   *                           met
-   * @param {number} [arg] - The argument to display if the condition is not
-   *                         met (optional)
-   */
-  static assert(condition, message, arg = null) {
-    if(!Data.isType(condition, "boolean"))
-      throw Sass.new(`Condition must be a boolean, got ${condition}`)
-
-    if(!Data.isType(message, "string"))
-      throw Sass.new(`Message must be a string, got ${message}`)
-
-    if(!(arg === null || arg === undefined || typeof arg === "number"))
-      throw Sass.new(`Arg must be a number, got ${arg}`)
-
-    if(!condition)
-      throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
-  }
-
-  /**
-   * Protects against prototype pollution by checking keys for dangerous
-   * property names.
-   *
-   * Throws if any restricted prototype properties are found in the keys array.
-   *
-   * @param {Array<string>} keys - Array of property keys to validate
-   * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
-   */
-  static prototypePollutionProtection(keys) {
-    Valid.type(keys, "String[]")
-
-    const oopsIDidItAgain = Collection.intersection(this.#restrictedProto, keys)
-
-    Valid.assert(
-      oopsIDidItAgain.length === 0,
-      `We don't pee in your pool, don't pollute ours with your ${String(oopsIDidItAgain)}`
-    )
-  }
+export default class Valid extends BrowserValid {
+  /** @type {typeof Sass} */
+  static _Sass = Sass
 }

package/types/browser/lib/Valid.d.ts

@@ -1,15 +1,23 @@
+/**
+ * Options for type validation methods.
+ *
+ * @typedef {object} TypeValidationOptions
+ * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+ */
 /**
  * Validation utility class providing type checking and assertion methods.
  */
 export default class Valid {
+    /** @type {typeof Sass} */
+    static _Sass: typeof Sass;
     /**
      * Validates a value against a type. Uses Data.isType.
      *
      * @param {unknown} value - The value to validate
      * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-     * @param {object} [options] - Additional options for validation.
+     * @param {TypeValidationOptions} [options] - Additional options for validation.
      */
-    static type(value: unknown, type: string, options?: object): void;
+    static type(value: unknown, type: string, options?: TypeValidationOptions): void;
     /**
      * Asserts a condition
      *
@@ -20,7 +28,7 @@ export default class Valid {
      *                         met (optional)
      */
     static assert(condition: boolean, message: string, arg?: number): void;
-    static #restrictedProto: string[];
+    static #restrictedProto: readonly string[];
     /**
      * Protects against prototype pollution by checking keys for dangerous property names.
      * Throws if any restricted prototype properties are found in the keys array.
@@ -30,4 +38,14 @@ export default class Valid {
      */
     static prototypePollutionProtection(keys: Array<string>): void;
 }
+/**
+ * Options for type validation methods.
+ */
+export type TypeValidationOptions = {
+    /**
+     * - Whether empty values are allowed
+     */
+    allowEmpty?: boolean;
+};
+import Sass from "./Sass.js";
 //# sourceMappingURL=Valid.d.ts.map

package/types/browser/lib/Valid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Valid.js"],"names":[],"mappings":"AAWA;;GAEG;AACH;IACE;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAkBhB;IAED,kCAAmE;IAEnE;;;;;;OAMG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF"}
+{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Valid.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AAEH;;GAEG;AACH;IACE,0BAA0B;IAC1B,cADW,OAAO,IAAI,CACH;IAEnB;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,qBAAqB,QAY/B;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAehB;IAED,2CAAkF;IAElF;;;;;;OAMG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF;;;;;;;;iBAvEa,OAAO;;iBARJ,WAAW"}

package/types/node/lib/Valid.d.ts

@@ -1,50 +1,11 @@
-/**
- * Options for type validation methods.
- *
- * @typedef {object} TypeValidationOptions
- * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
- */
 /**
  * Validation utility class providing type checking and assertion methods.
+ * Inherits all behaviour from browser Valid; only the Sass class differs.
  */
-export default class Valid {
-    static #restrictedProto: string[];
-    /**
-     * Validates a value against a type. Uses Data.isType.
-     *
-     * @param {unknown} value - The value to validate
-     * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-     * @param {TypeValidationOptions} [options] - Additional options for validation.
-     */
-    static type(value: unknown, type: string, options?: TypeValidationOptions): void;
-    /**
-     * Asserts a condition
-     *
-     * @param {boolean} condition - The condition to assert
-     * @param {string} message - The message to display if the condition is not
-     *                           met
-     * @param {number} [arg] - The argument to display if the condition is not
-     *                         met (optional)
-     */
-    static assert(condition: boolean, message: string, arg?: number): void;
-    /**
-     * Protects against prototype pollution by checking keys for dangerous
-     * property names.
-     *
-     * Throws if any restricted prototype properties are found in the keys array.
-     *
-     * @param {Array<string>} keys - Array of property keys to validate
-     * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
-     */
-    static prototypePollutionProtection(keys: Array<string>): void;
+export default class Valid extends BrowserValid {
+    /** @type {typeof Sass} */
+    static _Sass: typeof Sass;
 }
-/**
- * Options for type validation methods.
- */
-export type TypeValidationOptions = {
-    /**
-     * - Whether empty values are allowed
-     */
-    allowEmpty?: boolean;
-};
+import BrowserValid from "../../browser/lib/Valid.js";
+import Sass from "./Sass.js";
 //# sourceMappingURL=Valid.d.ts.map

package/types/node/lib/Valid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Valid.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AAEH;;GAEG;AACH;IACE,kCAAmE;IAEnE;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,qBAAqB,QAY/B;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAehB;IAED;;;;;;;;OAQG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF;;;;;;;;iBAtEa,OAAO"}
+{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Valid.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH;IACE,0BAA0B;IAC1B,cADW,OAAO,IAAI,CACH;CACpB;yBAVwB,4BAA4B;iBACpC,WAAW"}

package/vendor/toolkit.esm.js

@@ -1,4 +1,4 @@
-// @gesslar/toolkit v5.0.1 - ES module bundle
+// @gesslar/toolkit v5.1.0 - ES module bundle
 /**
  * @file Tantrum.js
  *
@@ -317,21 +317,36 @@ class Sass extends Error {
  */
 
 
+/**
+ * Options for type validation methods.
+ *
+ * @typedef {object} TypeValidationOptions
+ * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+ */
+
 /**
  * Validation utility class providing type checking and assertion methods.
  */
 class Valid {
+  /** @type {typeof Sass} */
+  static _Sass = Sass
+
   /**
    * Validates a value against a type. Uses Data.isType.
    *
    * @param {unknown} value - The value to validate
    * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-   * @param {object} [options] - Additional options for validation.
+   * @param {TypeValidationOptions} [options] - Additional options for validation.
    */
   static type(value, type, options) {
-    Valid.assert(
+    const expected = [type];
+
+    if(options?.allowEmpty !== true)
+      expected.push("[no empty values]");
+
+    this.assert(
       Data.isType(value, type, options),
-      `Invalid type. Expected ${type}, got ${Data.typeOf(value)}`
+      `Invalid type. Expected ${expected.join(" ")}, got ${Data.typeOf(value)}`
     );
   }
 
@@ -345,23 +360,20 @@ class Valid {
    *                         met (optional)
    */
   static assert(condition, message, arg = null) {
-    if(!Data.isType(condition, "boolean")) {
-      throw Sass.new(`Condition must be a boolean, got ${condition}`)
-    }
+    if(!Data.isType(condition, "boolean"))
+      throw this._Sass.new(`Condition must be a boolean, got ${condition}`)
 
-    if(!Data.isType(message, "string")) {
-      throw Sass.new(`Message must be a string, got ${message}`)
-    }
+    if(!Data.isType(message, "string"))
+      throw this._Sass.new(`Message must be a string, got ${message}`)
 
-    if(!(arg === null || arg === undefined || typeof arg === "number")) {
-      throw Sass.new(`Arg must be a number, got ${arg}`)
-    }
+    if(!(arg === null || arg === undefined || typeof arg === "number"))
+      throw this._Sass.new(`Arg must be a number, got ${arg}`)
 
     if(!condition)
-      throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
+      throw this._Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
   }
 
-  static #restrictedProto = ["__proto__", "constructor", "prototype"]
+  static #restrictedProto = Object.freeze(["__proto__", "constructor", "prototype"])
 
   /**
    * Protects against prototype pollution by checking keys for dangerous property names.
@@ -371,11 +383,11 @@ class Valid {
    * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
    */
   static prototypePollutionProtection(keys) {
-    Valid.type(keys, "String[]");
+    this.type(keys, "String[]");
 
-    const oopsIDidItAgain = Collection.intersection(this.#restrictedProto, keys);
+    const oopsIDidItAgain = Collection.intersection(Valid.#restrictedProto, keys);
 
-    Valid.assert(
+    this.assert(
       oopsIDidItAgain.length === 0,
       `We don't pee in your pool, don't pollute ours with your ${String(oopsIDidItAgain)}`
     );
@@ -761,7 +773,7 @@ class TypeSpec {
       // Handle non-array values
       if(!isArray && !allowedArray) {
         if(valueType === allowedType)
-          return allowEmpty || !empty
+          return Data.isBaseType(value, allowedType) && (allowEmpty || !empty)
 
         if(valueType === "Null" || valueType === "Undefined")
           return false

package/vendor/toolkit.umd.js

@@ -1,4 +1,4 @@
-// @gesslar/toolkit v5.0.1 - UMD bundle
+// @gesslar/toolkit v5.1.0 - UMD bundle
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -323,21 +323,36 @@
    */
 
 
+  /**
+   * Options for type validation methods.
+   *
+   * @typedef {object} TypeValidationOptions
+   * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+   */
+
   /**
    * Validation utility class providing type checking and assertion methods.
    */
   class Valid {
+    /** @type {typeof Sass} */
+    static _Sass = Sass
+
     /**
      * Validates a value against a type. Uses Data.isType.
      *
      * @param {unknown} value - The value to validate
      * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-     * @param {object} [options] - Additional options for validation.
+     * @param {TypeValidationOptions} [options] - Additional options for validation.
      */
     static type(value, type, options) {
-      Valid.assert(
+      const expected = [type];
+
+      if(options?.allowEmpty !== true)
+        expected.push("[no empty values]");
+
+      this.assert(
         Data.isType(value, type, options),
-        `Invalid type. Expected ${type}, got ${Data.typeOf(value)}`
+        `Invalid type. Expected ${expected.join(" ")}, got ${Data.typeOf(value)}`
       );
     }
 
@@ -351,23 +366,20 @@
      *                         met (optional)
      */
     static assert(condition, message, arg = null) {
-      if(!Data.isType(condition, "boolean")) {
-        throw Sass.new(`Condition must be a boolean, got ${condition}`)
-      }
+      if(!Data.isType(condition, "boolean"))
+        throw this._Sass.new(`Condition must be a boolean, got ${condition}`)
 
-      if(!Data.isType(message, "string")) {
-        throw Sass.new(`Message must be a string, got ${message}`)
-      }
+      if(!Data.isType(message, "string"))
+        throw this._Sass.new(`Message must be a string, got ${message}`)
 
-      if(!(arg === null || arg === undefined || typeof arg === "number")) {
-        throw Sass.new(`Arg must be a number, got ${arg}`)
-      }
+      if(!(arg === null || arg === undefined || typeof arg === "number"))
+        throw this._Sass.new(`Arg must be a number, got ${arg}`)
 
       if(!condition)
-        throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
+        throw this._Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
     }
 
-    static #restrictedProto = ["__proto__", "constructor", "prototype"]
+    static #restrictedProto = Object.freeze(["__proto__", "constructor", "prototype"])
 
     /**
      * Protects against prototype pollution by checking keys for dangerous property names.
@@ -377,11 +389,11 @@
      * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
      */
     static prototypePollutionProtection(keys) {
-      Valid.type(keys, "String[]");
+      this.type(keys, "String[]");
 
-      const oopsIDidItAgain = Collection.intersection(this.#restrictedProto, keys);
+      const oopsIDidItAgain = Collection.intersection(Valid.#restrictedProto, keys);
 
-      Valid.assert(
+      this.assert(
         oopsIDidItAgain.length === 0,
         `We don't pee in your pool, don't pollute ours with your ${String(oopsIDidItAgain)}`
       );
@@ -767,7 +779,7 @@
         // Handle non-array values
         if(!isArray && !allowedArray) {
           if(valueType === allowedType)
-            return allowEmpty || !empty
+            return Data.isBaseType(value, allowedType) && (allowEmpty || !empty)
 
           if(valueType === "Null" || valueType === "Undefined")
             return false