@procedures/client 0.8.0 → 0.8.1

package/src/procedures/collection/index.ts

@@ -21,6 +21,10 @@ export {
   getAllOutputSchema,
   entriesInputSchema,
   entriesOutputSchema,
+  findInputSchema,
+  findOutputSchema,
+  patchInputSchema,
+  patchOutputSchema,
   idsInputSchema,
   idsOutputSchema,
   changesInputSchema,
@@ -46,6 +50,8 @@ export type {
   GetAllInput,
   EntriesInput,
   CollectionEntry,
+  FindInput,
+  PatchInput,
   IdsInput,
   ChangesInput,
   ChangesOutput,
@@ -58,6 +64,52 @@ export type {
 
 // Procedures
 export { createCollectionProcedures } from "./procedures.js";
+export type { CollectionProceduresOptions, CollectionChangeEventsOptions } from "./procedures.js";
+
+// The change events of the writes (roadmap CLI-15)
+export { collectionChangeTopic, collectionTopicReads } from "./changes.js";
+export type { CollectionChangeEvent } from "./changes.js";
 
 // The storage interface of the core (the shape of client-collections' CollectionStorage)
-export type { CollectionStorage, StorageChanges, StorageMetadata } from "./storage.js";
+export type {
+  CollectionStorage,
+  StorageChanges,
+  StorageMetadata,
+  StorageWriteOptions,
+  StorageSetChange,
+  StorageDeleteChange,
+  StorageClearChange,
+  StorageChangeEvent,
+  StorageChangeBatch,
+  StorageObserver,
+} from "./storage.js";
+
+// The query language of the storages: the same JSON on the wire and in query() (roadmap CLI-34:
+// the one copy of the language)
+export {
+  DEFAULT_FIND_LIMIT,
+  DEFAULT_QUERY_OPERATORS,
+  DEFAULT_QUERY_POLICY,
+  QUERY_OPERATORS,
+  applyPatch,
+  compareStorageValues,
+  compileSelector,
+  isPatchOperations,
+  matchesSelector,
+  mergePatch,
+  patchProblems,
+  queryEntries,
+  queryOptionsProblems,
+  selectorProblems,
+} from "./query.js";
+export type {
+  StorageFieldOperators,
+  StoragePatch,
+  StoragePatchOperations,
+  StorageQueryOperator,
+  StorageQueryOptions,
+  StorageQueryPolicy,
+  StorageSelector,
+  StorageSort,
+  StorageSortDirection,
+} from "./query.js";

package/src/procedures/collection/procedures.ts

@@ -34,6 +34,12 @@ import {
   setBatchOutputSchema,
   deleteBatchInputSchema,
   deleteBatchOutputSchema,
+  findInputSchemaOf,
+  findOutputSchema,
+  patchInputSchema,
+  patchOutputSchema,
+  type FindInput,
+  type PatchInput,
   type GetInput,
   type GetFoundOutput,
   type SetInput,
@@ -50,6 +56,9 @@ import {
   type SetBatchInput,
   type DeleteBatchInput,
 } from "./schemas.js";
+import { DEFAULT_FIND_LIMIT, applyPatch, queryEntries, type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy } from "./query.js";
+import type { CollectionStorage, StorageWriteOptions } from "./storage.js";
+import { collectionChangeTopic, startChangeChain, writeWithChangeEvent } from "./changes.js";
 
 // =============================================================================
 // Handler Factory
@@ -77,6 +86,93 @@ function getStorage<T>(ctx: ProcedureContext): ReturnType<NonNullable<ProcedureC
   return ctx.repository.getStorage<T>(collection);
 }
 
+/** The options of a query from the input of `find`. */
+function queryOptionsOf(input: FindInput, policy: StorageQueryPolicy): StorageQueryOptions {
+  // A find without a limit gets the maxLimit of the policy (roadmap CLI-14)
+  const limit = input.limit ?? (Number.isFinite(policy.maxLimit) ? policy.maxLimit : undefined);
+  return {
+    ...(input.sort !== undefined && { sort: input.sort }),
+    ...(input.skip !== undefined && { skip: input.skip }),
+    ...(limit !== undefined && { limit }),
+  };
+}
+
+/** The options of the change events of the collection procedures (roadmap CLI-15). */
+export interface CollectionChangeEventsOptions {
+  /**
+   * The topic of the change events of a call, or undefined for no event. The partition of a
+   * collection (roadmap CLI-17) goes into the topic here, for example from the scope of the call.
+   * @default the topic `collections.<name>` of `collectionChangeTopic()`
+   */
+  topic?: ((collection: string, ctx: ProcedureContext) => string | undefined) | undefined;
+  /**
+   * True: the events also carry the values of the changed items. Each row `{ id, value }` passes
+   * the output filter of the host (`admitItem`) for each subscriber, and a refused row stays out of
+   * that event: its id goes to `withheld`. Without it, the events carry only the ids and the
+   * versions, and a subscriber reads the values with `changes`.
+   * @default false
+   */
+  values?: boolean | undefined;
+}
+
+/** The options of the collection procedures. */
+export interface CollectionProceduresOptions {
+  /**
+   * The query policy of `find`: the operators, and the limits of a selector and of the result. A
+   * selector or a limit that the policy does not permit is a `VALIDATION_ERROR`. The policy also
+   * goes to `query()` of the storage. `$regex` is off unless the policy has it in `operators`.
+   * @default DEFAULT_QUERY_POLICY, with `maxLimit` DEFAULT_FIND_LIMIT (1000)
+   */
+  queryPolicy?: StorageQueryPolicy | undefined;
+  /**
+   * The change events of the writes (roadmap CLI-15). Each write publishes a
+   * `CollectionChangeEvent` on the bus of its context, while a subscriber listens to the topic.
+   * The event has the ids and the versions, and the values only with `values`. False: the
+   * procedures publish no event.
+   * @default true, with the topic `collections.<name>` and no values
+   */
+  changeEvents?: boolean | CollectionChangeEventsOptions | undefined;
+}
+
+/** The write options of an input with an origin. */
+function writeOptionsOf(input: { origin?: string }): StorageWriteOptions | undefined {
+  return input.origin === undefined ? undefined : { origin: input.origin };
+}
+
+/**
+ * The patches of a storage without `patch()` that run, for each id. A patch of an id waits for the
+ * patch before it, so two patches of one process keep each field. A write of another writer
+ * between the read and the write of a patch is lost: give the storage a `patch()` for one step.
+ */
+const PATCHES = new WeakMap<object, Map<string, Promise<unknown>>>();
+
+/** This function patches an item of a storage without `patch()`: a read, a merge and a write. */
+function patchInParts(storage: CollectionStorage<unknown>, id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<unknown> {
+  let running = PATCHES.get(storage);
+  if (!running) {
+    running = new Map();
+    PATCHES.set(storage, running);
+  }
+  const queue = running;
+  const before = queue.get(id) ?? Promise.resolve();
+  const patch = before.then(async () => {
+    const current = await storage.get(id);
+    if (current === undefined) return undefined;
+    const next = applyPatch(current, fields);
+    await storage.set(id, next, options);
+    return next;
+  });
+  const settled = patch.then(
+    () => undefined,
+    () => undefined,
+  );
+  queue.set(id, settled);
+  void settled.then(() => {
+    if (queue.get(id) === settled) queue.delete(id);
+  });
+  return patch;
+}
+
 // =============================================================================
 // Collection Procedure Definitions
 // =============================================================================
@@ -85,6 +181,7 @@ function getStorage<T>(ctx: ProcedureContext): ReturnType<NonNullable<ProcedureC
  * Create collection procedures for a specific collection name.
  *
  * @param collectionName - Name of the collection
+ * @param options - The query policy of `find`
  * @returns Array of procedure definitions
  *
  * @example
@@ -93,10 +190,21 @@ function getStorage<T>(ctx: ProcedureContext): ReturnType<NonNullable<ProcedureC
  * registry.registerAll(userProcedures);
  * ```
  */
-export function createCollectionProcedures(collectionName: string): AnyProcedure[] {
+export function createCollectionProcedures(collectionName: string, options: CollectionProceduresOptions = {}): AnyProcedure[] {
   const basePath = ["collections", collectionName];
+  // A find of a caller gets a limit: DEFAULT_FIND_LIMIT, unless the policy gives its own maxLimit
+  const queryPolicy: StorageQueryPolicy = { ...options.queryPolicy, maxLimit: options.queryPolicy?.maxLimit ?? DEFAULT_FIND_LIMIT };
   // Each collection is a resource of its own (CAPABILITIES-2026-10): a capability can permit one
   const resource = `collection:${collectionName}`;
+  // The topic of the change events of a call (roadmap CLI-15). CLI-17 adds the partition with the option topic.
+  const events = options.changeEvents ?? true;
+  const topicRule: ((collection: string, ctx: ProcedureContext) => string | undefined) | undefined =
+    events === false ? undefined : (events !== true && events.topic) || ((name: string) => collectionChangeTopic(name));
+  const topicOf = (ctx: ProcedureContext): string | undefined => topicRule?.(collectionName, ctx);
+  const withValues = events !== false && events !== true && events.values === true;
+  /** A write, and then its change event on the bus of the context. */
+  const changing = <R>(ctx: ProcedureContext, storage: CollectionStorage<unknown>, ids: readonly string[] | "*", origin: string | undefined, write: () => Promise<R>): Promise<R> =>
+    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx) : undefined, ids, origin, write, withValues);
 
   return [
     // Get
@@ -131,7 +239,7 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
       handler: async (input: SetInput, ctx: ProcedureContext) => {
         const storage = getStorage(ctx);
-        await storage.set(input.id, input.value);
+        await changing(ctx, storage, [input.id], input.origin, () => storage.set(input.id, input.value, writeOptionsOf(input)));
       },
     }),
 
@@ -147,7 +255,7 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
       handler: async (input: DeleteInput, ctx: ProcedureContext) => {
         const storage = getStorage(ctx);
-        return storage.delete(input.id);
+        return changing(ctx, storage, [input.id], input.origin, () => storage.delete(input.id, writeOptionsOf(input)));
       },
     }),
 
@@ -235,6 +343,9 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
         const storage = getStorage(ctx);
         if (storage.getChangesSince) {
           const changes = await storage.getChangesSince(input.since);
+          // The chain of the change events starts at this version: the caller then applies the
+          // next event without a read (roadmap CLI-15)
+          if (topicRule) startChangeChain(ctx.bus, storage, topicOf(ctx), changes.version);
           return {
             version: changes.version,
             full: changes.full,
@@ -252,6 +363,51 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
     }),
 
+    // Find: the items that match a JSON selector, with an order, a skip and a limit (roadmap CLI-14)
+    defineProcedure({
+      path: [...basePath, "find"],
+      input: findInputSchemaOf(queryPolicy),
+      output: findOutputSchema,
+      metadata: {
+        effects: { reads: [resource], writes: [] },
+        description: `Find the items of ${collectionName} that match a selector, with their ids, an order, a skip and a limit`,
+        tags: ["collections", collectionName, "read", "query"],
+      },
+      handler: async (input: FindInput, ctx: ProcedureContext) => {
+        const storage = getStorage(ctx);
+        const selector = input.selector ?? {};
+        const query = queryOptionsOf(input, queryPolicy);
+        // The storage runs the selector itself when it can: a database does not read each item. It
+        // gets the policy of the host, so it permits what the procedure permits.
+        if (storage.query) return (await storage.query(selector, query, queryPolicy)).map(([id, value]) => ({ id, value }));
+        if (!storage.getEntries) {
+          throw new Error(`The storage of ${collectionName} cannot run a selector or give the ids of its items`);
+        }
+        return queryEntries(await storage.getEntries(), selector, query, queryPolicy).map(([id, value]) => ({ id, value }));
+      },
+    }),
+
+    // Patch: merge fields into one item, a JSON Merge Patch (roadmap CLI-14)
+    defineProcedure({
+      path: [...basePath, "patch"],
+      input: patchInputSchema,
+      output: patchOutputSchema,
+      metadata: {
+        effects: { reads: [resource], writes: [resource], idempotent: true },
+        description: `Merge fields into one item of ${collectionName}: a JSON Merge Patch, or the operations $set and $unset`,
+        tags: ["collections", collectionName, "write"],
+      },
+      handler: async (input: PatchInput, ctx: ProcedureContext) => {
+        const storage = getStorage(ctx);
+        const write = writeOptionsOf(input);
+        const value = await changing(ctx, storage, [input.id], input.origin, () =>
+          storage.patch ? storage.patch(input.id, input.fields, write) : patchInParts(storage, input.id, input.fields, write),
+        );
+        const output: GetFoundOutput = value === undefined ? { found: false } : { found: true, value };
+        return output;
+      },
+    }),
+
     // Size
     defineProcedure({
       path: [...basePath, "size"],
@@ -278,9 +434,9 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
         description: `Clear all items from ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (_input: ClearInput, ctx: ProcedureContext) => {
+      handler: async (input: ClearInput, ctx: ProcedureContext) => {
         const storage = getStorage(ctx);
-        await storage.clear();
+        await changing(ctx, storage, "*", input.origin, () => storage.clear(writeOptionsOf(input)));
       },
     }),
 
@@ -318,7 +474,7 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
           item.id,
           item.value,
         ]);
-        await storage.setBatch(items);
+        await changing(ctx, storage, items.map(([id]) => id), input.origin, () => storage.setBatch(items, writeOptionsOf(input)));
       },
     }),
 
@@ -334,7 +490,7 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
       handler: async (input: DeleteBatchInput, ctx: ProcedureContext) => {
         const storage = getStorage(ctx);
-        return storage.deleteBatch(input.ids);
+        return changing(ctx, storage, input.ids, input.origin, () => storage.deleteBatch(input.ids, writeOptionsOf(input)));
       },
     }),
   ];