@vielzeug/postmaster 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export interface RetryPolicy {
+    readonly delay?: (attempt: number) => number;
+    readonly maxAttempts: number;
+    readonly shouldRetry: (error: unknown, attempt: number) => boolean;
+}
+export interface JobContext {
+    readonly attempt: number;
+    readonly entryId: string;
+    readonly key: string;
+    readonly signal: AbortSignal;
+}
+export type Validate<T> = ((value: unknown) => T) | {
+    parse(value: unknown): T;
+};
+export interface JobDefinition<T> {
+    readonly execute: (payload: T, context: JobContext) => Promise<void>;
+    readonly key: (payload: T) => string;
+    readonly migrate?: (payload: unknown, fromVersion: number) => unknown;
+    readonly retry?: RetryPolicy;
+    readonly validate?: Validate<T>;
+    readonly version: number;
+}
+export type JobDefinitions = Record<string, JobDefinition<unknown>>;
+export type InferJobPayload<J> = J extends JobDefinition<infer T> ? T : never;
+export type EntryStatus = 'dead-letter' | 'queued' | 'running';
+export interface StoredFailure {
+    readonly message: string;
+    readonly name: string;
+    readonly occurredAt: number;
+}
+export interface StoredJob {
+    readonly attempts: number;
+    readonly availableAt: number;
+    readonly createdAt: number;
+    readonly failure?: StoredFailure;
+    readonly id: string;
+    readonly key: string;
+    readonly leaseExpiresAt?: number;
+    readonly name: string;
+    readonly ownerId?: string;
+    readonly payload: JsonValue;
+    readonly status: EntryStatus;
+    readonly updatedAt: number;
+    readonly version: number;
+}
+export type PostmasterEntry = Pick<StoredJob, 'attempts' | 'availableAt' | 'createdAt' | 'failure' | 'id' | 'key' | 'name' | 'status' | 'updatedAt' | 'version'>;
+export interface EntryFilter {
+    readonly status?: EntryStatus;
+}
+export interface PostmasterStats {
+    readonly deadLetter: number;
+    readonly queued: number;
+    readonly running: number;
+}
+export type RetryResult = {
+    readonly status: 'not-dead-letter' | 'not-found' | 'running';
+} | {
+    readonly entry: PostmasterEntry;
+    readonly status: 'retried';
+};
+export type RemoveResult = {
+    readonly status: 'not-found' | 'running';
+} | {
+    readonly id: string;
+    readonly status: 'removed';
+};
+/**
+ * Transactional operations available inside `PostmasterStore.transact()`.
+ * Stores implement these primitives; the processor owns all ownership/transition logic.
+ */
+export interface StoreTx {
+    countByStatus(): Promise<PostmasterStats>;
+    delete(id: string): Promise<void>;
+    /** Earliest claimable job: queued with `availableAt <= now`, or running with expired lease. Ordered by availableAt then createdAt. */
+    findClaimable(now: number): Promise<StoredJob | undefined>;
+    /** Earliest future wake time across queued `availableAt > now` and running `leaseExpiresAt > now`, or undefined if none. */
+    findNextWake(now: number): Promise<number | undefined>;
+    get(id: string): Promise<StoredJob | undefined>;
+    put(entry: StoredJob): Promise<void>;
+}
+export interface PostmasterStore {
+    readonly disposalSignal: AbortSignal;
+    dispose(): Promise<void>;
+    readonly disposed: boolean;
+    list(filter?: EntryFilter): Promise<StoredJob[]>;
+    subscribe(listener: () => void): () => void;
+    transact<T>(fn: (tx: StoreTx) => Promise<T>): Promise<T>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export type PostmasterEvent = {
+    readonly entry: PostmasterEntry;
+    readonly type: 'enqueued' | 'started' | 'completed' | 'retry-scheduled' | 'dead-lettered';
+} | {
+    readonly id: string;
+    readonly type: 'removed' | 'lease-lost';
+} | {
+    readonly error: Error;
+    readonly type: 'processor-error';
+} | {
+    readonly type: 'dispose';
+};
+export interface FlushResult {
+    readonly completed: number;
+    readonly deadLettered: number;
+    readonly processed: number;
+    readonly retryScheduled: number;
+}
+export interface CreatePostmasterOptions<J extends JobDefinitions> {
+    readonly clock?: () => number;
+    readonly jobs: J;
+    readonly leaseDuration?: number;
+    readonly signal?: AbortSignal;
+    readonly store: PostmasterStore;
+}
+export interface Postmaster<J extends JobDefinitions> {
+    readonly disposalSignal: AbortSignal;
+    dispose(): Promise<void>;
+    readonly disposed: boolean;
+    enqueue<K extends keyof J & string>(name: K, payload: InferJobPayload<J[K]>): Promise<PostmasterEntry>;
+    flush(options?: {
+        signal?: AbortSignal;
+    }): Promise<FlushResult>;
+    list(filter?: EntryFilter): Promise<PostmasterEntry[]>;
+    remove(id: string): Promise<RemoveResult>;
+    retry(id: string): Promise<RetryResult>;
+    start(): Promise<void>;
+    stats(): Promise<PostmasterStats>;
+    tap(handler: (event: PostmasterEvent) => void, options?: {
+        readonly signal?: AbortSignal;
+    }): () => void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@vielzeug/postmaster",
+  "version": "2.0.0",
+  "description": "Typed durable job outbox with leased processing, retries, and dead-letter recovery",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/helmuthdu/vielzeug",
+    "directory": "packages/postmaster"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./indexeddb": {
+      "import": "./dist/indexeddb.js",
+      "require": "./dist/indexeddb.cjs",
+      "types": "./dist/indexeddb.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs",
+      "types": "./dist/testing.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "indexeddb": [
+        "dist/indexeddb.d.ts"
+      ],
+      "testing": [
+        "dist/testing.d.ts"
+      ]
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:bundle": "vite build --config vite.bundle.config.ts",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "biome check --write src",
+    "lint": "biome ci src",
+    "prepublishOnly": "pnpm run build",
+    "preview": "vite preview",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@vielzeug/arsenal": "2.1.0",
+    "@vielzeug/vault": "2.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "fake-indexeddb": "^6.2.5",
+    "typescript": "^6.0.3",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10"
+  }
+}