@gesslar/toolkit 1.5.0 → 1.6.0

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
-}

package/src/types/DirectoryObject.d.ts

@@ -1,135 +0,0 @@
-// Implementation: ../lib/DirectoryObject.js
-// Type definitions for DirectoryObject
-
-import FS from './FS.js'
-import FileObject from './FileObject.js'
-
-export interface DirectoryListing {
-  /** Array of FileObject instances */
-  files: Array<FileObject>
-  /** Array of DirectoryObject instances */
-  directories: Array<DirectoryObject>
-}
-
-/**
- * DirectoryObject encapsulates metadata and operations for a directory,
- * including path resolution and existence checks.
- */
-export default class DirectoryObject extends FS {
-  /**
-   * 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
-
-  /** The platform-specific path separator (e.g., '/' on Unix, '\\' on Windows) */
-  readonly sep: string
-
-  /** Array of directory path segments split by separator */
-  readonly trail: string[]
-
-  /** Always false for directories */
-  readonly isFile: false
-
-  /** Always true for directories */
-  readonly isDirectory: true
-
-  /** Whether the directory exists (async) */
-  readonly exists: Promise<boolean>
-
-  /**
-   * Generator that walks up the directory tree, yielding parent directories.
-   * Starts from the current directory and yields each parent until reaching the root.
-   *
-   * @example
-   * ```typescript
-   * const dir = new DirectoryObject('/path/to/deep/directory')
-   * for (const parent of dir.walkUp) {
-   *   console.log(parent.path)
-   *   // /path/to/deep/directory
-   *   // /path/to/deep
-   *   // /path/to
-   *   // /path
-   *   // /
-   * }
-   * ```
-   */
-  readonly walkUp: Generator<DirectoryObject, void, unknown>
-
-  /** 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
-  }
-
-  /**
-   * Lists the contents of this directory.
-   * Returns FileObject instances for files and DirectoryObject instances for subdirectories.
-   *
-   * @returns Promise resolving to object with files and directories arrays
-   * @throws {Error} If directory cannot be read
-   *
-   * @example
-   * ```typescript
-   * const dir = new DirectoryObject('./src')
-   * const {files, directories} = await dir.read()
-   *
-   * console.log(`Found ${files.length} files`)
-   * files.forEach(file => console.log(file.name))
-   *
-   * console.log(`Found ${directories.length} subdirectories`)
-   * directories.forEach(subdir => console.log(subdir.name))
-   * ```
-   */
-  read(): Promise<DirectoryListing>
-
-  /**
-   * Ensures this directory exists, creating it if necessary.
-   * Gracefully handles the case where the directory already exists (EEXIST error).
-   * Pass options to control directory creation behavior (e.g., recursive, mode).
-   *
-   * @param options - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
-   * @returns Promise that resolves when directory exists or has been created
-   * @throws {Sass} If directory creation fails for reasons other than already existing
-   *
-   * @example
-   * ```typescript
-   * const dir = new DirectoryObject('./build/output')
-   *
-   * // Create directory recursively
-   * await dir.assureExists({recursive: true})
-   *
-   * // Now safe to write files
-   * const file = new FileObject('result.json', dir)
-   * await file.write(JSON.stringify(data))
-   * ```
-   */
-  assureExists(options?: any): Promise<void>
-}

package/src/types/FS.d.ts

@@ -1,40 +0,0 @@
-// Implementation: ../lib/FS.js
-// Type definitions for FS utilities
-
-import FileObject from './FileObject.js'
-import DirectoryObject from './DirectoryObject.js'
-
-/**
- * Base filesystem utilities class. FileObject and DirectoryObject extend this class.
- */
-export default class FS {
-  /** Array of lowercase file descriptor types */
-  static readonly fdTypes: readonly ['file', 'directory']
-
-  /** Array of uppercase file descriptor types */
-  static readonly upperFdTypes: readonly ['FILE', 'DIRECTORY']
-
-  /** Mapping from uppercase to lowercase file descriptor types */
-  static readonly fdType: Readonly<Record<'FILE' | 'DIRECTORY', 'file' | 'directory'>>
-
-  /** 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
-
-  /** Retrieve files matching glob pattern(s) */
-  static getFiles(glob: string | Array<string>): Promise<Array<FileObject>>
-
-  /** Compute relative path between two file system objects */
-  static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string
-
-  /** Merge two paths by finding overlapping segments and combining them efficiently */
-  static mergeOverlappingPaths(path1: string, path2: string, sep?: string): string
-
-  /** Resolve a path relative to another path using various strategies. Handles absolute paths, relative navigation, and overlap-based merging */
-  static resolvePath(fromPath: string, toPath: string): string
-}