@procedures/client 0.2.3 → 0.4.0

package/src/procedures/collection/index.ts

@@ -19,6 +19,10 @@ export {
   hasOutputSchema,
   getAllInputSchema,
   getAllOutputSchema,
+  entriesInputSchema,
+  entriesOutputSchema,
+  changesInputSchema,
+  changesOutputSchema,
   sizeInputSchema,
   sizeOutputSchema,
   clearInputSchema,
@@ -37,6 +41,10 @@ export type {
   DeleteInput,
   HasInput,
   GetAllInput,
+  EntriesInput,
+  CollectionEntry,
+  ChangesInput,
+  ChangesOutput,
   SizeInput,
   ClearInput,
   GetBatchInput,
@@ -48,4 +56,4 @@ export type {
 export { createCollectionProcedures } from "./procedures.js";
 
 // The storage interface of the core (the shape of client-collections' CollectionStorage)
-export type { CollectionStorage, StorageMetadata } from "./storage.js";
+export type { CollectionStorage, StorageChanges, StorageMetadata } from "./storage.js";

package/src/procedures/collection/procedures.ts

@@ -18,6 +18,10 @@ import {
   hasOutputSchema,
   getAllInputSchema,
   getAllOutputSchema,
+  entriesInputSchema,
+  entriesOutputSchema,
+  changesInputSchema,
+  changesOutputSchema,
   sizeInputSchema,
   sizeOutputSchema,
   clearInputSchema,
@@ -33,6 +37,9 @@ import {
   type DeleteInput,
   type HasInput,
   type GetAllInput,
+  type EntriesInput,
+  type ChangesInput,
+  type ChangesOutput,
   type SizeInput,
   type ClearInput,
   type GetBatchInput,
@@ -168,6 +175,56 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
     }),
 
+    // Entries: each item with its id, for a sync (roadmap R2)
+    defineProcedure({
+      path: [...basePath, "entries"],
+      input: 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);
+        if (!storage.getEntries) {
+          throw new Error(`The storage of ${collectionName} cannot give the ids of its items`);
+        }
+        return (await storage.getEntries()).map(([id, value]) => ({ id, value }));
+      },
+    }),
+
+    // Changes: the items that changed after a version, for a delta sync (roadmap R28)
+    defineProcedure({
+      path: [...basePath, "changes"],
+      input: 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);
+        if (storage.getChangesSince) {
+          const changes = await storage.getChangesSince(input.since);
+          return {
+            version: changes.version,
+            full: changes.full,
+            changed: changes.changed.map(([id, value]) => ({ id, value })),
+            deleted: changes.deleted,
+          };
+        }
+        // A storage without a change log gives all its items. The empty version asks for all
+        // items again at the next call.
+        if (storage.getEntries) {
+          const entries = await storage.getEntries();
+          return { version: "", full: true, changed: entries.map(([id, value]) => ({ id, value })), deleted: [] };
+        }
+        throw new Error(`The storage of ${collectionName} cannot give its changes or the ids of its items`);
+      },
+    }),
+
     // Size
     defineProcedure({
       path: [...basePath, "size"],

package/src/procedures/collection/schemas.ts

@@ -335,6 +335,116 @@ export const getAllOutputSchema : ZodLike<unknown[]> = createSchema<unknown[]>((
   };
 });
 
+// =============================================================================
+// Entries Operation Schemas
+// =============================================================================
+
+/**
+ * Input for entries operation - empty object.
+ */
+export interface EntriesInput {}
+
+export const entriesInputSchema : ZodLike<EntriesInput> = createSchema<EntriesInput>((data) => {
+  if (!isObject(data)) {
+    return {
+      success: false,
+      error: {
+        message: "Input must be an object",
+        errors: [{ path: [], message: "Input must be an object" }],
+      },
+    };
+  }
+  return { success: true, data: {} };
+});
+
+/** One item of a collection with its id. */
+export interface CollectionEntry {
+  id: string;
+  value: unknown;
+}
+
+/**
+ * Output for entries operation - each item with its id. A sync needs the ids: `getAll` gives
+ * only the values (roadmap R2).
+ */
+export const entriesOutputSchema : ZodLike<CollectionEntry[]> = createSchema<CollectionEntry[]>((data) => {
+  if (isArray(data) && data.every((entry) => isObject(entry) && isString(entry["id"]) && "value" in entry)) {
+    return { success: true, data: data as CollectionEntry[] };
+  }
+  return {
+    success: false,
+    error: {
+      message: "Output must be an array of { id, value } objects",
+      errors: [{ path: [], message: "Output must be an array of { id, value } objects" }],
+    },
+  };
+});
+
+// =============================================================================
+// Changes Operation Schemas
+// =============================================================================
+
+/** Input for changes operation: the version of an earlier call (roadmap R28). */
+export interface ChangesInput {
+  /** The `version` of an earlier result. Without it, the result has all items. */
+  since?: string;
+}
+
+export const changesInputSchema : ZodLike<ChangesInput> = createSchema<ChangesInput>((data) => {
+  if (!isObject(data)) {
+    return {
+      success: false,
+      error: {
+        message: "Input must be an object",
+        errors: [{ path: [], message: "Input must be an object" }],
+      },
+    };
+  }
+  const since = data["since"];
+  if (since !== undefined && !isString(since)) {
+    return {
+      success: false,
+      error: {
+        message: "since must be a string",
+        errors: [{ path: ["since"], message: "since must be a string" }],
+      },
+    };
+  }
+  return { success: true, data: since === undefined ? {} : { since } };
+});
+
+/**
+ * Output for changes operation: the items that changed after the version, the deleted ids, and
+ * the new version. When `full` is true, `changed` has each item (roadmap R28).
+ */
+export interface ChangesOutput {
+  version: string;
+  full: boolean;
+  changed: CollectionEntry[];
+  deleted: string[];
+}
+
+export const changesOutputSchema : ZodLike<ChangesOutput> = createSchema<ChangesOutput>((data) => {
+  if (
+    isObject(data) &&
+    isString(data["version"]) &&
+    typeof data["full"] === "boolean" &&
+    isArray(data["changed"]) &&
+    data["changed"].every((entry) => isObject(entry) && isString(entry["id"]) && "value" in entry) &&
+    isArray(data["deleted"]) &&
+    data["deleted"].every((id) => isString(id))
+  ) {
+    return { success: true, data: data as unknown as ChangesOutput };
+  }
+  return {
+    success: false,
+    error: {
+      message: "Output must be { version, full, changed: [{ id, value }], deleted: [id] }",
+      errors: [{ path: [], message: "Output must be { version, full, changed: [{ id, value }], deleted: [id] }" }],
+    },
+  };
+});
+
 // =============================================================================
 // Size Operation Schemas
 // =============================================================================

package/src/procedures/collection/storage.ts

@@ -15,6 +15,18 @@ export interface CollectionStorage<T> {
   get(id: string): Promise<T | undefined>;
   /** Every item of the collection. */
   getAll(): Promise<T[]>;
+  /**
+   * Every item with its id. A sync needs the ids (roadmap R2). A storage that cannot give
+   * them does not have this method.
+   */
+  getEntries?(): Promise<Array<[string, T]>>;
+  /**
+   * The changes after a version (roadmap R28). A storage without a change log does not have
+   * this method, and a sync uses `getEntries()`.
+   *
+   * @param since - A `version` that an earlier call gave. Without it, the result has all items.
+   */
+  getChangesSince?(since?: string): Promise<StorageChanges<T>>;
   /** The items for which the predicate gives true. */
   find(predicate: (item: T) => boolean): Promise<T[]>;
   /** True when an item has this id. */
@@ -33,12 +45,38 @@ export interface CollectionStorage<T> {
   deleteBatch(ids: string[]): Promise<number>;
   /** The items of several ids. An id with no item is not in the map. */
   getBatch(ids: string[]): Promise<Map<string, T>>;
+  /**
+   * This method sends the writes that wait in the storage to their destination (roadmap R28). A storage
+   * that keeps no writes does not have this method. `ProcedureServer.useStorage` calls it.
+   */
+  flush?(): Promise<void>;
   /** Release the resources of the storage. */
   close(): Promise<void>;
   /** The kind, the size and the statistics of the storage. */
   getMetadata?(): Promise<StorageMetadata>;
 }
 
+/**
+ * The changes of a storage after a version (roadmap R28).
+ *
+ * - `version` is opaque. The next call gives it back as `since`.
+ * - When `full` is true, `changed` has every item, and each id that it does not have was
+ *   deleted. A storage gives a full result when it cannot find the changes since the version:
+ *   the first call, a version of an older run, or a change log that dropped old deletes.
+ * - When `full` is false, `changed` has the items that changed after the version, and `deleted`
+ *   has the ids that were deleted after it.
+ */
+export interface StorageChanges<T> {
+  /** The version of the storage that includes these changes. */
+  version: string;
+  /** True when `changed` has every item of the storage. */
+  full: boolean;
+  /** The items that changed, with their ids. */
+  changed: Array<[string, T]>;
+  /** The ids that were deleted. Empty when `full` is true. */
+  deleted: string[];
+}
+
 /** The metadata that a storage gives about itself. */
 export interface StorageMetadata {
   type: "memory" | "api" | "hybrid" | "synced" | "custom";

package/src/procedures/core/array.ts

@@ -10,6 +10,17 @@ import { anyOutput, arrayOutput, booleanOutput, numberOutput } from "./outputs.j
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";
 import { PURE_EFFECTS, withEffects } from "../effects.js";
+import { isPlainObject } from "../ref.js";
+
+/**
+ * This function gives the own field `key` of an item, or undefined. A field of the prototype
+ * (`toString`, `constructor`) is not a field of the item: before, `count` with the key
+ * `toString` counted each item (catalog test, roadmap R29, as R6 for the object procedures).
+ */
+function fieldOf(item: unknown, key: string): unknown {
+  if (item === null || item === undefined) return undefined;
+  return Object.hasOwn(Object(item), key) ? (item as Record<string, unknown>)[key] : undefined;
+}
 
 // =============================================================================
 // First Procedure
@@ -209,8 +220,8 @@ const sortProcedure: SortProcedure = defineProcedure({
     const direction = input.desc ? -1 : 1;
 
     return items.sort((a, b) => {
-      let aVal = input.key ? (a as Record<string, unknown>)[input.key] : a;
-      let bVal = input.key ? (b as Record<string, unknown>)[input.key] : b;
+      let aVal = input.key ? fieldOf(a, input.key) : a;
+      let bVal = input.key ? fieldOf(b, input.key) : b;
 
       if (typeof aVal === "string" && typeof bVal === "string") {
         return aVal.localeCompare(bVal) * direction;
@@ -291,10 +302,47 @@ interface UniqueInput {
 }
 
 const UniqueInputSchema = z.object({
-  items: z.array(z.unknown()).describe("The array"),
-  key: z.string().optional().describe("The key (a field name of the items)"),
+  items: z.array(z.unknown()).describe("The array. Equal JSON values are duplicates: objects and arrays compare by value."),
+  key: z.string().optional().describe("The key (a field name of the items). The values of the field compare by value."),
 });
 
+/**
+ * This function gives a function that makes a text key for a value: two equal JSON values get
+ * the same key. An array compares by its items in order, and a plain object by its own fields in
+ * any order. A number and its string get different keys. Another object (a `Date`, a `Map`) and
+ * a symbol compare by identity.
+ */
+function valueKeys(): (value: unknown) => string {
+  const identities = new Map<unknown, number>();
+  const identity = (value: unknown): string => {
+    let id = identities.get(value);
+    if (id === undefined) {
+      id = identities.size;
+      identities.set(value, id);
+    }
+    return `#${id}`;
+  };
+  const keyOf = (value: unknown, parents: Set<unknown>): string => {
+    if (typeof value === "string") return JSON.stringify(value);
+    // -0 and 0 are one value, and NaN is one value, as in a Set
+    if (typeof value === "number") return Object.is(value, -0) ? "0" : String(value);
+    if (typeof value === "bigint") return `${value}n`;
+    if (value === null || value === undefined || typeof value === "boolean") return String(value);
+    // A cycle is not JSON: its object compares by identity
+    if (parents.has(value) || (!Array.isArray(value) && !isPlainObject(value))) return identity(value);
+    parents.add(value);
+    const text = Array.isArray(value)
+      ? `[${value.map((item) => keyOf(item, parents)).join(",")}]`
+      : `{${Object.keys(value)
+          .sort()
+          .map((field) => `${JSON.stringify(field)}:${keyOf(value[field], parents)}`)
+          .join(",")}}`;
+    parents.delete(value);
+    return text;
+  };
+  return (value) => keyOf(value, new Set());
+}
+
 type UniqueProcedure = Procedure<UniqueInput, unknown[], { description: string; tags: string[] }>;
 
 const uniqueProcedure: UniqueProcedure = defineProcedure({
@@ -302,20 +350,19 @@ const uniqueProcedure: UniqueProcedure = defineProcedure({
   input: UniqueInputSchema,
   output: arrayOutput("The items without duplicates"),
   metadata: {
-    description: "Remove duplicate values (optionally by key)",
+    description: "Remove duplicate values (optionally by key). It compares by value and keeps the first item of each value.",
     tags: ["core", "array"],
   },
   handler: async (input: UniqueInput): Promise<unknown[]> => {
-    if (input.key) {
-      const seen = new Set<unknown>();
-      return input.items.filter((item) => {
-        const val = (item as Record<string, unknown>)[input.key!];
-        if (seen.has(val)) return false;
-        seen.add(val);
-        return true;
-      });
-    }
-    return [...new Set(input.items)];
+    // Before, objects compared by reference, so two equal objects both stayed (catalog test, R29)
+    const keyOf = valueKeys();
+    const seen = new Set<string>();
+    return input.items.filter((item) => {
+      const key = keyOf(input.key ? fieldOf(item, input.key) : item);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
   },
 });
 
@@ -346,11 +393,13 @@ const groupByProcedure: GroupByProcedure = defineProcedure({
   handler: async (input: GroupByInput): Promise<Record<string, unknown[]>> => {
     const result: Record<string, unknown[]> = {};
     for (const item of input.items) {
-      const keyVal = String((item as Record<string, unknown>)[input.key]);
-      if (!result[keyVal]) {
-        result[keyVal] = [];
+      const keyVal = String(fieldOf(item, input.key));
+      // Only an own group: before, a group "constructor" or "toString" found the function of the
+      // prototype, and push failed (catalog test, roadmap R29)
+      if (!Object.hasOwn(result, keyVal)) {
+        Object.defineProperty(result, keyVal, { value: [], writable: true, enumerable: true, configurable: true });
       }
-      result[keyVal].push(item);
+      result[keyVal]!.push(item);
     }
     return result;
   },
@@ -611,8 +660,8 @@ interface FilterInput {
   value?: unknown | undefined;
   /** Values to match (any of these) */
   values?: unknown[] | undefined;
-  /** Match mode: 'equals', 'not', 'in', 'notIn', 'contains', 'startsWith', 'endsWith' */
-  match?: 'equals' | 'not' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | undefined;
+  /** Match mode: 'equals', 'not', 'in', 'notIn', 'contains', 'startsWith', 'endsWith', 'gt', 'gte', 'lt', 'lte' */
+  match?:'equals' | 'not' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | undefined;
   /** Invert the filter */
   invert?: boolean | undefined;
 }
@@ -622,7 +671,7 @@ const FilterInputSchema = z.object({
   key: z.string().optional().describe("Property to match against"),
   value: z.unknown().optional().describe("Value to match (equality check)"),
   values: z.array(z.unknown()).optional().describe("Values to match (any of these)"),
-  match: z.enum(["equals", "not", "in", "notIn", "contains", "startsWith", "endsWith", "gt", "gte", "lt", "lte"]).optional().describe("Match mode: 'equals', 'not', 'in', 'notIn', 'contains', 'startsWith', 'endsWith'"),
+  match: z.enum(["equals", "not", "in", "notIn", "contains", "startsWith", "endsWith", "gt", "gte", "lt", "lte"]).optional().describe("Match mode (default 'equals'): 'equals' and 'not' compare with value, 'in' and 'notIn' with values. 'contains', 'startsWith' and 'endsWith' compare strings. 'gt', 'gte', 'lt' and 'lte' compare numbers."),
   invert: z.boolean().optional().describe("Invert the filter"),
 });
 
@@ -640,7 +689,7 @@ const filterProcedure: FilterProcedure = defineProcedure({
     const { items, key, value, values, match = 'equals', invert = false } = input;
 
     const predicate = (item: unknown): boolean => {
-      const itemValue = key ? (item as Record<string, unknown>)[key] : item;
+      const itemValue = key ? fieldOf(item, key) : item;
 
       let result: boolean;
       switch (match) {
@@ -716,10 +765,7 @@ const whereProcedure: WhereProcedure = defineProcedure({
   },
   handler: async (input: WhereInput): Promise<unknown[]> => {
     const { items, where } = input;
-    return items.filter((item) => {
-      const obj = item as Record<string, unknown>;
-      return Object.entries(where).every(([key, value]) => obj[key] === value);
-    });
+    return items.filter((item) => Object.entries(where).every(([key, value]) => fieldOf(item, key) === value));
   },
 });
 
@@ -750,7 +796,7 @@ const pluckProcedure: PluckProcedure = defineProcedure({
     tags: ["core", "array", "transform"],
   },
   handler: async (input: PluckInput): Promise<unknown[]> => {
-    return input.items.map((item) => (item as Record<string, unknown>)[input.key]);
+    return input.items.map((item) => fieldOf(item, input.key));
   },
 });
 
@@ -785,7 +831,9 @@ const arrPickProcedure: ArrPickProcedure = defineProcedure({
       const obj = item as Record<string, unknown>;
       const result: Record<string, unknown> = {};
       for (const key of input.keys) {
-        if (key in obj) {
+        // Only own fields, as client.pick: before, "toString" picked a function of the prototype
+        // (catalog test, roadmap R29)
+        if (Object.hasOwn(obj, key)) {
           result[key] = obj[key];
         }
       }
@@ -881,7 +929,7 @@ const partitionProcedure: PartitionProcedure = defineProcedure({
     const falsy: unknown[] = [];
 
     for (const item of input.items) {
-      const itemValue = (item as Record<string, unknown>)[input.key];
+      const itemValue = fieldOf(item, input.key);
       const matches = input.value !== undefined ? itemValue === input.value : Boolean(itemValue);
       if (matches) {
         truthy.push(item);
@@ -929,7 +977,7 @@ const countProcedure: CountProcedure = defineProcedure({
     }
 
     return input.items.filter((item) => {
-      const itemValue = (item as Record<string, unknown>)[input.key!];
+      const itemValue = fieldOf(item, input.key!);
       return input.value !== undefined ? itemValue === input.value : Boolean(itemValue);
     }).length;
   },

package/src/procedures/core/index.ts

@@ -84,9 +84,16 @@ const ConditionalInputSchema = z.looseObject({
 const LogicInputSchema = z.looseObject({
   values: z.array(z.unknown()).describe("The operands, in order: values or calls. The evaluation stops at the deciding value."),
 });
-const NotInputSchema = z.looseObject({ value: operand("The value or call to negate") });
+// not, all, any and none take values (roadmap R29, the owner's choice). They do not run a call in
+// their operands: a call is an object, thus truthy. In a program, the calls of their input run
+// first, as for each procedure that is not control flow. client.and and client.or run calls.
+const NotInputSchema = z.looseObject({
+  value: operand("The value to negate. This procedure does not run a call: a call is an object, thus truthy."),
+});
 const VariadicBoolInputSchema = z.looseObject({
-  values: z.array(z.unknown()).describe("The values or calls to evaluate"),
+  values: z
+    .array(z.unknown())
+    .describe("The values to evaluate. This procedure does not run calls: a call is an object, thus truthy. client.and and client.or run calls."),
 });
 const MapInputSchema = z.looseObject({
   items: operand("The array, or a call that gives it"),
@@ -582,6 +589,10 @@ const mapProcedure: MapProcedure = defineProcedure({
     // map is a control-flow procedure: its operands arrive raw, and it runs them here.
     // Before, the handler only returned the raw items, so their refs never ran and no
     // function was applied.
+    if (input.fn !== undefined && !isAnyProcedureRef(input.fn)) {
+      // Before, a fn that was not a call was ignored without a word (roadmap R4)
+      throw new Error("client.map: fn must be one call ({ $proc, input }), or absent");
+    }
     const outer = scopeOf(input);
     const items = await hydrateItems(input.items, ctx, outer);
     if (!isAnyProcedureRef(input.fn) || !ctx?.client) {
@@ -625,6 +636,10 @@ const reduceProcedure: ReduceProcedure = defineProcedure({
     tags: controlFlowTags("collection"),
   },
   handler: async (input: ReduceInput, ctx?: ProcedureContext): Promise<unknown> => {
+    if (input.fn !== undefined && !isAnyProcedureRef(input.fn)) {
+      // Before, a fn that was not a call was ignored without a word (roadmap R4)
+      throw new Error("client.reduce: fn must be one call ({ $proc, input }), or absent");
+    }
     if (!ctx?.client) {
       return input.accumulated ?? input.initial;
     }

package/src/procedures/core/logic.ts

@@ -184,7 +184,7 @@ export const orMetadata: LogicMetadata = {
  * Metadata for the NOT operator.
  */
 export const notMetadata: LogicMetadata = {
-  description: "Logical NOT",
+  description: "Logical NOT of a value",
   tags: ["core", "logic"],
   arity: "unary",
   commutative: false, // n/a for unary

package/src/procedures/core/math.ts

@@ -151,10 +151,14 @@ const modProcedure: ModProcedure = defineProcedure({
   input: ModInputSchema,
   output: numberOutput("The remainder of a divided by b"),
   metadata: {
-    description: "Modulo (remainder of a / b)",
+    description: "Modulo (remainder of a / b). It refuses b = 0, as client.divide does.",
     tags: ["core", "math"],
   },
   handler: async (input: ModInput): Promise<number> => {
+    // Before, b = 0 gave NaN, and client.divide refused it (catalog test, roadmap R29)
+    if (input.b === 0) {
+      throw new Error("Division by zero");
+    }
     return input.a % input.b;
   },
 });