@gesslar/toolkit 0.0.1

package/src/lib/Type.js

@@ -0,0 +1,207 @@
+/**
+ * @file Type specification and validation utilities.
+ * Provides TypeSpec class for parsing and validating complex type specifications
+ * including arrays, unions, and options.
+ */
+
+import Sass from "./Sass.js"
+import Data from "./Data.js"
+
+/**
+ * Type specification class for parsing and validating complex type definitions.
+ * Supports union types, array types, and validation options.
+ */
+export default class TypeSpec {
+  #specs
+
+  /**
+   * Creates a new TypeSpec instance.
+   *
+   * @param {string} string - The type specification string (e.g., "string|number", "object[]")
+   * @param {object} options - Additional parsing options
+   */
+  constructor(string, options) {
+    this.#specs = []
+    this.#parse(string, options)
+    Object.freeze(this.#specs)
+    this.specs = this.#specs
+    this.length = this.#specs.length
+    this.stringRepresentation = this.toString()
+    Object.freeze(this)
+  }
+
+  /**
+   * Returns a string representation of the type specification.
+   *
+   * @returns {string} The type specification as a string (e.g., "string|number[]")
+   */
+  toString() {
+    return this.#specs
+      .map(spec => {
+        return `${spec.typeName}${spec.array ? "[]" : ""}`
+      })
+      .join("|")
+  }
+
+  /**
+   * Returns a JSON representation of the TypeSpec.
+   *
+   * @returns {object} Object containing specs, length, and string representation
+   */
+  toJSON() {
+    // Serialize as a string representation or as raw data
+    return {
+      specs: this.#specs,
+      length: this.length,
+      stringRepresentation: this.toString(),
+    }
+  }
+
+  /**
+   * Executes a provided function once for each type specification.
+   *
+   * @param {function(unknown): void} callback - Function to execute for each spec
+   */
+  forEach(callback) {
+    this.#specs.forEach(callback)
+  }
+
+  /**
+   * Tests whether all type specifications pass the provided test function.
+   *
+   * @param {function(unknown): boolean} callback - Function to test each spec
+   * @returns {boolean} True if all specs pass the test
+   */
+  every(callback) {
+    return this.#specs.every(callback)
+  }
+
+  /**
+   * Tests whether at least one type specification passes the provided test function.
+   *
+   * @param {function(unknown): boolean} callback - Function to test each spec
+   * @returns {boolean} True if at least one spec passes the test
+   */
+  some(callback) {
+    return this.#specs.some(callback)
+  }
+
+  /**
+   * 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
+   */
+  filter(callback) {
+    return this.#specs.filter(callback)
+  }
+
+  /**
+   * 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
+   */
+  map(callback) {
+    return this.#specs.map(callback)
+  }
+
+  /**
+   * Executes a reducer function on each spec, resulting in a single output value.
+   *
+   * @param {function(unknown, unknown): unknown} callback - Function to execute on each spec
+   * @param {unknown} initialValue - Initial value for the accumulator
+   * @returns {unknown} The final accumulated value
+   */
+  reduce(callback, initialValue) {
+    return this.#specs.reduce(callback, initialValue)
+  }
+
+  /**
+   * Returns the first type specification that satisfies the provided testing function.
+   *
+   * @param {function(unknown): boolean} callback - Function to test each spec
+   * @returns {object|undefined} The first spec that matches, or undefined
+   */
+  find(callback) {
+    return this.#specs.find(callback)
+  }
+
+  /**
+   * Tests whether a value matches any of the type specifications.
+   * Handles array types, union types, and empty value validation.
+   *
+   * @param {unknown} value - The value to test against the type specifications
+   * @param {object} options - Validation options
+   * @param {boolean} options.allowEmpty - Whether empty values are allowed
+   * @returns {boolean} True if the value matches any type specification
+   */
+  match(value, options) {
+    const allowEmpty = options?.allowEmpty ?? true
+    const empty = Data.isEmpty(value)
+
+    // If we have a list of types, because the string was validly parsed,
+    // we need to ensure that all of the types that were parsed are valid types
+    // in JavaScript.
+    if(this.length && !this.every(t => Data.isValidType(t.typeName)))
+      return false
+
+    // Now, let's do some checking with the types, respecting the array flag
+    // with the value
+    const valueType = Data.typeOf(value)
+    const isArray = valueType === "array"
+
+    // We need to ensure that we match the type and the consistency of the types
+    // in an array, if it is an array and an array is allowed.
+    const matchingTypeSpec = this.filter(spec => {
+      const {typeName: allowedType, array: allowedArray} = spec
+
+      if(valueType === allowedType && !isArray && !allowedArray)
+        return !allowEmpty ? !empty : true
+
+      if(isArray) {
+        if(allowedType === "array")
+          if(!allowedArray)
+            return true
+
+        if(empty)
+          if(allowEmpty)
+            return true
+
+        return Data.isArrayUniform(value, allowedType)
+      }
+    })
+
+    return matchingTypeSpec.length > 0
+  }
+
+  /**
+   * Parses a type specification string into individual type specs.
+   * Handles union types separated by delimiters and array notation.
+   *
+   * @private
+   * @param {string} string - The type specification string to parse
+   * @param {object} options - Parsing options
+   * @param {string} options.delimiter - The delimiter for union types
+   * @throws {TypeError} If the type specification is invalid
+   */
+  #parse(string, options) {
+    const delimiter = options?.delimiter ?? "|"
+    const parts = string.split(delimiter)
+
+    this.#specs = parts.map(part => {
+      const typeMatches = /(\w+)(\[\])?/.exec(part)
+
+      if(!typeMatches || typeMatches.length !== 3)
+        throw Sass.new(`Invalid type: ${part}`)
+
+      if(!Data.isValidType(typeMatches[1]))
+        throw Sass.new(`Invalid type: ${typeMatches[1]}`)
+
+      return {
+        typeName: typeMatches[1],
+        array: typeMatches[2] === "[]",
+      }
+    })
+  }
+}

package/src/lib/Valid.js

@@ -0,0 +1,50 @@
+import _assert from "node:assert/strict"
+
+import Sass from "./Sass.js"
+import Data from "./Data.js"
+
+export default class Valid {
+/**
+ * Validates a value against a type
+ *
+ * @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 validType(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) {
+    _assert(
+      Data.isType(condition, "boolean"),
+      `Condition must be a boolean, got ${condition}`,
+    )
+    _assert(
+      Data.isType(message, "string"),
+      `Message must be a string, got ${message}`,
+    )
+    _assert(
+      arg === null || arg === undefined || typeof arg === "number",
+      `Arg must be a number, got ${arg}`,
+    )
+
+    if(!condition)
+      throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
+  }
+
+}

package/src/types/Data.d.ts

@@ -0,0 +1,96 @@
+// Type definitions for Data utilities
+
+import Type from './Type.js'
+
+/**
+ * Data utility functions for type checking, object manipulation, and array operations.
+ */
+export default class Data {
+  /** Array of JavaScript primitive type names */
+  static readonly primitives: readonly string[]
+
+  /** Array of JavaScript constructor names for built-in objects */
+  static readonly constructors: readonly string[]
+
+  /** Combined array of all supported data types */
+  static readonly dataTypes: readonly string[]
+
+  /** Array of type names that can be checked for emptiness */
+  static readonly emptyableTypes: readonly string[]
+
+  /** Append a string if it doesn't already end with it */
+  static appendString(string: string, append: string): string
+
+  /** Prepend a string if it doesn't already start with it */
+  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
+
+  /** Remove duplicates from an array */
+  static isArrayUnique<T>(arr: T[]): T[]
+
+  /** Get the intersection of two arrays */
+  static arrayIntersection<T>(arr1: T[], arr2: T[]): T[]
+
+  /** Check if two arrays have any elements in common */
+  static arrayIntersects<T>(arr1: T[], arr2: T[]): boolean
+
+  /** Pad an array to a specified length */
+  static arrayPad<T>(arr: T[], length: number, value: T, position?: number): 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>>
+
+  /** Map an object using a transformer function */
+  static mapObject<T extends Record<string, any>, R>(
+    original: T,
+    transformer: (key: string, value: any) => R | Promise<R>,
+    mutate?: boolean
+  ): Promise<Record<string, R>>
+
+  /** Check if an object is empty */
+  static isObjectEmpty(obj: Record<string, any>): boolean
+
+  /** Create a type spec from a string */
+  static newTypeSpec(string: string, options?: any): Type
+
+  /** Check if a value is of a specified type */
+  static isType(value: unknown, type: string | Type, options?: { allowEmpty?: boolean }): boolean
+
+  /** Check if a type is valid */
+  static isValidType(type: string): boolean
+
+  /** Check if a value is of a base type (primitive or constructor) */
+  static isBaseType(value: unknown, type: string): boolean
+
+  /** Get the type of a value */
+  static typeOf(value: unknown): string
+
+  /** Check if a value is undefined or null */
+  static isNothing(value: unknown): value is null | undefined
+
+  /** Check if a value is empty */
+  static isEmpty(value: unknown, checkForNothing?: boolean): boolean
+
+  /** Recursively freeze an object */
+  static deepFreezeObject<T>(obj: T): T
+
+  /** Ensure a nested path of objects exists */
+  static assureObjectPath(obj: Record<string, any>, keys: string[]): Record<string, any>
+
+  /** Set a value in a nested object structure */
+  static setNestedValue(obj: Record<string, any>, keys: string[], value: unknown): void
+
+  /** Deeply merge objects */
+  static mergeObject<T extends Record<string, any>>(...sources: T[]): T
+
+  /** Check if all elements in an array are strings */
+  static uniformStringArray(arr: unknown[]): arr is string[]
+
+  /** Filter an array asynchronously */
+  static asyncFilter<T>(arr: T[], predicate: (item: T) => Promise<boolean>): Promise<T[]>
+}

package/src/types/DirectoryObject.d.ts

@@ -0,0 +1,55 @@
+// Type definitions for DirectoryObject
+
+/**
+ * DirectoryObject encapsulates metadata and operations for a directory,
+ * including path resolution and existence checks.
+ */
+export default class DirectoryObject {
+  /**
+   * Create a new DirectoryObject instance.
+   * @param directory - The directory path
+   */
+  constructor(directory: string)
+
+  /** User-supplied path */
+  readonly supplied: string
+
+  /** The absolute directory path */
+  readonly path: string
+
+  /** The directory URI */
+  readonly uri: string
+
+  /** The directory name */
+  readonly name: string
+
+  /** The directory name without extension */
+  readonly module: string
+
+  /** The directory extension (usually empty) */
+  readonly extension: string
+
+  /** Always false for directories */
+  readonly isFile: false
+
+  /** Always true for directories */
+  readonly isDirectory: true
+
+  /** Whether the directory exists (async) */
+  readonly exists: Promise<boolean>
+
+  /** Returns a string representation of the DirectoryObject */
+  toString(): string
+
+  /** Returns a JSON representation of the DirectoryObject */
+  toJSON(): {
+    supplied: string
+    path: string
+    uri: string
+    name: string
+    module: string
+    extension: string
+    isFile: boolean
+    isDirectory: boolean
+  }
+}

package/src/types/File.d.ts

@@ -0,0 +1,76 @@
+// Type definitions for File utilities
+
+import FileObject from './FileObject.js'
+import DirectoryObject from './DirectoryObject.js'
+
+export interface FileParts {
+  /** The file name with extension */
+  base: string
+  /** The directory path */
+  dir: string
+  /** The file extension (including dot) */
+  ext: string
+}
+
+export interface DirectoryListing {
+  /** Array of FileObject instances */
+  files: FileObject[]
+  /** Array of DirectoryObject instances */
+  directories: DirectoryObject[]
+}
+
+/**
+ * File system utilities for reading, writing, and manipulating files and directories.
+ */
+export default class File {
+  /** Fix slashes in a path */
+  static fixSlashes(pathName: string): string
+
+  /** Convert a path to a URI */
+  static pathToUri(pathName: string): string
+
+  /** Convert a URI to a path */
+  static uriToPath(pathName: string): string
+
+  /** Check if a file can be read */
+  static canReadFile(file: FileObject): Promise<boolean>
+
+  /** Check if a file can be written */
+  static canWriteFile(file: FileObject): Promise<boolean>
+
+  /** Check if a file exists */
+  static fileExists(file: FileObject): Promise<boolean>
+
+  /** Get the size of a file */
+  static fileSize(file: FileObject): Promise<number | null>
+
+  /** Get the last modification time of a file */
+  static fileModified(file: FileObject): Promise<Date | null>
+
+  /** Check if a directory exists */
+  static directoryExists(dirObject: DirectoryObject): Promise<boolean>
+
+  /** Deconstruct a filename into parts */
+  static deconstructFilenameToParts(fileName: string): FileParts
+
+  /** Retrieve files matching glob pattern(s) */
+  static getFiles(glob: string | string[]): Promise<FileObject[]>
+
+  /** List the contents of a directory */
+  static ls(directory: string): Promise<DirectoryListing>
+
+  /** Read the content of a file */
+  static readFile(fileObject: FileObject): Promise<string>
+
+  /** Write content to a file */
+  static writeFile(fileObject: FileObject, content: string): Promise<void>
+
+  /** Load an object from JSON or YAML file */
+  static loadDataFile(fileObject: FileObject): Promise<any>
+
+  /** Ensure a directory exists, creating it if necessary */
+  static assureDirectory(dirObject: DirectoryObject, options?: any): Promise<boolean>
+
+  /** Compute relative path between two file system objects */
+  static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string
+}

package/src/types/FileObject.d.ts

@@ -0,0 +1,59 @@
+// Type definitions for FileObject
+
+import DirectoryObject from './DirectoryObject.js'
+
+/**
+ * FileObject encapsulates metadata and operations for a file, including path
+ * resolution and existence checks.
+ */
+export default class FileObject {
+  /**
+   * Create a new FileObject instance.
+   * @param fileName - The file path
+   * @param directory - The parent directory (object or string)
+   */
+  constructor(fileName: string, directory?: DirectoryObject | string | null)
+
+  /** User-supplied path */
+  readonly supplied: string
+
+  /** The absolute file path */
+  readonly path: string
+
+  /** The file URI */
+  readonly uri: string
+
+  /** The file name */
+  readonly name: string
+
+  /** The file name without extension */
+  readonly module: string
+
+  /** The file extension */
+  readonly extension: string
+
+  /** Always true for files */
+  readonly isFile: true
+
+  /** Always false for files */
+  readonly isDirectory: false
+
+  /** The parent directory object */
+  readonly directory: DirectoryObject
+
+  /** Whether the file exists (async) */
+  readonly exists: Promise<boolean>
+
+  /** Returns a JSON representation of the FileObject */
+  toJSON(): {
+    supplied: string
+    path: string
+    uri: string
+    name: string
+    module: string
+    extension: string
+    isFile: boolean
+    isDirectory: boolean
+    directory: string | null
+  }
+}

package/src/types/Sass.d.ts

@@ -0,0 +1,23 @@
+// Type definitions for Sass error class
+
+/**
+ * Custom error class for toolkit errors.
+ */
+export default class Sass extends Error {
+  constructor(message: string, ...arg: any[])
+
+  /** Array of trace messages */
+  readonly trace: string[]
+
+  /** Add a trace message and return this instance for chaining */
+  addTrace(message: string): this
+
+  /** Report the error to the terminal */
+  report(nerdMode?: boolean): void
+
+  /** Create a Sass from an existing Error object */
+  static from(error: Error, message: string): Sass
+
+  /** Factory method to create or enhance Sass instances */
+  static new(message: string, error?: Error | Sass): Sass
+}

package/src/types/Term.d.ts

@@ -0,0 +1,15 @@
+// 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 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
+  static resetTerminal(): Promise<void>
+  static clearLines(num: number): Promise<void>
+  static directWrite(output: string): Promise<void>
+}

package/src/types/Type.d.ts

@@ -0,0 +1,25 @@
+// Type definitions for Type specification class
+
+interface TypeSpecDefinition {
+  typeName: string
+  array: boolean
+}
+
+export default class TypeSpec {
+  constructor(string: string, options?: { delimiter?: string })
+
+  readonly specs: readonly TypeSpecDefinition[]
+  readonly length: number
+  readonly stringRepresentation: string
+
+  toString(): string
+  toJSON(): { specs: 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[]
+  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/Valid.d.ts

@@ -0,0 +1,9 @@
+// Type definitions for Valid utility class
+
+export default class Valid {
+  /** Validate a value against a type specification */
+  static validType(value: unknown, type: string, options?: { allowEmpty?: boolean }): void
+
+  /** Assert a condition */
+  static assert(condition: boolean, message: string, arg?: number | null): void
+}

package/src/types/index.d.ts

@@ -0,0 +1,14 @@
+// Core file system abstractions
+export { default as FileObject } from './FileObject.js'
+export { default as DirectoryObject } from './DirectoryObject.js'
+export { default as File } from './File.js'
+
+// Utility classes
+export { default as Data } from './Data.js'
+export { default as Sass } from './Sass.js'
+export { default as Term } from './Term.js'
+export { default as Type } from './Type.js'
+export { default as Valid } from './Valid.js'
+
+// Type exports
+export type { FileParts } from './File.js'