cooper-stack 0.5.3 → 0.5.4

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { database, type DatabaseClient } from "./db.js";
 export { middleware, cooper } from "./middleware.js";
 export { authHandler } from "./auth.js";
 export { topic, type Topic } from "./pubsub.js";
+export { closeNats } from "./nats.js";
 export { cron } from "./cron.js";
 export { cache, type CacheClient } from "./cache.js";
 export { bucket, type BucketClient } from "./storage.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -4,6 +4,7 @@ export { database } from "./db.js";
 export { middleware, cooper } from "./middleware.js";
 export { authHandler } from "./auth.js";
 export { topic } from "./pubsub.js";
+export { closeNats } from "./nats.js";
 export { cron } from "./cron.js";
 export { cache } from "./cache.js";
 export { bucket } from "./storage.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAuB,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,EAAc,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAuB,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,EAAc,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/nats.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NATS Connection Manager — singleton lazy connection to embedded NATS.
+ *
+ * JetStream is used for durable pub/sub with delivery guarantees.
+ * Falls back gracefully if NATS is unavailable (logs warning once).
+ */
+import { type NatsConnection, type JetStreamClient, type JetStreamManager } from "nats";
+declare const jc: import("nats").Codec<unknown>;
+export declare function ensureConnected(): Promise<boolean>;
+export declare function getJetStream(): JetStreamClient | null;
+export declare function getJetStreamManager(): JetStreamManager | null;
+export declare function getConnection(): NatsConnection | null;
+export { jc as jsonCodec };
+/**
+ * Sanitize a topic name into a valid NATS stream name.
+ * NATS streams: alphanumeric + dash + underscore only.
+ */
+export declare function streamName(topicName: string): string;
+/**
+ * Sanitize a subscriber name into a valid NATS durable consumer name.
+ */
+export declare function consumerName(subscriberName: string): string;
+/**
+ * Ensure a JetStream stream exists for a topic.
+ * Creates it if missing, no-ops if it already exists.
+ */
+export declare function ensureStream(topicName: string, config?: {
+    dedup?: boolean;
+}): Promise<void>;
+/**
+ * Graceful shutdown — drain and close the connection.
+ */
+export declare function closeNats(): Promise<void>;
+//# sourceMappingURL=nats.d.ts.map

package/dist/nats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nats.d.ts","sourceRoot":"","sources":["../src/nats.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAKtB,MAAM,MAAM,CAAC;AAQd,QAAA,MAAM,EAAE,+BAAc,CAAC;AA0BvB,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAOxD;AAED,wBAAgB,YAAY,IAAI,eAAe,GAAG,IAAI,CAErD;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED,wBAAgB,aAAa,IAAI,cAAc,GAAG,IAAI,CAErD;AAED,OAAO,EAAE,EAAE,IAAI,SAAS,EAAE,CAAC;AAE3B;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAI/C"}

package/dist/nats.js

@@ -0,0 +1,104 @@
+/**
+ * NATS Connection Manager — singleton lazy connection to embedded NATS.
+ *
+ * JetStream is used for durable pub/sub with delivery guarantees.
+ * Falls back gracefully if NATS is unavailable (logs warning once).
+ */
+import { connect, JSONCodec, RetentionPolicy, StorageType, } from "nats";
+let nc = null;
+let js = null;
+let jsm = null;
+let connectPromise = null;
+let warnedOnce = false;
+const jc = JSONCodec();
+function getNatsUrl() {
+    return process.env.COOPER_NATS_URL ?? "nats://localhost:4222";
+}
+async function doConnect() {
+    try {
+        nc = await connect({ servers: getNatsUrl(), maxReconnectAttempts: 5 });
+        js = nc.jetstream();
+        jsm = await nc.jetstreamManager();
+        return true;
+    }
+    catch (err) {
+        if (!warnedOnce) {
+            console.warn(`[cooper] NATS unavailable at ${getNatsUrl()} — pub/sub will use in-memory fallback. ${err.message}`);
+            warnedOnce = true;
+        }
+        nc = null;
+        js = null;
+        jsm = null;
+        return false;
+    }
+}
+export async function ensureConnected() {
+    if (nc && !nc.isClosed())
+        return true;
+    if (connectPromise)
+        return connectPromise;
+    connectPromise = doConnect().finally(() => {
+        connectPromise = null;
+    });
+    return connectPromise;
+}
+export function getJetStream() {
+    return js;
+}
+export function getJetStreamManager() {
+    return jsm;
+}
+export function getConnection() {
+    return nc;
+}
+export { jc as jsonCodec };
+/**
+ * Sanitize a topic name into a valid NATS stream name.
+ * NATS streams: alphanumeric + dash + underscore only.
+ */
+export function streamName(topicName) {
+    return "COOPER_" + topicName.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+}
+/**
+ * Sanitize a subscriber name into a valid NATS durable consumer name.
+ */
+export function consumerName(subscriberName) {
+    return subscriberName.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/**
+ * Ensure a JetStream stream exists for a topic.
+ * Creates it if missing, no-ops if it already exists.
+ */
+export async function ensureStream(topicName, config) {
+    if (!jsm)
+        return;
+    const name = streamName(topicName);
+    const subject = `cooper.topic.${topicName}`;
+    try {
+        await jsm.streams.info(name);
+    }
+    catch {
+        await jsm.streams.add({
+            name,
+            subjects: [subject],
+            retention: RetentionPolicy.Interest,
+            max_msgs: -1,
+            max_bytes: -1,
+            max_age: 7 * 24 * 60 * 60 * 1_000_000_000, // 7 days in nanos
+            storage: StorageType.File,
+            num_replicas: 1,
+            duplicate_window: config?.dedup
+                ? 2 * 60 * 1_000_000_000 // 2 min dedup window
+                : 0,
+        });
+    }
+}
+/**
+ * Graceful shutdown — drain and close the connection.
+ */
+export async function closeNats() {
+    if (nc && !nc.isClosed()) {
+        await nc.drain();
+    }
+}
+//# sourceMappingURL=nats.js.map

package/dist/nats.js.map

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

package/dist/pubsub.d.ts

@@ -19,6 +19,9 @@ export interface Topic<T> {
  *   { deliveryGuarantee: "at-least-once" }
  * );
  * ```
+ *
+ * Local dev uses embedded NATS with JetStream for durable delivery.
+ * Falls back to in-memory if NATS is unavailable.
  */
 export declare function topic<T = any>(name: string, config?: TopicConfig): Topic<T>;
 //# sourceMappingURL=pubsub.d.ts.map

package/dist/pubsub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pubsub.d.ts","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,GAAG,CAAC;CACvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAyC3E"}
+{"version":3,"file":"pubsub.d.ts","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,GAAG,CAAC;CACvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CA2I3E"}

package/dist/pubsub.js

@@ -1,4 +1,6 @@
 import { registry } from "./registry.js";
+import { ensureConnected, getJetStream, getJetStreamManager, jsonCodec, streamName, consumerName, ensureStream, } from "./nats.js";
+import { headers as natsHeaders, AckPolicy } from "nats";
 /**
  * Declare a typed Pub/Sub topic.
  *
@@ -8,15 +10,84 @@ import { registry } from "./registry.js";
  *   { deliveryGuarantee: "at-least-once" }
  * );
  * ```
+ *
+ * Local dev uses embedded NATS with JetStream for durable delivery.
+ * Falls back to in-memory if NATS is unavailable.
  */
 export function topic(name, config) {
     const subscribers = new Map();
+    const useDedup = config?.deliveryGuarantee === "exactly-once";
+    const subject = `cooper.topic.${name}`;
+    // Track whether JetStream consumers have been started
+    const activeConsumers = new Set();
+    /**
+     * Start a JetStream pull consumer for a subscriber.
+     * Runs in the background, processing messages until the connection closes.
+     */
+    async function startConsumer(subName, handler, concurrency) {
+        if (activeConsumers.has(subName))
+            return;
+        activeConsumers.add(subName);
+        const js = getJetStream();
+        const jsm = getJetStreamManager();
+        if (!js || !jsm)
+            return;
+        const stream = streamName(name);
+        const durable = consumerName(subName);
+        // Ensure consumer exists
+        try {
+            await jsm.consumers.info(stream, durable);
+        }
+        catch {
+            await jsm.consumers.add(stream, {
+                durable_name: durable,
+                ack_policy: AckPolicy.Explicit,
+                max_ack_pending: concurrency,
+                filter_subject: subject,
+            });
+        }
+        const consumer = await js.consumers.get(stream, durable);
+        // Process messages in the background
+        (async () => {
+            try {
+                const messages = await consumer.consume();
+                for await (const msg of messages) {
+                    try {
+                        const data = jsonCodec.decode(msg.data);
+                        await handler(data);
+                        msg.ack();
+                    }
+                    catch (err) {
+                        console.error(`[cooper] Subscriber "${subName}" on topic "${name}" failed:`, err);
+                        // NAK with delay for retry (5 second backoff)
+                        msg.nak(5000);
+                    }
+                }
+            }
+            catch (err) {
+                // Consumer iteration ended (connection closed, etc.)
+                activeConsumers.delete(subName);
+                if (!err.message?.includes("closed")) {
+                    console.error(`[cooper] Consumer "${subName}" on topic "${name}" stopped:`, err);
+                }
+            }
+        })();
+    }
     const t = {
         async publish(data) {
-            // In local dev, deliver directly to subscribers
-            // In production, publish to NATS/SNS/Pub/Sub
-            const natsUrl = process.env.COOPER_NATS_URL ?? "nats://localhost:4222";
-            // Direct local delivery for development
+            const connected = await ensureConnected();
+            if (connected) {
+                const js = getJetStream();
+                if (js) {
+                    await ensureStream(name, { dedup: useDedup });
+                    const headers = useDedup && data && typeof data === "object"
+                        ? createDedup(data, config?.orderBy)
+                        : undefined;
+                    await js.publish(subject, jsonCodec.encode(data), { headers });
+                    return;
+                }
+            }
+            // Fallback: in-memory delivery
             for (const [subName, sub] of subscribers) {
                 try {
                     await sub.handler(data);
@@ -35,6 +106,16 @@ export function topic(name, config) {
                 name,
                 subscribers,
             });
+            // Start JetStream consumer in the background
+            const concurrency = subConfig.concurrency ?? 1;
+            ensureConnected().then(async (connected) => {
+                if (connected) {
+                    await ensureStream(name, { dedup: useDedup });
+                    startConsumer(subName, subConfig.handler, concurrency).catch((err) => {
+                        console.error(`[cooper] Failed to start consumer "${subName}":`, err);
+                    });
+                }
+            });
             return {
                 _cooper_type: "subscription",
                 topic: name,
@@ -45,4 +126,27 @@ export function topic(name, config) {
     registry.registerTopic(name, { name, subscribers });
     return t;
 }
+/**
+ * Create NATS headers for exactly-once dedup.
+ * Uses Nats-Msg-Id header — JetStream deduplicates within the stream's
+ * duplicate_window based on this ID.
+ */
+function createDedup(data, orderBy) {
+    const h = natsHeaders();
+    // Generate a deterministic dedup ID.
+    // If an ordering key is set, use that field's value as the dedup key.
+    // Otherwise, hash the entire payload for content-based dedup.
+    if (orderBy && data[orderBy] !== undefined) {
+        h.set("Nats-Msg-Id", `${orderBy}-${String(data[orderBy])}`);
+    }
+    else {
+        const payload = JSON.stringify(data);
+        let hash = 0;
+        for (let i = 0; i < payload.length; i++) {
+            hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;
+        }
+        h.set("Nats-Msg-Id", `msg-${Math.abs(hash)}`);
+    }
+    return h;
+}
 //# sourceMappingURL=pubsub.js.map

package/dist/pubsub.js.map

@@ -1 +1 @@
-{"version":3,"file":"pubsub.js","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAiBzC;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CAAU,IAAY,EAAE,MAAoB;IAC/D,MAAM,WAAW,GAAG,IAAI,GAAG,EAA+C,CAAC;IAE3E,MAAM,CAAC,GAAa;QAClB,KAAK,CAAC,OAAO,CAAC,IAAO;YACnB,gDAAgD;YAChD,6CAA6C;YAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,uBAAuB,CAAC;YAEvE,wCAAwC;YACxC,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,WAAW,EAAE,CAAC;gBACzC,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,WAAW,EAAE,GAAG,CAAC,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QAED,SAAS,CAAC,OAAe,EAAE,SAA0B;YACnD,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE;gBACvB,OAAO,EAAE,SAAS,CAAC,OAAO;gBAC1B,OAAO,EAAE,SAAS;aACnB,CAAC,CAAC;YAEH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE;gBAC3B,IAAI;gBACJ,WAAW;aACZ,CAAC,CAAC;YAEH,OAAO;gBACL,YAAY,EAAE,cAAc;gBAC5B,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,OAAO;aACd,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IAEpD,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"pubsub.js","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAiBzD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,KAAK,CAAU,IAAY,EAAE,MAAoB;IAC/D,MAAM,WAAW,GAAG,IAAI,GAAG,EAA+C,CAAC;IAC3E,MAAM,QAAQ,GAAG,MAAM,EAAE,iBAAiB,KAAK,cAAc,CAAC;IAC9D,MAAM,OAAO,GAAG,gBAAgB,IAAI,EAAE,CAAC;IAEvC,sDAAsD;IACtD,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAE1C;;;OAGG;IACH,KAAK,UAAU,aAAa,CAC1B,OAAe,EACf,OAAiB,EACjB,WAAmB;QAEnB,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO;QACzC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE7B,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG;YAAE,OAAO;QAExB,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAEtC,yBAAyB;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE;gBAC9B,YAAY,EAAE,OAAO;gBACrB,UAAU,EAAE,SAAS,CAAC,QAAQ;gBAC9B,eAAe,EAAE,WAAW;gBAC5B,cAAc,EAAE,OAAO;aACxB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAEzD,qCAAqC;QACrC,CAAC,KAAK,IAAI,EAAE;YACV,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;gBAC1C,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;oBACjC,IAAI,CAAC;wBACH,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;wBACxC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;wBACpB,GAAG,CAAC,GAAG,EAAE,CAAC;oBACZ,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,OAAO,CAAC,KAAK,CACX,wBAAwB,OAAO,eAAe,IAAI,WAAW,EAC7D,GAAG,CACJ,CAAC;wBACF,8CAA8C;wBAC9C,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBAChB,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,OAAO,GAAQ,EAAE,CAAC;gBAClB,qDAAqD;gBACrD,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAChC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACrC,OAAO,CAAC,KAAK,CACX,sBAAsB,OAAO,eAAe,IAAI,YAAY,EAC5D,GAAG,CACJ,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IAED,MAAM,CAAC,GAAa;QAClB,KAAK,CAAC,OAAO,CAAC,IAAO;YACnB,MAAM,SAAS,GAAG,MAAM,eAAe,EAAE,CAAC;YAE1C,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;gBAC1B,IAAI,EAAE,EAAE,CAAC;oBACP,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;oBAE9C,MAAM,OAAO,GACX,QAAQ,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;wBAC1C,CAAC,CAAC,WAAW,CAAC,IAAW,EAAE,MAAM,EAAE,OAAO,CAAC;wBAC3C,CAAC,CAAC,SAAS,CAAC;oBAEhB,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;oBAC/D,OAAO;gBACT,CAAC;YACH,CAAC;YAED,+BAA+B;YAC/B,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,WAAW,EAAE,CAAC;gBACzC,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,WAAW,EAAE,GAAG,CAAC,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QAED,SAAS,CAAC,OAAe,EAAE,SAA0B;YACnD,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE;gBACvB,OAAO,EAAE,SAAS,CAAC,OAAO;gBAC1B,OAAO,EAAE,SAAS;aACnB,CAAC,CAAC;YAEH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE;gBAC3B,IAAI;gBACJ,WAAW;aACZ,CAAC,CAAC;YAEH,6CAA6C;YAC7C,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,IAAI,CAAC,CAAC;YAC/C,eAAe,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;gBACzC,IAAI,SAAS,EAAE,CAAC;oBACd,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;oBAC9C,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,KAAK,CAC1D,CAAC,GAAG,EAAE,EAAE;wBACN,OAAO,CAAC,KAAK,CACX,sCAAsC,OAAO,IAAI,EACjD,GAAG,CACJ,CAAC;oBACJ,CAAC,CACF,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,OAAO;gBACL,YAAY,EAAE,cAAc;gBAC5B,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,OAAO;aACd,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IAEpD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAClB,IAAyB,EACzB,OAAgB;IAEhB,MAAM,CAAC,GAAG,WAAW,EAAE,CAAC;IAExB,qCAAqC;IACrC,sEAAsE;IACtE,8DAA8D;IAC9D,IAAI,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,CAAC,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9D,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC1D,CAAC;QACD,CAAC,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cooper-stack",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "The backend framework for TypeScript",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,8 @@
   "dependencies": {
     "pg": "^8.13.0",
     "mysql2": "^3.11.0",
-    "ioredis": "^5.4.0"
+    "ioredis": "^5.4.0",
+    "nats": "^2.29.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

package/src/index.ts

@@ -4,6 +4,7 @@ export { database, type DatabaseClient } from "./db.js";
 export { middleware, cooper } from "./middleware.js";
 export { authHandler } from "./auth.js";
 export { topic, type Topic } from "./pubsub.js";
+export { closeNats } from "./nats.js";
 export { cron } from "./cron.js";
 export { cache, type CacheClient } from "./cache.js";
 export { bucket, type BucketClient } from "./storage.js";

package/src/nats.ts

@@ -0,0 +1,128 @@
+/**
+ * NATS Connection Manager — singleton lazy connection to embedded NATS.
+ *
+ * JetStream is used for durable pub/sub with delivery guarantees.
+ * Falls back gracefully if NATS is unavailable (logs warning once).
+ */
+
+import {
+  connect,
+  type NatsConnection,
+  type JetStreamClient,
+  type JetStreamManager,
+  JSONCodec,
+  RetentionPolicy,
+  StorageType,
+  AckPolicy,
+} from "nats";
+
+let nc: NatsConnection | null = null;
+let js: JetStreamClient | null = null;
+let jsm: JetStreamManager | null = null;
+let connectPromise: Promise<boolean> | null = null;
+let warnedOnce = false;
+
+const jc = JSONCodec();
+
+function getNatsUrl(): string {
+  return process.env.COOPER_NATS_URL ?? "nats://localhost:4222";
+}
+
+async function doConnect(): Promise<boolean> {
+  try {
+    nc = await connect({ servers: getNatsUrl(), maxReconnectAttempts: 5 });
+    js = nc.jetstream();
+    jsm = await nc.jetstreamManager();
+    return true;
+  } catch (err: any) {
+    if (!warnedOnce) {
+      console.warn(
+        `[cooper] NATS unavailable at ${getNatsUrl()} — pub/sub will use in-memory fallback. ${err.message}`
+      );
+      warnedOnce = true;
+    }
+    nc = null;
+    js = null;
+    jsm = null;
+    return false;
+  }
+}
+
+export async function ensureConnected(): Promise<boolean> {
+  if (nc && !nc.isClosed()) return true;
+  if (connectPromise) return connectPromise;
+  connectPromise = doConnect().finally(() => {
+    connectPromise = null;
+  });
+  return connectPromise;
+}
+
+export function getJetStream(): JetStreamClient | null {
+  return js;
+}
+
+export function getJetStreamManager(): JetStreamManager | null {
+  return jsm;
+}
+
+export function getConnection(): NatsConnection | null {
+  return nc;
+}
+
+export { jc as jsonCodec };
+
+/**
+ * Sanitize a topic name into a valid NATS stream name.
+ * NATS streams: alphanumeric + dash + underscore only.
+ */
+export function streamName(topicName: string): string {
+  return "COOPER_" + topicName.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+}
+
+/**
+ * Sanitize a subscriber name into a valid NATS durable consumer name.
+ */
+export function consumerName(subscriberName: string): string {
+  return subscriberName.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/**
+ * Ensure a JetStream stream exists for a topic.
+ * Creates it if missing, no-ops if it already exists.
+ */
+export async function ensureStream(
+  topicName: string,
+  config?: { dedup?: boolean }
+): Promise<void> {
+  if (!jsm) return;
+
+  const name = streamName(topicName);
+  const subject = `cooper.topic.${topicName}`;
+
+  try {
+    await jsm.streams.info(name);
+  } catch {
+    await jsm.streams.add({
+      name,
+      subjects: [subject],
+      retention: RetentionPolicy.Interest,
+      max_msgs: -1,
+      max_bytes: -1,
+      max_age: 7 * 24 * 60 * 60 * 1_000_000_000, // 7 days in nanos
+      storage: StorageType.File,
+      num_replicas: 1,
+      duplicate_window: config?.dedup
+        ? 2 * 60 * 1_000_000_000 // 2 min dedup window
+        : 0,
+    });
+  }
+}
+
+/**
+ * Graceful shutdown — drain and close the connection.
+ */
+export async function closeNats(): Promise<void> {
+  if (nc && !nc.isClosed()) {
+    await nc.drain();
+  }
+}

package/src/pubsub.ts

@@ -1,4 +1,14 @@
 import { registry } from "./registry.js";
+import {
+  ensureConnected,
+  getJetStream,
+  getJetStreamManager,
+  jsonCodec,
+  streamName,
+  consumerName,
+  ensureStream,
+} from "./nats.js";
+import { headers as natsHeaders, AckPolicy } from "nats";
 
 export interface TopicConfig {
   deliveryGuarantee?: "at-least-once" | "exactly-once";
@@ -24,17 +34,102 @@ export interface Topic<T> {
  *   { deliveryGuarantee: "at-least-once" }
  * );
  * ```
+ *
+ * Local dev uses embedded NATS with JetStream for durable delivery.
+ * Falls back to in-memory if NATS is unavailable.
  */
 export function topic<T = any>(name: string, config?: TopicConfig): Topic<T> {
   const subscribers = new Map<string, { handler: Function; options: any }>();
+  const useDedup = config?.deliveryGuarantee === "exactly-once";
+  const subject = `cooper.topic.${name}`;
+
+  // Track whether JetStream consumers have been started
+  const activeConsumers = new Set<string>();
+
+  /**
+   * Start a JetStream pull consumer for a subscriber.
+   * Runs in the background, processing messages until the connection closes.
+   */
+  async function startConsumer(
+    subName: string,
+    handler: Function,
+    concurrency: number
+  ): Promise<void> {
+    if (activeConsumers.has(subName)) return;
+    activeConsumers.add(subName);
+
+    const js = getJetStream();
+    const jsm = getJetStreamManager();
+    if (!js || !jsm) return;
+
+    const stream = streamName(name);
+    const durable = consumerName(subName);
+
+    // Ensure consumer exists
+    try {
+      await jsm.consumers.info(stream, durable);
+    } catch {
+      await jsm.consumers.add(stream, {
+        durable_name: durable,
+        ack_policy: AckPolicy.Explicit,
+        max_ack_pending: concurrency,
+        filter_subject: subject,
+      });
+    }
+
+    const consumer = await js.consumers.get(stream, durable);
+
+    // Process messages in the background
+    (async () => {
+      try {
+        const messages = await consumer.consume();
+        for await (const msg of messages) {
+          try {
+            const data = jsonCodec.decode(msg.data);
+            await handler(data);
+            msg.ack();
+          } catch (err) {
+            console.error(
+              `[cooper] Subscriber "${subName}" on topic "${name}" failed:`,
+              err
+            );
+            // NAK with delay for retry (5 second backoff)
+            msg.nak(5000);
+          }
+        }
+      } catch (err: any) {
+        // Consumer iteration ended (connection closed, etc.)
+        activeConsumers.delete(subName);
+        if (!err.message?.includes("closed")) {
+          console.error(
+            `[cooper] Consumer "${subName}" on topic "${name}" stopped:`,
+            err
+          );
+        }
+      }
+    })();
+  }
 
   const t: Topic<T> = {
     async publish(data: T) {
-      // In local dev, deliver directly to subscribers
-      // In production, publish to NATS/SNS/Pub/Sub
-      const natsUrl = process.env.COOPER_NATS_URL ?? "nats://localhost:4222";
+      const connected = await ensureConnected();
+
+      if (connected) {
+        const js = getJetStream();
+        if (js) {
+          await ensureStream(name, { dedup: useDedup });
 
-      // Direct local delivery for development
+          const headers =
+            useDedup && data && typeof data === "object"
+              ? createDedup(data as any, config?.orderBy)
+              : undefined;
+
+          await js.publish(subject, jsonCodec.encode(data), { headers });
+          return;
+        }
+      }
+
+      // Fallback: in-memory delivery
       for (const [subName, sub] of subscribers) {
         try {
           await sub.handler(data);
@@ -55,6 +150,22 @@ export function topic<T = any>(name: string, config?: TopicConfig): Topic<T> {
         subscribers,
       });
 
+      // Start JetStream consumer in the background
+      const concurrency = subConfig.concurrency ?? 1;
+      ensureConnected().then(async (connected) => {
+        if (connected) {
+          await ensureStream(name, { dedup: useDedup });
+          startConsumer(subName, subConfig.handler, concurrency).catch(
+            (err) => {
+              console.error(
+                `[cooper] Failed to start consumer "${subName}":`,
+                err
+              );
+            }
+          );
+        }
+      });
+
       return {
         _cooper_type: "subscription",
         topic: name,
@@ -67,3 +178,31 @@ export function topic<T = any>(name: string, config?: TopicConfig): Topic<T> {
 
   return t;
 }
+
+/**
+ * Create NATS headers for exactly-once dedup.
+ * Uses Nats-Msg-Id header — JetStream deduplicates within the stream's
+ * duplicate_window based on this ID.
+ */
+function createDedup(
+  data: Record<string, any>,
+  orderBy?: string
+): any {
+  const h = natsHeaders();
+
+  // Generate a deterministic dedup ID.
+  // If an ordering key is set, use that field's value as the dedup key.
+  // Otherwise, hash the entire payload for content-based dedup.
+  if (orderBy && data[orderBy] !== undefined) {
+    h.set("Nats-Msg-Id", `${orderBy}-${String(data[orderBy])}`);
+  } else {
+    const payload = JSON.stringify(data);
+    let hash = 0;
+    for (let i = 0; i < payload.length; i++) {
+      hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;
+    }
+    h.set("Nats-Msg-Id", `msg-${Math.abs(hash)}`);
+  }
+
+  return h;
+}