@mengine/storage 1.1.0 → 1.2.0

package/dist/{base-B0LSXWTK.d.ts → base-CPnEm_ZJ.d.ts}

@@ -72,6 +72,37 @@ interface DocUpdate {
   docId: string;
   data: Uint8Array;
 }
+/**
+ * What a peer says about ITSELF after accepting a push.
+ *
+ * Every field is optional because most peers report nothing: the local pg/idb
+ * write paths never decode Loro, so they have no version to give and return an
+ * empty receipt. Only a peer that answers with its own state — today the
+ * mengine-server HTTP path — fills this in.
+ */
+interface DocPushReceipt {
+  /**
+   * The encoded version vector the peer holds AFTER this write.
+   *
+   * Same class of evidence as {@link DocDiff.version}: a complete statement
+   * about the peer, so a caller tracking "what the remote has" may adopt it
+   * outright — including downward. A peer that lost an op it once acked reports
+   * a version below the caller's belief, and copying that lower version is what
+   * makes the caller re-send. Taking a per-peer max instead would make the
+   * belief monotonic and destroy that healing path.
+   *
+   * It may LEAD the caller's doc on OTHER peers, covering concurrent ops the
+   * caller has not seen yet; adopting that is safe and is the point, because
+   * those ops are then never re-sent. It must NOT be believed where it leads on
+   * the caller's OWN peer: `export({ from })` skips every local op the version
+   * already covers, so a claim beyond what the caller actually sent makes those
+   * ops unsendable while the push still reports success. Callers are expected to
+   * clamp their own entry to what the request provably carried — the bytes here
+   * are a claim, not a proof, and `VersionVector.decode` accepts inputs that are
+   * not version vectors at all.
+   */
+  version?: Uint8Array;
+}
 interface DocUpdateRecord extends DocUpdate {
   seq: number;
   createdAt: Date;
@@ -105,9 +136,21 @@ interface DocStorage {
    */
   getDocDiff(docId: string, knownVersion?: Uint8Array): Promise<DocDiff | null>;
   /**
-   * Push updates into storage
+   * Push updates into storage.
+   *
+   * Every field of the {@link DocPushReceipt} is optional, so a peer with nothing
+   * to report answers `{}`. A peer that CAN state its resulting version should,
+   * because that statement covers other peers' ops too and lets the caller stop
+   * re-sending them.
+   *
+   * Resolving means the bytes are durable at this peer, so a peer that would drop
+   * the write must reject instead — callers read "resolved" as proof of a write,
+   * and a silent drop is indistinguishable from success. A peer that refuses ALL
+   * writes is different in kind: it is a standing condition, not a failed request,
+   * so it reports itself through {@link DocStorage.isReadonly} and callers are
+   * expected to check that rather than to discover it one rejection at a time.
    */
-  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<DocPushReceipt>;
   /**
    * Delete a specific doc data with all snapshots and updates
    */
@@ -140,7 +183,7 @@ declare abstract class BaseDocStorage<Opts = {}> implements DocStorage {
   constructor(options: Opts & DocStorageOptions);
   getDoc(docId: string): Promise<DocSnapshotRecord | null>;
   getDocDiff(docId: string, knownVersion?: Uint8Array): Promise<DocDiff | null>;
-  abstract pushDocUpdate(update: DocUpdate, origin: unknown): Promise<void>;
+  abstract pushDocUpdate(update: DocUpdate, origin: unknown): Promise<DocPushReceipt>;
   abstract deleteDoc(docId: string): Promise<void>;
   subscribeDocUpdate(callback: (update: DocUpdate, origin: unknown) => void): () => void;
   /**
@@ -188,4 +231,4 @@ declare abstract class BaseDocStorage<Opts = {}> implements DocStorage {
   protected lockDocForUpdate(docId: string): Promise<AsyncDisposable>;
 }
 //#endregion
-export { DocStorage as a, DocUpdateRecord as c, Connection as d, ConnectionStatus as f, DocSnapshotRecord as i, share as l, Locker as n, DocStorageOptions as o, DummyConnection as p, DocDiff as r, DocUpdate as s, BaseDocStorage as t, AutoReconnectConnection as u };
+export { DocSnapshotRecord as a, DocUpdate as c, AutoReconnectConnection as d, Connection as f, DocPushReceipt as i, DocUpdateRecord as l, DummyConnection as m, Locker as n, DocStorage as o, ConnectionStatus as p, DocDiff as r, DocStorageOptions as s, BaseDocStorage as t, share as u };

package/dist/idb.d.ts

@@ -1,4 +1,4 @@
-import { c as DocUpdateRecord, i as DocSnapshotRecord, n as Locker, s as DocUpdate, t as BaseDocStorage, u as AutoReconnectConnection } from "./base-B0LSXWTK.js";
+import { a as DocSnapshotRecord, c as DocUpdate, d as AutoReconnectConnection, i as DocPushReceipt, l as DocUpdateRecord, n as Locker, t as BaseDocStorage } from "./base-CPnEm_ZJ.js";
 import { DBSchema, IDBPDatabase } from "idb";
 
 //#region src/impls/idb/schema.d.ts
@@ -105,7 +105,7 @@ declare class IndexedDBDocStorage extends BaseDocStorage<{
   protected readonly locker: IndexedDBLocker;
   get db(): import("idb").IDBPDatabase<DocStorageSchema>;
   get channel(): BroadcastChannel;
-  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<DocPushReceipt>;
   protected getDocSnapshot(docId: string): Promise<DocSnapshotRecord | null>;
   deleteDoc(docId: string): Promise<void>;
   protected setDocSnapshot(snapshot: DocSnapshotRecord): Promise<boolean>;

package/dist/idb.js

@@ -125,7 +125,7 @@ var IndexedDBDocStorage = class extends BaseDocStorage {
 				createdAt: /* @__PURE__ */ new Date(),
 				updatedAt: /* @__PURE__ */ new Date()
 			});
-			return;
+			return {};
 		}
 		let seq = await trx.objectStore("sequences").get(update.docId);
 		if (!seq) seq = {
@@ -155,6 +155,7 @@ var IndexedDBDocStorage = class extends BaseDocStorage {
 			},
 			origin
 		});
+		return {};
 	}
 	async getDocSnapshot(docId) {
 		return await this.db.transaction("snapshots", "readonly").store.get(docId) ?? null;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { a as DocStorage, c as DocUpdateRecord, d as Connection, f as ConnectionStatus, i as DocSnapshotRecord, l as share, o as DocStorageOptions, p as DummyConnection, r as DocDiff, s as DocUpdate, t as BaseDocStorage, u as AutoReconnectConnection } from "./base-B0LSXWTK.js";
-export { AutoReconnectConnection, BaseDocStorage, Connection, ConnectionStatus, DocDiff, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord, DummyConnection, share };
+import { a as DocSnapshotRecord, c as DocUpdate, d as AutoReconnectConnection, f as Connection, i as DocPushReceipt, l as DocUpdateRecord, m as DummyConnection, o as DocStorage, p as ConnectionStatus, r as DocDiff, s as DocStorageOptions, t as BaseDocStorage, u as share } from "./base-CPnEm_ZJ.js";
+export { AutoReconnectConnection, BaseDocStorage, Connection, ConnectionStatus, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord, DummyConnection, share };

package/dist/pg.d.ts

@@ -1,4 +1,4 @@
-import { c as DocUpdateRecord, i as DocSnapshotRecord, s as DocUpdate, t as BaseDocStorage, u as AutoReconnectConnection } from "./base-B0LSXWTK.js";
+import { a as DocSnapshotRecord, c as DocUpdate, d as AutoReconnectConnection, i as DocPushReceipt, l as DocUpdateRecord, t as BaseDocStorage } from "./base-CPnEm_ZJ.js";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { Pool } from "pg";
 
@@ -659,7 +659,7 @@ declare class PgDocStorage extends BaseDocStorage<PgConnectionOptions> {
     }>;
   }>;
   getDoc(docId: string): Promise<DocSnapshotRecord | null>;
-  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<DocPushReceipt>;
   deleteDoc(docId: string): Promise<void>;
   protected getDocSnapshot(docId: string): Promise<DocSnapshotRecord | null>;
   protected setDocSnapshot(snapshot: DocSnapshotRecord): Promise<boolean>;

package/dist/pg.js

@@ -199,6 +199,7 @@ var PgDocStorage = class extends BaseDocStorage {
 				createdAt: now
 			});
 		});
+		return {};
 	}
 	async deleteDoc(docId) {
 		await this.db.transaction(async (tx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/storage",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     "drizzle-orm": "^0.45.2",
     "lodash-es": "^4.18.1",
     "loro-crdt": "^1.13.6",
-    "@mengine/utils": "1.1.0"
+    "@mengine/utils": "1.2.0"
   },
   "devDependencies": {
     "@testcontainers/postgresql": "^12.0.1",