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

package/dist/src/Evolu/Protocol.js

@@ -1,4 +1,3 @@
-/* eslint-disable jsdoc/no-undefined-types */
 /**
  * Evolu Protocol
  *
@@ -21,7 +20,7 @@
  * transfer, ownership, real-time broadcasting, request-response semantics, and
  * error handling.
  *
- * ### Message Structure
+ * ### Message structure
  *
  * | Field                          | Notes                     |
  * | :----------------------------- | :------------------------ |
@@ -44,7 +43,7 @@
  * | - {@link NonNegativeInt}       | Number of ranges.         |
  * | - {@link Range}                |                           |
  *
- * ### WriteKey Validation
+ * ### WriteKey validation
  *
  * The initiator sends a hasWriteKey flag and optionally a WriteKey. The
  * WriteKey is required when sending messages as a secure token proving the
@@ -80,33 +79,33 @@
  * initiator. In relay-to-relay or P2P sync, both sides may require the
  * {@link OwnerWriteKey} depending on who is the initiator.
  *
- * ### Protocol Errors
+ * ### Protocol errors
  *
  * The protocol uses error codes in the header to signal issues:
  *
  * - {@link ProtocolWriteKeyError}: The provided WriteKey is invalid or missing.
- * - {@link ProtocolWriteError}: A write operation failed (e.g., due to storage
- *   limits or billing).
- * - {@link ProtocolSyncError}: A generic or unexpected synchronization failure
+ * - {@link ProtocolWriteError}: A serious relay-side write failure occurred.
+ * - {@link ProtocolSyncError}: A serious relay-side synchronization failure
  *   occurred.
+ * - {@link ProtocolQuotaExceededError}: Storage or billing quota exceeded.
  * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
  * - {@link ProtocolInvalidDataError}: The message is malformed or corrupted.
  *
  * All protocol errors except `ProtocolInvalidDataError` include the `OwnerId`
  * to allow clients to associate errors with the correct owner.
  *
- * ### Message Size Limit
+ * ### Message size limit
  *
  * The protocol enforces a strict maximum size for all messages, defined by
- * {@link maxProtocolMessageSize}. This ensures every {@link ProtocolMessage} is
+ * {@link ProtocolMessageMaxSize}. This ensures every {@link ProtocolMessage} is
  * less than or equal to this limit, enabling stateless transports, simplified
  * relay implementation, and predictable memory usage. When all messages don't
  * fit within the limit, the protocol automatically continues synchronization in
  * subsequent rounds using range-based reconciliation.
  *
- * Individual database mutations are limited to `maxMutationSize` (640KB), which
- * is smaller than the protocol message limit to ensure efficient sync with
- * {@link maxProtocolMessageRangesSize}.
+ * Database mutations are limited to 640KB, which is smaller than the protocol
+ * message limit to ensure efficient sync with
+ * {@link defaultProtocolMessageRangesMaxSize}.
  *
  * ### Why Binary?
  *
@@ -149,6 +148,15 @@
  * Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
  * over time and provide clear feedback about version mismatches.
  *
+ * ### Credible exit
+ *
+ * The protocol specification is intentionally non-configurable to ensure
+ * universal compatibility. This design allows applications (users) to switch
+ * between any compliant relay without negotiation or compatibility checks
+ * beyond version matching. Relays are generic infrastructure that any
+ * application can use interchangeably making exit from any single provider
+ * technically feasible and economically viable.
+ *
  * @module
  */
 import { Packr } from "msgpackr";
@@ -160,21 +168,62 @@ import { eqArrayNumber } from "../Eq.js";
 import { computeBalancedBuckets } from "../Number.js";
 import { objectToEntries } from "../Object.js";
 import { err, ok } from "../Result.js";
-import { Base64Url, base64UrlToUint8Array, DateIso, Id, idBytesToId, idBytesTypeValueLength, idToIdBytes, Json, jsonToJsonValue, NonNegativeInt, Number, uint8ArrayToBase64Url, } from "../Type.js";
+import { Base64Url, base64UrlToUint8Array, between, DateIso, Id, idBytesToId, idBytesTypeValueLength, idToIdBytes, Int, Json, jsonToJsonValue, NonNegativeInt, Number, uint8ArrayToBase64Url, } from "../Type.js";
 import { ownerIdToOwnerIdBytes, ownerWriteKeyLength, } from "./Owner.js";
 import { fingerprintSize, InfiniteUpperBound, RangeType, } from "./Storage.js";
 import { Counter, eqTimestamp, Millis, timestampBytesLength, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
 /**
- * MessagePack serializer for standard compatibility and compact encoding.
+ * Evolu uses MessagePack for numbers and JSONs.
  *
  * - `variableMapSize: true` - More compact maps, ~5-10% slower encoding
  * - `useRecords: false` - Standard MessagePack without extensions
  */
 const packr = new Packr({ variableMapSize: true, useRecords: false });
-/** Maximum size of the entire protocol message in bytes. */
-export const maxProtocolMessageSize = 1_000_000;
-/** Maximum size of the ranges in bytes. */
-export const maxProtocolMessageRangesSize = 30_000;
+const minProtocolMessageMaxSize = 1_000_000;
+const maxProtocolMessageMaxSize = 100_000_000;
+/**
+ * Protocol message maximum size.
+ *
+ * Defines the upper limit for how large a single protocol message can be.
+ * Implementations must enforce a maximum size between 1MB and 100MB to ensure
+ * compatibility across all Evolu implementations (the maximum size of mutation
+ * change is hardcoded and enforced hence the maximum size can't be smaller).
+ *
+ * Larger maximum sizes can be configured by relays to reduce roundtrips. For
+ * example, a dedicated relay with ample resources could configure a 100MB
+ * maximum to minimize roundtrips for large syncs.
+ *
+ * Only relays can safely configure larger sizes, as clients will handle them.
+ * Increasing this value on the client side would break compatibility with
+ * relays that enforce smaller limits.
+ */
+export const ProtocolMessageMaxSize = between(minProtocolMessageMaxSize, maxProtocolMessageMaxSize)(Int);
+/**
+ * Default {@link ProtocolMessageMaxSize} (1MB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export const defaultProtocolMessageMaxSize = minProtocolMessageMaxSize;
+/**
+ * Protocol message ranges maximum size.
+ *
+ * Defines the upper limit for how large the ranges section of a protocol
+ * message can be. Implementations must enforce a maximum size between 3KB and
+ * 100KB to ensure compatibility.
+ *
+ * The upper bound is set to ensure ranges fit within the default 1MB
+ * {@link defaultProtocolMessageMaxSize}, maintaining compatibility between all
+ * clients and relays.
+ */
+export const ProtocolMessageRangesMaxSize = between(3_000, 100_000)(Int);
+/**
+ * Default {@link ProtocolMessageRangesMaxSize} (30KB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export const defaultProtocolMessageRangesMaxSize = 30_000;
 /** Evolu Protocol version. */
 export const protocolVersion = 0;
 export const MessageType = {
@@ -201,18 +250,20 @@ export const ProtocolErrorCode = {
     WriteError: 2,
     /** A code for {@link ProtocolSyncError}. */
     SyncError: 3,
+    /** A code for {@link ProtocolQuotaExceededError}. */
+    QuotaExceededError: 4,
 };
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
- * If the message size would exceed {@link maxProtocolMessageSize}, the protocol
- * ensures all messages will be sent in the next round(s) even over
+ * If the message size would exceed {@link defaultProtocolMessageMaxSize}, the
+ * protocol ensures all messages will be sent in the next round(s) even over
  * unidirectional and stateless transports.
  */
 export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages, maxSize) => {
     const buffer = createProtocolMessageBuffer(owner.id, {
         messageType: MessageType.Request,
-        totalMaxSize: maxSize ?? maxProtocolMessageSize,
+        totalMaxSize: maxSize ?? defaultProtocolMessageMaxSize,
         writeKey: owner.writeKey,
     });
     let notAllMessagesSent = false;
@@ -236,8 +287,8 @@ export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages,
          *
          * The ideal approach would be to send three ranges (skip, fingerprint,
          * skip) where the fingerprint of unsent messages would act as narrow sync
-         * probe. I think we can send {@link zeroFingerprint} which can be
-         * interpreted as an indication that the other side should reply with
+         * probe. I think we can send `zeroFingerprint` which can be interpreted
+         * as an indication that the other side should reply with
          * {@link TimestampsRange}, so no need to restart syncing.
          *
          * For now, using a random fingerprint avoids extra complexity and is good
@@ -272,7 +323,7 @@ export const createProtocolMessageForUnsubscribe = (ownerId) => createProtocolMe
     subscriptionFlag: SubscriptionFlags.Unsubscribe,
 }).unwrap();
 export const createProtocolMessageBuffer = (ownerId, options) => {
-    const { totalMaxSize = maxProtocolMessageSize, rangesMaxSize = maxProtocolMessageRangesSize, version = protocolVersion, } = options;
+    const { totalMaxSize = defaultProtocolMessageMaxSize, rangesMaxSize = defaultProtocolMessageRangesMaxSize, version = protocolVersion, } = options;
     const buffers = {
         header: createBuffer(),
         messages: {
@@ -507,6 +558,11 @@ export const applyProtocolMessageAsClient = (deps) => async (inputMessage, optio
                             type: "ProtocolSyncError",
                             ownerId,
                         });
+                    case ProtocolErrorCode.QuotaExceededError:
+                        return err({
+                            type: "ProtocolQuotaExceededError",
+                            ownerId,
+                        });
                     default:
                         throw new ProtocolDecodeError(`Invalid ProtocolErrorCode: ${errorCode}`);
                 }
@@ -537,7 +593,6 @@ export const applyProtocolMessageAsClient = (deps) => async (inputMessage, optio
         const output = createProtocolMessageBuffer(ownerId, {
             messageType: MessageType.Request,
             writeKey,
-            totalMaxSize: options.totalMaxSize,
             rangesMaxSize: options.rangesMaxSize,
         });
         const syncResult = sync(deps)(ranges, output, ownerIdBytes);

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

@@ -1,14 +1,81 @@
-import { ConsoleConfig } from "../Console.js";
+import { ConsoleConfig, ConsoleDep } from "../Console.js";
 import { TimingSafeEqualDep } from "../Crypto.js";
+import { LazyValue } from "../Function.js";
 import { Result } from "../Result.js";
 import { SqliteError } from "../Sqlite.js";
 import { SimpleName } from "../Type.js";
+import { OwnerId } from "./Owner.js";
+import { ProtocolInvalidDataError } from "./Protocol.js";
 import { CreateSqliteStorageBaseOptions, SqliteStorageDeps, Storage } from "./Storage.js";
 export interface Relay extends Disposable {
 }
 export interface RelayConfig extends ConsoleConfig {
+    /**
+     * The relay name.
+     *
+     * Implementations can use this for identification purposes (e.g., database
+     * file name, logging).
+     */
     readonly name?: SimpleName;
+    /**
+     * Optional callback to authenticate an {@link OwnerId} with the relay.
+     *
+     * If this callback is not provided, all owners are allowed.
+     *
+     * If provided, the callback receives the OwnerId and should return a promise
+     * that resolves to `true` to allow access, or `false` to deny.
+     *
+     * The callback returns a boolean rather than an error type because error
+     * handling and logging are the responsibility of the callback implementation,
+     * not the relay. This prevents leaking authentication implementation details
+     * into the generic relay interface.
+     *
+     * OwnerId is used for authentication rather than short-lived tokens because
+     * this only controls relay access, not write permissions. Since all data is
+     * encrypted on the relay, OwnerId exposure is safe.
+     *
+     * Owners specify which relays to connect to via {@link TransportConfig}. In
+     * WebSocket-based implementations, this check occurs before accepting the
+     * connection, with the OwnerId typically extracted from the URL path (e.g.,
+     * `ws://localhost:4000/<ownerId>`).
+     *
+     * ### Example
+     *
+     * ```ts
+     * const relay = await createNodeJsRelay(deps)({
+     *   authenticateOwner: async (ownerId) => {
+     *     const isRegistered = await db.checkOwner(ownerId);
+     *     if (!isRegistered) {
+     *       logger.warn("Unauthorized access attempt", { ownerId });
+     *     }
+     *     return isRegistered;
+     *   },
+     * });
+     * ```
+     */
+    readonly authenticateOwner?: (ownerId: OwnerId) => Promise<boolean>;
 }
-export type RelaySqliteStorageDeps = SqliteStorageDeps & TimingSafeEqualDep;
-export declare const createRelayStorage: (deps: RelaySqliteStorageDeps) => (options: CreateSqliteStorageBaseOptions) => Result<Storage, SqliteError>;
+export declare const createRelaySqliteStorage: (deps: SqliteStorageDeps & TimingSafeEqualDep) => (options: CreateSqliteStorageBaseOptions) => Result<Storage, SqliteError>;
+export interface RelayLogger {
+    readonly started: (enableLogging: boolean, port: number) => void;
+    readonly storageError: (error: unknown) => void;
+    readonly upgradeSocketError: (error: Error) => void;
+    readonly invalidOrMissingOwnerIdInUrl: (url: string | undefined) => void;
+    readonly unauthorizedOwner: (ownerId: OwnerId) => void;
+    readonly authenticateOwnerError: (error: unknown) => void;
+    readonly connectionEstablished: (totalConnectionCount: number) => void;
+    readonly connectionWebSocketError: (error: Error) => void;
+    readonly relayOptionSubscribe: (ownerId: OwnerId, getSubscriberCount: LazyValue<number>) => void;
+    readonly relayOptionUnsubscribe: (ownerId: OwnerId, getSubscriberCount: LazyValue<number>) => void;
+    readonly relayOptionBroadcast: (ownerId: OwnerId, broadcastCount: number, subscriberCount: number) => void;
+    readonly messageLength: (messageLength: number) => void;
+    readonly applyProtocolMessageAsRelayError: (error: ProtocolInvalidDataError) => void;
+    readonly responseLength: (responseLength: number) => void;
+    readonly applyProtocolMessageAsRelayUnknownError: (error: unknown) => void;
+    readonly connectionClosed: (totalConnectionCount: number) => void;
+    readonly shuttingDown: () => void;
+    readonly webSocketServerDisposed: () => void;
+    readonly httpServerDisposed: () => void;
+}
+export declare const createRelayLogger: (deps: ConsoleDep) => RelayLogger;
 //# sourceMappingURL=Relay.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Relay.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAW,MAAM,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAO,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAEL,8BAA8B,EAE9B,iBAAiB,EACjB,OAAO,EACR,MAAM,cAAc,CAAC;AAGtB,MAAM,WAAW,KAAM,SAAQ,UAAU;CAAG;AAE5C,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE5E,eAAO,MAAM,kBAAkB,GAC5B,MAAM,sBAAsB,MAC5B,SAAS,8BAA8B,KAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAiKrE,CAAC"}
+{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Relay.ts"],"names":[],"mappings":"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"}

package/dist/src/Evolu/Relay.js

@@ -3,7 +3,7 @@ import { err, ok } from "../Result.js";
 import { sql } from "../Sqlite.js";
 import { createSqliteStorageBase, } from "./Storage.js";
 import { timestampToTimestampBytes } from "./Timestamp.js";
-export const createRelayStorage = (deps) => (options) => {
+export const createRelaySqliteStorage = (deps) => (options) => {
     const sqliteStorageBase = createSqliteStorageBase(deps)(options);
     if (!sqliteStorageBase.ok)
         return sqliteStorageBase;
@@ -145,3 +145,76 @@ export const createRelayStorage = (deps) => (options) => {
         },
     });
 };
+export const createRelayLogger = (deps) => ({
+    started: (enableLogging, port) => {
+        deps.console.enabled = true;
+        deps.console.log(`Evolu Relay started on port ${port}`);
+        deps.console.enabled = enableLogging;
+    },
+    storageError: (error) => {
+        deps.console.error("[relay]", "storage", error);
+    },
+    upgradeSocketError: (error) => {
+        deps.console.warn("[relay]", "socket error", { error });
+    },
+    invalidOrMissingOwnerIdInUrl: (url) => {
+        deps.console.warn("[relay]", "invalid or missing ownerId in URL", { url });
+    },
+    unauthorizedOwner: (ownerId) => {
+        deps.console.warn("[relay]", "unauthorized owner", { ownerId });
+    },
+    authenticateOwnerError: (error) => {
+        deps.console.error("[relay]", "authenticateOwner error", error);
+    },
+    connectionEstablished: (totalConnectionCount) => {
+        deps.console.log("[relay]", "connection", { totalConnectionCount });
+    },
+    connectionWebSocketError: (error) => {
+        deps.console.error("[relay]", "error", { error });
+    },
+    relayOptionSubscribe: (ownerId, getSubscriberCount) => {
+        if (deps.console.enabled)
+            deps.console.log("[relay]", "subscribe", {
+                ownerId,
+                subscriberCount: getSubscriberCount(),
+            });
+    },
+    relayOptionUnsubscribe: (ownerId, getSubscriberCount) => {
+        if (deps.console.enabled)
+            deps.console.log("[relay]", "unsubscribe", {
+                ownerId,
+                subscriberCount: getSubscriberCount(),
+            });
+    },
+    relayOptionBroadcast: (ownerId, broadcastCount, totalSubscribers) => {
+        deps.console.log("[relay]", "broadcast", {
+            ownerId,
+            broadcastCount,
+            totalSubscribers,
+        });
+    },
+    messageLength: (messageLength) => {
+        deps.console.log("[relay]", "on message", { messageLength });
+    },
+    applyProtocolMessageAsRelayError: (error) => {
+        deps.console.error("[relay]", "applyProtocolMessageAsRelay", error);
+    },
+    responseLength: (responseLength) => {
+        deps.console.log("[relay]", "responseLength", { responseLength });
+    },
+    applyProtocolMessageAsRelayUnknownError: (error) => {
+        deps.console.error("[relay]", "applyProtocolMessageAsRelayUnknownError", error);
+    },
+    connectionClosed: (totalConnectionCount) => {
+        deps.console.log("[relay]", "close", { totalConnectionCount });
+    },
+    shuttingDown: () => {
+        deps.console.log("Shutting down Evolu Relay...");
+    },
+    webSocketServerDisposed: () => {
+        deps.console.log("Evolu Relay WebSocketServer disposed");
+    },
+    httpServerDisposed: () => {
+        deps.console.log("Evolu Relay HTTP server disposed");
+    },
+});

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

@@ -12,7 +12,7 @@ import { AppOwner, OwnerEncryptionKey, OwnerId, OwnerIdBytes, OwnerWriteKey, Tra
 import { ProtocolError, ProtocolInvalidDataError, ProtocolTimestampMismatchError } from "./Protocol.js";
 import { MutationChange } from "./Schema.js";
 import { CrdtMessage, SqliteStorageBase, Storage } from "./Storage.js";
-import { Millis, Timestamp, TimestampBytes, TimestampConfigDep, TimestampCounterOverflowError, TimestampDriftError, TimestampTimeOutOfRangeError } from "./Timestamp.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.
@@ -68,6 +68,7 @@ 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.
@@ -110,14 +111,4 @@ export interface PaymentRequiredError {
     readonly type: "PaymentRequiredError";
 }
 export declare const initialSyncState: SyncStateInitial;
-/**
- * Efficiently checks which binary timestamps already exist in the database
- * using a single CTE query instead of N individual queries. Crucial for WASM
- * SQLite performance where JS↔WASM boundary crossings are expensive.
- *
- * Used for fast idempotency detection in writeMessages before onMessage
- * validation. While applyMessages ensures internal idempotency, this pre-check
- * is faster and required for main thread message validation.
- */
-export declare const getExistingTimestamps: (deps: SqliteDep) => (ownerIdBytes: OwnerIdBytes, timestampsBytes: NonEmptyReadonlyArray<TimestampBytes>) => Result<ReadonlyArray<TimestampBytes>, SqliteError>;
 //# sourceMappingURL=Sync.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Sync.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Sync.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Sync.ts"],"names":[],"mappings":"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"}

package/dist/src/Evolu/Sync.js

@@ -1,5 +1,4 @@
 import { assert } from "../Assert.js";
-import { concatBytes } from "../Buffer.js";
 import { eqArrayNumber } from "../Eq.js";
 import { createTransferableError } from "../Error.js";
 import { constFalse } from "../Function.js";
@@ -351,7 +350,7 @@ export const applyLocalOnlyChange = (deps) => (change) => {
     }
     return ok();
 };
-const applyMessages = (deps) => (ownerId, messages) => {
+export const applyMessages = (deps) => (ownerId, messages) => {
     const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
     for (const message of messages) {
         const result1 = applyMessageToAppTable(deps)(ownerIdBytes, message);
@@ -369,30 +368,26 @@ const applyMessageToAppTable = (deps) => (ownerId, message) => {
     for (const [column, value] of objectToEntries(message.change.values)) {
         const result = deps.sqlite.exec(sql.prepared `
         with
-          lastTimestamp as (
-            select "timestamp"
+          existingTimestamp as (
+            select 1
             from evolu_history
             where
               "ownerId" = ${ownerId}
               and "table" = ${message.change.table}
-              and "id" = ${message.change.id}
+              and "id" = ${idToIdBytes(message.change.id)}
               and "column" = ${column}
-            order by "timestamp" desc
+              and "timestamp" >= ${timestamp}
             limit 1
           )
         insert into ${sql.identifier(message.change.table)}
           ("id", ${sql.identifier(column)}, updatedAt)
         select ${message.change.id}, ${value}, ${updatedAt}
-        where
-          (select "timestamp" from lastTimestamp) is null
-          or (select "timestamp" from lastTimestamp) < ${timestamp}
+        where not exists (select 1 from existingTimestamp)
         on conflict ("id") do update
           set
             ${sql.identifier(column)} = ${value},
             updatedAt = ${updatedAt}
-          where
-            (select "timestamp" from lastTimestamp) is null
-            or (select "timestamp" from lastTimestamp) < ${timestamp};
+          where not exists (select 1 from existingTimestamp);
       `);
         if (!result.ok)
             return result;
@@ -426,37 +421,3 @@ export const applyMessageToTimestampAndHistoryTables = (deps) => (ownerId, messa
     return ok();
 };
 export const initialSyncState = { type: "SyncStateInitial" };
-/**
- * Efficiently checks which binary timestamps already exist in the database
- * using a single CTE query instead of N individual queries. Crucial for WASM
- * SQLite performance where JS↔WASM boundary crossings are expensive.
- *
- * Used for fast idempotency detection in writeMessages before onMessage
- * validation. While applyMessages ensures internal idempotency, this pre-check
- * is faster and required for main thread message validation.
- */
-export const getExistingTimestamps = (deps) => (ownerIdBytes, timestampsBytes) => {
-    const concatenatedTimestamps = concatBytes(...timestampsBytes);
-    const result = deps.sqlite.exec(sql `
-      with recursive
-        split_timestamps(timestampBytes, pos) as (
-          select
-            substr(${concatenatedTimestamps}, 1, 16),
-            17 as pos
-          union all
-          select
-            substr(${concatenatedTimestamps}, pos, 16),
-            pos + 16
-          from split_timestamps
-          where pos <= length(${concatenatedTimestamps})
-        )
-      select s.timestampBytes
-      from
-        split_timestamps s
-        join evolu_timestamp t
-          on t.ownerId = ${ownerIdBytes} and s.timestampBytes = t.t;
-    `);
-    if (!result.ok)
-        return result;
-    return ok(result.value.rows.map((row) => row.timestampBytes));
-};

package/dist/src/Result.d.ts

@@ -228,23 +228,26 @@
  *
  * ### FAQ
  *
- * #### What if my function doesn't return a value on success?
+ * #### When should a function return a plain value instead of `Result<T, E>`?
  *
- * If your function performs an operation but doesn't need to return a value on
- * success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
- * than using `Result<true, E>` or `Result<null, E>` because it communicates
- * that the function doesn't produce a value but can produce errors.
+ * Use `Result<T, E>` only when a function can fail with **known, expected
+ * errors** that callers need to handle. If a function cannot fail with a known
+ * error, return the value directly.
+ *
+ * - ✅ Return `Result<User, UserNotFoundError>` - can fail with a known error
+ * - ✅ Return `User` - cannot fail with a known error
+ * - ❌ Don't return `Result<User, never>` - unnecessary wrapper
  *
- * #### When can a function return `void` instead of `Result<void, E>`?
+ * This keeps the codebase clean and makes error handling intentional. The type
+ * system communicates which operations can fail and which cannot.
  *
- * A function can safely return `void` (instead of `Result<void, E>`) when all
- * unsafe code within it is properly wrapped with `trySync` or `tryAsync`. If
- * developers consistently wrap all potentially throwing operations, then any
- * function returning `void` is guaranteed not to throw and can be called
- * without error handling.
+ * Unsafe code from external libraries (not under our control) should be wrapped
+ * with `trySync` or `tryAsync` at the boundaries. Once wrapped, if the error is
+ * not important to callers, functions can safely return plain values. If the
+ * error matters, use `Result` with a typed error.
  *
  * ```ts
- * // ✅ Safe to return void - all unsafe code is wrapped
+ * // ✅ Safe to return void - unsafe code is wrapped and error is handled
  * const processData = (data: string): void => {
  *   const parseResult = trySync(
  *     () => JSON.parse(data),
@@ -252,7 +255,7 @@
  *   );
  *
  *   if (!parseResult.ok) {
- *     logError(parseResult.error); // Handle error appropriately
+ *     logError(parseResult.error);
  *     return;
  *   }
  *
@@ -263,9 +266,12 @@
  * processData(jsonString);
  * ```
  *
- * This approach creates a clear contract: functions returning `void` are safe
- * to call, while functions returning `Result<T, E>` require explicit error
- * handling.
+ * #### What if my function doesn't return a value on success?
+ *
+ * If your function performs an operation but doesn't need to return a value on
+ * success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
+ * than using `Result<true, E>` or `Result<null, E>` because it communicates
+ * that the function doesn't produce a value but can produce errors.
  *
  * #### How do I short-circuit processing of an array on the first error?
  *
@@ -441,6 +447,29 @@ export declare const err: <E>(error: E) => Err<E>;
  * Throws: `Error` with the original error attached as `cause`.
  */
 export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
+/**
+ * Extracts the value from a {@link Result} if it is an `Ok`, or returns `null`
+ * if it is an `Err`.
+ *
+ * **Intended usage:**
+ *
+ * - When you need to convert a `Result` to a nullable value for APIs that expect
+ *   `T | null`.
+ * - When the error is not important and you just want the value or nothing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const parseResult = parseJson('{"key": "value"}');
+ * const value = getOrNull(parseResult);
+ * // value is unknown | null
+ *
+ * if (value != null) {
+ *   console.log("Parsed value:", value);
+ * }
+ * ```
+ */
+export declare const getOrNull: <T, E>(result: Result<T, E>) => T | null;
 /**
  * Wraps synchronous functions that may throw exceptions, returning a
  * {@link Result}.

package/dist/src/Result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../../src/Result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmUG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAE1C,mCAAmC;AACnC,MAAM,WAAW,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC5C,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC7C,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/B,2DAA2D;AAC3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAKvC;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,GAAG,CAAC,CAAC,CAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAMvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAC1B,IAAI,MAAM,CAAC,EACX,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,MAAM,CAAC,CAAC,EAAE,CAAC,CAMb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EACjC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAIpB,CAAC"}
+{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../../src/Result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyUG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAE1C,mCAAmC;AACnC,MAAM,WAAW,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC5C,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC7C,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/B,2DAA2D;AAC3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAKvC;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,GAAG,CAAC,CAAC,CAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAMvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,GAAG,IAC1B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAC1B,IAAI,MAAM,CAAC,EACX,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,MAAM,CAAC,CAAC,EAAE,CAAC,CAMb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EACjC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAIpB,CAAC"}