enqiu 0.1.0

package/dist/memory.d.ts

@@ -0,0 +1,344 @@
+export type MaybePromise<T> = T | PromiseLike<T>;
+export type JobStatus = "queued" | "scheduled" | "running" | "succeeded" | "failed" | "cancelled" | "expired";
+export interface JobContext<Name extends string = string> {
+    readonly id: string;
+    readonly name: Name;
+    readonly attempt: number;
+    readonly signal: AbortSignal;
+    progress(value: unknown): void;
+    log(entry: JobLogEntry): void;
+}
+export type JobLogLevel = "debug" | "info" | "warn" | "error";
+export interface JobLogEntry {
+    readonly timestamp: number;
+    readonly level: JobLogLevel;
+    readonly message: string;
+    readonly fields?: Readonly<Record<string, unknown>>;
+}
+export type JobHandler<Input = unknown, Output = unknown, Name extends string = string> = (input: Input, context: JobContext<Name>) => MaybePromise<Output>;
+export type JobMap = Record<string, JobHandler<any, any, any>>;
+export type JobName<Jobs extends JobMap> = Extract<keyof Jobs, string>;
+export type JobInput<Jobs extends JobMap, Name extends JobName<Jobs>> = Parameters<Jobs[Name]>[0];
+export type JobOutput<Jobs extends JobMap, Name extends JobName<Jobs>> = Awaited<ReturnType<Jobs[Name]>>;
+export interface BackoffOptions {
+    type?: "fixed" | "exponential";
+    delay: number;
+    /**
+     * Randomize each delay by up to this fraction.
+     * `1` is full jitter; `0.2` produces a value between 80–100%.
+     */
+    jitter?: number;
+}
+export type BackoffStrategy = number | BackoffOptions | ((attempt: number, error: Error) => MaybePromise<number>);
+export interface RetryOptions {
+    /** Number of retries after the first attempt. */
+    retries: number;
+    backoff?: BackoffStrategy;
+    /** Return `false` to fail immediately instead of retrying this error. */
+    when?: (error: Error, attempt: number) => MaybePromise<boolean>;
+}
+export interface RateLimitOptions {
+    /** Maximum number of job starts in the interval. */
+    limit: number;
+    /** Rolling-window duration in milliseconds. */
+    interval: number;
+}
+export interface KeyedConcurrencyOptions {
+    limit: number;
+    key: string;
+}
+export interface ThrottleOptions {
+    limit: number;
+    interval: number;
+    burst: number;
+    key: string;
+}
+export interface DebounceOptions {
+    wait: number;
+    mode: "leading" | "trailing";
+    key: string;
+}
+export interface QueueOptions {
+    /** Used in generated job IDs and diagnostics. */
+    name?: string;
+    /** Maximum number of handlers running at once. @default Infinity */
+    concurrency?: number;
+    /** Keep jobs queued until `start()` is called. @default true */
+    autoStart?: boolean;
+    /** Default retry policy. A number means retry that many times. */
+    retry?: number | RetryOptions;
+    /** Default per-attempt timeout in milliseconds. */
+    timeout?: number;
+    /** Optional strict rolling-window rate limit. */
+    rateLimit?: RateLimitOptions;
+    /** Number of finished jobs retained for inspection. @default 1000 */
+    historyLimit?: number;
+    /** Maximum structured log entries retained per job. @default 100 */
+    logLimit?: number;
+}
+export interface AddOptions {
+    /** Custom job ID. Duplicate IDs throw. */
+    id?: string;
+    /**
+     * Single-flight key. While a matching job is unfinished, `add` returns it
+     * instead of creating duplicate work.
+     */
+    key?: string;
+    /** Delay in milliseconds, or an exact future date. */
+    delay?: number | Date;
+    /** Higher values run first. Equal priorities remain FIFO. */
+    priority?: number;
+    /** Override the queue retry policy. */
+    retry?: number | RetryOptions;
+    /** Override the queue per-attempt timeout. */
+    timeout?: number;
+    /** Expire before execution after this many milliseconds. */
+    expiresIn?: number;
+    /** Internal resolved per-key execution limit. */
+    concurrency?: KeyedConcurrencyOptions;
+    /** Internal resolved token-bucket policy. */
+    throttle?: ThrottleOptions;
+    /** Internal resolved debounce policy. */
+    debounce?: DebounceOptions;
+    /** Retain an idempotency key after completion for this duration. */
+    keyRetention?: number;
+    /** Cancels the job when aborted. */
+    signal?: AbortSignal;
+}
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string | undefined;
+}
+export interface JobSnapshot<Input = unknown, Output = unknown, Name extends string = string> {
+    id: string;
+    name: Name;
+    input: Input;
+    status: JobStatus;
+    priority: number;
+    attempt: number;
+    retries: number;
+    createdAt: number;
+    runAt: number;
+    expiresAt?: number | undefined;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    progress?: unknown;
+    output?: Output | undefined;
+    error?: SerializedError | undefined;
+    logs?: readonly JobLogEntry[] | undefined;
+}
+export interface QueueStats {
+    queued: number;
+    scheduled: number;
+    running: number;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+    expired: number;
+    total: number;
+}
+export interface CleanupOptions {
+    /** Only remove jobs finished at least this many milliseconds ago. @default 0 */
+    olderThan?: number;
+    /** Maximum number of jobs to remove. @default Infinity */
+    limit?: number;
+}
+export interface CloseOptions {
+    /** Finish queued and scheduled work before closing. @default true */
+    drain?: boolean;
+}
+export interface QueueEventMap {
+    added: JobSnapshot;
+    started: JobSnapshot;
+    progress: JobSnapshot;
+    log: {
+        job: JobSnapshot;
+        entry: JobLogEntry;
+    };
+    retry: {
+        job: JobSnapshot;
+        error: Error;
+        delay: number;
+    };
+    succeeded: JobSnapshot;
+    failed: JobSnapshot;
+    cancelled: JobSnapshot;
+    expired: JobSnapshot;
+    idle: QueueStats;
+}
+export declare class JobFailedError extends Error {
+    readonly jobId: string;
+    constructor(jobId: string, message: string, options?: ErrorOptions);
+}
+export declare class JobCancelledError extends Error {
+    readonly jobId: string;
+    constructor(jobId: string, message?: string);
+}
+export declare class JobTimeoutError extends Error {
+    readonly jobId: string;
+    readonly timeout: number;
+    constructor(jobId: string, timeout: number);
+}
+export declare class JobExpiredError extends Error {
+    readonly jobId: string;
+    constructor(jobId: string);
+}
+export declare class QueueClosedError extends Error {
+    constructor(name: string);
+}
+/**
+ * An awaitable handle returned synchronously by `queue.add()`.
+ *
+ * Ignoring a handle is safe: MemoryQueue does not create a rejecting promise until
+ * the handle is awaited or `.result` is read.
+ */
+export interface Job<Output = unknown, Input = unknown, Name extends string = string> extends PromiseLike<Output> {
+    readonly id: string;
+    readonly name: Name;
+    readonly input: Input;
+    readonly status: JobStatus;
+    readonly deduplicated: boolean;
+    /** Resolves once the queue has accepted and stored the job. */
+    readonly accepted: Promise<void>;
+    readonly result: Promise<Output>;
+    cancel(reason?: string): boolean;
+    snapshot(): JobSnapshot<Input, Output, Name>;
+    catch<Result = never>(onRejected?: ((reason: unknown) => Result | PromiseLike<Result>) | null): Promise<Output | Result>;
+    finally(onFinally?: (() => void) | null): Promise<Output>;
+}
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve(value: T): void;
+}
+interface NormalizedRetry {
+    retries: number;
+    backoff: BackoffStrategy | undefined;
+    when: RetryOptions["when"] | undefined;
+}
+interface InternalJob {
+    id: string;
+    name: string;
+    input: unknown;
+    status: JobStatus;
+    priority: number;
+    attempt: number;
+    retry: NormalizedRetry;
+    timeout: number | undefined;
+    key: string | undefined;
+    keyRetention: number;
+    keyExpiresAt: number | undefined;
+    concurrency: KeyedConcurrencyOptions | undefined;
+    throttle: ThrottleOptions | undefined;
+    debounceKey: string | undefined;
+    createdAt: number;
+    runAt: number;
+    expiresAt: number | undefined;
+    startedAt: number | undefined;
+    finishedAt: number | undefined;
+    progress: unknown;
+    output: unknown;
+    error: SerializedError | undefined;
+    errorCause: Error | undefined;
+    logs: JobLogEntry[];
+    sequence: number;
+    controller: AbortController | undefined;
+    completion: Deferred<JobSnapshot>;
+    externalSignal: AbortSignal | undefined;
+    abortListener: (() => void) | undefined;
+}
+/**
+ * A zero-dependency, single-process job queue with strongly typed named jobs.
+ *
+ * State is intentionally kept in memory. MemoryQueue is ideal for local background
+ * work, concurrency control, API throttling, and tests. It is not durable or
+ * distributed; use a database-backed queue when jobs must survive restarts.
+ */
+export declare class MemoryQueue<Jobs extends JobMap> {
+    readonly name: string;
+    private readonly handlers;
+    private readonly records;
+    private readonly keys;
+    private readonly activeKeys;
+    private readonly throttleStates;
+    private readonly debounceStates;
+    private readonly ready;
+    private readonly delayed;
+    private readonly listeners;
+    private readonly defaultRetry;
+    private readonly defaultTimeout;
+    private readonly rateLimit;
+    private readonly historyLimit;
+    private readonly logLimit;
+    private readonly starts;
+    private readonly idleWaiters;
+    private readonly sizeWaiters;
+    private _concurrency;
+    private runningCount;
+    private sequence;
+    private started;
+    private closed;
+    private idleNotified;
+    private pumpQueued;
+    private timer;
+    private policyWakeAt;
+    constructor(handlers: Jobs, options?: QueueOptions);
+    get concurrency(): number;
+    set concurrency(value: number);
+    /** Jobs waiting to start, including scheduled jobs. */
+    get size(): number;
+    /** Jobs currently running. */
+    get pending(): number;
+    get isPaused(): boolean;
+    get isRateLimited(): boolean;
+    get isSaturated(): boolean;
+    get stats(): QueueStats;
+    add<Name extends JobName<Jobs>>(name: Name, input: JobInput<Jobs, Name>, options?: AddOptions): Job<JobOutput<Jobs, Name>, JobInput<Jobs, Name>, Name>;
+    private updateTrailingDebounce;
+    addMany<Name extends JobName<Jobs>>(name: Name, inputs: readonly JobInput<Jobs, Name>[], options?: AddOptions): Array<Job<JobOutput<Jobs, Name>, JobInput<Jobs, Name>, Name>>;
+    get(id: string): JobSnapshot | undefined;
+    list(status?: JobStatus): JobSnapshot[];
+    cancel(id: string, reason?: string): boolean;
+    clear(reason?: string): number;
+    retry(id: string): Job<unknown> | undefined;
+    pause(): this;
+    start(): this;
+    onIdle(): Promise<void>;
+    onSizeLessThan(limit: number): Promise<void>;
+    cleanup(options?: CleanupOptions): string[];
+    close(options?: CloseOptions): Promise<void>;
+    on<Event extends keyof QueueEventMap>(event: Event, listener: (payload: QueueEventMap[Event]) => void): () => void;
+    /** @internal Used by the awaitable job handle. */
+    resultFor(job: InternalJob): Promise<unknown>;
+    private handle;
+    private createId;
+    private connectSignal;
+    private disconnectSignal;
+    private requestPump;
+    private pump;
+    private promoteDelayed;
+    private expireWaiting;
+    private peekDelayed;
+    private popReady;
+    private canStart;
+    private beginExecutionPolicy;
+    private releaseExecutionPolicy;
+    private refillThrottle;
+    private hasReady;
+    private hasRateCapacity;
+    private pruneStarts;
+    private scheduleNextWake;
+    private execute;
+    private handleFailure;
+    private finish;
+    private pruneHistory;
+    private prunePolicyState;
+    private notifyIdle;
+    private notifySizeWaiters;
+    private emit;
+    private clearTimer;
+    private assertOpen;
+}
+/** Create a strongly typed queue from a map of named handlers. */
+export declare function memoryQueue<const Jobs extends JobMap>(handlers: Jobs, options?: QueueOptions): MemoryQueue<Jobs>;
+export {};