@procedures/client 0.8.0 → 0.9.0

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,10 @@ 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";
+import { partitionOfCall, storageOfCall, withPartition, type PartitionInput } from "./partition.js";
 
 // =============================================================================
 // Handler Factory
@@ -66,15 +76,91 @@ function getCollectionFromPath(path: string[]): string {
   return path[1]!;
 }
 
+/** 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. It gets the partition of
+   * the call (roadmap CLI-17).
+   * @default `collectionChangeTopic(name, partition)`: `collections.<name>`, or `collections.<name>.<partition>`
+   */
+  topic?: ((collection: string, ctx: ProcedureContext, partition: string | undefined) => 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 };
+}
+
 /**
- * Get storage from context, throwing if repository is not available.
+ * 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.
  */
-function getStorage<T>(ctx: ProcedureContext): ReturnType<NonNullable<ProcedureContext["repository"]>["getStorage"]> {
-  if (!ctx.repository) {
-    throw new Error("Repository not available in procedure context");
+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 collection = getCollectionFromPath(ctx.path);
-  return ctx.repository.getStorage<T>(collection);
+  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;
 }
 
 // =============================================================================
@@ -85,6 +171,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,24 +180,44 @@ 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), with its partition (roadmap CLI-17)
+  const events = options.changeEvents ?? true;
+  const topicRule: ((collection: string, ctx: ProcedureContext, partition: string | undefined) => string | undefined) | undefined =
+    events === false ? undefined : (events !== true && events.topic) || ((name: string, _ctx: ProcedureContext, partition: string | undefined) => collectionChangeTopic(name, partition));
+  const topicOf = (ctx: ProcedureContext, partition: string | undefined): string | undefined => topicRule?.(collectionName, ctx, partition);
+  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, partition: string | undefined, storage: CollectionStorage<unknown>, ids: readonly string[] | "*", origin: string | undefined, write: () => Promise<R>): Promise<R> =>
+    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx, partition) : undefined, ids, origin, write, withValues);
+  /**
+   * The partition and the storage of a call (roadmap CLI-17). The repository of the call has the
+   * partitions of the collection and their resolver: the tenant comes from the principal.
+   */
+  const storageOf = async (input: PartitionInput, ctx: ProcedureContext): Promise<{ storage: CollectionStorage<unknown>; partition: string | undefined }> => {
+    const collection = getCollectionFromPath(ctx.path);
+    const partition = await partitionOfCall(ctx, collection, input.partition);
+    return { storage: storageOfCall<unknown>(ctx, collection, partition), partition };
+  };
 
   return [
     // Get
     defineProcedure({
       path: [...basePath, "get"],
-      input: getInputSchema,
+      input: withPartition(getInputSchema),
       output: getOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get item from ${collectionName} by ID`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (input: GetInput, ctx : ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: GetInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         const value = await storage.get(input.id);
         if (input.found !== true) return value;
         // The output with `found` keeps a stored null apart from a missing id, in one call
@@ -122,47 +229,47 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // Set
     defineProcedure({
       path: [...basePath, "set"],
-      input: setInputSchema,
+      input: withPartition(setInputSchema),
       output: setOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Set item in ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (input: SetInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        await storage.set(input.id, input.value);
+      handler: async (input: SetInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
+        await changing(ctx, partition, storage, [input.id], input.origin, () => storage.set(input.id, input.value, writeOptionsOf(input)));
       },
     }),
 
     // Delete
     defineProcedure({
       path: [...basePath, "delete"],
-      input: deleteInputSchema,
+      input: withPartition(deleteInputSchema),
       output: deleteOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Delete item from ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (input: DeleteInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        return storage.delete(input.id);
+      handler: async (input: DeleteInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
+        return changing(ctx, partition, storage, [input.id], input.origin, () => storage.delete(input.id, writeOptionsOf(input)));
       },
     }),
 
     // Has
     defineProcedure({
       path: [...basePath, "has"],
-      input: hasInputSchema,
+      input: withPartition(hasInputSchema),
       output: hasOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Check if item exists in ${collectionName}`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (input: HasInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: HasInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         return storage.has(input.id);
       },
     }),
@@ -170,15 +277,15 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // GetAll
     defineProcedure({
       path: [...basePath, "getAll"],
-      input: getAllInputSchema,
+      input: withPartition(getAllInputSchema),
       output: getAllOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get all items from ${collectionName}`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: GetAllInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: GetAllInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         return storage.getAll();
       },
     }),
@@ -186,15 +293,15 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // Entries: each item with its id, for a sync (roadmap R2)
     defineProcedure({
       path: [...basePath, "entries"],
-      input: entriesInputSchema,
+      input: withPartition(entriesInputSchema),
       output: entriesOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get all items of ${collectionName} with their ids`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: EntriesInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: EntriesInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         if (!storage.getEntries) {
           throw new Error(`The storage of ${collectionName} cannot give the ids of its items`);
         }
@@ -205,15 +312,15 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // Ids: the ids of the items without the values, for a full sync
     defineProcedure({
       path: [...basePath, "ids"],
-      input: idsInputSchema,
+      input: withPartition(idsInputSchema),
       output: idsOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get the ids of the items of ${collectionName}, without the values`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: IdsInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: IdsInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         if (storage.getIds) return storage.getIds();
         // A storage without getIds() gives its entries: the values stay on the server
         if (storage.getEntries) return (await storage.getEntries()).map(([id]) => id);
@@ -224,17 +331,20 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // Changes: the items that changed after a version, for a delta sync (roadmap R28)
     defineProcedure({
       path: [...basePath, "changes"],
-      input: changesInputSchema,
+      input: withPartition(changesInputSchema),
       output: changesOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get the items of ${collectionName} that changed after a version`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (input: ChangesInput, ctx: ProcedureContext): Promise<ChangesOutput> => {
-        const storage = getStorage(ctx);
+      handler: async (input: ChangesInput & PartitionInput, ctx: ProcedureContext): Promise<ChangesOutput> => {
+        const { storage, partition } = await storageOf(input, 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, partition), changes.version);
           return {
             version: changes.version,
             full: changes.full,
@@ -252,18 +362,63 @@ 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: withPartition(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 & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, 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: withPartition(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 & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
+        const write = writeOptionsOf(input);
+        const value = await changing(ctx, partition, 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"],
-      input: sizeInputSchema,
+      input: withPartition(sizeInputSchema),
       output: sizeOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get number of items in ${collectionName}`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: SizeInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: SizeInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         return storage.size();
       },
     }),
@@ -271,31 +426,31 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // Clear
     defineProcedure({
       path: [...basePath, "clear"],
-      input: clearInputSchema,
+      input: withPartition(clearInputSchema),
       output: clearOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Clear all items from ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (_input: ClearInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        await storage.clear();
+      handler: async (input: ClearInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
+        await changing(ctx, partition, storage, "*", input.origin, () => storage.clear(writeOptionsOf(input)));
       },
     }),
 
     // GetBatch
     defineProcedure({
       path: [...basePath, "getBatch"],
-      input: getBatchInputSchema,
+      input: withPartition(getBatchInputSchema),
       output: getBatchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get multiple items from ${collectionName}`,
         tags: ["collections", collectionName, "read", "batch"],
       },
-      handler: async (input: GetBatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: GetBatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         const result = await storage.getBatch(input.ids);
         // Convert Map to plain object
         return Object.fromEntries(result);
@@ -305,36 +460,36 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
     // SetBatch
     defineProcedure({
       path: [...basePath, "setBatch"],
-      input: setBatchInputSchema,
+      input: withPartition(setBatchInputSchema),
       output: setBatchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Set multiple items in ${collectionName}`,
         tags: ["collections", collectionName, "write", "batch"],
       },
-      handler: async (input: SetBatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: SetBatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
         const items: Array<[string, unknown]> = input.items.map((item) => [
           item.id,
           item.value,
         ]);
-        await storage.setBatch(items);
+        await changing(ctx, partition, storage, items.map(([id]) => id), input.origin, () => storage.setBatch(items, writeOptionsOf(input)));
       },
     }),
 
     // DeleteBatch
     defineProcedure({
       path: [...basePath, "deleteBatch"],
-      input: deleteBatchInputSchema,
+      input: withPartition(deleteBatchInputSchema),
       output: deleteBatchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Delete multiple items from ${collectionName}`,
         tags: ["collections", collectionName, "write", "batch"],
       },
-      handler: async (input: DeleteBatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        return storage.deleteBatch(input.ids);
+      handler: async (input: DeleteBatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
+        return changing(ctx, partition, storage, input.ids, input.origin, () => storage.deleteBatch(input.ids, writeOptionsOf(input)));
       },
     }),
   ];