@gesslar/toolkit 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -17,7 +17,7 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "scripts": {
     "types:build": "tsc -p tsconfig.types.json",
@@ -58,10 +58,10 @@
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.5.0",
-    "@types/node": "^24.9.1",
-    "@typescript-eslint/eslint-plugin": "^8.46.2",
-    "@typescript-eslint/parser": "^8.46.2",
-    "eslint": "^9.38.0",
-    "eslint-plugin-jsdoc": "^61.1.8"
+    "@types/node": "^24.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.1",
+    "eslint-plugin-jsdoc": "^61.1.12"
   }
 }

package/src/lib/Data.js

@@ -410,4 +410,28 @@ export default class Data {
 
     return proto === current
   }
+
+  /**
+   * Checks if a value is binary data.
+   * Returns true for ArrayBuffer, TypedArrays (Uint8Array, Int16Array, etc.),
+   * Blob, and Node Buffer instances.
+   *
+   * @param {unknown} value - The value to check
+   * @returns {boolean} True if the value is binary data, false otherwise
+   * @example
+   * Data.isBinary(new Uint8Array([1, 2, 3])) // true
+   * Data.isBinary(new ArrayBuffer(10)) // true
+   * Data.isBinary(Buffer.from('hello')) // true
+   * Data.isBinary(new Blob(['text'])) // true
+   * Data.isBinary('string') // false
+   * Data.isBinary({}) // false
+   * Data.isBinary(undefined) // false
+   */
+  static isBinary(value) {
+    return (value !== undefined) &&
+           (
+             ArrayBuffer.isView(value) ||
+             Data.isType(value, "ArrayBuffer|Blob|Buffer")
+           )
+  }
 }

package/src/lib/FileObject.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/types/lib/Data.d.ts

@@ -184,6 +184,23 @@ export default class Data {
      * isPlainObject(class Person{}) // false
      */
     static isPlainObject(value: unknown): boolean;
+    /**
+     * Checks if a value is binary data.
+     * Returns true for ArrayBuffer, TypedArrays (Uint8Array, Int16Array, etc.),
+     * Blob, and Node Buffer instances.
+     *
+     * @param {unknown} value - The value to check
+     * @returns {boolean} True if the value is binary data, false otherwise
+     * @example
+     * Data.isBinary(new Uint8Array([1, 2, 3])) // true
+     * Data.isBinary(new ArrayBuffer(10)) // true
+     * Data.isBinary(Buffer.from('hello')) // true
+     * Data.isBinary(new Blob(['text'])) // true
+     * Data.isBinary('string') // false
+     * Data.isBinary({}) // false
+     * Data.isBinary(undefined) // false
+     */
+    static isBinary(value: unknown): boolean;
 }
 import TypeSpec from "./TypeSpec.js";
 //# sourceMappingURL=Data.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE6C;IAEpE;;;;;;OAMG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ,YACf,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA2BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;CACF;qBApZoB,eAAe"}
+{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE6C;IAEpE;;;;;;OAMG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ,YACf,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA2BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAXW,OAAO,GACL,OAAO,CAgBnB;CACF;qBA5aoB,eAAe"}

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

@@ -138,6 +138,19 @@ export default class FileObject extends FS {
      * @returns {Promise<string>} The file contents
      */
     read(encoding?: string): Promise<string>;
+    /**
+     * 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.)
+     */
+    readBinary(): Promise<Buffer>;
     /**
      * Writes content to a file asynchronously.
      * Validates that the parent directory exists before writing.
@@ -145,12 +158,29 @@ 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'}))
      */
     write(content: string, encoding?: string): Promise<void>;
+    /**
+     * 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)
+     */
+    writeBinary(data: ArrayBuffer | Blob | Buffer): Promise<void>;
     /**
      * Loads an object from JSON or YAML file.
      * Attempts to parse content as JSON5 first, then falls back to YAML if specified.

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

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,cACN,eAAe,GAAC,MAAM,GAAC,IAAI,EAsCrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;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;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;IApUD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA8TF;eAxcc,SAAS;oBAJN,UAAU;4BAGA,sBAAsB;iBALjC,WAAW;kBAHV,OAAO;iBAIR,MAAM"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,cACN,eAAe,GAAC,MAAM,GAAC,IAAI,EAsCrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;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;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;IA7XD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CAuXF;eAjgBc,SAAS;oBAJN,UAAU;4BAGA,sBAAsB;iBALjC,WAAW;kBAHV,OAAO;iBAIR,MAAM"}

package/src/types/lib/Util.d.ts

@@ -171,7 +171,7 @@ export default class Util {
      * @param {object} emitter - Any object with EventEmitter-like interface
      * @param {string} event - The event name to emit
      * @param {...unknown} args - Arguments to pass to event listeners
-     * @returns {Promise<void>} Resolves when all listeners have completed
+     * @returns {Promise<void>} Resolves when all listeners have completed, but no grapes.
      */
     static asyncEmitQuack(emitter: object, event: string, ...args: unknown[]): Promise<void>;
     /**