@gesslar/toolkit 1.5.0 → 1.8.0

package/src/types/Terms.d.ts

@@ -1,145 +0,0 @@
-// Implementation: ../lib/Terms.js
-
-/**
- * Terms represents an interface definition - what an action promises to provide or accept.
- * It's just the specification, not the negotiation. Contract handles the negotiation.
- *
- * Terms can be created from objects, strings (YAML/JSON), or file references.
- * File references use the format "ref://path/to/file" for loading external definitions.
- *
- * @example
- * ```typescript
- * // Create terms from object definition
- * const terms = new Terms({
- *   provides: {
- *     type: "object",
- *     properties: {
- *       userId: { type: "string" },
- *       userName: { type: "string" }
- *     },
- *     required: ["userId"]
- *   }
- * })
- * ```
- *
- * @example
- * ```typescript
- * // Parse terms from YAML string
- * const yamlData = `
- * accepts:
- *   type: object
- *   properties:
- *     input:
- *       type: string
- *       minLength: 1
- * `
- * const parsedTerms = await Terms.parse(yamlData)
- * ```
- *
- * @example
- * ```typescript
- * // Parse terms from file reference
- * const directory = new DirectoryObject("/path/to/schemas")
- * const parsedTerms = await Terms.parse("ref://user-schema.json", directory)
- * ```
- */
-declare class Terms {
-  /**
-   * Creates a new Terms instance with the given definition
-   *
-   * @param definition - The terms definition object describing what is provided or accepted
-   *
-   * @example
-   * ```typescript
-   * const terms = new Terms({
-   *   provides: {
-   *     type: "object",
-   *     properties: {
-   *       data: { type: "array", items: { type: "string" } },
-   *       metadata: {
-   *         type: "object",
-   *         properties: {
-   *           timestamp: { type: "string", format: "date-time" }
-   *         }
-   *       }
-   *     }
-   *   }
-   * })
-   * ```
-   */
-  constructor(definition: object)
-
-  /**
-   * Parses terms data from various sources, handling file references
-   *
-   * @param termsData - Terms data as string (YAML/JSON/file reference) or object
-   * @param directoryObject - Directory context for resolving file references (required for ref:// URLs)
-   * @returns Promise resolving to parsed terms data object
-   *
-   * @throws {Sass} If termsData is not a string or object
-   * @throws {Sass} If string data cannot be parsed as YAML or JSON
-   * @throws {Sass} If file reference cannot be loaded (missing directory or file not found)
-   *
-   * @example
-   * ```typescript
-   * // Parse from YAML string
-   * const yamlTerms = await Terms.parse(`
-   *   provides:
-   *     type: string
-   *     pattern: "^[A-Z][a-z]+"
-   * `)
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Parse from JSON string
-   * const jsonTerms = await Terms.parse(`{
-   *   "accepts": {
-   *     "type": "number",
-   *     "minimum": 0,
-   *     "maximum": 100
-   *   }
-   * }`)
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Parse from file reference
-   * const directory = new DirectoryObject("./schemas")
-   * const fileTerms = await Terms.parse("ref://api-contract.yaml", directory)
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Parse from object (returns as-is)
-   * const objectTerms = await Terms.parse({
-   *   provides: { type: "boolean" }
-   * })
-   * ```
-   */
-  static parse(
-    termsData: string | object,
-    directoryObject?: import('./DirectoryObject.js').default
-  ): Promise<object>
-
-  /**
-   * Get the terms definition object
-   *
-   * @returns The complete terms definition as provided to the constructor
-   *
-   * @example
-   * ```typescript
-   * const terms = new Terms({
-   *   accepts: { type: "string" },
-   *   provides: { type: "number" }
-   * })
-   *
-   * const definition = terms.definition
-   * console.log(definition.accepts)  // { type: "string" }
-   * console.log(definition.provides) // { type: "number" }
-   * ```
-   */
-  get definition(): object
-}
-
-export default Terms

package/src/types/Type.d.ts

@@ -1,26 +0,0 @@
-// Implementation: ../lib/Type.js
-// Type definitions for Type specification class
-
-interface TypeSpecDefinition {
-  typeName: string
-  array: boolean
-}
-
-export default class TypeSpec {
-  constructor(string: string, options?: { delimiter?: string })
-
-  readonly specs: ReadonlyArray<TypeSpecDefinition>
-  readonly length: number
-  readonly stringRepresentation: string
-
-  toString(): 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): 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,275 +0,0 @@
-// Implementation: ../lib/Util.js
-
-/**
- * Utility class providing common helper functions for string manipulation,
- * timing, hashing, and option parsing.
- */
-declare class Util {
-  /**
-   * Capitalizes the first letter of a string.
-   *
-   * @param text - The text to capitalize
-   * @returns Text with first letter capitalized
-   * @throws {TypeError} If `text` is not a string
-   *
-   * @example
-   * ```typescript
-   * const result = Util.capitalize("hello world")
-   * console.log(result) // "Hello world"
-   *
-   * // Works with empty strings and single characters
-   * Util.capitalize("") // ""
-   * Util.capitalize("a") // "A"
-   * ```
-   */
-  static capitalize(text: string): string
-
-  /**
-   * Measure wall-clock time for an async function.
-   * Useful for performance monitoring and debugging async operations.
-   *
-   * @template T
-   * @param fn - Thunk returning a promise.
-   * @returns Object containing result and elapsed ms (number, 1 decimal).
-   *
-   * @example
-   * ```typescript
-   * const {result, cost} = await Util.time(async () => {
-   *   await new Promise(resolve => setTimeout(resolve, 100))
-   *   return "completed"
-   * })
-   * console.log(`Operation took ${cost}ms`) // "Operation took 100.2ms"
-   * console.log(result) // "completed"
-   * ```
-   */
-  static time<T>(fn: () => Promise<T>): Promise<{result: T, cost: number}>
-
-  /**
-   * Right-align a string inside a fixed width (left pad with spaces).
-   * If the string exceeds width it is returned unchanged.
-   *
-   * @param text - Text to align.
-   * @param width - Target field width (default 80).
-   * @returns Padded string.
-   */
-  static rightAlignText(text: string | number, width?: number): string
-
-  /**
-   * Centre-align a string inside a fixed width (pad with spaces on left).
-   * If the string exceeds width it is returned unchanged.
-   *
-   * @param text - Text to align.
-   * @param width - Target field width (default 80).
-   * @returns Padded string with text centred.
-   */
-  static centreAlignText(text: string | number, width?: number): string
-
-  /**
-   * Compute sha256 hash (hex) of the provided string.
-   *
-   * @param s - Input string.
-   * @returns 64-char hexadecimal digest.
-   *
-   * @example
-   * ```typescript
-   * const hash = Util.hashOf("hello world")
-   * console.log(hash) // "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
-   * ```
-   */
-  static hashOf(s: string): string
-
-  /**
-   * Extracts canonical option names from a Commander-style options object.
-   *
-   * Each key in the input object is a string containing one or more option
-   * forms, separated by commas (e.g. "-w, --watch"). This function splits each
-   * key, trims whitespace, and parses out the long option name (e.g. "watch")
-   * for each entry. If no long option ("--") is present, the short option (e.g.
-   * "v" from "-v") will be included in the result array. If both are present,
-   * the long option is preferred.
-   *
-   * @param object - Mapping of option strings to descriptions.
-   * @returns Array of canonical option names (long preferred, short if no long present).
-   *
-   * @example
-   * ```typescript
-   * const options = {
-   *   "-w, --watch": "Watch for changes",
-   *   "-v": "Verbose output",
-   *   "--config": "Config file path"
-   * }
-   * const names = Util.generateOptionNames(options)
-   * console.log(names) // ["watch", "v", "config"]
-   * ```
-   *
-   * @remarks
-   * Edge cases:
-   * - If a key contains only a short option ("-v"), that short name will be included
-   * - If multiple long options are present, only the first is used
-   * - Malformed option strings may return undefined (filtered out)
-   */
-  static generateOptionNames(object: Record<string, any>): Array<string>
-
-  /**
-   * Asynchronously awaits all promises in parallel.
-   * Wrapper around Promise.all for consistency with other utility methods.
-   *
-   * @param promises - Array of promises to await
-   * @returns Results of all promises
-   */
-  static awaitAll<T>(promises: Array<Promise<T>>): Promise<Array<T>>
-
-  /**
-   * Settles all promises (both fulfilled and rejected) in parallel.
-   * Wrapper around Promise.allSettled for consistency with other utility methods.
-   *
-   * @param promises - Array of promises to settle
-   * @returns Results of all settled promises with status and value/reason
-   */
-  static settleAll<T>(promises: Array<Promise<T>>): Promise<Array<PromiseSettledResult<T>>>
-
-  /**
-   * Returns the first promise to resolve or reject from an array of promises.
-   * Wrapper around Promise.race for consistency with other utility methods.
-   *
-   * @param promises - Array of promises to race
-   * @returns Result of the first settled promise
-   */
-  static race<T>(promises: Array<Promise<T>>): Promise<T>
-
-  /**
-   * Emits an event asynchronously and waits for all listeners to complete.
-   *
-   * Unlike the standard EventEmitter.emit() which is synchronous, this method
-   * properly handles async event listeners by waiting for all of them to
-   * resolve or reject using Promise.allSettled(). If any listener throws an
-   * error, the first error encountered will be re-thrown.
-   *
-   * Uses strict instanceof checking to ensure the emitter is a genuine EventEmitter.
-   *
-   * @param emitter - The EventEmitter instance to emit on
-   * @param event - The event name to emit
-   * @param args - Arguments to pass to event listeners
-   * @returns Resolves when all listeners have completed
-   *
-   * @example
-   * ```typescript
-   * import { EventEmitter } from 'events'
-   * import { Util } from '@gesslar/toolkit'
-   *
-   * const emitter = new EventEmitter()
-   *
-   * emitter.on('data', async (payload) => {
-   *   console.log('Processing:', payload.id)
-   *   await new Promise(resolve => setTimeout(resolve, 100))
-   *   console.log('Completed:', payload.id)
-   * })
-   *
-   * // Wait for all async listeners to complete
-   * await Util.asyncEmit(emitter, 'data', { id: 'task-1' })
-   * console.log('All listeners finished')
-   * ```
-   *
-   * @throws Will throw an error if any listener rejects or throws
-   */
-  static asyncEmit(emitter: import('events').EventEmitter, event: string, ...args: unknown[]): Promise<void>
-
-  /**
-   * Emits an event asynchronously and waits for all listeners to complete.
-   * Like asyncEmit, but uses duck typing for more flexible emitter validation.
-   * Accepts any object that has the required EventEmitter-like methods.
-   *
-   * @param emitter - Any object with EventEmitter-like interface
-   * @param event - The event name to emit
-   * @param args - Arguments to pass to event listeners
-   * @returns Resolves when all listeners have completed
-   */
-  static asyncEmitAnon(
-    emitter: {
-      listeners(event: string): Function[],
-      on(event: string, listener: Function): any,
-      emit(event: string, ...args: unknown[]): any
-    },
-    event: string,
-    ...args: unknown[]
-  ): Promise<void>
-
-  /**
-   * Determine the Levenshtein distance between two string values.
-   * The Levenshtein distance is the minimum number of single-character edits
-   * (insertions, deletions, or substitutions) required to change one string into another.
-   *
-   * @param a - The first string for comparison
-   * @param b - The second string for comparison
-   * @returns The Levenshtein distance (number of edits needed)
-   *
-   * @example
-   * ```typescript
-   * Util.levenshteinDistance("kitten", "sitting") // 3
-   * Util.levenshteinDistance("book", "back") // 2
-   * Util.levenshteinDistance("hello", "hello") // 0
-   * ```
-   */
-  static levenshteinDistance(a: string, b: string): number
-
-  /**
-   * Find the closest match between an input string and an array of allowed values
-   * using Levenshtein distance. Returns the closest match if it's within a threshold
-   * of 2 edits, otherwise returns null.
-   *
-   * Useful for fuzzy string matching, such as suggesting corrections for typos
-   * in command-line arguments or configuration values.
-   *
-   * @param input - The input string to find a match for
-   * @param allowedValues - Array of allowed string values to match against
-   * @param threshold - Maximum edit distance for a match (default: 2)
-   * @returns The closest matching string, or null if no match within threshold
-   *
-   * @example
-   * ```typescript
-   * const commands = ["help", "build", "test", "deploy"]
-   * Util.findClosestMatch("bulid", commands) // "build"
-   * Util.findClosestMatch("xyz", commands) // null
-   * ```
-   */
-  static findClosestMatch(input: string, allowedValues: string[], threshold?: number): string | null
-
-  /**
-   * Creates a RegExp from a multiline string by removing line breaks and
-   * optionally trimming whitespace from each line.
-   *
-   * This utility makes complex regular expressions more readable by allowing
-   * them to be written across multiple lines with proper formatting and indentation.
-   * The resulting regex is functionally identical to writing it as a single line.
-   *
-   * @param input - Multiline string containing the regex pattern (required)
-   * @param trim - Whether to trim whitespace from each line (default: true)
-   * @param flags - Array of regex flags to apply (default: [])
-   * @returns A new RegExp object with the processed pattern
-   *
-   * @throws Will throw if input is not a string
-   * @throws Will throw if trim is not a boolean
-   * @throws Will throw if flags is not an array
-   * @throws Will throw if flags contains non-string elements
-   *
-   * @example
-   * ```typescript
-   * const regex = Util.regexify(`
-   *   \\s*\\*\\s*
-   *   @(?<tag>\\w+)
-   *   \\s*
-   *   \\{(?<type>\\w+(?:\\|\\w+)*(?:\\*)?)\\}
-   *   \\s+
-   *   (?<name>\\w+)
-   * `)
-   * // Creates: /\s*\*\s*@(?<tag>\w+)\s*\{(?<type>\w+(?:\|\w+)*(?:\*)?)\}\s+(?<name>\w+)/
-   *
-   * // With flags:
-   * const globalRegex = Util.regexify(pattern, true, ['g', 'i'])
-   * // Creates regex with global and case-insensitive flags
-   * ```
-   */
-  static regexify(input: string, trim?: boolean, flags?: string[]): RegExp
-}
-
-export default Util

package/src/types/Valid.d.ts

@@ -1,13 +0,0 @@
-// Implementation: ../lib/Valid.js
-// Type definitions for Valid utility class
-
-export default class Valid {
-  /** Validate a value against a type specification */
-  static type(value: unknown, type: string, options?: { allowEmpty?: boolean }): void
-
-  /** Assert a condition */
-  static assert(condition: boolean, message: string, arg?: number | null): void
-
-  /** Protect against prototype pollution by checking for dangerous keys */
-  static prototypePollutionProtection(keys: string[]): void
-}

package/src/types/browser/lib/Disposable.d.ts

@@ -1,35 +0,0 @@
-/**
- * Simple lifecycle helper that tracks disposer callbacks.
- * Register any teardown functions and call dispose() to run them in reverse.
- */
-export class Disposer {
-  /**
-   * Registers a disposer callback to be executed when disposed.
-   *
-   * @param {...(() => void)|Array<() => void>} disposers - Cleanup callbacks.
-   * @returns {(() => void)|Array<() => void>} Function(s) to unregister the disposer(s).
-   */
-  register(...disposers: Array<(() => void) | Array<() => void>>): (() => void) | Array<() => void>;
-  /**
-   * Runs all registered disposers in reverse order.
-   *
-   * @returns {void}
-   */
-  dispose(): void;
-  /**
-   * Whether disposal has run.
-   *
-   * @returns {boolean} True when dispose() has already been called.
-   */
-  get disposed(): boolean;
-  /**
-   * Read-only list of registered disposers.
-   *
-   * @returns {Array<() => void>} Snapshot of disposer callbacks.
-   */
-  get disposers(): Array<() => void>;
-  #private;
-}
-declare const _default: Disposer;
-export default _default;
-//# sourceMappingURL=Disposer.d.ts.map

package/src/types/browser/lib/Disposable.d.ts.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "file": "Disposer.d.ts",
-  "sourceRoot": "",
-  "sources": [
-    "../../../browser/lib/Disposer.js"
-  ],
-  "names": [],
-  "mappings": "AAAA;;;GAGG;AACH;IAIE;;;;;OAKG;IACH,2BAHW,MAAM,IAAI,GACR,MAAM,IAAI,CAStB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAoBhB;IAED;;;;OAIG;IACH,gBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,KAAK,CAAC,MAAM,IAAI,CAAC,CAI7B;;CAQF"
-}

package/src/types/browser/lib/Hook.d.ts

@@ -1,11 +0,0 @@
-declare const _default: typeof PipeClass;
-export default _default;
-declare class PipeClass {
-    static source(func: any): PipeClass;
-    constructor(func: any);
-    name: string;
-    then(func: any): Promise<this>;
-    get value(): any;
-    #private;
-}
-//# sourceMappingURL=Hook.d.ts.map

package/src/types/browser/lib/Hook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Hook.d.ts","sourceRoot":"","sources":["../../../browser/lib/Hook.js"],"names":[],"mappings":";;AAGA;IAYE,oCAEC;IARD,uBAIC;IATD,aAAa;IAeb,+BAgBC;IAED,iBAEC;;CAuBF"}

package/src/types/browser/lib/test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=test.d.ts.map

package/src/types/browser/lib/test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../../browser/lib/test.js"],"names":[],"mappings":""}

package/src/types/browser/lib/test2.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=test2.d.ts.map

package/src/types/browser/lib/test2.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test2.d.ts","sourceRoot":"","sources":["../../../browser/lib/test2.js"],"names":[],"mappings":""}

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

@@ -1,37 +0,0 @@
-/**
- * Custom error class for toolkit errors.
- * Provides error chaining, trace management, and formatted error reporting.
- */
-export default class Chide extends Sass {
-    /**
-     * Creates an Chide 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 {Chide} New Chide instance with trace from the original error
-     * @throws {Chide} If the first parameter is not an Error instance
-     */
-    static from(error: Error, message: string): Chide;
-    /**
-     * 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|Chide} [error] - Optional existing error to wrap or enhance
-     * @returns {Chide} New or enhanced Sass instance
-     */
-    static "new"(message: string, error?: Error | Sass | Tantrum | Chide): Chide;
-    /**
-     * Adds a trace message and returns this instance for chaining.
-     *
-     * @param {string} message - The trace message to add
-     * @returns {this} This Chide instance for method chaining
-     */
-    addTrace(message: string): this;
-    #private;
-}
-import Sass from "./Sass.js";
-import Tantrum from "./Tantrum.js";
-//# sourceMappingURL=Chide.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Chide.d.ts","sourceRoot":"","sources":["../../lib/Chide.js"],"names":[],"mappings":"AAkBA;;;GAGG;AACH;IA2GE;;;;;;;;OAQG;IACH,mBALW,KAAK,WACL,MAAM,GACJ,KAAK,CAWjB;IAED;;;;;;;;OAQG;IACH,sBAJW,MAAM,UACN,KAAK,GAAC,IAAI,GAAC,OAAO,GAAC,KAAK,GACtB,KAAK,CAWjB;IA/GD;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,IAAI,CAShB;;CAmGF;iBAzJgB,WAAW;oBAER,cAAc"}