@proseql/core 0.1.0

package/dist/reactive/change-event.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Factory functions for creating ChangeEvent objects.
+ *
+ * These functions provide a convenient and type-safe way to create change events
+ * that are published by CRUD operations and file watchers to notify reactive subscriptions.
+ */
+import type { ChangeEvent } from "../types/reactive-types.js";
+/**
+ * Creates a ChangeEvent for a collection mutation.
+ *
+ * @param collection - The name of the collection that was modified
+ * @param operation - The type of mutation: "create", "update", "delete", or "reload"
+ * @returns A ChangeEvent object
+ *
+ * @example
+ * ```ts
+ * // After creating an entity
+ * const event = createChangeEvent("books", "create")
+ * yield* PubSub.publish(pubsub, event)
+ *
+ * // After updating an entity
+ * const event = createChangeEvent("books", "update")
+ * yield* PubSub.publish(pubsub, event)
+ * ```
+ */
+export declare const createChangeEvent: (collection: string, operation: ChangeEvent["operation"]) => ChangeEvent;
+/**
+ * Creates a ChangeEvent for a file watcher reload.
+ *
+ * This is a convenience function for the common case of creating
+ * a reload event after data is reloaded from disk.
+ *
+ * @param collection - The name of the collection that was reloaded
+ * @returns A ChangeEvent with operation: "reload"
+ *
+ * @example
+ * ```ts
+ * // After reloading data from disk
+ * const event = reloadEvent("books")
+ * yield* PubSub.publish(pubsub, event)
+ * ```
+ */
+export declare const reloadEvent: (collection: string) => ChangeEvent;
+//# sourceMappingURL=change-event.d.ts.map

package/dist/reactive/change-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-event.d.ts","sourceRoot":"","sources":["../../src/reactive/change-event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,YAAY,MAAM,EAClB,WAAW,WAAW,CAAC,WAAW,CAAC,KACjC,WAGD,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,MAAM,KAAG,WAG/C,CAAC"}

package/dist/reactive/change-event.js

@@ -0,0 +1,49 @@
+/**
+ * Factory functions for creating ChangeEvent objects.
+ *
+ * These functions provide a convenient and type-safe way to create change events
+ * that are published by CRUD operations and file watchers to notify reactive subscriptions.
+ */
+/**
+ * Creates a ChangeEvent for a collection mutation.
+ *
+ * @param collection - The name of the collection that was modified
+ * @param operation - The type of mutation: "create", "update", "delete", or "reload"
+ * @returns A ChangeEvent object
+ *
+ * @example
+ * ```ts
+ * // After creating an entity
+ * const event = createChangeEvent("books", "create")
+ * yield* PubSub.publish(pubsub, event)
+ *
+ * // After updating an entity
+ * const event = createChangeEvent("books", "update")
+ * yield* PubSub.publish(pubsub, event)
+ * ```
+ */
+export const createChangeEvent = (collection, operation) => ({
+    collection,
+    operation,
+});
+/**
+ * Creates a ChangeEvent for a file watcher reload.
+ *
+ * This is a convenience function for the common case of creating
+ * a reload event after data is reloaded from disk.
+ *
+ * @param collection - The name of the collection that was reloaded
+ * @returns A ChangeEvent with operation: "reload"
+ *
+ * @example
+ * ```ts
+ * // After reloading data from disk
+ * const event = reloadEvent("books")
+ * yield* PubSub.publish(pubsub, event)
+ * ```
+ */
+export const reloadEvent = (collection) => ({
+    collection,
+    operation: "reload",
+});
+//# sourceMappingURL=change-event.js.map

package/dist/reactive/change-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-event.js","sourceRoot":"","sources":["../../src/reactive/change-event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAChC,UAAkB,EAClB,SAAmC,EACrB,EAAE,CAAC,CAAC;IAClB,UAAU;IACV,SAAS;CACT,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAAkB,EAAe,EAAE,CAAC,CAAC;IAChE,UAAU;IACV,SAAS,EAAE,QAAQ;CACnB,CAAC,CAAC"}

package/dist/reactive/change-pubsub.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PubSub for broadcasting change events to reactive query subscribers.
+ *
+ * Uses Effect's unbounded PubSub to ensure all change events are delivered
+ * to subscribers - dropping events would break subscription correctness.
+ */
+import { type Effect, PubSub } from "effect";
+import type { ChangeEvent } from "../types/reactive-types.js";
+/**
+ * Creates an unbounded PubSub for broadcasting ChangeEvents.
+ *
+ * The PubSub is unbounded because:
+ * - Dropping change events would cause subscriptions to miss mutations
+ * - This could lead to stale result sets being displayed
+ * - Back-pressure is handled by debouncing at the subscription level
+ *
+ * @returns Effect that produces a PubSub for ChangeEvents
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const pubsub = yield* createChangePubSub()
+ *   // Publishers can publish events
+ *   yield* pubsub.publish({ collection: "books", operation: "create" })
+ *   // Subscribers receive events via subscription queues
+ *   const subscription = yield* pubsub.subscribe
+ *   const event = yield* Queue.take(subscription)
+ * })
+ * ```
+ */
+export declare const createChangePubSub: () => Effect.Effect<PubSub.PubSub<ChangeEvent>>;
+//# sourceMappingURL=change-pubsub.d.ts.map

package/dist/reactive/change-pubsub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-pubsub.d.ts","sourceRoot":"","sources":["../../src/reactive/change-pubsub.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,QAAO,MAAM,CAAC,MAAM,CAClD,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CACS,CAAC"}

package/dist/reactive/change-pubsub.js

@@ -0,0 +1,31 @@
+/**
+ * PubSub for broadcasting change events to reactive query subscribers.
+ *
+ * Uses Effect's unbounded PubSub to ensure all change events are delivered
+ * to subscribers - dropping events would break subscription correctness.
+ */
+import { PubSub } from "effect";
+/**
+ * Creates an unbounded PubSub for broadcasting ChangeEvents.
+ *
+ * The PubSub is unbounded because:
+ * - Dropping change events would cause subscriptions to miss mutations
+ * - This could lead to stale result sets being displayed
+ * - Back-pressure is handled by debouncing at the subscription level
+ *
+ * @returns Effect that produces a PubSub for ChangeEvents
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const pubsub = yield* createChangePubSub()
+ *   // Publishers can publish events
+ *   yield* pubsub.publish({ collection: "books", operation: "create" })
+ *   // Subscribers receive events via subscription queues
+ *   const subscription = yield* pubsub.subscribe
+ *   const event = yield* Queue.take(subscription)
+ * })
+ * ```
+ */
+export const createChangePubSub = () => PubSub.unbounded();
+//# sourceMappingURL=change-pubsub.js.map

package/dist/reactive/change-pubsub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-pubsub.js","sourceRoot":"","sources":["../../src/reactive/change-pubsub.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAe,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAEhC,EAAE,CAAC,MAAM,CAAC,SAAS,EAAe,CAAC"}

package/dist/reactive/evaluate-query.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Reusable query evaluation function for reactive queries.
+ *
+ * Reads the current state from a Ref and applies the query pipeline
+ * (filter, sort, select, paginate) to produce a result array.
+ *
+ * Used by watch() for initial emission and re-evaluation on change events.
+ */
+import { Effect, Ref } from "effect";
+/**
+ * Configuration for query evaluation.
+ * Mirrors the subset of QueryConfig that applies to reactive queries.
+ */
+export interface EvaluateQueryConfig {
+    readonly where?: Record<string, unknown>;
+    readonly sort?: Record<string, "asc" | "desc">;
+    readonly select?: Record<string, unknown> | ReadonlyArray<string>;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/**
+ * Entity constraint: must have a readonly string `id` field.
+ */
+type HasId = {
+    readonly id: string;
+};
+/**
+ * Evaluates a query against the current state in the Ref.
+ *
+ * Reads all entities from the Ref, applies the query pipeline (filter, sort,
+ * select, paginate), and returns the result as a ReadonlyArray.
+ *
+ * This is a pure function that:
+ * - Does NOT emit multiple values over time (unlike a Stream)
+ * - Does NOT provide cursor-based pagination (returns complete result snapshot)
+ * - Returns the entire result set as a single ReadonlyArray
+ *
+ * @param ref - The collection Ref containing entities keyed by ID
+ * @param config - Query configuration (where, sort, select, limit, offset)
+ * @returns Effect producing the query result as a ReadonlyArray
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const ref = yield* createCollectionState<Book>([
+ *     { id: "1", title: "Dune", year: 1965, genre: "sci-fi" },
+ *     { id: "2", title: "Neuromancer", year: 1984, genre: "sci-fi" },
+ *     { id: "3", title: "The Hobbit", year: 1937, genre: "fantasy" },
+ *   ])
+ *
+ *   const results = yield* evaluateQuery(ref, {
+ *     where: { genre: "sci-fi" },
+ *     sort: { year: "desc" },
+ *     limit: 1,
+ *   })
+ *   // results: [{ id: "2", title: "Neuromancer", year: 1984, genre: "sci-fi" }]
+ * })
+ * ```
+ */
+export declare const evaluateQuery: <T extends HasId>(ref: Ref.Ref<ReadonlyMap<string, T>>, config?: EvaluateQueryConfig) => Effect.Effect<ReadonlyArray<T>>;
+export {};
+//# sourceMappingURL=evaluate-query.d.ts.map

package/dist/reactive/evaluate-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-query.d.ts","sourceRoot":"","sources":["../../src/reactive/evaluate-query.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAU,MAAM,QAAQ,CAAC;AAM7C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,KAAK,EAC5C,KAAK,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EACpC,SAAQ,mBAAwB,KAC9B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAiB9B,CAAC"}

package/dist/reactive/evaluate-query.js

@@ -0,0 +1,57 @@
+/**
+ * Reusable query evaluation function for reactive queries.
+ *
+ * Reads the current state from a Ref and applies the query pipeline
+ * (filter, sort, select, paginate) to produce a result array.
+ *
+ * Used by watch() for initial emission and re-evaluation on change events.
+ */
+import { Effect, Ref, Stream } from "effect";
+import { applyFilter } from "../operations/query/filter-stream.js";
+import { applyPagination } from "../operations/query/paginate-stream.js";
+import { applySelect } from "../operations/query/select-stream.js";
+import { applySort } from "../operations/query/sort-stream.js";
+/**
+ * Evaluates a query against the current state in the Ref.
+ *
+ * Reads all entities from the Ref, applies the query pipeline (filter, sort,
+ * select, paginate), and returns the result as a ReadonlyArray.
+ *
+ * This is a pure function that:
+ * - Does NOT emit multiple values over time (unlike a Stream)
+ * - Does NOT provide cursor-based pagination (returns complete result snapshot)
+ * - Returns the entire result set as a single ReadonlyArray
+ *
+ * @param ref - The collection Ref containing entities keyed by ID
+ * @param config - Query configuration (where, sort, select, limit, offset)
+ * @returns Effect producing the query result as a ReadonlyArray
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const ref = yield* createCollectionState<Book>([
+ *     { id: "1", title: "Dune", year: 1965, genre: "sci-fi" },
+ *     { id: "2", title: "Neuromancer", year: 1984, genre: "sci-fi" },
+ *     { id: "3", title: "The Hobbit", year: 1937, genre: "fantasy" },
+ *   ])
+ *
+ *   const results = yield* evaluateQuery(ref, {
+ *     where: { genre: "sci-fi" },
+ *     sort: { year: "desc" },
+ *     limit: 1,
+ *   })
+ *   // results: [{ id: "2", title: "Neuromancer", year: 1984, genre: "sci-fi" }]
+ * })
+ * ```
+ */
+export const evaluateQuery = (ref, config = {}) => Effect.gen(function* () {
+    // Read current state from Ref
+    const map = yield* Ref.get(ref);
+    const entities = Array.from(map.values());
+    // Build and execute the query pipeline
+    const stream = Stream.fromIterable(entities).pipe(applyFilter(config.where), applySort(config.sort), applyPagination(config.offset, config.limit), applySelect(config.select));
+    // Collect results into an array
+    const chunk = yield* Stream.runCollect(stream);
+    return Array.from(chunk);
+});
+//# sourceMappingURL=evaluate-query.js.map

package/dist/reactive/evaluate-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-query.js","sourceRoot":"","sources":["../../src/reactive/evaluate-query.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAmB/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,GAAoC,EACpC,SAA8B,EAAE,EACE,EAAE,CACpC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IACnB,8BAA8B;IAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1C,uCAAuC;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,IAAI,CAChD,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EACzB,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EACtB,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,EAC5C,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAC1B,CAAC;IAEF,gCAAgC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAqB,CAAC;AAC9C,CAAC,CAAC,CAAC"}

package/dist/reactive/watch-by-id.d.ts

@@ -0,0 +1,53 @@
+/**
+ * watchById() implementation for reactive single-entity queries.
+ *
+ * Thin wrapper over watch() that filters by ID and maps results to T | null.
+ * Emits the entity when it exists, or null when it's deleted or doesn't exist.
+ */
+import { Effect, type PubSub, type Ref, Stream } from "effect";
+import type { ChangeEvent } from "../types/reactive-types.js";
+import { type WatchQueryConfig } from "./watch.js";
+/**
+ * Entity constraint: must have a readonly string `id` field.
+ */
+type HasId = {
+    readonly id: string;
+};
+/**
+ * Creates a reactive watch stream for a single entity by ID.
+ *
+ * This is a thin wrapper over watch() that:
+ * 1. Filters by `where: { id }` to only match the specific entity
+ * 2. Maps the result array to `T | null` (first element or null if empty)
+ *
+ * The stream:
+ * - Emits the entity immediately if it exists, or null if not
+ * - Re-emits when the entity is created, updated, or deleted
+ * - Emits null when the entity is deleted (result array becomes empty)
+ * - Is scoped: auto-cleanup when scope closes or stream is interrupted
+ *
+ * @param pubsub - The PubSub broadcasting ChangeEvents from mutations
+ * @param ref - The collection Ref containing entities keyed by ID
+ * @param collectionName - Name of the collection to watch (for filtering events)
+ * @param id - The entity ID to watch
+ * @param config - Optional additional watch configuration (debounceMs)
+ * @returns Scoped Effect producing a Stream of T | null
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const pubsub = yield* createChangePubSub()
+ *   const ref = yield* createCollectionState<Book>([
+ *     { id: "1", title: "Dune", author: "Frank Herbert" }
+ *   ])
+ *
+ *   const stream = yield* watchById(pubsub, ref, "books", "1")
+ *
+ *   // Emits: { id: "1", title: "Dune", author: "Frank Herbert" }
+ *   // After delete: emits null
+ * }).pipe(Effect.scoped)
+ * ```
+ */
+export declare const watchById: <T extends HasId>(pubsub: PubSub.PubSub<ChangeEvent>, ref: Ref.Ref<ReadonlyMap<string, T>>, collectionName: string, id: string, config?: Pick<WatchQueryConfig, "debounceMs">) => Effect.Effect<Stream.Stream<T | null>, never, import("effect").Scope.Scope>;
+export {};
+//# sourceMappingURL=watch-by-id.d.ts.map

package/dist/reactive/watch-by-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-by-id.d.ts","sourceRoot":"","sources":["../../src/reactive/watch-by-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAS,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,KAAK,EACxC,QAAQ,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAClC,KAAK,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EACpC,gBAAgB,MAAM,EACtB,IAAI,MAAM,EACV,SAAQ,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAM,KAC/C,MAAM,CAAC,MAAM,CACf,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,EACvB,KAAK,EACL,OAAO,QAAQ,EAAE,KAAK,CAAC,KAAK,CAa1B,CAAC"}

package/dist/reactive/watch-by-id.js

@@ -0,0 +1,55 @@
+/**
+ * watchById() implementation for reactive single-entity queries.
+ *
+ * Thin wrapper over watch() that filters by ID and maps results to T | null.
+ * Emits the entity when it exists, or null when it's deleted or doesn't exist.
+ */
+import { Effect, Stream } from "effect";
+import { watch } from "./watch.js";
+/**
+ * Creates a reactive watch stream for a single entity by ID.
+ *
+ * This is a thin wrapper over watch() that:
+ * 1. Filters by `where: { id }` to only match the specific entity
+ * 2. Maps the result array to `T | null` (first element or null if empty)
+ *
+ * The stream:
+ * - Emits the entity immediately if it exists, or null if not
+ * - Re-emits when the entity is created, updated, or deleted
+ * - Emits null when the entity is deleted (result array becomes empty)
+ * - Is scoped: auto-cleanup when scope closes or stream is interrupted
+ *
+ * @param pubsub - The PubSub broadcasting ChangeEvents from mutations
+ * @param ref - The collection Ref containing entities keyed by ID
+ * @param collectionName - Name of the collection to watch (for filtering events)
+ * @param id - The entity ID to watch
+ * @param config - Optional additional watch configuration (debounceMs)
+ * @returns Scoped Effect producing a Stream of T | null
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const pubsub = yield* createChangePubSub()
+ *   const ref = yield* createCollectionState<Book>([
+ *     { id: "1", title: "Dune", author: "Frank Herbert" }
+ *   ])
+ *
+ *   const stream = yield* watchById(pubsub, ref, "books", "1")
+ *
+ *   // Emits: { id: "1", title: "Dune", author: "Frank Herbert" }
+ *   // After delete: emits null
+ * }).pipe(Effect.scoped)
+ * ```
+ */
+export const watchById = (pubsub, ref, collectionName, id, config = {}) => Effect.gen(function* () {
+    // Use watch() with a where clause filtering by ID
+    const watchStream = yield* watch(pubsub, ref, collectionName, {
+        ...config,
+        where: { id },
+    });
+    // Map the result array to T | null
+    // - results[0] when the entity exists
+    // - null when the entity is deleted or doesn't exist
+    return Stream.map(watchStream, (results) => results[0] ?? null);
+});
+//# sourceMappingURL=watch-by-id.js.map

package/dist/reactive/watch-by-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-by-id.js","sourceRoot":"","sources":["../../src/reactive/watch-by-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAyB,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE/D,OAAO,EAAyB,KAAK,EAAE,MAAM,YAAY,CAAC;AAO1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACxB,MAAkC,EAClC,GAAoC,EACpC,cAAsB,EACtB,EAAU,EACV,SAA+C,EAAE,EAKhD,EAAE,CACH,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IACnB,kDAAkD;IAClD,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE;QAC7D,GAAG,MAAM;QACT,KAAK,EAAE,EAAE,EAAE,EAAE;KACb,CAAC,CAAC;IAEH,mCAAmC;IACnC,sCAAsC;IACtC,qDAAqD;IACrD,OAAO,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;AACjE,CAAC,CAAC,CAAC"}

package/dist/reactive/watch.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Core watch() implementation for reactive queries.
+ *
+ * Creates a Stream that emits result sets whenever the underlying collection data changes.
+ * Subscribes to the PubSub for change notifications, filters events by collection name,
+ * re-evaluates the query pipeline on each change, deduplicates identical consecutive results,
+ * and emits the new result set.
+ */
+import { Effect, PubSub, type Ref, Scope, Stream } from "effect";
+import type { ChangeEvent } from "../types/reactive-types.js";
+import { type EvaluateQueryConfig } from "./evaluate-query.js";
+/**
+ * Configuration for the watch query.
+ * Extends EvaluateQueryConfig with debounce options.
+ */
+export interface WatchQueryConfig extends EvaluateQueryConfig {
+    /**
+     * Debounce interval in milliseconds for change event processing.
+     * When multiple mutations occur in rapid succession, they are coalesced
+     * into a single re-evaluation after the debounce interval settles.
+     * Default: 10ms (fast enough for interactive use, long enough to batch bursts).
+     */
+    readonly debounceMs?: number;
+}
+/**
+ * Entity constraint: must have a readonly string `id` field.
+ */
+type HasId = {
+    readonly id: string;
+};
+/**
+ * Creates a reactive watch stream that emits query results whenever the collection changes.
+ *
+ * The stream:
+ * 1. Emits the current result set immediately upon subscription
+ * 2. Subscribes to the PubSub for change notifications (scoped - auto-cleanup)
+ * 3. Filters events to only those matching the specified collection
+ * 4. Debounces change events to coalesce rapid mutations into single re-evaluations
+ * 5. Re-evaluates the query pipeline on each relevant change
+ * 6. Deduplicates consecutive identical result sets to avoid spurious emissions
+ * 7. Emits the new result set as a ReadonlyArray
+ *
+ * Resource management:
+ * - Uses Effect.acquireRelease to manage the PubSub subscription lifecycle
+ * - Subscription is acquired when the watch Effect runs and released when:
+ *   - The enclosing Scope closes, OR
+ *   - The stream is interrupted/completes (via Stream.ensuring)
+ * - This ensures no memory leaks from lingering subscriptions
+ *
+ * @param pubsub - The PubSub broadcasting ChangeEvents from mutations
+ * @param ref - The collection Ref containing entities keyed by ID
+ * @param collectionName - Name of the collection to watch (for filtering events)
+ * @param config - Optional query configuration (where, sort, select, limit, offset, debounceMs)
+ * @returns Scoped Effect producing a Stream of result arrays
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const pubsub = yield* createChangePubSub()
+ *   const ref = yield* createCollectionState<Book>([])
+ *
+ *   const stream = yield* watch(pubsub, ref, "books", {
+ *     where: { genre: "sci-fi" },
+ *     sort: { year: "desc" },
+ *     limit: 10,
+ *     debounceMs: 50, // custom debounce interval
+ *   })
+ *
+ *   // Consume the stream
+ *   yield* Stream.runForEach(stream, (results) =>
+ *     Effect.log(`Got ${results.length} results`)
+ *   )
+ * }).pipe(Effect.scoped)
+ * ```
+ */
+export declare const watch: <T extends HasId>(pubsub: PubSub.PubSub<ChangeEvent>, ref: Ref.Ref<ReadonlyMap<string, T>>, collectionName: string, config?: WatchQueryConfig) => Effect.Effect<Stream.Stream<ReadonlyArray<T>>, never, Scope.Scope>;
+export {};
+//# sourceMappingURL=watch.d.ts.map

package/dist/reactive/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/reactive/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,MAAM,EAGN,MAAM,EACN,KAAK,GAAG,EACR,KAAK,EACL,MAAM,EACN,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,KAAK,mBAAmB,EAAiB,MAAM,qBAAqB,CAAC;AAE9E;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC5D;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAgCrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,KAAK,EACpC,QAAQ,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAClC,KAAK,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EACpC,gBAAgB,MAAM,EACtB,SAAQ,gBAAqB,KAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAmFjE,CAAC"}

package/dist/reactive/watch.js

@@ -0,0 +1,133 @@
+/**
+ * Core watch() implementation for reactive queries.
+ *
+ * Creates a Stream that emits result sets whenever the underlying collection data changes.
+ * Subscribes to the PubSub for change notifications, filters events by collection name,
+ * re-evaluates the query pipeline on each change, deduplicates identical consecutive results,
+ * and emits the new result set.
+ */
+import { Duration, Effect, ExecutionStrategy, Exit, PubSub, Scope, Stream, } from "effect";
+import { evaluateQuery } from "./evaluate-query.js";
+/**
+ * Compares two result arrays for structural equality.
+ *
+ * Uses JSON serialization for deep comparison. This is simple and correct for
+ * comparing arrays of plain objects (which is what query results are).
+ *
+ * @param a - First result array
+ * @param b - Second result array
+ * @returns true if the arrays are structurally equal
+ */
+const resultsAreEqual = (a, b) => {
+    // Fast path: same reference
+    if (a === b)
+        return true;
+    // Fast path: different lengths
+    if (a.length !== b.length)
+        return false;
+    // Compare by serialization for deep structural equality
+    return JSON.stringify(a) === JSON.stringify(b);
+};
+/**
+ * Default debounce interval in milliseconds.
+ * Fast enough for interactive use, long enough to batch typical burst patterns.
+ */
+const DEFAULT_DEBOUNCE_MS = 10;
+/**
+ * Creates a reactive watch stream that emits query results whenever the collection changes.
+ *
+ * The stream:
+ * 1. Emits the current result set immediately upon subscription
+ * 2. Subscribes to the PubSub for change notifications (scoped - auto-cleanup)
+ * 3. Filters events to only those matching the specified collection
+ * 4. Debounces change events to coalesce rapid mutations into single re-evaluations
+ * 5. Re-evaluates the query pipeline on each relevant change
+ * 6. Deduplicates consecutive identical result sets to avoid spurious emissions
+ * 7. Emits the new result set as a ReadonlyArray
+ *
+ * Resource management:
+ * - Uses Effect.acquireRelease to manage the PubSub subscription lifecycle
+ * - Subscription is acquired when the watch Effect runs and released when:
+ *   - The enclosing Scope closes, OR
+ *   - The stream is interrupted/completes (via Stream.ensuring)
+ * - This ensures no memory leaks from lingering subscriptions
+ *
+ * @param pubsub - The PubSub broadcasting ChangeEvents from mutations
+ * @param ref - The collection Ref containing entities keyed by ID
+ * @param collectionName - Name of the collection to watch (for filtering events)
+ * @param config - Optional query configuration (where, sort, select, limit, offset, debounceMs)
+ * @returns Scoped Effect producing a Stream of result arrays
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const pubsub = yield* createChangePubSub()
+ *   const ref = yield* createCollectionState<Book>([])
+ *
+ *   const stream = yield* watch(pubsub, ref, "books", {
+ *     where: { genre: "sci-fi" },
+ *     sort: { year: "desc" },
+ *     limit: 10,
+ *     debounceMs: 50, // custom debounce interval
+ *   })
+ *
+ *   // Consume the stream
+ *   yield* Stream.runForEach(stream, (results) =>
+ *     Effect.log(`Got ${results.length} results`)
+ *   )
+ * }).pipe(Effect.scoped)
+ * ```
+ */
+export const watch = (pubsub, ref, collectionName, config = {}) => Effect.gen(function* () {
+    // Get the current scope so we can fork a child scope for this subscription.
+    // The child scope allows us to clean up the subscription independently of
+    // the parent scope - either when the stream ends OR when the parent closes.
+    const parentScope = yield* Scope.Scope;
+    // Fork a child scope that will manage the subscription lifetime.
+    // When this child scope closes, the subscription will be cleaned up.
+    const subscriptionScope = yield* Scope.fork(parentScope, ExecutionStrategy.sequential);
+    // Use Effect.acquireRelease to manage the subscription:
+    // - Acquire: Subscribe to the PubSub (returns a Dequeue of ChangeEvents)
+    // - Release: Close the subscription scope (which triggers subscription cleanup)
+    //
+    // This explicit acquireRelease pattern makes the resource management visible
+    // and ensures proper cleanup when the stream is interrupted or completes.
+    const subscription = yield* Effect.acquireRelease(
+    // Acquire: Subscribe to the PubSub within the child scope
+    // PubSub.subscribe returns Effect<Dequeue, never, Scope.Scope>
+    // We provide the subscription scope so cleanup is tied to it
+    PubSub.subscribe(pubsub).pipe(Effect.provideService(Scope.Scope, subscriptionScope)), 
+    // Release: Close the child scope to trigger subscription cleanup
+    // This runs when the enclosing scope closes
+    () => Scope.close(subscriptionScope, Exit.void));
+    // Create a stream from the subscription queue
+    const changeStream = Stream.fromQueue(subscription);
+    // Filter to only events for this collection
+    const filteredStream = Stream.filter(changeStream, (event) => event.collection === collectionName);
+    // Apply debouncing to coalesce rapid mutations into a single re-evaluation.
+    // This prevents re-evaluating the query on every single mutation when they
+    // arrive in bursts (e.g., createMany inserting 100 entities).
+    const debounceMs = config.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const debouncedStream = Stream.debounce(filteredStream, Duration.millis(debounceMs));
+    // Map each (debounced) change event to a re-evaluation of the query.
+    // This transforms Stream<ChangeEvent> into Stream<ReadonlyArray<T>>
+    const changeResultStream = Stream.mapEffect(debouncedStream, () => evaluateQuery(ref, config));
+    // Create the initial emission stream: emit current result set immediately
+    const initialStream = Stream.fromEffect(evaluateQuery(ref, config));
+    // Concatenate initial emission with the change-driven stream
+    // This ensures subscribers receive the current state immediately,
+    // then receive updates as changes occur
+    const combinedStream = Stream.concat(initialStream, changeResultStream);
+    // Deduplicate consecutive identical result sets to avoid spurious emissions.
+    // This prevents re-emitting the same result set when a change event occurs
+    // but doesn't actually affect the query results (e.g., inserting an entity
+    // that doesn't match the where clause).
+    const deduplicatedStream = Stream.changesWith(combinedStream, resultsAreEqual);
+    // Ensure the subscription is cleaned up when the stream ends.
+    // This handles the case where the stream is interrupted or completed
+    // before the parent scope closes (e.g., Stream.take(n) stopping early).
+    // Closing the subscription scope triggers the acquireRelease cleanup.
+    const resultStream = Stream.ensuring(deduplicatedStream, Scope.close(subscriptionScope, Exit.void));
+    return resultStream;
+});
+//# sourceMappingURL=watch.js.map

package/dist/reactive/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/reactive/watch.ts"],"names":[],"mappings":"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"}