@weft-js/realtime-redis 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-redis
 
-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 Redis pub/sub.
+
+```bash
+npm install @weft-js/realtime-redis
+```

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@weft-js/realtime-redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/realtime-redis: the realtime.bus provider for Redis pub/sub",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./plugin.mjs"
+  },
+  "dependencies": {
+    "ioredis": "6.0.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>
+/** `redis()` for `weft.config.ts`: Redis as the `realtime.bus` provider, at `REDIS_URL`. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,19 @@
+// redis() 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 redis = definePlugin({
+  name: '@weft-js/realtime-redis',
+  version: '0.1.0',
+  weft: '*',
+  permissions: { net: ['env:REDIS_URL'], env: ['REDIS_URL', 'WEFT_BUILD'] },
+  contribute: options => ({
+    provides: [provide(slot, { sides: { server: { module: '@weft-js/realtime-redis', export: 'bus', options } } })],
+    agents: { title: 'Realtime bus (Redis)', text: '`realtime.bus` is Redis, at `REDIS_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: 'Redis' }],
+  }),
+})
+
+export default redis

package/src/index.ts

@@ -0,0 +1,76 @@
+// Redis pub/sub (research 32 §6): two connections, because a subscriber can't publish. ioredis resubscribes after a
+// reconnect, and whatever was published meanwhile is gone: every `ready` after the first is the `gap`.
+
+import { Redis } from 'ioredis'
+import type { Bus } from '@weft-js/start/bus'
+import { StartError } from '@weft-js/start/data'
+
+/** Options of `redisBus()`. */
+export interface RedisBusOptions {
+  /** `redis://…` or `rediss://…`. */
+  url: string
+  /** Prefix of every Redis channel. Default `weft:`: several apps can share a server. */
+  prefix?: string
+}
+
+/** A `Bus` over Redis pub/sub, connecting on first use. Throws Q013 without a `redis://` URL, except during a build. */
+export function redisBus({ url, prefix = 'weft:' }: RedisBusOptions): Bus {
+  if (!url && process.env.WEFT_BUILD) url = 'redis://localhost' // a build loads this module and never connects
+  if (!/^rediss?:\/\//.test(url ?? ''))
+    throw new StartError('Q013', `\`redisBus\` needs a \`redis://\` URL, not \`${(url ?? '').replace(/\/\/.*@/, '//…@')}\``, 'set the URL, or leave `bus` out for the memory bus on one instance')
+  let pub: Redis | undefined, sub: Redis | undefined
+  const listeners = new Map<string, Set<(message: string) => void>>()
+  const gaps = new Set<() => void>()
+  const opts = { maxRetriesPerRequest: null, lazyConnect: false }
+  const subscriber = () => {
+    if (sub) return sub
+    let connected = false
+    sub = new Redis(url, opts)
+    sub.on('error', () => {}) // ioredis retries; an unhandled `error` event would end the process
+    sub.on('ready', () => {
+      if (connected) for (const gap of gaps) gap()
+      connected = true
+    })
+    sub.on('message', (channel: string, message: string) => {
+      const list = listeners.get(channel)
+      if (list) for (const on of list) on(message)
+    })
+    return sub
+  }
+  const publisher = () => {
+    if (pub) return pub
+    pub = new Redis(url, opts)
+    pub.on('error', () => {})
+    return pub
+  }
+  return {
+    name: 'redis',
+    async publish(channel, message) {
+      await publisher().publish(prefix + channel, message)
+    },
+    async subscribe(channel, on, gap) {
+      const name = prefix + channel
+      let list = listeners.get(name)
+      if (!list) listeners.set(name, (list = new Set()))
+      list.add(on)
+      if (gap) gaps.add(gap)
+      if (list.size === 1) await subscriber().subscribe(name)
+      return () => {
+        list.delete(on)
+        if (gap) gaps.delete(gap)
+        if (list.size) return
+        listeners.delete(name)
+        void sub?.unsubscribe(name).catch(() => {})
+      }
+    },
+    close() {
+      sub?.disconnect()
+      pub?.disconnect()
+      sub = pub = undefined
+      return Promise.resolve()
+    },
+  }
+}
+
+/** The `realtime.bus` provider: `REDIS_URL` unless the plugin was given a `url`. */
+export const bus = (options: Partial<RedisBusOptions> = {}) => redisBus({ ...options, url: options.url ?? process.env.REDIS_URL ?? '' })