@gesslar/toolkit 0.7.1 → 1.0.0

package/src/browser/lib/Valid.js

@@ -0,0 +1,76 @@
+/**
+ * @file Valid.js
+ *
+ * Provides validation utilities for type checking and assertion.
+ * Includes prototype pollution protection for secure object manipulation.
+ */
+
+import Sass from "./Sass.js"
+import Data from "./Data.js"
+import Collection from "./Collection.js"
+
+/**
+ * Validation utility class providing type checking and assertion methods.
+ */
+export default class Valid {
+  /**
+   * 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.
+   */
+  static type(value, type, options) {
+    Valid.assert(
+      Data.isType(value, type, options),
+      `Invalid type. Expected ${type}, got ${JSON.stringify(value)}`,
+      1,
+    )
+  }
+
+  /**
+   * 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}` : ""}`)
+  }
+
+  static #restrictedProto = ["__proto__", "constructor", "prototype"]
+
+  /**
+   * 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)}`
+    )
+  }
+}

package/src/index.js

@@ -1,19 +1,21 @@
-// Core file system abstractions
-export {default as FileObject} from "./lib/FileObject.js"
-export {default as DirectoryObject} from "./lib/DirectoryObject.js"
-export {default as FS} from "./lib/FS.js"
+// Browser-compatible utilities (pure JS)
+export {default as Collection} from "./browser/lib/Collection.js"
+export {default as Data} from "./browser/lib/Data.js"
+export {default as Type} from "./browser/lib/TypeSpec.js"
+export {default as Valid} from "./lib/Valid.js"
+
+// Node-enhanced versions (use Term for better formatting, crypto, etc.)
+export {default as Sass} from "./lib/Sass.js"
+export {default as Tantrum} from "./lib/Tantrum.js"
+export {default as Util} from "./lib/Util.js"
 
-// Utility classes
+// Node-specific exports
 export {default as Cache} from "./lib/Cache.js"
-export {default as Collection} from "./lib/Collection.js"
 export {default as Contract} from "./lib/Contract.js"
-export {default as Data} from "./lib/Data.js"
+export {default as DirectoryObject} from "./lib/DirectoryObject.js"
+export {default as FileObject} from "./lib/FileObject.js"
+export {default as FS} from "./lib/FS.js"
 export {default as Glog} from "./lib/Glog.js"
-export {default as Sass} from "./lib/Sass.js"
 export {default as Schemer} from "./lib/Schemer.js"
-export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Term} from "./lib/Term.js"
 export {default as Terms} from "./lib/Terms.js"
-export {default as Type} from "./lib/TypeSpec.js"
-export {default as Util} from "./lib/Util.js"
-export {default as Valid} from "./lib/Valid.js"

package/src/lib/Cache.js

@@ -1,4 +1,3 @@
-import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
 
 /**
@@ -22,7 +21,7 @@ export default class Cache {
    * maintained.
    *
    * @private
-   * @param {FileObject} file - The file object to remove from cache
+   * @param {import("./FileObject.js").FileObject} file - The file object to remove from cache
    * @returns {void}
    */
   #cleanup(file) {
@@ -39,7 +38,7 @@ export default class Cache {
    * freshness while optimizing performance for repeated file access during
    * parallel processing.
    *
-   * @param {FileObject} fileObject - The file object to load and cache
+   * @param {import("./FileObject.js").FileObject} fileObject - The file object to load and cache
    * @returns {Promise<unknown>} The parsed file data (JSON5 or YAML)
    * @throws {Sass} If the file cannot be found or accessed
    */

package/src/lib/Contract.js

@@ -1,7 +1,6 @@
 import Sass from "./Sass.js"
 import Schemer from "./Schemer.js"
-import Terms from "./Terms.js"
-import Data from "./Data.js"
+import Data from "../browser/lib/Data.js"
 
 /**
  * Contract represents a successful negotiation between Terms.
@@ -18,8 +17,8 @@ export default class Contract {
   /**
    * Creates a contract by negotiating between provider and consumer terms
    *
-   * @param {Terms} providerTerms - What the provider offers
-   * @param {Terms} consumerTerms - What the consumer expects
+   * @param {import("./Terms.js").Terms} providerTerms - What the provider offers
+   * @param {import("./Terms.js").Terms} consumerTerms - What the consumer expects
    * @param {object} options - Configuration options
    * @param {import('../types.js').DebugFunction} [options.debug] - Debug function
    */

package/src/lib/FS.js

@@ -9,12 +9,13 @@ import {globby} from "globby"
 import path from "node:path"
 import url from "node:url"
 
-import Collection from "./Collection.js"
-import DirectoryObject from "./DirectoryObject.js"
-import FileObject from "./FileObject.js"
+import Collection from "../browser/lib/Collection.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
 
+/** @typedef {import("./FileObject.js").default} FileObject */
+/** @typedef {import("./DirectoryObject.js").default} DirectoryObject */
+
 const fdTypes = Object.freeze(["file", "directory"])
 const upperFdTypes = Object.freeze(fdTypes.map(type => type.toUpperCase()))
 const fdType = Object.freeze(
@@ -78,37 +79,31 @@ export default class FS {
    * @throws {Sass} If the glob pattern array is empty or for other search failures.
    */
   static async getFiles(glob) {
+    const isString = typeof glob === "string"
+    const isArray = Array.isArray(glob)
+    const isStringArray = isArray && glob.every(item => typeof item === "string")
+
     Valid.assert(
-      (
-        (typeof glob === "string" && glob.length > 0) ||
-        (
-          Collection.isArrayUniform(glob, "string") &&
-          glob.length > 0
-        )
-      ),
+      (isString && glob.length > 0) ||
+      (isStringArray && glob.length > 0),
       "glob must be a non-empty string or array of strings.",
       1
     )
 
     const globbyArray = (
-      typeof glob === "string"
-        ? glob
-          .split("|")
-          .map(g => g.trim())
-          .filter(Boolean)
+      isString
+        ? glob.split("|").map(g => g.trim()).filter(Boolean)
         : glob
     ).map(g => FS.fixSlashes(g))
 
-    if(
-      Array.isArray(globbyArray) &&
-      Collection.isArrayUniform(globbyArray, "string") &&
-      !globbyArray.length
-    )
+    if(isArray && !globbyArray.length)
       throw Sass.new(
         `Invalid glob pattern: Array cannot be empty. Got ${JSON.stringify(glob)}`,
       )
 
     // Use Globby to fetch matching files
+    const {default: FileObject} = await import("./FileObject.js")
+
     const filesArray = await globby(globbyArray)
     const files = filesArray.map(file => new FileObject(file))
 

package/src/lib/FileObject.js

@@ -11,7 +11,7 @@ import util from "node:util"
 import YAML from "yaml"
 import {URL} from "node:url"
 
-import Data from "./Data.js"
+import Data from "../browser/lib/Data.js"
 import DirectoryObject from "./DirectoryObject.js"
 import FS from "./FS.js"
 import Sass from "./Sass.js"
@@ -355,15 +355,39 @@ export default class FileObject extends FS {
    * @returns {Promise<string>} The file contents
    */
   async read(encoding="utf8") {
-    const filePath = this.path
+    const url = this.url
+
+    if(!url)
+      throw Sass.new("No URL in file map")
+
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${url.href}'`)
+
+    return await fs.readFile(url, encoding)
+  }
+
+  /**
+   * Reads binary data from a file asynchronously.
+   * Returns the file contents as a Buffer (Node.js binary data type).
+   *
+   * @returns {Promise<Buffer>} The file contents as a Buffer
+   * @throws {Sass} If the file URL is invalid
+   * @throws {Sass} If the file does not exist
+   * @example
+   * const file = new FileObject('./image.png')
+   * const buffer = await file.readBinary()
+   * // Use the buffer (e.g., send in HTTP response, process image, etc.)
+   */
+  async readBinary() {
+    const url = this.url
 
-    if(!filePath)
-      throw Sass.new("No absolute path in file map")
+    if(!url)
+      throw Sass.new("No URL in file map")
 
     if(!(await this.exists))
-      throw Sass.new(`No such file '${filePath}'`)
+      throw Sass.new(`No such file '${url.href}'`)
 
-    return await fs.readFile(filePath, encoding)
+    return await fs.readFile(url)
   }
 
   /**
@@ -373,22 +397,55 @@ export default class FileObject extends FS {
    * @param {string} content - The content to write
    * @param {string} [encoding] - The encoding in which to write (default: "utf8")
    * @returns {Promise<void>}
-   * @throws {Sass} If the file path is invalid or the parent directory doesn't exist
+   * @throws {Sass} If the file URL is invalid or the parent directory doesn't exist
    * @example
    * const file = new FileObject('./output/data.json')
    * await file.write(JSON.stringify({key: 'value'}))
    */
   async write(content, encoding="utf8") {
-    if(!this.path)
-      throw Sass.new("No absolute path in file")
+    if(!this.url)
+      throw Sass.new("No URL in file")
 
     if(await this.directory.exists)
-      await fs.writeFile(this.path, content, encoding)
+      await fs.writeFile(this.url, content, encoding)
 
     else
       throw Sass.new(`Invalid directory, ${this.directory.url.href}`)
   }
 
+  /**
+   * Writes binary data to a file asynchronously.
+   * Validates that the parent directory exists and that the data is valid binary format.
+   * Supports ArrayBuffer, TypedArrays (Uint8Array, etc.), Blob, and Node Buffer types.
+   *
+   * @param {ArrayBuffer|Blob|Buffer} data - The binary data to write
+   * @returns {Promise<void>}
+   * @throws {Sass} If the file URL is invalid
+   * @throws {Sass} If the parent directory doesn't exist
+   * @throws {Sass} If the data is not a valid binary type
+   * @example
+   * const file = new FileObject('./output/image.png')
+   * const response = await fetch('https://example.com/image.png')
+   * const buffer = await response.arrayBuffer()
+   * await file.writeBinary(buffer)
+   */
+  async writeBinary(data) {
+    if(!this.url)
+      throw Sass.new("No URL in file")
+
+    const exists = await this.directory.exists
+    Valid.assert(exists, `Invalid directory, ${this.directory.url.href}`)
+
+    Valid.assert(Data.isBinary(data), "Data must be binary (ArrayBuffer, TypedArray, Blob, or Buffer)")
+
+    // Convert ArrayBuffer to Buffer if needed (fs.writeFile doesn't accept ArrayBuffer directly)
+    const bufferData = data instanceof ArrayBuffer ? Buffer.from(data) : data
+
+    // According to the internet, if it's already binary, I don't need
+    // an encoding. 🤷
+    return await fs.writeFile(this.url, bufferData)
+  }
+
   /**
    * Loads an object from JSON or YAML file.
    * Attempts to parse content as JSON5 first, then falls back to YAML if specified.
@@ -459,14 +516,14 @@ export default class FileObject extends FS {
    * await file.delete()
    */
   async delete() {
-    const filePath = this.path
+    const url = this.url
 
-    if(!filePath)
+    if(!url)
       throw Sass.new("This object does not represent a valid resource.")
 
     if(!(await this.exists))
-      throw Sass.new(`No such resource '${this.url.href}'`)
+      throw Sass.new(`No such resource '${url.href}'`)
 
-    return await fs.unlink(this.path)
+    return await fs.unlink(url)
   }
 }

package/src/lib/Glog.js

@@ -13,9 +13,9 @@
 
 import c from "@gesslar/colours"
 
-import Data from "./Data.js"
+import Data from "../browser/lib/Data.js"
 import Term from "./Term.js"
-import Util from "./Util.js"
+import Util from "../browser/lib/Util.js"
 // ErrorStackParser will be dynamically imported when needed
 
 // Enhanced color system using @gesslar/colours

package/src/lib/Sass.js

@@ -11,61 +11,14 @@
  * debugging.
  */
 
+import {Sass as BrowserSass} from "../browser/index.js"
 import Term from "./Term.js"
-import Tantrum from "./Tantrum.js"
 
 /**
  * Custom error class for toolkit errors.
  * Provides error chaining, trace management, and formatted error reporting.
  */
-export default class Sass extends Error {
-  #trace = []
-
-  /**
-   * Creates a new Sass instance.
-   *
-   * @param {string} message - The error message
-   * @param {...unknown} [arg] - Additional arguments passed to parent Error constructor
-   */
-  constructor(message, ...arg) {
-    super(message, ...arg)
-
-    this.trace = message
-  }
-
-  /**
-   * Gets the error trace array.
-   *
-   * @returns {Array<string>} Array of trace messages
-   */
-  get trace() {
-    return this.#trace
-  }
-
-  /**
-   * Adds a message to the beginning of the trace array.
-   *
-   * @param {string} message - The trace message to add
-   */
-  set trace(message) {
-    this.#trace.unshift(message)
-  }
-
-  /**
-   * Adds a trace message and returns this instance for chaining.
-   *
-   * @param {string} message - The trace message to add
-   * @returns {this} This Sass instance for method chaining
-   */
-  addTrace(message) {
-    if(typeof message !== "string")
-      throw Sass.new(`Sass.addTrace expected string, got ${JSON.stringify(message)}`)
-
-    this.trace = message
-
-    return this
-  }
-
+export default class Sass extends BrowserSass {
   /**
    * Reports the error to the terminal with formatted output.
    * Optionally includes detailed stack trace information.
@@ -124,46 +77,4 @@ export default class Sass extends Error {
 
     return lines.join("\n")
   }
-
-  /**
-   * Creates an Sass from an existing Error object with additional
-   * trace message.
-   *
-   * @param {Error} error - The original error object
-   * @param {string} message - Additional trace message to add
-   * @returns {Sass} New Sass instance with trace from the original error
-   * @throws {Sass} If the first parameter is not an Error instance
-   */
-  static from(error, message) {
-    if(!(error instanceof Error))
-      throw Sass.new("Sass.from must take an Error object.")
-
-    const oldMessage = error.message
-    const newError = new Sass(oldMessage, {cause: error}).addTrace(message)
-
-    return newError
-  }
-
-  /**
-   * Factory method to create or enhance Sass instances.
-   * If error parameter is provided, enhances existing Sass or wraps
-   * other errors. Otherwise creates a new Sass instance.
-   *
-   * @param {string} message - The error message
-   * @param {Error|Sass|Tantrum} [error] - Optional existing error to wrap or enhance
-   * @returns {Sass} New or enhanced Sass instance
-   */
-  static new(message, error) {
-    if(error) {
-      if(error instanceof Tantrum)
-        return Tantrum.new(message, error)
-
-      return error instanceof Sass
-        ? error.addTrace(message)
-        : Sass.from(error, message)
-    } else {
-
-      return new Sass(message)
-    }
-  }
 }

package/src/lib/Schemer.js

@@ -1,7 +1,7 @@
 import Ajv from "ajv"
 
-import Data from "./Data.js"
-import Util from "./Util.js"
+import Data from "../browser/lib/Data.js"
+import Util from "../browser/lib/Util.js"
 import Valid from "./Valid.js"
 
 /**

package/src/lib/Tantrum.js

@@ -9,6 +9,7 @@
  * multiple error scenarios.
  */
 
+import {Tantrum as BrowserTantrum} from "../browser/index.js"
 import Sass from "./Sass.js"
 import Term from "./Term.js"
 
@@ -16,63 +17,9 @@ import Term from "./Term.js"
  * Custom aggregate error class that extends AggregateError.
  * Automatically wraps plain errors in Sass instances for consistent reporting.
  */
-export default class Tantrum extends AggregateError {
-  #trace = []
-
-  /**
-   * Creates a new Tantrum instance.
-   *
-   * @param {string} message - The aggregate error message
-   * @param {Array<Error|Sass>} errors - Array of errors to aggregate
-   */
+export default class Tantrum extends BrowserTantrum {
   constructor(message, errors = []) {
-    // Auto-wrap plain errors in Sass, keep existing Sass instances
-    const wrappedErrors = errors.map(error => {
-      if(error instanceof Sass)
-        return error
-
-      if(!(error instanceof Error))
-        throw new TypeError(`All items in errors array must be Error instances, got: ${typeof error}`)
-
-      return Sass.new(error.message, error)
-    })
-
-    super(wrappedErrors, message)
-    this.name = "Tantrum"
-  }
-
-  /**
-   * Adds a trace message and returns this instance for chaining.
-   *
-   * @param {string} message - The trace message to add
-   * @param {Error|Sass} [_error] - Optional error (currently unused, reserved for future use)
-   * @returns {this} This Tantrum instance for method chaining
-   */
-  addTrace(message, _error) {
-    if(typeof message !== "string")
-      throw Sass.new(`Tantrum.addTrace expected string, got ${JSON.stringify(message)}`)
-
-    this.trace = message
-
-    return this
-  }
-
-  /**
-   * Gets the error trace array.
-   *
-   * @returns {Array<string>} Array of trace messages
-   */
-  get trace() {
-    return this.#trace
-  }
-
-  /**
-   * Adds a message to the beginning of the trace array.
-   *
-   * @param {string} message - The trace message to add
-   */
-  set trace(message) {
-    this.#trace.unshift(message)
+    super(message, errors, Sass)
   }
 
   /**
@@ -95,18 +42,4 @@ export default class Tantrum extends AggregateError {
       error.report(nerdMode)
     })
   }
-
-  /**
-   * Factory method to create a Tantrum instance.
-   *
-   * @param {string} message - The aggregate error message
-   * @param {Array<Error|Sass>} errors - Array of errors to aggregate
-   * @returns {Tantrum} New Tantrum instance
-   */
-  static new(message, errors = []) {
-    if(errors instanceof Tantrum)
-      return errors.addTrace(message)
-
-    return new Tantrum(message, errors)
-  }
 }

package/src/lib/Terms.js

@@ -1,8 +1,7 @@
 import JSON5 from "json5"
 import yaml from "yaml"
 
-import Data from "./Data.js"
-import DirectoryObject from "./DirectoryObject.js"
+import Data from "../browser/lib/Data.js"
 import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
@@ -24,7 +23,7 @@ export default class Terms {
    * Parses terms data, handling file references
    *
    * @param {string|object} termsData - Terms data or reference
-   * @param {DirectoryObject?} directoryObject - Directory context for file resolution
+   * @param {import("./DirectoryObject.js").DirectoryObject?} directoryObject - Directory context for file resolution
    * @returns {object} Parsed terms data
    */
   static async parse(termsData, directoryObject) {