knitting 0.1.55 → 0.1.60

package/src/api.d.ts

@@ -0,0 +1,92 @@
+import { setModuleUrl } from "./common/task-source.js";
+import { endpointSymbol } from "./common/task-symbol.js";
+import type { AbortSignalConfig, AbortSignalOption, AbortSignalToolkit, Args, CompiledWorkerCheck, CompiledWorkerOptions, CompiledWorkerSource, ComposedWithKey, CreatePool, FixPoint, ImportTaskOptions, MaybePromise, Pool, ReturnFixed, TaskInput, tasks, TaskTimeout } from "./types.js";
+type ToListAndIds = {
+    list: string[];
+    ids: number[];
+    names: string[];
+    at: number[];
+};
+type ToListAndIdsFn = (args: ComposedWithKey[]) => ToListAndIds;
+type CreatePoolFactory = (options: CreatePool) => <T extends tasks>(tasks: T) => Pool<T>;
+type InferredTaskFunction = (...args: any[]) => MaybePromise<Args>;
+type InferredTaskInput<F extends InferredTaskFunction, AS extends AbortSignalOption> = Parameters<F> extends [] ? void : AS extends undefined ? Parameters<F> extends [infer A] ? A extends TaskInput ? A : never : never : Parameters<F> extends [infer A] ? A extends TaskInput ? A : never : Parameters<F> extends [infer A, AbortSignalToolkit<AS>] ? A extends TaskInput ? A : never : never;
+type InferredTaskOutput<F extends InferredTaskFunction> = Awaited<ReturnType<F>> extends infer R ? R extends Blob ? never : R extends Args ? R : never : never;
+type InferredTaskShape<F extends InferredTaskFunction, AS extends AbortSignalOption> = [InferredTaskInput<F, AS>] extends [never] ? never : [InferredTaskOutput<F>] extends [never] ? never : {
+    readonly f: F;
+    readonly timeout?: TaskTimeout;
+} & (AS extends undefined ? {
+    readonly abortSignal?: undefined;
+} : {
+    readonly abortSignal: AS;
+});
+export declare const isMain: boolean;
+export { endpointSymbol as endpointSymbol };
+/**
+ * Declare the task module's URL for runtimes without stack traces (e.g.
+ * Andromeda) that can't auto-discover the caller. Call once at module top
+ * level, before defining tasks:
+ *
+ * ```ts
+ * import { setModuleUrl, task } from "knitting";
+ * setModuleUrl(import.meta.url);
+ * export const add = task({ f: ([a, b]: [number, number]) => a + b });
+ * ```
+ *
+ * Runs in both host and worker (same module re-imported), so both agree on the
+ * path. No-op-safe on Node/Deno/Bun, where stack discovery already works.
+ */
+export { setModuleUrl as setModuleUrl };
+/**
+ * Reconstructs stable task order from top-level exports before names are bound.
+ */
+export declare const toListAndIds: ToListAndIdsFn;
+/**
+ * Check whether a task module has a compatible prebuilt native worker.
+ *
+ * By default tasks.ts resolves to tasks.knt plus tasks.knt.json.
+ * This only inspects the artifact; it never executes it.
+ */
+export declare const checkCompiledWorker: (source: CompiledWorkerSource, options?: CompiledWorkerOptions) => CompiledWorkerCheck;
+/**
+ * Create a typed worker pool from module-scope exported tasks/functions.
+ *
+ * Install/import as `knitting` on npm or `@vixeny/knitting` on JSR. Requires
+ * Node 22+, Deno 2+, or Bun 1+.
+ *
+ * Use `createPool(options)({ taskA })`, call `await pool.call.taskA(arg)`, and
+ * clean up with `using pool = ...` or `await pool.shutdown()`.
+ *
+ * Guard host-only pool setup with `isMain`: workers re-import task modules, and
+ * top-level imports in those modules run in every worker. Keep task modules
+ * lean and separate from server/framework setup. Each task receives one
+ * argument; use an object or tuple for multiple values.
+ */
+export declare const createPool: CreatePoolFactory;
+/**
+ * Define a worker task with options.
+ *
+ * Pass raw module-scope exported functions to `createPool` directly when you do
+ * not need options. Use `task({ f })` for timeouts, abort signals, or the
+ * single-task `.createPool()` shorthand.
+ *
+ * The function receives one argument; use a tuple/object for multiple values.
+ * Inputs may be direct values or native Promises, so `request.arrayBuffer()` can
+ * be forwarded without awaiting on the host.
+ */
+export declare function task<F extends InferredTaskFunction>(I: InferredTaskShape<F, undefined>): ReturnFixed<InferredTaskInput<F, undefined>, InferredTaskOutput<F>, undefined>;
+export declare function task<F extends InferredTaskFunction>(I: InferredTaskShape<F, true>): ReturnFixed<InferredTaskInput<F, true>, InferredTaskOutput<F>, true>;
+export declare function task<AS extends AbortSignalConfig, F extends InferredTaskFunction>(I: InferredTaskShape<F, AS>): ReturnFixed<InferredTaskInput<F, AS>, InferredTaskOutput<F>, AS>;
+export declare function task<A extends TaskInput = void, B extends Args = void>(I: FixPoint<A, B, true>): ReturnFixed<A, B, true>;
+export declare function task<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalConfig = AbortSignalConfig>(I: FixPoint<A, B, AS>): ReturnFixed<A, B, AS>;
+export declare function task<A extends TaskInput = void, B extends Args = void>(I: FixPoint<A, B, undefined>): ReturnFixed<A, B, undefined>;
+/**
+ * Define a task whose worker-side code is imported only by workers.
+ *
+ * Use this for untrusted or security-sensitive code: the host keeps a typed
+ * wrapper and does not import/evaluate `href`. The target export must be a
+ * plain function, not a `task()` wrapper.
+ */
+export declare function importTask<A extends TaskInput = void, B extends Args = void>(options: ImportTaskOptions<A, B, true>): ReturnFixed<A, B, true>;
+export declare function importTask<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalConfig = AbortSignalConfig>(options: ImportTaskOptions<A, B, AS>): ReturnFixed<A, B, AS>;
+export declare function importTask<A extends TaskInput = void, B extends Args = void>(options: ImportTaskOptions<A, B, undefined>): ReturnFixed<A, B, undefined>;