@gesslar/toolkit 0.0.7 → 0.0.9

package/README.md

@@ -1,4 +1,4 @@
-# @gesslar/toolkit
+# npm i @gesslar/toolkit
 
 This package is intended to be a collection of useful utilities for any
 project's consumption. Not the kind that gives you bleeding, hacking coughs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -21,9 +21,18 @@
   },
   "scripts": {
     "lint": "eslint src/",
+    "lint:docs": "cd docs && npm run lint",
+    "lint:fix": "eslint src/ --fix",
+    "lint:fix:docs": "cd docs && npm run lint:fix",
     "submit": "npm publish --access public",
     "update": "npx npm-check-updates -u && npm install",
-    "test": "node examples/FileSystem/index.js"
+    "test": "node examples/FileSystem/index.js",
+    "docs:dev": "npm run docs:build && cd docs && npm run start",
+    "docs:build": "npm run docs:clean && npm run docs:generate && cd docs && npm run build",
+    "docs:serve": "cd docs && npm run serve",
+    "docs:clean": "cd docs && npm run docs:clean",
+    "docs:generate": "npx typedoc src/types/index.d.ts --out docs/docs/api --plugin typedoc-plugin-markdown --readme none --excludePrivate --excludeProtected --excludeInternal --includeVersion",
+    "docs:install": "cd docs && npm install"
   },
   "repository": {
     "type": "git",
@@ -57,6 +66,8 @@
     "@typescript-eslint/eslint-plugin": "^8.44.0",
     "@typescript-eslint/parser": "^8.44.0",
     "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.1.0"
+    "eslint-plugin-jsdoc": "^60.1.0",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "^4.9.0"
   }
 }

package/src/lib/File.js

@@ -225,15 +225,15 @@ export default class File {
   /**
    * Lists the contents of a directory.
    *
-   * @param {string} directory - The directory to list.
+   * @param {DirectoryObject} directory - The directory to list.
    * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and
    * directories in the directory.
    */
   static async ls(directory) {
-    const found = await fs.readdir(directory, {withFileTypes: true})
+    const found = await fs.readdir(directory.uri, {withFileTypes: true})
     const results = await Promise.all(
       found.map(async dirent => {
-        const fullPath = path.join(directory, dirent.name)
+        const fullPath = path.join(directory.uri, dirent.name)
         const stat = await fs.stat(fullPath)
 
         return {dirent, stat, fullPath}

package/src/lib/Glog.js

@@ -107,6 +107,19 @@ class Glog {
   }
 }
 
+/**
+ * Global logging utility with proxy-based dual interface.
+ * Can be used as both a class and a function for maximum flexibility.
+ *
+ * @class Glog
+ * @example
+ * // Use as function
+ * Glog('Hello world')
+ * Glog(2, 'Debug message')
+ *
+ * // Use class methods
+ * Glog.setLogLevel(3).setLogPrefix('[App]')
+ */
 // Wrap the class in a proxy
 export default new Proxy(Glog, {
   apply(target, thisArg, argumentsList) {

package/src/types/Data.d.ts

@@ -19,16 +19,164 @@ export default class Data {
   /** Array of type names that can be checked for emptiness */
   static readonly emptyableTypes: ReadonlyArray<string>
 
-  /** Append a string if it doesn't already end with it */
+  /**
+   * 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 string if it doesn't already start with it */
+  /**
+   * 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
 
-  /** Check if all elements in an array are of a specified type */
+  /**
+   * Check if all elements in an array are of a specified type or all the same type.
+   * 
+   * Performs type checking on every element in the array using the toolkit's type
+   * system. If no type is specified, checks that all elements are of the same type.
+   * Useful for validating data structures and ensuring type consistency before processing.
+   *
+   * @param arr - The array to check for type uniformity. Can be empty (returns true).
+   * @param type - Optional type name to check against. If not provided, checks that all
+   *              elements have the same type. Must be a valid type from Data.dataTypes.
+   * @returns True if all elements match the specified type or are all the same type,
+   *         false if there's any type mismatch or if type parameter is invalid
+   * 
+   * @example
+   * ```typescript
+   * import { Data } from '@gesslar/toolkit'
+   * 
+   * // Check for specific type uniformity
+   * const numbers = [1, 2, 3, 4, 5]
+   * const strings = ['a', 'b', 'c']
+   * const mixed = [1, 'a', true]
+   * 
+   * console.log(Data.isArrayUniform(numbers, 'number'))  // true
+   * console.log(Data.isArrayUniform(strings, 'string'))  // true
+   * console.log(Data.isArrayUniform(mixed, 'number'))    // false
+   * 
+   * // Check that all elements are the same type (any type)
+   * console.log(Data.isArrayUniform(numbers))     // true (all numbers)
+   * console.log(Data.isArrayUniform(strings))     // true (all strings) 
+   * console.log(Data.isArrayUniform(mixed))       // false (mixed types)
+   * console.log(Data.isArrayUniform([]))          // true (empty array)
+   * 
+   * // Useful for validation before processing
+   * function processNumbers(data: unknown[]) {
+   *   if (!Data.isArrayUniform(data, 'number')) {
+   *     throw new Error('Array must contain only numbers')
+   *   }
+   *   return data.reduce((sum, num) => sum + num, 0)
+   * }
+   * ```
+   */
   static isArrayUniform(arr: Array<unknown>, type?: string): boolean
 
-  /** Remove duplicates from an array */
+  /**
+   * Remove duplicate elements from an array, returning a new array with unique values.
+   * 
+   * Creates a new array containing only the first occurrence of each unique value,
+   * preserving the original order of first appearances. Uses strict equality (===)
+   * for primitive comparisons and shallow comparison for objects.
+   *
+   * @param arr - The array to remove duplicates from. Can be empty or contain any types.
+   * @returns A new array with duplicate elements removed, preserving order of first occurrence
+   * 
+   * @example
+   * ```typescript
+   * import { Data } from '@gesslar/toolkit'
+   * 
+   * // Basic duplicate removal
+   * const numbers = [1, 2, 2, 3, 3, 4]
+   * const uniqueNumbers = Data.isArrayUnique(numbers)
+   * console.log(uniqueNumbers) // [1, 2, 3, 4]
+   * 
+   * // Mixed types
+   * const mixed = ['a', 1, 'a', 2, 1, 'b']
+   * const uniqueMixed = Data.isArrayUnique(mixed)
+   * console.log(uniqueMixed) // ['a', 1, 2, 'b']
+   * 
+   * // Object arrays (shallow comparison)
+   * const users = [
+   *   { id: 1, name: 'Alice' },
+   *   { id: 2, name: 'Bob' },
+   *   { id: 1, name: 'Alice' }  // Different object reference, not filtered
+   * ]
+   * const uniqueUsers = Data.isArrayUnique(users)
+   * console.log(uniqueUsers.length) // 3 (objects compared by reference)
+   * 
+   * // Empty and single element arrays
+   * console.log(Data.isArrayUnique([])) // []
+   * console.log(Data.isArrayUnique(['single'])) // ['single']
+   * 
+   * // String array deduplication
+   * const tags = ['javascript', 'node', 'javascript', 'typescript', 'node']
+   * const uniqueTags = Data.isArrayUnique(tags)
+   * console.log(uniqueTags) // ['javascript', 'node', 'typescript']
+   * ```
+   */
   static isArrayUnique<T>(arr: Array<T>): Array<T>
 
   /** Get the intersection of two arrays */

package/src/types/File.d.ts

@@ -58,7 +58,7 @@ export default class File {
   static getFiles(glob: string | Array<string>): Promise<Array<FileObject>>
 
   /** List the contents of a directory */
-  static ls(directory: string): Promise<DirectoryListing>
+  static ls(directory: DirectoryObject): Promise<DirectoryListing>
 
   /** Read the content of a file */
   static readFile(fileObject: FileObject): Promise<string>
@@ -74,4 +74,4 @@ export default class File {
 
   /** Compute relative path between two file system objects */
   static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string
-}
+}

package/src/types/FileObject.d.ts

@@ -1,48 +1,281 @@
 // Implementation: ../lib/FileObject.js
-// Type definitions for FileObject
 
 import DirectoryObject from './DirectoryObject.js'
 
 /**
- * FileObject encapsulates metadata and operations for a file, including path
- * resolution and existence checks.
+ * FileObject encapsulates metadata and operations for a file, providing intelligent
+ * path resolution, metadata extraction, and file system operations. This class serves
+ * as the primary abstraction for file handling in the toolkit.
+ *
+ * FileObject automatically resolves relative paths, provides rich metadata without
+ * requiring file system access, and integrates seamlessly with DirectoryObject for
+ * hierarchical file operations. The class uses lazy evaluation for expensive operations
+ * and provides both synchronous metadata access and asynchronous file operations.
+ *
+ * Key features include automatic path normalization, extension parsing, URI generation,
+ * and parent directory integration. All path operations are cross-platform compatible.
+ *
+ * @example
+ * ```typescript
+ * import { FileObject } from '@gesslar/toolkit'
+ *
+ * // Basic file creation and metadata access
+ * const config = new FileObject('./config.json')
+ * console.log('Name:', config.name)           // 'config.json'
+ * console.log('Module:', config.module)       // 'config' (without extension)
+ * console.log('Extension:', config.extension) // '.json'
+ * console.log('Path:', config.path)           // '/absolute/path/to/config.json'
+ * console.log('URI:', config.uri)             // 'file:///absolute/path/to/config.json'
+ *
+ * // Working with different directory contexts
+ * const srcDir = new DirectoryObject('./src')
+ * const indexFile = new FileObject('index.js', srcDir)
+ * const componentFile = new FileObject('components/Button.tsx', './src')
+ *
+ * // File existence and operations
+ * if (await config.exists) {
+ *   console.log('Config file exists')
+ *   // File operations would go here using File utility
+ * } else {
+ *   console.log('Config file not found at:', config.path)
+ * }
+ *
+ * // Integration with parent directory
+ * console.log('Parent directory:', indexFile.directory.path)
+ * console.log('Is in src?', indexFile.directory.name === 'src')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with different file types and paths
+ * import { FileObject, DirectoryObject } from '@gesslar/toolkit'
+ *
+ * // Handle various file extensions and types
+ * const files = [
+ *   new FileObject('./docs/README.md'),
+ *   new FileObject('package.json'),
+ *   new FileObject('../lib/utils.ts'),
+ *   new FileObject('/absolute/path/to/script.sh')
+ * ]
+ *
+ * for (const fileItem of files) {
+ *   console.log(`${fileItem.module}${fileItem.extension} -> ${fileItem.path}`)
+ *   
+ *   // Type-based processing
+ *   switch (fileItem.extension) {
+ *     case '.json':
+ *       console.log('JSON file detected')
+ *       break
+ *     case '.md':
+ *       console.log('Markdown documentation')
+ *       break
+ *     case '.ts':
+ *     case '.js':
+ *       console.log('JavaScript/TypeScript source')
+ *       break
+ *     default:
+ *       console.log('Other file type')
+ *   }
+ * }
+ *
+ * // Error handling for invalid paths
+ * try {
+ *   const badFile = new FileObject('')  // Empty path
+ * } catch (error) {
+ *   console.error('Invalid file path:', error.message)
+ * }
+ * ```
+ *
+ * @remarks
+ * FileObject is designed for metadata extraction and path operations. For actual
+ * file I/O operations (reading, writing, copying), use the File utility class
+ * which accepts FileObject instances as parameters.
+ *
+ * The `exists` property returns a Promise and should always be awaited. Path
+ * resolution happens synchronously during construction, making metadata access
+ * immediate and efficient.
+ *
+ * When working with DirectoryObject parents, the FileObject automatically
+ * inherits the directory's resolved path, ensuring consistency in hierarchical
+ * file operations.
  */
 export default class FileObject {
   /**
-   * Create a new FileObject instance.
-   * @param fileName - The file path
-   * @param directory - The parent directory (object or string)
+   * Create a new FileObject instance with intelligent path resolution.
+   *
+   * Constructs a FileObject from the provided filename and optional directory context.
+   * Automatically resolves relative paths to absolute paths, normalizes path separators
+   * for cross-platform compatibility, and establishes parent-child relationships with
+   * DirectoryObject instances.
+   *
+   * @param fileName - The file path, which can be relative or absolute. Empty strings
+   *                  and invalid paths will throw an error during construction.
+   * @param directory - Optional parent directory context. Can be a DirectoryObject instance,
+   *                   a string path that will be converted to a DirectoryObject, or null
+   *                   to use the current working directory as the parent.
+   *
+   * @throws {Error} When fileName is empty or contains invalid path characters
+   * @throws {Error} When the directory parameter is invalid or cannot be resolved
+   *
+   * @example
+   * ```typescript
+   * // Simple file in current directory - most common usage
+   * const packageJson = new FileObject('package.json')
+   * const readme = new FileObject('./README.md')  // Equivalent to above
+   *
+   * // File with string directory path
+   * const configFile = new FileObject('app.config.js', './config')
+   * const componentFile = new FileObject('Button.tsx', './src/components')
+   *
+   * // File with DirectoryObject parent for hierarchical operations
+   * const srcDir = new DirectoryObject('./src')
+   * const indexFile = new FileObject('index.js', srcDir)
+   * const utilsFile = new FileObject('utils/helpers.js', srcDir)
+   *
+   * // Absolute paths (directory parameter ignored)
+   * const systemFile = new FileObject('/etc/hosts')
+   * const winFile = new FileObject('C:\\Windows\\System32\\drivers\\etc\\hosts')
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Complex directory structures and nested files
+   * const projectRoot = new DirectoryObject('./my-project')
+   * const srcDir = new DirectoryObject('src', projectRoot)
+   * 
+   * // Create files within nested directory structure  
+   * const mainApp = new FileObject('App.tsx', srcDir)
+   * const stylesheet = new FileObject('styles/main.css', srcDir)
+   * const testFile = new FileObject('__tests__/App.test.tsx', srcDir)
+   *
+   * console.log('Main app:', mainApp.path)     // /absolute/path/my-project/src/App.tsx
+   * console.log('Stylesheet:', stylesheet.path) // /absolute/path/my-project/src/styles/main.css
+   * console.log('Test file:', testFile.path)   // /absolute/path/my-project/src/__tests__/App.test.tsx
+   * 
+   * // All files share the same parent directory reference
+   * console.log('Same parent?', mainApp.directory === srcDir) // true
+   * ```
    */
   constructor(fileName: string, directory?: DirectoryObject | string | null)
 
-  /** User-supplied path */
+  /**
+   * The original user-supplied path string used during construction.
+   * 
+   * Preserves the exact path string passed to the constructor, including
+   * any relative path indicators (./, ../) or path separators. Useful
+   * for debugging, logging, or when you need to recreate the original
+   * user input.
+   *
+   * @example
+   * ```typescript
+   * const file1 = new FileObject('./config.json')
+   * const file2 = new FileObject('../package.json')
+   * 
+   * console.log(file1.supplied) // './config.json'
+   * console.log(file2.supplied) // '../package.json'
+   * console.log(file1.path)     // '/absolute/path/to/config.json'
+   * console.log(file2.path)     // '/absolute/path/package.json'
+   * ```
+   */
   readonly supplied: string
 
-  /** The absolute file path */
+  /**
+   * The fully resolved absolute file path with normalized separators.
+   * 
+   * Automatically resolved during construction using Node.js path utilities.
+   * Always uses forward slashes on Unix systems and backslashes on Windows.
+   * This is the canonical path that should be used for all file operations.
+   *
+   * @example
+   * ```typescript
+   * // Different inputs, same resolved path
+   * const file1 = new FileObject('./src/../config.json')  
+   * const file2 = new FileObject('config.json')
+   * 
+   * console.log(file1.path) // '/absolute/path/config.json'
+   * console.log(file2.path) // '/absolute/path/config.json'
+   * console.log(file1.path === file2.path) // true
+   * ```
+   */
   readonly path: string
 
-  /** The file URI */
+  /**
+   * The file URI representation following RFC 3986 standard.
+   * 
+   * Converts the absolute file path to a proper file:// URI scheme,
+   * handling URL encoding for special characters and proper formatting
+   * for cross-platform file URI access.
+   *
+   * @example
+   * ```typescript
+   * const file = new FileObject('./my project/config file.json')
+   * console.log(file.uri) 
+   * // 'file:///absolute/path/my%20project/config%20file.json'
+   * 
+   * // Can be used with URL constructor or file:// handlers
+   * const url = new URL(file.uri)
+   * console.log(url.pathname) // '/absolute/path/my project/config file.json'
+   * ```
+   */
   readonly uri: string
 
-  /** The file name */
+  /**
+   * The complete filename including extension.
+   * 
+   * Extracted from the resolved path using Node.js path utilities.
+   * Includes the file extension but excludes any directory components.
+   *
+   * @example
+   * ```typescript
+   * const jsFile = new FileObject('./src/components/Button.tsx')
+   * const configFile = new FileObject('../.env.production')
+   * 
+   * console.log(jsFile.name)    // 'Button.tsx'
+   * console.log(configFile.name) // '.env.production'
+   * ```
+   */
   readonly name: string
 
-  /** The file name without extension */
+  /**
+   * The filename without its extension, suitable for module identification.
+   * 
+   * Useful for generating module names, import statements, or when you need
+   * the base name without file type information. Handles complex extensions
+   * and dotfiles appropriately.
+   */
   readonly module: string
 
-  /** The file extension */
+  /**
+   * The file extension including the leading dot.
+   * 
+   * Extracted using Node.js path utilities, always includes the dot prefix.
+   * Returns an empty string for files without extensions. Handles multiple
+   * extensions by returning only the last one.
+   */
   readonly extension: string
 
-  /** Always true for files */
+  /** Type discriminator - always true for FileObject instances */
   readonly isFile: true
 
-  /** Always false for files */
+  /** Type discriminator - always false for FileObject instances */
   readonly isDirectory: false
 
-  /** The parent directory object */
+  /**
+   * The parent DirectoryObject containing this file.
+   * 
+   * Automatically created during FileObject construction based on the resolved
+   * file path. Provides access to parent directory operations and maintains
+   * the hierarchical relationship between files and directories.
+   */
   readonly directory: DirectoryObject
 
-  /** Whether the file exists (async) */
+  /**
+   * Promise that resolves to whether the file exists on the filesystem.
+   * 
+   * Performs an asynchronous filesystem check to determine file existence.
+   * The Promise will resolve to true if the file exists and is accessible,
+   * false otherwise. Always await this property before using the result.
+   */
   readonly exists: Promise<boolean>
 
   /** Returns a JSON representation of the FileObject */
@@ -57,4 +290,4 @@ export default class FileObject {
     isDirectory: boolean
     directory: string | null
   }
-}
+}

package/src/types/Glog.d.ts

@@ -9,16 +9,36 @@
  * The Glog class uses a proxy to enable both class-style and function-style
  * usage patterns, making it convenient for different coding preferences.
  *
+ * Log levels range from 0 (critical/always shown) to 5 (verbose debug).
+ * Messages with levels higher than the configured threshold are filtered out.
+ *
  * @example
  * ```typescript
- * // Set up logging configuration
+ * import { Glog } from '@gesslar/toolkit'
+ *
+ * // Configure logging once at startup
  * Glog.setLogLevel(3).setLogPrefix('[MyApp]')
  *
- * // Log messages with different levels
- * Glog(0, 'Critical error')  // Always shown
- * Glog(2, 'Debug info')      // Shown if logLevel >= 2
- * Glog('Simple message')     // Level 0 by default
+ * // Use as a function (most common)
+ * Glog(0, 'Critical error - system failure!')  // Always shown
+ * Glog(1, 'Warning: deprecated API used')      // Shown if level >= 1
+ * Glog(2, 'Info: processing user request')     // Shown if level >= 2
+ * Glog(3, 'Debug: cache hit for key:', key)    // Shown if level >= 3
+ * Glog('Simple message')                       // Level 0 by default
+ *
+ * // Method chaining for configuration
+ * Glog.setLogLevel(2)
+ *     .setLogPrefix('[API]')
+ *
+ * // Different contexts can use different prefixes
+ * const dbLogger = Glog.setLogPrefix('[DB]')
+ * const apiLogger = Glog.setLogPrefix('[API]')
  * ```
+ *
+ * @remarks
+ * The proxy implementation allows Glog to be called directly as a function
+ * while still providing static methods for configuration. This makes it
+ * extremely convenient for quick logging without ceremony.
  */
 interface GlogInterface {
   /**
@@ -57,7 +77,7 @@ interface GlogInterface {
 interface GlogCallable {
   /**
    * Log a message with optional level specification.
-   * 
+   *
    * @param args - Either (level: number, ...messages) or (...messages)
    */
   (...args: any[]): void
@@ -69,4 +89,4 @@ interface GlogCallable {
  */
 declare const Glog: GlogInterface & GlogCallable
 
-export default Glog
+export default Glog

package/src/types/Util.d.ts

@@ -10,15 +10,36 @@ declare class Util {
    *
    * @param text - The text to capitalize
    * @returns Text with first letter capitalized
+   *
+   * @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}>
 
@@ -37,6 +58,12 @@ declare class Util {
    *
    * @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
 
@@ -52,6 +79,23 @@ declare class Util {
    *
    * @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>
 
@@ -84,9 +128,11 @@ declare class Util {
 
   /**
    * 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().
+   * 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.
    *
@@ -94,6 +140,26 @@ declare class Util {
    * @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>
 
@@ -110,4 +176,4 @@ declare class Util {
   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>
 }
 
-export default Util
+export default Util