forgeframe 1.0.0

package/dist/utils/cleanup.d.ts

@@ -0,0 +1,122 @@
+/**
+ * A function that performs cleanup, optionally returning a Promise for async cleanup.
+ * @internal
+ */
+type CleanupTask = () => void | Promise<void>;
+/**
+ * Manages cleanup tasks for proper resource disposal in a LIFO (Last-In-First-Out) order.
+ *
+ * @remarks
+ * The CleanupManager provides a centralized way to register and execute cleanup tasks,
+ * ensuring resources are properly disposed of when components or processes are torn down.
+ * Tasks are executed in reverse registration order (LIFO), which is appropriate for
+ * nested resource allocation patterns.
+ *
+ * @example
+ * ```typescript
+ * const cleanup = new CleanupManager();
+ *
+ * // Register cleanup tasks
+ * cleanup.register(() => console.log('First registered, last executed'));
+ * cleanup.register(() => console.log('Last registered, first executed'));
+ *
+ * // Execute all cleanup tasks
+ * await cleanup.cleanup();
+ * ```
+ *
+ * @public
+ */
+export declare class CleanupManager {
+    /**
+     * Array of registered cleanup tasks awaiting execution.
+     * @internal
+     */
+    private tasks;
+    /**
+     * Flag indicating whether cleanup has already been performed.
+     * @internal
+     */
+    private cleaned;
+    /**
+     * Registers a cleanup task to be executed when {@link cleanup} is called.
+     *
+     * @param task - The cleanup function to register
+     *
+     * @remarks
+     * If cleanup has already been performed, the task is executed immediately
+     * rather than being registered. This ensures late-registered tasks are
+     * still handled appropriately.
+     *
+     * @example
+     * ```typescript
+     * cleanup.register(() => {
+     *   eventEmitter.removeAllListeners();
+     * });
+     *
+     * cleanup.register(async () => {
+     *   await database.close();
+     * });
+     * ```
+     *
+     * @public
+     */
+    register(task: CleanupTask): void;
+    /**
+     * Executes all registered cleanup tasks in LIFO order.
+     *
+     * @returns A Promise that resolves when all cleanup tasks have completed
+     *
+     * @remarks
+     * Tasks are executed in reverse order of registration (LIFO pattern).
+     * Each task is awaited individually, and errors are caught and logged
+     * to prevent one failing task from blocking subsequent cleanup operations.
+     * Calling this method multiple times has no effect after the first call.
+     *
+     * @example
+     * ```typescript
+     * // In a component's destroy lifecycle
+     * async destroy() {
+     *   await this.cleanupManager.cleanup();
+     * }
+     * ```
+     *
+     * @public
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Checks whether cleanup has already been performed.
+     *
+     * @returns `true` if {@link cleanup} has been called, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * if (!cleanupManager.isCleaned()) {
+     *   // Safe to register more tasks
+     *   cleanupManager.register(myTask);
+     * }
+     * ```
+     *
+     * @public
+     */
+    isCleaned(): boolean;
+    /**
+     * Resets the manager to its initial state, allowing it to be reused.
+     *
+     * @remarks
+     * This method clears all registered tasks and resets the cleaned flag.
+     * It is primarily intended for testing scenarios or cases where the
+     * manager needs to be reused after cleanup.
+     *
+     * @example
+     * ```typescript
+     * // In a test teardown
+     * afterEach(() => {
+     *   cleanupManager.reset();
+     * });
+     * ```
+     *
+     * @public
+     */
+    reset(): void;
+}
+export {};

package/dist/utils/dimension.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @packageDocumentation
+ * Dimension normalization utilities for consistent handling of width/height values.
+ */
+/**
+ * Normalizes a dimension value to a CSS-compatible string.
+ *
+ * @remarks
+ * Numeric values are converted to pixel strings (e.g., `400` becomes `'400px'`).
+ * String values are returned as-is, allowing for units like `'100%'` or `'auto'`.
+ * Undefined values return the fallback (defaults to `'100%'`).
+ *
+ * @param value - The dimension value (number for pixels, string with units, or undefined)
+ * @param fallback - The value to use if value is undefined (default: '100%')
+ * @returns A CSS-compatible dimension string
+ *
+ * @example
+ * ```typescript
+ * normalizeDimensionToCSS(400);        // '400px'
+ * normalizeDimensionToCSS('100%');     // '100%'
+ * normalizeDimensionToCSS(undefined);  // '100%'
+ * normalizeDimensionToCSS(undefined, 'auto'); // 'auto'
+ * ```
+ *
+ * @public
+ */
+export declare function normalizeDimensionToCSS(value: string | number | undefined, fallback?: string): string;
+/**
+ * Normalizes a dimension value to a numeric pixel value.
+ *
+ * @remarks
+ * This function is useful for popup window APIs that require numeric values.
+ * String values are parsed as integers (e.g., `'500px'` becomes `500`).
+ * Undefined values or unparseable strings return the fallback.
+ *
+ * @param value - The dimension value to normalize
+ * @param fallback - The fallback value to use if normalization fails
+ * @returns A numeric pixel value
+ *
+ * @example
+ * ```typescript
+ * normalizeDimensionToNumber(400, 500);      // 400
+ * normalizeDimensionToNumber('500px', 500);  // 500
+ * normalizeDimensionToNumber('100%', 500);   // 500 (cannot parse percentage)
+ * normalizeDimensionToNumber(undefined, 500); // 500
+ * ```
+ *
+ * @public
+ */
+export declare function normalizeDimensionToNumber(value: string | number | undefined, fallback: number): number;

package/dist/utils/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Utility functions and classes for ForgeFrame.
+ *
+ * @remarks
+ * This module provides common utilities used throughout the ForgeFrame framework:
+ * - **UID generation**: Functions for creating unique identifiers
+ * - **Cleanup management**: A class for managing resource disposal
+ * - **Promise utilities**: Helpers for working with async operations
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   generateUID,
+ *   CleanupManager,
+ *   createDeferred,
+ *   delay
+ * } from './utils';
+ *
+ * // Generate a unique ID
+ * const id = generateUID();
+ *
+ * // Manage cleanup tasks
+ * const cleanup = new CleanupManager();
+ * cleanup.register(() => console.log('Cleaning up...'));
+ *
+ * // Work with deferred promises
+ * const deferred = createDeferred<string>();
+ * setTimeout(() => deferred.resolve('done'), 1000);
+ * await deferred.promise;
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { generateUID, generateShortUID, isValidUID } from './uid';
+export { CleanupManager } from './cleanup';
+export { createDeferred, promiseTimeout, waitFor, delay, tryCatch, type Deferred, } from './promise';
+export { normalizeDimensionToCSS, normalizeDimensionToNumber } from './dimension';

package/dist/utils/promise.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Represents a deferred promise with externally accessible resolve and reject functions.
+ *
+ * @typeParam T - The type of value the promise will resolve to
+ *
+ * @remarks
+ * This interface is useful when you need to create a promise that will be
+ * resolved or rejected from outside the promise executor function.
+ *
+ * @public
+ */
+export interface Deferred<T> {
+    /** The underlying promise that can be awaited */
+    promise: Promise<T>;
+    /** Function to resolve the promise with a value */
+    resolve: (value: T) => void;
+    /** Function to reject the promise with an error */
+    reject: (error: Error) => void;
+}
+/**
+ * Creates a deferred promise with externally accessible resolve and reject functions.
+ *
+ * @typeParam T - The type of value the promise will resolve to
+ * @returns A {@link Deferred} object containing the promise and its control functions
+ *
+ * @remarks
+ * This utility is helpful when the resolution of a promise depends on external
+ * events or callbacks that occur outside the promise executor scope.
+ *
+ * @example
+ * ```typescript
+ * const deferred = createDeferred<string>();
+ *
+ * // Pass the promise to something that will await it
+ * someAsyncOperation(deferred.promise);
+ *
+ * // Later, resolve from elsewhere
+ * deferred.resolve('Success!');
+ * ```
+ *
+ * @public
+ */
+export declare function createDeferred<T>(): Deferred<T>;
+/**
+ * Wraps a promise with a timeout, rejecting if the timeout is exceeded.
+ *
+ * @typeParam T - The type of value the promise will resolve to
+ * @param promise - The promise to wrap with a timeout
+ * @param ms - The timeout duration in milliseconds
+ * @param message - Custom error message for timeout (defaults to 'Operation timed out')
+ * @returns A new promise that resolves with the original value or rejects on timeout
+ *
+ * @throws Error when the timeout is exceeded before the promise resolves
+ *
+ * @remarks
+ * This is useful for adding time constraints to operations that might hang
+ * or take unexpectedly long. The original promise continues executing even
+ * after timeout, but its result is ignored.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await promiseTimeout(
+ *     fetchData(),
+ *     5000,
+ *     'Data fetch timed out'
+ *   );
+ * } catch (error) {
+ *   console.error(error.message); // "Data fetch timed out (5000ms)"
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function promiseTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+/**
+ * Waits for a condition function to return true, polling at a specified interval.
+ *
+ * @param condition - A function that returns `true` when the wait condition is met
+ * @param options - Configuration options for the wait behavior
+ * @param options.timeout - Maximum time to wait in milliseconds (defaults to 5000)
+ * @param options.interval - Polling interval in milliseconds (defaults to 50)
+ * @returns A promise that resolves when the condition becomes true
+ *
+ * @throws Error when the timeout is exceeded before the condition becomes true
+ *
+ * @remarks
+ * This utility is particularly useful in testing scenarios or when waiting
+ * for DOM elements, state changes, or other asynchronous conditions.
+ *
+ * @example
+ * ```typescript
+ * // Wait for an element to appear
+ * await waitFor(
+ *   () => document.querySelector('.modal') !== null,
+ *   { timeout: 3000, interval: 100 }
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function waitFor(condition: () => boolean, options?: {
+    timeout?: number;
+    interval?: number;
+}): Promise<void>;
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * @param ms - The delay duration in milliseconds
+ * @returns A promise that resolves after the specified delay
+ *
+ * @remarks
+ * This is a simple utility for introducing delays in async code,
+ * useful for throttling, debouncing, or creating artificial pauses.
+ *
+ * @example
+ * ```typescript
+ * console.log('Starting...');
+ * await delay(1000);
+ * console.log('One second later');
+ * ```
+ *
+ * @public
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Executes a function and returns its result, returning a fallback value if an error occurs.
+ *
+ * @typeParam T - The type of value returned by the function and fallback
+ * @param fn - The function to execute (can be sync or async)
+ * @param fallback - The value to return if the function throws an error
+ * @returns A promise that resolves to either the function result or the fallback value
+ *
+ * @remarks
+ * This utility provides a concise way to handle errors without explicit try-catch blocks,
+ * particularly useful when a sensible default value exists for error cases.
+ *
+ * @example
+ * ```typescript
+ * // Safely parse JSON with a fallback
+ * const config = await tryCatch(
+ *   () => JSON.parse(rawConfig),
+ *   { defaultSetting: true }
+ * );
+ *
+ * // Safely fetch with a fallback
+ * const data = await tryCatch(
+ *   async () => await fetchData(),
+ *   []
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function tryCatch<T>(fn: () => T | Promise<T>, fallback: T): Promise<T>;

package/dist/utils/uid.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Generates a unique identifier by combining a timestamp with a random string.
+ *
+ * @returns A unique identifier string in the format `{timestamp}_{random}`
+ *
+ * @remarks
+ * The UID is composed of two parts separated by an underscore:
+ * - A base-36 encoded timestamp from `Date.now()`
+ * - A random base-36 string of up to 9 characters
+ *
+ * This combination provides both temporal ordering and collision resistance.
+ *
+ * @example
+ * ```typescript
+ * const id = generateUID();
+ * // Returns something like: "lxyz123_abc456def"
+ * ```
+ *
+ * @public
+ */
+export declare function generateUID(): string;
+/**
+ * Generates a short unique identifier suitable for function references and internal use.
+ *
+ * @returns A short random string of up to 9 characters
+ *
+ * @remarks
+ * Unlike {@link generateUID}, this function does not include a timestamp component,
+ * making it shorter but without temporal ordering guarantees. Use this for cases
+ * where a compact identifier is preferred over strict uniqueness.
+ *
+ * @example
+ * ```typescript
+ * const shortId = generateShortUID();
+ * // Returns something like: "abc456def"
+ * ```
+ *
+ * @public
+ */
+export declare function generateShortUID(): string;
+/**
+ * Validates whether a string conforms to the ForgeFrame UID format.
+ *
+ * @param uid - The string to validate
+ * @returns `true` if the string matches the UID format, `false` otherwise
+ *
+ * @remarks
+ * A valid ForgeFrame UID consists of two lowercase alphanumeric segments
+ * separated by an underscore (e.g., `lxyz123_abc456def`).
+ *
+ * @example
+ * ```typescript
+ * isValidUID('abc123_def456'); // true
+ * isValidUID('invalid');       // false
+ * isValidUID('ABC_123');       // false (uppercase not allowed)
+ * ```
+ *
+ * @public
+ */
+export declare function isValidUID(uid: string): boolean;