@evolu/common 6.0.1-preview.8 → 7.0.0

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

@@ -1,8 +1,8 @@
-import { NanoIdLibDep } from "../NanoId.js";
+import { RandomBytesDep } from "../Crypto.js";
 import { Order } from "../Order.js";
 import { Result } from "../Result.js";
 import { TimeDep } from "../Time.js";
-import { Brand } from "../Types.js";
+import { DateIso, InferType } from "../Type.js";
 export interface TimestampConfig {
     /**
      * Maximum physical clock drift allowed in ms.
@@ -14,7 +14,7 @@ export interface TimestampConfig {
 export interface TimestampConfigDep {
     readonly timestampConfig: TimestampConfig;
 }
-export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError;
+export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError;
 export interface TimestampDriftError {
     readonly type: "TimestampDriftError";
     readonly next: Millis;
@@ -23,10 +23,6 @@ export interface TimestampDriftError {
 export interface TimestampCounterOverflowError {
     readonly type: "TimestampCounterOverflowError";
 }
-export interface TimestampDuplicateNodeError {
-    readonly type: "TimestampDuplicateNodeError";
-    readonly nodeId: NodeId;
-}
 export interface TimestampTimeOutOfRangeError {
     readonly type: "TimestampTimeOutOfRangeError";
 }
@@ -42,11 +38,11 @@ export interface TimestampTimeOutOfRangeError {
  *
  * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
  */
-export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & import("../Brand.js").Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
 export type Millis = typeof Millis.Type;
 export declare const minMillis: Millis;
 export declare const maxMillis: Millis;
-export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & import("../Brand.js").Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
 export type Counter = typeof Counter.Type;
 export declare const minCounter: Counter;
 export declare const maxCounter: Counter;
@@ -63,14 +59,17 @@ export declare const maxCounter: Counter;
  *
  * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
  *
- * What will happen if a different device generates the same NodeId?
+ * What happens if different devices generate the same NodeId?
  *
- * If the device belongs to a different owner, nothing will happen because
- * different owner have different owner IDs. Timestamps are partitioned by
- * OwnerId.
+ * If devices with the same NodeId use different owners, no issues occur.
  *
- * If the device belongs to the same owner, the other device will return
- * {@link TimestampDuplicateNodeError}.
+ * If devices with the same NodeId use the same owner, problems only arise when
+ * they generate CRDT messages with identical timestamps (same millis, counter,
+ * and NodeId). In this case, the protocol sync algorithm treats them as the
+ * same message: the first will be synced with the relay, while the affected
+ * message will not be delivered. The affected devices will see different data
+ * 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 declare const NodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
 export type NodeId = typeof NodeId.Type;
@@ -79,28 +78,82 @@ export declare const maxNodeId: NodeId;
 /**
  * Hybrid Logical Clock timestamp.
  *
+ * Timestamps serve as globally unique, causally ordered identifiers for CRDT
+ * messages in Evolu's sync protocol.
+ *
+ * ### 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
+ * clocks while staying close to physical time for better human
+ * interpretability.
+ *
+ * The counter component ensures causality is maintained even when physical
+ * clocks are imperfect. When clocks drift or operations occur concurrently, the
+ * counter increments to establish a total order. This means Evolu achieves
+ * well-defined, eventually-consistent behavior regardless of physical clock
+ * accuracy.
+ *
+ * Vector clocks can accurately track causality and detect concurrent
+ * operations, but they require unbounded space in peer-to-peer systems and
+ * crucially, still don't solve our fundamental problem: when they detect
+ * operations as concurrent, we still need a deterministic way to choose a
+ * winner. Additionally, any deterministic conflict resolution can be gamed by
+ * malicious actors.
+ *
+ * HLC timestamps work well in practice because modern device clocks accurately
+ * reflect the order of sequential edits in the common case. Evolu's `maxDrift`
+ * configuration protects against buggy clocks and prevents problematic
+ * future-dated entries from propagating through the network.
+ *
+ * ### 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
+ *
+ * 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
+ * avoid it if maximum privacy is required.
+ *
+ * With real-time communication, participants always see activity (receiving
+ * bytes). We cannot trust anyone not to store that information, so explicitly
+ * exposing timestamps doesn't add additional risk.
+ *
+ * If we really want not to leak user activity, we can implement a local write
+ * queue:
+ *
+ * 1. Write changes immediately to a local-only table
+ * 2. Periodically and randomly flush messages to sync tables
+ *
+ * **Trade-off:** It breaks real-time collaboration.
  */
 export declare const Timestamp: import("../Type.js").ObjectType<{
-    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
-    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & import("../Brand.js").Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & import("../Brand.js").Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
     nodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
 }>;
-export type Timestamp = typeof Timestamp.Type;
+export interface Timestamp extends InferType<typeof Timestamp> {
+}
+/** Equality function for comparing {@link Timestamp}. */
+export declare const eqTimestamp: import("../Eq.js").Eq<{
+    readonly millis: number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative"> & import("../Brand.js").Brand<`LessThanOrEqualTo${number}`> & import("../Brand.js").Brand<"Millis">;
+    readonly counter: number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative"> & import("../Brand.js").Brand<"LessThanOrEqualTo65535"> & import("../Brand.js").Brand<"Counter">;
+    readonly nodeId: string & import("../Brand.js").Brand<"NodeId">;
+}>;
 export declare const createTimestamp: ({ millis, counter, nodeId, }?: Partial<Timestamp>) => Timestamp;
-export declare const createInitialTimestamp: (deps: NanoIdLibDep) => Timestamp;
-/** TimestampString is a sortable string version of {@link Timestamp}. */
-export type TimestampString = string & Brand<"TimestampString">;
-export declare const timestampToTimestampString: (t: Timestamp) => TimestampString;
-export declare const timestampStringToTimestamp: (timestampString: TimestampString) => Timestamp;
+export declare const createInitialTimestamp: (deps: RandomBytesDep) => Timestamp;
 export declare const sendTimestamp: (deps: TimeDep & TimestampConfigDep) => (timestamp: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
-export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError>;
-/** BinaryTimestamp is a binary and sortable version of {@link Timestamp} for DB. */
-export type BinaryTimestamp = Uint8Array & Brand<"BinaryTimestamp">;
-export declare const binaryTimestampLength: number & Brand<"Int"> & Brand<"NonNegative">;
-export declare const timestampToBinaryTimestamp: (timestamp: Timestamp) => BinaryTimestamp;
-export declare const binaryTimestampToTimestamp: (timestamp: BinaryTimestamp) => Timestamp;
-export declare const orderBinaryTimestamp: Order<BinaryTimestamp>;
+export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
+/** Sortable bytes representation of {@link Timestamp}. */
+export declare const TimestampBytes: import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, "TimestampBytes", import("../Type.js").BrandWithoutRefineError<"TimestampBytes", import("../Type.js").Uint8ArrayError>, never>;
+export type TimestampBytes = typeof TimestampBytes.Type;
+export declare const timestampBytesLength: number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative">;
+export declare const timestampToTimestampBytes: (timestamp: Timestamp) => TimestampBytes;
+export declare const timestampBytesToTimestamp: (timestamp: TimestampBytes) => Timestamp;
+export declare const orderTimestampBytes: Order<TimestampBytes>;
+export declare const timestampToDateIso: (timestamp: Timestamp) => DateIso;
 //# sourceMappingURL=Timestamp.d.ts.map

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

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

package/dist/src/Evolu/Timestamp.js

@@ -1,8 +1,9 @@
-import { assert } from "../Assert.js";
+import { bytesToHex } from "../Buffer.js";
+import { createEqObject, eqNumber, eqString } from "../Eq.js";
 import { increment } from "../Number.js";
 import { orderUint8Array } from "../Order.js";
-import { err, getOrThrow, ok } from "../Result.js";
-import { brand, lessThanOrEqualTo, NonNegativeInt, object, regex, String, } from "../Type.js";
+import { err, ok } from "../Result.js";
+import { brand, lessThanOrEqualTo, NonNegativeInt, object, regex, String, Uint8Array, } from "../Type.js";
 /**
  * Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
  * maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
@@ -34,14 +35,17 @@ export const maxCounter = 65535;
  *
  * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
  *
- * What will happen if a different device generates the same NodeId?
+ * What happens if different devices generate the same NodeId?
  *
- * If the device belongs to a different owner, nothing will happen because
- * different owner have different owner IDs. Timestamps are partitioned by
- * OwnerId.
+ * If devices with the same NodeId use different owners, no issues occur.
  *
- * If the device belongs to the same owner, the other device will return
- * {@link TimestampDuplicateNodeError}.
+ * If devices with the same NodeId use the same owner, problems only arise when
+ * they generate CRDT messages with identical timestamps (same millis, counter,
+ * and NodeId). In this case, the protocol sync algorithm treats them as the
+ * same message: the first will be synced with the relay, while the affected
+ * message will not be delivered. The affected devices will see different data
+ * 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 minNodeId = "0000000000000000";
@@ -49,36 +53,75 @@ export const maxNodeId = "ffffffffffffffff";
 /**
  * Hybrid Logical Clock timestamp.
  *
+ * Timestamps serve as globally unique, causally ordered identifiers for CRDT
+ * messages in Evolu's sync protocol.
+ *
+ * ### 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
+ * clocks while staying close to physical time for better human
+ * interpretability.
+ *
+ * The counter component ensures causality is maintained even when physical
+ * clocks are imperfect. When clocks drift or operations occur concurrently, the
+ * counter increments to establish a total order. This means Evolu achieves
+ * well-defined, eventually-consistent behavior regardless of physical clock
+ * accuracy.
+ *
+ * Vector clocks can accurately track causality and detect concurrent
+ * operations, but they require unbounded space in peer-to-peer systems and
+ * crucially, still don't solve our fundamental problem: when they detect
+ * operations as concurrent, we still need a deterministic way to choose a
+ * winner. Additionally, any deterministic conflict resolution can be gamed by
+ * malicious actors.
+ *
+ * HLC timestamps work well in practice because modern device clocks accurately
+ * reflect the order of sequential edits in the common case. Evolu's `maxDrift`
+ * configuration protects against buggy clocks and prevents problematic
+ * future-dated entries from propagating through the network.
+ *
+ * ### 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
+ *
+ * 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
+ * avoid it if maximum privacy is required.
+ *
+ * With real-time communication, participants always see activity (receiving
+ * bytes). We cannot trust anyone not to store that information, so explicitly
+ * exposing timestamps doesn't add additional risk.
+ *
+ * If we really want not to leak user activity, we can implement a local write
+ * queue:
+ *
+ * 1. Write changes immediately to a local-only table
+ * 2. Periodically and randomly flush messages to sync tables
+ *
+ * **Trade-off:** It breaks real-time collaboration.
  */
 export const Timestamp = object({
     millis: Millis,
     counter: Counter,
     nodeId: NodeId,
 });
+/** Equality function for comparing {@link Timestamp}. */
+export const eqTimestamp = createEqObject({
+    millis: eqNumber,
+    counter: eqNumber,
+    nodeId: eqString,
+});
 export const createTimestamp = ({ millis = minMillis, counter = minCounter, nodeId = minNodeId, } = {}) => ({ millis, counter, nodeId });
-const hexAlphabet = "0123456789abcdef";
 export const createInitialTimestamp = (deps) => {
-    const nodeId = deps.nanoIdLib.customAlphabet(hexAlphabet, 16)();
+    const nodeId = bytesToHex(deps.randomBytes.create(8));
     return createTimestamp({ nodeId });
 };
-export const timestampToTimestampString = (t) => [
-    new Date(t.millis).toISOString(),
-    t.counter.toString(16).toUpperCase().padStart(4, "0"),
-    t.nodeId,
-].join("-");
-export const timestampStringToTimestamp = (timestampString) => {
-    const array = timestampString.split("-");
-    const timestamp = {
-        millis: Date.parse(array.slice(0, 3).join("-")).valueOf(),
-        counter: parseInt(array[3], 16),
-        nodeId: array[4],
-    };
-    assert(Timestamp.is(timestamp), "timestampString is malformed");
-    return timestamp;
-};
 const getNextMillis = (deps) => (millis) => {
     const now = Millis.from(deps.time.now());
     if (!now.ok) {
@@ -115,9 +158,6 @@ export const sendTimestamp = (deps) => (timestamp) => {
     });
 };
 export const receiveTimestamp = (deps) => (local, remote) => {
-    if (local.nodeId === remote.nodeId) {
-        return err({ type: "TimestampDuplicateNodeError", nodeId: local.nodeId });
-    }
     const millis = getNextMillis(deps)([local.millis, remote.millis]);
     if (!millis.ok)
         return millis;
@@ -136,11 +176,13 @@ export const receiveTimestamp = (deps) => (local, remote) => {
         nodeId: local.nodeId,
     });
 };
-export const binaryTimestampLength = getOrThrow(NonNegativeInt.from(16));
-export const timestampToBinaryTimestamp = (timestamp) => {
+/** Sortable bytes representation of {@link Timestamp}. */
+export const TimestampBytes = brand("TimestampBytes", Uint8Array);
+export const timestampBytesLength = NonNegativeInt.orThrow(16);
+export const timestampToTimestampBytes = (timestamp) => {
     const { millis, counter, nodeId } = timestamp;
     // 6 bytes for millis, 2 bytes for counter, 8 bytes for nodeId.
-    const value = new Uint8Array(16);
+    const value = new globalThis.Uint8Array(16);
     // Encode `millis` into the first 6 bytes.
     const millisBigInt = BigInt(millis);
     value[0] = Number((millisBigInt >> 40n) & 0xffn);
@@ -159,7 +201,7 @@ export const timestampToBinaryTimestamp = (timestamp) => {
     }
     return value;
 };
-export const binaryTimestampToTimestamp = (timestamp) => {
+export const timestampBytesToTimestamp = (timestamp) => {
     // Decode `millis` from the first 6 bytes.
     const millis = (BigInt(timestamp[0]) << 40n) |
         (BigInt(timestamp[1]) << 32n) |
@@ -176,4 +218,7 @@ export const binaryTimestampToTimestamp = (timestamp) => {
     }
     return { millis: Number(millis), counter, nodeId };
 };
-export const orderBinaryTimestamp = orderUint8Array;
+export const orderTimestampBytes = orderUint8Array;
+export const timestampToDateIso = (timestamp) => 
+// `as DateIso` is safe because the timestamp is always valid
+new Date(timestamp.millis).toISOString();

package/dist/src/Identicon.d.ts

@@ -0,0 +1,35 @@
+import type { Brand } from "./Brand.js";
+import { Id } from "./Type.js";
+/**
+ * SVG string representing a visual identicon for an {@link Id}, created with
+ * {@link createIdenticon}.
+ */
+export type Identicon = string & Brand<"Identicon">;
+/** {@link Identicon} style. */
+export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
+/**
+ * Creates a deterministic identicon SVG from an {@link Id}.
+ *
+ * Works with any {@link Id} including branded IDs like `OwnerId`, etc.
+ *
+ * Available styles:
+ *
+ * - `"github"` (default): 5x5 grid with horizontal mirroring (GitHub-style)
+ * - `"quadrant"`: 2x2 grid with direct RGB color mapping from bytes
+ * - `"gradient"`: Diagonal stripes with smooth color gradients
+ * - `"sutnar"`: Three compositional variants with adaptive colors
+ *
+ * ### Example
+ *
+ * ```ts
+ * const svg = createIdenticon(id);
+ * const quadrantStyle = createIdenticon(id, "quadrant");
+ * const gradientStyle = createIdenticon(id, "gradient");
+ * const sutnarStyle = createIdenticon(id, "sutnar");
+ *
+ * // Works with branded IDs
+ * const ownerSvg = createIdenticon(ownerId);
+ * ```
+ */
+export declare const createIdenticon: (id: Id, style?: IdenticonStyle) => Identicon;
+//# sourceMappingURL=Identicon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAG5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,EAAE,EACN,QAAO,cAAyB,KAC/B,SA4JF,CAAC"}

package/dist/src/Identicon.js

@@ -0,0 +1,143 @@
+import { idToIdBytes } from "./Type.js";
+import { md5 } from "@noble/hashes/legacy.js";
+/**
+ * Creates a deterministic identicon SVG from an {@link Id}.
+ *
+ * Works with any {@link Id} including branded IDs like `OwnerId`, etc.
+ *
+ * Available styles:
+ *
+ * - `"github"` (default): 5x5 grid with horizontal mirroring (GitHub-style)
+ * - `"quadrant"`: 2x2 grid with direct RGB color mapping from bytes
+ * - `"gradient"`: Diagonal stripes with smooth color gradients
+ * - `"sutnar"`: Three compositional variants with adaptive colors
+ *
+ * ### Example
+ *
+ * ```ts
+ * const svg = createIdenticon(id);
+ * const quadrantStyle = createIdenticon(id, "quadrant");
+ * const gradientStyle = createIdenticon(id, "gradient");
+ * const sutnarStyle = createIdenticon(id, "sutnar");
+ *
+ * // Works with branded IDs
+ * const ownerSvg = createIdenticon(ownerId);
+ * ```
+ */
+export const createIdenticon = (id, style = "github") => {
+    const bytes = idToIdBytes(id);
+    switch (style) {
+        case "github": {
+            // GitHub-style identicon: MD5 hash the bytes first
+            const hashedBytes = md5(bytes);
+            // Map function for value ranges
+            const map = (value, inMin, inMax, outMin, outMax) => ((value - inMin) * (outMax - outMin)) / (inMax - inMin) + outMin;
+            // Extract 12-bit hue from bytes[12] (lower 4 bits) + bytes[13]
+            const h = ((hashedBytes[12] & 0x0f) << 8) | hashedBytes[13];
+            const hue = map(h, 0, 4095, 0, 360);
+            const saturation = 65 - map(hashedBytes[14], 0, 255, 0, 20);
+            const lightness = 75 - map(hashedBytes[15], 0, 255, 0, 20);
+            const fgColor = `hsl(${hue},${saturation}%,${lightness}%)`;
+            const bgColor = `hsl(${hue},${saturation}%,90%)`;
+            let rects = `<rect width="5" height="5" fill="${bgColor}"/>`;
+            // Extract nibbles and generate pattern
+            let nibbleIndex = 0;
+            for (let x = 2; x >= 0; x--) {
+                for (let y = 0; y < 5; y++) {
+                    const byte = hashedBytes[Math.floor(nibbleIndex / 2)];
+                    const nibble = nibbleIndex % 2 === 0 ? byte >> 4 : byte & 0x0f;
+                    const paint = nibble % 2 === 0;
+                    nibbleIndex++;
+                    if (paint) {
+                        rects += `<rect x="${x}" y="${y}" width="1" height="1" fill="${fgColor}"/>`;
+                        const mx = 4 - x;
+                        if (mx !== x) {
+                            rects += `<rect x="${mx}" y="${y}" width="1" height="1" fill="${fgColor}"/>`;
+                        }
+                    }
+                }
+            }
+            return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 5 5" shape-rendering="crispEdges">${rects}</svg>`;
+        }
+        case "quadrant": {
+            const toHex = (b) => b.toString(16).padStart(2, "0");
+            let rects = "";
+            for (let i = 0; i < 4; i++) {
+                const x = i % 2;
+                const y = Math.floor(i / 2);
+                const r = bytes[i * 3];
+                const g = bytes[i * 3 + 1];
+                const b = bytes[i * 3 + 2];
+                const color = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+                rects += `<rect x="${x}" y="${y}" width="1" height="1" fill="${color}"/>`;
+            }
+            return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2 2">${rects}</svg>`;
+        }
+        case "gradient": {
+            // Smooth color gradients with diagonal stripes.
+            const toHex = (b) => b.toString(16).padStart(2, "0");
+            // Generate colors from bytes.
+            const color1 = `#${toHex(bytes[0])}${toHex(bytes[1])}${toHex(bytes[2])}`;
+            const color2 = `#${toHex(bytes[3])}${toHex(bytes[4])}${toHex(bytes[5])}`;
+            const color3 = `#${toHex(bytes[6])}${toHex(bytes[7])}${toHex(bytes[8])}`;
+            let defs = "";
+            let shapes = "";
+            // Diagonal stripes with gradient.
+            defs += `<linearGradient id="grad1-${id}" x1="0%" y1="0%" x2="0%" y2="100%">`;
+            defs += `<stop offset="0%" style="stop-color:${color1};stop-opacity:1" />`;
+            defs += `<stop offset="100%" style="stop-color:${color2};stop-opacity:1" />`;
+            defs += `</linearGradient>`;
+            defs += `<linearGradient id="grad2-${id}" x1="0%" y1="0%" x2="0%" y2="100%">`;
+            defs += `<stop offset="0%" style="stop-color:${color2};stop-opacity:1" />`;
+            defs += `<stop offset="100%" style="stop-color:${color3};stop-opacity:1" />`;
+            defs += `</linearGradient>`;
+            shapes += `<rect width="100" height="100" fill="url(#grad1-${id})"/>`;
+            const stripeWidth = 15 + (bytes[9] / 255) * 20;
+            const angle = 30 + (bytes[10] / 255) * 60;
+            shapes += `<rect x="20" y="-50" width="${stripeWidth}" height="200" fill="url(#grad2-${id})" transform="rotate(${angle} 50 50)" opacity="0.7"/>`;
+            shapes += `<rect x="60" y="-50" width="${stripeWidth}" height="200" fill="url(#grad2-${id})" transform="rotate(${angle} 50 50)" opacity="0.5"/>`;
+            return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><defs>${defs}</defs>${shapes}</svg>`;
+        }
+        case "sutnar": {
+            // Three compositional variants with adaptive colors.
+            const hue = (bytes[0] / 255) * 360;
+            const saturation = 50 + (bytes[1] / 255) * 30;
+            const lightness = 50 + (bytes[2] / 255) * 20;
+            // Generate palette from base hue with variations
+            const toHsl = (h, s, l) => `hsl(${h},${s}%,${l}%)`;
+            const color1 = toHsl(hue, saturation, lightness);
+            const color2 = toHsl((hue + 120) % 360, saturation, lightness);
+            const color3 = toHsl((hue + 240) % 360, saturation, lightness);
+            const color4 = toHsl(hue, saturation * 0.3, lightness * 0.5);
+            const color5 = toHsl(hue, saturation * 0.5, Math.min(lightness * 1.3, 90));
+            const palette = [color1, color2, color3, color4, color5];
+            // Layout variant based on first byte.
+            const variant = bytes[3] % 3;
+            let shapes = "";
+            // Almost white background with subtle tint.
+            shapes += `<rect width="100" height="100" fill="${toHsl(hue, 10, 95)}"/>`;
+            if (variant === 0) {
+                // Composition A: Circle + horizontal bar.
+                const circleColor = palette[bytes[4] % palette.length];
+                const barColor = palette[(bytes[4] + 1) % palette.length];
+                shapes += `<circle cx="30" cy="50" r="22" fill="${circleColor}"/>`;
+                shapes += `<rect x="60" y="40" width="35" height="20" fill="${barColor}"/>`;
+            }
+            else if (variant === 1) {
+                // Composition B: Vertical bar + circle.
+                const barColor = palette[bytes[5] % palette.length];
+                const circleColor = palette[(bytes[5] + 1) % palette.length];
+                shapes += `<rect x="15" y="10" width="18" height="80" fill="${barColor}"/>`;
+                shapes += `<circle cx="70" cy="50" r="15" fill="${circleColor}"/>`;
+            }
+            else {
+                // Composition C: Square + circle.
+                const squareColor = palette[bytes[6] % palette.length];
+                const circleColor = palette[(bytes[6] + 1) % palette.length];
+                shapes += `<rect x="20" y="20" width="30" height="30" fill="${squareColor}"/>`;
+                shapes += `<circle cx="70" cy="70" r="18" fill="${circleColor}"/>`;
+            }
+            return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shapes}</svg>`;
+        }
+    }
+};

package/dist/src/Instances.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"Instances.d.ts","sourceRoot":"","sources":["../../src/Instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,UAAU,CAC/D,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

@@ -0,0 +1,44 @@
+/** 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");
+            }
+        },
+    };
+};