@procedures/store 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @procedures/store
 
+## 0.15.0
+
+### Minor Changes
+
+- c7198ca: Breaking (roadmap CLI-16, decision D11): the collection writes take an optional expected version. This is its own MINOR of the client group (D13).
+  
+  New:
+  
+  - `collections.<name>.set` and `delete` take `expectedVersion`, and each item of `setBatch` takes `expectedVersion`. The value is the version of the current item that the write expects. `null` expects no item.
+  - A conflict changes nothing. The call fails with the new protocol code `VERSION_CONFLICT` (HTTP 409, not retryable). The metadata key `conflicts` (and the field `conflicts` of the HTTP body) has the current item and its version for each id.
+  - `StorageItemWriteOptions.expectedVersion` (`set`, `delete`) and `StorageBatchWriteOptions.expectedVersions` (`setBatch`) in both copies of `CollectionStorage`. `VersionConflictError`, `versionConflictsOf()` and the other helpers come from `@procedures/client/query`, `@procedures/client` and `@procedures/collections`.
+  - The option `versionOf` of `InMemoryStorage`, `SqliteStorage` and `MongoDocumentStorage` gives the version of an item. The test and the write are one step: synchronous in memory, one transaction in SQLite, the transaction or a compare-and-set on `_seq` in MongoDB. `MongoStorage` refuses a precondition.
+  - `ApiStorage` sends the expected versions to the collection procedures, and gives a `VERSION_CONFLICT` back as a `VersionConflictError`.
+  - `HybridStorage` sends the base version of each queued write as its expected version. A conflict of the remote goes to `conflictResolution`, as a conflict of a pull. The new option `sendBaseVersions: false` stops it.
+  - `ClientError.metadata` gives the metadata of the error response.
+  - The contract suite `@procedures/collections/testing` has the cases of the preconditions, and the option `createWithVersions`.
+  
+  The changes of behavior:
+  
+  - A storage must test a precondition, or refuse the write. A storage without `versionOf` refuses a write with an expected version with a `TypeError` whose code is `PRECONDITION_NOT_SUPPORTED`. The contract suite tests it for each storage.
+  - A `HybridStorage` with `versionOf` now sends the base version of each queued write. A queued write over a change of another writer got through before. Now the remote refuses it with `VERSION_CONFLICT`, and `conflictResolution` decides: `remote` drops the queued write, `merge` sends the merged item, `local` sends the write again over the current version, and `error` throws `ConflictError` and keeps the queue. The remote must test the precondition: a server storage without `versionOf` refuses each push.
+  - `ApiStorage`: a write without an expected version writes as before, and gets no `VERSION_CONFLICT`. Only a caller that gives an expected version, or a `HybridStorage` with `versionOf` over it, can get one.
+  - `HybridStorage` with `versionOf`: a queued write that won before can now get the conflict path. The opt-out is `new HybridStorage(remote, { versionOf, sendBaseVersions: false })`: the push sends no expected version, and the last write wins, as before. The default is the new behavior.
+  - A write without an expected version writes as before: the last write wins.
+  
+  Migration:
+  
+  - **Site.** No change. The site does not write collections.
+  - **MiniMongo.** No change for a storage or a `HybridStorage` without `versionOf`. A `HybridStorage` with `versionOf` over `ApiStorage` needs a server storage with the same `versionOf` (for example `new InMemoryStorage({ versionOf })`), or the option `sendBaseVersions: false`.
+  - **Graph.** Graph keeps last-write-wins first (D11): it gives no expected version, so nothing changes. `GraphDocsStorage` must refuse a write with an expected version until it tests one. Add the guard to its `set`, `delete` and `setBatch`, and run the contract suite: its first case tests the refusal. To adopt the version later, stamp a version field on the server, give the storage a `versionOf` that tests it in the write, and give the same `versionOf` to the `HybridStorage` of the client. Then add `createWithVersions` to the contract run.
+  - **jarvis.** No change: jarvis gives no expected version. A storage of jarvis that implements `CollectionStorage` must refuse a write with an expected version, as for Graph.
+  - **Other storages.** Each class that implements `CollectionStorage` reads the new options of `set`, `delete` and `setBatch`. It tests them in the write, or it rejects the write with `preconditionNotSupported()`. It never ignores them.
+
+### Patch Changes
+
+- Updated dependencies [c7198ca]
+  - @procedures/client@0.15.0
+  - @procedures/collections@0.15.0
+
+## 0.14.1
+
+### Patch Changes
+
+- fc968f6: Fixed: `@procedures/geo`, `@procedures/ics` and `@procedures/splay` import `@procedures/client/browser`, not the root of `@procedures/client` (CLI-39). The root also exports `HttpServerTransport`, which imports `http`. Thus a browser build with Vite found `http` and gave a warning. The exports of the packages do not change.
+  
+  New: each package that operates in a browser names its browser entries in the field `client.browser` of its `package.json`. A CI check bundles each of these entries for a browser with esbuild. The check fails when an import reaches a Node built-in, with or without the prefix `node:`. The root of `@procedures/client` joins the check after CLI-6. `@procedures/splay` joins it when `splay.bridge.info` reads its version without `node:fs/promises`.
+- 26a145d: The new entry `@procedures/store/browser` has the parts of the store that run in a browser (roadmap CLI-19). It exports `HybridStorage` with its errors, `ApiStorage`, `EventsChangeFeed` and all of `@procedures/store/indexeddb`. No module of the entry imports a module of Node. The entry does not have `FileProgramStore` or `FileQueueStore`, because they use `node:fs`.
+  
+  `HybridStorage`, `ApiStorage` and `EventsChangeFeed` import `@procedures/client/browser` and not the root of the client, because the root imports `http` and `ws`. The classes are the same as the classes of the root. PATCH: the change adds an entry, and nothing changes for the existing imports.
+- Updated dependencies [85999c1]
+- Updated dependencies [fc968f6]
+- Updated dependencies [dc7a462]
+- Updated dependencies [e091108]
+- Updated dependencies [073e4c3]
+- Updated dependencies [6969637]
+  - @procedures/client@0.14.1
+  - @procedures/collections@0.14.1
+
 ## 0.14.0
 
 ### Patch Changes

package/README.md

@@ -94,10 +94,13 @@ The contract suite of `@procedures/collections/testing` tests `ApiStorage`, and
 - **The queries.** `query(selector, { sort, skip, limit })` gives the result of `queryEntries()` of `@procedures/collections`. `ApiStorage.query()` sends the JSON selector to the procedure `collections.<name>.find`, so the server applies it.
 - **The patches.** `ApiStorage.patch(id, fields)` sends a patch to the procedure `collections.<name>.patch`. The server changes the item in one step. A patch is a JSON Merge Patch, or the operations `{ $set, $unset, $remove, $insert }`. An index of `$remove` or `$insert` is a position at the time of the patch. A client that works from an older read uses the version check of the collection, where the collection has one.
 - **The query policy.** The server applies the policy of its host to each `find`. The default policy does not permit `$regex`, and a `find` gets at most 1000 items.
+- **The preconditions.** `set`, `delete` and `setBatch` take an expected version of the current item (roadmap CLI-16). `ApiStorage` sends it to the collection procedures, and the storage of the server tests it. A conflict rejects with `VersionConflictError`, with the current items. A storage that cannot test it rejects the write.
 
 Notes:
 
 - A custom `service` or a custom `get` operation gets the input `{ id }`, as before. Its `null` reads back as `undefined`.
+- A custom `service` gets no expected version. `ApiStorage` rejects a write with one, so the precondition is not lost.
+- `HybridStorage` gives the expected version of a caller to its local copy. The default local copy gets the option `versionOf` of the storage. In `write-through` mode, the remote write gets it too. In `remote-only` mode, only the remote tests it.
 - A server before the procedure `find` answers `NOT_FOUND`. Then `ApiStorage.query()` reads the entries and applies the query in the client, with the same result.
 - `ApiStorage.find(predicate)` reads each item, because a function cannot go over the network. Use `query()` with a selector to filter on the server.
 - `HybridStorage.query()` reads the local copy, or the remote in `remote-only` mode. Its option `queryPolicy` goes to the storage under it.
@@ -192,6 +195,21 @@ const users = new HybridStorage(new ApiStorage(client, { collection: "users" }),
 - Without versions, a pull reads each local item without a queued write. It compares the JSON of the local item and the remote item.
 - The option `pullInterval` starts a periodic pull in the modes `write-through` and `write-back`. `close()` stops it.
 
+### The base versions on the server
+
+With `versionOf`, the push of a queued write sends its base version as the expected version (roadmap CLI-16, decision D11). The base version is the remote version of the id when the local write went in the queue. The server then refuses a write over a change of another writer.
+
+- The remote answers `VERSION_CONFLICT` with the current item. The storage gives the conflict to `conflictResolution`, as a conflict of a pull.
+- `remote`: the remote item replaces the local item, and the queued writes of the id go.
+- `merge`: `mergeFn` gives the item. A new queued write sends it, with the current version as its base.
+- `local`: the current version becomes the base, and the push sends the queued write again. It replaces the remote item.
+- `error`: the push throws `ConflictError` with the ids. The queue and the remote keep their items, and the next push tries again.
+- A remote item that is the value of the queued write is not a conflict. An earlier send reached the remote, and its answer was lost.
+- An id without a known base version gets no expected version. Its queued write wins, as before.
+- The remote must test the precondition: an `ApiStorage` of the collection procedures over a storage with the same `versionOf`. A remote that cannot test it refuses each push.
+- The option `sendBaseVersions: false` stops the expected versions. Then a queued write replaces the remote item, as before CLI-16.
+- A write of the mode `write-through` goes to the remote directly. It sends only the expected version of its caller.
+
 ### The clock, the backoff and the status
 
 The timers and the retries run on a clock: `Clock` of `@mark1russell7/service/clock`. A test gives `fakeClock` of `@mark1russell7/service/testing`, and the times are then exact.
@@ -286,6 +304,34 @@ const users = new HybridStorage(new ApiStorage(client, { collection: "users" }),
 
 `createSyncedRegistry({ type: "hybrid", client, mode })` takes the first mode. `setMode()` of the registry changes the mode of its storage.
 
+## The browser entry
+
+The entry `@procedures/store/browser` has the parts of the store that run in a browser (roadmap CLI-19). A page imports this entry and not the package root.
+
+- `HybridStorage`, its errors and its types.
+- `ApiStorage`, the remote storage over the collection procedures of a server.
+- `EventsChangeFeed`, the push feed of the remote changes.
+- All of `@procedures/store/indexeddb`: the IndexedDB stores and their fallbacks in memory.
+
+No module of the entry imports a module of Node. The modules import `@procedures/client/browser` and not the root of the client, because the root imports `http` and `ws`. The test `src/browser.test.ts` examines the imports of each module of the entry. The entry is in `client.browser` of `package.json`, so the CI check of the browser entries (`scripts/check-browser-entries.mjs`) bundles it for a browser too.
+
+The entry does not have these parts:
+
+- `FileProgramStore` and `FileQueueStore`. They use `node:fs`.
+- The procedures, the synced registry and the serialization. They import the root of the client. They are in the package root, for Node.
+
+An import of the entry registers nothing. Its classes are the same as the classes of the package root.
+
+```ts
+import { ApiStorage, EventsChangeFeed, HybridStorage, IndexedDbQueueStore, IndexedDbSyncStateStore } from "@procedures/store/browser";
+
+const users = new HybridStorage(new ApiStorage(client, { collection: "users" }), {
+  queueStore: new IndexedDbQueueStore("users-queue"),
+  syncState: new IndexedDbSyncStateStore("users-sync"),
+  feed: new EventsChangeFeed(client, { collection: "users" }),
+});
+```
+
 ## The root of the files
 
 No input of `procedure.store`, `procedure.load` and `procedure.sync` names a file. Under the root of a host (`mark --fs-root`, `procedure-server --fs-root`, `MCP_FS_ROOT`), they use the program store of the host. The host chooses the file of a file store, also outside the root. A loaded program is data-driven, so its nested calls get their own rules.