@gesslar/toolkit 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/Data.js

@@ -12,7 +12,7 @@ export default class Data {
  * Array of JavaScript primitive type names.
  * Includes basic types and object categories from the typeof operator.
  *
- * @type {string[]}
+ * @type {Array<string>}
  */
   static primitives = Object.freeze([
   // Primitives
@@ -32,7 +32,7 @@ export default class Data {
    * Array of JavaScript constructor names for built-in objects.
    * Includes common object types and typed arrays.
    *
-   * @type {string[]}
+   * @type {Array<string>}
    */
   static constructors = Object.freeze([
   // Object Constructors
@@ -57,7 +57,7 @@ export default class Data {
    * Combined array of all supported data types (primitives and constructors in lowercase).
    * Used for type validation throughout the utility functions.
    *
-   * @type {string[]}
+   * @type {Array<string>}
    */
   static dataTypes = Object.freeze([
     ...Data.primitives,
@@ -68,7 +68,7 @@ export default class Data {
    * Array of type names that can be checked for emptiness.
    * These types have meaningful empty states that can be tested.
    *
-   * @type {string[]}
+   * @type {Array<string>}
    */
   static emptyableTypes = Object.freeze(["string", "array", "object"])
 
@@ -204,7 +204,7 @@ export default class Data {
    * Allocates an object from a source array and a spec array or function.
    *
    * @param {unknown} source The source array
-   * @param {Array|function(unknown): unknown} spec The spec array or function
+   * @param {Array<unknown>|function(Array<unknown>): Promise<Array<unknown>>|Array<unknown>} spec The spec array or function
    * @returns {Promise<object>} The allocated object
    */
   static async allocateObject(source, spec) {
@@ -289,7 +289,7 @@ export default class Data {
    *
    * @param {string} string - The string to parse into a type spec.
    * @param {object} options - Additional options for parsing.
-   * @returns {object[]} An array of type specs.
+   * @returns {Array<object>} An array of type specs.
    */
   static newTypeSpec(string, options) {
     return new TypeSpec(string, options)

package/src/lib/File.js

@@ -178,7 +178,7 @@ export default class File {
   /**
    * Retrieve all files matching a specific glob pattern.
    *
-   * @param {string|string[]} glob - The glob pattern(s) to search.
+   * @param {string|Array<string>} glob - The glob pattern(s) to search.
    * @returns {Promise<Array<FileObject>>} A promise that resolves to an array of file objects
    * @throws {Sass} If the input is not a string or array of strings.
    * @throws {Sass} If the glob pattern array is empty or for other search failures.

package/src/lib/FileObject.js

@@ -66,13 +66,9 @@ export default class FileObject {
     if(!directory)
       directory = new DirectoryObject(dir)
 
-    let final
-
-    if(path.isAbsolute(fixedFile)) {
-      final = fixedFile
-    } else {
-      final = path.resolve(directory.path, fixedFile)
-    }
+    const final = path.isAbsolute(fixedFile)
+      ? fixedFile
+      : path.resolve(directory.path, fixedFile)
 
     const resolved = final
     const fileUri = File.pathToUri(resolved)

package/src/lib/Term.js

@@ -91,7 +91,7 @@ export default class Term {
    * Recursion: array input is normalised into a single string then re-dispatched
    * through `status` to leverage the string branch (keeps logic DRY).
    *
-   * @param {string | Array<string, string> | Array<string, string, string>} argList - Message spec.
+   * @param {string | Array<string | [string, string] | [string, string, string]>} argList - Message spec.
    * @returns {void}
    */
   static terminalMessage(argList) {
@@ -142,7 +142,7 @@ export default class Term {
    * This method does not append trailing spaces; callers are responsible for
    * joining multiple segments with appropriate separators.
    *
-   * @param {string[]} parts - Tuple: [level, text]. Additional entries ignored.
+   * @param {Array<string>} parts - Tuple: [level, text]. Additional entries ignored.
    * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
    * @throws {Sass} If any element of `parts` is not a string.
    */

package/src/lib/Type.js

@@ -90,7 +90,7 @@ export default class TypeSpec {
    * Creates a new array with all type specifications that pass the provided test function.
    *
    * @param {function(unknown): boolean} callback - Function to test each spec
-   * @returns {Array} New array with filtered specs
+   * @returns {Array<unknown>} New array with filtered specs
    */
   filter(callback) {
     return this.#specs.filter(callback)
@@ -100,7 +100,7 @@ export default class TypeSpec {
    * Creates a new array populated with the results of calling the provided function on every spec.
    *
    * @param {function(unknown): unknown} callback - Function to call on each spec
-   * @returns {Array} New array with mapped values
+   * @returns {Array<unknown>} New array with mapped values
    */
   map(callback) {
     return this.#specs.map(callback)

package/src/lib/Util.js

@@ -84,7 +84,7 @@ export default class Util {
    *     (filtered out).
    *
    * @param {object} object - Mapping of option strings to descriptions.
-   * @returns {string[]} Array of canonical option names (long preferred, short if no long present).
+   * @returns {Array<string>} Array of canonical option names (long preferred, short if no long present).
    */
   static generateOptionNames(object) {
     return Object.keys(object)
@@ -103,8 +103,8 @@ export default class Util {
    * Asynchronously awaits all promises in parallel.
    * Wrapper around Promise.all for consistency with other utility methods.
    *
-   * @param {Promise[]} promises - Array of promises to await
-   * @returns {Promise<unknown[]>} Results of all promises
+   * @param {Array<Promise<unknown>>} promises - Array of promises to await
+   * @returns {Promise<Array<unknown>>} Results of all promises
    */
   static async awaitAll(promises) {
     return await Promise.all(promises)
@@ -114,8 +114,8 @@ export default class Util {
    * Settles all promises (both fulfilled and rejected) in parallel.
    * Wrapper around Promise.allSettled for consistency with other utility methods.
    *
-   * @param {Promise[]} promises - Array of promises to settle
-   * @returns {Promise<Array>} Results of all settled promises with status and value/reason
+   * @param {Array<Promise<unknown>>} promises - Array of promises to settle
+   * @returns {Promise<Array<object>>} Results of all settled promises with status and value/reason
    */
   static async settleAll(promises) {
     return await Promise.allSettled(promises)
@@ -125,7 +125,7 @@ export default class Util {
    * Returns the first promise to resolve or reject from an array of promises.
    * Wrapper around Promise.race for consistency with other utility methods.
    *
-   * @param {Promise[]} promises - Array of promises to race
+   * @param {Array<Promise<unknown>>} promises - Array of promises to race
    * @returns {Promise<unknown>} Result of the first settled promise
    */
   static async race(promises) {

package/src/types/Cache.d.ts

@@ -1,4 +1,5 @@
-import FileObject from '../lib/FileObject.js'
+// Implementation: ../lib/Cache.js
+import FileObject from './FileObject.js'
 
 /**
  * File system cache for theme compilation data with automatic invalidation.
@@ -26,4 +27,4 @@ declare class Cache {
   loadCachedData(fileObject: FileObject): Promise<object>
 }
 
-export default Cache
+export default Cache

package/src/types/Data.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../lib/Data.js
 // Type definitions for Data utilities
 
 import Type from './Type.js'
@@ -7,16 +8,16 @@ import Type from './Type.js'
  */
 export default class Data {
   /** Array of JavaScript primitive type names */
-  static readonly primitives: readonly string[]
+  static readonly primitives: ReadonlyArray<string>
 
   /** Array of JavaScript constructor names for built-in objects */
-  static readonly constructors: readonly string[]
+  static readonly constructors: ReadonlyArray<string>
 
   /** Combined array of all supported data types */
-  static readonly dataTypes: readonly string[]
+  static readonly dataTypes: ReadonlyArray<string>
 
   /** Array of type names that can be checked for emptiness */
-  static readonly emptyableTypes: readonly string[]
+  static readonly emptyableTypes: ReadonlyArray<string>
 
   /** Append a string if it doesn't already end with it */
   static appendString(string: string, append: string): string
@@ -25,25 +26,25 @@ export default class Data {
   static prependString(string: string, prepend: string): string
 
   /** Check if all elements in an array are of a specified type */
-  static isArrayUniform(arr: unknown[], type?: string): boolean
+  static isArrayUniform(arr: Array<unknown>, type?: string): boolean
 
   /** Remove duplicates from an array */
-  static isArrayUnique<T>(arr: T[]): T[]
+  static isArrayUnique<T>(arr: Array<T>): Array<T>
 
   /** Get the intersection of two arrays */
-  static arrayIntersection<T>(arr1: T[], arr2: T[]): T[]
+  static arrayIntersection<T>(arr1: Array<T>, arr2: Array<T>): Array<T>
 
   /** Check if two arrays have any elements in common */
-  static arrayIntersects<T>(arr1: T[], arr2: T[]): boolean
+  static arrayIntersects<T>(arr1: Array<T>, arr2: Array<T>): boolean
 
   /** Pad an array to a specified length */
-  static arrayPad<T>(arr: T[], length: number, value: T, position?: number): T[]
+  static arrayPad<T>(arr: Array<T>, length: number, value: T, position?: number): Array<T>
 
   /** Clone an object */
   static cloneObject<T extends Record<string, any>>(obj: T, freeze?: boolean): T
 
   /** Allocate an object from a source array and spec */
-  static allocateObject(source: unknown[], spec: unknown[] | ((source: unknown[]) => unknown[])): Promise<Record<string, unknown>>
+  static allocateObject(source: Array<unknown>, spec: Array<unknown> | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)): Promise<Record<string, unknown>>
 
   /** Map an object using a transformer function */
   static mapObject<T extends Record<string, any>, R>(
@@ -80,17 +81,17 @@ export default class Data {
   static deepFreezeObject<T>(obj: T): T
 
   /** Ensure a nested path of objects exists */
-  static assureObjectPath(obj: Record<string, any>, keys: string[]): Record<string, any>
+  static assureObjectPath(obj: Record<string, any>, keys: Array<string>): Record<string, any>
 
   /** Set a value in a nested object structure */
-  static setNestedValue(obj: Record<string, any>, keys: string[], value: unknown): void
+  static setNestedValue(obj: Record<string, any>, keys: Array<string>, value: unknown): void
 
   /** Deeply merge objects */
-  static mergeObject<T extends Record<string, any>>(...sources: T[]): T
+  static mergeObject<T extends Record<string, any>>(...sources: Array<T>): T
 
   /** Check if all elements in an array are strings */
-  static uniformStringArray(arr: unknown[]): arr is string[]
+  static uniformStringArray(arr: Array<unknown>): arr is Array<string>
 
   /** Filter an array asynchronously */
-  static asyncFilter<T>(arr: T[], predicate: (item: T) => Promise<boolean>): Promise<T[]>
+  static asyncFilter<T>(arr: Array<T>, predicate: (item: T) => Promise<boolean>): Promise<Array<T>>
 }

package/src/types/DirectoryObject.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../lib/DirectoryObject.js
 // Type definitions for DirectoryObject
 
 /**

package/src/types/File.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../lib/File.js
 // Type definitions for File utilities
 
 import FileObject from './FileObject.js'
@@ -14,9 +15,9 @@ export interface FileParts {
 
 export interface DirectoryListing {
   /** Array of FileObject instances */
-  files: FileObject[]
+  files: Array<FileObject>
   /** Array of DirectoryObject instances */
-  directories: DirectoryObject[]
+  directories: Array<DirectoryObject>
 }
 
 /**
@@ -54,7 +55,7 @@ export default class File {
   static deconstructFilenameToParts(fileName: string): FileParts
 
   /** Retrieve files matching glob pattern(s) */
-  static getFiles(glob: string | string[]): Promise<FileObject[]>
+  static getFiles(glob: string | Array<string>): Promise<Array<FileObject>>
 
   /** List the contents of a directory */
   static ls(directory: string): Promise<DirectoryListing>

package/src/types/FileObject.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../lib/FileObject.js
 // Type definitions for FileObject
 
 import DirectoryObject from './DirectoryObject.js'

package/src/types/Sass.d.ts

@@ -1,13 +1,14 @@
+// Implementation: ../lib/Sass.js
 // Type definitions for Sass error class
 
 /**
  * Custom error class for toolkit errors.
  */
 export default class Sass extends Error {
-  constructor(message: string, ...arg: any[])
+  constructor(message: string, ...arg: Array<any>)
 
   /** Array of trace messages */
-  readonly trace: string[]
+  readonly trace: Array<string>
 
   /** Add a trace message and return this instance for chaining */
   addTrace(message: string): this

package/src/types/Term.d.ts

@@ -1,11 +1,12 @@
+// Implementation: ../lib/Term.js
 // Type definitions for Term utility class
 
 export default class Term {
-  static log(...arg: unknown[]): void
-  static info(...arg: unknown[]): void
-  static warn(...arg: unknown[]): void
-  static error(...arg: unknown[]): void
-  static debug(...arg: unknown[]): void
+  static log(...arg: Array<unknown>): void
+  static info(...arg: Array<unknown>): void
+  static warn(...arg: Array<unknown>): void
+  static error(...arg: Array<unknown>): void
+  static debug(...arg: Array<unknown>): void
   static status(args: string | Array<string | [string, string]>, options?: { silent?: boolean }): void
   static terminalMessage(argList: string | Array<string | [string, string] | [string, string, string]>): string
   static terminalBracket(parts: [string, string, [string, string]?]): string

package/src/types/Type.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../lib/Type.js
 // Type definitions for Type specification class
 
 interface TypeSpecDefinition {
@@ -8,17 +9,17 @@ interface TypeSpecDefinition {
 export default class TypeSpec {
   constructor(string: string, options?: { delimiter?: string })
 
-  readonly specs: readonly TypeSpecDefinition[]
+  readonly specs: ReadonlyArray<TypeSpecDefinition>
   readonly length: number
   readonly stringRepresentation: string
 
   toString(): string
-  toJSON(): { specs: TypeSpecDefinition[], length: number, stringRepresentation: string }
+  toJSON(): { specs: Array<TypeSpecDefinition>, length: number, stringRepresentation: string }
   forEach(callback: (spec: TypeSpecDefinition) => void): void
   every(callback: (spec: TypeSpecDefinition) => boolean): boolean
   some(callback: (spec: TypeSpecDefinition) => boolean): boolean
-  filter(callback: (spec: TypeSpecDefinition) => boolean): TypeSpecDefinition[]
-  map<T>(callback: (spec: TypeSpecDefinition) => T): T[]
+  filter(callback: (spec: TypeSpecDefinition) => boolean): Array<TypeSpecDefinition>
+  map<T>(callback: (spec: TypeSpecDefinition) => T): Array<T>
   reduce<T>(callback: (acc: T, spec: TypeSpecDefinition) => T, initialValue: T): T
   find(callback: (spec: TypeSpecDefinition) => boolean): TypeSpecDefinition | undefined
   match(value: unknown, options?: { allowEmpty?: boolean }): boolean

package/src/types/Util.d.ts

@@ -1,3 +1,5 @@
+// Implementation: ../lib/Util.js
+
 /**
  * Utility class providing common helper functions for string manipulation,
  * timing, hashing, and option parsing.
@@ -51,7 +53,7 @@ declare class Util {
    * @param object - Mapping of option strings to descriptions.
    * @returns Array of canonical option names (long preferred, short if no long present).
    */
-  static generateOptionNames(object: Record<string, any>): string[]
+  static generateOptionNames(object: Record<string, any>): Array<string>
 
   /**
    * Asynchronously awaits all promises in parallel.
@@ -60,7 +62,7 @@ declare class Util {
    * @param promises - Array of promises to await
    * @returns Results of all promises
    */
-  static awaitAll<T>(promises: Promise<T>[]): Promise<T[]>
+  static awaitAll<T>(promises: Array<Promise<T>>): Promise<Array<T>>
 
   /**
    * Settles all promises (both fulfilled and rejected) in parallel.
@@ -69,7 +71,7 @@ declare class Util {
    * @param promises - Array of promises to settle
    * @returns Results of all settled promises with status and value/reason
    */
-  static settleAll<T>(promises: Promise<T>[]): Promise<PromiseSettledResult<T>[]>
+  static settleAll<T>(promises: Array<Promise<T>>): Promise<Array<PromiseSettledResult<T>>>
 
   /**
    * Returns the first promise to resolve or reject from an array of promises.
@@ -78,7 +80,7 @@ declare class Util {
    * @param promises - Array of promises to race
    * @returns Result of the first settled promise
    */
-  static race<T>(promises: Promise<T>[]): Promise<T>
+  static race<T>(promises: Array<Promise<T>>): Promise<T>
 }
 
 export default Util

package/src/types/Valid.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../lib/Valid.js
 // Type definitions for Valid utility class
 
 export default class Valid {

package/src/types/index.d.ts

@@ -1,3 +1,4 @@
+// Implementation: ../index.js
 // Core file system abstractions
 export { default as FileObject } from './FileObject.js'
 export { default as DirectoryObject } from './DirectoryObject.js'