@procedures/collections 0.3.0 → 0.4.0

package/src/storage/memory.ts

@@ -30,6 +30,7 @@ function newEpoch(): string {
  * - 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
@@ -62,27 +63,27 @@ export class InMemoryStorage<T> implements CollectionStorage<T> {
   // ═══ 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);
   }
 
-  getAll(): Promise<T[]> {
-    return Promise.resolve(Array.from(this.data.values()));
+  async getAll(): Promise<T[]> {
+    return Array.from(this.data.values());
   }
 
-  getEntries(): Promise<Array<[string, T]>> {
-    return Promise.resolve(Array.from(this.data.entries()));
+  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`).
    */
-  getChangesSince(since?: string): Promise<StorageChanges<T>> {
+  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 Promise.resolve({ version, full: true, changed: Array.from(this.data.entries()), deleted: [] });
+      return { version, full: true, changed: Array.from(this.data.entries()), deleted: [] };
     }
     const changed: Array<[string, T]> = [];
     for (const [id, at] of this.changedAt) {
@@ -92,62 +93,59 @@ export class InMemoryStorage<T> implements CollectionStorage<T> {
     for (const [id, at] of this.deletedAt) {
       if (at > from) deleted.push(id);
     }
-    return Promise.resolve({ version, full: false, changed, deleted });
+    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);
     this.noteSet(id);
-    return Promise.resolve();
   }
 
-  delete(id: string): Promise<boolean> {
+  async delete(id: string): Promise<boolean> {
     const existed = this.data.delete(id);
     if (existed) this.noteDelete(id);
-    return Promise.resolve(existed);
+    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)) {
@@ -155,10 +153,10 @@ export class InMemoryStorage<T> implements CollectionStorage<T> {
         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);
@@ -166,14 +164,14 @@ 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();
     // A new epoch: a version of the closed storage gives all items
@@ -182,22 +180,21 @@ export class InMemoryStorage<T> implements CollectionStorage<T> {
     this.epoch = newEpoch();
     this.seq = 0;
     this.floor = 0;
-    return Promise.resolve();
   }
 
-  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,
       },
-    });
+    };
   }
 
   //

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";