@mdbase-dev/connect 0.1.0-beta.111 → 0.1.0-beta.112

package/README.md

@@ -119,6 +119,53 @@ function useMdbaseSession() {
 }
 ```
 
+An application that lets people type into a record opens it as a session
+instead of calling `update()` per change. Every view that opens the same path
+shares one session, so a record never has two competing writers:
+
+```ts
+if (watch.ok) connection.records.follow(watch.value);
+
+const opened = await connection.records.open("Notes/today.md", {
+  autosave: { idleMs: 1_000 },
+  timeoutMs: 8_000
+});
+if (!opened.ok) return renderProblem(opened.problem);
+const { session, release } = opened.value;
+
+const unsubscribeRecord = session.subscribe(() => render(session.getSnapshot()));
+editor.onChange((text) => session.setBody(text));
+propertiesPanel.onChange((patch) => session.patchFrontmatter(patch));
+
+// Leaving the view: write what is left, then let the session go.
+const flushed = await session.flush();
+if (!flushed.ok && flushed.problem.code === "concurrent_modification") {
+  showConflict(session.getSnapshot()); // then session.resolve({ keep: "mine" | "theirs" })
+}
+unsubscribeRecord();
+release();
+```
+
+The session autosaves after the idle interval, serializes its writes, sends
+only the body and frontmatter keys that changed, and checks each write against
+the revision it was based on. It recognizes its own saves after they settle, so
+a watch event or another view that publishes the saved (possibly normalized)
+record first is not mistaken for someone else's edit. A change made elsewhere
+becomes a `conflict` only when it touched something edited locally; otherwise
+the session rebases onto it, and a clean session adopts it. A write whose
+response is lost enters `recovery` and is continued only through its durable
+pending mutation, never sent again, even after a reload: `open()` finds the
+record's interrupted update (by a digest, so its path is never stored) and
+resumes it as `recovery`. `follow()` refreshes open sessions from the
+watch, follows renames, marks deletions (local text is kept), and re-reads
+everything after a change gap. Releasing the last view never cancels a pending
+save. `snapshot.state` is one of `saved`, `unsaved`, `saving`, `conflict`,
+`recovery`, `error` or `deleted`; `snapshot.problem` says why a write failed.
+The session is an external store, so `externalStore(session)` works with
+`useSyncExternalStore`. Applications whose records live behind their own
+repository construct `MdbaseRecordSession` with an `MdbaseRecordSessionAdapter`
+from `/advanced`.
+
 Browser and native callbacks share the same typed completion boundary:
 
 ```ts

package/dist/advanced.d.ts

@@ -7,3 +7,5 @@ export { connectFailure, connectSuccess } from "./outcomes.js";
 export type { MdbaseApplicationVerificationStore, MdbaseApplicationSessionConnect } from "./application-session.js";
 export { MdbaseSession } from "./session.js";
 export type { MdbaseSessionConnect, MdbaseSessionOptions, MdbaseSessionSnapshot } from "./session.js";
+/** Custom record transports, for sessions over an application's own repository or a test double. */
+export type { MdbaseRecordChange, MdbaseRecordSessionAdapter } from "./record-session.js";

package/dist/base64.js

@@ -3,11 +3,19 @@ export function randomBase64Url(size) {
     crypto.getRandomValues(bytes);
     return bytesToBase64Url(bytes);
 }
+// Encrypted requests and responses carry whole records, so these run over
+// megabytes: convert in chunks rather than one character at a time.
+const CHUNK = 0x8000;
 export function bytesToBase64Url(bytes) {
     let binary = "";
-    for (const byte of bytes)
-        binary += String.fromCharCode(byte);
-    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+    for (let index = 0; index < bytes.length; index += CHUNK) {
+        binary += String.fromCharCode.apply(null, bytes.subarray(index, index + CHUNK));
+    }
+    const encoded = btoa(binary).replaceAll("+", "-").replaceAll("/", "_");
+    let end = encoded.length;
+    while (end > 0 && encoded.charCodeAt(end - 1) === 61 /* = */)
+        end -= 1;
+    return encoded.slice(0, end);
 }
 export function base64UrlBytes(value) {
     const padded = value.replaceAll("-", "+").replaceAll("_", "/")

package/dist/browser/integrity.json

@@ -1,4 +1,4 @@
 {
   "file": "mdbase-connect.min.js",
-  "integrity": "sha384-/62JQssTDGRQGVQwcO5KLWO7BOqrDVxB0ne307QlEFVO3/MzYMBJfjmbz/OdCRWP"
+  "integrity": "sha384-uKL9FxAY8Ji2mQSA44JTIIarA2CnPGN3EFC4jxk1Kx+OfDsPbFr2J+iwlH/p77Qz"
 }