@valentinkolb/sync 2.1.2 → 3.0.0

package/src/browser/scheduler.d.ts

@@ -0,0 +1,164 @@
+import { type MisfirePolicy } from "../internal/cron";
+type JobSubmitter = {
+    id: string;
+    submit(cfg: {
+        input: unknown;
+        key?: string;
+        keyTtlMs?: number;
+        at?: number;
+        delayMs?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<string>;
+    validateInput?(input: unknown): void;
+};
+export type SchedulerMetric = {
+    type: "leader_acquired";
+    ts: number;
+} | {
+    type: "leader_lost";
+    ts: number;
+    reason: "extend_failed" | "stop";
+} | {
+    type: "tick_error";
+    ts: number;
+    message: string;
+} | {
+    type: "schedule_registered";
+    ts: number;
+    scheduleId: string;
+    created: boolean;
+} | {
+    type: "schedule_updated";
+    ts: number;
+    scheduleId: string;
+} | {
+    type: "schedule_unregistered";
+    ts: number;
+    scheduleId: string;
+} | {
+    type: "dispatch_submitted";
+    ts: number;
+    scheduleId: string;
+    slotTs: number;
+    jobId: string;
+} | {
+    type: "dispatch_skipped";
+    ts: number;
+    scheduleId: string;
+    reason: "missing_handler" | "cas_stale";
+} | {
+    type: "dispatch_failed";
+    ts: number;
+    scheduleId: string;
+    message: string;
+} | {
+    type: "dispatch_dlq";
+    ts: number;
+    scheduleId: string;
+    slotTs: number;
+    message: string;
+} | {
+    type: "dispatch_advanced_after_failures";
+    ts: number;
+    scheduleId: string;
+    slotTs: number;
+    failures: number;
+} | {
+    type: "trigger_submitted";
+    ts: number;
+    scheduleId: string;
+    jobId: string;
+} | {
+    type: "trigger_rejected";
+    ts: number;
+    scheduleId: string;
+    reason: "missing_schedule" | "missing_handler" | "invalid_schedule";
+} | {
+    type: "trigger_failed";
+    ts: number;
+    scheduleId: string;
+    message: string;
+};
+export type SchedulerConfig = {
+    id: string;
+    prefix?: string;
+    leader?: {
+        leaseMs?: number;
+        heartbeatMs?: number;
+    };
+    dispatch?: {
+        tickMs?: number;
+        batchSize?: number;
+        maxSubmitsPerTick?: number;
+        submitRetries?: number;
+        submitBackoffBaseMs?: number;
+        submitBackoffMaxMs?: number;
+        scheduledJobKeyTtlMs?: number;
+        dlqMaxEntries?: number;
+        maxConsecutiveDispatchFailures?: number;
+    };
+    strictHandlers?: boolean;
+    onMetric?: (metric: SchedulerMetric) => void;
+};
+export type SchedulerRegisterConfig = {
+    id: string;
+    cron: string;
+    tz?: string;
+    job: JobSubmitter;
+    input: unknown;
+    misfire?: MisfirePolicy;
+    maxCatchUpRuns?: number;
+    meta?: Record<string, unknown>;
+};
+export type SchedulerUnregisterConfig = {
+    id: string;
+};
+export type SchedulerTriggerNowConfig = {
+    id: string;
+    key?: string;
+};
+export type SchedulerGetConfig = {
+    id: string;
+};
+export type SchedulerInfo = {
+    id: string;
+    cron: string;
+    tz: string;
+    misfire: MisfirePolicy;
+    maxCatchUpRuns: number;
+    jobId: string;
+    nextRunAt: number;
+    createdAt: number;
+    updatedAt: number;
+};
+export type SchedulerMetricsSnapshot = {
+    isLeader: boolean;
+    leaderEpoch: number;
+    leaderChanges: number;
+    dispatchSubmitted: number;
+    dispatchFailed: number;
+    dispatchRetried: number;
+    dispatchSkipped: number;
+    dispatchDlq: number;
+    triggerSubmitted: number;
+    triggerFailed: number;
+    triggerRejected: number;
+    tickErrors: number;
+    lastTickAt: number | null;
+};
+export type Scheduler = {
+    id: string;
+    start(): void;
+    stop(): Promise<void>;
+    register(cfg: SchedulerRegisterConfig): Promise<{
+        created: boolean;
+        updated: boolean;
+    }>;
+    unregister(cfg: SchedulerUnregisterConfig): Promise<void>;
+    triggerNow(cfg: SchedulerTriggerNowConfig): Promise<string>;
+    get(cfg: SchedulerGetConfig): Promise<SchedulerInfo | null>;
+    list(): Promise<SchedulerInfo[]>;
+    metrics(): SchedulerMetricsSnapshot;
+};
+export declare const scheduler: (config: SchedulerConfig) => Scheduler;
+export {};

package/src/browser/store.d.ts

@@ -0,0 +1,17 @@
+export interface Store {
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown, ttlMs?: number): void;
+    del(key: string): void;
+    keys(prefix?: string): string[];
+}
+export declare class MemoryStore implements Store {
+    private data;
+    private timers;
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown, ttlMs?: number): void;
+    del(key: string): void;
+    keys(prefix?: string): string[];
+    /** Clear all keys and timers (useful for tests). */
+    clear(): void;
+}
+export declare const createMemoryStore: () => MemoryStore;

package/src/browser/topic.d.ts

@@ -0,0 +1,65 @@
+import type { z } from "zod";
+import { type Store } from "./store";
+export type TopicConfig<TSchema extends z.ZodTypeAny> = {
+    id: string;
+    schema: TSchema;
+    tenantId?: string;
+    prefix?: string;
+    limits?: {
+        payloadBytes?: number;
+    };
+    retentionMs?: number;
+    store?: Store;
+};
+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>>;

package/src/registry.d.ts

@@ -0,0 +1,130 @@
+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;
+    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";
+    tenantId?: string;
+    limit?: number;
+    afterKey?: 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>>;