reflectdb 0.1.2 → 0.2.0

package/dist/cjs/server/storage/object/index.d.cts

@@ -0,0 +1,578 @@
+interface ExistingRow {
+	row: Record<string, unknown> | null;
+	rowHlc: string | null;
+	colClocks: Record<string, string>;
+}
+interface OpLogEntry {
+	table: string;
+	op: string;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	colClocks: Record<string, string>;
+}
+interface StorageAdapter {
+	getRow(table: string, rowId: string): Promise<ExistingRow>;
+	/**
+	* Read many rows of one table in a single round trip, keyed by rowId.
+	* Missing rows are simply absent from the result.
+	*
+	* A 100-op batch otherwise issues 100 sequential `getRow` calls before it
+	* can even start writing. Optional — the handler falls back to `getRow`.
+	*/
+	getRowsByIds?(table: string, rowIds: string[]): Promise<Record<string, ExistingRow>>;
+	putRow(table: string, rowId: string, row: Record<string, unknown> | null, colClocks: Record<string, string>, hlc: string): Promise<void>;
+	getRows(table: string, filter?: Record<string, unknown>): Promise<{
+		rows: Record<string, unknown>[];
+		colClocks: Record<string, Record<string, string>>;
+	}>;
+	appendOp(entry: OpLogEntry): Promise<void>;
+	/**
+	* Atomic write: putRow + appendOp in a single transaction.
+	* Prevents divergence between the row store and op log on crash.
+	* Optional — handler falls back to sequential putRow+appendOp if absent.
+	*/
+	applyOp?(table: string, rowId: string, row: Record<string, unknown> | null, colClocks: Record<string, string>, hlc: string, opType: string, payload: Record<string, unknown> | null): Promise<void>;
+	getOpsSince(since: string, tables: string[]): Promise<OpLogEntry[]>;
+	/**
+	* Distinct table names with ops newer than `since`, restricted to `tables`.
+	*
+	* Resume only needs the set of changed tables — it re-executes each affected
+	* query and sends a snapshot rather than replaying ops. Without this,
+	* resume loads every op row since the watermark into memory just to collect
+	* distinct names, which is unbounded for a long-offline client.
+	*
+	* Optional — the handler falls back to `getOpsSince` when absent.
+	*/
+	getChangedTablesSince?(since: string, tables: string[]): Promise<string[]>;
+	/**
+	* Highest op-log HLC across `tables`, or null when the log is empty.
+	*
+	* HA polling uses it as a cheap "did anything change at all" probe: without
+	* it, every poll tick re-executes every query for every subscriber group
+	* even when there were zero writes. Optional.
+	*/
+	getOplogHead?(tables: string[]): Promise<string | null>;
+	deleteOpsBefore(hlc: string): Promise<number>;
+	/**
+	* Atomic reserve-or-detect-replay: returns true if this opId was fresh
+	* (inserted), false if it was already reserved. MUST be implemented as a
+	* single atomic operation (e.g. INSERT ... ON CONFLICT DO NOTHING) — a
+	* non-atomic check-then-write race-conditions in HA setups where multiple
+	* instances share storage and double-applies the op.
+	*/
+	reserveOp(opId: string): Promise<boolean>;
+	/**
+	* Batch form of `reserveOp`: returns the subset of `opIds` that were fresh.
+	* Must be atomic per id, like `reserveOp`. Optional — the handler falls
+	* back to one `reserveOp` per op.
+	*/
+	reserveOps?(opIds: string[]): Promise<string[]>;
+	getMeta(key: string): Promise<string | null>;
+	setMeta(key: string, value: string): Promise<void>;
+	/**
+	* Acquire a cross-instance lock (e.g. Postgres pg_advisory_lock).
+	* Returns true if acquired, false if another instance holds it.
+	* Optional — handler runs best-effort if absent.
+	*/
+	tryLock?(key: string): Promise<boolean>;
+	unlock?(key: string): Promise<void>;
+}
+/**
+* Contracts for the object-storage backend.
+*
+* Design: docs/object-storage.md. The short version — the object store is the
+* only durable store, but it is never on the read path. State is authoritative
+* in memory; writes append to a buffer that group-commits one object per batch;
+* a CAS'd manifest is the linearization point.
+*
+* Nothing in this directory may statically import a `node:` builtin. `bunup`
+* builds `src/` with `target: "browser"`, and a `node:` import anywhere here is
+* hoisted into a shared chunk that every entry point — including
+* `reflectdb/core` and `reflectdb/react` — side-effect-imports, which breaks
+* consumer bundles outright. Use `src/server/node-require.ts` when a builtin is
+* genuinely needed (the filesystem driver), and WebCrypto rather than
+* `node:crypto` everywhere else.
+*/
+/** A stored object plus the etag needed to CAS against it. */
+interface ObjectRecord {
+	body: Uint8Array;
+	etag: string;
+}
+interface ObjectPutOptions {
+	/**
+	* Overwrite only if the current etag matches. A mismatch throws
+	* `PreconditionFailedError`. This is the CAS primitive the manifest and
+	* lease are built on.
+	*/
+	ifMatch?: string;
+	/**
+	* Write only if the key is absent. Only `"*"` is meaningful, matching the S3
+	* header. Drivers reporting `caps.casWildcard === false` (MinIO) reject this
+	* — see `ObjectDriverCapabilities.casWildcard`.
+	*/
+	ifNoneMatch?: "*";
+}
+interface ObjectListEntry {
+	key: string;
+	size: number;
+}
+interface ObjectDriverCapabilities {
+	/**
+	* Whether `ifNoneMatch: "*"` (create-if-absent) is supported.
+	*
+	* MinIO shipped conditional writes before AWS but requires an exact etag and
+	* rejects the wildcard, so create-if-absent is unavailable there. Stores on a
+	* driver reporting `false` require a one-time `init()` that unconditionally
+	* seeds `_lease` and `_manifest`; every later write is a plain `ifMatch`,
+	* which MinIO handles fine.
+	*
+	* `init()` is a deploy step. Racing it from N servers on a non-wildcard
+	* driver is unsafe.
+	*/
+	casWildcard: boolean;
+}
+/**
+* The whole provider surface. Four methods — everything above this interface is
+* provider-agnostic and never learns which store it is talking to.
+*
+* Keys are store-relative; the driver owns bucket and prefix.
+*/
+interface ObjectDriver {
+	/** Returns `null` when the key is absent — absence is not an error. */
+	get(key: string): Promise<ObjectRecord | null>;
+	/**
+	* Writes `body` and returns the new etag.
+	*
+	* @throws {PreconditionFailedError} when `ifMatch` / `ifNoneMatch` fails.
+	*/
+	put(key: string, body: Uint8Array, opts?: ObjectPutOptions): Promise<string>;
+	/** Lists keys under `prefix`. Must page internally and return the full set. */
+	list(prefix: string): Promise<ObjectListEntry[]>;
+	/** Deletes keys. Absent keys are not an error. */
+	delete(keys: string[]): Promise<void>;
+	readonly caps: ObjectDriverCapabilities;
+	/** Releases any pooled resources. Optional. */
+	close?(): Promise<void> | void;
+}
+/**
+* A conditional write lost. Callers treat this as "someone else moved first",
+* never as a transport failure — retrying without re-reading is always wrong.
+*/
+declare class PreconditionFailedError extends Error {
+	readonly key: string;
+	constructor(key: string, message?: string);
+}
+/** The write buffer exceeded `batch.maxBufferBytes` under `onBackpressure: "reject"`. */
+declare class BackpressureError extends Error {
+	readonly bufferedBytes: number;
+	readonly limitBytes: number;
+	constructor(bufferedBytes: number, limitBytes: number);
+}
+/** In-memory state exceeded the configured budget under `memory.onExceeded: "reject"`. */
+declare class MemoryLimitExceededError extends Error {
+	readonly usedBytes: number;
+	readonly limitBytes: number;
+	constructor(usedBytes: number, limitBytes: number);
+}
+/**
+* The manifest names an object the store does not have.
+*
+* Always a hard failure: the manifest is the room's index, so a key it lists
+* and the store cannot produce means data the room was told was durable is
+* gone. Booting past it would present the loss as an empty room and then
+* overwrite whatever survived. Typed rather than a bare `Error` because a
+* caller whose data is disposable — a demo board, a scratch room — may
+* legitimately choose to clear the prefix and start over, and that decision
+* must never be made by matching on a message string.
+*/
+declare class IncompleteStateError extends Error {
+	readonly roomId: string;
+	readonly key: string;
+	constructor(roomId: string, key: string, detail: string);
+}
+/**
+* This instance is not the writer for the room: another holds an unexpired
+* lease, or a renewal failed and the writer self-fenced.
+*/
+declare class NotWriterError extends Error {
+	readonly roomId: string;
+	constructor(roomId: string, detail?: string);
+}
+/**
+* The lease object. CAS'd on every acquire and renew; `epoch` is the fencing
+* token stamped into every WAL segment name and manifest write.
+*/
+interface LeaseRecord {
+	owner: string;
+	epoch: number;
+	/** Wall-clock ms. Coarse by design — the manifest CAS is the real guard. */
+	expiresAt: number;
+}
+interface WalSegmentRef {
+	key: string;
+	epoch: number;
+	seq: number;
+	bytes: number;
+	/** Highest HLC in the segment; lets replay skip segments below a snapshot. */
+	maxHlc: string;
+}
+/**
+* The single CAS'd linearization point. Every field a booting reader needs to
+* reconstruct state is here, so boot is one GET plus the objects it names.
+*/
+interface ManifestRecord {
+	version: 1;
+	epoch: number;
+	/**
+	* Increments on every commit. Exists solely to make the manifest bytes differ
+	* on every write, which closes an ABA hole in etag-based CAS.
+	*
+	* S3 derives an etag from object content, so writing identical bytes leaves
+	* the etag unchanged. Without this counter a writer could read etag E, have
+	* another writer commit a manifest that happens to serialize identically, and
+	* still win its `ifMatch: E` — a lost update that no 412 reports. In practice
+	* `oplogHead` and `walSegs` almost always differ, but "almost always" is not
+	* a property to rest a linearization point on. A monotonic counter makes it
+	* impossible by construction rather than by luck.
+	*/
+	commitSeq: number;
+	/**
+	* `writerId` of whoever wrote this version.
+	*
+	* Together with `commitSeq` it identifies a commit uniquely, which is what
+	* lets a writer that took a 412 tell "my own write, acknowledged late" from
+	* "someone else got there first". `epoch` cannot do that job under
+	* `concurrency: "optimistic"`: there is no lease, so every instance shares the
+	* manifest's epoch and two of them will attempt the same `commitSeq` — making
+	* an epoch-based check adopt a rival's commit as your own and silently drop
+	* the segment you just wrote.
+	*/
+	lastWriter: string;
+	/** Key of the newest snapshot, or `null` before the first compaction. */
+	snapshotKey: string | null;
+	/** Highest HLC covered by the snapshot; segments at or below it are replaceable. */
+	snapshotHlc: string | null;
+	/** Segments to replay after the snapshot, in commit order. */
+	walSegs: WalSegmentRef[];
+	/** Highest HLC committed anywhere in the log. */
+	oplogHead: string | null;
+	/** `getMeta` / `setMeta` storage. Small by contract. */
+	meta: Record<string, string>;
+	/** Segments superseded by compaction, deleted once `gcGraceMs` has elapsed. */
+	pendingGc: {
+		key: string;
+		deletableAt: number;
+	}[];
+}
+/** A materialized row, mirroring `ExistingRow` plus its id. */
+interface SnapshotRow {
+	table: string;
+	rowId: string;
+	row: Record<string, unknown>;
+	colClocks: Record<string, string>;
+	hlc: string;
+}
+interface SnapshotRecord {
+	version: 1;
+	hlc: string | null;
+	rows: SnapshotRow[];
+	/** Op ids still inside the replay-protection window, with their timestamps. */
+	reservedOps: [opId: string, atMs: number][];
+}
+type StoreProvider = "aws" | "r2" | "tigris" | "minio" | "gcs";
+interface StoreCredentials {
+	keyId: string;
+	secret: string;
+	sessionToken?: string;
+}
+interface StoreConfig {
+	/** Fills `endpoint` and `urlStyle` when they are not given explicitly. */
+	provider?: StoreProvider;
+	bucket: string;
+	prefix?: string;
+	endpoint?: string;
+	region?: string;
+	urlStyle?: "vhost" | "path";
+	credentials: StoreCredentials;
+	/** Cloudflare R2 account id; only used to derive the endpoint for `provider: "r2"`. */
+	accountId?: string;
+}
+type DurabilityMode = "durable" | "buffered";
+type BackpressurePolicy = "reject" | "degrade";
+type MemoryPolicy = "reject" | "evict" | "spill";
+type LeaseMode = "always" | "on-write";
+/**
+* How this process expects to share the room with other processes.
+*
+* `"single-writer"` (default) is the design in docs/object-storage.md: one
+* writer per room, elected by a lease, holding authoritative state in memory.
+* Reads never touch the network and a write is one segment PUT plus one CAS.
+* It requires the deployment to route a room to one instance.
+*
+* `"optimistic"` drops the lease for platforms that cannot make that promise —
+* Vercel functions, or anything where any request may land on any instance. It
+* rests on the same guarantee the single-writer mode does: the manifest CAS is
+* what keeps the data correct, and the lease was only ever an optimization to
+* stop two servers doing redundant work. Concurrent writers race on the CAS,
+* the loser re-reads and retries, and nobody is fenced.
+*
+* What it costs: in-memory state is no longer authoritative, because another
+* instance may have committed since this one last looked. Call `refresh()`
+* before serving a read that must be current — one conditional GET of the
+* manifest, which is why the poll loop in a serverless deployment is cheap.
+*/
+type ConcurrencyMode = "single-writer" | "optimistic";
+type StorageHealth = "healthy" | "degraded" | "unavailable";
+interface BatchConfig {
+	maxBytes?: number;
+	/** Coalesces ops arriving in the same event-loop tick. Not a flush interval. */
+	minLingerMs?: number;
+	maxBufferBytes?: number;
+	onBackpressure?: BackpressurePolicy;
+}
+interface CompactionConfig2 {
+	afterSegments?: number;
+	afterBytes?: number;
+	/** Delay before deleting superseded segments, so in-flight readers do not 404. */
+	gcGraceMs?: number;
+}
+interface LeaseConfig {
+	ttlMs?: number;
+	renewMs?: number;
+	mode?: LeaseMode;
+}
+interface MemoryConfig {
+	maxTotalBytes?: number;
+	maxRoomBytes?: number;
+	onExceeded?: MemoryPolicy;
+	idleEvictMs?: number;
+}
+interface ObjectStorageConfig {
+	/** A ready driver, or a `StoreConfig` from which the S3 driver is built. */
+	driver?: ObjectDriver;
+	store?: StoreConfig;
+	roomId: string;
+	/**
+	* Identifies this writer in the lease. Defaults to a random id; set it
+	* explicitly to make lease ownership legible in logs.
+	*/
+	writerId?: string;
+	/**
+	* `"durable"` (default) acks after the manifest CAS — correct with no
+	* protocol change. `"buffered"` acks on memory apply and is LOSSY until the
+	* durable-watermark protocol lands: a crash before flush drops ops the client
+	* has already retired. See docs/object-storage.md.
+	*/
+	durability?: DurabilityMode;
+	retentionMs?: number;
+	/**
+	* Defaults to `"single-writer"`. Set `"optimistic"` on a platform that cannot
+	* route a room to one instance — see `ConcurrencyMode`.
+	*/
+	concurrency?: ConcurrencyMode;
+	batch?: BatchConfig;
+	compaction?: CompactionConfig2;
+	lease?: LeaseConfig;
+	memory?: MemoryConfig;
+	shutdownFlushMs?: number;
+	/** Fired after each batch reaches durability. Phase 2 broadcasts this to clients. */
+	onDurable?: (hlc: string) => void;
+	onHealthChange?: (health: StorageHealth) => void;
+}
+/** Every knob resolved. Internals read this, never the optional-laden input. */
+interface ResolvedObjectStorageConfig {
+	roomId: string;
+	writerId: string;
+	durability: DurabilityMode;
+	retentionMs: number;
+	concurrency: ConcurrencyMode;
+	batch: Required<BatchConfig>;
+	compaction: Required<CompactionConfig2>;
+	lease: Required<LeaseConfig>;
+	memory: Required<MemoryConfig>;
+	shutdownFlushMs: number;
+}
+/** Everything `ResolvedObjectStorageConfig` carries except the per-room identity. */
+type ObjectStorageDefaults = Omit<ResolvedObjectStorageConfig, "roomId" | "writerId">;
+declare const OBJECT_STORAGE_DEFAULTS: ObjectStorageDefaults;
+/**
+* Every wall-clock read and every timer in this directory goes through a
+* `Clock`. Lease expiry, op-id retention and flush backoff are all time-driven,
+* and a test that has to `await delay(300_000)` to prove a lease lapsed is a
+* test nobody runs. Injecting the clock keeps those paths deterministic.
+*/
+interface Clock {
+	now(): number;
+	delay(ms: number): Promise<void>;
+	/** Schedules `fn` and returns a cancel function. */
+	setTimer(fn: () => void, ms: number): () => void;
+}
+/**
+* Process-wide byte budget shared by every room.
+*
+* The budget is global rather than per-room because a per-room cap lets one
+* whale room starve five hundred small ones: each stays under its own limit
+* while the process as a whole runs out of heap. `maxRoomBytes` still exists as
+* a blast-radius guard, but `maxTotalBytes` is the one that maps to the machine.
+*/
+declare class ProcessMemoryBudget {
+	private limitBytes;
+	private usedBytes;
+	get used(): number;
+	get limit(): number;
+	/**
+	* Narrows the process budget. The tightest configuration wins: two rooms
+	* built with different `maxTotalBytes` values describe the same heap, and
+	* honoring the looser one would silently discard the stricter operator's
+	* intent.
+	*/
+	constrain(limit: number): void;
+	add(delta: number): void;
+}
+/** The operations the fault hook can intercept. One hook call per driver call. */
+type MemoryDriverOp = "get" | "put" | "list" | "delete";
+interface MemoryDriverFaultContext {
+	op: MemoryDriverOp;
+	/**
+	* The key the call names. For `list` this is the prefix; for `delete`, which
+	* is a single request against the store (S3 `DeleteObjects`), it is every key
+	* joined with `","` — a fault there aborts the whole batch, as a real 500
+	* would.
+	*/
+	key: string;
+	/**
+	* 1-based ordinal across *all* operations on this driver, so a test can pin a
+	* fault to a point in a sequence ("the 4th thing this room does"). For "the
+	* 2nd put" specifically, read `stats.put` inside the hook: counters are
+	* incremented before the hook runs, so during the 2nd put `stats.put === 2`.
+	*/
+	call: number;
+}
+/**
+* What to inject. `undefined` (or no hook) means "proceed normally".
+*
+* When both fields are given the delay happens *first*, then the throw — that is
+* the shape of a real store failure worth testing, a request that hangs and then
+* fails, rather than one that fails instantly.
+*/
+type MemoryDriverFault = {
+	throw: Error;
+} | {
+	delayMs: number;
+} | {
+	throw: Error;
+	delayMs: number;
+};
+interface MemoryDriverOptions {
+	/**
+	* Reported as `caps.casWildcard`. Configurable so the MinIO path — a store
+	* that supports `If-Match` but rejects `If-None-Match: *` — is testable
+	* without a MinIO. Defaults to `true`.
+	*/
+	casWildcard?: boolean;
+	faults?: {
+		/**
+		* Called before each operation. Return a fault to inject it, or
+		* `undefined` / nothing to let the operation proceed.
+		*/
+		before?(ctx: MemoryDriverFaultContext): MemoryDriverFault | void;
+	};
+}
+/** Test affordances layered on top of the driver contract. */
+interface MemoryDriverHandle {
+	/**
+	* Call counts per operation, for asserting the *cost* of a design decision
+	* rather than its behavior. Counts attempts: a call a fault aborted is still
+	* a call the room decided to make, which is the thing under test.
+	*/
+	stats: {
+		get: number;
+		put: number;
+		list: number;
+		delete: number;
+	};
+	/**
+	* Snapshot of the whole store, keys in ascending order, bodies copied. For
+	* asserting what actually landed without going through `list` + `get` (which
+	* would itself move `stats` and fire fault hooks).
+	*/
+	dump(): Map<string, Uint8Array>;
+}
+declare function createMemoryDriver(options?: MemoryDriverOptions): ObjectDriver & MemoryDriverHandle;
+declare function createFilesystemDriver(rootDir: string): ObjectDriver & {
+	close?(): void;
+};
+interface S3DriverConfig extends StoreConfig {
+	/**
+	* TEST-ONLY transport override. Lets a test stub S3 without a network and
+	* assert on the exact signed request. Not part of the public configuration
+	* surface; production always uses global `fetch`.
+	*
+	* @internal
+	*/
+	fetch?: typeof fetch;
+	/**
+	* TEST-ONLY clock, threaded into `signRequest` so a test can pin `x-amz-date`
+	* and assert a byte-exact `Authorization` header.
+	*
+	* @internal
+	*/
+	now?: () => Date;
+	/**
+	* TEST-ONLY sleep, so retry backoff does not burn wall-clock in the suite.
+	*
+	* @internal
+	*/
+	sleep?: (ms: number) => Promise<void>;
+}
+declare function createS3Driver(config: S3DriverConfig): ObjectDriver;
+/**
+* Room key namespace. The driver owns bucket and prefix; the room path is the
+* adapter's, because `roomId` is adapter configuration.
+*
+* `encodeURIComponent` is not cosmetic: a room id containing `/` or `..` would
+* otherwise write into another room's namespace, and room ids routinely come
+* from user-controlled URL segments via `resolveRoomKey`.
+*/
+declare function roomPrefix(roomId: string): string;
+/** The adapter plus the lifecycle and observability surface the design adds. */
+interface ObjectStorage extends StorageAdapter {
+	/**
+	* Boots the room: manifest, snapshot, WAL replay. Idempotent, and implied by
+	* the first call to any other method — call it explicitly to surface boot
+	* failures at startup rather than on the first query.
+	*/
+	init(): Promise<void>;
+	/** Drains the write buffer and resolves once everything buffered is durable. */
+	flush(): Promise<void>;
+	close(): Promise<void>;
+	readonly health: StorageHealth;
+	/** Highest HLC known durable. Phase 2 broadcasts this as the retire watermark. */
+	readonly durableHlc: string | null;
+	onDurable(callback: (hlc: string) => void): void;
+	onHealthChange(callback: (health: StorageHealth) => void): void;
+	/**
+	* Folds in anything another instance has committed since this one last
+	* looked, and reports whether the room actually moved.
+	*
+	* Only meaningful under `concurrency: "optimistic"`, where in-memory state is
+	* NOT authoritative — under `"single-writer"` this instance IS the writer, so
+	* there is nothing to catch up on and this resolves `false` without a request.
+	*
+	* Costs one GET, and does nothing further when the manifest's `commitSeq` has
+	* not moved. That is what makes a serverless poll loop affordable: the steady
+	* state is a single small conditional read, and queries re-run only when this
+	* returns true.
+	*/
+	refresh(): Promise<boolean>;
+}
+interface ObjectStorageOptions {
+	/** Injected for deterministic tests; defaults to wall-clock time and timers. */
+	clock?: Clock;
+	/** Process-wide memory budget. Tests pass their own so suites do not share one. */
+	budget?: ProcessMemoryBudget;
+}
+declare function resolveObjectStorageConfig(config: ObjectStorageConfig): ResolvedObjectStorageConfig;
+declare function createObjectStorage(config: ObjectStorageConfig, options?: ObjectStorageOptions): ObjectStorage;
+export { BackpressureError, BackpressurePolicy, BatchConfig, CompactionConfig2 as CompactionConfig, DurabilityMode, IncompleteStateError, LeaseConfig, LeaseMode, LeaseRecord, ManifestRecord, MemoryConfig, MemoryLimitExceededError, MemoryPolicy, NotWriterError, OBJECT_STORAGE_DEFAULTS, ObjectDriver, ObjectDriverCapabilities, ObjectListEntry, ObjectPutOptions, ObjectRecord, ObjectStorage, ObjectStorageConfig, ObjectStorageOptions, PreconditionFailedError, ResolvedObjectStorageConfig, SnapshotRecord, SnapshotRow, StorageHealth, StoreConfig, StoreCredentials, StoreProvider, WalSegmentRef, createFilesystemDriver, createMemoryDriver, createObjectStorage, createS3Driver, resolveObjectStorageConfig, roomPrefix };

package/dist/cjs/svelte/index.cjs

@@ -1,4 +1,3 @@
-var import_node_module = require("node:module");
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/cjs/transport/bun-ws.cjs

@@ -1,4 +1,3 @@
-var import_node_module = require("node:module");
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/cjs/transport/polling.cjs

@@ -1,4 +1,3 @@
-var import_node_module = require("node:module");
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/cjs/transport/sse.cjs

@@ -1,4 +1,3 @@
-var import_node_module = require("node:module");
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -112,11 +111,16 @@ __export(exports_sse, {
   createSseServerTransport: () => createSseServerTransport
 });
 module.exports = __toCommonJS(exports_sse);
+var COLLECT_STABLE_TICKS = 3;
+var MAX_COLLECT_TICKS = 60;
 function createSseServerTransport(cfg = {}) {
   const controllers = new Map;
   const buffers = new Map;
   const counters = new Map;
   const replayBufferSize = cfg.replayBufferSize ?? 256;
+  const serverless = cfg.serverless ?? false;
+  const collecting = new Map;
+  const connected = new Set;
   const maxMessageBytes = cfg.maxMessageBytes ?? 1e6;
   let messageHandler = null;
   let connectHandler = null;
@@ -164,7 +168,10 @@ data: ${data}
           }
         }
       }
-      connectHandler?.(clientId, new Request("https://sse-connect"));
+      if (!connected.has(clientId)) {
+        connected.add(clientId);
+        connectHandler?.(clientId, new Request("https://sse-connect"));
+      }
     },
     handleMessage(clientId, message) {
       let byteLen;
@@ -182,6 +189,7 @@ data: ${data}
     },
     handleDisconnect(clientId) {
       controllers.delete(clientId);
+      connected.delete(clientId);
       disconnectHandler?.(clientId);
     },
     createEventStream(clientId, lastEventId) {
@@ -195,6 +203,11 @@ data: ${data}
       });
     },
     async send(clientId, message) {
+      const sink = collecting.get(clientId);
+      if (sink) {
+        sink.push(message);
+        return;
+      }
       const id = nextId(clientId);
       const encoded = encode(id, message);
       const controller = controllers.get(clientId);
@@ -216,6 +229,31 @@ data: ${data}
         throw new TransportSendError(clientId, `sse replay buffer overflow (size ${replayBufferSize}); undelivered frames dropped`);
       }
     },
+    async collectReplies(clientId, message, settle) {
+      if (!serverless) {
+        this.handleMessage(clientId, message);
+        return [];
+      }
+      if (!connected.has(clientId)) {
+        connected.add(clientId);
+        connectHandler?.(clientId, new Request("https://sse-connect"));
+      }
+      const sink = [];
+      collecting.set(clientId, sink);
+      try {
+        this.handleMessage(clientId, message);
+        await (settle?.() ?? Promise.resolve());
+        let stable = 0;
+        for (let i = 0;i < MAX_COLLECT_TICKS && stable < COLLECT_STABLE_TICKS; i++) {
+          const before = sink.length;
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          stable = sink.length === before ? stable + 1 : 0;
+        }
+      } finally {
+        collecting.delete(clientId);
+      }
+      return sink;
+    },
     async broadcast(_roomId, message, exclude) {
       for (const [clientId, controller] of controllers) {
         if (clientId === exclude)
@@ -281,6 +319,18 @@ function createSseClientTransport(config) {
       if (!res.ok) {
         throw new Error(`SSE send failed: ${res.status} ${res.statusText}`);
       }
+      if (!config.serverless)
+        return;
+      let replies;
+      try {
+        const body = await res.json();
+        replies = Array.isArray(body) ? body : body.messages ?? [];
+      } catch {
+        console.warn("[reflectdb] SSE: serverless mode is on but the POST returned no JSON replies. " + "Set `serverless: true` on createSseServerTransport and return " + "`collectReplies(...)` from the message endpoint.");
+        return;
+      }
+      for (const reply of replies)
+        handler?.(reply);
     },
     subscribe(h) {
       handler = h;