@gesslar/toolkit 1.5.0 → 1.8.0

package/src/types/Collection.d.ts

@@ -1,321 +0,0 @@
-// Implementation: ../lib/Collection.js
-// Type definitions for Collection utilities
-
-/**
- * Collection utility functions for evaluating and manipulating arrays, objects, sets, and maps.
- * Provides functional programming patterns for collection processing with consistent error handling.
- */
-export default class Collection {
-  /**
-   * Evaluates an array with a predicate function, returning the first truthy result.
-   *
-   * @param collection - The array to evaluate
-   * @param predicate - Function called for each element: (element, index, array) => result
-   * @param forward - Whether to iterate forward (true) or backward (false). Default: true
-   * @returns The first truthy result from the predicate, or undefined if none found
-   *
-   * @throws {Sass} If collection is not an Array or predicate is not a Function
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const numbers = [1, 2, 3, 4, 5]
-   * const result = Collection.evalArray(numbers, (n, i) => n > 3 ? n * 2 : null)
-   * console.log(result) // 8 (first element > 3, doubled)
-   * ```
-   */
-  static evalArray<T, R>(
-    collection: T[],
-    predicate: (element: T, index: number, array: T[]) => R | null | undefined,
-    forward?: boolean
-  ): R | undefined
-
-  /**
-   * Evaluates an object with a predicate function, returning the first truthy result.
-   *
-   * @param collection - The object to evaluate
-   * @param predicate - Function called for each property: (value, key, object) => result
-   * @returns The first truthy result from the predicate, or undefined if none found
-   *
-   * @throws {Sass} If collection is not an Object or predicate is not a Function
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const obj = {a: 1, b: 2, c: 3}
-   * const result = Collection.evalObject(obj, (value, key) => value > 2 ? `${key}:${value}` : null)
-   * console.log(result) // "c:3"
-   * ```
-   */
-  static evalObject<T, R>(
-    collection: Record<string, T>,
-    predicate: (value: T, key: string, object: Record<string, T>) => R | null | undefined
-  ): R | undefined
-
-  /**
-   * Evaluates a Set with a predicate function, returning the first truthy result.
-   *
-   * @param collection - The Set to evaluate
-   * @param predicate - Function called for each element: (element, set) => result
-   * @returns The first truthy result from the predicate, or undefined if none found
-   *
-   * @throws {Sass} If collection is not a Set or predicate is not a Function
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const set = new Set([1, 2, 3, 4, 5])
-   * const result = Collection.evalSet(set, (n, s) => n > 3 ? n * 2 : null)
-   * console.log(result) // 8
-   * ```
-   */
-  static evalSet<T, R>(
-    collection: Set<T>,
-    predicate: (element: T, set: Set<T>) => R | null | undefined
-  ): R | undefined
-
-  /**
-   * Evaluates a Map with a predicate function, returning the first truthy result.
-   *
-   * @param collection - The Map to evaluate
-   * @param predicate - Function called for each entry: (value, key, map) => result
-   * @param forward - Whether to iterate forward (true) or backward (false). Default: true
-   * @returns The first truthy result from the predicate, or undefined if none found
-   *
-   * @throws {Sass} If collection is not a Map or predicate is not a Function
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const map = new Map([['a', 1], ['b', 2], ['c', 3]])
-   * const result = Collection.evalMap(map, (value, key) => value > 2 ? `${key}:${value}` : null)
-   * console.log(result) // "c:3"
-   * ```
-   */
-  static evalMap<K, V, R>(
-    collection: Map<K, V>,
-    predicate: (value: V, key: K, map: Map<K, V>) => R | null | undefined,
-    forward?: boolean
-  ): R | undefined
-
-  /**
-   * Zips two arrays together into an array of pairs.
-   *
-   * @param array1 - The first array
-   * @param array2 - The second array
-   * @returns Array of [element1, element2] pairs, length of shorter input array
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const result = Collection.zip([1, 2, 3], ['a', 'b', 'c'])
-   * console.log(result) // [[1, 'a'], [2, 'b'], [3, 'c']]
-   * ```
-   */
-  static zip<T, U>(array1: T[], array2: U[]): [T, U][]
-
-  /**
-   * Unzips an array of arrays into separate arrays.
-   *
-   * @param array - Array of arrays to unzip
-   * @returns Array of separate arrays, one for each position
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const zipped = [[1, 'a'], [2, 'b'], [3, 'c']]
-   * const result = Collection.unzip(zipped)
-   * console.log(result) // [[1, 2, 3], ['a', 'b', 'c']]
-   * ```
-   */
-  static unzip<T>(array: T[][]): T[][]
-
-  /**
-   * Maps an array through an async function, executing operations sequentially.
-   *
-   * Unlike Promise.all(array.map(fn)), this executes each async operation
-   * one at a time, maintaining order and preventing overwhelming external resources.
-   *
-   * @param array - The array to map over
-   * @param asyncFn - Async function called for each element: (element) => Promise<result>
-   * @returns Promise resolving to array of mapped results
-   *
-   * @throws {Sass} If array is not an Array or asyncFn is not a Function
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * // Sequential API calls (won't overwhelm server)
-   * const urls = ['url1', 'url2', 'url3']
-   * const responses = await Collection.asyncMap(urls, async (url) => {
-   *   return await fetch(url).then(r => r.json())
-   * })
-   * console.log(responses) // [data1, data2, data3]
-   *
-   * // Works with sync functions too
-   * const numbers = [1, 2, 3]
-   * const doubled = await Collection.asyncMap(numbers, async (n) => n * 2)
-   * console.log(doubled) // [2, 4, 6]
-   * ```
-   */
-  static asyncMap<T, R>(array: T[], asyncFn: (element: T) => Promise<R> | R): Promise<R[]>
-
-  /** Check if all elements in an array are of a specified type or all the same type */
-  static isArrayUniform(arr: Array<unknown>, type?: string): boolean
-
-  /** Remove duplicate elements from an array, returning a new array with unique values */
-  static isArrayUnique<T>(arr: Array<T>): Array<T>
-
-  /** Get the intersection of two arrays */
-  static intersection<T>(arr1: Array<T>, arr2: Array<T>): Array<T>
-
-  /** Check if two arrays have any elements in common */
-  static intersects<T>(arr1: Array<T>, arr2: Array<T>): boolean
-
-  /** Pad an array to a specified length */
-  static arrayPad<T>(arr: Array<T>, length: number, value: T, position?: number): Array<T>
-
-  /** Filter an array asynchronously */
-  static asyncFilter<T>(arr: Array<T>, predicate: (item: T) => Promise<boolean>): Promise<Array<T>>
-
-  /** Clone an object */
-  static cloneObject<T extends Record<string, any>>(obj: T, freeze?: boolean): T
-
-  /** Check if an object is empty */
-  static isObjectEmpty(obj: Record<string, any>): boolean
-
-  /** Ensure a nested path of objects exists */
-  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: Array<string>, value: unknown): void
-
-  /** Deeply merge objects */
-  static mergeObject<T extends Record<string, any>>(...sources: Array<T>): T
-
-  /** Recursively freeze an object */
-  static deepFreezeObject<T>(obj: T): T
-
-  /** 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>>
-
-  /** Allocate an object from a source array and spec */
-  static allocateObject(
-    source: Array<unknown>,
-    spec:
-      | Array<unknown>
-      | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)
-  ): Promise<Record<string, unknown>>
-
-  /**
-   * Flattens one level of an array of plain objects, transposing values so each
-   * key maps to the collected values from every object.
-   *
-   * Accepts either a simple array of objects or an array that mixes objects and
-   * nested object arrays (one level deep). Nested arrays are flattened before
-   * transposition.
-   *
-   * @param input - Array of plain objects (optionally containing nested arrays)
-   * @returns Object with keys mapped to arrays of values from all input objects
-   *
-   * @throws {Sass} If input is not an Array or if any element is not a plain object after flattening
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const objects = [
-   *   [{ name: 'Alice', age: 25 }],
-   *   { name: 'Bob', age: 30 }
-   * ]
-   *
-   * const result = Collection.flattenObjectArray(objects)
-   * // result: { name: ['Alice', 'Bob'], age: [25, 30] }
-   * ```
-   */
-  static flattenObjectArray(
-    input: Array<Record<string, unknown> | Array<Record<string, unknown>>>
-  ): Record<string, Array<unknown>>
-
-  /**
-   * Transposes an array of plain objects into an object of arrays, keyed by the
-   * original object keys.
-   *
-   * @param objects - Array of plain objects to transpose
-   * @returns Object with keys mapped to arrays of values from the input objects
-   *
-   * @throws {Sass} If objects is not an Array or if any element is not a plain object
-   */
-  static transposeObjects(objects: Array<Record<string, unknown>>): Record<string, Array<unknown>>
-
-  /**
-   * Trims falsy values from both ends of an array.
-   *
-   * @param arr - The array to trim
-   * @param except - Array of values to exclude from trimming (default: [])
-   * @returns The trimmed array (modified in place)
-   *
-   * @throws {Sass} If arr or except is not an Array
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const arr = [null, 0, 1, 2, "", undefined]
-   * Collection.trimArray(arr)
-   * console.log(arr) // [1, 2]
-   * ```
-   */
-  static trimArray<T>(arr: Array<T>, except?: Array<T>): Array<T>
-
-  /**
-   * Trims falsy values from the right end of an array.
-   *
-   * @param arr - The array to trim
-   * @param except - Array of values to exclude from trimming (default: [])
-   * @returns The trimmed array (modified in place)
-   *
-   * @throws {Sass} If arr or except is not an Array
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const arr = [1, "", undefined]
-   * Collection.trimArrayRight(arr)
-   * console.log(arr) // [1]
-   * ```
-   */
-  static trimArrayRight<T>(arr: Array<T>, except?: Array<T>): Array<T>
-
-  /**
-   * Trims falsy values from the left end of an array.
-   *
-   * @param arr - The array to trim
-   * @param except - Array of values to exclude from trimming (default: [])
-   * @returns The trimmed array (modified in place)
-   *
-   * @throws {Sass} If arr or except is not an Array
-   *
-   * @example
-   * ```typescript
-   * import { Collection } from '@gesslar/toolkit'
-   *
-   * const arr = [null, undefined, "value"]
-   * Collection.trimArrayLeft(arr)
-   * console.log(arr) // ["value"]
-   * ```
-   */
-  static trimArrayLeft<T>(arr: Array<T>, except?: Array<T>): Array<T>
-}

package/src/types/Contract.d.ts

@@ -1,162 +0,0 @@
-// Implementation: ../lib/Contract.js
-
-import type { ValidateFunction } from 'ajv'
-
-/**
- * Debug function type for Contract operations
- */
-export type DebugFunction = (message: string, level?: number, ...args: unknown[]) => void
-
-/**
- * Contract represents a successful negotiation between Terms.
- * It handles validation and compatibility checking between what
- * one action provides and what another accepts.
- *
- * @example
- * ```typescript
- * // Two-party contract between provider and consumer
- * const provider = new Terms(providerDefinition)
- * const consumer = new Terms(consumerDefinition)
- * const contract = new Contract(provider, consumer, { debug: console.log })
- *
- * // Validate data against the contract
- * const isValid = contract.validate(someData)
- * ```
- *
- * @example
- * ```typescript
- * // Single-party contract from terms definition
- * const contract = Contract.fromTerms("parser", {
- *   provides: {
- *     type: "object",
- *     properties: {
- *       name: { type: "string" },
- *       age: { type: "number" }
- *     }
- *   }
- * })
- *
- * contract.validate({ name: "John", age: 30 }) // true
- * ```
- */
-declare class Contract {
-  /**
-   * Creates a contract by negotiating between provider and consumer terms
-   *
-   * @param providerTerms - What the provider offers
-   * @param consumerTerms - What the consumer expects
-   * @param options - Configuration options
-   * @param options.debug - Debug function for logging negotiation details
-   *
-   * @throws {Sass} If contract negotiation fails due to incompatible terms
-   */
-  constructor(
-    providerTerms: import('./Terms.js').default | null,
-    consumerTerms: import('./Terms.js').default | null,
-    options?: { debug?: DebugFunction }
-  )
-
-  /**
-   * Creates a contract from terms with schema validation
-   *
-   * @param name - Contract identifier for error reporting
-   * @param termsDefinition - The terms definition object
-   * @param validator - Optional AJV schema validator function with .errors property
-   * @param debug - Debug function for logging validation details
-   * @returns New contract instance ready for data validation
-   *
-   * @throws {Sass} If terms definition is invalid according to the validator
-   *
-   * @example
-   * ```typescript
-   * const contract = Contract.fromTerms("user-parser", {
-   *   provides: {
-   *     type: "object",
-   *     properties: {
-   *       id: { type: "string" },
-   *       name: { type: "string" }
-   *     },
-   *     required: ["id", "name"]
-   *   }
-   * })
-   * ```
-   */
-  static fromTerms(
-    name: string,
-    termsDefinition: object,
-    validator?: ValidateFunction | null,
-    debug?: DebugFunction
-  ): Contract
-
-  /**
-   * Validates data against this contract's schema
-   *
-   * @param data - Data object to validate against the contract
-   * @returns True if validation passes
-   *
-   * @throws {Sass} If validation fails with detailed error messages
-   * @throws {Sass} If contract has not been successfully negotiated
-   * @throws {Sass} If no validator is available for this contract
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   contract.validate({ id: "123", name: "John" })
-   *   console.log("Data is valid!")
-   * } catch (error) {
-   *   console.error("Validation failed:", error.message)
-   * }
-   * ```
-   */
-  validate(data: object): boolean
-
-  /**
-   * Check if contract negotiation was successful
-   *
-   * @returns True if the contract has been successfully negotiated
-   *
-   * @example
-   * ```typescript
-   * if (contract.isNegotiated) {
-   *   contract.validate(data)
-   * } else {
-   *   console.error("Contract negotiation failed")
-   * }
-   * ```
-   */
-  get isNegotiated(): boolean
-
-  /**
-   * Get the provider terms (if any)
-   *
-   * @returns Provider terms or null for single-party contracts
-   */
-  get providerTerms(): import('./Terms.js').default | null
-
-  /**
-   * Get the consumer terms (if any)
-   *
-   * @returns Consumer terms or null for single-party contracts
-   */
-  get consumerTerms(): import('./Terms.js').default | null
-
-  /**
-   * Get the contract validator function
-   *
-   * @returns The AJV validator function used by this contract, or null if none available
-   *
-   * @example
-   * ```typescript
-   * const validator = contract.validator
-   * if (validator) {
-   *   const isValid = validator(someData)
-   *   if (!isValid) {
-   *     console.log("Validation errors:", validator.errors)
-   *   }
-   * }
-   * ```
-   */
-  get validator(): ((data: object) => boolean) | null
-}
-
-export default Contract

package/src/types/Data.d.ts

@@ -1,175 +0,0 @@
-// Implementation: ../lib/Data.js
-// 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: ReadonlyArray<string>
-
-  /** Array of JavaScript constructor names for built-in objects */
-  static readonly constructors: ReadonlyArray<string>
-
-  /** Combined array of all supported data types */
-  static readonly dataTypes: ReadonlyArray<string>
-
-  /** Array of type names that can be checked for emptiness */
-  static readonly emptyableTypes: ReadonlyArray<string>
-
-  /**
-   * Append a suffix string to the end of a string if it doesn't already end with it.
-   *
-   * Useful for ensuring strings have consistent endings like file extensions,
-   * URL paths, or punctuation. Performs case-sensitive comparison and only appends
-   * if the string doesn't already end with the specified suffix.
-   *
-   * @param string - The base string to potentially append to. Can be empty string.
-   * @param append - The suffix to append if not already present. Cannot be empty.
-   * @returns The string with the suffix appended, or the original string if suffix already present
-   *
-   * @throws {Error} When append parameter is empty or undefined
-   *
-   * @example
-   * ```typescript
-   * import { Data } from '@gesslar/toolkit'
-   *
-   * // Basic usage with file extensions
-   * const filename = Data.appendString('config', '.json')
-   * console.log(filename) // 'config.json'
-   *
-   * // No double-appending
-   * const alreadyHasExt = Data.appendString('package.json', '.json')
-   * console.log(alreadyHasExt) // 'package.json' (unchanged)
-   *
-   * // URL path handling
-   * const apiPath = Data.appendString('/api/users', '/')
-   * console.log(apiPath) // '/api/users/'
-   *
-   * // Works with empty strings
-   * const fromEmpty = Data.appendString('', '.txt')
-   * console.log(fromEmpty) // '.txt'
-   * ```
-   */
-  static appendString(string: string, append: string): string
-
-  /**
-   * Prepend a prefix string to the beginning of a string if it doesn't already start with it.
-   *
-   * Useful for ensuring strings have consistent beginnings like protocol prefixes,
-   * path separators, or formatting markers. Performs case-sensitive comparison and
-   * only prepends if the string doesn't already start with the specified prefix.
-   *
-   * @param string - The base string to potentially prepend to. Can be empty string.
-   * @param prepend - The prefix to prepend if not already present. Cannot be empty.
-   * @returns The string with the prefix prepended, or the original string if prefix already present
-   *
-   * @throws {Error} When prepend parameter is empty or undefined
-   *
-   * @example
-   * ```typescript
-   * import { Data } from '@gesslar/toolkit'
-   *
-   * // Basic usage with protocols
-   * const url = Data.prependString('example.com', 'https://')
-   * console.log(url) // 'https://example.com'
-   *
-   * // No double-prepending
-   * const alreadyHasProtocol = Data.prependString('https://api.example.com', 'https://')
-   * console.log(alreadyHasProtocol) // 'https://api.example.com' (unchanged)
-   *
-   * // File path handling
-   * const absolutePath = Data.prependString('home/user/docs', '/')
-   * console.log(absolutePath) // '/home/user/docs'
-   *
-   * // CSS class prefixing
-   * const className = Data.prependString('button-primary', 'css-')
-   * console.log(className) // 'css-button-primary'
-   * ```
-   */
-  static prependString(string: string, prepend: string): string
-
-
-  /** 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: Array<string>): Record<string, any>
-
-  /** Set a value in a nested object structure */
-  static setNestedValue(obj: Record<string, any>, keys: Array<string>, value: unknown): void
-
-  /** Deeply merge objects */
-  static mergeObject<T extends Record<string, any>>(...sources: Array<T>): T
-
-  /** Filter an array asynchronously */
-  static asyncFilter<T>(arr: Array<T>, predicate: (item: T) => Promise<boolean>): Promise<Array<T>>
-
-  /** Ensures a value is within a specified range */
-  static clamp(val: number, min: number, max: number): number
-
-  /** Checks if a value is within a specified range (inclusive) */
-  static clamped(val: number, min: number, max: number): boolean
-
-  /**
-   * Checks if a value is a plain object - created with object literals {},
-   * new Object(), or Object.create(null).
-   *
-   * Distinguishes plain objects from objects created by custom constructors, built-ins,
-   * or primitives. Plain objects only have Object.prototype or null in their prototype chain.
-   * Useful for validating configuration objects or data structures that should be plain objects.
-   *
-   * @param value - The value to check for plain object status
-   * @returns True if the value is a plain object, false otherwise
-   *
-   * @example
-   * ```typescript
-   * import { Data } from '@gesslar/toolkit'
-   *
-   * // Plain objects return true
-   * console.log(Data.isPlainObject({})) // true
-   * console.log(Data.isPlainObject(new Object())) // true
-   * console.log(Data.isPlainObject(Object.create(null))) // true
-   *
-   * // Non-plain objects return false
-   * console.log(Data.isPlainObject([])) // false
-   * console.log(Data.isPlainObject(new Date())) // false
-   * console.log(Data.isPlainObject(/regex/)) // false
-   * console.log(Data.isPlainObject(null)) // false
-   * console.log(Data.isPlainObject('string')) // false
-   *
-   * // Useful for validating config objects
-   * function processConfig(config: unknown) {
-   *   if (!Data.isPlainObject(config)) {
-   *     throw new Error('Config must be a plain object')
-   *   }
-   *   // Safe to treat as object with string keys
-   *   return Object.entries(config)
-   * }
-   * ```
-   */
-  static isPlainObject(value: unknown): boolean
-}