@nwire/mongo 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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,74 @@
+# @nwire/mongo
+
+> MongoDB-backed `ActorStore` + `ProjectionStore` — the canonical production store.
+
+## What it does
+
+Persists actor state and projection rows to MongoDB. Tenant-partitioned. Includes idempotent `ensureIndexes()` (`{actorName, tenant}`, `{actorName, fireAtList}` for the timer scheduler, `{projectionName, tenant}` for read paths). Tested via [`mongodb-memory-server`](https://github.com/nodkz/mongodb-memory-server) so suites run without Docker.
+
+## Install
+
+```bash
+pnpm add @nwire/mongo mongodb
+```
+
+## Quick start
+
+```ts
+import { MongoClient } from "mongodb";
+import { MongoActorStore, MongoProjectionStore } from "@nwire/mongo";
+import { createApp } from "@nwire/forge";
+
+const client = await MongoClient.connect(process.env.MONGODB_URL!);
+const db = client.db("learnflow");
+
+const actorStore = new MongoActorStore(db.collection("actors"));
+const projectionStore = new MongoProjectionStore(db.collection("projections"));
+await actorStore.ensureIndexes();
+await projectionStore.ensureIndexes();
+
+const app = createApp("learnflow", { modules, actorStore, projectionStore });
+```
+
+## API surface
+
+- `MongoActorStore(collection, options?)` — implements `ActorStore`; `.ensureIndexes()`.
+- `MongoProjectionStore(collection)` — implements `ProjectionStore`; `.ensureIndexes()`.
+- `createMongoActorStore(db, { actorCollection?, lockCollection?, lockTtlMs?, lockPollMs?, lockAcquireTimeoutMs? })` — convenience factory; defaults: `actors`, `actor_locks`, `30000`, `25`, `30000`.
+
+## Distributed locking (HA / multi-replica)
+
+Single-process deployments are safe with the default options — the runtime's
+in-memory lock chain serialises dispatches per actor key. For multi-replica
+deployments, pass a `lockCollection` so the per-`(actor, key, tenant)` critical
+section is serialised across processes:
+
+```ts
+const actorStore = new MongoActorStore(db.collection("actors"), {
+  lockCollection: db.collection("actor_locks"),
+  lockTtlMs: 30_000, // max hold time before a competitor may reclaim
+});
+await actorStore.ensureIndexes(); // creates a TTL index on actor_locks.expiresAt
+```
+
+Mechanism: `findOneAndUpdate({ _id, $or: [{ expiresAt: { $lt: now } }, { owner }] }, ..., { upsert: true })`
+atomically claims the lock or waits. On release the doc is deleted; if the
+holder crashes the TTL takes over (belt and braces — index reaps within ~1
+minute, but a live competitor reclaims as soon as `expiresAt` passes).
+
+## When to use
+
+Production workloads with stateful actors and read-model projections.
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```

package/dist/mongo-store.d.ts

@@ -0,0 +1,130 @@
+/**
+ * MongoDB-backed actor + projection stores.
+ *
+ *   const client = new MongoClient(env.MONGODB_URL)
+ *   await client.connect()
+ *   const db = client.db('lemida')
+ *   const actorStore = new MongoActorStore(db.collection('amit_actors'))
+ *   const projectionStore = new MongoProjectionStore(db.collection('amit_projections'))
+ *   const app = createApp({ modules, actorStore, projectionStore })
+ *
+ * Schemas:
+ *   actors collection:
+ *     _id:           "{tenant}::{actorName}::{key}"   (compound PK)
+ *     actorName:     string                            (indexed for listInstances)
+ *     key:           string
+ *     tenant:        string                            (indexed for partition queries)
+ *     state:         string
+ *     data:          unknown                           (the actor's typed data)
+ *     activeTimers:  Record<string, ActorTimerHandle>
+ *     fireAtList:    number[]                          (denormalized fireAt values
+ *                                                        for index-friendly timer
+ *                                                        scheduler queries)
+ *
+ *   projections collection:
+ *     _id:           "{tenant}::{projectionName}"     (compound PK)
+ *     projectionName: string
+ *     tenant:        string
+ *     state:         unknown
+ *
+ * Recommended indexes (callers create at boot):
+ *   actors:       { actorName: 1, tenant: 1 }
+ *                 { actorName: 1, "fireAtList": 1 }   for timer scheduler
+ *   projections:  { projectionName: 1, tenant: 1 }
+ */
+import type { Collection, Db, Document } from "mongodb";
+import type * as forge from "@nwire/forge";
+type ActorStore = forge.ActorStore;
+type ActorInstance = forge.ActorInstance;
+type ProjectionStore = forge.ProjectionStore;
+interface LockDoc extends Document {
+    _id: string;
+    owner: string;
+    expiresAt: Date;
+}
+export interface MongoActorStoreOptions {
+    /**
+     * Collection that backs the per-(actor, key, tenant) distributed lock.
+     * Required for multi-replica deployments. Without it `lockKey` falls back
+     * to a no-op — safe for single-process, dangerous under HA.
+     */
+    readonly lockCollection?: Collection<LockDoc> | AnyCollection;
+    /**
+     * Lock TTL in milliseconds — the maximum time a single critical section
+     * may hold the lock. A crashed holder's lock becomes claimable after this.
+     * Keep it well above the longest expected load → reduce → save window.
+     * Default: 30s.
+     */
+    readonly lockTtlMs?: number;
+    /**
+     * Polling interval while waiting for a contended lock. Default: 25ms.
+     * Lower values reduce wait latency at the cost of more Mongo round-trips.
+     */
+    readonly lockPollMs?: number;
+    /**
+     * How long to keep retrying before giving up. Default: 30s.
+     * Acquisition failure throws — the runtime treats it as a transient
+     * error and the dispatching transport decides retry semantics.
+     */
+    readonly lockAcquireTimeoutMs?: number;
+}
+type AnyCollection = Collection<any>;
+export declare class MongoActorStore implements ActorStore {
+    private readonly collection;
+    private readonly lockCollection;
+    private readonly lockTtlMs;
+    private readonly lockPollMs;
+    private readonly lockAcquireTimeoutMs;
+    /**
+     * Unique identifier for this process/instance. Stamped on every lock
+     * acquisition so a holder can renew (no-contention re-entry) and so
+     * release only removes its own lock — never a stranger's.
+     */
+    private readonly ownerId;
+    constructor(collection: AnyCollection, options?: MongoActorStoreOptions);
+    /**
+     * Create the recommended indexes for this store. Call once at boot. Safe
+     * to call repeatedly — Mongo's `createIndex` is idempotent.
+     *
+     * If a lock collection is configured, this also creates a TTL index on
+     * `expiresAt` so abandoned locks (e.g. from a crashed process) are
+     * eventually reaped by Mongo's background TTL monitor — a belt-and-braces
+     * safety net on top of the per-acquire expiry check.
+     */
+    ensureIndexes(): Promise<void>;
+    load(actorName: string, key: string, tenant?: string): Promise<ActorInstance | null>;
+    save(instance: ActorInstance): Promise<void>;
+    exists(actorName: string, key: string, tenant?: string): Promise<boolean>;
+    listInstances(actorName: string, tenant?: string): Promise<readonly ActorInstance[]>;
+    /**
+     * Acquire a distributed lock on `(actorName, key, tenant)` and return a
+     * release function. Multi-replica safe: the lock doc lives in Mongo and
+     * is claimed atomically via `findOneAndUpdate` with upsert. Holds the
+     * lock for at most `lockTtlMs` — if a holder crashes, a competitor can
+     * reclaim once the stored `expiresAt` passes.
+     *
+     * Without a configured `lockCollection` this is a no-op (single-process
+     * deployments). For HA, always pass `lockCollection`.
+     */
+    lockKey(actorName: string, key: string, tenant?: string): Promise<() => void>;
+}
+/**
+ * Convenience: derive collections + lock collection from a single `Db`.
+ * Defaults match the docs; opt out of the lock collection by passing
+ * `lockCollection: false` (no-op locking — single-process mode).
+ */
+export declare function createMongoActorStore(db: Db, options?: {
+    actorCollection?: string;
+    lockCollection?: string | false;
+    lockTtlMs?: number;
+    lockPollMs?: number;
+    lockAcquireTimeoutMs?: number;
+}): MongoActorStore;
+export declare class MongoProjectionStore implements ProjectionStore {
+    private readonly collection;
+    constructor(collection: AnyCollection);
+    ensureIndexes(): Promise<void>;
+    load<TState = unknown>(projectionName: string, tenant?: string): Promise<TState | null>;
+    save<TState = unknown>(projectionName: string, state: TState, tenant?: string): Promise<void>;
+}
+export {};

package/dist/mongo-store.js

@@ -0,0 +1,229 @@
+/**
+ * MongoDB-backed actor + projection stores.
+ *
+ *   const client = new MongoClient(env.MONGODB_URL)
+ *   await client.connect()
+ *   const db = client.db('lemida')
+ *   const actorStore = new MongoActorStore(db.collection('amit_actors'))
+ *   const projectionStore = new MongoProjectionStore(db.collection('amit_projections'))
+ *   const app = createApp({ modules, actorStore, projectionStore })
+ *
+ * Schemas:
+ *   actors collection:
+ *     _id:           "{tenant}::{actorName}::{key}"   (compound PK)
+ *     actorName:     string                            (indexed for listInstances)
+ *     key:           string
+ *     tenant:        string                            (indexed for partition queries)
+ *     state:         string
+ *     data:          unknown                           (the actor's typed data)
+ *     activeTimers:  Record<string, ActorTimerHandle>
+ *     fireAtList:    number[]                          (denormalized fireAt values
+ *                                                        for index-friendly timer
+ *                                                        scheduler queries)
+ *
+ *   projections collection:
+ *     _id:           "{tenant}::{projectionName}"     (compound PK)
+ *     projectionName: string
+ *     tenant:        string
+ *     state:         unknown
+ *
+ * Recommended indexes (callers create at boot):
+ *   actors:       { actorName: 1, tenant: 1 }
+ *                 { actorName: 1, "fireAtList": 1 }   for timer scheduler
+ *   projections:  { projectionName: 1, tenant: 1 }
+ */
+import { randomUUID } from "node:crypto";
+function actorPk(actorName, key, tenant) {
+    return `${tenant}::${actorName}::${key}`;
+}
+function projectionPk(projectionName, tenant) {
+    return `${tenant}::${projectionName}`;
+}
+function lockPk(actorName, key, tenant) {
+    return `${tenant}::${actorName}::${key}`;
+}
+const DEFAULT_LOCK_TTL_MS = 30_000;
+const DEFAULT_LOCK_POLL_MS = 25;
+const DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS = 30_000;
+export class MongoActorStore {
+    collection;
+    lockCollection;
+    lockTtlMs;
+    lockPollMs;
+    lockAcquireTimeoutMs;
+    /**
+     * Unique identifier for this process/instance. Stamped on every lock
+     * acquisition so a holder can renew (no-contention re-entry) and so
+     * release only removes its own lock — never a stranger's.
+     */
+    ownerId = randomUUID();
+    constructor(collection, options = {}) {
+        this.collection = collection;
+        this.lockCollection = options.lockCollection ?? null;
+        this.lockTtlMs = options.lockTtlMs ?? DEFAULT_LOCK_TTL_MS;
+        this.lockPollMs = options.lockPollMs ?? DEFAULT_LOCK_POLL_MS;
+        this.lockAcquireTimeoutMs = options.lockAcquireTimeoutMs ?? DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS;
+    }
+    /**
+     * Create the recommended indexes for this store. Call once at boot. Safe
+     * to call repeatedly — Mongo's `createIndex` is idempotent.
+     *
+     * If a lock collection is configured, this also creates a TTL index on
+     * `expiresAt` so abandoned locks (e.g. from a crashed process) are
+     * eventually reaped by Mongo's background TTL monitor — a belt-and-braces
+     * safety net on top of the per-acquire expiry check.
+     */
+    async ensureIndexes() {
+        await this.collection.createIndex({ actorName: 1, tenant: 1 });
+        await this.collection.createIndex({ actorName: 1, fireAtList: 1 });
+        if (this.lockCollection) {
+            // expireAfterSeconds: 0 means "expire AT the timestamp stored in
+            // expiresAt". Mongo's TTL monitor runs ~once/minute, so this is a
+            // crash-recovery fallback only — live contention relies on the
+            // per-acquire `expiresAt < now` check inside findOneAndUpdate.
+            await this.lockCollection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+        }
+    }
+    async load(actorName, key, tenant = "") {
+        const doc = await this.collection.findOne({ _id: actorPk(actorName, key, tenant) });
+        if (!doc)
+            return null;
+        return docToInstance(doc);
+    }
+    async save(instance) {
+        const fireAtList = Object.values(instance.activeTimers).map((t) => t.fireAt);
+        const doc = {
+            _id: actorPk(instance.actorName, instance.key, instance.tenant),
+            actorName: instance.actorName,
+            key: instance.key,
+            tenant: instance.tenant,
+            state: instance.state,
+            data: instance.data,
+            version: instance.version,
+            activeTimers: instance.activeTimers,
+            fireAtList,
+        };
+        await this.collection.replaceOne({ _id: doc._id }, doc, { upsert: true });
+    }
+    async exists(actorName, key, tenant = "") {
+        const count = await this.collection.countDocuments({ _id: actorPk(actorName, key, tenant) }, { limit: 1 });
+        return count > 0;
+    }
+    async listInstances(actorName, tenant) {
+        const filter = { actorName };
+        if (tenant !== undefined)
+            filter.tenant = tenant;
+        const docs = await this.collection.find(filter).toArray();
+        return docs.map(docToInstance);
+    }
+    /**
+     * Acquire a distributed lock on `(actorName, key, tenant)` and return a
+     * release function. Multi-replica safe: the lock doc lives in Mongo and
+     * is claimed atomically via `findOneAndUpdate` with upsert. Holds the
+     * lock for at most `lockTtlMs` — if a holder crashes, a competitor can
+     * reclaim once the stored `expiresAt` passes.
+     *
+     * Without a configured `lockCollection` this is a no-op (single-process
+     * deployments). For HA, always pass `lockCollection`.
+     */
+    async lockKey(actorName, key, tenant = "") {
+        if (!this.lockCollection)
+            return () => { };
+        const lockId = lockPk(actorName, key, tenant);
+        const lockCollection = this.lockCollection;
+        const deadline = Date.now() + this.lockAcquireTimeoutMs;
+        while (true) {
+            const now = new Date();
+            const expiresAt = new Date(now.getTime() + this.lockTtlMs);
+            try {
+                // Atomic claim: match either (a) no existing doc (upsert path),
+                // (b) an expired doc (previous holder's TTL passed), or (c) our
+                // own doc (re-entry by the same owner — safe to refresh). Any
+                // other state means a live competitor holds the lock and we wait.
+                const result = await lockCollection.findOneAndUpdate({
+                    _id: lockId,
+                    $or: [{ expiresAt: { $lt: now } }, { owner: this.ownerId }],
+                }, { $set: { owner: this.ownerId, expiresAt } }, { upsert: true, returnDocument: "after" });
+                if (result && result.owner === this.ownerId) {
+                    return async () => {
+                        // Release only if we still own it — never delete a stranger's
+                        // lock. If our TTL expired and a competitor claimed it, our
+                        // delete becomes a harmless no-op.
+                        await lockCollection.deleteOne({ _id: lockId, owner: this.ownerId });
+                    };
+                }
+            }
+            catch (err) {
+                // E11000 duplicate-key races happen when two acquirers upsert
+                // simultaneously; one wins, the other should retry. Anything else
+                // is a real failure — surface it.
+                if (!isDuplicateKeyError(err))
+                    throw err;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`MongoActorStore.lockKey: timed out acquiring lock for ${lockId} after ${this.lockAcquireTimeoutMs}ms`);
+            }
+            await sleep(this.lockPollMs);
+        }
+    }
+}
+/**
+ * Convenience: derive collections + lock collection from a single `Db`.
+ * Defaults match the docs; opt out of the lock collection by passing
+ * `lockCollection: false` (no-op locking — single-process mode).
+ */
+export function createMongoActorStore(db, options = {}) {
+    const actorCollection = options.actorCollection ?? "actors";
+    const lockCollectionName = options.lockCollection === undefined ? "actor_locks" : options.lockCollection;
+    const lockCollection = lockCollectionName === false ? undefined : db.collection(lockCollectionName);
+    return new MongoActorStore(db.collection(actorCollection), {
+        lockCollection,
+        lockTtlMs: options.lockTtlMs,
+        lockPollMs: options.lockPollMs,
+        lockAcquireTimeoutMs: options.lockAcquireTimeoutMs,
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isDuplicateKeyError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === 11000);
+}
+export class MongoProjectionStore {
+    collection;
+    constructor(collection) {
+        this.collection = collection;
+    }
+    async ensureIndexes() {
+        await this.collection.createIndex({ projectionName: 1, tenant: 1 });
+    }
+    async load(projectionName, tenant = "") {
+        const doc = await this.collection.findOne({ _id: projectionPk(projectionName, tenant) });
+        if (!doc)
+            return null;
+        return doc.state;
+    }
+    async save(projectionName, state, tenant = "") {
+        const doc = {
+            _id: projectionPk(projectionName, tenant),
+            projectionName,
+            tenant,
+            state,
+        };
+        await this.collection.replaceOne({ _id: doc._id }, doc, { upsert: true });
+    }
+}
+function docToInstance(doc) {
+    return {
+        actorName: doc.actorName,
+        key: doc.key,
+        tenant: doc.tenant,
+        state: doc.state,
+        data: doc.data,
+        version: doc.version ?? 0,
+        activeTimers: doc.activeTimers,
+    };
+}

package/dist/store-mongo.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@nwire/mongo` — MongoDB-backed ActorStore + ProjectionStore.
+ *
+ *   import { MongoActorStore, MongoProjectionStore } from '@nwire/mongo'
+ *   import { MongoClient } from 'mongodb'
+ *
+ *   const client = await MongoClient.connect(env.MONGODB_URL)
+ *   const db = client.db('learnflow')
+ *   const actorStore = new MongoActorStore(db.collection('actors'))
+ *   const projectionStore = new MongoProjectionStore(db.collection('projections'))
+ *   await actorStore.ensureIndexes()
+ *   await projectionStore.ensureIndexes()
+ *
+ *   const app = createApp({ modules, actorStore, projectionStore })
+ *
+ * Indexes (idempotent):
+ *   actors:       { actorName: 1, tenant: 1 }
+ *                 { actorName: 1, fireAtList: 1 }   ← for timer scheduler
+ *   projections:  { projectionName: 1, tenant: 1 }
+ */
+export { MongoActorStore, MongoProjectionStore, createMongoActorStore, type MongoActorStoreOptions, } from "./mongo-store.js";

package/dist/store-mongo.js

@@ -0,0 +1,21 @@
+/**
+ * `@nwire/mongo` — MongoDB-backed ActorStore + ProjectionStore.
+ *
+ *   import { MongoActorStore, MongoProjectionStore } from '@nwire/mongo'
+ *   import { MongoClient } from 'mongodb'
+ *
+ *   const client = await MongoClient.connect(env.MONGODB_URL)
+ *   const db = client.db('learnflow')
+ *   const actorStore = new MongoActorStore(db.collection('actors'))
+ *   const projectionStore = new MongoProjectionStore(db.collection('projections'))
+ *   await actorStore.ensureIndexes()
+ *   await projectionStore.ensureIndexes()
+ *
+ *   const app = createApp({ modules, actorStore, projectionStore })
+ *
+ * Indexes (idempotent):
+ *   actors:       { actorName: 1, tenant: 1 }
+ *                 { actorName: 1, fireAtList: 1 }   ← for timer scheduler
+ *   projections:  { projectionName: 1, tenant: 1 }
+ */
+export { MongoActorStore, MongoProjectionStore, createMongoActorStore, } from "./mongo-store.js";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@nwire/mongo",
+  "version": "0.10.0",
+  "description": "Nwire — MongoDB adapters for ActorStore + ProjectionStore. (actorName, key, tenant) compound PK; fireAtList denormalized for indexable timer-scheduler queries; ensureIndexes() idempotent.",
+  "keywords": [
+    "actor-store",
+    "adapter",
+    "mongodb",
+    "nwire",
+    "projection-store",
+    "store"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/store-mongo.js",
+  "types": "./dist/store-mongo.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/store-mongo.js",
+      "types": "./dist/store-mongo.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "mongodb": "^6.21.0",
+    "@nwire/forge": "0.10.0",
+    "@nwire/envelope": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "mongodb-memory-server": "^10.1.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}