@krizaka/realtime 0.0.0-stage → 0.1.0

package/dist/chunk-WHRDA5M4.js

@@ -0,0 +1,73 @@
+import {
+  ReplicatedPresence,
+  emitSafely,
+  localEmitter
+} from "./chunk-HJCRR3FF.js";
+
+// src/postgres.ts
+import { randomUUID } from "crypto";
+var NOTIFY_LIMIT = 7900;
+var DEFAULT_CHANNEL = "realtime_events";
+var PRESENCE_TOPIC = "__rt.presence";
+function postgresBus(options) {
+  const channel = options.channel ?? DEFAULT_CHANNEL;
+  const emitter = localEmitter();
+  const instanceId = randomUUID();
+  const intervalMs = options.snapshotIntervalMs ?? 3e4;
+  const send = async (topic, event) => {
+    const payload = JSON.stringify({ topic, event });
+    if (Buffer.byteLength(payload) > NOTIFY_LIMIT) throw new Error(`payload too large for ${topic}`);
+    await options.db.notify(channel, payload);
+  };
+  const presence = new ReplicatedPresence({
+    ...options,
+    instanceId,
+    snapshotTtlMs: Math.round(intervalMs * 2.5),
+    broadcast: (replica) => void send(PRESENCE_TOPIC, replica).catch(() => void 0)
+  });
+  const listener = options.db.listen(channel, (payload) => {
+    try {
+      const { topic, event } = JSON.parse(payload);
+      if (topic === PRESENCE_TOPIC) presence.receive(event);
+      else emitSafely(emitter, topic, event);
+    } catch {
+    }
+  });
+  const timer = setInterval(() => {
+    for (const page of presence.snapshot()) void send(PRESENCE_TOPIC, page).catch(() => void 0);
+  }, intervalMs);
+  timer.unref?.();
+  return {
+    kind: "postgres",
+    get connected() {
+      return listener.connected;
+    },
+    presence,
+    async publish(topic, event) {
+      const hearsEcho = listener.connected;
+      try {
+        await send(topic, event);
+        if (!hearsEcho) emitSafely(emitter, topic, event);
+      } catch (error) {
+        console.warn(`[realtime] publish ${topic} failed, delivered locally`, error.message);
+        emitSafely(emitter, topic, event);
+      }
+    },
+    subscribe(topic, handler) {
+      emitter.on(topic, handler);
+      return () => void emitter.off(topic, handler);
+    },
+    async close() {
+      clearInterval(timer);
+      emitter.removeAllListeners();
+      await listener.close();
+    }
+  };
+}
+
+export {
+  NOTIFY_LIMIT,
+  DEFAULT_CHANNEL,
+  postgresBus
+};
+//# sourceMappingURL=chunk-WHRDA5M4.js.map

package/dist/chunk-WHRDA5M4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/postgres.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nimport { emitSafely, localEmitter } from \"./memory\";\nimport { type PresenceReplica,ReplicatedPresence } from \"./presence\";\nimport type { PresenceOptions, RealtimeBus } from \"./types\";\n\n/**\n * The two PostgreSQL primitives the adapter needs — injected, so this module depends on no database client. Bring\n * your own (the app's pool for `notify`, a dedicated connection for `listen`), or build both with `pgChannel` from\n * `@krizaka/realtime/pg`.\n */\nexport interface PostgresChannel {\n  /** `select pg_notify(channel, payload)` — delivered to every LISTENer at commit. */\n  notify(channel: string, payload: string): Promise<void>;\n  /** One dedicated LISTEN connection that reconnects by itself. */\n  listen(channel: string, onMessage: (payload: string) => void): { readonly connected: boolean; close(): Promise<void> };\n}\n\nexport interface PostgresBusOptions extends Partial<PresenceOptions> {\n  db: PostgresChannel;\n  /**\n   * The NOTIFY channel (one for every topic), a lowercase SQL identifier. Every instance of one app must use the same\n   * one; two apps sharing a database use two. Default `DEFAULT_CHANNEL`.\n   */\n  channel?: string;\n  /** How often this instance tells the others who is connected to it (ms). */\n  snapshotIntervalMs?: number;\n}\n\n/** PostgreSQL's limit is 8000 bytes per payload; the envelope stays under it. */\nexport const NOTIFY_LIMIT = 7900;\n/** The NOTIFY channel used when none is given. */\nexport const DEFAULT_CHANNEL = \"realtime_events\";\nconst PRESENCE_TOPIC = \"__rt.presence\";\n\n/**\n * PostgreSQL LISTEN/NOTIFY: every instance LISTENs on one channel and hands each event to its local subscribers —\n * no broker, the database the app already has does the fan-out. Every instance receives every event (fine for a\n * handful of instances; past that, Redis subscribes per channel). Presence is kept in each instance's memory and\n * replicated over the same channel (deltas + a snapshot every `snapshotIntervalMs`). While the LISTEN connection is\n * down, events still reach the other instances (NOTIFY needs no LISTEN) and this instance's subscribers directly.\n */\nexport function postgresBus(options: PostgresBusOptions): RealtimeBus {\n  const channel = options.channel ?? DEFAULT_CHANNEL;\n  const emitter = localEmitter();\n  const instanceId = randomUUID();\n  const intervalMs = options.snapshotIntervalMs ?? 30_000;\n\n  const send = async (topic: string, event: unknown) => {\n    const payload = JSON.stringify({ topic, event });\n    if (Buffer.byteLength(payload) > NOTIFY_LIMIT) throw new Error(`payload too large for ${topic}`);\n    await options.db.notify(channel, payload);\n  };\n\n  const presence = new ReplicatedPresence({\n    ...options,\n    instanceId,\n    snapshotTtlMs: Math.round(intervalMs * 2.5),\n    broadcast: (replica) => void send(PRESENCE_TOPIC, replica).catch(() => undefined),\n  });\n\n  const listener = options.db.listen(channel, (payload) => {\n    try {\n      const { topic, event } = JSON.parse(payload) as { topic: string; event: unknown };\n      if (topic === PRESENCE_TOPIC) presence.receive(event as PresenceReplica);\n      else emitSafely(emitter, topic, event);\n    } catch {\n      /* not ours */\n    }\n  });\n\n  const timer = setInterval(() => {\n    for (const page of presence.snapshot()) void send(PRESENCE_TOPIC, page).catch(() => undefined);\n  }, intervalMs);\n  timer.unref?.();\n\n  return {\n    kind: \"postgres\",\n    get connected() {\n      return listener.connected;\n    },\n    presence,\n    async publish(topic, event) {\n      // NOTIFY needs no LISTEN: publish even while this instance's own listener is (re)connecting — the others hear it\n      // — and hand it to the local subscribers directly in that case, since the echo will not come back.\n      const hearsEcho = listener.connected;\n      try {\n        await send(topic, event);\n        if (!hearsEcho) emitSafely(emitter, topic, event);\n      } catch (error) {\n        console.warn(`[realtime] publish ${topic} failed, delivered locally`, (error as Error).message);\n        emitSafely(emitter, topic, event);\n      }\n    },\n    subscribe(topic, handler) {\n      emitter.on(topic, handler);\n      return () => void emitter.off(topic, handler);\n    },\n    async close() {\n      clearInterval(timer);\n      emitter.removeAllListeners();\n      await listener.close();\n    },\n  };\n}\n"],"mappings":";;;;;;;AAAA,SAAS,kBAAkB;AA8BpB,IAAM,eAAe;AAErB,IAAM,kBAAkB;AAC/B,IAAM,iBAAiB;AAShB,SAAS,YAAY,SAA0C;AACpE,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,UAAU,aAAa;AAC7B,QAAM,aAAa,WAAW;AAC9B,QAAM,aAAa,QAAQ,sBAAsB;AAEjD,QAAM,OAAO,OAAO,OAAe,UAAmB;AACpD,UAAM,UAAU,KAAK,UAAU,EAAE,OAAO,MAAM,CAAC;AAC/C,QAAI,OAAO,WAAW,OAAO,IAAI,aAAc,OAAM,IAAI,MAAM,yBAAyB,KAAK,EAAE;AAC/F,UAAM,QAAQ,GAAG,OAAO,SAAS,OAAO;AAAA,EAC1C;AAEA,QAAM,WAAW,IAAI,mBAAmB;AAAA,IACtC,GAAG;AAAA,IACH;AAAA,IACA,eAAe,KAAK,MAAM,aAAa,GAAG;AAAA,IAC1C,WAAW,CAAC,YAAY,KAAK,KAAK,gBAAgB,OAAO,EAAE,MAAM,MAAM,MAAS;AAAA,EAClF,CAAC;AAED,QAAM,WAAW,QAAQ,GAAG,OAAO,SAAS,CAAC,YAAY;AACvD,QAAI;AACF,YAAM,EAAE,OAAO,MAAM,IAAI,KAAK,MAAM,OAAO;AAC3C,UAAI,UAAU,eAAgB,UAAS,QAAQ,KAAwB;AAAA,UAClE,YAAW,SAAS,OAAO,KAAK;AAAA,IACvC,QAAQ;AAAA,IAER;AAAA,EACF,CAAC;AAED,QAAM,QAAQ,YAAY,MAAM;AAC9B,eAAW,QAAQ,SAAS,SAAS,EAAG,MAAK,KAAK,gBAAgB,IAAI,EAAE,MAAM,MAAM,MAAS;AAAA,EAC/F,GAAG,UAAU;AACb,QAAM,QAAQ;AAEd,SAAO;AAAA,IACL,MAAM;AAAA,IACN,IAAI,YAAY;AACd,aAAO,SAAS;AAAA,IAClB;AAAA,IACA;AAAA,IACA,MAAM,QAAQ,OAAO,OAAO;AAG1B,YAAM,YAAY,SAAS;AAC3B,UAAI;AACF,cAAM,KAAK,OAAO,KAAK;AACvB,YAAI,CAAC,UAAW,YAAW,SAAS,OAAO,KAAK;AAAA,MAClD,SAAS,OAAO;AACd,gBAAQ,KAAK,sBAAsB,KAAK,8BAA+B,MAAgB,OAAO;AAC9F,mBAAW,SAAS,OAAO,KAAK;AAAA,MAClC;AAAA,IACF;AAAA,IACA,UAAU,OAAO,SAAS;AACxB,cAAQ,GAAG,OAAO,OAAO;AACzB,aAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,OAAO;AAAA,IAC9C;AAAA,IACA,MAAM,QAAQ;AACZ,oBAAc,KAAK;AACnB,cAAQ,mBAAmB;AAC3B,YAAM,SAAS,MAAM;AAAA,IACvB;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { P as PresenceOptions, R as RealtimeBus, a as PresenceState, C as ConnectionState, b as PresenceStore, c as PresenceChange, d as PresenceInfo, B as BusKind } from './types-BP1h40fn.js';
+export { D as DEFAULT_PRESENCE, U as Unsubscribe, r as rank } from './types-BP1h40fn.js';
+import { PostgresChannel } from './postgres.js';
+export { DEFAULT_CHANNEL, NOTIFY_LIMIT, PostgresBusOptions, postgresBus } from './postgres.js';
+export { EventStreamControls, EventStreamOptions, SseFrame, eventStream, sseFrame } from './sse.js';
+import { RedisBusOptions } from './redis.js';
+import 'ioredis';
+
+declare function memoryBus(options?: Partial<PresenceOptions>): RealtimeBus;
+
+/**
+ * Presence in this process's memory, optionally replicated between instances through the bus that carries it
+ * (PostgreSQL LISTEN/NOTIFY). Each instance keeps its own connections (heartbeat + TTL) and tells the others its
+ * *local* view of a person when it changes, plus a snapshot of everyone connected to it at a regular pace; a person's
+ * presence is the best of the local view and the views of the other instances still heard from.
+ *
+ * Changes are announced once: by the instance where the event happened (a remote report only updates what this
+ * instance believes was announced). An instance that dies stops refreshing its snapshot: its people fade out after
+ * `snapshotTtlMs` (no event — clients refresh presence on a slow poll as a fallback).
+ */
+/** What an instance tells the others: one person's local state (`d` = delta), or a page of its connected people. */
+type PresenceReplica = {
+    t: "d";
+    i: string;
+    u: string;
+    s: PresenceState;
+    at: number;
+} | {
+    t: "s";
+    i: string;
+    at: number;
+    users: [string, ConnectionState][];
+};
+interface ReplicatedPresenceOptions extends Partial<PresenceOptions> {
+    /** This instance's id (random per process). */
+    instanceId: string;
+    /** Sends a replica to the other instances (absent: a single instance). */
+    broadcast?: (replica: PresenceReplica) => void;
+    /** How long another instance's snapshot counts (ms) — about 2.5 snapshot intervals. */
+    snapshotTtlMs?: number;
+    /** The most people a snapshot page carries (a PostgreSQL NOTIFY payload stays under 8 KB). */
+    snapshotPage?: number;
+}
+declare class ReplicatedPresence implements PresenceStore {
+    private readonly config;
+    readonly options: PresenceOptions;
+    private readonly local;
+    private readonly remote;
+    private readonly announced;
+    /** The local view last told to the other instances. */
+    private readonly told;
+    private readonly lastSeen;
+    private readonly listeners;
+    private readonly snapshotTtlMs;
+    private readonly snapshotPage;
+    constructor(config: ReplicatedPresenceOptions);
+    /** This instance's view of one person: the best of its live connections (expired ones are dropped). */
+    private localState;
+    private remoteState;
+    private state;
+    /**
+     * Compares with what was announced; records and returns the change. A change caused by another instance's report is
+     * returned only when it is an offline the reporter may not have seen (both instances lost the person at once): the
+     * instance with the greater id announces it — at most a duplicate, never a person left online forever.
+     */
+    private evaluate;
+    private see;
+    beat(userId: string, connectionId: string, state: ConnectionState, now?: number): Promise<PresenceChange | null>;
+    leave(userId: string, connectionId: string, now?: number): Promise<PresenceChange | null>;
+    settle(userId: string, now?: number): Promise<PresenceChange | null>;
+    get(userIds: string[], now?: number): Promise<Map<string, PresenceInfo>>;
+    onChange(listener: (change: PresenceChange) => void): () => undefined;
+    /** Another instance spoke (ignored when it is this one). */
+    receive(replica: PresenceReplica, now?: number): void;
+    /** This instance's connected people, in pages small enough for the bus (sent at a regular pace). */
+    snapshot(now?: number): PresenceReplica[];
+    /** How many connections this instance holds (metrics, tests). */
+    get connections(): number;
+}
+
+/**
+ * @krizaka/realtime — the realtime layer behind one interface (`RealtimeBus`: publish / subscribe by channel, and
+ * presence), three adapters chosen by configuration, and Server-Sent Events. It knows no product: the app wires it
+ * once (its own `lib/realtime.ts`). The root entry needs no driver: the PostgreSQL adapter takes its connection by
+ * injection (`@krizaka/realtime/pg` builds one on `pg`), the Redis adapter lives in `@krizaka/realtime/redis` (`ioredis`).
+ */
+
+interface BusConfig extends Partial<PresenceOptions> {
+    kind: BusKind;
+    /** Required by `postgres`: the NOTIFY / LISTEN primitives (`pgChannel` from `@krizaka/realtime/pg`, or the app's own). */
+    postgres?: PostgresChannel;
+    /** The PostgreSQL NOTIFY channel (`postgres`; default `DEFAULT_CHANNEL`). */
+    channel?: string;
+    /** Required by `redis`: the `redisBus` of `@krizaka/realtime/redis` — passed in, so `ioredis` loads only when used. */
+    redisBus?: (options: RedisBusOptions) => RealtimeBus;
+    /** Required by `redis`. */
+    redisUrl?: string;
+    /** Prefix of every Redis key and channel (`redis`; default `DEFAULT_PREFIX`). */
+    prefix?: string;
+}
+/** The bus a deployment asked for — refuses a configuration that cannot work rather than falling back silently. */
+declare function createBus(config: BusConfig): RealtimeBus;
+/** Reads `REALTIME_BUS` (default `postgres`). */
+declare function busKind(value: string | undefined): BusKind;
+
+export { type BusConfig, BusKind, ConnectionState, PostgresChannel, PresenceChange, PresenceInfo, PresenceOptions, type PresenceReplica, PresenceState, PresenceStore, RealtimeBus, ReplicatedPresence, type ReplicatedPresenceOptions, busKind, createBus, memoryBus };

package/dist/index.js

@@ -0,0 +1,49 @@
+import {
+  eventStream,
+  sseFrame
+} from "./chunk-GBVW7BAQ.js";
+import {
+  DEFAULT_CHANNEL,
+  NOTIFY_LIMIT,
+  postgresBus
+} from "./chunk-WHRDA5M4.js";
+import {
+  DEFAULT_PRESENCE,
+  ReplicatedPresence,
+  memoryBus,
+  rank
+} from "./chunk-HJCRR3FF.js";
+
+// src/index.ts
+function createBus(config) {
+  if (config.kind === "memory") return memoryBus(config);
+  if (config.kind === "postgres") {
+    if (!config.postgres) throw new Error("the postgres realtime bus needs a PostgreSQL channel");
+    return postgresBus({ ...config, db: config.postgres });
+  }
+  if (config.kind === "redis") {
+    if (!config.redisUrl) throw new Error("REALTIME_BUS=redis needs REDIS_URL");
+    if (!config.redisBus) throw new Error("REALTIME_BUS=redis needs redisBus from @krizaka/realtime/redis");
+    return config.redisBus({ ...config, url: config.redisUrl });
+  }
+  throw new Error(`unknown realtime bus "${String(config.kind)}" (memory, postgres or redis)`);
+}
+function busKind(value) {
+  const kind = value?.trim().toLowerCase() || "postgres";
+  if (kind !== "memory" && kind !== "postgres" && kind !== "redis") throw new Error(`REALTIME_BUS must be memory, postgres or redis, not "${value}"`);
+  return kind;
+}
+export {
+  DEFAULT_CHANNEL,
+  DEFAULT_PRESENCE,
+  NOTIFY_LIMIT,
+  ReplicatedPresence,
+  busKind,
+  createBus,
+  eventStream,
+  memoryBus,
+  postgresBus,
+  rank,
+  sseFrame
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @krizaka/realtime — the realtime layer behind one interface (`RealtimeBus`: publish / subscribe by channel, and\n * presence), three adapters chosen by configuration, and Server-Sent Events. It knows no product: the app wires it\n * once (its own `lib/realtime.ts`). The root entry needs no driver: the PostgreSQL adapter takes its connection by\n * injection (`@krizaka/realtime/pg` builds one on `pg`), the Redis adapter lives in `@krizaka/realtime/redis` (`ioredis`).\n */\nexport { memoryBus } from \"./memory\";\nexport { DEFAULT_CHANNEL, NOTIFY_LIMIT, postgresBus, type PostgresBusOptions, type PostgresChannel } from \"./postgres\";\nexport { type PresenceReplica, ReplicatedPresence, type ReplicatedPresenceOptions } from \"./presence\";\nexport { eventStream, type EventStreamControls, type EventStreamOptions, type SseFrame, sseFrame } from \"./sse\";\nexport * from \"./types\";\n\nimport { memoryBus } from \"./memory\";\nimport { postgresBus, type PostgresChannel } from \"./postgres\";\nimport type { RedisBusOptions } from \"./redis\";\nimport type { BusKind, PresenceOptions, RealtimeBus } from \"./types\";\n\nexport interface BusConfig extends Partial<PresenceOptions> {\n  kind: BusKind;\n  /** Required by `postgres`: the NOTIFY / LISTEN primitives (`pgChannel` from `@krizaka/realtime/pg`, or the app's own). */\n  postgres?: PostgresChannel;\n  /** The PostgreSQL NOTIFY channel (`postgres`; default `DEFAULT_CHANNEL`). */\n  channel?: string;\n  /** Required by `redis`: the `redisBus` of `@krizaka/realtime/redis` — passed in, so `ioredis` loads only when used. */\n  redisBus?: (options: RedisBusOptions) => RealtimeBus;\n  /** Required by `redis`. */\n  redisUrl?: string;\n  /** Prefix of every Redis key and channel (`redis`; default `DEFAULT_PREFIX`). */\n  prefix?: string;\n}\n\n/** The bus a deployment asked for — refuses a configuration that cannot work rather than falling back silently. */\nexport function createBus(config: BusConfig): RealtimeBus {\n  if (config.kind === \"memory\") return memoryBus(config);\n  if (config.kind === \"postgres\") {\n    if (!config.postgres) throw new Error(\"the postgres realtime bus needs a PostgreSQL channel\");\n    return postgresBus({ ...config, db: config.postgres });\n  }\n  if (config.kind === \"redis\") {\n    if (!config.redisUrl) throw new Error(\"REALTIME_BUS=redis needs REDIS_URL\");\n    if (!config.redisBus) throw new Error(\"REALTIME_BUS=redis needs redisBus from @krizaka/realtime/redis\");\n    return config.redisBus({ ...config, url: config.redisUrl });\n  }\n  throw new Error(`unknown realtime bus \"${String(config.kind)}\" (memory, postgres or redis)`);\n}\n\n/** Reads `REALTIME_BUS` (default `postgres`). */\nexport function busKind(value: string | undefined): BusKind {\n  const kind = (value?.trim().toLowerCase() || \"postgres\") as BusKind;\n  if (kind !== \"memory\" && kind !== \"postgres\" && kind !== \"redis\") throw new Error(`REALTIME_BUS must be memory, postgres or redis, not \"${value}\"`);\n  return kind;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgCO,SAAS,UAAU,QAAgC;AACxD,MAAI,OAAO,SAAS,SAAU,QAAO,UAAU,MAAM;AACrD,MAAI,OAAO,SAAS,YAAY;AAC9B,QAAI,CAAC,OAAO,SAAU,OAAM,IAAI,MAAM,sDAAsD;AAC5F,WAAO,YAAY,EAAE,GAAG,QAAQ,IAAI,OAAO,SAAS,CAAC;AAAA,EACvD;AACA,MAAI,OAAO,SAAS,SAAS;AAC3B,QAAI,CAAC,OAAO,SAAU,OAAM,IAAI,MAAM,oCAAoC;AAC1E,QAAI,CAAC,OAAO,SAAU,OAAM,IAAI,MAAM,gEAAgE;AACtG,WAAO,OAAO,SAAS,EAAE,GAAG,QAAQ,KAAK,OAAO,SAAS,CAAC;AAAA,EAC5D;AACA,QAAM,IAAI,MAAM,yBAAyB,OAAO,OAAO,IAAI,CAAC,+BAA+B;AAC7F;AAGO,SAAS,QAAQ,OAAoC;AAC1D,QAAM,OAAQ,OAAO,KAAK,EAAE,YAAY,KAAK;AAC7C,MAAI,SAAS,YAAY,SAAS,cAAc,SAAS,QAAS,OAAM,IAAI,MAAM,wDAAwD,KAAK,GAAG;AAClJ,SAAO;AACT;","names":[]}

package/dist/pg.d.ts

@@ -0,0 +1,57 @@
+import { PostgresChannel } from './postgres.js';
+import './types-BP1h40fn.js';
+
+/**
+ * `PostgresChannel` on node-postgres (`pg`, an optional peer dependency): one dedicated LISTEN connection per process
+ * that reconnects by itself with a growing delay, and NOTIFY through a pool — yours or a small one of its own.
+ *
+ * LISTEN needs a **session**: give it a direct connection (`listen`), never a transaction pooler (PgBouncer in
+ * transaction mode drops the subscription between transactions). NOTIFY is one statement and goes through anything,
+ * a transaction pooler included — pass the app's pool as `notify`. Nothing is read from the environment: the app
+ * decides which URL is the direct one.
+ */
+/** Connection settings of node-postgres (`connectionString`, `host`, `ssl`, …). */
+type PgConnection = string | ({
+    connectionString?: string;
+} & Record<string, unknown>);
+/** What NOTIFY goes through: a `pg.Pool`, a `pg.Client`, or anything with the same `query`. */
+interface PgQueryable {
+    query(text: string, values?: unknown[]): Promise<unknown>;
+}
+/** The parts of node-postgres used here — injected by tests or a compatible driver. */
+interface PgDriver {
+    Client: new (config: Record<string, unknown>) => PgListenClient;
+    Pool: new (config: Record<string, unknown>) => PgQueryable & {
+        end(): Promise<void>;
+    };
+}
+interface PgListenClient {
+    connect(): Promise<unknown>;
+    query(text: string): Promise<unknown>;
+    end(): Promise<void>;
+    on(event: "error" | "end", listener: () => void): unknown;
+    on(event: "notification", listener: (msg: {
+        channel: string;
+        payload?: string;
+    }) => void): unknown;
+    removeAllListeners(): unknown;
+}
+interface PgChannelOptions {
+    /** The LISTEN connection: a direct (session) connection string or settings — never a transaction pooler. */
+    listen: PgConnection;
+    /** What NOTIFY goes through (the app's pool, a transaction pooler is fine). Absent: a pool of 2 on `listen`. */
+    notify?: PgQueryable;
+    /** Called when the LISTEN connection comes up or goes down. */
+    onState?: (connected: boolean) => void;
+    /** Longest wait between two reconnection attempts (ms, default 30 000; the first is 1 000). */
+    maxReconnectDelayMs?: number;
+    /** Default: node-postgres. */
+    driver?: PgDriver;
+}
+interface PgChannel extends PostgresChannel {
+    /** Ends the pool this channel opened for NOTIFY (not one passed as `notify`). */
+    close(): Promise<void>;
+}
+declare function pgChannel(options: PgChannelOptions): PgChannel;
+
+export { type PgChannel, type PgChannelOptions, type PgConnection, type PgDriver, type PgListenClient, type PgQueryable, pgChannel };

package/dist/pg.js

@@ -0,0 +1,90 @@
+import {
+  NOTIFY_LIMIT
+} from "./chunk-WHRDA5M4.js";
+import "./chunk-HJCRR3FF.js";
+
+// src/pg.ts
+import pg from "pg";
+var IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+var settings = (connection) => typeof connection === "string" ? { connectionString: connection } : { ...connection };
+function pgChannel(options) {
+  const driver = options.driver ?? pg;
+  const maxDelay = options.maxReconnectDelayMs ?? 3e4;
+  let ownPool = null;
+  const notifier = () => options.notify ?? (ownPool ??= new driver.Pool({ ...settings(options.listen), max: 2 }));
+  return {
+    async notify(channel, payload) {
+      if (Buffer.byteLength(payload) > NOTIFY_LIMIT) throw new Error(`notify payload too large (${channel})`);
+      await notifier().query("select pg_notify($1, $2)", [channel, payload]);
+    },
+    listen(channel, onMessage) {
+      if (!IDENTIFIER.test(channel)) throw new Error(`invalid channel name ${channel}`);
+      let client = null;
+      let closed = false;
+      let connected = false;
+      let delay = 1e3;
+      let timer = null;
+      const setState = (value) => {
+        if (connected === value) return;
+        connected = value;
+        options.onState?.(value);
+      };
+      const retry = () => {
+        setState(false);
+        client?.removeAllListeners();
+        client?.end().catch(() => void 0);
+        client = null;
+        if (closed || timer) return;
+        timer = setTimeout(() => {
+          timer = null;
+          void connect();
+        }, delay);
+        delay = Math.min(delay * 2, maxDelay);
+      };
+      const connect = async () => {
+        const next = new driver.Client(settings(options.listen));
+        client = next;
+        next.on("error", retry);
+        next.on("end", retry);
+        next.on("notification", (msg) => {
+          if (msg.channel === channel && msg.payload) onMessage(msg.payload);
+        });
+        try {
+          await next.connect();
+          await next.query(`LISTEN ${channel}`);
+          if (closed) return void next.end().catch(() => void 0);
+          delay = 1e3;
+          setState(true);
+        } catch (error) {
+          console.warn(`[realtime] listen ${channel}: ${error.message}`);
+          retry();
+        }
+      };
+      void connect();
+      return {
+        get connected() {
+          return connected;
+        },
+        async close() {
+          closed = true;
+          if (timer) clearTimeout(timer);
+          timer = null;
+          setState(false);
+          const last = client;
+          client = null;
+          last?.removeAllListeners();
+          await last?.end().catch(() => void 0);
+        }
+      };
+    },
+    async close() {
+      const pool = ownPool;
+      ownPool = null;
+      await pool?.end();
+    }
+  };
+}
+export {
+  pgChannel
+};
+//# sourceMappingURL=pg.js.map

package/dist/pg.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pg.ts"],"sourcesContent":["import pg from \"pg\";\n\nimport { NOTIFY_LIMIT, type PostgresChannel } from \"./postgres\";\n\n/**\n * `PostgresChannel` on node-postgres (`pg`, an optional peer dependency): one dedicated LISTEN connection per process\n * that reconnects by itself with a growing delay, and NOTIFY through a pool — yours or a small one of its own.\n *\n * LISTEN needs a **session**: give it a direct connection (`listen`), never a transaction pooler (PgBouncer in\n * transaction mode drops the subscription between transactions). NOTIFY is one statement and goes through anything,\n * a transaction pooler included — pass the app's pool as `notify`. Nothing is read from the environment: the app\n * decides which URL is the direct one.\n */\n\n/** Connection settings of node-postgres (`connectionString`, `host`, `ssl`, …). */\nexport type PgConnection = string | ({ connectionString?: string } & Record<string, unknown>);\n\n/** What NOTIFY goes through: a `pg.Pool`, a `pg.Client`, or anything with the same `query`. */\nexport interface PgQueryable {\n  query(text: string, values?: unknown[]): Promise<unknown>;\n}\n\n/** The parts of node-postgres used here — injected by tests or a compatible driver. */\nexport interface PgDriver {\n  Client: new (config: Record<string, unknown>) => PgListenClient;\n  Pool: new (config: Record<string, unknown>) => PgQueryable & { end(): Promise<void> };\n}\n\nexport interface PgListenClient {\n  connect(): Promise<unknown>;\n  query(text: string): Promise<unknown>;\n  end(): Promise<void>;\n  on(event: \"error\" | \"end\", listener: () => void): unknown;\n  on(event: \"notification\", listener: (msg: { channel: string; payload?: string }) => void): unknown;\n  removeAllListeners(): unknown;\n}\n\nexport interface PgChannelOptions {\n  /** The LISTEN connection: a direct (session) connection string or settings — never a transaction pooler. */\n  listen: PgConnection;\n  /** What NOTIFY goes through (the app's pool, a transaction pooler is fine). Absent: a pool of 2 on `listen`. */\n  notify?: PgQueryable;\n  /** Called when the LISTEN connection comes up or goes down. */\n  onState?: (connected: boolean) => void;\n  /** Longest wait between two reconnection attempts (ms, default 30 000; the first is 1 000). */\n  maxReconnectDelayMs?: number;\n  /** Default: node-postgres. */\n  driver?: PgDriver;\n}\n\nexport interface PgChannel extends PostgresChannel {\n  /** Ends the pool this channel opened for NOTIFY (not one passed as `notify`). */\n  close(): Promise<void>;\n}\n\nconst IDENTIFIER = /^[a-z_][a-z0-9_]*$/;\n\nconst settings = (connection: PgConnection): Record<string, unknown> =>\n  typeof connection === \"string\" ? { connectionString: connection } : { ...connection };\n\nexport function pgChannel(options: PgChannelOptions): PgChannel {\n  const driver: PgDriver = options.driver ?? (pg as unknown as PgDriver);\n  const maxDelay = options.maxReconnectDelayMs ?? 30_000;\n  let ownPool: (PgQueryable & { end(): Promise<void> }) | null = null;\n  const notifier = () => options.notify ?? (ownPool ??= new driver.Pool({ ...settings(options.listen), max: 2 }));\n\n  return {\n    async notify(channel, payload) {\n      if (Buffer.byteLength(payload) > NOTIFY_LIMIT) throw new Error(`notify payload too large (${channel})`);\n      await notifier().query(\"select pg_notify($1, $2)\", [channel, payload]);\n    },\n\n    listen(channel, onMessage) {\n      if (!IDENTIFIER.test(channel)) throw new Error(`invalid channel name ${channel}`);\n      let client: PgListenClient | null = null;\n      let closed = false;\n      let connected = false;\n      let delay = 1000;\n      let timer: ReturnType<typeof setTimeout> | null = null;\n\n      const setState = (value: boolean) => {\n        if (connected === value) return;\n        connected = value;\n        options.onState?.(value);\n      };\n\n      const retry = () => {\n        setState(false);\n        client?.removeAllListeners();\n        client?.end().catch(() => undefined);\n        client = null;\n        if (closed || timer) return;\n        timer = setTimeout(() => {\n          timer = null;\n          void connect();\n        }, delay);\n        delay = Math.min(delay * 2, maxDelay);\n      };\n\n      const connect = async () => {\n        const next = new driver.Client(settings(options.listen));\n        client = next;\n        next.on(\"error\", retry);\n        next.on(\"end\", retry);\n        next.on(\"notification\", (msg) => {\n          if (msg.channel === channel && msg.payload) onMessage(msg.payload);\n        });\n        try {\n          await next.connect();\n          await next.query(`LISTEN ${channel}`);\n          if (closed) return void next.end().catch(() => undefined);\n          delay = 1000;\n          setState(true);\n        } catch (error) {\n          console.warn(`[realtime] listen ${channel}: ${(error as Error).message}`);\n          retry();\n        }\n      };\n\n      void connect();\n      return {\n        get connected() {\n          return connected;\n        },\n        async close() {\n          closed = true;\n          if (timer) clearTimeout(timer);\n          timer = null;\n          setState(false);\n          const last = client;\n          client = null;\n          last?.removeAllListeners();\n          await last?.end().catch(() => undefined);\n        },\n      };\n    },\n\n    async close() {\n      const pool = ownPool;\n      ownPool = null;\n      await pool?.end();\n    },\n  };\n}\n"],"mappings":";;;;;;AAAA,OAAO,QAAQ;AAuDf,IAAM,aAAa;AAEnB,IAAM,WAAW,CAAC,eAChB,OAAO,eAAe,WAAW,EAAE,kBAAkB,WAAW,IAAI,EAAE,GAAG,WAAW;AAE/E,SAAS,UAAU,SAAsC;AAC9D,QAAM,SAAmB,QAAQ,UAAW;AAC5C,QAAM,WAAW,QAAQ,uBAAuB;AAChD,MAAI,UAA2D;AAC/D,QAAM,WAAW,MAAM,QAAQ,WAAW,YAAY,IAAI,OAAO,KAAK,EAAE,GAAG,SAAS,QAAQ,MAAM,GAAG,KAAK,EAAE,CAAC;AAE7G,SAAO;AAAA,IACL,MAAM,OAAO,SAAS,SAAS;AAC7B,UAAI,OAAO,WAAW,OAAO,IAAI,aAAc,OAAM,IAAI,MAAM,6BAA6B,OAAO,GAAG;AACtG,YAAM,SAAS,EAAE,MAAM,4BAA4B,CAAC,SAAS,OAAO,CAAC;AAAA,IACvE;AAAA,IAEA,OAAO,SAAS,WAAW;AACzB,UAAI,CAAC,WAAW,KAAK,OAAO,EAAG,OAAM,IAAI,MAAM,wBAAwB,OAAO,EAAE;AAChF,UAAI,SAAgC;AACpC,UAAI,SAAS;AACb,UAAI,YAAY;AAChB,UAAI,QAAQ;AACZ,UAAI,QAA8C;AAElD,YAAM,WAAW,CAAC,UAAmB;AACnC,YAAI,cAAc,MAAO;AACzB,oBAAY;AACZ,gBAAQ,UAAU,KAAK;AAAA,MACzB;AAEA,YAAM,QAAQ,MAAM;AAClB,iBAAS,KAAK;AACd,gBAAQ,mBAAmB;AAC3B,gBAAQ,IAAI,EAAE,MAAM,MAAM,MAAS;AACnC,iBAAS;AACT,YAAI,UAAU,MAAO;AACrB,gBAAQ,WAAW,MAAM;AACvB,kBAAQ;AACR,eAAK,QAAQ;AAAA,QACf,GAAG,KAAK;AACR,gBAAQ,KAAK,IAAI,QAAQ,GAAG,QAAQ;AAAA,MACtC;AAEA,YAAM,UAAU,YAAY;AAC1B,cAAM,OAAO,IAAI,OAAO,OAAO,SAAS,QAAQ,MAAM,CAAC;AACvD,iBAAS;AACT,aAAK,GAAG,SAAS,KAAK;AACtB,aAAK,GAAG,OAAO,KAAK;AACpB,aAAK,GAAG,gBAAgB,CAAC,QAAQ;AAC/B,cAAI,IAAI,YAAY,WAAW,IAAI,QAAS,WAAU,IAAI,OAAO;AAAA,QACnE,CAAC;AACD,YAAI;AACF,gBAAM,KAAK,QAAQ;AACnB,gBAAM,KAAK,MAAM,UAAU,OAAO,EAAE;AACpC,cAAI,OAAQ,QAAO,KAAK,KAAK,IAAI,EAAE,MAAM,MAAM,MAAS;AACxD,kBAAQ;AACR,mBAAS,IAAI;AAAA,QACf,SAAS,OAAO;AACd,kBAAQ,KAAK,qBAAqB,OAAO,KAAM,MAAgB,OAAO,EAAE;AACxE,gBAAM;AAAA,QACR;AAAA,MACF;AAEA,WAAK,QAAQ;AACb,aAAO;AAAA,QACL,IAAI,YAAY;AACd,iBAAO;AAAA,QACT;AAAA,QACA,MAAM,QAAQ;AACZ,mBAAS;AACT,cAAI,MAAO,cAAa,KAAK;AAC7B,kBAAQ;AACR,mBAAS,KAAK;AACd,gBAAM,OAAO;AACb,mBAAS;AACT,gBAAM,mBAAmB;AACzB,gBAAM,MAAM,IAAI,EAAE,MAAM,MAAM,MAAS;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAAA,IAEA,MAAM,QAAQ;AACZ,YAAM,OAAO;AACb,gBAAU;AACV,YAAM,MAAM,IAAI;AAAA,IAClB;AAAA,EACF;AACF;","names":[]}

package/dist/postgres.d.ts

@@ -0,0 +1,40 @@
+import { P as PresenceOptions, R as RealtimeBus } from './types-BP1h40fn.js';
+
+/**
+ * The two PostgreSQL primitives the adapter needs — injected, so this module depends on no database client. Bring
+ * your own (the app's pool for `notify`, a dedicated connection for `listen`), or build both with `pgChannel` from
+ * `@krizaka/realtime/pg`.
+ */
+interface PostgresChannel {
+    /** `select pg_notify(channel, payload)` — delivered to every LISTENer at commit. */
+    notify(channel: string, payload: string): Promise<void>;
+    /** One dedicated LISTEN connection that reconnects by itself. */
+    listen(channel: string, onMessage: (payload: string) => void): {
+        readonly connected: boolean;
+        close(): Promise<void>;
+    };
+}
+interface PostgresBusOptions extends Partial<PresenceOptions> {
+    db: PostgresChannel;
+    /**
+     * The NOTIFY channel (one for every topic), a lowercase SQL identifier. Every instance of one app must use the same
+     * one; two apps sharing a database use two. Default `DEFAULT_CHANNEL`.
+     */
+    channel?: string;
+    /** How often this instance tells the others who is connected to it (ms). */
+    snapshotIntervalMs?: number;
+}
+/** PostgreSQL's limit is 8000 bytes per payload; the envelope stays under it. */
+declare const NOTIFY_LIMIT = 7900;
+/** The NOTIFY channel used when none is given. */
+declare const DEFAULT_CHANNEL = "realtime_events";
+/**
+ * PostgreSQL LISTEN/NOTIFY: every instance LISTENs on one channel and hands each event to its local subscribers —
+ * no broker, the database the app already has does the fan-out. Every instance receives every event (fine for a
+ * handful of instances; past that, Redis subscribes per channel). Presence is kept in each instance's memory and
+ * replicated over the same channel (deltas + a snapshot every `snapshotIntervalMs`). While the LISTEN connection is
+ * down, events still reach the other instances (NOTIFY needs no LISTEN) and this instance's subscribers directly.
+ */
+declare function postgresBus(options: PostgresBusOptions): RealtimeBus;
+
+export { DEFAULT_CHANNEL, NOTIFY_LIMIT, type PostgresBusOptions, type PostgresChannel, postgresBus };

package/dist/postgres.js

@@ -0,0 +1,12 @@
+import {
+  DEFAULT_CHANNEL,
+  NOTIFY_LIMIT,
+  postgresBus
+} from "./chunk-WHRDA5M4.js";
+import "./chunk-HJCRR3FF.js";
+export {
+  DEFAULT_CHANNEL,
+  NOTIFY_LIMIT,
+  postgresBus
+};
+//# sourceMappingURL=postgres.js.map

package/dist/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/redis.d.ts

@@ -0,0 +1,52 @@
+import { RedisOptions, Redis } from 'ioredis';
+import { P as PresenceOptions, b as PresenceStore, C as ConnectionState, a as PresenceState, d as PresenceInfo, R as RealtimeBus } from './types-BP1h40fn.js';
+
+interface RedisBusOptions extends Partial<PresenceOptions> {
+    /** `redis://` or `rediss://` (Redis or Valkey — DigitalOcean Managed Caching speaks the same protocol). */
+    url: string;
+    /** Prefix of every key and channel (several products can share one server). Default `DEFAULT_PREFIX`. */
+    prefix?: string;
+    /** How long "last seen" is kept (seconds). */
+    lastSeenTtlSeconds?: number;
+    redisOptions?: RedisOptions;
+}
+/** The key and channel prefix used when none is given — give each app its own when they share a server. */
+declare const DEFAULT_PREFIX = "rt:";
+/** Presence in Redis / Valkey: shared by every instance, one atomic script per beat, keys that expire by themselves. */
+declare class RedisPresence implements PresenceStore {
+    private readonly redis;
+    private readonly prefix;
+    readonly options: PresenceOptions;
+    private readonly keep;
+    constructor(redis: Redis, prefix: string, options?: Partial<PresenceOptions> & {
+        lastSeenTtlSeconds?: number;
+    });
+    private keys;
+    private run;
+    beat(userId: string, connectionId: string, state: ConnectionState, now?: number): Promise<{
+        userId: string;
+        state: PresenceState;
+        at: number;
+    } | null>;
+    leave(userId: string, connectionId: string, now?: number): Promise<{
+        userId: string;
+        state: PresenceState;
+        at: number;
+    } | null>;
+    settle(userId: string, now?: number): Promise<{
+        userId: string;
+        state: PresenceState;
+        at: number;
+    } | null>;
+    /** Every change is the answer of the call that caused it: nothing is discovered later. */
+    onChange(): () => void;
+    get(userIds: string[], now?: number): Promise<Map<string, PresenceInfo>>;
+}
+/**
+ * Redis / Valkey pub/sub: each instance subscribes only to the channels its open streams need (one subscription per
+ * channel, counted), so an event crosses the network only to the instances that have someone listening — the choice
+ * for several instances and many streams. Presence lives in Redis (`RedisPresence`).
+ */
+declare function redisBus(options: RedisBusOptions): RealtimeBus;
+
+export { DEFAULT_PREFIX, type RedisBusOptions, RedisPresence, redisBus };