@evolu/common 7.4.1 → 8.0.0-next.0

package/src/local-first/Timestamp.ts

@@ -1,14 +1,23 @@
+/**
+ * Hybrid logical clock timestamps for CRDT ordering.
+ *
+ * @module
+ */
+
 import { bytesToHex } from "../Buffer.js";
-import { RandomBytesDep } from "../Crypto.js";
+import type { RandomBytesDep } from "../Crypto.js";
 import { createEqObject, eqNumber, eqString } from "../Eq.js";
 import { increment } from "../Number.js";
-import { Order, orderUint8Array } from "../Order.js";
-import { err, ok, Result } from "../Result.js";
-import { TimeDep } from "../Time.js";
+import type { Order } from "../Order.js";
+import { orderUint8Array } from "../Order.js";
+import type { Result } from "../Result.js";
+import { err, ok } from "../Result.js";
+import type { TimeDep } from "../Time.js";
+import { Millis, minMillis } from "../Time.js";
+import type { DateIso, InferType, Typed } from "../Type.js";
 import {
   brand,
-  DateIso,
-  InferType,
+  length,
   lessThanOrEqualTo,
   NonNegativeInt,
   object,
@@ -26,6 +35,9 @@ export interface TimestampConfig {
   readonly maxDrift: number;
 }
 
+/** Default value for {@link TimestampConfig.maxDrift}. */
+export const defaultTimestampMaxDrift = 5 * 60 * 1000;
+
 export interface TimestampConfigDep {
   readonly timestampConfig: TimestampConfig;
 }
@@ -35,44 +47,18 @@ export type TimestampError =
   | TimestampCounterOverflowError
   | TimestampTimeOutOfRangeError;
 
-export interface TimestampDriftError {
-  readonly type: "TimestampDriftError";
+export interface TimestampDriftError extends Typed<"TimestampDriftError"> {
   readonly next: Millis;
   readonly now: Millis;
 }
 
-export interface TimestampCounterOverflowError {
-  readonly type: "TimestampCounterOverflowError";
-}
-
-export interface TimestampTimeOutOfRangeError {
-  readonly type: "TimestampTimeOutOfRangeError";
-}
-
-/**
- * Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
- * maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
- * for infinity). This enables more efficient binary serialization, saving 2
- * bytes compared to the typical 8-byte (64-bit) timestamp representation.
- *
- * This limit is enforced to prevent data corruption. If a device's clock
- * exceeds this range, Evolu will stop saving data until the clock is
- * corrected.
- *
- * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
- */
-export const Millis = brand(
-  "Millis",
-  lessThanOrEqualTo(281474976710655 - 1)(NonNegativeInt),
-);
-export type Millis = typeof Millis.Type;
+export interface TimestampCounterOverflowError extends Typed<"TimestampCounterOverflowError"> {}
 
-export const minMillis = 0 as Millis;
-export const maxMillis = (281474976710655 - 1) as Millis;
+export interface TimestampTimeOutOfRangeError extends Typed<"TimestampTimeOutOfRangeError"> {}
 
-export const Counter = brand(
+export const Counter = /*#__PURE__*/ brand(
   "Counter",
-  lessThanOrEqualTo(65535)(NonNegativeInt),
+  /*#__PURE__*/ lessThanOrEqualTo(65535)(NonNegativeInt),
 );
 export type Counter = typeof Counter.Type;
 
@@ -104,7 +90,7 @@ export const maxCounter = 65535 as Counter;
  * yet they will think they are synced. This is extremely rare and can be
  * resolved by resetting one device to generate a new NodeId.
  */
-export const NodeId = regex("NodeId", /^[a-f0-9]{16}$/)(String);
+export const NodeId = /*#__PURE__*/ regex("NodeId", /^[a-f0-9]{16}$/)(String);
 export type NodeId = typeof NodeId.Type;
 
 export const minNodeId = "0000000000000000" as NodeId;
@@ -116,7 +102,7 @@ export const maxNodeId = "ffffffffffffffff" as NodeId;
  * Timestamps serve as globally unique, causally ordered identifiers for CRDT
  * messages in Evolu's sync protocol.
  *
- * ### Why Hybrid Logical Clocks
+ * ## Why Hybrid Logical Clocks
  *
  * Evolu uses Hybrid Logical Clocks (HLC), which combine physical time (millis)
  * with a logical counter. This hybrid approach preserves causality like logical
@@ -141,14 +127,14 @@ export const maxNodeId = "ffffffffffffffff" as NodeId;
  * configuration protects against buggy clocks and prevents problematic
  * future-dated entries from propagating through the network.
  *
- * ### References
+ * ## References
  *
  * - https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
  * - https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
  * - https://jaredforsyth.com/posts/hybrid-logical-clocks/
  * - https://willowprotocol.org/more/timestamps_really/index.html
  *
- * ### Privacy Considerations
+ * ## Privacy Considerations
  *
  * Timestamps are metadata visible to relays and collaborators. While it can be
  * considered a privacy leak, let us explain why it's necessary, and how to
@@ -165,8 +151,12 @@ export const maxNodeId = "ffffffffffffffff" as NodeId;
  * 2. Periodically and randomly flush messages to sync tables
  *
  * **Trade-off:** It breaks real-time collaboration.
+ *
+ * Another technique is generating fake random activity (dummy messages) to mask
+ * real usage patterns. This preserves real-time collaboration but increases
+ * storage and bandwidth usage.
  */
-export const Timestamp = object({
+export const Timestamp = /*#__PURE__*/ object({
   millis: Millis,
   counter: Counter,
   nodeId: NodeId,
@@ -174,7 +164,7 @@ export const Timestamp = object({
 export interface Timestamp extends InferType<typeof Timestamp> {}
 
 /** Equality function for comparing {@link Timestamp}. */
-export const eqTimestamp = createEqObject<Timestamp>({
+export const eqTimestamp = /*#__PURE__*/ createEqObject<Timestamp>({
   millis: eqNumber,
   counter: eqNumber,
   nodeId: eqString,
@@ -277,10 +267,13 @@ export const receiveTimestamp =
   };
 
 /** Sortable bytes representation of {@link Timestamp}. */
-export const TimestampBytes = brand("TimestampBytes", Uint8Array);
+export const TimestampBytes = /*#__PURE__*/ brand(
+  "TimestampBytes",
+  /*#__PURE__*/ length(16)(Uint8Array),
+);
 export type TimestampBytes = typeof TimestampBytes.Type;
 
-export const timestampBytesLength = NonNegativeInt.orThrow(16);
+export const timestampBytesLength = /*#__PURE__*/ NonNegativeInt.orThrow(16);
 
 export const timestampToTimestampBytes = (
   timestamp: Timestamp,

package/src/local-first/index.ts

@@ -1,25 +1,11 @@
-/**
- * Internal local-first modules re-exported from "@evolu/common/local-first"
- *
- * These exports expose the internal building blocks of Evolu's local-first
- * implementation (Db, Relay, Sync, Query, Storage, Timestamp, etc.). They are
- * primarily intended for use within Evolu packages and for advanced use-cases
- * that require direct access to local-first internals.
- *
- * Public consumers should us top-level exports from `@evolu/common` unless you
- * have a specific need to import these internals.
- *
- * @module
- */
-
 export * from "./Db.js";
+export * from "./Error.js";
 export * from "./Evolu.js";
 export * from "./Owner.js";
-export * from "./Platform.js";
 export * from "./Protocol.js";
 export * from "./Query.js";
 export * from "./Relay.js";
 export * from "./Schema.js";
+export * from "./Shared.js";
 export * from "./Storage.js";
-export * from "./Sync.js";
 export * from "./Timestamp.js";

package/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2023 Evolu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/src/Instances.d.ts

@@ -1,34 +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 declare const createInstances: <K extends string, T extends Disposable>() => Instances<K, T>;
-//# sourceMappingURL=Instances.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Instances.d.ts","sourceRoot":"","sources":["../../src/Instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS,CACxB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,UAAU,CACpB,SAAQ,UAAU;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CACf,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,MAAM,CAAC,EACf,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,KAC/B,CAAC,CAAC;IAEP,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAEnC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;CACtC;AAED,oCAAoC;AACpC,eAAO,MAAM,eAAe,GAC1B,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,UAAU,OACjB,SAAS,CAAC,CAAC,EAAE,CAAC,CA6ClB,CAAC"}

package/dist/src/Instances.js

@@ -1,44 +0,0 @@
-/** Creates an {@link Instances}. */
-export const createInstances = () => {
-    const instances = new Map();
-    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 = [];
-            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");
-            }
-        },
-    };
-};

package/dist/src/Resources.d.ts

@@ -1,118 +0,0 @@
-import { Result } from "./Result.js";
-/**
- * A generic resource manager that handles reference counting and delayed
- * disposal of shared resources. Useful for managing expensive resources like
- * WebSocket connections that need to be shared among multiple consumers.
- */
-export interface Resources<TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string> extends Disposable {
-    /**
-     * Adds a consumer to resources, creating them if necessary. Increments
-     * reference counts for existing consumer-resource pairs.
-     */
-    readonly addConsumer: (consumer: TConsumer, resourceConfigs: ReadonlyArray<TResourceConfig>) => void;
-    /**
-     * Removes a consumer from resources. Decrements reference counts and
-     * schedules disposal when no consumers remain.
-     *
-     * Returns an error if the resource doesn't exist or if the consumer wasn't
-     * added to the resource.
-     */
-    readonly removeConsumer: (consumer: TConsumer, resourceConfigs: ReadonlyArray<TResourceConfig>) => Result<void, ResourceNotFoundError<TResourceKey> | ConsumerNotFoundError<TConsumerId, TResourceKey>>;
-    /** Gets the resource for the specified key, or null if it doesn't exist. */
-    readonly getResource: (key: TResourceKey) => TResource | null;
-    /** Gets all consumer IDs currently using the specified resource key. */
-    readonly getConsumersForResource: (key: TResourceKey) => ReadonlyArray<TConsumerId>;
-    /** Checks if a consumer is currently using any resources. */
-    readonly hasConsumerAnyResource: (consumer: TConsumer) => boolean;
-    /**
-     * Gets the consumer for the specified consumer ID, or null if not found or
-     * not using any resources.
-     */
-    readonly getConsumer: (consumerId: TConsumerId) => TConsumer | null;
-}
-/** Error when trying to remove a consumer from a resource that doesn't exist. */
-export interface ResourceNotFoundError<TResourceKey extends string = string> {
-    readonly type: "ResourceNotFoundError";
-    readonly resourceKey: TResourceKey;
-}
-/** Error when trying to remove a consumer that wasn't added to a resource. */
-export interface ConsumerNotFoundError<TConsumerId extends string = string, TResourceKey extends string = string> {
-    readonly type: "ConsumerNotFoundError";
-    readonly consumerId: TConsumerId;
-    readonly resourceKey: TResourceKey;
-}
-export interface ResourcesConfig<TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string> {
-    /** Creates a new resource for the given config. */
-    readonly createResource: (config: TResourceConfig) => TResource;
-    /** Extracts a unique key from a resource config for deduplication. */
-    readonly getResourceKey: (config: TResourceConfig) => TResourceKey;
-    /** Extracts a unique identifier from a consumer for reference counting. */
-    readonly getConsumerId: (consumer: TConsumer) => TConsumerId;
-    /**
-     * Delay in milliseconds before disposing unused resources. Helps avoid
-     * resource churn during rapid add/remove cycles. Defaults to 100ms.
-     */
-    readonly disposalDelay?: number;
-    /**
-     * Called when a consumer is added to a resource for the first time. This
-     * happens when the consumer's reference count goes from 0 to 1 for this
-     * resource.
-     */
-    readonly onConsumerAdded?: (consumer: TConsumer, resource: TResource, resourceKey: TResourceKey) => void;
-    /**
-     * Called when a consumer is completely removed from a resource. This happens
-     * when the consumer's reference count goes from 1 to 0 for this resource.
-     */
-    readonly onConsumerRemoved?: (consumer: TConsumer, resource: TResource, resourceKey: TResourceKey) => void;
-}
-/**
- * Creates {@link Resources}.
- *
- * This tracks which consumers are using which resources and maintains reference
- * counts to know when it's safe to dispose resources. Resources are created
- * on-demand and disposed with a configurable delay to avoid churn.
- *
- * ### Example Usage
- *
- * ```ts
- * // WebSocket connections
- * interface WebSocketConfig {
- *   readonly url: WebSocketUrl;
- * }
- *
- * type WebSocketUrl = string & Brand<"WebSocketUrl">;
- * type UserId = string & Brand<"UserId">;
- *
- * const webSockets = createResources<
- *   WebSocket,
- *   WebSocketUrl,
- *   WebSocketConfig,
- *   User,
- *   UserId
- * >({
- *   createResource: (config) => new WebSocket(config.url),
- *   getResourceKey: (config) => config.url,
- *   getConsumerId: (user) => user.id,
- *   disposalDelay: 1000,
- * });
- *
- * // Add users to WebSocket connections
- * webSockets.addConsumer(user1, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- *   { url: "ws://server2.com" as WebSocketUrl },
- * ]);
- * webSockets.addConsumer(user2, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- * ]);
- *
- * // Remove users - server1 stays alive (user2 still using it)
- * webSockets.removeConsumer(user1, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- *   { url: "ws://server2.com" as WebSocketUrl },
- * ]);
- *
- * // server2 gets disposed after delay, server1 stays alive
- * ```
- */
-export declare const createResources: <TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string>(config: ResourcesConfig<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>) => Resources<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>;
-//# sourceMappingURL=Resources.d.ts.map

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

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

package/dist/src/Resources.js

@@ -1,197 +0,0 @@
-import { err, ok } from "./Result.js";
-import { PositiveInt } from "./Type.js";
-/**
- * Creates {@link Resources}.
- *
- * This tracks which consumers are using which resources and maintains reference
- * counts to know when it's safe to dispose resources. Resources are created
- * on-demand and disposed with a configurable delay to avoid churn.
- *
- * ### Example Usage
- *
- * ```ts
- * // WebSocket connections
- * interface WebSocketConfig {
- *   readonly url: WebSocketUrl;
- * }
- *
- * type WebSocketUrl = string & Brand<"WebSocketUrl">;
- * type UserId = string & Brand<"UserId">;
- *
- * const webSockets = createResources<
- *   WebSocket,
- *   WebSocketUrl,
- *   WebSocketConfig,
- *   User,
- *   UserId
- * >({
- *   createResource: (config) => new WebSocket(config.url),
- *   getResourceKey: (config) => config.url,
- *   getConsumerId: (user) => user.id,
- *   disposalDelay: 1000,
- * });
- *
- * // Add users to WebSocket connections
- * webSockets.addConsumer(user1, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- *   { url: "ws://server2.com" as WebSocketUrl },
- * ]);
- * webSockets.addConsumer(user2, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- * ]);
- *
- * // Remove users - server1 stays alive (user2 still using it)
- * webSockets.removeConsumer(user1, [
- *   { url: "ws://server1.com" as WebSocketUrl },
- *   { url: "ws://server2.com" as WebSocketUrl },
- * ]);
- *
- * // server2 gets disposed after delay, server1 stays alive
- * ```
- */
-export const createResources = (config) => {
-    let isDisposed = false;
-    const resourcesMap = new Map();
-    const consumerCounts = new Map();
-    const consumers = new Map();
-    const disposalTimeouts = new Map();
-    const disposalDelay = config.disposalDelay ?? 100;
-    const ensureResource = (resourceConfig) => {
-        const key = config.getResourceKey(resourceConfig);
-        const timeout = disposalTimeouts.get(key);
-        if (timeout) {
-            clearTimeout(timeout);
-            disposalTimeouts.delete(key);
-        }
-        if (!resourcesMap.has(key)) {
-            const resource = config.createResource(resourceConfig);
-            resourcesMap.set(key, resource);
-        }
-    };
-    const scheduleDisposal = (key) => {
-        const timeout = setTimeout(() => {
-            const resource = resourcesMap.get(key);
-            if (resource) {
-                resource[Symbol.dispose]();
-                resourcesMap.delete(key);
-            }
-            disposalTimeouts.delete(key);
-        }, disposalDelay);
-        disposalTimeouts.set(key, timeout);
-    };
-    const resources = {
-        addConsumer: (consumer, resourceConfigs) => {
-            if (isDisposed)
-                return;
-            const consumerId = config.getConsumerId(consumer);
-            // Store consumer (last added consumer for this ID)
-            consumers.set(consumerId, consumer);
-            for (const resourceConfig of resourceConfigs) {
-                ensureResource(resourceConfig);
-                const resourceKey = config.getResourceKey(resourceConfig);
-                let counts = consumerCounts.get(resourceKey);
-                if (!counts) {
-                    counts = new Map();
-                    consumerCounts.set(resourceKey, counts);
-                }
-                const currentCount = counts.get(consumerId) ?? 0;
-                const newCount = currentCount + 1;
-                counts.set(consumerId, PositiveInt.orThrow(newCount));
-                // Call onConsumerAdded callback only when consumer is added for the first time (0 -> 1)
-                if (currentCount === 0 && config.onConsumerAdded) {
-                    const resource = resourcesMap.get(resourceKey);
-                    if (resource) {
-                        config.onConsumerAdded(consumer, resource, resourceKey);
-                    }
-                }
-            }
-        },
-        removeConsumer: (consumer, resourceConfigs) => {
-            if (isDisposed)
-                return ok();
-            const consumerId = config.getConsumerId(consumer);
-            for (const resourceConfig of resourceConfigs) {
-                const key = config.getResourceKey(resourceConfig);
-                const counts = consumerCounts.get(key);
-                if (!counts) {
-                    return err({ type: "ResourceNotFoundError", resourceKey: key });
-                }
-                const currentCount = counts.get(consumerId);
-                if (currentCount == null) {
-                    return err({
-                        type: "ConsumerNotFoundError",
-                        consumerId: consumerId,
-                        resourceKey: key,
-                    });
-                }
-                if (currentCount === 1) {
-                    counts.delete(consumerId);
-                    // Call onConsumerRemoved callback only when consumer is completely removed (1 -> 0)
-                    if (config.onConsumerRemoved) {
-                        const resource = resourcesMap.get(key);
-                        if (resource) {
-                            config.onConsumerRemoved(consumer, resource, key);
-                        }
-                    }
-                    if (counts.size === 0) {
-                        consumerCounts.delete(key);
-                        scheduleDisposal(key);
-                    }
-                }
-                else {
-                    counts.set(consumerId, PositiveInt.orThrow(currentCount - 1));
-                }
-            }
-            if (!resources.hasConsumerAnyResource(consumer)) {
-                consumers.delete(consumerId);
-            }
-            return ok();
-        },
-        getResource: (key) => {
-            if (isDisposed)
-                return null;
-            return resourcesMap.get(key) ?? null;
-        },
-        getConsumersForResource: (key) => {
-            if (isDisposed)
-                return [];
-            const counts = consumerCounts.get(key);
-            return counts ? Array.from(counts.keys()) : [];
-        },
-        hasConsumerAnyResource: (consumer) => {
-            if (isDisposed)
-                return false;
-            const consumerId = config.getConsumerId(consumer);
-            // If slow, can be optimized with reverse index
-            return Array.from(consumerCounts.values()).some((counts) => counts.has(consumerId));
-        },
-        getConsumer: (consumerId) => {
-            if (isDisposed)
-                return null;
-            const consumer = consumers.get(consumerId);
-            if (!consumer)
-                return null;
-            // Only return consumer if it's currently using any resources
-            if (!resources.hasConsumerAnyResource(consumer)) {
-                return null;
-            }
-            return consumer;
-        },
-        [Symbol.dispose]: () => {
-            if (isDisposed)
-                return;
-            isDisposed = true;
-            for (const timeout of disposalTimeouts.values()) {
-                clearTimeout(timeout);
-            }
-            disposalTimeouts.clear();
-            for (const resource of resourcesMap.values()) {
-                resource[Symbol.dispose]();
-            }
-            resourcesMap.clear();
-            consumerCounts.clear();
-            consumers.clear();
-        },
-    };
-    return resources;
-};

package/dist/src/local-first/Platform.d.ts

@@ -1,25 +0,0 @@
-/**
- * FlushSync is for libraries like React to flush updates synchronously inside
- * the provided callback to ensure the DOM is updated immediately.
- *
- * For example, with React, when we want to focus on an element rendered as a
- * result of a mutation, Evolu ensures all DOM changes are flushed synchronously
- * if an onComplete callback is used.
- *
- * https://react.dev/reference/react-dom/flushSync
- */
-export type FlushSync = (callback: () => void) => void;
-export interface FlushSyncDep {
-    readonly flushSync: FlushSync;
-}
-/**
- * Reload the app in a platform-specific way.
- *
- * - **Web**: Redirects to the specified URL
- * - **React Native**: Restarts the app (URL parameter ignored)
- */
-export type ReloadApp = (url: string) => void;
-export interface ReloadAppDep {
-    readonly reloadApp: ReloadApp;
-}
-//# sourceMappingURL=Platform.d.ts.map

package/dist/src/local-first/Platform.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../../src/local-first/Platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B"}

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

@@ -1 +0,0 @@
-export {};

package/dist/src/local-first/Public.d.ts

@@ -1,22 +0,0 @@
-/**
- * Public local-first API exported from "@evolu/common"
- *
- * This module provides the supported consumer-facing API for Evolu's
- * local-first system: prefer importing from `@evolu/common` (this module) when
- * using Evolu in applications. If you require access to lower level internals,
- * consider importing from `@evolu/common/local-first`.
- *
- * @module
- */
-export { createEvolu } from "./Evolu.js";
-export type { Evolu, EvoluConfig, EvoluDeps, EvoluError } from "./Evolu.js";
-export type { UnuseOwner } from "./Evolu.js";
-export * from "./LocalAuth.js";
-export * from "./Owner.js";
-export * as kysely from "./PublicKysely.js";
-export type { InferRow, Query, QueryRows, Row } from "./Query.js";
-export type { EvoluSchema } from "./Schema.js";
-export type { NetworkError, PaymentRequiredError, ServerError, SyncOwner, SyncState, SyncStateInitial, SyncStateIsNotSynced, SyncStateIsSynced, SyncStateIsSyncing, } from "./Sync.js";
-export { Timestamp, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
-export type { TimestampBytes, TimestampCounterOverflowError, TimestampDriftError, TimestampError, TimestampTimeOutOfRangeError, } from "./Timestamp.js";
-//# sourceMappingURL=Public.d.ts.map