@valentinkolb/sync 2.2.0 → 3.0.0

package/package.json

@@ -1,21 +1,36 @@
 {
   "name": "@valentinkolb/sync",
-  "version": "2.2.0",
-  "description": "Distributed synchronization primitives for Bun and TypeScript",
+  "version": "3.0.0",
+  "description": "Synchronization primitives for TypeScript — server (Redis) and browser (in-memory)",
   "main": "index.js",
   "module": "index.js",
   "types": "index.d.ts",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": "./index.js",
       "types": "./index.d.ts"
-    }
+    },
+    "./browser": {
+      "import": "./browser/index.js",
+      "types": "./browser/index.d.ts"
+    },
+    "./browser/ratelimit": { "import": "./browser/ratelimit.js", "types": "./browser/ratelimit.d.ts" },
+    "./browser/mutex": { "import": "./browser/mutex.js", "types": "./browser/mutex.d.ts" },
+    "./browser/queue": { "import": "./browser/queue.js", "types": "./browser/queue.d.ts" },
+    "./browser/topic": { "import": "./browser/topic.js", "types": "./browser/topic.d.ts" },
+    "./browser/job": { "import": "./browser/job.js", "types": "./browser/job.d.ts" },
+    "./browser/scheduler": { "import": "./browser/scheduler.js", "types": "./browser/scheduler.d.ts" },
+    "./browser/ephemeral": { "import": "./browser/ephemeral.js", "types": "./browser/ephemeral.d.ts" },
+    "./browser/registry": { "import": "./browser/registry.js", "types": "./browser/registry.d.ts" },
+    "./browser/retry": { "import": "./browser/retry.js", "types": "./browser/retry.d.ts" },
+    "./browser/store": { "import": "./browser/store.js", "types": "./browser/store.d.ts" }
   },
   "peerDependencies": {
     "zod": "^4"
   },
-  "keywords": ["bun", "redis", "ratelimit", "mutex", "jobs", "queue", "distributed"],
+  "keywords": ["bun", "redis", "ratelimit", "mutex", "jobs", "queue", "distributed", "browser", "local-first"],
   "author": "Valentin Kolb",
   "license": "MIT",
   "repository": {

package/src/browser/ephemeral.d.ts

@@ -0,0 +1,101 @@
+import type { z } from "zod";
+export declare class EphemeralCapacityError extends Error {
+    constructor(message?: string);
+}
+export declare class EphemeralPayloadTooLargeError extends Error {
+    constructor(message: string);
+}
+export type EphemeralConfig<TSchema extends z.ZodTypeAny> = {
+    id: string;
+    schema: TSchema;
+    ttlMs: number;
+    tenantId?: string;
+    limits?: {
+        maxEntries?: number;
+        maxPayloadBytes?: number;
+        eventRetentionMs?: number;
+        eventMaxLen?: number;
+    };
+};
+export type EphemeralUpsertConfig<T> = {
+    key: string;
+    value: T;
+    ttlMs?: number;
+    tenantId?: string;
+};
+export type EphemeralTouchConfig = {
+    key: string;
+    ttlMs?: number;
+    tenantId?: string;
+};
+export type EphemeralRemoveConfig = {
+    key: string;
+    reason?: string;
+    tenantId?: string;
+};
+export type EphemeralEntry<T> = {
+    key: string;
+    value: T;
+    version: string;
+    updatedAt: number;
+    expiresAt: number;
+};
+export type EphemeralSnapshot<T> = {
+    entries: EphemeralEntry<T>[];
+    cursor: string;
+};
+export type EphemeralRecvConfig = {
+    wait?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export type EphemeralEvent<T> = {
+    type: "upsert";
+    cursor: string;
+    entry: EphemeralEntry<T>;
+} | {
+    type: "touch";
+    cursor: string;
+    key: string;
+    version: string;
+    expiresAt: number;
+} | {
+    type: "delete";
+    cursor: string;
+    key: string;
+    version: string;
+    deletedAt: number;
+    reason?: string;
+} | {
+    type: "expire";
+    cursor: string;
+    key: string;
+    version: string;
+    expiredAt: number;
+} | {
+    type: "overflow";
+    cursor: string;
+    after: string;
+    firstAvailable: string;
+};
+export type EphemeralReader<T> = {
+    recv(cfg?: EphemeralRecvConfig): Promise<EphemeralEvent<T> | null>;
+    stream(cfg?: EphemeralRecvConfig): AsyncIterable<EphemeralEvent<T>>;
+};
+export type EphemeralStore<T> = {
+    upsert(cfg: EphemeralUpsertConfig<T>): Promise<EphemeralEntry<T>>;
+    touch(cfg: EphemeralTouchConfig): Promise<{
+        ok: boolean;
+        version?: string;
+        expiresAt?: number;
+    }>;
+    remove(cfg: EphemeralRemoveConfig): Promise<boolean>;
+    snapshot(cfg?: {
+        tenantId?: string;
+    }): Promise<EphemeralSnapshot<T>>;
+    reader(cfg?: {
+        after?: string;
+        tenantId?: string;
+    }): EphemeralReader<T>;
+};
+export declare const ephemeral: <TSchema extends z.ZodTypeAny>(config: EphemeralConfig<TSchema>) => EphemeralStore<z.infer<TSchema>>;

package/src/browser/index.d.ts

@@ -0,0 +1,10 @@
+export { createMemoryStore, MemoryStore, type Store } from "./store";
+export { retry, isRetryableTransportError, DEFAULT_RETRY_OPTIONS, type RetryOptions } from "./retry";
+export { ratelimit, RateLimitError, type RateLimiter, type RateLimitResult, type RateLimitConfig } from "./ratelimit";
+export { mutex, LockError, type Mutex, type Lock, type MutexConfig } from "./mutex";
+export { topic, type Topic, type TopicConfig, type TopicPubConfig, type TopicRecvConfig, type TopicDelivery, type TopicLiveConfig, type TopicLiveEvent, type TopicReader, } from "./topic";
+export { queue, type Queue, type QueueConfig, type QueueSendConfig, type QueueRecvConfig, type QueueReceived, type QueueReader, } from "./queue";
+export { ephemeral, EphemeralCapacityError, EphemeralPayloadTooLargeError, type EphemeralStore, type EphemeralConfig, type EphemeralUpsertConfig, type EphemeralTouchConfig, type EphemeralRemoveConfig, type EphemeralEntry, type EphemeralSnapshot, type EphemeralRecvConfig, type EphemeralEvent, type EphemeralReader, } from "./ephemeral";
+export { registry, RegistryCapacityError, RegistryPayloadTooLargeError, type Registry, type RegistryConfig, type RegistryUpsertConfig, type RegistryTouchConfig, type RegistryRemoveConfig, type RegistryGetConfig, type RegistryListConfig, type RegistryCasConfig, type RegistryEntry, type RegistrySnapshot, type RegistryRecvConfig, type RegistryEvent, type RegistryReader, } from "./registry";
+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 "./job";
+export { scheduler, type Scheduler, type SchedulerConfig, type SchedulerRegisterConfig, type SchedulerUnregisterConfig, type SchedulerTriggerNowConfig, type SchedulerGetConfig, type SchedulerInfo, type SchedulerMetric, type SchedulerMetricsSnapshot, } from "./scheduler";

package/src/browser/internal/emitter.d.ts

@@ -0,0 +1,11 @@
+export declare class Emitter<T = void> {
+    private listeners;
+    /** Subscribe to events. Returns an unsubscribe function. */
+    on(fn: (value: T) => void): () => void;
+    /** Emit a value to all current listeners. */
+    emit(value: T): void;
+    /** Returns a promise that resolves on the next emit. */
+    once(): Promise<T>;
+    /** Returns a promise that resolves on the next emit, or rejects on abort. */
+    onceWithSignal(signal?: AbortSignal): Promise<T>;
+}

package/src/browser/internal/event-log.d.ts

@@ -0,0 +1,33 @@
+export type EventLogEntry = {
+    id: string;
+    ts: number;
+    fields: Record<string, unknown>;
+};
+export type EventLogConfig = {
+    maxLen?: number;
+    retentionMs?: number;
+};
+export declare class EventLog {
+    private entries;
+    private seq;
+    private emitter;
+    private maxLen;
+    private retentionMs;
+    constructor(config?: EventLogConfig);
+    /** Append an entry and return its cursor ID. */
+    append(fields: Record<string, unknown>): string;
+    /** Get entries after a cursor, optionally limited by count. */
+    range(after: string, count?: number): EventLogEntry[];
+    /** Get the latest cursor, or "0" if empty. */
+    latest(): string;
+    /** Get the earliest available cursor, or null if empty. */
+    earliest(): string | null;
+    /** Check whether a specific cursor still exists in the log. */
+    has(cursor: string): boolean;
+    /** Subscribe to new entries after a cursor. Yields entries as they arrive. */
+    subscribe(after: string, signal?: AbortSignal): AsyncIterable<EventLogEntry>;
+    /** Trim old entries based on maxLen and retentionMs. */
+    trim(): void;
+    /** Number of entries currently in the log. */
+    get size(): number;
+}

package/src/browser/internal/id.d.ts

@@ -0,0 +1,9 @@
+/** Generate a random UUID. */
+export declare const randomId: () => string;
+/** Generate a random hex string of the given byte length. */
+export declare const randomHex: (bytes: number) => string;
+export declare const nextSeq: () => number;
+/** Reset the sequence counter (for tests). */
+export declare const resetSeq: () => void;
+/** Simple non-cryptographic hash for long strings (djb2). */
+export declare const simpleHash: (str: string) => string;

package/src/browser/internal/sleep.d.ts

@@ -0,0 +1,2 @@
+export declare const sleep: (ms: number) => Promise<void>;
+export declare const sleepWithSignal: (delayMs: number, signal?: AbortSignal) => Promise<void>;

package/src/browser/job.d.ts

@@ -0,0 +1,107 @@
+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;
+    keyTtlMs?: number;
+    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>;
+    validateInput(input: unknown): void;
+    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/browser/mutex.d.ts

@@ -0,0 +1,28 @@
+import { type Store } from "./store";
+export type Lock = {
+    resource: string;
+    value: string;
+    ttl: number;
+    expiration: number;
+};
+export type MutexConfig = {
+    id: string;
+    prefix?: string;
+    retryCount?: number;
+    retryDelay?: number;
+    defaultTtl?: number;
+    store?: Store;
+};
+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/browser/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> = {
+    data: T;
+    delayMs?: number;
+    orderingKey?: string;
+    idempotencyKey?: string;
+    idempotencyTtlMs?: number;
+    meta?: Record<string, unknown>;
+    tenantId?: string;
+};
+export type QueueRecvConfig = {
+    wait?: boolean;
+    timeoutMs?: number;
+    leaseMs?: number;
+    signal?: AbortSignal;
+    consumerId?: string;
+    tenantId?: string;
+};
+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/browser/ratelimit.d.ts

@@ -0,0 +1,24 @@
+import { type Store } from "./store";
+export type RateLimitResult = {
+    limited: boolean;
+    remaining: number;
+    resetIn: number;
+};
+export type RateLimitConfig = {
+    id: string;
+    limit: number;
+    windowSecs?: number;
+    prefix?: string;
+    store?: Store;
+};
+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/browser/registry.d.ts

@@ -0,0 +1,131 @@
+import type { z } from "zod";
+export declare class RegistryCapacityError extends Error {
+    constructor(message?: string);
+}
+export declare class RegistryPayloadTooLargeError extends Error {
+    constructor(message: string);
+}
+export type RegistryConfig<TSchema extends z.ZodTypeAny> = {
+    id: string;
+    schema: TSchema;
+    tenantId?: string;
+    prefix?: string;
+    limits?: {
+        maxEntries?: number;
+        maxPayloadBytes?: number;
+        eventRetentionMs?: number;
+        eventMaxLen?: number;
+        tombstoneRetentionMs?: number;
+        reconcileBatchSize?: number;
+    };
+};
+export type RegistryUpsertConfig<T> = {
+    key: string;
+    value: T;
+    ttlMs?: number;
+    tenantId?: string;
+};
+export type RegistryTouchConfig = {
+    key: string;
+    ttlMs?: number;
+    tenantId?: string;
+};
+export type RegistryRemoveConfig = {
+    key: string;
+    reason?: string;
+    tenantId?: string;
+};
+export type RegistryGetConfig = {
+    key: string;
+    tenantId?: string;
+    includeExpired?: boolean;
+};
+export type RegistryListConfig = {
+    prefix?: string;
+    status?: "active" | "expired";
+    afterKey?: string;
+    limit?: number;
+    tenantId?: string;
+};
+export type RegistryCasConfig<T> = {
+    key: string;
+    version: string;
+    value: T;
+    tenantId?: string;
+};
+export type RegistryEntry<T> = {
+    key: string;
+    value: T;
+    version: string;
+    status: "active" | "expired";
+    createdAt: number;
+    updatedAt: number;
+    ttlMs: number | null;
+    expiresAt: number | null;
+};
+export type RegistrySnapshot<T> = {
+    entries: RegistryEntry<T>[];
+    cursor: string;
+    nextKey?: string;
+};
+export type RegistryRecvConfig = {
+    wait?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export type RegistryEvent<T> = {
+    type: "upsert";
+    cursor: string;
+    entry: RegistryEntry<T>;
+} | {
+    type: "touch";
+    cursor: string;
+    key: string;
+    version: string;
+    updatedAt: number;
+    expiresAt: number;
+} | {
+    type: "delete";
+    cursor: string;
+    key: string;
+    version: string;
+    removedAt: number;
+    reason?: string;
+} | {
+    type: "expire";
+    cursor: string;
+    key: string;
+    version: string;
+    removedAt: number;
+} | {
+    type: "overflow";
+    cursor: string;
+    after: string;
+    firstAvailable: string;
+};
+export type RegistryReader<T> = {
+    recv(cfg?: RegistryRecvConfig): Promise<RegistryEvent<T> | null>;
+    stream(cfg?: RegistryRecvConfig): AsyncIterable<RegistryEvent<T>>;
+};
+export type Registry<T> = {
+    upsert(cfg: RegistryUpsertConfig<T>): Promise<RegistryEntry<T>>;
+    touch(cfg: RegistryTouchConfig): Promise<{
+        ok: boolean;
+        version?: string;
+        expiresAt?: number;
+    }>;
+    remove(cfg: RegistryRemoveConfig): Promise<boolean>;
+    get(cfg: RegistryGetConfig): Promise<RegistryEntry<T> | null>;
+    list(cfg?: RegistryListConfig): Promise<RegistrySnapshot<T>>;
+    cas(cfg: RegistryCasConfig<T>): Promise<{
+        ok: boolean;
+        entry?: RegistryEntry<T>;
+    }>;
+    reader(cfg?: {
+        key?: string;
+        prefix?: string;
+        after?: string;
+        tenantId?: string;
+    }): RegistryReader<T>;
+};
+export declare const registry: <TSchema extends z.ZodTypeAny>(config: RegistryConfig<TSchema>) => Registry<z.infer<TSchema>>;

package/src/browser/retry.d.ts

@@ -0,0 +1,19 @@
+export type RetryOptions = {
+    attempts?: number;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+    jitter?: number;
+    signal?: AbortSignal;
+    retryIf?: (error: unknown) => boolean;
+};
+export declare const isRetryableTransportError: (error: unknown) => boolean;
+export declare const DEFAULT_RETRY_OPTIONS: {
+    readonly attempts: 8;
+    readonly minDelayMs: 100;
+    readonly maxDelayMs: 2000;
+    readonly factor: 2;
+    readonly jitter: 0.2;
+    readonly retryIf: (error: unknown) => boolean;
+};
+export declare const retry: <T>(fn: (attempt: number) => Promise<T> | T, opts?: RetryOptions) => Promise<T>;