@terreno/api 0.13.2 → 0.14.0

package/dist/realtime/changeStreamWatcher.d.ts

@@ -0,0 +1,73 @@
+import mongoose from "mongoose";
+import type { Server } from "socket.io";
+type ChangeStreamDocument = mongoose.mongo.ChangeStreamDocument;
+import type { User } from "../auth";
+import { type RealtimeRegistryEntry } from "./registry";
+import type { ChangeStreamConfig, RealtimeEvent } from "./types";
+/**
+ * Map MongoDB change stream operation types to our method names.
+ *
+ * Soft deletes (an `update` that sets `deleted: true`) are reclassified as
+ * `"delete"` only when the model has `"delete"` enabled in its realtime
+ * methods. Otherwise they fall back to `"update"` so models that subscribe
+ * to updates (but not deletes) still see the change — without this fallback,
+ * a model configured with `methods: ["create", "update"]` would silently
+ * drop soft-delete events.
+ *
+ * Exported for testing.
+ */
+export declare const mapOperationType: (operationType: string, change: ChangeStreamDocument, enabledMethods?: ReadonlyArray<"create" | "update" | "delete">) => "create" | "update" | "delete" | null;
+/**
+ * Determine which Socket.io rooms to emit to based on the room strategy.
+ * Exported for testing.
+ */
+export declare const resolveRooms: (entry: RealtimeRegistryEntry, doc: any, method: string) => string[];
+/**
+ * Ensure serialized documents include `id` to match REST API responses.
+ * Change stream fullDocument payloads are raw BSON objects with `_id` only.
+ */
+export declare const ensureApiId: (data: unknown) => unknown;
+/**
+ * Serialize a document for emission.
+ *
+ * Precedence:
+ *   1. `realtimeResponseHandler` if provided (full control over what's emitted).
+ *   2. modelRouter `responseHandler` if provided — invoked with a synthetic request
+ *      so the same stripping logic used for REST responses (e.g. removing `hash`/`salt`)
+ *      applies to realtime events. This prevents accidental leaks when an app only
+ *      configures sanitization in the REST `responseHandler`.
+ *   3. `toJSON()` fallback.
+ *
+ * If a user-supplied handler throws, we re-throw so the caller's outer try/catch
+ * records the failure and the event is dropped. Falling back to `toJSON()` here
+ * would risk leaking unsanitized fields (e.g. `hash`/`salt`) that the handler
+ * was supposed to strip.
+ */
+export declare const serializeDoc: (entry: RealtimeRegistryEntry, doc: any, method: "create" | "update" | "delete", user?: User) => Promise<any>;
+export declare const emitToAuthorizedRoom: (io: Server, room: string, event: RealtimeEvent, entry: RealtimeRegistryEntry, fullDocument: any, logDebug: (msg: string) => void) => Promise<void>;
+/**
+ * Emit a sync event to document-specific and query rooms.
+ *
+ * Document rooms: `document:{collection}:{docId}` — clients subscribed to a single document.
+ * Query rooms: `query:{queryId}` — clients subscribed to a query filter. The change stream
+ * watcher evaluates whether the document matches each active query for the collection.
+ *
+ * For deletes, we are careful not to leak cross-user activity:
+ *   - Soft deletes (fullDocument present) are matched against each query like updates so
+ *     query subscribers only see deletes for docs that matched their filter.
+ *   - Hard deletes (fullDocument absent) on owner-strategy collections are NOT forwarded
+ *     to query rooms — subscribers will reconcile on their next fetch. Other strategies
+ *     forward the delete because the model/broadcast rooms are not user-scoped.
+ *
+ * Exported for testing.
+ */
+export declare const emitToDocumentAndQueryRooms: (io: Server, collection: string, event: RealtimeEvent, fullDocument: any, logDebug: (msg: string) => void, entry?: RealtimeRegistryEntry) => Promise<void>;
+/**
+ * Start watching MongoDB change streams and emitting real-time events.
+ */
+export declare const startChangeStreamWatcher: (io: Server, config?: ChangeStreamConfig, debug?: boolean) => void;
+/**
+ * Stop the change stream watcher.
+ */
+export declare const stopChangeStreamWatcher: () => Promise<void>;
+export {};