@offmain/workerkit 0.14.1 → 1.0.0

package/dist/types/tools/collect-results/collect-results.d.ts

@@ -0,0 +1,26 @@
+import { CollectOptions, CollectedResult, TypedSettledResults } from '../main-worker-factory/types';
+import { CollectResultsContext } from './types';
+/**
+ * Collects and merges the results of multiple worker execution promises.
+ *
+ * This function processes an array of settled promises from worker executions,
+ * segregates them into fulfilled and rejected results, and then reduces (merges)
+ * the fulfilled data into a single combined output.
+ *
+ * If a `reducer` is provided in `options`, it will be used to merge the shards.
+ * Otherwise, a default reducer that flats the array will be used.
+ *
+ * The merge operation is offloaded to an ephemeral Web Worker. The reducer worker
+ * receives a direct `MessagePort` to the MemoryWorker, so it fetches shard data
+ * directly without routing through the main thread.
+ *
+ * @template T - The expected type of the data returned from an individual worker.
+ * @template R - The expected type of the merged data.
+ *
+ * @param settled - The settled results (`Promise.allSettled` output) from the workers.
+ * @param options - Options for collection, such as a custom `reducer` function.
+ * @param context - Context object providing logger, worker tracking, termination checks, and MemoryWorkerProxy.
+ * @returns A promise resolving to the collected results containing the merged data, success count, failure count, and errors.
+ * @throws Will throw an error if the `MainWorkerFactory` context has been terminated prior to collection.
+ */
+export declare function collectWorkerResults<T = unknown, R = T extends (infer Item)[] ? Item[] : T[]>(settled: TypedSettledResults<T> | TypedSettledResults<unknown>, options: CollectOptions<T, R> | undefined, context: CollectResultsContext): Promise<CollectedResult<R>>;

package/dist/types/tools/collect-results/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './collect-results';

package/dist/types/tools/collect-results/types.d.ts

@@ -0,0 +1,10 @@
+import { ILogger } from '../logger';
+import { MemoryWorkerProxy } from '../memory-store';
+export interface CollectResultsContext {
+    isTerminated: () => boolean;
+    trackWorker: (worker: Worker) => Worker;
+    terminateWorker: (worker: Worker) => void;
+    logger: ILogger;
+    memoryWorkerProxy: MemoryWorkerProxy;
+    factoryToken: string;
+}

package/dist/types/tools/define-worker/define-worker.d.ts

@@ -0,0 +1,31 @@
+import { WorkerFunction } from '../main-worker-factory/types';
+/**
+ * Defines a function to run inside a native Web Worker script, establishing
+ * a standard messaging interface that provides full compatibility with `MainWorkerFactory`.
+ *
+ * This helper wraps your worker logic and automatically handles:
+ * - Standard single-execution runs (`foreman.run()`).
+ * - Worker-to-worker message passing in pipelines (`foreman.pipeline()`).
+ * - Dataset caching and persistent state (`foreman.runPersistent()`).
+ * - Extracting and passing transferable objects (like `ArrayBuffer` or `MessagePort`)
+ *   automatically to optimize memory usage without structured cloning overhead.
+ * - Catching synchronous and asynchronous errors and formatting them for the main thread.
+ *
+ * @typeParam TParams - The type of the payload/parameters sent to the worker.
+ *                      It typically includes a `data` field alongside optional configurations.
+ * @typeParam TResult - The return type of the worker function. Can be a promise or a direct value.
+ *
+ * @param workerFn - The function containing the worker's execution logic. It takes the parsed
+ *                   payload and returns the computed result (or a Promise resolving to it).
+ *
+ * @example
+ * // my-native-worker.ts
+ * import { defineWorker } from '@offmain/workerkit';
+ *
+ * // This worker function is compatible with standard runs and pipelines
+ * export default defineWorker(async ({ data, options }: { data: number[], options?: { mult?: number } }) => {
+ *   const mult = options?.mult ?? 2;
+ *   return data.map((x) => x * mult);
+ * });
+ */
+export declare function defineWorker<TParams = unknown, TResult = unknown>(workerFn: WorkerFunction<TParams, TResult | Promise<TResult>>): void;

package/dist/types/tools/define-worker/define-worker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tools/define-worker/index.d.ts

@@ -0,0 +1 @@
+export * from './define-worker';

package/dist/types/tools/define-worker-config/define-worker-config.d.ts

@@ -0,0 +1,23 @@
+import { WorkerConfig, WorkerFunction } from '../main-worker-factory/types';
+/**
+ * Helper to strictly type a single WorkerConfig.
+ * Especially useful for `createWorker` configs where the function type is not natively inferrable.
+ *
+ * @example
+ * defineWorkerConfig<typeof myFunc>({ name: 'myWorker', createWorker: () => new Worker(...) })
+ */
+export declare function defineWorkerConfig<TFunc extends WorkerFunction<any, any>>(): <const TConfig extends WorkerConfig<TFunc>>(config: TConfig) => TConfig & {
+    _typeHint: TFunc;
+};
+export declare function defineWorkerConfig<const TConfig extends WorkerConfig<any>>(config: TConfig): TConfig;
+/**
+ * Helper to strictly type an array of WorkerConfigs.
+ * Eliminates the need for `as const` while preserving the exact generics of each worker.
+ *
+ * @example
+ * const workers = defineWorkerConfigs(
+ *   defineWorkerConfig({ name: 'a', func: funcA }),
+ *   defineWorkerConfig<typeof b>()({ name: 'b', createWorker: () => new Worker(...) })
+ * );
+ */
+export declare function defineWorkerConfigs<T extends readonly WorkerConfig<any>[]>(...workers: T): T;

package/dist/types/tools/define-worker-config/index.d.ts

@@ -0,0 +1 @@
+export * from './define-worker-config';

package/dist/types/tools/extract-transferable/extract-transferable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Recursively extracts transferable objects from a given payload to optimize Web Worker messages.
+ *
+ * Transferable objects (like `ArrayBuffer`, `MessagePort`, `ImageBitmap`, `OffscreenCanvas`)
+ * are transferred by reference rather than being copied via Structured Clone, which significantly
+ * reduces memory usage and improves performance when sending large datasets.
+ *
+ * This utility traverses arrays, objects, and nested structures to collect all valid transferables.
+ * It also intelligently handles circular references by maintaining a `seen` Set.
+ *
+ * @param value - The input value to scan for transferable objects.
+ * @param seen - An optional Set used internally to track visited objects and prevent infinite recursion in cyclic structures.
+ * @returns An array containing all unique transferable objects found within the value.
+ */
+export declare function extractTransferable(value: unknown, seen?: Set<object>): Transferable[];

package/dist/types/tools/extract-transferable/extract-transferable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tools/extract-transferable/index.d.ts

@@ -0,0 +1 @@
+export * from './extract-transferable';

package/dist/types/tools/index.d.ts

@@ -1,3 +1,5 @@
 export * from './worker-factory';
 export * from './main-worker-factory';
+export * from './define-worker/index';
+export * from './define-worker-config';
 export * from './define-worker';

package/dist/types/tools/logger/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './logger';

package/dist/types/tools/logger/logger.d.ts

@@ -0,0 +1,21 @@
+import { LogLevel, ILogger } from './types';
+/**
+ * A lightweight logging utility designed for the Web Worker Manager.
+ *
+ * Supports various log levels to control the verbosity of the output:
+ * - `verbose`: Outputs debug, info, and error messages.
+ * - `info`: Outputs info and error messages (suppresses debug).
+ * - `error`: Outputs only error messages (suppresses debug and info).
+ * - `silent`: Suppresses all messages.
+ *
+ * All log messages are automatically prefixed with `[WorkerManager]` to
+ * distinguish them easily in the console.
+ */
+export declare class Logger implements ILogger {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    verbose(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}

package/dist/types/tools/logger/logger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tools/logger/types.d.ts

@@ -0,0 +1,6 @@
+export type LogLevel = 'verbose' | 'info' | 'error' | 'silent';
+export interface ILogger {
+    verbose(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}

package/dist/types/tools/main-worker-factory/main-worker-factory.d.ts

@@ -1,318 +1,161 @@
-import { CollectOptions, CollectedResult, PipelineStep, WorkerConfig, WorkerConfigMap, WorkerDataParam, WorkerFunction, WorkerReturnType, TypedSettledResults, MemoryStats } from './types.ts';
+import { CollectOptions, CollectedResult, WorkerConfig, WorkerConfigMap, WorkerDataParam, WorkerReturnType, TypedSettledResults, MemoryStats, RunWorkerOptions } from './types';
+import { Logger, LogLevel } from '../logger';
 /**
- * Recursively collects all Transferable objects from a value.
- * Transferable (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas)
- * are zero-copy — they are moved to the worker instead of cloned.
- */
-export declare function extractTransferable(value: unknown, seen?: Set<object>): Transferable[];
-/**
- * Central orchestrator for running typed Web Workers in parallel.
- *
- * `MainWorkerFactory` manages a registry of named worker configurations and
- * handles the full lifecycle of each worker: spawning, partitioning input
- * data across threads, retrying on failure, and collecting results.
- *
- * Also supports:
- * - **Pipelines** — chain workers via `MessageChannel` so intermediate data
- *   never crosses back to the main thread ({@link pipeline}).
- * - **Persistent workers** — keep a worker alive with a cached dataset,
- *   re-running it with different configs without re-sending the data
- *   ({@link runPersistent}, {@link release}).
+ * Main orchestration class for Web Worker management.
+ * Provides high-level APIs to configure, dispatch, and monitor workers,
+ * handling memory isolation, sharding, and concurrency.
  *
- * @typeParam TConfigs - A readonly tuple of {@link WorkerConfig} objects that
- *   defines the set of available workers and their typed signatures.
+ * Workers store their results directly into the dedicated `MemoryWorker` thread
+ * via a pre-allocated `MessagePort`. Only lightweight `__memory_ref__` tokens
+ * cross the main thread boundary. `runWorker` auto-collects shards and returns
+ * a `CollectedResult<R>` directly — no manual `collectResults` call needed.
  *
- * @example
- * const foreman = new MainWorkerFactory({
- *   workers: [
- *     { name: 'sum', role: 'compute', func: sumWorker, partition: true },
- *   ] as const,
- * });
- *
- * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3, 4] });
- * const { data } = await foreman.collectResults(settled);
+ * @typeParam TConfigs - A tuple of WorkerConfig configurations.
  */
-declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFunction<any, any>>[]> {
+declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<any>[]> {
     private readonly _workers;
     private readonly _threads;
-    private readonly _persistentWorkers;
     private readonly _activeWorkers;
     private readonly _memoryStore;
+    private readonly _memoryWorkerProxy;
+    private readonly _factoryToken;
     private _isTerminated;
+    private readonly _persistentManager;
+    private readonly _orchestrator;
+    /**
+     * The logger instance used by this factory.
+     */
+    readonly logger: Logger;
     /**
-     * Creates a new `MainWorkerFactory`.
+     * Initializes a new MainWorkerFactory.
      *
-     * @param options - Configuration object containing the `workers` registry.
+     * @param options - Configuration options.
+     * @param options.workers - The list of worker configurations.
+     * @param options.logLevel - Optional logging level (defaults to 'error').
      */
     constructor(options: {
         workers: TConfigs;
+        logLevel?: LogLevel;
     });
     /**
-     * Returns `true` if the factory has been terminated.
+     * Indicates whether the factory has been terminated.
      */
     get isTerminated(): boolean;
-    /**
-     * Registers an active worker instance for lifecycle tracking.
-     */
     private trackWorker;
-    /**
-     * Terminates a worker instance and removes it from tracking.
-     */
     private terminateWorker;
     /**
-     * Instantiates a {@link WorkerFactory} for the given worker configuration.
-     *
-     * @param config - The worker configuration containing `func` or `createWorker`.
-     * @returns A new `WorkerFactory` wrapping the worker.
-     */
-    private initWorker;
-    /**
-     * Splits an array into up to `numChunks` evenly-sized sub-arrays.
+     * Helper utility to partition an array into a specified number of chunks.
      *
-     * When the array length is not evenly divisible, the first `remainder`
-     * chunks receive one extra element so no data is lost.
-     *
-     * @param array     - The source array to partition.
-     * @param numChunks - Maximum number of chunks to produce.
-     *   Clamped to `array.length` so you never get empty chunks.
-     * @returns An array of sub-arrays. Returns `[]` when `array` is empty.
-     * @throws {Error} When `numChunks` is not a positive integer.
-     *
-     * @example
-     * partitionArray([1, 2, 3, 4, 5], 3);
-     * // → [[1, 2], [3, 4], [5]]
+     * @param array - The array to partition.
+     * @param numChunks - The desired number of chunks.
+     * @returns An array of array chunks.
+     * @template T - The type of elements in the array.
      */
     partitionArray<T>(array: T[], numChunks: number): T[][];
-    /**
-     * Looks up a registered worker configuration by name.
-     *
-     * @param name - The `name` field of the target {@link WorkerConfig}.
-     * @returns The matching config, or `undefined` if not found.
-     */
     private findWorkerByName;
     /**
-     * Runs a named worker against the provided data, distributing work across
-     * threads when the worker is configured for partitioning.
-     *
-     * When `config.partition` is `true` and `srcData` is an array with more
-     * than one element, the array is split into up to `maxConcurrency` (or
-     * `navigator.hardwareConcurrency`) shards and each shard is processed by
-     * a separate worker thread in parallel.
-     *
-     * All threads are awaited with `Promise.allSettled`, so a failure in one
-     * shard does not cancel the others. Use {@link collectResults} to merge
-     * the settled output.
+     * Dispatches a worker task with the given parameters.
      *
-     * @typeParam TName - The literal name of the worker to run (inferred from
-     *   the registered `workers` tuple).
+     * Workers store their results directly in the `MemoryWorker` thread — large data
+     * never touches the main thread heap. Results are auto-collected and merged in a
+     * dedicated reducer worker. Returns a `CollectedResult<R>` directly.
      *
-     * @param workerName - Name of the worker as declared in the `workers` config.
-     * @param params     - Object containing `srcData` (the payload) plus any
-     *   additional key/value pairs forwarded to the worker verbatim.
+     * Pass `autoCollect: false` in `rawParams` to skip auto-collection and receive
+     * the raw settled state (escape hatch for advanced custom reducers).
      *
-     * @returns A {@link TypedSettledResults} wrapping the settled promises from
-     *   all spawned worker threads.
-     *
-     * @example
-     * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3] });
+     * @param workerName - The name of the registered worker to execute.
+     * @param rawParams - The payload, options, and reducer for the worker.
+     * @returns A promise resolving to a CollectedResult with merged data and shard stats.
+     * @template TName - The name of the registered worker.
+     * @template T - The return type of the worker function.
+     * @template R - The merged return type after reducing shards.
      */
-    runWorker<TName extends keyof WorkerConfigMap<TConfigs> & string>(workerName: TName, rawParams: {
+    runWorker<TName extends keyof WorkerConfigMap<TConfigs> & string, T = WorkerReturnType<WorkerConfigMap<TConfigs>[TName]>, R = T extends (infer Item)[] ? Item[] : T[]>(workerName: TName, rawParams: {
         srcData?: WorkerDataParam<WorkerConfigMap<TConfigs>[TName]>;
         __memory_ref__?: string;
         deleteMemory?: boolean;
-    } & Record<string, unknown>): Promise<TypedSettledResults<WorkerReturnType<WorkerConfigMap<TConfigs>[TName]>>>;
+    } & RunWorkerOptions<T, R> & Record<string, unknown>): Promise<CollectedResult<R>>;
     /**
-     * Deletes a specific memory reference from the factory's memory store.
+     * Deletes a specific reference from the memory store and MemoryWorker.
      *
-     * @param ref - The `__memory_ref__` token string to delete.
-     * @returns A promise that resolves to `true` if deleted, `false` otherwise.
+     * @param ref - The memory reference ID to delete.
+     * @returns True if the reference existed and was deleted, false otherwise.
      */
     deleteMemory(ref: string): Promise<boolean>;
     /**
-     * Clears all stored dataset references from the factory's memory store.
+     * Clears all references from the memory store and MemoryWorker.
      */
     clearMemory(): Promise<void>;
     /**
-     * Saves the output of a completed worker execution into MemoryStore
-     * and modifies the returned settled results with a `__memory_ref__` token.
-     */
-    private storeWorkerMemoryResult;
-    /**
-     * Returns statistics about active memory references in the factory.
-     */
-    getMemoryStats(): Promise<MemoryStats>;
-    /**
-     * Builds the array of per-thread worker promises for a single `runWorker`
-     * call.
-     *
-     * When `isPartitioned` is `true`, each promise receives its own slice of
-     * `srcData`; otherwise every thread receives the full payload.
+     * Retrieves statistics about the currently stored memory handles.
      *
-     * @param config         - The resolved {@link WorkerConfig} for this run.
-     * @param workerName     - Name used in error/retry logging.
-     * @param srcWorkerData  - Combined `{ data, ...otherParams }` payload.
-     * @param threadCount    - Number of parallel worker threads to spawn.
-     * @param isPartitioned  - Whether `data` is a pre-split array of shards.
-     * @returns An array of promises, one per thread.
+     * @returns The MemoryStats containing count and active reference IDs.
      */
-    private createWorkerPromises;
-    /**
-     * Runs a single worker instance, retrying on failure up to `retryCount`
-     * times before re-throwing the last error.
-     *
-     * Each retry is logged to `console.error` with the remaining attempt count
-     * so failures are visible during development.
-     *
-     * @param instanceConfig - Full configuration for the worker instance.
-     * @param retryCount     - Remaining retry attempts (default `2`).
-     * @returns The successful {@link WorkerResult} once the worker resolves.
-     * @throws The last caught error when all retries are exhausted.
-     */
-    private runWorkerWithRetry;
+    getMemoryStats(): Promise<MemoryStats>;
     /**
-     * Spawns a single worker thread, posts the payload, and resolves or rejects
-     * based on the message the worker sends back.
-     *
-     * The worker is expected to respond with either:
-     * - `{ ok: true, data: T }` — success; resolves with a {@link WorkerResult}.
-     * - `{ ok: false, error: string }` — logical failure; rejects with a
-     *   structured error object.
-     *
-     * Any transferable objects found in the payload are moved (not copied) to
-     * the worker via the `transfer` list of `postMessage`.
+     * Collects and reduces the results from a `runWorker` execution.
      *
-     * The underlying `Worker` is always terminated after the message completes.
+     * @deprecated `runWorker` now auto-collects results. This method is kept as
+     * an escape hatch for advanced cases where `autoCollect: false` was passed to
+     * `runWorker`. In the common case, the return value of `runWorker` already
+     * contains the merged `CollectedResult`.
      *
-     * @param instanceConfig - Worker function, factory, name, shard index, and data.
-     * @returns A promise that resolves with the worker's result.
-     */
-    private initiateWorker;
-    /**
-     * Collects and merges the settled results from {@link runWorker} — off the
-     * main thread.
-     *
-     * Fulfilled shards are extracted and passed to the `reducer` function, which
-     * runs inside a dedicated inline worker so the merge itself never blocks the
-     * main thread. Failed shards are counted and their raw rejection reasons are
-     * preserved in `errors`.
-     *
-     * @typeParam T - The per-shard data type (inferred from `settled`).
-     * @typeParam R - The final merged output type (defaults to a flat array of
-     *   `T` items when no custom reducer is provided).
-     *
-     * @param settled  - The {@link TypedSettledResults} returned by `runWorker`.
-     * @param options  - Optional {@link CollectOptions}. Supply a `reducer` to
-     *   control how shards are merged. The reducer **must be self-contained**
-     *   (no closures over external variables) because it is serialised and run
-     *   inside a worker.
-     *
-     * @returns A {@link CollectedResult} with the merged `data`, counts of
-     *   `succeeded`/`failed` shards, and the raw `errors` array.
-     *
-     * @example
-     * // default: flat array of all shard data
-     * const { data, succeeded, failed } = await foreman.collectResults(res);
-     *
-     * @example
-     * // custom reducer: sum numbers across shards
-     * const { data } = await foreman.collectResults<number[], number>(res, {
-     *   reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0),
-     * });
+     * @param settled - The settled results from `runWorker` (when `autoCollect: false`).
+     * @param options - Options containing the reducer function.
+     * @returns A structured CollectedResult object.
+     * @template T - The type of the worker result data.
+     * @template R - The type of the merged result data.
      */
     collectResults<T = unknown, R = T extends (infer Item)[] ? Item[] : T[]>(settled: TypedSettledResults<T> | TypedSettledResults<unknown>, options?: CollectOptions<T, R>): Promise<CollectedResult<R>>;
     /**
-     * Runs a chain of workers where each step's output feeds directly into the
-     * next step — **without passing through the main thread**.
-     *
-     * Internally, adjacent workers are connected via `MessageChannel` ports.
-     * Only the final result is sent back to the main thread, minimising
-     * serialisation overhead for large intermediate data.
-     *
-     * @typeParam TResult - The expected type of the final pipeline output.
-     *   Defaults to `unknown` if not specified.
-     *
-     * @param steps - An ordered array of {@link PipelineStep} objects. The first
-     *   step must include `srcData`; subsequent steps receive the previous
-     *   step's output as `{ data: previousOutput, index: 0 }`.
+     * Executes a sequential pipeline of worker steps.
+     * Passes the output of one step as the input to the next step.
      *
-     * @returns A promise that resolves with the final step's output.
-     * @throws {Error} When `steps` is empty or a worker name is not found.
-     *
-     * @example
-     * const result = await foreman.pipeline<FilteredPost[]>([
-     *   { worker: 'fetchPosts', srcData: { url: '/api/posts' } },
-     *   { worker: 'transformPosts' },
-     *   { worker: 'filterPosts' },
-     * ]);
-     * console.log(result); // final transformed + filtered data
+     * @param steps - An array of PipelineStep configurations.
+     * @returns A CollectedResult containing the final pipeline output and shard stats,
+     *          consistent with the shape returned by `runWorker()`.
+     * @template TResult - The type of the pipeline result.
      */
-    pipeline<TResult = unknown>(steps: PipelineStep[]): Promise<TResult>;
+    pipeline<TResult = unknown>(steps: {
+        worker: keyof WorkerConfigMap<TConfigs> & string;
+        srcData?: unknown;
+        [key: string]: unknown;
+    }[]): Promise<CollectedResult<TResult>>;
     /**
-     * Runs a persistent worker that caches its dataset between calls.
-     *
-     * On the first call, provide both `dataset` and `config`. The worker stores
-     * the dataset in memory. On subsequent calls, only `config` is needed — the
-     * worker reuses the cached dataset and reprocesses it with the new config.
-     *
-     * The worker stays alive until {@link release} is called.
+     * Executes a task on a persistent (long-lived) worker thread.
+     * Useful for workers that maintain local state (like WebAssembly modules or databases)
+     * across multiple invocations.
      *
-     * @param workerName - Name of the registered worker.
-     * @param params - Object with optional `dataset` and required `config`.
-     * @returns The worker function's return value.
-     *
-     * @example
-     * // First call: send dataset + config
-     * const r1 = await factory.runPersistent('transform', {
-     *   dataset: largeArray,
-     *   config: { multiplier: 2 },
-     * });
-     *
-     * // Subsequent calls: only config, dataset is cached
-     * const r2 = await factory.runPersistent('transform', {
-     *   config: { multiplier: 5 },
-     * });
-     *
-     * // Update dataset when needed
-     * const r3 = await factory.runPersistent('transform', {
-     *   dataset: newArray,
-     *   config: { multiplier: 3 },
-     * });
-     *
-     * // Release when done
-     * factory.release('transform');
+     * @param workerName - The name of the persistent worker to run.
+     * @param params - The input data and configuration for the task.
+     * @returns The result from the persistent worker thread.
+     * @template TResult - The expected type of the result from the worker thread.
      */
-    runPersistent<TResult = unknown>(workerName: string, params: {
+    runPersistent<TName extends keyof WorkerConfigMap<TConfigs> & string, TResult = WorkerReturnType<WorkerConfigMap<TConfigs>[TName]>>(workerName: TName, params: {
         dataset?: unknown;
         config: unknown;
     }): Promise<TResult>;
     /**
-     * Releases a persistent worker, freeing its cached dataset and terminating
-     * the thread.
-     *
-     * After calling `release`, subsequent `runPersistent` calls for this worker
-     * will create a fresh instance (requiring a new dataset).
+     * Releases and terminates a persistent worker by name.
      *
-     * @param workerName - Name of the persistent worker to release.
+     * @param workerName - The name of the persistent worker to release.
      */
     release(workerName: string): void;
     /**
-     * Terminates the factory and all active and persistent worker instances.
-     *
-     * Calling `terminate()` immediately stops all running worker threads, releases
-     * cached persistent workers, and clears all internal worker state.
+     * Terminates all active worker threads, persistent workers, MemoryWorker, and clears the memory store.
+     * Marks this factory instance as terminated.
      */
     terminate(): void;
     /**
-     * Alias for {@link terminate}. Terminates the factory and all worker instances.
+     * Alias for {@link terminate}. Terminates all active resources.
      */
     destroy(): void;
     /**
-     * Resets the factory by terminating all active and persistent workers
-     * and resetting the factory state, allowing new worker instances to be initiated.
+     * Terminates all resources and resets the factory to an active state.
      */
     reset(): void;
     /**
-     * Alias for {@link reset}. Resets the factory state to initiate new worker instances.
+     * Alias for {@link reset}. Terminates and reactivates the factory.
      */
     restart(): void;
 }