@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/local-first/Sync.js

@@ -1,529 +0,0 @@
-import { appendToArray, firstInArray, isNonEmptyReadonlyArray, } from "../Array.js";
-import { assert, assertNonEmptyReadonlyArray } from "../Assert.js";
-import { eqArrayNumber } from "../Eq.js";
-import { createTransferableError } from "../Error.js";
-import { constFalse, constTrue } from "../Function.js";
-import { createRecord, getProperty, objectToEntries } from "../Object.js";
-import { createResources } from "../Resources.js";
-import { err, ok } from "../Result.js";
-import { booleanToSqliteBoolean, sql, SqliteBoolean, sqliteBooleanToBoolean, } from "../Sqlite.js";
-import { createMutex } from "../Task.js";
-import { Boolean, idBytesToId, idToIdBytes, } from "../Type.js";
-import { ownerIdBytesToOwnerId, ownerIdToOwnerIdBytes, } from "./Owner.js";
-import { applyProtocolMessageAsClient, createProtocolMessageForSync, createProtocolMessageForUnsubscribe, createProtocolMessageFromCrdtMessages, decryptAndDecodeDbChange, encodeAndEncryptDbChange, SubscriptionFlags, } from "./Protocol.js";
-import { systemColumns } from "./Schema.js";
-import { createBaseSqliteStorage, DbChange, getOwnerUsage, getTimestampInsertStrategy, updateOwnerUsage, } from "./Storage.js";
-import { createInitialTimestamp, receiveTimestamp, sendTimestamp, timestampBytesToTimestamp, timestampToDateIso, timestampToTimestampBytes, } from "./Timestamp.js";
-export const createSync = (deps) => (config) => {
-    let isDisposed = false;
-    /** Returns owner data only if actively assigned to at least one transport. */
-    const getSyncOwner = (ownerId) => {
-        if (isDisposed)
-            return null;
-        return resources.getConsumer(ownerId);
-    };
-    const storageResult = createClientStorage({
-        ...deps,
-        getSyncOwner,
-    })(config);
-    if (!storageResult.ok)
-        return storageResult;
-    const storage = storageResult.value;
-    const createResource = (transport) => {
-        const transportKey = createTransportKey(transport);
-        deps.console.log("[sync]", "createWebSocket", {
-            transportKey,
-            url: transport.url,
-        });
-        return deps.createWebSocket(transport.url, {
-            binaryType: "arraybuffer",
-            onOpen: () => {
-                if (isDisposed)
-                    return;
-                const webSocket = resources.getResource(transportKey);
-                if (!webSocket)
-                    return;
-                const ownerIds = resources.getConsumersForResource(transportKey);
-                deps.console.log("[sync]", "onOpen", { transportKey, ownerIds });
-                for (const ownerId of ownerIds) {
-                    const message = createProtocolMessageForSync({ storage })(ownerId, SubscriptionFlags.Subscribe);
-                    if (!message)
-                        continue;
-                    deps.console.log("[sync]", "send", { message });
-                    webSocket.send(message);
-                }
-            },
-            onClose: (event) => {
-                deps.console.log("[sync]", "onClose", {
-                    transportKey,
-                    code: event.code,
-                    reason: event.reason,
-                    wasClean: event.wasClean,
-                });
-            },
-            onError: (error) => {
-                deps.console.warn("[sync]", "onError", { transportKey, error });
-            },
-            onMessage: (data) => {
-                // Only handle ArrayBuffer data for sync messages
-                if (isDisposed || !(data instanceof ArrayBuffer))
-                    return;
-                const webSocket = resources.getResource(transportKey);
-                if (!webSocket)
-                    return;
-                const input = new Uint8Array(data);
-                deps.console.log("[sync]", "onMessage", {
-                    transportKey,
-                    message: input,
-                });
-                applyProtocolMessageAsClient({ storage })(input, {
-                    // No write key, no sync (for a case when an owner was unused).
-                    getWriteKey: (ownerId) => getSyncOwner(ownerId)?.writeKey ?? null,
-                })
-                    .then((message) => {
-                    if (!message.ok) {
-                        config.onError(message.error);
-                        return;
-                    }
-                    switch (message.value.type) {
-                        case "response":
-                            webSocket.send(message.value.message);
-                            break;
-                        case "no-response":
-                            // Sync complete, no response needed
-                            break;
-                        case "broadcast":
-                            // This was a broadcast message, don't affect sync counter
-                            break;
-                    }
-                })
-                    .catch((error) => {
-                    config.onError(createTransferableError(error));
-                });
-            },
-        });
-    };
-    const resources = createResources({
-        createResource,
-        getResourceKey: createTransportKey,
-        getConsumerId: (owner) => owner.id,
-        disposalDelay: config.disposalDelayMs ?? 100,
-        onConsumerAdded: (owner, webSocket) => {
-            deps.console.log("[sync]", "onConsumerAdded", {
-                ownerId: owner.id,
-                isOpen: webSocket.isOpen(),
-            });
-            // The onOpen handler will sync it.
-            if (!webSocket.isOpen())
-                return;
-            const message = createProtocolMessageForSync({ storage })(owner.id, SubscriptionFlags.Subscribe);
-            if (message)
-                webSocket.send(message);
-        },
-        onConsumerRemoved: (owner, webSocket) => {
-            deps.console.log("[sync]", "onConsumerRemoved", {
-                ownerId: owner.id,
-                isOpen: webSocket.isOpen(),
-            });
-            const message = createProtocolMessageForUnsubscribe(owner.id);
-            webSocket.send(message);
-        },
-    });
-    const sync = {
-        useOwner: (use, owner) => {
-            if (isDisposed) {
-                deps.console.warn("[sync]", "useOwner called on disposed Sync instance", { owner });
-                return;
-            }
-            deps.console.log("[sync]", "useOwner", { use, owner });
-            const transports = owner.transports ?? config.transports;
-            if (use) {
-                resources.addConsumer(owner, transports);
-            }
-            else {
-                const result = resources.removeConsumer(owner, transports);
-                if (!result.ok) {
-                    deps.console.warn("[sync]", "Failed to remove consumer", {
-                        transports,
-                        ownerId: owner.id,
-                        error: result.error,
-                    });
-                }
-            }
-        },
-        applyChanges: (changes) => {
-            deps.console.log("[sync]", "applyChanges", { changes });
-            let clockTimestamp = deps.clock.get();
-            const ownerMessages = new Map();
-            for (const change of changes) {
-                const nextTimestamp = sendTimestamp(deps)(clockTimestamp);
-                if (!nextTimestamp.ok)
-                    return nextTimestamp;
-                clockTimestamp = nextTimestamp.value;
-                const { ownerId = config.appOwner.id, ...dbChange } = change;
-                const message = {
-                    timestamp: clockTimestamp,
-                    change: dbChange,
-                };
-                const messages = ownerMessages.get(ownerId);
-                if (messages)
-                    messages.push(message);
-                else
-                    ownerMessages.set(ownerId, [message]);
-            }
-            for (const [ownerId, messages] of ownerMessages) {
-                const result = applyMessages({ ...deps, storage })(ownerId, messages);
-                if (!result.ok)
-                    return result;
-                const owner = getSyncOwner(ownerId);
-                if (!owner?.writeKey)
-                    continue;
-                const message = createProtocolMessageFromCrdtMessages(deps)({
-                    id: owner.id,
-                    encryptionKey: owner.encryptionKey,
-                    writeKey: owner.writeKey,
-                }, messages);
-                const transports = owner.transports ?? config.transports;
-                // Send message to all transports for this owner
-                for (const transport of transports) {
-                    const transportKey = createTransportKey(transport);
-                    const webSocket = resources.getResource(transportKey);
-                    if (!webSocket)
-                        continue;
-                    if (webSocket.isOpen()) {
-                        deps.console.log("[sync]", "send", { transportKey, message });
-                        webSocket.send(message);
-                    }
-                }
-            }
-            return deps.clock.save(clockTimestamp);
-        },
-        [Symbol.dispose]: () => {
-            if (isDisposed)
-                return;
-            isDisposed = true;
-            resources[Symbol.dispose]();
-        },
-    };
-    return ok(sync);
-};
-export const createClock = (deps) => (initialTimestamp = createInitialTimestamp(deps)) => {
-    let currentTimestamp = initialTimestamp;
-    return {
-        get: () => currentTimestamp,
-        save: (timestamp) => {
-            currentTimestamp = timestamp;
-            const result = deps.sqlite.exec(sql.prepared `
-          update evolu_config
-          set "clock" = ${timestampToTimestampBytes(timestamp)};
-        `);
-            if (!result.ok)
-                return result;
-            return ok();
-        },
-    };
-};
-const createClientStorage = (deps) => (config) => {
-    const sqliteStorageBase = createBaseSqliteStorage(deps)({
-        onStorageError: config.onError,
-        isOwnerWithinQuota: constTrue, // Clients don't have quota limits
-    });
-    // TODO: Mutex per OwnerId
-    const mutex = createMutex();
-    const storage = {
-        ...sqliteStorageBase,
-        // Not implemented yet.
-        validateWriteKey: constFalse,
-        setWriteKey: constFalse,
-        writeMessages: async (ownerIdBytes, encryptedMessages) => {
-            const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
-            // Everything is sync now, but we will need async crypto in the future.
-            const result = await mutex.withLock(async () => {
-                const owner = deps.getSyncOwner(ownerId);
-                // Owner can be removed during syncing.
-                // `ok(true)` means success, we just skipped the write.
-                if (!owner)
-                    return ok(true);
-                // TODO: Add quota checking for collaborative scenarios.
-                // When receiving messages from other owners via relay broadcast,
-                // check if this owner is within quota before accepting the data.
-                // This prevents an owner from exceeding storage limits when receiving
-                // data shared by other collaborators.
-                const messages = [];
-                for (const message of encryptedMessages) {
-                    const change = decryptAndDecodeDbChange(deps)(message, owner.encryptionKey);
-                    if (!change.ok)
-                        return change;
-                    messages.push({
-                        timestamp: message.timestamp,
-                        change: change.value,
-                    });
-                }
-                const transaction = deps.sqlite.transaction(() => {
-                    let clockTimestamp = deps.clock.get();
-                    for (const message of messages) {
-                        const nextTimestamp = receiveTimestamp(deps)(clockTimestamp, message.timestamp);
-                        if (!nextTimestamp.ok)
-                            return nextTimestamp;
-                        clockTimestamp = nextTimestamp.value;
-                    }
-                    if (isNonEmptyReadonlyArray(messages)) {
-                        const result = applyMessages({ ...deps, storage })(owner.id, messages);
-                        if (!result.ok)
-                            return result;
-                    }
-                    return deps.clock.save(clockTimestamp);
-                });
-                if (!transaction.ok)
-                    return transaction;
-                return ok(true);
-            })();
-            if (!result.ok) {
-                if (result.error.type !== "AbortError") {
-                    config.onError(result.error);
-                }
-                return err({ type: "StorageWriteError", ownerId });
-            }
-            config.onReceive();
-            return ok();
-        },
-        readDbChange: (ownerId, timestamp) => {
-            const owner = deps.getSyncOwner(ownerIdBytesToOwnerId(ownerId));
-            // Owner can be removed to stop syncing.
-            if (!owner)
-                return null;
-            const result = deps.sqlite.exec(sql `
-          select "table", "id", "column", "value"
-          from evolu_history
-          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp}
-          union all
-          select "table", "id", "column", "value"
-          from evolu_message_quarantine
-          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
-        `);
-            if (!result.ok) {
-                config.onError(result.error);
-                return null;
-            }
-            const { rows } = result.value;
-            assertNonEmptyReadonlyArray(rows, "Every timestamp must have rows in evolu_history or quarantine");
-            const { table, id } = firstInArray(rows);
-            const values = createRecord();
-            let isInsert;
-            let isDelete = null;
-            for (const r of rows) {
-                assert(r.table === table, "All rows must have the same table");
-                assert(eqArrayNumber(r.id, id), "All rows must have the same Id");
-                switch (r.column) {
-                    case "createdAt":
-                        isInsert = true;
-                        break;
-                    case "updatedAt":
-                        isInsert = false;
-                        break;
-                    case "isDeleted":
-                        assert(SqliteBoolean.is(r.value), "isDeleted column must contain a valid SqliteBoolean");
-                        isDelete = sqliteBooleanToBoolean(r.value);
-                        break;
-                    default:
-                        values[r.column] = r.value;
-                }
-            }
-            assert(Boolean.is(isInsert), "isInsert must be in evolu_history");
-            const message = {
-                timestamp: timestampBytesToTimestamp(timestamp),
-                change: DbChange.orThrow({
-                    table: rows[0].table,
-                    id: idBytesToId(rows[0].id),
-                    values,
-                    isInsert,
-                    isDelete,
-                }),
-            };
-            return encodeAndEncryptDbChange(deps)(message, owner.encryptionKey);
-        },
-    };
-    return ok(storage);
-};
-/** Creates a unique identifier for a {@link OwnerTransport}. */
-const createTransportKey = (transport) => {
-    return `${transport.type}:${transport.url}`;
-};
-const dbChangeToColumns = (change, now) => {
-    let values = objectToEntries(change.values);
-    // SystemColumns are not encoded in change.values.
-    values = appendToArray(values, [
-        change.isInsert ? "createdAt" : "updatedAt",
-        now,
-    ]);
-    if (change.isDelete != null) {
-        values = appendToArray(values, [
-            "isDeleted",
-            booleanToSqliteBoolean(change.isDelete),
-        ]);
-    }
-    return values;
-};
-export const applyLocalOnlyChange = (deps) => (change) => {
-    if (change.isDelete) {
-        const result = deps.sqlite.exec(sql `
-        delete from ${sql.identifier(change.table)}
-        where id = ${change.id};
-      `);
-        if (!result.ok)
-            return result;
-    }
-    else {
-        const ownerId = deps.appOwner.id;
-        const columns = dbChangeToColumns(change, deps.time.nowIso());
-        for (const [column, value] of columns) {
-            const result = deps.sqlite.exec(sql.prepared `
-          insert into ${sql.identifier(change.table)}
-            ("ownerId", "id", ${sql.identifier(column)})
-          values (${ownerId}, ${change.id}, ${value})
-          on conflict ("ownerId", "id") do update
-            set ${sql.identifier(column)} = ${value};
-        `);
-            if (!result.ok)
-                return result;
-        }
-    }
-    return ok();
-};
-const applyMessages = (deps) => (ownerId, messages) => {
-    const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
-    const usage = getOwnerUsage(deps)(ownerIdBytes, timestampToTimestampBytes(firstInArray(messages).timestamp));
-    if (!usage.ok)
-        return usage;
-    let { firstTimestamp, lastTimestamp } = usage.value;
-    for (const { timestamp, change } of messages) {
-        const columns = dbChangeToColumns(change, timestampToDateIso(timestamp));
-        const idBytes = idToIdBytes(change.id);
-        const timestampBytes = timestampToTimestampBytes(timestamp);
-        for (const [column, value] of columns) {
-            if (validateColumnValue(deps)(change.table, column, value)) {
-                const result = applyColumnChange(deps)(ownerIdBytes, ownerId, change.table, idBytes, change.id, column, value, timestampBytes);
-                if (!result.ok)
-                    return result;
-            }
-            else {
-                const result = deps.sqlite.exec(sql.prepared `
-            insert into evolu_message_quarantine
-              ("ownerId", "timestamp", "table", "id", "column", "value")
-            values
-              (
-                ${ownerIdBytes},
-                ${timestampBytes},
-                ${change.table},
-                ${idBytes},
-                ${column},
-                ${value}
-              )
-            on conflict do nothing;
-          `);
-                if (!result.ok)
-                    return result;
-            }
-        }
-        let strategy;
-        [strategy, firstTimestamp, lastTimestamp] = getTimestampInsertStrategy(timestampBytes, firstTimestamp, lastTimestamp);
-        const result = deps.storage.insertTimestamp(ownerIdBytes, timestampBytes, strategy);
-        if (!result.ok)
-            return result;
-    }
-    /**
-     * TODO: Implement proper storedBytes tracking for client using received and
-     * sent encrypted message sizes.
-     */
-    return updateOwnerUsage(deps)(ownerIdBytes, 1, // Placeholder until proper tracking implemented
-    firstTimestamp, lastTimestamp);
-};
-/**
- * System columns that can appear in sync messages. Excludes `ownerId` because
- * it's handled separately (stored per-row, not per-column in messages).
- */
-const systemColumnsWithoutOwnerId = systemColumns.difference(new Set(["ownerId"]));
-const validateColumnValue = (deps) => (table, column, _value) => {
-    const schemaColumns = getProperty(deps.dbSchema.tables, table);
-    return (schemaColumns != null &&
-        (systemColumnsWithoutOwnerId.has(column) || schemaColumns.has(column)));
-};
-const applyColumnChange = (deps) => (ownerIdBytes, ownerId, table, idBytes, id, column, value, timestampBytes) => {
-    const result = deps.sqlite.exec(sql.prepared `
-      with
-        existingTimestamp as (
-          select 1
-          from evolu_history
-          where
-            "ownerId" = ${ownerIdBytes}
-            and "table" = ${table}
-            and "id" = ${idBytes}
-            and "column" = ${column}
-            and "timestamp" >= ${timestampBytes}
-          limit 1
-        )
-      insert into ${sql.identifier(table)}
-        ("ownerId", "id", ${sql.identifier(column)})
-      select ${ownerId}, ${id}, ${value}
-      where not exists (select 1 from existingTimestamp)
-      on conflict ("ownerId", "id") do update
-        set ${sql.identifier(column)} = ${value}
-        where not exists (select 1 from existingTimestamp);
-    `);
-    if (!result.ok)
-        return result;
-    {
-        const result = deps.sqlite.exec(sql.prepared `
-        insert into evolu_history
-          ("ownerId", "table", "id", "column", "value", "timestamp")
-        values
-          (
-            ${ownerIdBytes},
-            ${table},
-            ${idBytes},
-            ${column},
-            ${value},
-            ${timestampBytes}
-          )
-        on conflict do nothing;
-      `);
-        if (!result.ok)
-            return result;
-    }
-    return ok();
-};
-/**
- * Attempts to apply quarantined messages that may now be valid after a schema
- * update. Messages are quarantined when they reference tables or columns that
- * don't exist in the current schema (e.g., from a newer app version).
- */
-export const tryApplyQuarantinedMessages = (deps) => () => {
-    const rows = deps.sqlite.exec(sql `
-      select "ownerId", "timestamp", "table", "id", "column", "value"
-      from evolu_message_quarantine;
-    `);
-    if (!rows.ok)
-        return rows;
-    for (const row of rows.value.rows) {
-        if (!validateColumnValue(deps)(row.table, row.column, row.value))
-            continue;
-        const result = applyColumnChange(deps)(row.ownerId, ownerIdBytesToOwnerId(row.ownerId), row.table, row.id, idBytesToId(row.id), row.column, row.value, row.timestamp);
-        if (!result.ok)
-            return result;
-        {
-            const result = deps.sqlite.exec(sql `
-          delete from evolu_message_quarantine
-          where
-            "ownerId" = ${row.ownerId}
-            and "timestamp" = ${row.timestamp}
-            and "table" = ${row.table}
-            and "id" = ${row.id}
-            and "column" = ${row.column};
-        `);
-            if (!result.ok)
-                return result;
-        }
-    }
-    return ok();
-};
-export const initialSyncState = { type: "SyncStateInitial" };

package/src/Instances.ts

@@ -1,90 +0,0 @@
-/**
- * Manages disposable instances by key, ensuring exactly one instance per key.
- *
- * Use cases:
- *
- * - One mutex per key to prevent concurrent writes
- * - Preserving state during hot module reloading
- *
- * **Important:** Do not use this as global shared state. Use it locally or pass
- * it as a dependency instead. The only exception is for hot reloading support,
- * where Evolu uses it to ensure only one instance exists across module reloads
- * (having two Evolu instances with the same name would mean two SQLite
- * connections to the same file, which could corrupt data).
- */
-export interface Instances<K extends string, T extends Disposable>
-  extends Disposable {
-  /**
-   * Ensures an instance exists for the given key, creating it if necessary. If
-   * the instance already exists, the optional `onCacheHit` callback is invoked
-   * to update the existing instance.
-   */
-  readonly ensure: (
-    key: K,
-    create: () => T,
-    onCacheHit?: (instance: T) => void,
-  ) => T;
-
-  /** Gets an instance by key, or returns `null` if it doesn't exist. */
-  readonly get: (key: K) => T | null;
-
-  /** Checks if an instance exists for the given key. */
-  readonly has: (key: K) => boolean;
-
-  /**
-   * Deletes and disposes an instance by key. Returns `true` if the instance
-   * existed and was deleted, `false` otherwise.
-   */
-  readonly delete: (key: K) => boolean;
-}
-
-/** Creates an {@link Instances}. */
-export const createInstances = <
-  K extends string,
-  T extends Disposable,
->(): Instances<K, T> => {
-  const instances = new Map<K, T>();
-
-  return {
-    ensure: (key, create, onCacheHit) => {
-      let instance = instances.get(key);
-
-      if (instance == null) {
-        instance = create();
-        instances.set(key, instance);
-      } else if (onCacheHit) {
-        onCacheHit(instance);
-      }
-
-      return instance;
-    },
-
-    get: (key) => instances.get(key) ?? null,
-
-    has: (key) => instances.has(key),
-
-    delete: (key) => {
-      const instance = instances.get(key);
-      if (instance == null) return false;
-      instances.delete(key);
-      instance[Symbol.dispose]();
-      return true;
-    },
-
-    [Symbol.dispose]: () => {
-      const errors: Array<unknown> = [];
-      for (const instance of instances.values()) {
-        try {
-          instance[Symbol.dispose]();
-        } catch (error) {
-          errors.push(error);
-        }
-      }
-      instances.clear();
-      if (errors.length === 1) throw errors[0];
-      if (errors.length > 1) {
-        throw new AggregateError(errors, "Multiple disposal errors occurred");
-      }
-    },
-  };
-};