@procedures/client 0.8.1 → 0.9.0

package/src/events/publisher.ts

@@ -28,8 +28,10 @@ import { z } from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { InvocationError } from "../procedures/invoke.js";
 import { capabilityRefusal } from "../procedures/capability.js";
-import { collectionTopicReads } from "../procedures/collection/changes.js";
+import { collectionChangeTopic, collectionTopicReads } from "../procedures/collection/changes.js";
+import { collectionTopicPartition, partitionOfCall } from "../procedures/collection/partition.js";
 import type { AnyProcedure, Capability, ProcedureContext } from "../procedures/types.js";
+import type { Principal } from "../server/types.js";
 import type { EventBus, Unsubscribe } from "./types.js";
 import { getGlobalEventBus } from "./bus.js";
 import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
@@ -53,6 +55,8 @@ export interface TopicCall {
   readonly capability: Capability;
   /** The metadata of the call: the connection id and the headers of a network request. */
   readonly metadata: Readonly<Record<string, unknown>>;
+  /** The principal of the call, from the authentication of the host. */
+  readonly principal?: Principal | undefined;
 }
 
 /** The options of an `EventPublisher`. */
@@ -161,17 +165,18 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
 
   constructor(
     bus: EventBus,
-    topics: readonly string[],
+    /** The topics of the subscriber, each with the topic of the bus that it listens to */
+    routes: ReadonlyArray<readonly [topic: string, busTopic: string]>,
     private readonly buffer: number,
     private readonly signal: AbortSignal | undefined,
     private readonly onClose: (subscription: TopicSubscription) => void,
     /** The output filter of the host for this subscriber: each row of a value passes it */
     private readonly admit: ((item: unknown) => Promise<boolean>) | undefined,
   ) {
-    this.confirmation = { type: "subscribed", topics };
+    this.confirmation = { type: "subscribed", topics: routes.map(([topic]) => topic) };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
-    this.unsubscribes = topics.map((topic) =>
-      bus.on(topic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
+    this.unsubscribes = routes.map(([topic, busTopic]) =>
+      bus.on(busTopic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
     );
     signal?.addEventListener("abort", this.onAbort, { once: true });
   }
@@ -344,11 +349,24 @@ export class EventPublisher {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
   }
 
+  /**
+   * The topic of the bus for a topic of a subscriber (roadmap CLI-17). A topic of a partitioned
+   * collection names the partition that the subscriber asks for, as the input of a procedure does:
+   * the resolver of the repository gives the partition, so a subscriber cannot name the topic of
+   * another tenant. A collection without partitions refuses a topic with a partition.
+   */
+  private async busTopic(topic: string, ctx: ProcedureContext): Promise<string> {
+    const parts = collectionTopicPartition(topic);
+    if (!parts) return topic;
+    const partition = await partitionOfCall(ctx, parts.collection, parts.partition);
+    return collectionChangeTopic(parts.collection, partition);
+  }
+
   /**
    * The stream of one subscription. The publisher examines each topic before it adds a listener:
-   * the topic rule first, then `allow`. A call with one bad topic makes no subscription.
+   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
    */
-  private subscribe(topics: readonly string[], ctx: ProcedureContext): TopicSubscription {
+  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
     const unique = [...new Set(topics)];
     for (const topic of unique) {
       if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
@@ -361,14 +379,16 @@ export class EventPublisher {
       if (refusal) throw new InvocationError("FORBIDDEN", `The topic "${topic}": ${refusal.message}`, ctx.path, refusal.reason);
     }
     if (this.allow) {
-      const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata };
+      const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata, ...(ctx.principal ? { principal: ctx.principal } : {}) };
       for (const topic of unique) {
         if (!this.allow(topic, call)) {
           throw new InvocationError("FORBIDDEN", `The capability of the call does not permit the topic "${topic}"`, ctx.path, "topic-not-allowed");
         }
       }
     }
-    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
+    const routes: Array<readonly [string, string]> = [];
+    for (const topic of unique) routes.push([topic, await this.busTopic(topic, ctx)]);
+    const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
     this.open.add(subscription);
     return subscription.closeIfAborted();
   }

package/src/procedures/collection/changes.ts

@@ -56,11 +56,11 @@ export interface CollectionChangeEvent {
 }
 
 /**
- * This function gives the topic of the change events of a collection: `collections.<name>`. The
- * partition of roadmap CLI-17 comes after the name, with the option `topic` of the procedures.
+ * This function gives the topic of the change events of a collection: `collections.<name>`, or
+ * `collections.<name>.<partition>` for a partition (roadmap CLI-17).
  */
-export function collectionChangeTopic(collection: string): string {
-  return `collections.${collection}`;
+export function collectionChangeTopic(collection: string, partition?: string): string {
+  return partition === undefined ? `collections.${collection}` : `collections.${collection}.${partition}`;
 }
 
 /**

package/src/procedures/collection/index.ts

@@ -70,6 +70,10 @@ export type { CollectionProceduresOptions, CollectionChangeEventsOptions } from
 export { collectionChangeTopic, collectionTopicReads } from "./changes.js";
 export type { CollectionChangeEvent } from "./changes.js";
 
+// The partitions of a collection (roadmap CLI-17)
+export { PARTITION_PATTERN, collectionTopicPartition, partitionOfCall, storageOfCall, withPartition } from "./partition.js";
+export type { CollectionPartitions, PartitionInput, PartitionResolver } from "./partition.js";
+
 // The storage interface of the core (the shape of client-collections' CollectionStorage)
 export type {
   CollectionStorage,

package/src/procedures/collection/partition.ts

@@ -0,0 +1,123 @@
+/**
+ * The partitions of a collection (roadmap CLI-17). One `collections.<name>.*` surface serves the
+ * items of several partitions, for example one per tenant, or one per tenant and scope. Each call
+ * reads and writes one partition.
+ *
+ * - The host registers the partitions of a collection with its repository: the storage of each
+ *   partition and the resolver (`ProcedureServer.usePartitions(name, { storageOf, resolve })`).
+ * - The input of a call can ask for a partition (`partition`, for example a scope). The resolver
+ *   gives the partition of the call from its context: the tenant comes from the principal, never
+ *   from the input alone. It can refuse the call.
+ * - A subscriber names the partition that it asks for in the topic, as an input does:
+ *   `collections.<name>.<requested>`. The publisher resolves it in the same way and listens to the
+ *   topic of the resolved partition, so a subscriber cannot name the topic of another tenant.
+ * - A collection without partitions refuses a call or a topic with a partition.
+ */
+import type { ZodLike } from "../../client/validation/types.js";
+import { InvocationError } from "../invoke.js";
+import type { ProcedureContext } from "../types.js";
+import type { CollectionStorage } from "./storage.js";
+
+/** The characters of a partition: letters, digits and `_ . : @ ~ + | / -`, 256 at most. */
+export const PARTITION_PATTERN: RegExp = /^[A-Za-z0-9_.:@~+|/-]{1,256}$/;
+
+/** The field of an input that asks for a partition. */
+export interface PartitionInput {
+  partition?: string;
+}
+
+/**
+ * The resolver of the partition of a call. It gets the context (with `ctx.principal`) and the
+ * partition that the input asks for. It gives the partition, `undefined` for the storage of the
+ * collection without a partition, or `null` to refuse the call (`FORBIDDEN`, reason
+ * `partition-not-allowed`). An error that it throws passes through.
+ */
+export type PartitionResolver = (ctx: ProcedureContext, requested: string | undefined) => string | undefined | null | Promise<string | undefined | null>;
+
+/**
+ * This function adds the field `partition` to the input schema of a collection procedure. The
+ * repository of the call decides at the call if the collection has partitions.
+ */
+export function withPartition<T>(schema: ZodLike<T>): ZodLike<T & PartitionInput> {
+  const validate = (data: unknown): { success: true; data: T & PartitionInput } | { success: false; error: { message: string; errors: { path: (string | number)[]; message: string }[] } } => {
+    const fail = (message: string) => ({ success: false as const, error: { message, errors: [{ path: ["partition"], message }] } });
+    const requested = typeof data === "object" && data !== null && !Array.isArray(data) ? (data as Record<string, unknown>)["partition"] : undefined;
+    if (requested !== undefined && (typeof requested !== "string" || !PARTITION_PATTERN.test(requested))) {
+      return fail("partition must have 1 to 256 letters, digits or the characters _ . : @ ~ + | / -");
+    }
+    const inner = schema.safeParse(data);
+    if (!inner.success) return inner as { success: false; error: { message: string; errors: { path: (string | number)[]; message: string }[] } };
+    const parsed = inner.data as T & PartitionInput;
+    return { success: true, data: requested === undefined ? parsed : { ...parsed, partition: requested as string } };
+  };
+  return {
+    parse(data: unknown) {
+      const result = validate(data);
+      if (result.success) return result.data;
+      throw new Error(result.error.message);
+    },
+    safeParse: validate,
+  } as ZodLike<T & PartitionInput>;
+}
+
+/** The partitions of a collection: the storage of each partition, and the resolver of a call. */
+export interface CollectionPartitions<T = unknown> {
+  /**
+   * The storage of a partition. Give the same storage for the same partition each time: the change
+   * events of a storage keep their order with it.
+   */
+  storageOf(partition: string): CollectionStorage<T>;
+  /** The resolver of the partition of a call. */
+  resolve: PartitionResolver;
+}
+
+/** The refusal of a partition. */
+function partitionRefused(ctx: ProcedureContext, message: string): InvocationError {
+  return new InvocationError("FORBIDDEN", message, ctx.path, "partition-not-allowed");
+}
+
+/**
+ * This function gives the partition of a call to a collection: the resolver of the repository
+ * gives it from the context and the requested partition. It throws `FORBIDDEN` (reason
+ * `partition-not-allowed`) when the resolver refuses, or when the collection has no partitions and
+ * the call asks for one.
+ */
+export async function partitionOfCall(ctx: ProcedureContext, collection: string, requested: string | undefined): Promise<string | undefined> {
+  const repository = ctx.repository;
+  if (!repository?.hasPartitions?.(collection) || !repository.resolvePartition) {
+    if (requested !== undefined) throw partitionRefused(ctx, `The collection ${collection} has no partitions`);
+    return undefined;
+  }
+  const partition = await repository.resolvePartition(collection, ctx, requested);
+  if (partition === null) {
+    throw partitionRefused(ctx, `The call cannot use the partition${requested === undefined ? "" : ` "${requested}"`} of ${collection}`);
+  }
+  if (partition !== undefined && !PARTITION_PATTERN.test(partition)) {
+    throw new Error(`The partition resolver gave a partition that is not valid: ${JSON.stringify(partition).slice(0, 80)}`);
+  }
+  return partition;
+}
+
+/**
+ * This function gives the storage of a call: of the collection, or of its partition. A repository
+ * without `getPartitionStorage` refuses a partition.
+ */
+export function storageOfCall<T>(ctx: ProcedureContext, collection: string, partition: string | undefined): CollectionStorage<T> {
+  const repository = ctx.repository;
+  if (!repository) throw new Error("Repository not available in procedure context");
+  if (partition === undefined) return repository.getStorage<T>(collection);
+  if (!repository.getPartitionStorage) {
+    throw new Error(`The repository has no partitions, so it cannot give the partition "${partition}" of ${collection}`);
+  }
+  return repository.getPartitionStorage<T>(collection, partition);
+}
+
+/**
+ * This function gives the collection and the partition part of a topic `collections.<name>` or
+ * `collections.<name>.<partition>`, or undefined for another topic.
+ */
+export function collectionTopicPartition(topic: string): { collection: string; partition: string | undefined } | undefined {
+  const match = /^collections\.([^.]+)(?:\.(.+))?$/.exec(topic);
+  if (!match) return undefined;
+  return { collection: match[1]!, partition: match[2] };
+}

package/src/procedures/collection/procedures.ts

@@ -59,6 +59,7 @@ import {
 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
@@ -75,17 +76,6 @@ function getCollectionFromPath(path: string[]): string {
   return path[1]!;
 }
 
-/**
- * Get storage from context, throwing if repository is not available.
- */
-function getStorage<T>(ctx: ProcedureContext): ReturnType<NonNullable<ProcedureContext["repository"]>["getStorage"]> {
-  if (!ctx.repository) {
-    throw new Error("Repository not available in procedure context");
-  }
-  const collection = getCollectionFromPath(ctx.path);
-  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)
@@ -100,11 +90,11 @@ function queryOptionsOf(input: FindInput, policy: StorageQueryPolicy): StorageQu
 /** 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()`
+   * 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) => string | undefined) | undefined;
+  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
@@ -196,29 +186,38 @@ export function createCollectionProcedures(collectionName: string, options: Coll
   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.
+  // 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) => string | undefined) | undefined =
-    events === false ? undefined : (events !== true && events.topic) || ((name: string) => collectionChangeTopic(name));
-  const topicOf = (ctx: ProcedureContext): string | undefined => topicRule?.(collectionName, ctx);
+  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, 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);
+  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
@@ -230,47 +229,47 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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 changing(ctx, storage, [input.id], input.origin, () => storage.set(input.id, input.value, writeOptionsOf(input)));
+      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 changing(ctx, storage, [input.id], input.origin, () => storage.delete(input.id, writeOptionsOf(input)));
+      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);
       },
     }),
@@ -278,15 +277,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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();
       },
     }),
@@ -294,15 +293,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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`);
         }
@@ -313,15 +312,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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);
@@ -332,20 +331,20 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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), changes.version);
+          if (topicRule) startChangeChain(ctx.bus, storage, topicOf(ctx, partition), changes.version);
           return {
             version: changes.version,
             full: changes.full,
@@ -366,15 +365,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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),
+      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, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      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
@@ -390,17 +389,17 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Patch: merge fields into one item, a JSON Merge Patch (roadmap CLI-14)
     defineProcedure({
       path: [...basePath, "patch"],
-      input: patchInputSchema,
+      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, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: PatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
         const write = writeOptionsOf(input);
-        const value = await changing(ctx, storage, [input.id], input.origin, () =>
+        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 };
@@ -411,15 +410,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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();
       },
     }),
@@ -427,31 +426,31 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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 changing(ctx, storage, "*", input.origin, () => storage.clear(writeOptionsOf(input)));
+      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);
@@ -461,36 +460,36 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // 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 changing(ctx, storage, items.map(([id]) => id), input.origin, () => storage.setBatch(items, writeOptionsOf(input)));
+        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 changing(ctx, storage, input.ids, input.origin, () => storage.deleteBatch(input.ids, writeOptionsOf(input)));
+      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)));
       },
     }),
   ];

package/src/procedures/index.ts

@@ -127,6 +127,8 @@ export {
   createCollectionProcedures,
   collectionChangeTopic,
   collectionTopicReads,
+  PARTITION_PATTERN,
+  collectionTopicPartition,
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
   DEFAULT_QUERY_POLICY,
@@ -146,6 +148,9 @@ export type {
   CollectionProceduresOptions,
   CollectionChangeEventsOptions,
   CollectionChangeEvent,
+  CollectionPartitions,
+  PartitionInput,
+  PartitionResolver,
   StoragePatchOperations,
   StorageQueryOperator,
   StorageQueryPolicy,