@evolu/common 6.0.1-preview.2 → 6.0.1-preview.21

package/dist/src/Evolu/Storage.d.ts

@@ -1,10 +1,155 @@
+import { NonEmptyReadonlyArray } from "../Array.js";
+import { Brand } from "../Brand.js";
+import { RandomDep } from "../Random.js";
+import { Result } from "../Result.js";
+import { SqliteDep, SqliteError } from "../Sqlite.js";
+import { NonNegativeInt } from "../Type.js";
+import { OwnerIdBytes, OwnerWriteKey } from "./Owner.js";
+import { Timestamp, TimestampBytes } from "./Timestamp.js";
+/**
+ * Evolu Storage
+ *
+ * The protocol using Storage is agnostic to storage implementation details—any
+ * storage can be plugged in, as long as it implements this interface.
+ * Implementations must handle their own errors; return values only indicate
+ * overall success or failure.
+ *
+ * The Storage API is synchronous because SQLite's synchronous API is the
+ * fastest way to use SQLite. Synchronous bindings (like better-sqlite3) call
+ * SQLite's C API directly with no context switching between the event loop and
+ * native code, and no promise microtasks or await overhead.
+ *
+ * The only exception is {@link Storage#writeMessages}, which is async to allow
+ * for async validation logic before writing to storage. The write operation
+ * itself remains synchronous.
+ */
+export interface Storage {
+    readonly getSize: (ownerId: OwnerIdBytes) => NonNegativeInt | null;
+    readonly fingerprint: (ownerId: OwnerIdBytes, begin: NonNegativeInt, end: NonNegativeInt) => Fingerprint | null;
+    /**
+     * Computes fingerprints with their upper bounds in one call.
+     *
+     * This function can be replaced with many fingerprint/findLowerBound calls,
+     * but implementations can leverage it for batching and more efficient
+     * fingerprint computation.
+     */
+    readonly fingerprintRanges: (ownerId: OwnerIdBytes, buckets: ReadonlyArray<NonNegativeInt>, upperBound?: RangeUpperBound) => ReadonlyArray<FingerprintRange> | null;
+    readonly findLowerBound: (ownerId: OwnerIdBytes, begin: NonNegativeInt, end: NonNegativeInt, upperBound: RangeUpperBound) => NonNegativeInt | null;
+    readonly iterate: (ownerId: OwnerIdBytes, begin: NonNegativeInt, end: NonNegativeInt, callback: (timestamp: TimestampBytes, index: NonNegativeInt) => boolean) => void;
+    /**
+     * Validates the {@link OwnerWriteKey} for the given {@link Owner}.
+     *
+     * Returns `true` if the write key is valid, `false` otherwise.
+     */
+    readonly validateWriteKey: (ownerId: OwnerIdBytes, writeKey: OwnerWriteKey) => boolean;
+    /** Sets the {@link OwnerWriteKey} for the given {@link Owner}. */
+    readonly setWriteKey: (ownerId: OwnerIdBytes, writeKey: OwnerWriteKey) => boolean;
+    /**
+     * Write encrypted {@link CrdtMessage}s to storage.
+     *
+     * Must use a mutex (per ownerId on Relay) to ensure sequential processing and
+     * proper protocol logic handling during sync operations.
+     *
+     * Returns `true` on success, `false` on failure.
+     */
+    readonly writeMessages: (ownerId: OwnerIdBytes, messages: NonEmptyReadonlyArray<EncryptedCrdtMessage>) => Promise<boolean>;
+    /** Read encrypted {@link DbChange}s from storage. */
+    readonly readDbChange: (ownerId: OwnerIdBytes, timestamp: TimestampBytes) => EncryptedDbChange | null;
+    /**
+     * Delete all data for the given {@link Owner}.
+     *
+     * Returns `true` on success, `false` on failure.
+     */
+    readonly deleteOwner: (ownerId: OwnerIdBytes) => boolean;
+}
+export interface StorageDep {
+    readonly storage: Storage;
+}
+/**
+ * A cryptographic hash used for efficiently comparing collections of
+ * {@link TimestampBytes}s.
+ *
+ * It consists of the first {@link fingerprintSize} bytes of the SHA-256 hash of
+ * one or more timestamps.
+ */
+export type Fingerprint = Uint8Array & Brand<"Fingerprint">;
+export declare const fingerprintSize: NonNegativeInt;
+/** A fingerprint of an empty range. */
+export declare const zeroFingerprint: Fingerprint;
+export interface BaseRange {
+    readonly upperBound: RangeUpperBound;
+}
+/**
+ * Union type for Range's upperBound: either a {@link TimestampBytes} or
+ * {@link InfiniteUpperBound}.
+ */
+export type RangeUpperBound = TimestampBytes | InfiniteUpperBound;
+export declare const InfiniteUpperBound: unique symbol;
+export type InfiniteUpperBound = typeof InfiniteUpperBound;
+export declare const RangeType: {
+    readonly Fingerprint: 1;
+    readonly Skip: 0;
+    readonly Timestamps: 2;
+};
+export type RangeType = (typeof RangeType)[keyof typeof RangeType];
+export interface SkipRange extends BaseRange {
+    readonly type: typeof RangeType.Skip;
+}
+export interface FingerprintRange extends BaseRange {
+    readonly type: typeof RangeType.Fingerprint;
+    readonly fingerprint: Fingerprint;
+}
+export interface TimestampsRange extends BaseRange {
+    readonly type: typeof RangeType.Timestamps;
+    readonly timestamps: ReadonlyArray<TimestampBytes>;
+}
+export type Range = SkipRange | FingerprintRange | TimestampsRange;
+/** An encrypted {@link CrdtMessage}. */
+export interface EncryptedCrdtMessage {
+    readonly timestamp: Timestamp;
+    readonly change: EncryptedDbChange;
+}
+/** Encrypted DbChange */
+export type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
 /**
- * Evolu Storage for SQLite
+ * A CRDT message combining a unique {@link Timestamp} with a {@link DbChange}.
+ *
+ * Used in Evolu's sync protocol to replicate data changes across devices. Evolu
+ * operates as a durable queue, providing exactly-once delivery guarantees for
+ * reliable synchronization across application restarts and network failures.
+ */
+export interface CrdtMessage {
+    readonly timestamp: Timestamp;
+    readonly change: DbChange;
+}
+/**
+ * A DbChange is a change to a table row. Together with a unique
+ * {@link Timestamp}, it forms a {@link CrdtMessage}.
+ */
+export declare const DbChange: import("../Type.js").ObjectType<{
+    table: import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>;
+    id: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").IdError, import("../Type.js").StringError>;
+    values: import("../Type.js").RecordType<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError, import("../Type.js").UnionType<[import("../Type.js").Type<"Null", null, null, import("../Type.js").NullError, null, import("../Type.js").NullError>, import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, import("../Type.js").Type<"Number", number, number, import("../Type.js").NumberError, number, import("../Type.js").NumberError>, import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>]>>;
+}>;
+export type DbChange = typeof DbChange.Type;
+/**
+ * Common interface for both client and relay SQLite storages.
  *
  * Evolu uses a Skiplist, which leverages SQLite indexes. The core logic is
  * implemented in SQL, so it doesn't have to make roundtrips to the DB.
  *
- * The ideal storage for a Relay should use a similar architecture to
+ * While the SQL implementation may look sophisticated, it's conceptually simple
+ * and LLMs can explain how it works. The Skiplist data structure is well
+ * explained in [this Stack Overflow
+ * answer](https://stackoverflow.com/questions/61944198/what-is-a-zip-tree-and-how-does-it-work).
+ * The logic resembles [Negentropy's C++
+ * storage](https://github.com/hoytech/negentropy), except we use a Skiplist to
+ * leverage SQLite indexes, which makes the code simpler.
+ *
+ * Note: A paid review by the SQLite team is planned, as they use the same
+ * algorithm for their rsync tool.
+ *
+ * The ideal storage for a Relay should use an architecture like
  * [strfry](https://github.com/hoytech/strfry) (a KV storage), but with Skiplist
  * to ensure that insertion order doesn't matter (local-first apps can often
  * write in the past.)
@@ -19,31 +164,31 @@
  * each other, if necessary. One relay should handle hundreds of thousands of
  * users, and when it goes down, nothing happens, because it will be
  * synchronized later.
- *
- * @module
  */
-import { RandomDep } from "../Random.js";
-import { Result } from "../Result.js";
-import { SqliteDep, SqliteError } from "../Sqlite.js";
-import { NonNegativeInt } from "../Type.js";
-import { BinaryOwnerId, Storage } from "./Protocol.js";
-import { BinaryTimestamp } from "./Timestamp.js";
-/** Common interface for both client and relay SQLite storages. */
 export interface SqliteStorageBase {
-    readonly insertTimestamp: (ownerId: BinaryOwnerId, timestamp: BinaryTimestamp) => Result<void, SqliteError>;
+    /**
+     * Inserts a timestamp for an owner into the skiplist-based storage.
+     *
+     * Must be idempotent - inserting the same timestamp multiple times has no
+     * effect after the first insertion. This is crucial for sync reliability as
+     * messages may be received and processed multiple times.
+     */
+    readonly insertTimestamp: (ownerId: OwnerIdBytes, timestamp: TimestampBytes) => Result<void, SqliteError>;
     readonly getSize: Storage["getSize"];
     readonly fingerprint: Storage["fingerprint"];
     readonly fingerprintRanges: Storage["fingerprintRanges"];
     readonly findLowerBound: Storage["findLowerBound"];
     readonly iterate: Storage["iterate"];
+    readonly deleteOwner: Storage["deleteOwner"];
 }
 export interface SqliteStorageBaseDep {
     readonly storage: SqliteStorageBase;
 }
-export type SqliteStorageDeps = SqliteDep & RandomDep;
+export type SqliteStorageDeps = RandomDep & SqliteDep;
 export interface CreateSqliteStorageBaseOptions {
     onStorageError: (error: SqliteError) => void;
 }
 export declare const createSqliteStorageBase: (deps: SqliteStorageDeps) => (options: CreateSqliteStorageBaseOptions) => Result<SqliteStorageBase, SqliteError>;
-export declare const getTimestampByIndex: (deps: SqliteDep) => (ownerId: BinaryOwnerId, index: NonNegativeInt) => Result<BinaryTimestamp, SqliteError>;
+export declare const timestampBytesToFingerprint: (timestamp: TimestampBytes) => Fingerprint;
+export declare const getTimestampByIndex: (deps: SqliteDep) => (ownerId: OwnerIdBytes, index: NonNegativeInt) => Result<TimestampBytes, SqliteError>;
 //# sourceMappingURL=Storage.d.ts.map

package/dist/src/Evolu/Storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAM,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAO,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAe,cAAc,EAAe,MAAM,YAAY,CAAC;AAGtE,OAAO,EACL,aAAa,EAQb,OAAO,EAER,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAwB,MAAM,gBAAgB,CAAC;AAEvE,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,eAAe,EAAE,CACxB,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,eAAe,KACvB,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAE/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACzD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,8BAA8B;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C;AAED,eAAO,MAAM,uBAAuB,GACjC,MAAM,iBAAiB,MAEtB,SAAS,8BAA8B,KACtC,MAAM,CAAC,iBAAiB,EAAE,WAAW,CAyIvC,CAAC;AA09BJ,eAAO,MAAM,mBAAmB,GAC7B,MAAM,SAAS,MAEd,SAAS,aAAa,EACtB,OAAO,cAAc,KACpB,MAAM,CAAC,eAAe,EAAE,WAAW,CA6ErC,CAAC"}
+{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Storage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAM,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAO,SAAS,EAAE,WAAW,EAAe,MAAM,cAAc,CAAC;AACxE,OAAO,EAGL,cAAc,EAKf,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,YAAY,EAEZ,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAuB,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,cAAc,GAAG,IAAI,CAAC;IAEnE,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,KAChB,WAAW,GAAG,IAAI,CAAC;IAExB;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,EACtC,UAAU,CAAC,EAAE,eAAe,KACzB,aAAa,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;IAE5C,QAAQ,CAAC,cAAc,EAAE,CACvB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,eAAe,KACxB,cAAc,GAAG,IAAI,CAAC;IAE3B,QAAQ,CAAC,OAAO,EAAE,CAChB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,KAAK,OAAO,KACpE,IAAI,CAAC;IAEV;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,CACzB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,aAAa,KACpB,OAAO,CAAC;IAEb,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,aAAa,KACpB,OAAO,CAAC;IAEb;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,CACtB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,KAClD,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,CACrB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,cAAc,KACtB,iBAAiB,GAAG,IAAI,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe,EAAS,cAAc,CAAC;AAEpD,uCAAuC;AACvC,eAAO,MAAM,eAAe,EAAsC,WAAW,CAAC;AAE9E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAElE,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAE3D,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,SAAS,CAAC,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,QAAQ,CAAC,IAAI,EAAE,OAAO,SAAS,CAAC,WAAW,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAE,OAAO,SAAS,CAAC,UAAU,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEnE,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,yBAAyB;AACzB,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,KAAK,CAAC,mBAAmB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;EAInB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,CACxB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,cAAc,KACtB,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAE/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACzD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,8BAA8B;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C;AAED,eAAO,MAAM,uBAAuB,GACjC,MAAM,iBAAiB,MAEtB,SAAS,8BAA8B,KACtC,MAAM,CAAC,iBAAiB,EAAE,WAAW,CAoJvC,CAAC;AAqlBJ,eAAO,MAAM,2BAA2B,GACtC,WAAW,cAAc,KACxB,WAGF,CAAC;AAuYF,eAAO,MAAM,mBAAmB,GAC7B,MAAM,SAAS,MAEd,SAAS,YAAY,EACrB,OAAO,cAAc,KACpB,MAAM,CAAC,cAAc,EAAE,WAAW,CA6EpC,CAAC"}

package/dist/src/Evolu/Storage.js

@@ -1,33 +1,29 @@
-/**
- * Evolu Storage for SQLite
- *
- * Evolu uses a Skiplist, which leverages SQLite indexes. The core logic is
- * implemented in SQL, so it doesn't have to make roundtrips to the DB.
- *
- * The ideal storage for a Relay should use a similar architecture to
- * [strfry](https://github.com/hoytech/strfry) (a KV storage), but with Skiplist
- * to ensure that insertion order doesn't matter (local-first apps can often
- * write in the past.)
- *
- * The ideal client implementation should probably use the SQLite extension
- * instead of SQL or even a KV storage, when such a thing for browsers/native
- * will exist and will be faster than SQLite.
- *
- * # Scaling
- *
- * The load can be distributed by deploying multiple relays, synchronized with
- * each other, if necessary. One relay should handle hundreds of thousands of
- * users, and when it goes down, nothing happens, because it will be
- * synchronized later.
- *
- * @module
- */
+import { sha256 } from "@noble/hashes/sha2.js";
 import { assert } from "../Assert.js";
 import { decrement } from "../Number.js";
 import { ok } from "../Result.js";
-import { sql } from "../Sqlite.js";
-import { binaryOwnerIdToOwnerId, binaryTimestampToFingerprint, InfiniteUpperBound, RangeType, zeroFingerprint, } from "./Protocol.js";
-import { orderBinaryTimestamp } from "./Timestamp.js";
+import { sql, SqliteValue } from "../Sqlite.js";
+import { Id, object, record, String, } from "../Type.js";
+import { ownerIdBytesToOwnerId, } from "./Owner.js";
+import { orderTimestampBytes } from "./Timestamp.js";
+export const fingerprintSize = 12;
+/** A fingerprint of an empty range. */
+export const zeroFingerprint = new Uint8Array(fingerprintSize);
+export const InfiniteUpperBound = Symbol("InfiniteUpperBound");
+export const RangeType = {
+    Fingerprint: 1,
+    Skip: 0,
+    Timestamps: 2,
+};
+/**
+ * A DbChange is a change to a table row. Together with a unique
+ * {@link Timestamp}, it forms a {@link CrdtMessage}.
+ */
+export const DbChange = object({
+    table: String,
+    id: Id,
+    values: record(String, SqliteValue),
+});
 export const createSqliteStorageBase = (deps) => (options) => {
     const createTablesResult = createTables(deps);
     if (!createTablesResult.ok)
@@ -35,7 +31,7 @@ export const createSqliteStorageBase = (deps) => (options) => {
     const ownerStats = new Map();
     return ok({
         insertTimestamp: (ownerId, timestamp) => {
-            const ownerIdString = binaryOwnerIdToOwnerId(ownerId);
+            const ownerIdString = ownerIdBytesToOwnerId(ownerId);
             const level = randomSkiplistLevel(deps);
             let stats = ownerStats.get(ownerIdString);
             if (!stats) {
@@ -53,11 +49,11 @@ export const createSqliteStorageBase = (deps) => (options) => {
                 ownerStats.set(ownerIdString, stats);
             }
             let strategy;
-            if (orderBinaryTimestamp(timestamp, stats.maxT) === 1) {
+            if (orderTimestampBytes(timestamp, stats.maxT) === 1) {
                 strategy = "append";
                 stats.maxT = timestamp;
             }
-            else if (orderBinaryTimestamp(timestamp, stats.minT) === -1) {
+            else if (orderTimestampBytes(timestamp, stats.minT) === -1) {
                 strategy = "prepend";
                 stats.minT = timestamp;
             }
@@ -141,6 +137,16 @@ export const createSqliteStorageBase = (deps) => (options) => {
                     return;
             }
         },
+        deleteOwner: (ownerId) => {
+            const result = deps.sqlite.exec(sql `
+          delete from evolu_timestamp where ownerId = ${ownerId};
+        `);
+            if (!result.ok) {
+                options.onStorageError(result.error);
+                return false;
+            }
+            return true;
+        },
     });
 };
 const assertBeginEnd = (begin, end) => {
@@ -159,7 +165,7 @@ const createTables = (deps) => {
          *
          * Columns:
          *
-         * - `t` – globally unique binary timestamp
+         * - `t` – TimestampBytes
          * - `h1`/`h2` – 12-byte fingerprint split into two integers for fast XOR
          * - `c` – incremental count
          * - `l` – Skiplist level (1 to 32)
@@ -208,7 +214,7 @@ const createTables = (deps) => {
 // they will prepend. They are always sorted in ascending order by the
 // Protocol.
 const insertTimestamp = (deps) => (ownerId, timestamp, level, strategy) => {
-    const [h1, h2] = fingerprintToSqliteFingerprint(binaryTimestampToFingerprint(timestamp));
+    const [h1, h2] = fingerprintToSqliteFingerprint(timestampBytesToFingerprint(timestamp));
     let queries = [];
     switch (strategy) {
         case "append":
@@ -717,6 +723,10 @@ const insertTimestamp = (deps) => (ownerId, timestamp, level, strategy) => {
     }
     return ok();
 };
+export const timestampBytesToFingerprint = (timestamp) => {
+    const hash = sha256(timestamp).slice(0, fingerprintSize);
+    return hash;
+};
 /**
  * Generates a random skiplist level in the range [1, skiplistMaxLevel].
  * Probabilistic approach avoids the need for explicit tree balancing.

package/dist/src/Evolu/Sync.d.ts

@@ -1,23 +1,78 @@
-import { ConsoleConfig, ConsoleDep } from "../Console.js";
-import { ProtocolMessage } from "./Protocol.js";
-import { Millis } from "./Timestamp.js";
-export interface Sync {
-    readonly send: (message: ProtocolMessage) => void;
+import { NonEmptyReadonlyArray } from "../Array.js";
+import { ConsoleDep } from "../Console.js";
+import { RandomBytesDep, SymmetricCryptoDecryptError, SymmetricCryptoDep } from "../Crypto.js";
+import { TransferableError } from "../Error.js";
+import { RandomDep } from "../Random.js";
+import { Result } from "../Result.js";
+import { SqliteDep, SqliteError } from "../Sqlite.js";
+import { TimeDep } from "../Time.js";
+import { CreateWebSocketDep } from "../WebSocket.js";
+import type { PostMessageDep } from "./Db.js";
+import { AppOwner, OwnerEncryptionKey, OwnerId, OwnerIdBytes, OwnerWriteKey, TransportConfig } from "./Owner.js";
+import { ProtocolError, ProtocolInvalidDataError, ProtocolTimestampMismatchError } from "./Protocol.js";
+import { MutationChange } from "./Schema.js";
+import { CrdtMessage, SqliteStorageBase, Storage } from "./Storage.js";
+import { Millis, Timestamp, TimestampConfigDep, TimestampCounterOverflowError, TimestampDriftError, TimestampTimeOutOfRangeError } from "./Timestamp.js";
+export interface Sync extends Disposable {
+    /**
+     * Assigns or removes an owner to/from transports with reference counting.
+     *
+     * Owners are only "active" if assigned to at least one transport. Uses
+     * `owner.transports` or falls back to config transports. Multiple calls
+     * increment/decrement reference counts (useful for React Hooks).
+     */
+    readonly useOwner: (use: boolean, owner: SyncOwner) => void;
+    readonly applyChanges: (changes: NonEmptyReadonlyArray<MutationChange>) => Result<void, SqliteError | TimestampCounterOverflowError | TimestampDriftError | TimestampTimeOutOfRangeError>;
 }
 export interface SyncDep {
     readonly sync: Sync;
 }
-export type CreateSync = (deps: ConsoleDep) => (config: SyncConfig) => Sync;
-export interface CreateSyncDep {
-    readonly createSync: CreateSync;
+/**
+ * Represents an owner for sync operations. This is a unified interface that
+ * abstracts over the specific owner types ({@link ShardOwner},
+ * {@link SharedOwner}, {@link SharedReadonlyOwner}) for the sync layer.
+ *
+ * The sync layer only needs the essential data for synchronization and doesn't
+ * need to distinguish between different owner types.
+ */
+export interface SyncOwner {
+    readonly id: OwnerId;
+    readonly encryptionKey: OwnerEncryptionKey;
+    /** Optional for read-only owners like {@link SharedReadonlyOwner}. */
+    readonly writeKey?: OwnerWriteKey;
+    readonly transports?: ReadonlyArray<TransportConfig>;
+}
+export interface SyncConfig {
+    readonly appOwner: AppOwner;
+    readonly transports: ReadonlyArray<TransportConfig>;
+    /**
+     * Delay in milliseconds before disposing unused WebSocket connections.
+     * Defaults to 100ms.
+     */
+    readonly disposalDelayMs?: number;
+    readonly onError: (error: ProtocolError | ProtocolInvalidDataError | ProtocolTimestampMismatchError | SqliteError | SymmetricCryptoDecryptError | TimestampCounterOverflowError | TimestampDriftError | TimestampTimeOutOfRangeError | TransferableError) => void;
+    readonly onReceive: () => void;
 }
-export interface SyncConfig extends ConsoleConfig {
-    readonly syncUrl: string;
-    readonly onOpen: (send: Sync["send"]) => void;
-    readonly onMessage: (message: Uint8Array, send: Sync["send"]) => void;
+export declare const createSync: (deps: ClockDep & ConsoleDep & CreateWebSocketDep & PostMessageDep & RandomBytesDep & RandomDep & SqliteDep & SymmetricCryptoDep & TimeDep & TimestampConfigDep) => (config: SyncConfig) => Result<Sync, SqliteError>;
+export interface ClockDep {
+    readonly clock: Clock;
 }
-export declare const createWebSocketSync: CreateSync;
+export interface Clock {
+    readonly get: () => Timestamp;
+    readonly save: (timestamp: Timestamp) => Result<void, SqliteError>;
+}
+export declare const createClock: (deps: RandomBytesDep & SqliteDep) => (initialTimestamp?: Timestamp) => Clock;
+export interface ClientStorage extends SqliteStorageBase, Storage {
+}
+export interface ClientStorageDep {
+    readonly storage: ClientStorage;
+}
+export declare const applyLocalOnlyChange: (deps: SqliteDep & TimeDep) => (change: MutationChange) => Result<void, SqliteError>;
+export declare const applyMessages: (deps: ClientStorageDep & ClockDep & RandomDep & SqliteDep) => (ownerId: OwnerId, messages: ReadonlyArray<CrdtMessage>) => Result<void, SqliteError>;
+export declare const applyMessageToTimestampAndHistoryTables: (deps: ClientStorageDep & SqliteDep) => (ownerId: OwnerIdBytes, message: CrdtMessage) => Result<void, SqliteError>;
 /**
+ * TODO: Rework for the new owners API.
+ *
  * The possible states of a synchronization process. The `SyncState` can be one
  * of the following:
  *

package/dist/src/Evolu/Sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sync.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;AAE5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;CACvE;AAED,eAAO,MAAM,mBAAmB,EAAE,UA2BjC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,oBAAoB,CAAC;AAEzB;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,oBAAoB,CAAC;CACnE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED,eAAO,MAAM,gBAAgB,EAAE,gBAA+C,CAAC"}
+{"version":3,"file":"Sync.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Sync.ts"],"names":[],"mappings":"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"}