@offmain/workerkit 0.14.0 → 1.0.0

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

@@ -1,4 +1,5 @@
 import { WorkerFactory } from '../worker-factory';
+import { LogLevel } from '../logger';
 /** A unique string identifier for a worker, matching its `name` field. */
 export type WorkerName = string;
 /** A descriptive label for the worker's role (e.g. `'compute'`, `'io'`). */
@@ -12,7 +13,7 @@ export type WorkerRole = string;
  * @typeParam TParams - The type of the message payload sent to the worker.
  * @typeParam TResult - The type of the value the worker posts back.
  */
-export type WorkerFunction<TParams = unknown, TResult = unknown> = (params: TParams) => TResult;
+export type WorkerFunction<TParams = any, TResult = any> = (params: TParams) => TResult;
 /**
  * Configuration object that registers a named worker with the factory.
  *
@@ -31,6 +32,11 @@ export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
      * while allowing `MainWorkerFactory` to scale concurrency and manage worker thread lifecycles.
      */
     createWorker?: () => Worker;
+    /**
+     * Optional compile-time type hint for workers that only use `createWorker`.
+     * Will not exist or be used at runtime.
+     */
+    _typeHint?: TFunc;
     /**
      * Maximum number of parallel threads to spawn for this worker.
      * Defaults to `navigator.hardwareConcurrency` when omitted.
@@ -52,6 +58,23 @@ export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
      * If any dependency fails, this worker will not run.
      */
     dependencies?: Array<() => void>;
+    /**
+     * When `true`, the worker's output is saved in the isolated `MemoryWorker`
+     * and returned alongside a `__memory_ref__` token.
+     */
+    memory?: boolean;
+    /**
+     * When `true`, the worker's output is saved in the isolated `MemoryWorker`
+     * and **only** the `__memory_ref__` token is returned (0 bytes data transferred back to main thread).
+     */
+    memoryOnly?: boolean;
+}
+/** Statistics about stored memory handles in MemoryWorker. */
+export interface MemoryStats {
+    /** Total number of active memory references. */
+    count: number;
+    /** Array of active reference IDs. */
+    refs: string[];
 }
 /**
  * Derives a `name → function` map from a readonly tuple of
@@ -62,9 +85,13 @@ export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
  *
  * @typeParam T - The readonly tuple of `WorkerConfig` values.
  */
-export type WorkerConfigMap<T extends readonly WorkerConfig<WorkerFunction<any, any>>[]> = {
+export type WorkerConfigMap<T extends readonly WorkerConfig<any>[]> = {
     [K in T[number]['name']]: NonNullable<Extract<T[number], {
         name: K;
+    }>['_typeHint']> extends WorkerFunction ? NonNullable<Extract<T[number], {
+        name: K;
+    }>['_typeHint']> : NonNullable<Extract<T[number], {
+        name: K;
     }>['func']> extends WorkerFunction ? NonNullable<Extract<T[number], {
         name: K;
     }>['func']> : WorkerFunction;
@@ -91,6 +118,7 @@ export type WorkerReturnType<TFunc extends WorkerFunction> = TFunc extends Worke
 /** Options passed to the `MainWorkerFactory` constructor. */
 export interface MainWorkerFactoryOptions {
     workers: WorkerConfig[];
+    logLevel?: LogLevel;
 }
 /** Internal representation of a worker config that has been instantiated. */
 export interface MainWorkerFactoryWorker extends WorkerConfig {
@@ -131,6 +159,10 @@ export interface WorkerResult {
 /**
  * Typed wrapper around the settled results from `runWorker`.
  * Carries `T` (the worker's return type) so `collectResults` can infer it.
+ *
+ * @internal Not part of the public API. `runWorker` now returns `CollectedResult<R>` directly.
+ * @deprecated Use the return value of `runWorker` directly.
+ * @template T - The worker's return type.
  */
 export declare class TypedSettledResults<T> {
     readonly results: PromiseSettledResult<WorkerResult>[];
@@ -138,7 +170,11 @@ export declare class TypedSettledResults<T> {
     /** Never actually exists at runtime — used only for type inference. */
     readonly __type: T;
 }
-/** Options for collectResults */
+/**
+ * Options passed to `collectResults` (kept for the opt-out escape hatch).
+ * @template T - The type of a single shard result.
+ * @template R - The type of the merged result.
+ */
 export interface CollectOptions<T, R = T[]> {
     /**
      * Custom reducer applied to the array of fulfilled shard values.
@@ -151,7 +187,32 @@ export interface CollectOptions<T, R = T[]> {
      */
     reducer?: (shards: T[]) => R;
 }
-/** Result returned by collectResults */
+/**
+ * Options that can be passed alongside `srcData` in `runWorker` to control
+ * auto-collection behaviour.
+ * @template T - The type of a single shard result.
+ * @template R - The type of the merged result.
+ */
+export interface RunWorkerOptions<T = unknown, R = T[]> {
+    /**
+     * Custom reducer to merge shard results.
+     * Must be a self-contained function (no closures over external variables)
+     * since it is serialised via `.toString()` and run inside a worker.
+     * Defaults to `(shards) => shards.flat()`.
+     */
+    reducer?: (shards: T[]) => R;
+    /**
+     * Set to `false` to skip auto-collection and receive a `TypedSettledResults`
+     * object instead of `CollectedResult`. Useful for advanced scenarios where
+     * you need to call `collectResults` with custom options manually.
+     * @default true
+     */
+    autoCollect?: boolean;
+}
+/**
+ * Result returned by collectResults
+ * @template R - The type of the merged data.
+ */
 export interface CollectedResult<R> {
     /** The merged output produced by the reducer */
     data: R;
@@ -161,6 +222,12 @@ export interface CollectedResult<R> {
     failed: number;
     /** Raw rejected results, if any */
     errors: PromiseRejectedResult[];
+    /**
+     * Present when the worker config has `memory: true`.
+     * The ref under which the merged result is stored in MemoryWorker,
+     * allowing it to be passed to subsequent workers without re-serializing.
+     */
+    __memory_ref__?: string;
 }
 /** A single step in a worker pipeline */
 export interface PipelineStep {

package/dist/types/tools/memory-store/index.d.ts

@@ -0,0 +1,3 @@
+export * from './memory-store';
+export * from './memory-worker';
+export * from './memory-worker-proxy';

package/dist/types/tools/memory-store/memory-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MemoryStore is a lightweight ref registry that lives on the main thread.
+ *
+ * It tracks **which memory refs exist** (and optional metadata) but does NOT
+ * store actual data. All large datasets are held inside the dedicated
+ * `MemoryWorker` thread, keeping the main thread heap free.
+ *
+ * Each ref is indexed by a cryptographically generated UUID to ensure
+ * collision-free, secure handle management.
+ */
+export declare class MemoryStore {
+    private readonly store;
+    /**
+     * Registers a ref in the registry.
+     *
+     * @param ref - The memory reference ID (generated by MemoryWorkerProxy).
+     * @param metadata - Optional metadata (size hint, type tag, etc.).
+     */
+    register(ref: string, metadata?: RefMetadata): void;
+    /**
+     * Checks if a reference ID is registered.
+     * @param refId - The reference ID to check.
+     */
+    has(refId: string): boolean;
+    /**
+     * Unregisters a reference ID.
+     *
+     * @param refId - The reference ID to unregister.
+     * @returns `true` if the key existed and was removed, `false` otherwise.
+     */
+    delete(refId: string): boolean;
+    /**
+     * Clears all registered references.
+     */
+    clear(): void;
+    /**
+     * Returns statistics about current registered handles.
+     */
+    stats(): {
+        count: number;
+        refs: string[];
+    };
+}
+/** Lightweight metadata stored alongside a ref in the main-thread registry. */
+export interface RefMetadata {
+    /** Optional size hint in bytes for diagnostics. */
+    size?: number;
+    /** Optional type tag (e.g. 'array', 'object'). */
+    type?: string;
+}

package/dist/types/tools/memory-store/memory-store.test.d.ts

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

package/dist/types/tools/memory-store/memory-worker-proxy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * MemoryWorkerProxy provides a Promise-based API for communicating with the
+ * dedicated `MemoryWorker` thread.
+ *
+ * It manages the worker's lifecycle, authenticates all requests with the
+ * factory token, and exposes high-level methods for storing, retrieving,
+ * and deleting datasets held off the main thread.
+ *
+ * The key method is `allocateWorkerPort()`, which creates a `MessageChannel`
+ * and registers one port with the MemoryWorker so that a computing worker
+ * or reducer worker can read/write data **directly** — without routing
+ * through the main thread.
+ */
+export declare class MemoryWorkerProxy {
+    private readonly worker;
+    private readonly factoryToken;
+    private readonly pending;
+    constructor(factoryToken: string);
+    private send;
+    /**
+     * Stores a dataset in the MemoryWorker.
+     *
+     * @param data - The dataset to store.
+     * @param ref - Optional ref ID; if omitted, MemoryWorker generates one.
+     * @returns The ref ID under which the data is stored.
+     */
+    set(data: unknown, ref?: string): Promise<string>;
+    /**
+     * Retrieves a dataset from the MemoryWorker by ref ID.
+     *
+     * @param ref - The ref ID to retrieve.
+     * @returns The stored dataset, or `undefined` if not found.
+     */
+    get(ref: string): Promise<unknown>;
+    /**
+     * Checks if a ref ID exists in the MemoryWorker.
+     * @param ref - The ref ID to check.
+     */
+    has(ref: string): Promise<boolean>;
+    /**
+     * Deletes a ref from the MemoryWorker.
+     *
+     * @param ref - The ref ID to delete.
+     * @returns `true` if the ref existed and was deleted.
+     */
+    delete(ref: string): Promise<boolean>;
+    /**
+     * Clears all data from the MemoryWorker.
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns statistics about data held in the MemoryWorker.
+     */
+    stats(): Promise<{
+        count: number;
+        refs: string[];
+    }>;
+    /**
+     * Allocates a direct `MessagePort` to the MemoryWorker for a computing or
+     * reducer worker.
+     *
+     * Creates a `MessageChannel` and registers one port with MemoryWorker via
+     * `REGISTER_PORT`. The other port (the "worker-side" port) is returned as a
+     * `Transferable` — it should be passed to the target worker via
+     * `postMessage(..., [workerPort])` so the worker can communicate with
+     * MemoryWorker directly without routing through the main thread.
+     *
+     * @returns The worker-side `MessagePort` ready to be transferred.
+     */
+    allocateWorkerPort(): Promise<MessagePort>;
+    /**
+     * Terminates the MemoryWorker thread and clears all pending requests.
+     */
+    terminate(): void;
+}

package/dist/types/tools/memory-store/memory-worker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Script source for the dedicated MemoryWorker thread.
+ *
+ * Runs inside an isolated Web Worker thread and maintains the MemoryStore.
+ * Handshakes and authenticates all incoming MessagePort requests using a secret `factoryToken`.
+ *
+ * Supports direct worker-to-MemoryWorker communication via `REGISTER_PORT`:
+ * A `MessagePort` can be registered so that computing workers and reducer workers
+ * can read/write data directly without routing through the main thread.
+ */
+export declare const memoryWorkerScript = "\nconst store = new Map();\n\nfunction handleMessage(msg, replyTarget) {\n  if (!msg || typeof msg !== 'object') return;\n\n  const { action, factoryToken, expectedToken, ref, data, id } = msg;\n\n  // Initial handshake to set expected token if needed\n  if (action === 'INIT_TOKEN') {\n    self.__expectedToken = expectedToken;\n    replyTarget.postMessage({ ok: true, action: 'INIT_TOKEN_ACK' });\n    return;\n  }\n\n  // Validate factory token\n  if (self.__expectedToken && factoryToken !== self.__expectedToken) {\n    replyTarget.postMessage({ ok: false, error: 'Unauthorized: invalid factory token', id });\n    return;\n  }\n\n  try {\n    switch (action) {\n      case 'SET': {\n        const refId = ref || ('mem_' + crypto.randomUUID());\n        store.set(refId, data);\n        replyTarget.postMessage({ ok: true, ref: refId, id });\n        break;\n      }\n      case 'GET': {\n        const resultData = store.get(ref);\n        const exists = store.has(ref);\n        replyTarget.postMessage({ ok: true, exists, data: resultData, ref, id });\n        break;\n      }\n      case 'DELETE': {\n        const deleted = store.delete(ref);\n        replyTarget.postMessage({ ok: true, deleted, ref, id });\n        break;\n      }\n      case 'CLEAR': {\n        store.clear();\n        replyTarget.postMessage({ ok: true, action: 'CLEAR_ACK', id });\n        break;\n      }\n      case 'STATS': {\n        replyTarget.postMessage({\n          ok: true,\n          stats: {\n            count: store.size,\n            refs: Array.from(store.keys()),\n          },\n          id,\n        });\n        break;\n      }\n      case 'REGISTER_PORT': {\n        // Register a MessagePort from a computing or reducer worker.\n        // All messages arriving on this port are handled with the same\n        // store operations, enabling direct worker-to-MemoryWorker data flow.\n        const port = msg.port;\n        if (!port) {\n          replyTarget.postMessage({ ok: false, error: 'REGISTER_PORT requires a port', id });\n          break;\n        }\n        port.onmessage = (event) => handleMessage(event.data, port);\n        port.start();\n        replyTarget.postMessage({ ok: true, action: 'PORT_REGISTERED', id });\n        break;\n      }\n      default:\n        replyTarget.postMessage({ ok: false, error: 'Unknown action: ' + action, id });\n    }\n  } catch (err) {\n    replyTarget.postMessage({\n      ok: false,\n      error: err instanceof Error ? err.message : String(err),\n      id,\n    });\n  }\n}\n\nself.addEventListener('message', (event) => {\n  // Handle REGISTER_PORT specially \u2014 the port itself is a Transferable in event.ports\n  if (event.data && event.data.action === 'REGISTER_PORT') {\n    const port = event.ports[0] ?? event.data.port;\n    const msg = { ...event.data, port };\n    handleMessage(msg, self);\n    return;\n  }\n  handleMessage(event.data, self);\n});\n";

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

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

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

@@ -0,0 +1,21 @@
+import { WorkerConfig, WorkerInstanceConfig, WorkerResult } from '../main-worker-factory/types';
+import { OrchestratorContext } from './types';
+/**
+ * WorkerOrchestrator manages the lifecycle and execution of dynamically spawned Web Workers.
+ *
+ * Responsibilities:
+ * - Spawns requested worker instances based on a provided configuration.
+ * - Slices and partitions data payloads (if `isPartitioned` is true) to distribute work.
+ * - Handles auto-retries for failing workers without bubbling up errors prematurely.
+ * - Integrates with the context to track active workers and safely clean them up upon completion.
+ * - Standardizes the result wrapping into structured `WorkerResult` objects.
+ */
+export declare class WorkerOrchestrator {
+    private context;
+    constructor(context: OrchestratorContext);
+    createWorkerPromises(config: WorkerConfig, workerName: string, srcWorkerData: {
+        data: unknown;
+    } & Record<string, unknown>, threadCount: number, isPartitioned: boolean): Promise<WorkerResult>[];
+    runWorkerWithRetry(instanceConfig: WorkerInstanceConfig, retryCount?: number): Promise<WorkerResult>;
+    private initiateWorker;
+}

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

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

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

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

package/dist/types/tools/partition-array/index.d.ts

@@ -0,0 +1 @@
+export * from './partition-array';

package/dist/types/tools/partition-array/partition-array.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Partitions a flat array into a specified number of smaller chunks.
+ *
+ * This is used to distribute a large dataset across multiple worker threads.
+ * If the array length is not perfectly divisible by `numChunks`, the remainder
+ * elements are distributed evenly across the first few chunks (1 extra element per chunk).
+ *
+ * @typeParam T - The type of elements within the array.
+ * @param array - The array to be partitioned.
+ * @param numChunks - The desired number of sub-arrays (chunks).
+ * @returns An array containing the partitioned sub-arrays. If the input array is empty, returns `[]`.
+ * @throws If `numChunks` is less than or equal to 0.
+ */
+export declare function partitionArray<T>(array: T[], numChunks: number): T[][];

package/dist/types/tools/partition-array/partition-array.test.d.ts

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

package/dist/types/tools/persistent-manager/index.d.ts

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

package/dist/types/tools/persistent-manager/persistent-manager.d.ts

@@ -0,0 +1,25 @@
+import { PersistentManagerContext } from './types';
+/**
+ * PersistentWorkerManager handles Web Workers that remain alive across multiple executions.
+ *
+ * Unlike transient workers which are terminated after a single run, persistent workers
+ * maintain their internal state and memory context. This makes them ideal for tasks that
+ * require heavy initialization, database connections, or large datasets.
+ *
+ * Responsibilities:
+ * - Lazily instantiates persistent workers on first use and caches their instances.
+ * - Routes execution requests (`type: 'run'`) to the correct running worker instance.
+ * - Provides memory safety by explicitly releasing specific workers or all workers
+ *   (`terminateAll`) when they are no longer needed.
+ */
+export declare class PersistentWorkerManager {
+    private context;
+    private readonly _persistentWorkers;
+    constructor(context: PersistentManagerContext);
+    runPersistent<TResult = unknown>(workerName: string, params: {
+        dataset?: unknown;
+        config: unknown;
+    }): Promise<TResult>;
+    release(workerName: string): void;
+    terminateAll(): void;
+}

package/dist/types/tools/persistent-manager/persistent-manager.test.d.ts

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

package/dist/types/tools/persistent-manager/types.d.ts

@@ -0,0 +1,9 @@
+import { WorkerConfig } from '../main-worker-factory/types';
+import { ILogger } from '../logger';
+export interface PersistentManagerContext {
+    isTerminated: () => boolean;
+    findWorkerByName: (name: string) => WorkerConfig | undefined;
+    trackWorker: (worker: Worker) => Worker;
+    logger: ILogger;
+    terminateWorker: (worker: Worker) => void;
+}

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

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

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

@@ -0,0 +1,17 @@
+import { PipelineStep, CollectedResult } from '../main-worker-factory/types';
+import { PipelineContext } from './types';
+/**
+ * Executes a pipeline of workers, handling initialization, data flow, and termination.
+ *
+ * This function can execute either a single-step worker or a multi-step worker pipeline.
+ * For multi-step pipelines, workers are linked together via `MessageChannel`s.
+ * Data flows directly from one worker to the next without routing through the main thread,
+ * while errors and pipeline status communicate back to the main thread.
+ *
+ * @param steps - An array of pipeline steps, where each step defines the worker name and input parameters.
+ * @param context - The execution context (provides orchestrator, logger, memory store).
+ * @returns A promise that resolves to a CollectedResult containing the final output of the pipeline, or rejects on error.
+ * @throws {Error} If the pipeline is empty, the worker manager is terminated, or a worker is not found.
+ * @template TResult - The type of the pipeline result.
+ */
+export declare function executePipeline<TResult = unknown>(steps: PipelineStep[], context: PipelineContext): Promise<CollectedResult<TResult>>;

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

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

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

@@ -0,0 +1,13 @@
+import { WorkerConfig } from '../main-worker-factory/types';
+import { MemoryStore } from '../memory-store';
+import { MemoryWorkerProxy } from '../memory-store/memory-worker-proxy';
+import { ILogger } from '../logger';
+export interface PipelineContext {
+    memoryStore: MemoryStore;
+    memoryWorkerProxy: MemoryWorkerProxy;
+    isTerminated: () => boolean;
+    findWorkerByName: (name: string) => WorkerConfig | undefined;
+    trackWorker: (worker: Worker) => Worker;
+    terminateWorker: (worker: Worker) => void;
+    logger: ILogger;
+}

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

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

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

@@ -0,0 +1,26 @@
+import { WorkerConfig, WorkerDataParam, WorkerReturnType, WorkerConfigMap, CollectedResult, RunWorkerOptions } from '../main-worker-factory/types';
+import { RunWorkerContext } from './types';
+/**
+ * Executes a specific worker with the provided parameters, optionally handling partitioning
+ * and data resolution from the memory store.
+ *
+ * Workers now run in Memory mode: they store their results directly into MemoryWorker
+ * via a pre-allocated MessagePort. Only `__memory_ref__` tokens return to the main thread.
+ * Auto-collect is then triggered to merge shards in a reducer worker (also without
+ * routing data through the main thread), and a `CollectedResult<R>` is returned.
+ *
+ * @param workerName - The name of the worker to execute (from configured workers).
+ * @param rawParams - The parameters to pass to the worker, including optional `srcData` and memory options.
+ * @param context - The execution context (provides orchestrator, logger, memory store, proxy).
+ * @returns A CollectedResult containing the merged data and shard stats.
+ * @throws {Error} If the worker factory is terminated or the worker is not found.
+ * @template TConfigs - A tuple of WorkerConfig configurations.
+ * @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.
+ */
+export declare function executeWorker<TConfigs extends readonly WorkerConfig[], 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;
+} & RunWorkerOptions<T, R> & Record<string, unknown>, context: RunWorkerContext): Promise<CollectedResult<R>>;

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

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

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

@@ -0,0 +1,14 @@
+import { WorkerConfig } from '../main-worker-factory/types';
+import { WorkerOrchestrator } from '../orchestrator';
+import { MemoryStore, MemoryWorkerProxy } from '../memory-store';
+import { ILogger } from '../logger/types';
+export interface RunWorkerContext {
+    isTerminated: () => boolean;
+    findWorkerByName: (name: string) => WorkerConfig | undefined;
+    memoryStore: MemoryStore;
+    memoryWorkerProxy: MemoryWorkerProxy;
+    factoryToken: string;
+    threads: number;
+    orchestrator: WorkerOrchestrator;
+    logger: ILogger;
+}

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

@@ -1 +1 @@
-export { default as WorkerFactory } from './worker-factory';
+export { default as WorkerFactory, WorkerMode } from './worker-factory';

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

@@ -2,7 +2,13 @@ import { WorkerFunction } from '../main-worker-factory/types';
 export declare enum WorkerMode {
     Default = "default",
     Pipeline = "pipeline",
-    Persistent = "persistent"
+    Persistent = "persistent",
+    /**
+     * Memory mode: the worker stores its result directly into the MemoryWorker
+     * thread via a pre-allocated `MessagePort`. Only a `__memory_ref__` token
+     * is posted back to the main thread — large data never touches main thread heap.
+     */
+    Memory = "memory"
 }
 export interface WorkerFactoryOptions {
     /** The worker execution mode. Defaults to `WorkerMode.Default`. */

package/dist/types/workers/initiator.d.ts

@@ -1,4 +1,4 @@
-/**o with
+/**
  * Default initiator — a minimal echo worker used as a no-op placeholder.
  *
  * When no custom initiator is passed to `MainWorkerFactory`, this function

package/dist/types/workers/initiator.test.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offmain/workerkit",
-  "version": "0.14.0",
+  "version": "1.0.0",
   "description": "A lightweight manager for running functions in Web Workers with partitioning, retries, and concurrency control",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./define-worker": {
+      "types": "./dist/types/tools/define-worker/index.d.ts",
+      "import": "./dist/define-worker.js",
+      "require": "./dist/define-worker.cjs"
+    },
     "./eslint-plugin": "./eslint-rules/index.cjs",
     "./eslint-rules/no-dom-in-worker": "./eslint-rules/no-dom-in-worker.cjs",
     "./eslint-rules/worker-exportable": "./eslint-rules/worker-exportable.cjs"
@@ -60,6 +65,8 @@
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "11.0.0",
+    "@types/luxon": "^3.7.2",
+    "@types/node": "^26.4.0",
     "@typescript-eslint/eslint-plugin": "^8.58.2",
     "@typescript-eslint/parser": "^8.58.2",
     "date-fns": "^4.1.0",
@@ -69,16 +76,15 @@
     "eslint-plugin-local-rules": "^3.0.2",
     "eslint-plugin-prettier": "^5.5.5",
     "husky": "^9.1.7",
+    "i18next": "^25.5.1",
     "jsdom": "^24.0.0",
     "lint-staged": "^16.4.0",
+    "luxon": "^3.7.2",
     "prettier": "^3.4.2",
     "release-it": "19.0.3",
     "typescript": "^5.7.2",
     "vite": "^6.3.3",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^1.0.0",
-    "luxon": "^3.7.2",
-    "i18next": "^25.5.1",
-    "@types/luxon": "^3.7.2"
+    "vitest": "^1.0.0"
   }
 }

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

@@ -1,21 +0,0 @@
-import { WorkerFunction } from './main-worker-factory/types';
-/**
- * Defines and exports a function to run inside a native Web Worker script,
- * providing full compatibility with `MainWorkerFactory` features including
- * standard runs, worker-to-worker pipelines (`foreman.pipeline()`), and
- * dataset caching (`foreman.runPersistent()`).
- *
- * @typeParam TParams - The type of the payload sent to the worker.
- * @typeParam TResult - The return type of the worker function.
- *
- * @param workerFn - The worker execution function.
- *
- * @example
- * // my-native-worker.ts
- * import { defineWorker } from '@offmain/workerkit';
- *
- * export default defineWorker(async ({ data }: { data: number[] }) => {
- *   return data.map((x) => x * 2);
- * });
- */
-export declare function defineWorker<TParams = unknown, TResult = unknown>(workerFn: WorkerFunction<TParams, TResult | Promise<TResult>>): void;