reflectdb 0.1.0 → 0.1.2

package/dist/cjs/server/ephemeral/index.cjs

@@ -0,0 +1,180 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/server/ephemeral/index.ts
+var exports_ephemeral = {};
+__export(exports_ephemeral, {
+  EphemeralManager: () => EphemeralManager,
+  createMemoryEphemeral: () => createMemoryEphemeral
+});
+module.exports = __toCommonJS(exports_ephemeral);
+
+// src/server/ephemeral/memory.ts
+var DEFAULT_MAX_ENTRIES = 1e4;
+function indexKey(room, key, clientId) {
+  return `${room}\x00${key}\x00${clientId}`;
+}
+function parseIndexKey(packed) {
+  const [room, key, clientId] = packed.split("\x00");
+  return { room, key, clientId };
+}
+
+class EphemeralManager {
+  store = new Map;
+  clientIndex = new Map;
+  entryCount = 0;
+  maxEntries;
+  constructor(maxEntries) {
+    this.maxEntries = maxEntries ?? DEFAULT_MAX_ENTRIES;
+  }
+  set(room, key, clientId, userId, data, ttlMs) {
+    const roomMap = this.store.get(room) ?? new Map;
+    const keyMap = roomMap.get(key) ?? new Map;
+    const existing = keyMap.get(clientId);
+    if (!existing && this.entryCount >= this.maxEntries) {
+      return false;
+    }
+    const state = {
+      clientId,
+      userId,
+      key,
+      data,
+      updatedAt: Date.now(),
+      ttlMs
+    };
+    keyMap.set(clientId, state);
+    roomMap.set(key, keyMap);
+    this.store.set(room, roomMap);
+    if (!existing) {
+      this.entryCount++;
+      this.addToClientIndex(clientId, indexKey(room, key, clientId));
+    }
+    return true;
+  }
+  addToClientIndex(clientId, packed) {
+    const clientSet = this.clientIndex.get(clientId) ?? new Set;
+    clientSet.add(packed);
+    this.clientIndex.set(clientId, clientSet);
+  }
+  removeFromClientIndex(clientId, packed) {
+    const clientSet = this.clientIndex.get(clientId);
+    if (!clientSet)
+      return;
+    clientSet.delete(packed);
+    if (clientSet.size === 0)
+      this.clientIndex.delete(clientId);
+  }
+  get(room, key) {
+    const roomMap = this.store.get(room);
+    if (!roomMap)
+      return {};
+    const keyMap = roomMap.get(key);
+    if (!keyMap)
+      return {};
+    return Object.fromEntries(keyMap.entries());
+  }
+  getRoom(room) {
+    const roomMap = this.store.get(room);
+    if (!roomMap)
+      return {};
+    const out = {};
+    for (const [key, keyMap] of roomMap) {
+      out[key] = Object.fromEntries(keyMap.entries());
+    }
+    return out;
+  }
+  remove(room, key, clientId) {
+    const roomMap = this.store.get(room);
+    if (!roomMap)
+      return;
+    const keyMap = roomMap.get(key);
+    if (!keyMap)
+      return;
+    if (keyMap.has(clientId)) {
+      keyMap.delete(clientId);
+      this.entryCount--;
+      this.removeFromClientIndex(clientId, indexKey(room, key, clientId));
+    }
+    if (keyMap.size === 0) {
+      roomMap.delete(key);
+    }
+    if (roomMap.size === 0) {
+      this.store.delete(room);
+    }
+  }
+  removeClient(clientId) {
+    const indices = this.clientIndex.get(clientId);
+    if (!indices)
+      return;
+    const entries = [...indices];
+    for (const packed of entries) {
+      const { room, key, clientId: owner } = parseIndexKey(packed);
+      this.remove(room, key, owner);
+    }
+    this.clientIndex.delete(clientId);
+  }
+  cleanupExpired() {
+    const now = Date.now();
+    const toRemove = [];
+    for (const [room, roomMap] of this.store) {
+      for (const [key, keyMap] of roomMap) {
+        for (const [clientId, state] of keyMap) {
+          if (state.ttlMs && now - state.updatedAt > state.ttlMs) {
+            toRemove.push({ room, key, clientId });
+          }
+        }
+      }
+    }
+    for (const { room, key, clientId } of toRemove) {
+      this.remove(room, key, clientId);
+    }
+  }
+  size() {
+    return this.entryCount;
+  }
+  destroy() {
+    this.store.clear();
+    this.clientIndex.clear();
+    this.entryCount = 0;
+  }
+}
+function createMemoryEphemeral(maxEntries) {
+  return new EphemeralManager(maxEntries);
+}

package/dist/cjs/server/ephemeral/index.d.cts

@@ -0,0 +1,102 @@
+/**
+* Ephemeral (presence, cursors, typing) storage and fan-out seam.
+*
+* The default adapter keeps state in the server process, which is correct for a
+* single node and invisible across a fleet: two clients on different instances
+* never see each other. An adapter backed by shared infrastructure (Redis, or a
+* hosted service) fixes both halves — the shared store answers "who is here"
+* for a client that just joined, and the bus carries each event to the peers
+* holding the other sockets.
+*/
+type MaybePromise<T> = T | Promise<T>;
+interface EphemeralState {
+	clientId: string;
+	userId: string;
+	key: string;
+	data: Record<string, unknown>;
+	updatedAt: number;
+	ttlMs?: number;
+}
+/** One fan-out target: subscribers of `query`, narrowed to `room` when set. */
+interface EphemeralTarget {
+	query: string;
+	room: string | null;
+}
+/**
+* An ephemeral event as it crosses the bus between server instances.
+*
+* Recipients are resolved on the origin instance and carried here as `targets`,
+* because the receiving instance holds no session for the sender and so cannot
+* re-derive them. `serverId` lets an instance drop its own echo on buses that
+* deliver published messages back to the publisher.
+*/
+interface EphemeralBroadcast {
+	serverId: string;
+	key: string;
+	clientId: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+	targets: EphemeralTarget[];
+}
+/**
+* Backing store and fan-out bus for ephemeral state.
+*
+* `publish`/`subscribe` are optional: an adapter that omits them is a
+* single-process store, and the handler still fans out to its own sockets.
+*/
+interface EphemeralAdapter {
+	/**
+	* Record one entry, keyed by `clientId`.
+	*
+	* Peer identity is the connection, not the account: two tabs from one login
+	* are two cursors, and the client bindings key peers the same way. `userId`
+	* rides along for display and authorization, not as the entry's identity.
+	*
+	* Returns false when the adapter is at capacity, which the handler surfaces
+	* as `ephemeral_full` rather than evicting silently.
+	*/
+	set(room: string, key: string, clientId: string, userId: string, data: Record<string, unknown>, ttlMs?: number): MaybePromise<boolean>;
+	/** Live entries for one channel, keyed by clientId. */
+	get(room: string, key: string): MaybePromise<Record<string, EphemeralState>>;
+	/**
+	* Live entries for every channel in a room, keyed by channel key then
+	* clientId. Backs the snapshot a client receives when it joins.
+	*/
+	getRoom(room: string): MaybePromise<Record<string, Record<string, EphemeralState>>>;
+	remove(room: string, key: string, clientId: string): MaybePromise<void>;
+	/** Drop everything a disconnecting client published. */
+	removeClient(clientId: string): MaybePromise<void>;
+	/** Sweep entries past their TTL. Called on a timer by the handler. */
+	cleanupExpired(): MaybePromise<void>;
+	/** Current entry count, for the capacity gate and `ephemeral_full`. */
+	size(): MaybePromise<number>;
+	destroy(): MaybePromise<void>;
+	/** Hand an event to peer instances. Absent on single-process adapters. */
+	publish?(event: EphemeralBroadcast): MaybePromise<void>;
+	/**
+	* Register the handler's delivery callback for events published by peers.
+	* Called once during wiring. Absent on single-process adapters.
+	*/
+	subscribe?(onEvent: (event: EphemeralBroadcast) => void): MaybePromise<void>;
+}
+declare class EphemeralManager implements EphemeralAdapter {
+	private store;
+	private clientIndex;
+	private entryCount;
+	private maxEntries;
+	constructor(maxEntries?: number);
+	set(room: string, key: string, clientId: string, userId: string, data: Record<string, unknown>, ttlMs?: number): boolean;
+	private addToClientIndex;
+	private removeFromClientIndex;
+	get(room: string, key: string): Record<string, EphemeralState>;
+	getRoom(room: string): Record<string, Record<string, EphemeralState>>;
+	remove(room: string, key: string, clientId: string): void;
+	removeClient(clientId: string): void;
+	cleanupExpired(): void;
+	size(): number;
+	destroy(): void;
+}
+/** Convenience factory mirroring the other adapters. */
+declare function createMemoryEphemeral(maxEntries?: number): EphemeralManager;
+export { EphemeralAdapter, EphemeralBroadcast, EphemeralManager, EphemeralState, EphemeralTarget, MaybePromise, createMemoryEphemeral };

package/dist/cjs/server/ephemeral/redis.cjs

@@ -0,0 +1,226 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/server/ephemeral/redis.ts
+var exports_redis = {};
+__export(exports_redis, {
+  createRedisEphemeral: () => createRedisEphemeral
+});
+module.exports = __toCommonJS(exports_redis);
+var DEFAULT_PREFIX = "reflectdb:eph";
+var DEFAULT_MAX_ENTRIES = 1e5;
+var DEFAULT_HASH_TTL_SECONDS = 24 * 60 * 60;
+var SWEEP_BATCH = 1000;
+function packed(room, key, clientId) {
+  return `${room}\x00${key}\x00${clientId}`;
+}
+function unpack(value) {
+  const [room, key, clientId] = value.split("\x00");
+  return { room, key, clientId };
+}
+function hashEntries(reply) {
+  if (Array.isArray(reply)) {
+    const out = [];
+    for (let i = 0;i + 1 < reply.length; i += 2) {
+      out.push([String(reply[i]), String(reply[i + 1])]);
+    }
+    return out;
+  }
+  if (reply && typeof reply === "object") {
+    return Object.entries(reply).map(([k, v]) => [k, String(v)]);
+  }
+  return [];
+}
+function toStringArray(reply) {
+  return Array.isArray(reply) ? reply.map((v) => String(v)) : [];
+}
+var SET_SCRIPT = `
+local isNew = 0
+if redis.call('HEXISTS', KEYS[1], ARGV[1]) == 0 then
+  local count = tonumber(redis.call('GET', KEYS[5]) or '0')
+  if count >= tonumber(ARGV[6]) then return 0 end
+  isNew = 1
+end
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+redis.call('EXPIRE', KEYS[1], ARGV[7])
+redis.call('SADD', KEYS[2], ARGV[4])
+redis.call('EXPIRE', KEYS[2], ARGV[7])
+redis.call('SADD', KEYS[3], ARGV[3])
+redis.call('EXPIRE', KEYS[3], ARGV[7])
+if ARGV[5] ~= '' then
+  redis.call('ZADD', KEYS[4], ARGV[5], ARGV[3])
+else
+  redis.call('ZREM', KEYS[4], ARGV[3])
+end
+if isNew == 1 then redis.call('INCR', KEYS[5]) end
+return 1
+`;
+var REMOVE_SCRIPT = `
+if redis.call('HDEL', KEYS[1], ARGV[1]) == 0 then return 0 end
+redis.call('ZREM', KEYS[3], ARGV[2])
+redis.call('SREM', KEYS[5], ARGV[2])
+if redis.call('HLEN', KEYS[1]) == 0 then
+  redis.call('SREM', KEYS[2], ARGV[3])
+end
+local count = tonumber(redis.call('GET', KEYS[4]) or '0')
+if count > 0 then redis.call('DECR', KEYS[4]) end
+return 1
+`;
+function createRedisEphemeral(config) {
+  const client = config.client;
+  const p = config.prefix ?? DEFAULT_PREFIX;
+  const maxEntries = config.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const hashTtl = config.hashTtlSeconds ?? DEFAULT_HASH_TTL_SECONDS;
+  const stateKey = (room, key) => `${p}:s:${room}:${key}`;
+  const roomKeysKey = (room) => `${p}:rk:${room}`;
+  const clientKey = (clientId) => `${p}:c:${clientId}`;
+  const expKey = `${p}:exp`;
+  const countKey = `${p}:n`;
+  const busChannel = `${p}:bus`;
+  let readyPromise = null;
+  let onEventCallback = null;
+  function parseState(raw) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  function isLive(state, now) {
+    return !state.ttlMs || now - state.updatedAt <= state.ttlMs;
+  }
+  async function removeEntry(room, key, clientId) {
+    await client.call("EVAL", REMOVE_SCRIPT, 5, stateKey(room, key), roomKeysKey(room), expKey, countKey, clientKey(clientId), clientId, packed(room, key, clientId), key);
+  }
+  async function ready() {
+    if (readyPromise)
+      return readyPromise;
+    const subscriber = config.subscriber;
+    if (!subscriber)
+      return;
+    readyPromise = (async () => {
+      await subscriber.subscribe(busChannel, (payload) => {
+        if (!onEventCallback)
+          return;
+        try {
+          onEventCallback(JSON.parse(payload));
+        } catch {}
+      });
+    })();
+    return readyPromise;
+  }
+  return {
+    ready,
+    async set(room, key, clientId, userId, data, ttlMs) {
+      const now = Date.now();
+      const state = {
+        clientId,
+        userId,
+        key,
+        data,
+        updatedAt: now,
+        ttlMs
+      };
+      const entry = packed(room, key, clientId);
+      const result = await client.call("EVAL", SET_SCRIPT, 5, stateKey(room, key), roomKeysKey(room), clientKey(clientId), expKey, countKey, clientId, JSON.stringify(state), entry, key, ttlMs ? String(now + ttlMs) : "", String(maxEntries), String(hashTtl));
+      return Number(result) === 1;
+    },
+    async get(room, key) {
+      const reply = await client.call("HGETALL", stateKey(room, key));
+      const now = Date.now();
+      const out = {};
+      for (const [entryClientId, raw] of hashEntries(reply)) {
+        const state = parseState(raw);
+        if (state && isLive(state, now))
+          out[entryClientId] = state;
+      }
+      return out;
+    },
+    async getRoom(room) {
+      const keys = toStringArray(await client.call("SMEMBERS", roomKeysKey(room)));
+      const now = Date.now();
+      const out = {};
+      for (const key of keys) {
+        const reply = await client.call("HGETALL", stateKey(room, key));
+        const channel = {};
+        for (const [entryClientId, raw] of hashEntries(reply)) {
+          const state = parseState(raw);
+          if (state && isLive(state, now))
+            channel[entryClientId] = state;
+        }
+        if (Object.keys(channel).length > 0)
+          out[key] = channel;
+      }
+      return out;
+    },
+    async remove(room, key, clientId) {
+      await removeEntry(room, key, clientId);
+    },
+    async removeClient(clientId) {
+      const entries = toStringArray(await client.call("SMEMBERS", clientKey(clientId)));
+      for (const value of entries) {
+        const { room, key, clientId: owner } = unpack(value);
+        await removeEntry(room, key, owner);
+      }
+      await client.call("DEL", clientKey(clientId));
+    },
+    async cleanupExpired() {
+      const due = toStringArray(await client.call("ZRANGEBYSCORE", expKey, "-inf", String(Date.now()), "LIMIT", 0, SWEEP_BATCH));
+      for (const value of due) {
+        const { room, key, clientId } = unpack(value);
+        await removeEntry(room, key, clientId);
+      }
+    },
+    async size() {
+      const reply = await client.call("GET", countKey);
+      return reply == null ? 0 : Number(reply);
+    },
+    async destroy() {
+      onEventCallback = null;
+    },
+    async publish(event) {
+      await client.call("PUBLISH", busChannel, JSON.stringify(event));
+    },
+    async subscribe(onEvent) {
+      onEventCallback = onEvent;
+      await ready();
+    }
+  };
+}

package/dist/cjs/server/ephemeral/redis.d.cts

@@ -0,0 +1,136 @@
+/**
+* Ephemeral (presence, cursors, typing) storage and fan-out seam.
+*
+* The default adapter keeps state in the server process, which is correct for a
+* single node and invisible across a fleet: two clients on different instances
+* never see each other. An adapter backed by shared infrastructure (Redis, or a
+* hosted service) fixes both halves — the shared store answers "who is here"
+* for a client that just joined, and the bus carries each event to the peers
+* holding the other sockets.
+*/
+type MaybePromise<T> = T | Promise<T>;
+interface EphemeralState {
+	clientId: string;
+	userId: string;
+	key: string;
+	data: Record<string, unknown>;
+	updatedAt: number;
+	ttlMs?: number;
+}
+/** One fan-out target: subscribers of `query`, narrowed to `room` when set. */
+interface EphemeralTarget {
+	query: string;
+	room: string | null;
+}
+/**
+* An ephemeral event as it crosses the bus between server instances.
+*
+* Recipients are resolved on the origin instance and carried here as `targets`,
+* because the receiving instance holds no session for the sender and so cannot
+* re-derive them. `serverId` lets an instance drop its own echo on buses that
+* deliver published messages back to the publisher.
+*/
+interface EphemeralBroadcast {
+	serverId: string;
+	key: string;
+	clientId: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+	targets: EphemeralTarget[];
+}
+/**
+* Backing store and fan-out bus for ephemeral state.
+*
+* `publish`/`subscribe` are optional: an adapter that omits them is a
+* single-process store, and the handler still fans out to its own sockets.
+*/
+interface EphemeralAdapter {
+	/**
+	* Record one entry, keyed by `clientId`.
+	*
+	* Peer identity is the connection, not the account: two tabs from one login
+	* are two cursors, and the client bindings key peers the same way. `userId`
+	* rides along for display and authorization, not as the entry's identity.
+	*
+	* Returns false when the adapter is at capacity, which the handler surfaces
+	* as `ephemeral_full` rather than evicting silently.
+	*/
+	set(room: string, key: string, clientId: string, userId: string, data: Record<string, unknown>, ttlMs?: number): MaybePromise<boolean>;
+	/** Live entries for one channel, keyed by clientId. */
+	get(room: string, key: string): MaybePromise<Record<string, EphemeralState>>;
+	/**
+	* Live entries for every channel in a room, keyed by channel key then
+	* clientId. Backs the snapshot a client receives when it joins.
+	*/
+	getRoom(room: string): MaybePromise<Record<string, Record<string, EphemeralState>>>;
+	remove(room: string, key: string, clientId: string): MaybePromise<void>;
+	/** Drop everything a disconnecting client published. */
+	removeClient(clientId: string): MaybePromise<void>;
+	/** Sweep entries past their TTL. Called on a timer by the handler. */
+	cleanupExpired(): MaybePromise<void>;
+	/** Current entry count, for the capacity gate and `ephemeral_full`. */
+	size(): MaybePromise<number>;
+	destroy(): MaybePromise<void>;
+	/** Hand an event to peer instances. Absent on single-process adapters. */
+	publish?(event: EphemeralBroadcast): MaybePromise<void>;
+	/**
+	* Register the handler's delivery callback for events published by peers.
+	* Called once during wiring. Absent on single-process adapters.
+	*/
+	subscribe?(onEvent: (event: EphemeralBroadcast) => void): MaybePromise<void>;
+}
+/**
+* Minimal Redis client interface — one raw-command entrypoint.
+*
+* Compatible with ioredis (`client.call`) directly. For node-redis, wrap it:
+*
+* ```ts
+* const shim = { call: (cmd, ...args) => client.sendCommand([cmd, ...args.map(String)]) };
+* ```
+*/
+interface RedisLike {
+	call(command: string, ...args: (string | number)[]): Promise<unknown>;
+}
+/**
+* Pub/sub seam — one function, because no two Redis clients agree on the shape
+* of theirs (argument order, `on("message")` vs a per-channel listener). Wire
+* yours in a two-line shim rather than have this module guess:
+*
+* ```ts
+* // ioredis (separate connection — subscribe mode blocks other commands)
+* { subscribe: (ch, onMessage) => {
+*     sub.on("message", (c, m) => { if (c === ch) onMessage(m); });
+*     return sub.subscribe(ch);
+*   } }
+*
+* // Bun
+* { subscribe: (ch, onMessage) => sub.subscribe(ch, (msg) => onMessage(msg)) }
+* ```
+*/
+interface RedisSubscriberLike {
+	subscribe(channel: string, onMessage: (payload: string) => void): Promise<unknown> | unknown;
+}
+interface RedisEphemeralConfig {
+	/** Command connection. */
+	client: RedisLike;
+	/**
+	* Separate connection used for pub/sub. Omit to run shared-state-only —
+	* peers then see each other's presence on join and on sweep, but not live.
+	*/
+	subscriber?: RedisSubscriberLike;
+	/** Key prefix. Default: "reflectdb:eph" */
+	prefix?: string;
+	/** Global entry ceiling across the fleet. Default: 100_000 */
+	maxEntries?: number;
+	/**
+	* Safety-net expiry on state hashes, in seconds. Guards against a crashed
+	* instance leaving entries behind when its clients never disconnect
+	* cleanly. Default: 86400 (24h), matching the handler's TTL clamp.
+	*/
+	hashTtlSeconds?: number;
+}
+declare function createRedisEphemeral(config: RedisEphemeralConfig): EphemeralAdapter & {
+	ready(): Promise<void>;
+};
+export { RedisEphemeralConfig, RedisLike, RedisSubscriberLike, createRedisEphemeral };