@procedures/store 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @procedures/store
 
+## 0.5.0
+
+### Minor Changes
+
+- 89481b0: A full pull of `HybridStorage` reads the local ids with `getIds()` of the local copy. Before, it read each local entry only for the ids, and `InMemoryStorage` copied each value (`structuredClone`) for it. A local copy without `getIds()` gives its entries, as before.
+  
+  - `HybridStorage.getIds()` gives the ids of the local copy, or of the remote in `remote-only` mode.
+  - A new nightly benchmark measures a full pull of 1,000 items with and without `getIds()`. In one CI run, the mean time went from 15.3 ms to 10.7 ms.
+- bc74091: `ApiStorage` and `HybridStorage` agree with the contract of `CollectionStorage`:
+  
+  - `ApiStorage.get()` asks the procedure `collections.<name>.get` for `{ found, value }`. A stored `null` reads back as `null`. Before, it read back as `undefined`. A custom `service` or `get` operation gets the input `{ id }`, as before.
+  - `HybridStorage` takes a copy of each written value for the local copy, the queue and the remote. Before, a change of a value after a `set()` in the mode `write-back` changed the queued write.
+  - After `close()`, each operation of `ApiStorage` and `HybridStorage` rejects with an error that says "closed", and a second `close()` does nothing. `HybridStorage.close()` waits for the operations, the mode switch and the syncs that run. A `close()` before the first sync makes no remote call.
+  - After `close()`, `SyncedProcedureRegistry.register()` and `unregister()` change only the registry in memory, and a second `close()` does nothing. `close()` waits for the auto-sync that runs.
+
+### Patch Changes
+
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [a47bee6]
+- Updated dependencies [bc74091]
+- Updated dependencies [bc74091]
+- Updated dependencies [89481b0]
+  - @procedures/client@0.5.0
+  - @procedures/collections@0.5.0
+
+## 0.4.0
+
+### Patch 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.
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [0abf2ec]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/collections@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -81,6 +81,23 @@ These parts moved here from `@procedures/client` (roadmap 3.2):
 
 An import of `@procedures/store/register` registers its procedures. An import of the package root registers nothing.
 
+### The contract of `ApiStorage` and `HybridStorage`
+
+The contract suite of `@procedures/collections/testing` tests `ApiStorage`, and `HybridStorage` in each mode. The two storages agree with `InMemoryStorage` and `SqliteStorage`:
+
+- **Copies.** A change of a written or a read value does not change the stored item. `HybridStorage` takes a copy of each written value for the local copy, the queue and the remote. The values that `ApiStorage` sends and reads go through the transport.
+- **`null`.** A stored `null` reads back as `null`. `ApiStorage.get()` sends `{ id, found: true }` to the procedure `collections.<name>.get`. The procedure then gives `{ found, value }` in one call.
+- **The order of a delta.** `getChangesSince()` follows the order of the last change of each id.
+- **The ids.** `HybridStorage.getIds()` gives the ids in the order of the entries. `ApiStorage` has no `getIds()`.
+- **After `close()`.** Each operation rejects with an error whose message says "closed". A second `close()` does nothing.
+
+Notes:
+
+- A custom `service` or a custom `get` operation gets the input `{ id }`, as before. Its `null` reads back as `undefined`.
+- A server before `found` ignores it and gives the item. Then a stored `null` reads back as `undefined`, as before.
+- `HybridStorage.close()` waits for the operations, the switch and the syncs that run. Then it sends the queue, and it closes the remote and the local copy.
+- `SyncedProcedureRegistry.close()` closes its storage. After it, `register()` and `unregister()` change only the registry in memory.
+
 ## The modes of `HybridStorage`
 
 `HybridStorage` keeps a local copy of a remote collection storage. It has four modes, and `setMode()` changes the mode while the storage operates.
@@ -136,7 +153,9 @@ await users.setMode("write-through"); // The switch sends the queue, then syncs
 - With a durable local copy, a new storage in `local-only` mode reads the items of the last run. It makes no remote call.
 - Give a durable `queueStore` with a durable local copy. A restart applies the loaded queue to the local copy again, and the result does not change.
 - The first sync after a restart reads all remote items. It removes each local item that the remote deleted and that no queued write changes.
-- `close()` closes the local copy. A durable local copy keeps its items.
+- A full sync reads the local ids with `getIds()` of the local copy. `InMemoryStorage` and `SqliteStorage` give the ids without a copy of the values. A local copy without `getIds()` gives its entries.
+- `HybridStorage.getIds()` gives the ids of the local copy, or of the remote in `remote-only` mode.
+- `close()` closes the local copy and the remote. A durable local copy keeps its items. A remote stays open when its own `close()` leaves it open, as `ApiStorage.close()` leaves the server.
 
 ```ts
 import { ApiStorage, HybridStorage } from "@procedures/store";
@@ -164,6 +183,8 @@ const users = new HybridStorage(new ApiStorage(client, { collection: "users" }),
 
 `ProcedureServer.useStorage(name, storage, { drain: true, close: true })` first starts `flush()` of the old storage. Then it uses the new storage and closes the old one. When the flush fails, the old storage stays.
 
+`ProcedureServer.stop()` closes each storage one time and removes the storages from the server. A closed storage rejects each operation. Before the server starts again, give it new storages with `useStorage()`.
+
 ### The mode of a synced registry
 
 `createSyncedRegistry({ type: "hybrid", client, mode })` takes the first mode. `setMode()` of the registry changes the mode of its storage.