@valentinkolb/sync 2.1.2 → 2.2.0

package/package.json

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

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>>;