@valentinkolb/sync 2.0.4 → 2.0.5

package/index.d.ts

@@ -0,0 +1,5 @@
+export { ratelimit, RateLimitError, type RateLimiter, type RateLimitResult, type RateLimitConfig, } from "./src/ratelimit";
+export { mutex, LockError, type Mutex, type Lock, type MutexConfig } from "./src/mutex";
+export { queue, type Queue, type QueueConfig, type QueueReader, type QueueRecvConfig, type QueueSendConfig, type QueueReceived, } from "./src/queue";
+export { topic, type Topic, type TopicConfig, type TopicReader, type TopicRecvConfig, type TopicPubConfig, type TopicDelivery, type TopicLiveConfig, type TopicLiveEvent, } from "./src/topic";
+export { job, type JobId, type JobStatus, type JobTerminal, type SubmitOptions, type JoinOptions, type CancelOptions, type JobEvent, type JobEvents, type JobContext, type JobHandle, type JobDefinition, } from "./src/job";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/sync",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Distributed synchronization primitives for Bun and TypeScript",
   "main": "index.js",
   "module": "index.js",

package/src/internal/job-utils.d.ts

@@ -0,0 +1,11 @@
+export type JobTerminalStatus = "completed" | "failed" | "cancelled" | "timed_out";
+export type RetryBackoff = {
+    kind: "fixed" | "exp";
+    baseMs: number;
+    maxMs?: number;
+} | undefined;
+export declare const isTerminalStatus: (status: string) => status is JobTerminalStatus;
+export declare const parseJsonOrNull: <T>(raw: string | null) => T | null;
+export declare const createTimeoutError: () => Error;
+export declare const withTimeout: <T>(promise: Promise<T>, timeoutMs: number) => Promise<T>;
+export declare const computeRetryDelay: (backoff: RetryBackoff, attempt: number) => number;

package/src/internal/topic-utils.d.ts

@@ -0,0 +1,7 @@
+export type RawFields = Record<string, string>;
+export type ParsedEntry = {
+    id: string;
+    fields: RawFields;
+};
+export declare const fieldArrayToObject: (value: unknown) => RawFields;
+export declare const parseFirstStreamEntry: (raw: unknown) => ParsedEntry | null;

package/src/job.d.ts

@@ -0,0 +1,105 @@
+import { z, type ZodTypeAny } from "zod";
+import { type Topic } from "./topic";
+export type JobId = string;
+export type JobStatus = "completed" | "failed" | "cancelled" | "timed_out";
+export type JobTerminal<Result = unknown> = {
+    id: JobId;
+    status: JobStatus;
+    result?: Result;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    finishedAt: number;
+};
+export type SubmitOptions = {
+    key?: string;
+    delayMs?: number;
+    at?: number;
+    maxAttempts?: number;
+    backoff?: {
+        kind: "fixed" | "exp";
+        baseMs: number;
+        maxMs?: number;
+    };
+    leaseMs?: number;
+    meta?: Record<string, unknown>;
+};
+export type JoinOptions = {
+    timeoutMs?: number;
+};
+export type CancelOptions = {
+    reason?: string;
+};
+export type JobEvent = {
+    type: "submitted";
+    id: JobId;
+    ts: number;
+} | {
+    type: "started";
+    id: JobId;
+    runId: string;
+    attempt: number;
+    ts: number;
+} | {
+    type: "heartbeat";
+    id: JobId;
+    runId: string;
+    ts: number;
+} | {
+    type: "retry";
+    id: JobId;
+    runId: string;
+    nextAt: number;
+    reason?: string;
+    ts: number;
+} | {
+    type: "completed";
+    id: JobId;
+    ts: number;
+} | {
+    type: "failed";
+    id: JobId;
+    reason?: string;
+    ts: number;
+} | {
+    type: "cancelled";
+    id: JobId;
+    reason?: string;
+    ts: number;
+};
+export type JobEvents = Pick<Topic<JobEvent>, "reader" | "live">;
+export type JobContext = {
+    step<T>(cfg: {
+        id: string;
+        run: () => Promise<T> | T;
+    }): Promise<T>;
+    heartbeat(cfg?: {
+        leaseMs?: number;
+    }): Promise<void>;
+    signal: AbortSignal;
+};
+export type JobHandle<Input, Result = unknown> = {
+    id: string;
+    submit(cfg: {
+        input: Input;
+    } & SubmitOptions): Promise<JobId>;
+    join(cfg: {
+        id: JobId;
+    } & JoinOptions): Promise<JobTerminal<Result>>;
+    cancel(cfg: {
+        id: JobId;
+    } & CancelOptions): Promise<void>;
+    events(id: JobId): JobEvents;
+    stop(): void;
+};
+export type JobDefinition<TSchema extends ZodTypeAny, Result = unknown> = {
+    id: string;
+    schema: TSchema;
+    defaults?: Omit<SubmitOptions, "key" | "delayMs" | "at" | "meta">;
+    process: (cfg: {
+        ctx: JobContext;
+        input: z.infer<TSchema>;
+    }) => Promise<Result> | Result;
+};
+export declare const job: <TSchema extends ZodTypeAny, Result = unknown>(definition: JobDefinition<TSchema, Result>) => JobHandle<z.infer<TSchema>, Result>;

package/src/mutex.d.ts

@@ -0,0 +1,26 @@
+export type Lock = {
+    resource: string;
+    value: string;
+    ttl: number;
+    expiration: number;
+};
+export type MutexConfig = {
+    id: string;
+    prefix?: string;
+    retryCount?: number;
+    retryDelay?: number;
+    defaultTtl?: number;
+};
+export type Mutex = {
+    id: string;
+    acquire(resource: string, ttl?: number): Promise<Lock | null>;
+    release(lock: Lock): Promise<void>;
+    withLock<T>(resource: string, fn: (lock: Lock) => Promise<T> | T, ttl?: number): Promise<T | null>;
+    withLockOrThrow<T>(resource: string, fn: (lock: Lock) => Promise<T> | T, ttl?: number): Promise<T>;
+    extend(lock: Lock, ttl?: number): Promise<boolean>;
+};
+export declare class LockError extends Error {
+    readonly resource: string;
+    constructor(resource: string);
+}
+export declare const mutex: (config: MutexConfig) => Mutex;

package/src/queue.d.ts

@@ -0,0 +1,67 @@
+import type { z } from "zod";
+export type QueueConfig<TSchema extends z.ZodTypeAny> = {
+    id: string;
+    schema: TSchema;
+    tenantId?: string;
+    prefix?: string;
+    ordering?: {
+        mode?: "best_effort" | "ordering_key_partitioned";
+        partitions?: number;
+    };
+    limits?: {
+        payloadBytes?: number;
+        maxMessageAgeMs?: number;
+        maxNackDelayMs?: number;
+        dlqRetentionMs?: number;
+    };
+    delivery?: {
+        defaultLeaseMs?: number;
+        maxDeliveries?: number;
+    };
+};
+export type QueueSendConfig<T> = {
+    tenantId?: string;
+    data: T;
+    delayMs?: number;
+    orderingKey?: string;
+    idempotencyKey?: string;
+    idempotencyTtlMs?: number;
+    meta?: Record<string, unknown>;
+};
+export type QueueRecvConfig = {
+    tenantId?: string;
+    wait?: boolean;
+    timeoutMs?: number;
+    leaseMs?: number;
+    consumerId?: string;
+    signal?: AbortSignal;
+};
+export type QueueReceived<T> = {
+    data: T;
+    messageId: string;
+    deliveryId: string;
+    attempt: number;
+    leaseUntil: number;
+    orderingKey?: string;
+    meta?: Record<string, unknown>;
+    ack(): Promise<boolean>;
+    nack(cfg?: {
+        delayMs?: number;
+        reason?: string;
+        error?: string;
+    }): Promise<boolean>;
+    touch(cfg?: {
+        leaseMs?: number;
+    }): Promise<boolean>;
+};
+export type QueueReader<T> = {
+    recv(cfg?: QueueRecvConfig): Promise<QueueReceived<T> | null>;
+    stream(cfg?: QueueRecvConfig): AsyncIterable<QueueReceived<T>>;
+};
+export type Queue<T> = QueueReader<T> & {
+    send(cfg: QueueSendConfig<T>): Promise<{
+        messageId: string;
+    }>;
+    reader(): QueueReader<T>;
+};
+export declare const queue: <TSchema extends z.ZodTypeAny>(config: QueueConfig<TSchema>) => Queue<z.infer<TSchema>>;

package/src/ratelimit.d.ts

@@ -0,0 +1,22 @@
+export type RateLimitResult = {
+    limited: boolean;
+    remaining: number;
+    resetIn: number;
+};
+export type RateLimitConfig = {
+    id: string;
+    limit: number;
+    windowSecs?: number;
+    prefix?: string;
+};
+export type RateLimiter = {
+    id: string;
+    check(identifier: string): Promise<RateLimitResult>;
+    checkOrThrow(identifier: string): Promise<RateLimitResult>;
+};
+export declare class RateLimitError extends Error {
+    readonly remaining: number;
+    readonly resetIn: number;
+    constructor(result: RateLimitResult);
+}
+export declare const ratelimit: (config: RateLimitConfig) => RateLimiter;

package/src/topic.d.ts

@@ -0,0 +1,63 @@
+import type { z } from "zod";
+export type TopicConfig<TSchema extends z.ZodTypeAny> = {
+    id: string;
+    schema: TSchema;
+    tenantId?: string;
+    prefix?: string;
+    limits?: {
+        payloadBytes?: number;
+    };
+    retentionMs?: number;
+};
+export type TopicPubConfig<T> = {
+    tenantId?: string;
+    data: T;
+    orderingKey?: string;
+    idempotencyKey?: string;
+    idempotencyTtlMs?: number;
+    meta?: Record<string, unknown>;
+};
+export type TopicRecvConfig = {
+    tenantId?: string;
+    timeoutMs?: number;
+    wait?: boolean;
+    signal?: AbortSignal;
+};
+export type TopicDelivery<T> = {
+    data: T;
+    eventId: string;
+    deliveryId: string;
+    cursor: string;
+    orderingKey?: string;
+    publishedAt: number;
+    meta?: Record<string, unknown>;
+    commit(): Promise<boolean>;
+};
+export type TopicLiveConfig = {
+    tenantId?: string;
+    after?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type TopicLiveEvent<T> = {
+    data: T;
+    eventId: string;
+    cursor: string;
+    orderingKey?: string;
+    publishedAt: number;
+    meta?: Record<string, unknown>;
+};
+export type TopicReader<T> = {
+    group: string;
+    recv(cfg?: TopicRecvConfig): Promise<TopicDelivery<T> | null>;
+    stream(cfg?: TopicRecvConfig): AsyncIterable<TopicDelivery<T>>;
+};
+export type Topic<T> = {
+    pub(cfg: TopicPubConfig<T>): Promise<{
+        eventId: string;
+        cursor: string;
+    }>;
+    reader(group?: string): TopicReader<T>;
+    live(cfg?: TopicLiveConfig): AsyncIterable<TopicLiveEvent<T>>;
+};
+export declare const topic: <TSchema extends z.ZodTypeAny>(config: TopicConfig<TSchema>) => Topic<z.infer<TSchema>>;