@procedures/collections 0.2.3 → 0.4.0

package/src/storage/memory.ts

@@ -5,7 +5,22 @@
  * All operations return Promises for interface consistency.
  */
 
-import type { CollectionStorage, StorageMetadata } from "./interface.js";
+import type { CollectionStorage, StorageChanges, StorageMetadata } from "./interface.js";
+
+/** Options of an in-memory storage. */
+export interface InMemoryStorageOptions {
+  /**
+   * The number of deletes that the change log keeps (roadmap R28). After more deletes, the log
+   * drops the oldest ones, and `getChangesSince` of an older version gives all items.
+   * @default 10000
+   */
+  maxTombstones?: number;
+}
+
+/** A new epoch: a version of another storage, or of a closed one, does not match it. */
+function newEpoch(): string {
+  return Math.random().toString(36).slice(2, 10);
+}
 
 /**
  * In-memory storage backed by JavaScript Map.
@@ -15,6 +30,8 @@ import type { CollectionStorage, StorageMetadata } from "./interface.js";
  * - No persistence (data lost on restart)
  * - Memory-bound (limited by available RAM)
  * - Returns Promises for API consistency with remote storage
+ * - Each error is a rejected promise: an error of a `find` predicate does not throw at once
+ * - A change log: `getChangesSince(version)` gives the changes after a version (roadmap R28)
  *
  * @example
  * ```typescript
@@ -26,76 +43,120 @@ import type { CollectionStorage, StorageMetadata } from "./interface.js";
 export class InMemoryStorage<T> implements CollectionStorage<T> {
   private data = new Map<string, T>();
 
+  // The change log (roadmap R28). Each write gets the next number of `seq`. A version is
+  // `<epoch>:<seq>`.
+  private epoch = newEpoch();
+  private seq = 0;
+  /** The number of the last write of each id that has an item */
+  private readonly changedAt = new Map<string, number>();
+  /** The number of the delete of each id that has no item, the oldest first (the tombstones) */
+  private readonly deletedAt = new Map<string, number>();
+  /** The log does not know the deletes at or below this number: they were dropped */
+  private floor = 0;
+  private readonly maxTombstones: number;
+
+  constructor(options: InMemoryStorageOptions = {}) {
+    this.maxTombstones = Math.max(0, options.maxTombstones ?? 10_000);
+  }
+
   //
   // ═══ Read Operations ═══
   //
 
-  get(id: string): Promise<T | undefined> {
-    return Promise.resolve(this.data.get(id));
+  async get(id: string): Promise<T | undefined> {
+    return this.data.get(id);
+  }
+
+  async getAll(): Promise<T[]> {
+    return Array.from(this.data.values());
   }
 
-  getAll(): Promise<T[]> {
-    return Promise.resolve(Array.from(this.data.values()));
+  async getEntries(): Promise<Array<[string, T]>> {
+    return Array.from(this.data.entries());
+  }
+
+  /**
+   * The changes after a version (roadmap R28). A version of another storage, of a closed
+   * storage, or older than the dropped deletes gives all items (`full: true`).
+   */
+  async getChangesSince(since?: string): Promise<StorageChanges<T>> {
+    const version = `${this.epoch}:${this.seq}`;
+    const from = this.parseVersion(since);
+    if (from === undefined || from < this.floor) {
+      return { version, full: true, changed: Array.from(this.data.entries()), deleted: [] };
+    }
+    const changed: Array<[string, T]> = [];
+    for (const [id, at] of this.changedAt) {
+      if (at > from) changed.push([id, this.data.get(id) as T]);
+    }
+    const deleted: string[] = [];
+    for (const [id, at] of this.deletedAt) {
+      if (at > from) deleted.push(id);
+    }
+    return { version, full: false, changed, deleted };
   }
 
-  find(predicate: (item: T) => boolean): Promise<T[]> {
+  async find(predicate: (item: T) => boolean): Promise<T[]> {
     const results: T[] = [];
     for (const item of this.data.values()) {
       if (predicate(item)) {
         results.push(item);
       }
     }
-    return Promise.resolve(results);
+    return results;
   }
 
-  has(id: string): Promise<boolean> {
-    return Promise.resolve(this.data.has(id));
+  async has(id: string): Promise<boolean> {
+    return this.data.has(id);
   }
 
-  size(): Promise<number> {
-    return Promise.resolve(this.data.size);
+  async size(): Promise<number> {
+    return this.data.size;
   }
 
   //
   // ═══ Write Operations ═══
   //
 
-  set(id: string, value: T): Promise<void> {
+  async set(id: string, value: T): Promise<void> {
     this.data.set(id, value);
-    return Promise.resolve();
+    this.noteSet(id);
   }
 
-  delete(id: string): Promise<boolean> {
-    return Promise.resolve(this.data.delete(id));
+  async delete(id: string): Promise<boolean> {
+    const existed = this.data.delete(id);
+    if (existed) this.noteDelete(id);
+    return existed;
   }
 
-  clear(): Promise<void> {
+  async clear(): Promise<void> {
+    for (const id of this.data.keys()) this.noteDelete(id);
     this.data.clear();
-    return Promise.resolve();
   }
 
   //
   // ═══ Bulk Operations ═══
   //
 
-  setBatch(items: Array<[string, T]>): Promise<void> {
+  async setBatch(items: Array<[string, T]>): Promise<void> {
     for (const [id, value] of items) {
       this.data.set(id, value);
+      this.noteSet(id);
     }
-    return Promise.resolve();
   }
 
-  deleteBatch(ids: string[]): Promise<number> {
+  async deleteBatch(ids: string[]): Promise<number> {
     let deleted = 0;
     for (const id of ids) {
       if (this.data.delete(id)) {
+        this.noteDelete(id);
         deleted++;
       }
     }
-    return Promise.resolve(deleted);
+    return deleted;
   }
 
-  getBatch(ids: string[]): Promise<Map<string, T>> {
+  async getBatch(ids: string[]): Promise<Map<string, T>> {
     const result = new Map<string, T>();
     for (const id of ids) {
       const value = this.data.get(id);
@@ -103,32 +164,37 @@ export class InMemoryStorage<T> implements CollectionStorage<T> {
         result.set(id, value);
       }
     }
-    return Promise.resolve(result);
+    return result;
   }
 
   //
   // ═══ Lifecycle & Metadata ═══
   //
 
-  close(): Promise<void> {
+  async close(): Promise<void> {
     // No cleanup needed for in-memory storage
     this.data.clear();
-    return Promise.resolve();
+    // A new epoch: a version of the closed storage gives all items
+    this.changedAt.clear();
+    this.deletedAt.clear();
+    this.epoch = newEpoch();
+    this.seq = 0;
+    this.floor = 0;
   }
 
-  getMetadata(): Promise<StorageMetadata> {
+  async getMetadata(): Promise<StorageMetadata> {
     // Rough memory estimation:
     // Each entry has ~overhead of 100 bytes (key string + Map entry overhead)
     const estimatedEntrySize = 100;
     const memoryUsage = this.data.size * estimatedEntrySize;
 
-    return Promise.resolve({
+    return {
       type: "memory",
       size: this.data.size,
       stats: {
         memoryUsage,
       },
-    });
+    };
   }
 
   //
@@ -177,4 +243,34 @@ export class InMemoryStorage<T> implements CollectionStorage<T> {
   [Symbol.iterator](): IterableIterator<[string, T]> {
     return this.data.entries();
   }
+
+  //
+  // ═══ The change log ═══
+  //
+
+  private noteSet(id: string): void {
+    this.changedAt.set(id, ++this.seq);
+    this.deletedAt.delete(id);
+  }
+
+  private noteDelete(id: string): void {
+    this.changedAt.delete(id);
+    // Delete, then set: the tombstone goes to the end of the order (the newest)
+    this.deletedAt.delete(id);
+    this.deletedAt.set(id, ++this.seq);
+    while (this.deletedAt.size > this.maxTombstones) {
+      const [oldest, at] = this.deletedAt.entries().next().value as [string, number];
+      this.deletedAt.delete(oldest);
+      this.floor = Math.max(this.floor, at);
+    }
+  }
+
+  /** The number of a version of this storage, or undefined for another or an unknown version. */
+  private parseVersion(since: string | undefined): number | undefined {
+    if (since === undefined) return undefined;
+    const separator = since.lastIndexOf(":");
+    if (separator < 0 || since.slice(0, separator) !== this.epoch) return undefined;
+    const at = Number(since.slice(separator + 1));
+    return Number.isInteger(at) && at >= 0 && at <= this.seq ? at : undefined;
+  }
 }

package/src/testing/check.ts

@@ -0,0 +1,86 @@
+/**
+ * The checks of the contract suite. The suite does not import a test framework, so a runtime
+ * entry of this package never loads one. A failed check throws `ContractViolation`.
+ */
+
+/** The error of a failed check of the contract suite. */
+export class ContractViolation extends Error {
+  override readonly name = "ContractViolation";
+}
+
+/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */
+export function show(value: unknown): string {
+  if (value === undefined) return "undefined";
+  try {
+    return JSON.stringify(value, (_key, item: unknown) => (item instanceof Map ? { Map: [...item.entries()] } : item === undefined ? "<undefined>" : item));
+  } catch {
+    return String(value);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
+ * are equal when they have the same keys with equal values, in any order.
+ */
+export function deepEqual(actual: unknown, expected: unknown): boolean {
+  if (Object.is(actual, expected)) return true;
+  if (actual instanceof Map && expected instanceof Map) {
+    if (actual.size !== expected.size) return false;
+    for (const [key, value] of actual) {
+      if (!expected.has(key) || !deepEqual(value, expected.get(key))) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(actual) && Array.isArray(expected)) {
+    return actual.length === expected.length && actual.every((item, index) => deepEqual(item, expected[index]));
+  }
+  if (isPlainObject(actual) && isPlainObject(expected)) {
+    const keys = Object.keys(actual);
+    if (keys.length !== Object.keys(expected).length) return false;
+    return keys.every((key) => Object.prototype.hasOwnProperty.call(expected, key) && deepEqual(actual[key], expected[key]));
+  }
+  return false;
+}
+
+/** This function throws `ContractViolation` when the two values are not deeply equal. */
+export function same(actual: unknown, expected: unknown, what: string): void {
+  if (!deepEqual(actual, expected)) {
+    throw new ContractViolation(`${what}: expected ${show(expected)}, got ${show(actual)}`);
+  }
+}
+
+/** This function throws `ContractViolation` when the condition is false. */
+export function holds(condition: boolean, what: string): void {
+  if (!condition) throw new ContractViolation(what);
+}
+
+/**
+ * This function starts an operation that must fail with a rejected promise, and gives the error.
+ * A synchronous throw breaks the contract too: each method of a storage gives a promise.
+ */
+export async function rejects(start: () => Promise<unknown>, what: string): Promise<unknown> {
+  let promise: Promise<unknown>;
+  try {
+    promise = start();
+  } catch (error) {
+    throw new ContractViolation(`${what}: the method threw at once (${show(error instanceof Error ? error.message : error)}), and did not give a rejected promise`);
+  }
+  holds(typeof promise?.then === "function", `${what}: the method did not give a promise`);
+  try {
+    await promise;
+  } catch (error) {
+    return error;
+  }
+  throw new ContractViolation(`${what}: the promise did not reject`);
+}
+
+/** The entries sorted by id, for a comparison where the order is not part of the contract. */
+export function byId<T>(entries: ReadonlyArray<readonly [string, T]>): Array<[string, T]> {
+  return [...entries].map(([id, value]): [string, T] => [id, value]).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}

package/src/testing/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@procedures/collections/testing`: the test-only entry of this package.
+ *
+ * This entry holds the contract suite of `CollectionStorage`. A storage package runs it in its
+ * tests with a factory of its storage. The entry imports no test framework: the caller gives
+ * `describe` and `it`. The runtime entries of the package do not import this entry.
+ */
+
+export {
+  collectionStorageContract,
+  describeCollectionStorageContract,
+  type CollectionStorageContractOptions,
+  type ContractCase,
+  type ContractItem,
+  type ContractStorage,
+  type ContractTestApi,
+  type ContractTestContext,
+} from "./storage-contract.js";
+export { ContractViolation, deepEqual } from "./check.js";