@procedures/collections 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @procedures/collections
 
+## 0.5.0
+
+### Minor Changes
+
+- bc74091: The storages agree on the contract of `CollectionStorage`. `InMemoryStorage` changes in three points:
+  
+  - It keeps copies. Each write takes a copy of the value (`structuredClone`), and each read gives a new copy. Before, it kept the values themselves. The option `copies: false` gives the old behavior for a caller that changes no value.
+  - A delta of `getChangesSince` follows the order of the last change of each id. Before, it followed the first write of each id.
+  - After `close()`, each operation rejects with an error that says "closed", and a second `close()` does nothing. Before, `close()` emptied the storage, and the storage kept working.
+  
+  The contract suite of `@procedures/collections/testing` has no options `copies` and `nullValues` now. It tests the copies, a stored `null`, the order of each delta and the operations after `close()` for each storage. The helper `byId` is removed.
+- 89481b0: The contract of `CollectionStorage` has the optional method `getIds()`. It gives the ids in the order of the entries, and it does not read or copy the values.
+  
+  - `InMemoryStorage.getIds()` gives the keys of its map, without a `structuredClone` of the values.
+  - The contract suite of `@procedures/collections/testing` tests `getIds()`: the order, a new array for each call, the ids of `getEntries()`, and the rejection after `close()`. A storage without `getIds()` skips the case.
+
+## 0.4.0
+
+### Minor Changes
+
+- 0abf2ec: The new test-only entry `@procedures/collections/testing` holds one contract suite for `CollectionStorage`: `describeCollectionStorageContract(name, { create, createWithMaxTombstones, copies, nullValues }, { describe, it })`. It tests the reads, the writes, the batches, the order of the entries, the JSON values, `getChangesSince` and its versions, `flush`, `getMetadata`, `close` and the errors. A random sequence of writes runs against a `Map`. The suite imports no test framework, so the runtime entries never load vitest. `InMemoryStorage`, `SqliteStorage`, `ApiStorage` and `HybridStorage` run it.
+  
+  The suite found two differences, and the contract fixes them:
+  
+  - An error of a `find` predicate of `InMemoryStorage` threw at once. Each method of a storage gives a promise, so each method of `InMemoryStorage` is now `async`, and an error is a rejected promise.
+  - `getMetadata().size` of `HybridStorage` was the size of the local copy, which `remote-only` keeps empty. It is now the result of `size()`. The new `stats.localSize` gives the size of the local copy.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -85,6 +85,9 @@ interface CollectionStorage<T> {
   // Read Operations
   get(id: string): Promise<T | undefined>;
   getAll(): Promise<T[]>;
+  getEntries?(): Promise<Array<[string, T]>>;
+  getIds?(): Promise<string[]>;
+  getChangesSince?(since?: string): Promise<StorageChanges<T>>;
   find(predicate: (item: T) => boolean): Promise<T[]>;
   has(id: string): Promise<boolean>;
   size(): Promise<number>;
@@ -105,20 +108,67 @@ interface CollectionStorage<T> {
 }
 ```
 
+Each storage agrees on these points:
+
+- A storage keeps a copy of each value that a write takes, and each read gives a new copy. A change of a written or a read value does not change the stored item.
+- A stored `null` reads back as `null`. A missing id reads back as `undefined`.
+- The entries keep the order of the first set of each id, as a `Map` does.
+- A delta of `getChangesSince` follows the order of the last change of each id. A full result follows the order of the entries.
+- `getIds()` gives the ids in the order of the entries, and it does not read or copy the values. A storage that cannot give the ids cheaply does not have it. `HybridStorage` uses it for a full sync.
+- After `close()`, each operation rejects with an error whose message says "closed". A second `close()` does nothing.
+
+### The contract suite: `@procedures/collections/testing`
+
+The test-only entry `@procedures/collections/testing` holds one test suite for the contract of `CollectionStorage`. A storage runs it with a factory:
+
+```typescript
+import { describe, it } from "vitest";
+import { describeCollectionStorageContract, type ContractItem } from "@procedures/collections/testing";
+
+describeCollectionStorageContract(
+  "MyStorage",
+  {
+    create: () => new MyStorage<ContractItem>(),
+    createWithMaxTombstones: (max) => new MyStorage<ContractItem>({ maxTombstones: max }),
+  },
+  { describe, it },
+);
+```
+
+- The suite tests the reads, the writes and the batches, the order of the entries, `getIds`, and the results as new arrays.
+- It tests the copies, the JSON values with `null`, and the writes at the same time.
+- It tests `getChangesSince` with its versions and its order, `flush`, `getMetadata`, `close` and the errors.
+- A case for an optional method skips a storage without the method.
+- A random sequence of writes runs against a `Map`. Each saved version must give the right changes, in the order of the last change of each id.
+- The suite imports no test framework. The caller gives `describe` and `it`, and a failed check throws `ContractViolation`. The runtime entries do not import this entry.
+- The suite has no option that hides a difference of a storage. Before, the options `copies` and `nullValues` declared the differences, and the suite sorted each delta.
+
+| Storage | Package | Notes |
+|---|---|---|
+| `InMemoryStorage` | `@procedures/collections` | It copies with `structuredClone`. The run with `copies: false` skips only the case of the copies. |
+| `SqliteStorage` (each engine, in memory and in a file) | `@procedures/sqlite` | It keeps JSON text, so it gives copies. |
+| `ApiStorage` | `@procedures/store` | It reads `{ found, value }` from the procedure `get`, so a stored `null` stays `null`. It has no `getIds`. |
+| `HybridStorage` (each mode, and a queue in IndexedDB) | `@procedures/store` | It has no `getChangesSince`. |
+
 ## Storage Backends
 
-### MemoryStorage
+### InMemoryStorage
 
 Fast, in-memory storage using JavaScript Map:
 
 ```typescript
-import { MemoryStorage } from "@procedures/collections";
+import { InMemoryStorage } from "@procedures/collections";
 
-const storage = new MemoryStorage<User>();
+const storage = new InMemoryStorage<User>();
 await storage.set("user-1", { name: "Alice", age: 30 });
 const user = await storage.get("user-1");
 ```
 
+- The storage keeps a copy of each written value, and each read gives a new copy (`structuredClone`). A `Date` stays a `Date`. A function in a value makes the write reject.
+- The option `copies: false` turns the copies off: the storage keeps the values themselves, and the reads give them. It is faster. Give it only when no caller changes a value after a write or a read.
+- `getIds()` gives the ids without a copy of the values.
+- `close()` drops the items. After it, each operation rejects, and the methods of the `Map` interface (`keys()`, `values()`, `entries()`, `forEach()`) throw.
+
 ### ApiStorage
 
 Remote storage via RPC client: