@weft-js/realtime-nats 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+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

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/realtime-nats
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+The realtime.bus provider for core NATS.
+
+```bash
+npm install @weft-js/realtime-nats
+```

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@weft-js/realtime-nats",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/realtime-nats: the realtime.bus provider for core NATS",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./plugin.mjs"
+  },
+  "dependencies": {
+    "@nats-io/transport-node": "3.4.0"
+  },
+  "peerDependencies": {
+    "@weft-js/start": "^0.1.0",
+    "@weft-js/core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.d.mts

@@ -0,0 +1,5 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** `nats()` for `weft.config.ts`: NATS as the `realtime.bus` provider, at `NATS_URL`. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,19 @@
+// nats() for weft.config.ts: this package as the `realtime.bus` provider. Listed here, it replaces the memory bus, and
+// a bus set in `src/realtime.server.ts` still wins.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'realtime.bus', version: 1, cardinality: 'one', sides: ['server'] })
+
+export const nats = definePlugin({
+  name: '@weft-js/realtime-nats',
+  version: '0.1.0',
+  weft: '*',
+  permissions: { net: ['env:NATS_URL'], env: ['NATS_URL', 'WEFT_BUILD'] },
+  contribute: options => ({
+    provides: [provide(slot, { sides: { server: { module: '@weft-js/realtime-nats', export: 'bus', options } } })],
+    agents: { title: 'Realtime bus (NATS)', text: '`realtime.bus` is NATS, at `NATS_URL`. Rooms, shared state, `.live` and streams reach every instance. It is at-most-once: anything that must survive is a mutation, and `collect` plus a query covers a gap.' },
+    map: [{ want: 'Change the realtime bus', call: 'replace this plugin in `plugins`, or set `bus` in `src/realtime.server.ts`', have: 'NATS' }],
+  }),
+})
+
+export default nats

package/src/index.ts

@@ -0,0 +1,59 @@
+// Core NATS (research 32 §6): at-most-once, like every bus. Channels come from tags and keys, and a subject can't hold
+// `*`, `>` or a space, so a subject is `weft.<base64url of the channel>`. A reconnect is the `gap`.
+
+import { connect, type NatsConnection } from '@nats-io/transport-node'
+import type { Bus } from '@weft-js/start/bus'
+import { StartError } from '@weft-js/start/data'
+
+/** Options of `natsBus()`: the servers, and the credentials if they ask for any. */
+export interface NatsBusOptions {
+  /** `nats://host:4222`, or several. */
+  servers: string | string[]
+  token?: string
+  user?: string
+  pass?: string
+}
+
+const subject = (channel: string) => `weft.${Buffer.from(channel).toString('base64url')}`
+
+/** A `Bus` over core NATS, connecting on first use. Throws Q013 without `servers`, except during a build. */
+export function natsBus(options: NatsBusOptions): Bus {
+  if (!options.servers?.length && process.env.WEFT_BUILD) options = { ...options, servers: 'nats://localhost:4222' } // a build never connects
+  if (!options.servers?.length)
+    throw new StartError('Q013', '`natsBus` needs `servers`', 'set the URL, or leave `bus` out for the memory bus on one instance')
+  let nc: Promise<NatsConnection> | undefined
+  const gaps = new Set<() => void>()
+  const client = () => (nc ??= connect({ ...options, maxReconnectAttempts: -1, reconnectTimeWait: 500 }).then(c => {
+    void (async () => {
+      for await (const s of c.status()) if (s.type === 'reconnect') for (const gap of gaps) gap()
+    })()
+    return c
+  }, e => {
+    nc = undefined // the next use tries again
+    throw e
+  }))
+  return {
+    name: 'nats',
+    async publish(channel, message) {
+      (await client()).publish(subject(channel), message)
+    },
+    async subscribe(channel, on, gap) {
+      const c = await client()
+      const sub = c.subscribe(subject(channel), { callback: (e, m) => { if (!e) on(m.string()) } })
+      await c.flush() // the server has the subscription: a publish after this resolves is delivered
+      if (gap) gaps.add(gap)
+      return () => {
+        sub.unsubscribe()
+        if (gap) gaps.delete(gap)
+      }
+    },
+    async close() {
+      const c = await nc?.catch(() => undefined)
+      nc = undefined
+      await c?.close()
+    },
+  }
+}
+
+/** The `realtime.bus` provider: `NATS_URL` unless the plugin was given `servers`. */
+export const bus = (options: Partial<NatsBusOptions> = {}) => natsBus({ ...options, servers: options.servers ?? process.env.NATS_URL ?? '' })