@gesslar/toolkit 5.7.0 → 5.8.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "5.7.0",
+  "version": "5.8.0",
   "license": "0BSD",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/node/lib/Data.js

@@ -2,36 +2,46 @@ import JSON5 from "json5"
 import YAML from "yaml"
 import BrowserData from "../../browser/lib/Data.js"
 import Sass from "./Sass.js"
+import Valid from "../../node/lib/Valid.js"
 
 /**
  * Node-side extension of Data with parsing utilities that require
  * node-specific dependencies.
  */
 export default class Data extends BrowserData {
+  static LOAD_DATA_TYPES = Object.freeze({
+    json: Object.freeze([JSON]),    // least permissive
+    json5: Object.freeze([JSON5]),
+    yaml: Object.freeze([YAML]),    // most permissive
+  })
+
   /**
-   * Parses text content as structured data (JSON5 or YAML).
+   * Parses text content as structured data (JSON, JSON5, or YAML).
+   *
+   * The `json` type uses strict JSON parsing and will NOT accept JSON5
+   * extensions (comments, trailing commas, unquoted keys); use `json5` for
+   * that. The `any` type tries each format from least to most permissive.
    *
    * @param {string} source - The text content to parse
-   * @param {string} [type="any"] - The expected format ("json",
-   *   "json5", "yaml", or "any")
+   * @param {string} [type="any"] - The expected format ("json", "json5",
+   *  "yaml", or "any")
    * @returns {unknown} The parsed data
-   * @throws {Sass} If content cannot be parsed or type is
-   *   unsupported
+   * @throws {Sass} If content cannot be parsed or type is unsupported
    */
   static textAsData(source, type="any") {
+    Valid.type(source, "String")
+    Valid.type(type, "String")
+
     const normalizedType = type.toLowerCase()
-    const toTry = {
-      json5: [JSON5],
-      json: [JSON5],
-      yaml: [YAML],
-      any: [JSON5, YAML],
-    }[normalizedType]
-
-    if(!toTry) {
-      throw Sass.new(
-        `Unsupported data type '${type}'.`
-        + ` Supported types: json, json5, yaml.`)
-    }
+
+    Valid.assert(
+      normalizedType === "any" || Object.hasOwn(this.LOAD_DATA_TYPES, normalizedType),
+      `Type must be one of any, ${Object.keys(this.LOAD_DATA_TYPES).join(", ")}.`
+    )
+
+    const toTry = normalizedType === "any"
+      ? Object.values(this.LOAD_DATA_TYPES).flat()
+      : this.LOAD_DATA_TYPES[normalizedType]
 
     for(const format of toTry) {
       try {
@@ -43,7 +53,14 @@ export default class Data extends BrowserData {
       }
     }
 
+    const tried = toTry.map(format =>
+      format === JSON
+        ? "JSON"
+        : format === JSON5
+          ? "JSON5"
+          : "YAML")
+
     throw Sass.new(
-      `Content is neither valid JSON5 nor valid YAML.`)
+      `Content is not valid ${tried.join(" or ")}.`)
   }
 }

package/src/node/lib/FileObject.js

@@ -587,8 +587,9 @@ export default class FileObject extends FS {
   }
 
   /**
-   * Loads an object from JSON or YAML file. Attempts to parse content as JSON5
-   * first, then falls back to YAML if specified.
+   * Loads an object from a JSON, JSON5, or YAML file. With the default "any"
+   * type, attempts each format from least to most permissive (JSON, then JSON5,
+   * then YAML); a specific type restricts parsing to that format.
    *
    * @param {object} [options] - Load options
    * @param {string} [options.type="any"] - The expected type of data to parse ("json", "json5", "yaml", or "any")

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

@@ -3,17 +3,27 @@
  * node-specific dependencies.
  */
 export default class Data extends BrowserData {
+    static LOAD_DATA_TYPES: Readonly<{
+        json: readonly JSON[];
+        json5: readonly (typeof JSON5)[];
+        yaml: readonly (typeof YAML)[];
+    }>;
     /**
-     * Parses text content as structured data (JSON5 or YAML).
+     * Parses text content as structured data (JSON, JSON5, or YAML).
+     *
+     * The `json` type uses strict JSON parsing and will NOT accept JSON5
+     * extensions (comments, trailing commas, unquoted keys); use `json5` for
+     * that. The `any` type tries each format from least to most permissive.
      *
      * @param {string} source - The text content to parse
-     * @param {string} [type="any"] - The expected format ("json",
-     *   "json5", "yaml", or "any")
+     * @param {string} [type="any"] - The expected format ("json", "json5",
+     *  "yaml", or "any")
      * @returns {unknown} The parsed data
-     * @throws {Sass} If content cannot be parsed or type is
-     *   unsupported
+     * @throws {Sass} If content cannot be parsed or type is unsupported
      */
     static textAsData(source: string, type?: string): unknown;
 }
 import BrowserData from "../../browser/lib/Data.js";
+import JSON5 from "json5";
+import YAML from "yaml";
 //# sourceMappingURL=Data.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Data.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH;IACE;;;;;;;;;OASG;IACH,0BAPW,MAAM,SACN,MAAM,GAEJ,OAAO,CA+BnB;CACF;wBA9CuB,2BAA2B"}
+{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Data.js"],"names":[],"mappings":"AAMA;;;GAGG;AACH;IACE;;;;OAIE;IAEF;;;;;;;;;;;;OAYG;IACH,0BANW,MAAM,SACN,MAAM,GAEJ,OAAO,CAqCnB;CACF;wBA/DuB,2BAA2B;kBAFjC,OAAO;iBACR,MAAM"}

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

@@ -240,8 +240,9 @@ export default class FileObject extends FS {
      */
     writeBinary(data: ArrayBuffer | Blob | Buffer): Promise<undefined>;
     /**
-     * Loads an object from JSON or YAML file. Attempts to parse content as JSON5
-     * first, then falls back to YAML if specified.
+     * Loads an object from a JSON, JSON5, or YAML file. With the default "any"
+     * type, attempts each format from least to most permissive (JSON, then JSON5,
+     * then YAML); a specific type restricts parsing to that format.
      *
      * @param {object} [options] - Load options
      * @param {string} [options.type="any"] - The expected type of data to parse ("json", "json5", "yaml", or "any")

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

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AAEH;yBA8Ha,MAAM,WACN,MAAM,oBAEJ,MAAM;IA2jBnB;;;;;;;;;;;OAWG;IACH,kBAPa,UAAU,CAsCtB;IA5sBD;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;IA8BD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFa,OAAO,CAAC,MAAM,GAAC,UAAU,GAAC,QAAQ,GAAC,MAAM,GAAC,IAAI,CAAC,CAI3D;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAoED;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,kBAJW,KAAK,GACH,UAAU,CAYtB;IAED;;;;OAIG;IACH,eAFa,UAAU,CAOtB;IAED;;;;OAIG;IACH,cAFa,UAAU,CAMtB;IAED;;;;;;;OAOG;IACH,+BAJG;QAAyB,QAAQ,GAAzB,MAAM;QACY,SAAS,GAA3B,OAAO;KACf,GAAU,OAAO,CAAC,MAAM,CAAC,CAa3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,SAAS,CAAC,CAiB9B;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,SAAS,CAAC,CAwB9B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,yCAZG;QAAyB,IAAI,GAArB,MAAM;QACW,QAAQ,GAAzB,MAAM;QACY,SAAS,GAA3B,OAAO;KACf,GAAU,OAAO,CAAC,OAAO,CAAC,CAqB5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;;OAYG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CAyB/B;IAED;;;;;;;;;;;;;OAaG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CA0C/B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,SAAS,CAAC,CAc9B;IAnjBD;;;;;;;OAOG;IACH,2BAHW,QAAQ,GAAC,QAAQ,GAAC,SAAS,GACzB,MAAM,GAAC,MAAM,CAQzB;;CAmlBF;eA5vBc,iBAAiB;4BADJ,sBAAsB;kBAFhC,YAAY"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AAEH;yBA8Ha,MAAM,WACN,MAAM,oBAEJ,MAAM;IA4jBnB;;;;;;;;;;;OAWG;IACH,kBAPa,UAAU,CAsCtB;IA7sBD;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;IA8BD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFa,OAAO,CAAC,MAAM,GAAC,UAAU,GAAC,QAAQ,GAAC,MAAM,GAAC,IAAI,CAAC,CAI3D;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAoED;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,kBAJW,KAAK,GACH,UAAU,CAYtB;IAED;;;;OAIG;IACH,eAFa,UAAU,CAOtB;IAED;;;;OAIG;IACH,cAFa,UAAU,CAMtB;IAED;;;;;;;OAOG;IACH,+BAJG;QAAyB,QAAQ,GAAzB,MAAM;QACY,SAAS,GAA3B,OAAO;KACf,GAAU,OAAO,CAAC,MAAM,CAAC,CAa3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,SAAS,CAAC,CAiB9B;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,SAAS,CAAC,CAwB9B;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yCAZG;QAAyB,IAAI,GAArB,MAAM;QACW,QAAQ,GAAzB,MAAM;QACY,SAAS,GAA3B,OAAO;KACf,GAAU,OAAO,CAAC,OAAO,CAAC,CAqB5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;;OAYG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CAyB/B;IAED;;;;;;;;;;;;;OAaG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CA0C/B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,SAAS,CAAC,CAc9B;IApjBD;;;;;;;OAOG;IACH,2BAHW,QAAQ,GAAC,QAAQ,GAAC,SAAS,GACzB,MAAM,GAAC,MAAM,CAQzB;;CAolBF;eA7vBc,iBAAiB;4BADJ,sBAAsB;kBAFhC,YAAY"}

package/vendor/toolkit.esm.js

@@ -1,4 +1,4 @@
-// @gesslar/toolkit v5.7.0 - ES module bundle
+// @gesslar/toolkit v5.8.0 - ES module bundle
 /**
  * @file Tantrum.js
  *

package/vendor/toolkit.umd.js

@@ -1,4 +1,4 @@
-// @gesslar/toolkit v5.7.0 - UMD bundle
+// @gesslar/toolkit v5.8.0 - UMD bundle
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :