@nexus_js/connect 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Contributors
+
+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,17 @@
+# @nexus_js/connect
+
+Nexus Connect — Edge-State Sync via SSE. $socket() rune for real-time state across all connected clients..
+
+## Documentation
+
+All guides, API reference, and examples live on **[nexusjs.dev](https://nexusjs.dev)**.
+
+## Links
+
+- **Website:** [https://nexusjs.dev](https://nexusjs.dev)
+- **Repository:** [github.com/bierfor/nexus](https://github.com/bierfor/nexus) (see `packages/connect/`)
+- **Issues:** [github.com/bierfor/nexus/issues](https://github.com/bierfor/nexus/issues)
+
+## License
+
+MIT © Nexus contributors

package/dist/broker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Nexus Connect — In-memory message broker.
+ *
+ * Maintains a pub/sub registry keyed by topic string.
+ * Keeps the last published message per topic for late subscribers
+ * (same semantics as RxJS BehaviorSubject).
+ *
+ * Designed to be a singleton per server process. In multi-process/Edge
+ * environments, replace the singleton with a Redis/Upstash adapter.
+ */
+export interface ConnectMessage<T = unknown> {
+    topic: string;
+    data: T;
+    id: string;
+    ts: number;
+}
+type Subscriber<T> = (msg: ConnectMessage<T>) => void;
+declare class MessageBroker {
+    private subs;
+    private cache;
+    subscribe<T>(topic: string, fn: Subscriber<T>): () => void;
+    publish<T>(topic: string, data: T): void;
+    /** Number of active SSE listeners for a topic (useful for presence) */
+    subscriberCount(topic: string): number;
+    /** All currently active topics */
+    topics(): string[];
+}
+/** Singleton broker shared across all channels in this server process. */
+export declare const broker: MessageBroker;
+export {};
+//# sourceMappingURL=broker.d.ts.map

package/dist/broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.d.ts","sourceRoot":"","sources":["../src/broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAG,CAAC,CAAC;IACT,EAAE,EAAK,MAAM,CAAC;IACd,EAAE,EAAK,MAAM,CAAC;CACf;AAED,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEtD,cAAM,aAAa;IACjB,OAAO,CAAC,IAAI,CAAgD;IAC5D,OAAO,CAAC,KAAK,CAA8C;IAE3D,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAa1D,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAWxC,uEAAuE;IACvE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAItC,kCAAkC;IAClC,MAAM,IAAI,MAAM,EAAE;CAGnB;AAED,0EAA0E;AAC1E,eAAO,MAAM,MAAM,eAAsB,CAAC"}

package/dist/broker.js

@@ -0,0 +1,47 @@
+/**
+ * Nexus Connect — In-memory message broker.
+ *
+ * Maintains a pub/sub registry keyed by topic string.
+ * Keeps the last published message per topic for late subscribers
+ * (same semantics as RxJS BehaviorSubject).
+ *
+ * Designed to be a singleton per server process. In multi-process/Edge
+ * environments, replace the singleton with a Redis/Upstash adapter.
+ */
+class MessageBroker {
+    subs = new Map();
+    cache = new Map();
+    subscribe(topic, fn) {
+        if (!this.subs.has(topic))
+            this.subs.set(topic, new Set());
+        this.subs.get(topic).add(fn);
+        // Replay last message for late subscribers (catch-up semantics)
+        const last = this.cache.get(topic);
+        if (last)
+            queueMicrotask(() => fn(last));
+        return () => {
+            this.subs.get(topic)?.delete(fn);
+        };
+    }
+    publish(topic, data) {
+        const msg = {
+            topic,
+            data,
+            id: `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+            ts: Date.now(),
+        };
+        this.cache.set(topic, msg);
+        this.subs.get(topic)?.forEach((fn) => fn(msg));
+    }
+    /** Number of active SSE listeners for a topic (useful for presence) */
+    subscriberCount(topic) {
+        return this.subs.get(topic)?.size ?? 0;
+    }
+    /** All currently active topics */
+    topics() {
+        return [...this.subs.keys()].filter((t) => (this.subs.get(t)?.size ?? 0) > 0);
+    }
+}
+/** Singleton broker shared across all channels in this server process. */
+export const broker = new MessageBroker();
+//# sourceMappingURL=broker.js.map

package/dist/broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.js","sourceRoot":"","sources":["../src/broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,MAAM,aAAa;IACT,IAAI,GAAI,IAAI,GAAG,EAAoC,CAAC;IACpD,KAAK,GAAG,IAAI,GAAG,EAAmC,CAAC;IAE3D,SAAS,CAAI,KAAa,EAAE,EAAiB;QAC3C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,EAAyB,CAAC,CAAC;QAErD,gEAAgE;QAChE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI;YAAE,cAAc,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAyB,CAAC,CAAC,CAAC;QAE9D,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,EAAyB,CAAC,CAAC;QAC1D,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,CAAI,KAAa,EAAE,IAAO;QAC/B,MAAM,GAAG,GAAsB;YAC7B,KAAK;YACL,IAAI;YACJ,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;YAC7D,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;SACf,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,GAA8B,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,GAA8B,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,uEAAuE;IACvE,eAAe,CAAC,KAAa;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,kCAAkC;IAClC,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChF,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Nexus Connect — Client-side $socket() rune.
+ *
+ * Connects to /_nexus/connect/:topic via SSE and returns a reactive
+ * state object whose .value updates in real time whenever the server publishes.
+ *
+ * Usage in a .nx island:
+ *   <script>
+ *   import { $socket } from '@nexus_js/connect/client';
+ *
+ *   const captures = $socket('global-captures', { default: { count: 0 } });
+ *   // captures.value.count is always up-to-date
+ *   </script>
+ *   <p>Global captures: {captures.value.count}</p>
+ */
+export interface SocketState<T> {
+    /** Current value — reactive in island components */
+    readonly value: T;
+    /** Register a callback that fires on every update */
+    subscribe: (fn: (value: T, prev: T) => void) => () => void;
+    /** Manually close the SSE connection */
+    close: () => void;
+    /** true while the SSE connection is establishing */
+    readonly connecting: boolean;
+    /** true if the connection is live */
+    readonly connected: boolean;
+}
+export interface SocketOptions<T> {
+    default: T;
+    /** Optional transform applied to the raw JSON payload */
+    transform?: (raw: unknown) => T;
+    /** Called on SSE connection error */
+    onError?: (err: Event) => void;
+    /** Reconnect automatically on error (default: true) */
+    reconnect?: boolean;
+}
+export declare function $socket<T>(topic: string, opts: SocketOptions<T>): SocketState<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,qDAAqD;IACrD,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC3D,wCAAwC;IACxC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,yDAAyD;IACzD,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IAC/B,uDAAuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AASD,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAuEhF"}

package/dist/client.js

@@ -0,0 +1,76 @@
+/**
+ * Nexus Connect — Client-side $socket() rune.
+ *
+ * Connects to /_nexus/connect/:topic via SSE and returns a reactive
+ * state object whose .value updates in real time whenever the server publishes.
+ *
+ * Usage in a .nx island:
+ *   <script>
+ *   import { $socket } from '@nexus_js/connect/client';
+ *
+ *   const captures = $socket('global-captures', { default: { count: 0 } });
+ *   // captures.value.count is always up-to-date
+ *   </script>
+ *   <p>Global captures: {captures.value.count}</p>
+ */
+export function $socket(topic, opts) {
+    let current = opts.default;
+    let _connecting = true;
+    let _connected = false;
+    const listeners = new Set();
+    let es = null;
+    function notify(next) {
+        const prev = current;
+        current = next;
+        if (typeof window !== 'undefined' && window.__NEXUS_DEV__) {
+            console.log(`%c[Nexus] 🛰️  Connect%c "${topic}" →`, 'color:#7c3aed;font-weight:700', 'color:#64748b', next);
+        }
+        listeners.forEach((fn) => fn(next, prev));
+    }
+    function connect() {
+        if (typeof window === 'undefined' || typeof EventSource === 'undefined')
+            return;
+        es = new EventSource(`/_nexus/connect/${encodeURIComponent(topic)}`);
+        es.addEventListener('connected', () => {
+            _connecting = false;
+            _connected = true;
+            if (typeof window !== 'undefined' && window.__NEXUS_DEV__) {
+                console.log(`%c[Nexus] 🛰️  Connect%c "${topic}" established`, 'color:#7c3aed;font-weight:700', 'color:#10b981');
+            }
+        });
+        es.addEventListener('message', (e) => {
+            try {
+                const raw = JSON.parse(e.data);
+                const value = opts.transform ? opts.transform(raw) : raw;
+                notify(value);
+            }
+            catch {
+                // malformed JSON — ignore
+            }
+        });
+        es.onerror = (err) => {
+            _connected = false;
+            _connecting = true;
+            opts.onError?.(err);
+            // EventSource auto-reconnects by default
+        };
+    }
+    connect();
+    return {
+        get value() { return current; },
+        get connecting() { return _connecting; },
+        get connected() { return _connected; },
+        subscribe(fn) {
+            listeners.add(fn);
+            fn(current, current); // immediate call with current value
+            return () => listeners.delete(fn);
+        },
+        close() {
+            es?.close();
+            _connected = false;
+            _connecting = false;
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @nexus_js/connect — Edge-State Sync
+ *
+ * Server exports:
+ *   getChannel(topic)     — pub/sub channel for server→client push
+ *   handleSSERequest()    — Web-standard SSE Response handler
+ *   handleSSERequestNode()— Node.js http.ServerResponse adapter
+ *   isConnectRequest()    — Route guard for /_nexus/connect/* URLs
+ *   CONNECT_PATH          — '/_nexus/connect/'
+ *
+ * Client exports (import from '@nexus_js/connect/client'):
+ *   $socket(topic, opts)  — reactive SSE subscription rune
+ */
+export { broker } from './broker.js';
+export { handleSSERequest, handleSSERequestNode, isConnectRequest, topicFromUrl, CONNECT_PATH } from './sse.js';
+export interface NexusChannel<T = unknown> {
+    topic: string;
+    /** Push data to all connected clients subscribed to this topic */
+    publish: (data: T) => void;
+    /** Subscribe to messages on this topic (server-side listener) */
+    subscribe: (fn: (data: T) => void) => () => void;
+    /** Number of currently connected SSE clients */
+    subscriberCount: () => number;
+}
+/**
+ * Returns a typed channel for a given topic.
+ * Call publish() from your server frontmatter to push state to clients.
+ *
+ * @example
+ * // In .nx frontmatter:
+ * import { getChannel } from '@nexus_js/connect';
+ * const stats = getChannel<{ captures: number }>('global-stats');
+ * stats.publish({ captures: await db.count('captures') });
+ */
+export declare function getChannel<T = unknown>(topic: string): NexusChannel<T>;
+/** All currently active (non-empty) topics — useful for admin dashboards */
+export declare function activeTopics(): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAIhH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,KAAK,EAAY,MAAM,CAAC;IACxB,kEAAkE;IAClE,OAAO,EAAU,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACnC,iEAAiE;IACjE,SAAS,EAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACvD,gDAAgD;IAChD,eAAe,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAOtE;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC"}

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * @nexus_js/connect — Edge-State Sync
+ *
+ * Server exports:
+ *   getChannel(topic)     — pub/sub channel for server→client push
+ *   handleSSERequest()    — Web-standard SSE Response handler
+ *   handleSSERequestNode()— Node.js http.ServerResponse adapter
+ *   isConnectRequest()    — Route guard for /_nexus/connect/* URLs
+ *   CONNECT_PATH          — '/_nexus/connect/'
+ *
+ * Client exports (import from '@nexus_js/connect/client'):
+ *   $socket(topic, opts)  — reactive SSE subscription rune
+ */
+export { broker } from './broker.js';
+export { handleSSERequest, handleSSERequestNode, isConnectRequest, topicFromUrl, CONNECT_PATH } from './sse.js';
+import { broker } from './broker.js';
+/**
+ * Returns a typed channel for a given topic.
+ * Call publish() from your server frontmatter to push state to clients.
+ *
+ * @example
+ * // In .nx frontmatter:
+ * import { getChannel } from '@nexus_js/connect';
+ * const stats = getChannel<{ captures: number }>('global-stats');
+ * stats.publish({ captures: await db.count('captures') });
+ */
+export function getChannel(topic) {
+    return {
+        topic,
+        publish: (data) => broker.publish(topic, data),
+        subscribe: (fn) => broker.subscribe(topic, (msg) => fn(msg.data)),
+        subscriberCount: () => broker.subscriberCount(topic),
+    };
+}
+/** All currently active (non-empty) topics — useful for admin dashboards */
+export function activeTopics() {
+    return broker.topics();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEhH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAYrC;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAc,KAAa;IACnD,OAAO;QACL,KAAK;QACL,OAAO,EAAU,CAAC,IAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,CAAC;QAC5D,SAAS,EAAQ,CAAC,EAAqB,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAI,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7F,eAAe,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY;IAC1B,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;AACzB,CAAC"}

package/dist/sse.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Nexus Connect — Server-Sent Events handler.
+ *
+ * Returns a streaming Response that stays open until the client disconnects.
+ * Works with any Web-standard Request/Response environment (Node 18+, Bun, Deno, Cloudflare Workers).
+ *
+ * SSE wire format:
+ *   id: <message-id>\n
+ *   event: message\n
+ *   data: <json-payload>\n\n
+ *
+ *   : heartbeat\n\n   ← keep-alive comment (every 15s)
+ */
+export declare const CONNECT_PATH = "/_nexus/connect/";
+/** Extract the topic name from a /_nexus/connect/:topic URL. */
+export declare function topicFromUrl(url: URL): string;
+/** Returns true if this request should be handled by Nexus Connect. */
+export declare function isConnectRequest(url: URL): boolean;
+/**
+ * Creates a streaming SSE Response for the given topic.
+ * The response stays open until the client disconnects (request.signal aborts).
+ */
+export declare function handleSSERequest(request: Request, topic: string): Response;
+/**
+ * Node.js adapter — writes SSE directly to a ServerResponse.
+ * Use this when you cannot return a Web Response (e.g. in http.createServer callbacks).
+ */
+export declare function handleSSERequestNode(req: {
+    signal?: AbortSignal;
+    on?: (event: string, fn: () => void) => void;
+}, res: {
+    writeHead: (s: number, h: Record<string, string>) => void;
+    write: (s: string) => boolean;
+    end: () => void;
+}, topic: string): void;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAE7C;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAuC1E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;CAAE,EAC3E,GAAG,EAAE;IAAE,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,IAAI,CAAA;CAAE,EAClH,KAAK,EAAE,MAAM,GACZ,IAAI,CA2BN"}

package/dist/sse.js

@@ -0,0 +1,90 @@
+/**
+ * Nexus Connect — Server-Sent Events handler.
+ *
+ * Returns a streaming Response that stays open until the client disconnects.
+ * Works with any Web-standard Request/Response environment (Node 18+, Bun, Deno, Cloudflare Workers).
+ *
+ * SSE wire format:
+ *   id: <message-id>\n
+ *   event: message\n
+ *   data: <json-payload>\n\n
+ *
+ *   : heartbeat\n\n   ← keep-alive comment (every 15s)
+ */
+import { broker } from './broker.js';
+const HEARTBEAT_MS = 15_000;
+export const CONNECT_PATH = '/_nexus/connect/';
+/** Extract the topic name from a /_nexus/connect/:topic URL. */
+export function topicFromUrl(url) {
+    return decodeURIComponent(url.pathname.slice(CONNECT_PATH.length));
+}
+/** Returns true if this request should be handled by Nexus Connect. */
+export function isConnectRequest(url) {
+    return url.pathname.startsWith(CONNECT_PATH) && url.pathname.length > CONNECT_PATH.length;
+}
+/**
+ * Creates a streaming SSE Response for the given topic.
+ * The response stays open until the client disconnects (request.signal aborts).
+ */
+export function handleSSERequest(request, topic) {
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const encoder = new TextEncoder();
+    const send = (chunk) => {
+        writer.write(encoder.encode(chunk)).catch(() => { });
+    };
+    // Initial handshake event
+    send(`event: connected\ndata: ${JSON.stringify({ topic, ts: Date.now() })}\n\n`);
+    // Subscribe and forward broker messages to the stream
+    const unsubscribe = broker.subscribe(topic, (msg) => {
+        send(`id: ${msg.id}\nevent: message\ndata: ${JSON.stringify(msg.data)}\n\n`);
+    });
+    // Heartbeat — prevents proxies from closing idle connections
+    const heartbeat = setInterval(() => {
+        send(': heartbeat\n\n');
+    }, HEARTBEAT_MS);
+    // Cleanup when client disconnects
+    request.signal.addEventListener('abort', () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+        writer.close().catch(() => { });
+    }, { once: true });
+    return new Response(readable, {
+        status: 200,
+        headers: {
+            'content-type': 'text/event-stream; charset=utf-8',
+            'cache-control': 'no-cache, no-transform',
+            'connection': 'keep-alive',
+            'x-accel-buffering': 'no',
+            'access-control-allow-origin': '*',
+        },
+    });
+}
+/**
+ * Node.js adapter — writes SSE directly to a ServerResponse.
+ * Use this when you cannot return a Web Response (e.g. in http.createServer callbacks).
+ */
+export function handleSSERequestNode(req, res, topic) {
+    res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache',
+        'connection': 'keep-alive',
+        'x-accel-buffering': 'no',
+        'access-control-allow-origin': '*',
+    });
+    res.write(`event: connected\ndata: ${JSON.stringify({ topic, ts: Date.now() })}\n\n`);
+    const unsubscribe = broker.subscribe(topic, (msg) => {
+        res.write(`id: ${msg.id}\nevent: message\ndata: ${JSON.stringify(msg.data)}\n\n`);
+    });
+    const heartbeat = setInterval(() => {
+        res.write(': heartbeat\n\n');
+    }, HEARTBEAT_MS);
+    const cleanup = () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+        res.end();
+    };
+    req.on?.('close', cleanup);
+    req.signal?.addEventListener('abort', cleanup, { once: true });
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@nexus_js/connect",
+  "version": "0.6.0",
+  "description": "Nexus Connect — Edge-State Sync via SSE. $socket() rune for real-time state across all connected clients.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "homepage": "https://nexusjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bierfor/nexus.git",
+    "directory": "packages/connect"
+  },
+  "bugs": {
+    "url": "https://github.com/bierfor/nexus/issues"
+  },
+  "keywords": [
+    "nexus",
+    "framework",
+    "full-stack",
+    "svelte",
+    "islands",
+    "ssr",
+    "vite",
+    "server-actions"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}