@equationalapplications/prisma-outbox 4.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Equational Applications
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @equationalapplications/prisma-outbox
+
+Prisma adapter for the [expo-llm-wiki](https://github.com/equationalapplications/expo-llm-wiki) transactional outbox pattern.
+
+[![npm version](https://img.shields.io/npm/v/%40equationalapplications%2Fprisma-outbox?label=prisma-outbox)](https://www.npmjs.com/package/@equationalapplications/prisma-outbox)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Polls the SQLite outbox table written by `@equationalapplications/core-llm-wiki` and syncs events to your Prisma-backed system inside a Prisma transaction, with configurable batch size, poll interval, error handling, and a concurrency guard.
+
+## Installation
+
+```bash
+npm install @equationalapplications/prisma-outbox
+# peer deps
+npm install @equationalapplications/core-llm-wiki @prisma/client
+```
+
+## Quick start
+
+```typescript
+import { PrismaOutboxWorker } from '@equationalapplications/prisma-outbox';
+import { WikiMemory } from '@equationalapplications/core-llm-wiki';
+import { PrismaClient } from '@prisma/client';
+
+const wiki = new WikiMemory(db, {
+  llmProvider,
+  config: { enableOutbox: true },
+});
+await wiki.setup();
+
+const prisma = new PrismaClient();
+
+const worker = new PrismaOutboxWorker({
+  wikiMemory: wiki,
+  prisma,
+  mapEvent: async (event, tx) => {
+    // mapEvent must be idempotent: at-least-once delivery means the same event
+    // can be retried if acknowledgement fails after the Prisma transaction commits.
+    if (event.operation === 'INSERT' && event.table_name.includes('entries')) {
+      await tx.wikiEntry.upsert({
+        where: { id: event.record_id },
+        create: { id: event.record_id, ...(event.payload as Record<string, unknown>) },
+        update: {},
+      });
+    }
+  },
+  pollIntervalMs: 5000,
+  batchSize: 100,
+  onError: (err, event) => {
+    console.error('Outbox event failed', event.id, err);
+    return false; // halt to preserve ordering; return true to skip poison-pill
+  },
+});
+
+worker.start();
+
+// On shutdown:
+worker.stop();
+```
+
+## API
+
+### `PrismaOutboxWorker`
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Begins polling on the configured interval. Idempotent. |
+| `stop()` | Clears the poll interval and any pending backlog timeout. |
+| `syncBatch()` | Manually trigger one poll cycle (useful for testing). |
+
+### `PrismaOutboxConfig`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `wikiMemory` | `WikiMemory` | required | The `WikiMemory` instance to poll. |
+| `prisma` | `PrismaLike<TTx>` | required | Any Prisma client with a `$transaction` method (your generated `PrismaClient` satisfies this). |
+| `mapEvent` | `(event, tx: TTx) => Promise<void>` | required | Maps one outbox event to Prisma operations inside a transaction. `tx` is inferred from your `PrismaClient`. |
+| `batchSize` | `number` | `100` | Max events fetched per cycle. |
+| `pollIntervalMs` | `number` | `5000` | Milliseconds between poll cycles. |
+| `onError` | `(err, event) => boolean \| undefined` | — | Return `true` to skip a failing event; `false`/`undefined` to halt. |
+| `onWorkerError` | `(err: Error) => void` | — | Called for worker-level errors (SQLite read/ack failures) not delivered to `onError`. |
+
+## How it works
+
+1. Every `WikiMemory` mutation (when `enableOutbox: true`) atomically writes an event to the SQLite `outbox` table in the same transaction as the domain write.
+2. `PrismaOutboxWorker` polls `getUnprocessedOutboxEvents()` and calls `mapEvent` inside a Prisma transaction for each event.
+3. Successfully processed event IDs are passed to `markOutboxEventsProcessed()`, which deletes them from SQLite.
+4. If a full batch is consumed without error, an immediate follow-up cycle runs (backlog optimization) to drain queues faster than the poll interval.
+
+## Limitations
+
+- **Single-instance only.** The worker does not use row-level locking or leases. Running two `PrismaOutboxWorker` instances against the same SQLite file will cause duplicate Prisma writes. Run exactly one worker per SQLite database. `mapEvent` must still be idempotent to tolerate at-least-once delivery (acknowledgement can fail after a successful Prisma commit).

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+import { WikiMemory, WikiOutboxEvent } from '@equationalapplications/core-llm-wiki';
+
+/** Minimal Prisma client shape required by the worker — avoids depending on generated types. */
+interface PrismaLike<TTx> {
+    $transaction: (fn: (tx: TTx) => Promise<void>) => Promise<unknown>;
+}
+interface PrismaOutboxConfig<TTx = unknown> {
+    /**
+     * The WikiMemory instance to poll for outbox events.
+     *
+     * **Singleton requirement:** run at most one `PrismaOutboxWorker` per SQLite database
+     * at a time. The in-process `running` guard prevents overlapping calls within a single
+     * worker, but two workers (or two processes) sharing the same database can fetch and
+     * process the same unclaimed rows concurrently, producing duplicate Prisma writes.
+     * If you need multi-process fan-out, add a claim/lease column to the outbox table.
+     */
+    wikiMemory: WikiMemory;
+    prisma: PrismaLike<TTx>;
+    /**
+     * Maps one outbox event to Prisma operations executed inside a Prisma transaction.
+     * `tx` is the Prisma transaction client passed by `prisma.$transaction`.
+     */
+    mapEvent: (event: WikiOutboxEvent, tx: TTx) => Promise<void>;
+    /** Max events fetched per poll cycle. Default: 100 */
+    batchSize?: number;
+    /** Milliseconds between poll cycles. Default: 5000 */
+    pollIntervalMs?: number;
+    /** Called when an event fails; return true to skip and continue, false/undefined to halt. */
+    onError?: (error: Error, event: WikiOutboxEvent) => boolean | undefined;
+    /** Called when a worker-level error occurs (e.g. SQLite read/ack failure). Not called for per-event errors handled by onError. */
+    onWorkerError?: (error: Error) => void;
+}
+
+declare class PrismaOutboxWorker<TTx = unknown> {
+    #private;
+    private config;
+    private timer?;
+    private backlogTimer?;
+    private running;
+    constructor(config: PrismaOutboxConfig<TTx>);
+    start(): void;
+    stop(): void;
+    syncBatch(): Promise<void>;
+}
+
+export { type PrismaLike, type PrismaOutboxConfig, PrismaOutboxWorker };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { WikiMemory, WikiOutboxEvent } from '@equationalapplications/core-llm-wiki';
+
+/** Minimal Prisma client shape required by the worker — avoids depending on generated types. */
+interface PrismaLike<TTx> {
+    $transaction: (fn: (tx: TTx) => Promise<void>) => Promise<unknown>;
+}
+interface PrismaOutboxConfig<TTx = unknown> {
+    /**
+     * The WikiMemory instance to poll for outbox events.
+     *
+     * **Singleton requirement:** run at most one `PrismaOutboxWorker` per SQLite database
+     * at a time. The in-process `running` guard prevents overlapping calls within a single
+     * worker, but two workers (or two processes) sharing the same database can fetch and
+     * process the same unclaimed rows concurrently, producing duplicate Prisma writes.
+     * If you need multi-process fan-out, add a claim/lease column to the outbox table.
+     */
+    wikiMemory: WikiMemory;
+    prisma: PrismaLike<TTx>;
+    /**
+     * Maps one outbox event to Prisma operations executed inside a Prisma transaction.
+     * `tx` is the Prisma transaction client passed by `prisma.$transaction`.
+     */
+    mapEvent: (event: WikiOutboxEvent, tx: TTx) => Promise<void>;
+    /** Max events fetched per poll cycle. Default: 100 */
+    batchSize?: number;
+    /** Milliseconds between poll cycles. Default: 5000 */
+    pollIntervalMs?: number;
+    /** Called when an event fails; return true to skip and continue, false/undefined to halt. */
+    onError?: (error: Error, event: WikiOutboxEvent) => boolean | undefined;
+    /** Called when a worker-level error occurs (e.g. SQLite read/ack failure). Not called for per-event errors handled by onError. */
+    onWorkerError?: (error: Error) => void;
+}
+
+declare class PrismaOutboxWorker<TTx = unknown> {
+    #private;
+    private config;
+    private timer?;
+    private backlogTimer?;
+    private running;
+    constructor(config: PrismaOutboxConfig<TTx>);
+    start(): void;
+    stop(): void;
+    syncBatch(): Promise<void>;
+}
+
+export { type PrismaLike, type PrismaOutboxConfig, PrismaOutboxWorker };

package/dist/index.js

@@ -0,0 +1,86 @@
+'use strict';
+
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/PrismaOutboxWorker.ts
+var _PrismaOutboxWorker_instances, workerError_fn;
+var PrismaOutboxWorker = class {
+  constructor(config) {
+    this.config = config;
+    __privateAdd(this, _PrismaOutboxWorker_instances);
+    this.running = false;
+  }
+  start() {
+    if (this.timer) return;
+    const rawInterval = this.config.pollIntervalMs ?? 5e3;
+    const pollIntervalMs = Number.isFinite(rawInterval) && rawInterval >= 1 ? Math.trunc(rawInterval) : 5e3;
+    this.timer = setInterval(
+      () => {
+        this.syncBatch().catch((err) => __privateMethod(this, _PrismaOutboxWorker_instances, workerError_fn).call(this, err));
+      },
+      pollIntervalMs
+    );
+  }
+  stop() {
+    clearInterval(this.timer);
+    this.timer = void 0;
+    clearTimeout(this.backlogTimer);
+    this.backlogTimer = void 0;
+  }
+  async syncBatch() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      const rawSize = this.config.batchSize ?? 100;
+      const batchSize = Number.isFinite(rawSize) && rawSize >= 1 ? Math.trunc(rawSize) : 100;
+      const events = await this.config.wikiMemory.getUnprocessedOutboxEvents(batchSize);
+      if (events.length === 0) return;
+      const processedIds = [];
+      let halted = false;
+      for (const event of events) {
+        try {
+          await this.config.prisma.$transaction((tx) => this.config.mapEvent(event, tx));
+          processedIds.push(event.id);
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          let skip = false;
+          try {
+            skip = this.config.onError?.(error, event) ?? false;
+          } catch {
+            halted = true;
+            break;
+          }
+          if (skip) {
+            processedIds.push(event.id);
+          } else {
+            halted = true;
+            break;
+          }
+        }
+      }
+      await this.config.wikiMemory.markOutboxEventsProcessed(processedIds);
+      if (!halted && events.length === batchSize && this.timer !== void 0) {
+        clearTimeout(this.backlogTimer);
+        this.backlogTimer = setTimeout(() => {
+          this.syncBatch().catch((err) => __privateMethod(this, _PrismaOutboxWorker_instances, workerError_fn).call(this, err));
+        }, 0);
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+};
+_PrismaOutboxWorker_instances = new WeakSet();
+workerError_fn = function(err) {
+  const error = err instanceof Error ? err : new Error(String(err));
+  this.config.onWorkerError?.(error);
+};
+
+exports.PrismaOutboxWorker = PrismaOutboxWorker;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/PrismaOutboxWorker.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { PrismaOutboxConfig } from './types';\n\nexport class PrismaOutboxWorker<TTx = unknown> {\n  private timer?: ReturnType<typeof setInterval>;\n  private backlogTimer?: ReturnType<typeof setTimeout>;\n  private running = false;\n\n  constructor(private config: PrismaOutboxConfig<TTx>) {}\n\n  start(): void {\n    if (this.timer) return;\n    const rawInterval = this.config.pollIntervalMs ?? 5000;\n    const pollIntervalMs = Number.isFinite(rawInterval) && rawInterval >= 1 ? Math.trunc(rawInterval) : 5000;\n    this.timer = setInterval(\n      () => { this.syncBatch().catch(err => this.#workerError(err)); },\n      pollIntervalMs\n    );\n  }\n\n  #workerError(err: unknown): void {\n    const error = err instanceof Error ? err : new Error(String(err));\n    this.config.onWorkerError?.(error);\n  }\n\n  stop(): void {\n    clearInterval(this.timer);\n    this.timer = undefined;\n    clearTimeout(this.backlogTimer);\n    this.backlogTimer = undefined;\n  }\n\n  async syncBatch(): Promise<void> {\n    if (this.running) return;\n    this.running = true;\n    try {\n      const rawSize = this.config.batchSize ?? 100;\n      const batchSize = Number.isFinite(rawSize) && rawSize >= 1 ? Math.trunc(rawSize) : 100;\n      const events = await this.config.wikiMemory.getUnprocessedOutboxEvents(batchSize);\n      if (events.length === 0) return;\n\n      const processedIds: string[] = [];\n      let halted = false;\n\n      for (const event of events) {\n        try {\n          await this.config.prisma.$transaction(tx => this.config.mapEvent(event, tx));\n          processedIds.push(event.id);\n        } catch (err) {\n          const error = err instanceof Error ? err : new Error(String(err));\n          let skip = false;\n          try {\n            skip = this.config.onError?.(error, event) ?? false;\n          } catch {\n            // thrown handler treated as halt; processedIds acknowledged below\n            halted = true;\n            break;\n          }\n          if (skip) {\n            processedIds.push(event.id); // acknowledge so the event isn't re-fetched\n          } else {\n            halted = true;\n            break; // halt to preserve ordering\n          }\n        }\n      }\n\n      await this.config.wikiMemory.markOutboxEventsProcessed(processedIds);\n\n      // Backlog optimization: full batch without halt means more events likely waiting.\n      // Only schedule when worker is still running (stop() not called) to avoid post-stop leaks.\n      // Use setTimeout(0) instead of setImmediate for React Native / Hermes compatibility.\n      if (!halted && events.length === batchSize && this.timer !== undefined) {\n        clearTimeout(this.backlogTimer);\n        this.backlogTimer = setTimeout(() => { this.syncBatch().catch(err => this.#workerError(err)); }, 0);\n      }\n    } finally {\n      this.running = false;\n    }\n  }\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,84 @@
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/PrismaOutboxWorker.ts
+var _PrismaOutboxWorker_instances, workerError_fn;
+var PrismaOutboxWorker = class {
+  constructor(config) {
+    this.config = config;
+    __privateAdd(this, _PrismaOutboxWorker_instances);
+    this.running = false;
+  }
+  start() {
+    if (this.timer) return;
+    const rawInterval = this.config.pollIntervalMs ?? 5e3;
+    const pollIntervalMs = Number.isFinite(rawInterval) && rawInterval >= 1 ? Math.trunc(rawInterval) : 5e3;
+    this.timer = setInterval(
+      () => {
+        this.syncBatch().catch((err) => __privateMethod(this, _PrismaOutboxWorker_instances, workerError_fn).call(this, err));
+      },
+      pollIntervalMs
+    );
+  }
+  stop() {
+    clearInterval(this.timer);
+    this.timer = void 0;
+    clearTimeout(this.backlogTimer);
+    this.backlogTimer = void 0;
+  }
+  async syncBatch() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      const rawSize = this.config.batchSize ?? 100;
+      const batchSize = Number.isFinite(rawSize) && rawSize >= 1 ? Math.trunc(rawSize) : 100;
+      const events = await this.config.wikiMemory.getUnprocessedOutboxEvents(batchSize);
+      if (events.length === 0) return;
+      const processedIds = [];
+      let halted = false;
+      for (const event of events) {
+        try {
+          await this.config.prisma.$transaction((tx) => this.config.mapEvent(event, tx));
+          processedIds.push(event.id);
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          let skip = false;
+          try {
+            skip = this.config.onError?.(error, event) ?? false;
+          } catch {
+            halted = true;
+            break;
+          }
+          if (skip) {
+            processedIds.push(event.id);
+          } else {
+            halted = true;
+            break;
+          }
+        }
+      }
+      await this.config.wikiMemory.markOutboxEventsProcessed(processedIds);
+      if (!halted && events.length === batchSize && this.timer !== void 0) {
+        clearTimeout(this.backlogTimer);
+        this.backlogTimer = setTimeout(() => {
+          this.syncBatch().catch((err) => __privateMethod(this, _PrismaOutboxWorker_instances, workerError_fn).call(this, err));
+        }, 0);
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+};
+_PrismaOutboxWorker_instances = new WeakSet();
+workerError_fn = function(err) {
+  const error = err instanceof Error ? err : new Error(String(err));
+  this.config.onWorkerError?.(error);
+};
+
+export { PrismaOutboxWorker };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/PrismaOutboxWorker.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type { PrismaOutboxConfig } from './types';\n\nexport class PrismaOutboxWorker<TTx = unknown> {\n  private timer?: ReturnType<typeof setInterval>;\n  private backlogTimer?: ReturnType<typeof setTimeout>;\n  private running = false;\n\n  constructor(private config: PrismaOutboxConfig<TTx>) {}\n\n  start(): void {\n    if (this.timer) return;\n    const rawInterval = this.config.pollIntervalMs ?? 5000;\n    const pollIntervalMs = Number.isFinite(rawInterval) && rawInterval >= 1 ? Math.trunc(rawInterval) : 5000;\n    this.timer = setInterval(\n      () => { this.syncBatch().catch(err => this.#workerError(err)); },\n      pollIntervalMs\n    );\n  }\n\n  #workerError(err: unknown): void {\n    const error = err instanceof Error ? err : new Error(String(err));\n    this.config.onWorkerError?.(error);\n  }\n\n  stop(): void {\n    clearInterval(this.timer);\n    this.timer = undefined;\n    clearTimeout(this.backlogTimer);\n    this.backlogTimer = undefined;\n  }\n\n  async syncBatch(): Promise<void> {\n    if (this.running) return;\n    this.running = true;\n    try {\n      const rawSize = this.config.batchSize ?? 100;\n      const batchSize = Number.isFinite(rawSize) && rawSize >= 1 ? Math.trunc(rawSize) : 100;\n      const events = await this.config.wikiMemory.getUnprocessedOutboxEvents(batchSize);\n      if (events.length === 0) return;\n\n      const processedIds: string[] = [];\n      let halted = false;\n\n      for (const event of events) {\n        try {\n          await this.config.prisma.$transaction(tx => this.config.mapEvent(event, tx));\n          processedIds.push(event.id);\n        } catch (err) {\n          const error = err instanceof Error ? err : new Error(String(err));\n          let skip = false;\n          try {\n            skip = this.config.onError?.(error, event) ?? false;\n          } catch {\n            // thrown handler treated as halt; processedIds acknowledged below\n            halted = true;\n            break;\n          }\n          if (skip) {\n            processedIds.push(event.id); // acknowledge so the event isn't re-fetched\n          } else {\n            halted = true;\n            break; // halt to preserve ordering\n          }\n        }\n      }\n\n      await this.config.wikiMemory.markOutboxEventsProcessed(processedIds);\n\n      // Backlog optimization: full batch without halt means more events likely waiting.\n      // Only schedule when worker is still running (stop() not called) to avoid post-stop leaks.\n      // Use setTimeout(0) instead of setImmediate for React Native / Hermes compatibility.\n      if (!halted && events.length === batchSize && this.timer !== undefined) {\n        clearTimeout(this.backlogTimer);\n        this.backlogTimer = setTimeout(() => { this.syncBatch().catch(err => this.#workerError(err)); }, 0);\n      }\n    } finally {\n      this.running = false;\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@equationalapplications/prisma-outbox",
+  "version": "4.9.0",
+  "description": "Prisma adapter for the expo-llm-wiki transactional outbox pattern.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@prisma/client": "^5.0.0 || ^6.0.0",
+    "@equationalapplications/core-llm-wiki": "4.9.0"
+  },
+  "devDependencies": {
+    "@prisma/client": "^5.0.0",
+    "prisma": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "4.1.5",
+    "@equationalapplications/core-llm-wiki": "4.9.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}