@evolu/common 8.10.0 → 8.12.0

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

@@ -1,19 +1,259 @@
 /**
  * Hybrid logical clock timestamps for CRDT ordering.
  *
+ * Every change to a synced table becomes a CRDT message stamped with a
+ * {@link Timestamp}. The timestamp is the message's identity for sync, which
+ * reconciles sets of timestamps between devices and relays, and its order for
+ * conflicts, which last-writer-wins resolves per column by comparing
+ * timestamps. Each database keeps one clock. It advances when stamping local
+ * changes to synced tables and accepting incoming messages, so later writes
+ * sort after earlier local writes and accepted messages.
+ *
+ * A device whose system clock is ahead produces future timestamps. They can
+ * override edits made later in real time on devices that have not yet accepted
+ * them. Accepting one advances the receiver's logical clock, so its later
+ * writes sort after the accepted message and carry future timestamps too, even
+ * before system time catches up. That propagation preserves ordering, and it
+ * does not compound: each device checks an incoming timestamp against its own
+ * system time. Counter rollover or a backwards system-clock adjustment can
+ * still put such a write in quarantine.
+ *
+ * ### Clock drift
+ *
+ * {@link sendTimestamp} and {@link receiveTimestamp} check the resulting clock
+ * against {@link TimestampConfig.maxDrift}, returning {@link TimestampDriftError}
+ * when it exceeds the limit. Receipt also checks the remote timestamp before
+ * arithmetic. The database uses the same {@link isTimestampBeyondMaxDrift}
+ * predicate to decide whether a message can be applied. Two situations matter
+ * here:
+ *
+ * - An incoming message has a timestamp too far ahead of the receiving device's
+ *   system time. It can come from another device of the same owner or from a
+ *   collaborator, and the check cannot tell whether the sender is ahead or the
+ *   receiver behind.
+ * - The device's own system time is ahead and a write advances its logical clock.
+ *   Drift is measured against the device's own system time, so the device
+ *   accepts such writes as normal and stamps them ahead; other devices
+ *   quarantine them. Only if system time then moves back far enough does the
+ *   logical clock remain ahead and subsequent local changes go to quarantine.
+ *   Ordinary incoming messages are still applied when their own timestamps are
+ *   within the limit, even when the local clock is ahead. The clock is shared
+ *   by all owners in the database.
+ *
+ * System time is usually wrong by hours, rarely by years. A person sets the
+ * clock by hand, often misreading daylight saving time or the year, or picks a
+ * wrong time zone while the clock is set manually. A virtual machine resumes
+ * from a snapshot. Time synchronization corrects a clock that ran fast. A
+ * device with a dead clock battery boots into the past. Daylight saving time
+ * itself changes nothing, because timestamps use epoch milliseconds. Drift of
+ * years comes from a clock set to the wrong year, a bug, or, in collaboration,
+ * a vandalizing collaborator.
+ *
+ * The database uses a five-minute limit. It tolerates a few minutes of
+ * difference between device clocks and quarantines messages hours or days ahead
+ * of system time. The limit is a trade-off: a smaller one quarantines more; a
+ * larger one admits more future skew and releases sooner. No limit orders
+ * independent offline edits by real time. Five minutes is a policy choice: the
+ * [HLC paper, Section 4.2](https://cse.buffalo.edu/tech-reports/2014-04.pdf)
+ * leaves the tolerance to application semantics and suggests at most seconds
+ * for NTP-synchronized servers, which user devices are not. [Actual
+ * Budget](https://github.com/actualbudget/actual/blob/master/packages/crdt/src/crdt/timestamp.ts)
+ * uses the same default, a precedent rather than proof.
+ *
+ * ### Quarantine
+ *
+ * When a message's own timestamp exceeds the limit, Evolu stores the message in
+ * quarantine without applying it to application tables. The database queue and
+ * sync continue; other messages and requests are processed normally. Completing
+ * a mutation means its changes are stored; some may be quarantined rather than
+ * visible in application queries.
+ *
+ * Quarantine is state, not an error. Nothing is reported through the error
+ * channel; the quarantine table records each unapplied message with its reason,
+ * whether this database stamped it for a local mutation or received it, and the
+ * system time when it was quarantined. Applications watch that table through
+ * queries, and a subscribed query reflects a local mutation's quarantined rows
+ * before its completion callback runs. Quarantine works offline, independently
+ * of sync state, so the application can explain why the user's change is not
+ * visible.
+ *
+ * A local change still receives the next logical timestamp, and that clock
+ * advance is persisted with the quarantined message. Further local changes also
+ * go to quarantine while their timestamps exceed the drift limit. New mutations
+ * apply normally once their timestamps fall within it; existing drift
+ * quarantine still waits for database worker startup. An incoming message is
+ * quarantined only when its own timestamp exceeds system time by more than the
+ * limit. `receiveTimestamp` rejects that timestamp before calculating the next
+ * clock, so the message keeps its original timestamp, quarantining it does not
+ * advance the local clock. For a message within the limit, the database applies
+ * the message and persists the next clock even if an already-ahead local clock
+ * or counter rollover produces a timestamp beyond the limit. An ahead local
+ * clock surfaces through local changes. A message whose timestamp is already in
+ * the owner's set is not written again: it was applied or quarantined before,
+ * and a duplicate cannot change that decision. Quarantined messages count as
+ * stored for sync and can be forwarded normally; each receiving device decides
+ * whether to apply or quarantine them. A quarantined timestamp far in the
+ * future also becomes the owner's last stored timestamp on every device and
+ * relay that stores it, so their later timestamps take the slower insert path
+ * of the timestamp skiplist instead of append until system time passes it. One
+ * device whose clock is set ahead is enough to cause this for the whole owner.
+ * The cost is a constant factor per stored message, the `insert` versus
+ * `append` workloads of the storage benchmark; ordering and sync are
+ * unaffected. Relays store and forward messages without checking clock drift:
+ * acceptance belongs to clients and must not depend on an honest relay or its
+ * system clock.
+ *
+ * Quarantine does not itself make sync fail: completing sync does not mean
+ * every stored message has been applied to application tables.
+ *
+ * ### Release
+ *
+ * Drift quarantine is checked only when the database worker starts, as schema
+ * quarantine is. At that point, messages are released if their timestamps are
+ * no more than the drift limit ahead of system time, matching acceptance on a
+ * fresh receipt. Devices can therefore converge on the same visible state after
+ * their workers restart, regardless of delivery timing.
+ *
+ * On the web, the tab holding the leader lock hosts the database worker. When
+ * that tab closes, reloads, or enters the browser's back-forward cache, a tab
+ * taking over leadership starts a replacement, and other open tabs refresh
+ * their subscribed queries. Reloading a non-leader tab does not restart the
+ * database worker.
+ *
+ * Release checks use one captured system time. The logical clock advances over
+ * distinct released timestamps in timestamp order, as receipts do, so later
+ * local changes sort after them even before system time catches up. Released
+ * columns use last-writer-wins, so a future-stamped message overrides edits any
+ * device stamped before accepting or releasing it. Columns the schema does not
+ * define move to schema quarantine and are applied after a schema update.
+ * Duplicate delivery does not release: the timestamp is already in the owner's
+ * set. Release during a running database worker's session is not implemented.
+ * Correcting system time does not trigger release; eligible messages are
+ * released when the database worker next starts. Until then, a later message
+ * from one author can be visible while an earlier one is not, so an application
+ * can see a row that refers to one still in quarantine. Devices each within the
+ * limit can also be up to twice the limit apart, so a message one of them
+ * accepted can be quarantined by the other.
+ *
+ * Release runs before the database worker reports its clock, so fresh requests
+ * start from the clock advanced by release. The stored clock never moves
+ * backwards. A replacement database worker's clock is adopted only if newer, so
+ * an empty `memoryOnly` replacement does not reset the session clock. Pending
+ * writes keep their captured inputs, so a replay reproduces the timestamps of
+ * the original attempt. Responses report their computed clock, which the
+ * SharedWorker adopts only if newer. Acquiring the replacement refreshes
+ * subscribed queries, because a startup release or a committed write whose
+ * response was lost would otherwise stay invisible.
+ *
+ * ### Recovery
+ *
+ * Recovery for messages further ahead than the drift limit is not implemented
+ * yet. These constraints shape it. Deleting quarantine rows is not a safe
+ * primitive: the timestamp stays in the owner's set and on relays, and a stored
+ * timestamp must be able to produce its message. Recovery therefore applies the
+ * rows early, re-authors them as a new mutation with a fresh timestamp, or
+ * marks them discarded. Re-authoring is only right for a local origin. All
+ * three leave the future-stamped message stored for sync with its original
+ * timestamp, so on other devices it still overrides edits stamped before they
+ * accept it. Applying early is acceptable while the rows are a short time
+ * ahead, as after a manual clock change; how short is an application decision,
+ * measured as the row's timestamp minus current time. Rows far ahead, from a
+ * clock set to the wrong year, a bug, or a vandalizing collaborator, require
+ * migrating the owner's visible state to a new owner with fresh timestamps; the
+ * old owner is abandoned. How relays treat an abandoned owner is not specified
+ * yet.
+ *
+ * On the device whose clock ran ahead, fresh timestamps first need a clock
+ * reset. The database clock is shared by all owners and never moves backwards,
+ * so after that device's system time is corrected, every later timestamp is
+ * still at least as far ahead, for every owner, including a new one.
+ * Re-authored rows and a migration to a new owner would be quarantined too.
+ * Recovery there therefore starts by resetting the clock to system time with a
+ * fresh random node ID, which keeps timestamps stamped after the reset distinct
+ * from the future ones. The SharedWorker must adopt the reset clock although it
+ * is older than its session clock, and, like node ID rotation, the reset runs
+ * as its own request, never inside a replayed write. The reset is never
+ * automatic, because a clock that fell back, as after a dead clock battery,
+ * looks the same, and resetting then would stamp changes in the past. Nor is it
+ * a standalone action: after it, local edits to columns holding future-stamped
+ * values are stored but lose last-writer-wins without being quarantined, so the
+ * reset belongs only inside the migration to a new owner. Such a device can be
+ * recognized by local-origin drift quarantine whose timestamps exceed their
+ * quarantine time by about the skew.
+ *
+ * ### Range ceiling
+ *
+ * Counter rollover past the {@link Millis} ceiling, in August 10889, throws. The
+ * clock can get there only if the system clock came within the drift limit of
+ * the ceiling or the stored clock was tampered with, because `receiveTimestamp`
+ * checks remote drift before clock arithmetic. Such a clock is as broken as one
+ * past the ceiling, which {@link Millis} already rejects by throwing.
+ *
+ * ### Duplicate node IDs
+ *
+ * Detection and recovery are deliberately deferred to separate work. This
+ * includes the receive-first collision below, where a local mutation can
+ * complete without being stored.
+ *
+ * The node ID is random per database and persisted in the clock. A database
+ * copied to another device, as when an operating system backup is restored to a
+ * new phone while the old one stays in use, leaves both independent copies
+ * stamping from the same node ID and clock. Tabs and Evolu instances sharing
+ * one database coordinate their writes through its shared clock.
+ *
+ * For the same owner, two changes stamped in the same logical millisecond with
+ * the same counter get identical timestamps. If both copies write before
+ * receiving the other's change, each keeps its own version, while relays and
+ * third devices keep the first arrival. The copies can diverge with no error.
+ * This is likely while the copied clock is ahead of both devices' system time,
+ * because both stamp counters 1, 2, 3 in the same millisecond.
+ *
+ * Receiving first can instead lose a local change. A copy quarantines an
+ * incoming timestamp beyond the drift limit without advancing its clock. Its
+ * next local mutation can then produce that same timestamp. The timestamp is
+ * already in the owner's set, so the local change is skipped: it is stored in
+ * neither application tables, history, nor quarantine, but `onComplete` still
+ * runs. The previously received change remains stored under that timestamp.
+ *
+ * Detection: a received message whose timestamp is new to the owner's set but
+ * carries the local node ID cannot be ours, because every timestamp authored
+ * locally is already in the set before it can be sent, and a restored or
+ * recreated database mints a fresh node ID. `applyMessages` knows both facts
+ * when `insertTimestamp` reports a new timestamp. Messages whose timestamps are
+ * already stored are invisible to this rule; a new timestamp from the copy
+ * trips it.
+ *
+ * An empty `memoryOnly` replacement is an exception: it can retain the
+ * SharedWorker's previous clock and node ID while losing the timestamp set.
+ * Detection must account for this before rotation, or our own earlier messages
+ * could be mistaken for another database's changes.
+ *
+ * Handling: rotate the local node ID to a fresh random one, which changes only
+ * future timestamps, and report the copy through sync state or the error store
+ * so the application can warn that edits before detection may have diverged or
+ * been lost. Both copies detect each other and rotate, after which detection
+ * stops because messages with the old ID are no longer ours. Rotation cannot
+ * heal past collisions. Deleting and resyncing the database automatically is
+ * rejected: it drops unsynced changes and local-only tables, needs a relay, and
+ * does not recover the dropped half of a collision; restore from mnemonic is
+ * its manual form. The rotation must not happen inside the replayed write: a
+ * replay sees nothing new and would save the input clock with the old node ID
+ * again. The write's response flags the detection and the SharedWorker enqueues
+ * a separate rotation request, which is harmless to replay.
+ *
  * @module
  */
 import type { RandomBytesDep } from "../Crypto.ts";
 import type { Order } from "../Order.ts";
 import type { Result } from "../Result.ts";
-import type { TimeDep } from "../Time.ts";
 import { Millis } from "../Time.ts";
 import { type DateIso, type InferType, type ObjectType, type Typed } from "../Type.ts";
 export interface TimestampConfig {
     /**
-     * Maximum physical clock drift allowed in ms.
+     * How far in ms a timestamp may be ahead of system time.
      *
-     * The default value is 5 * 60 * 1000 (5 minutes).
+     * The database uses {@link defaultTimestampMaxDrift}; it is not configurable.
+     * A timestamp behind system time is never drift.
      */
     readonly maxDrift: number;
 }
@@ -22,43 +262,39 @@ export declare const defaultTimestampMaxDrift: number;
 export interface TimestampConfigDep {
     readonly timestampConfig: TimestampConfig;
 }
-export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError;
+/** Errors from advancing a {@link Timestamp}. */
+export type TimestampError = TimestampDriftError;
+/**
+ * A timestamp exceeds {@link TimestampConfig.maxDrift}.
+ *
+ * For local drift, the failed operation includes its candidate for explicit
+ * recovery by the database. For remote drift, it includes the rejected input;
+ * the local clock must not advance from it.
+ *
+ * Local drift stays an error even when the database recovers: callers can rely
+ * on successful timestamp operations satisfying the drift limit without a
+ * separate check.
+ */
 export interface TimestampDriftError extends Typed<"TimestampDriftError"> {
-    readonly next: Millis;
+    /** The computed candidate for local drift, or the rejected remote input. */
+    readonly timestamp: Timestamp;
+    readonly cause: "local" | "remote";
+    /** Captured system time used for the drift check. */
     readonly now: Millis;
 }
-export interface TimestampCounterOverflowError extends Typed<"TimestampCounterOverflowError"> {
-}
-export interface TimestampTimeOutOfRangeError extends Typed<"TimestampTimeOutOfRangeError"> {
-}
 export declare const Counter: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"Number", number, number, import("../Type.ts").TypeOfError<"Number">, null, import("../Type.ts").TypeOfError<"Number">, never, number, true>, "NonNaN", import("../Type.ts").NonNaNError>, "Finite", import("../Type.ts").FiniteError>, "Int", import("../Type.ts").IntError>, "NonNegative", import("../Type.ts").NonNegativeError>, "LessThanOrEqualTo65535", import("../Type.ts").LessThanOrEqualToError<65535>>, "Counter", never>;
 export type Counter = typeof Counter.Output;
 export declare const minCounter: Counter;
 export declare const maxCounter: Counter;
 /**
- * A NodeId uniquely identifies an owner's device. Generated once per device
- * using cryptographic randomness.
- *
- * Collision probability (birthday paradox):
- *
- * - 1,000 devices: ~0.00000000000271% (negligible).
- * - 1M devices: ~0.00000271% (1 in 37M chance).
- * - 135M devices: ~1% chance.
- * - 4.29B devices: ~50% chance.
- *
- * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
- *
- * What happens if different devices generate the same NodeId?
- *
- * If devices with the same NodeId use different owners, no issues occur.
+ * A NodeId identifies the database that stamped a timestamp. It is 64 random
+ * bits, generated when the database is created and persisted in its clock.
  *
- * 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.
+ * Only databases that share an owner can collide, so random collisions are
+ * negligible. Identical timestamps (same millis, counter, and NodeId) are the
+ * same message to sync: one of the changes is lost, and the affected devices
+ * see different data while they appear synced. The realistic case is a copied
+ * database, described in the Timestamp module's Duplicate node IDs section.
  */
 export declare const NodeId: import("../Type.ts").BrandType<import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, "NodeId", import("../Type.ts").RegexError<"NodeId">>;
 export type NodeId = typeof NodeId.Output;
@@ -86,11 +322,20 @@ export declare const nodeIdBytesToNodeId: (nodeIdBytes: NodeIdBytes) => NodeId;
  * 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.
+ * The counter gives a total order and preserves causality for accepted
+ * messages: when clocks differ within the drift limit or operations occur
+ * concurrently, it increments so later writes sort after what the device has
+ * seen. Messages beyond the drift limit wait in quarantine, and devices
+ * converge once system time is within the limit of those messages and the
+ * database worker restarts. See the Timestamp module's Clock drift section.
+ *
+ * When the 16-bit counter is exhausted, the logical millisecond advances by one
+ * and the counter resets to zero. The resulting timestamp must still fit within
+ * {@link Millis}. If rollover exceeds {@link TimestampConfig.maxDrift},
+ * {@link sendTimestamp} and {@link receiveTimestamp} return
+ * {@link TimestampDriftError} with the candidate timestamp for the database to
+ * handle. Rollover preserves deterministic ordering even when a batch uses one
+ * captured wall time.
  *
  * Vector clocks can accurately track causality and detect concurrent
  * operations, but they require unbounded space in peer-to-peer systems and
@@ -100,12 +345,22 @@ export declare const nodeIdBytesToNodeId: (nodeIdBytes: NodeIdBytes) => NodeId;
  * 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.
+ * reflect the order of sequential edits in the common case. The database uses
+ * the drift limit to quarantine messages whose own timestamps are too far ahead
+ * of its system time without applying them to application tables. Quarantined
+ * messages remain stored and synchronized; each receiving device checks drift
+ * against its own system time.
  *
  * ## References
  *
+ * - Kulkarni, Demirbas, Madeppa, Avva, Leone: [Logical Physical Clocks and
+ *   Consistent Snapshots in Globally Distributed
+ *   Databases](https://cse.buffalo.edu/tech-reports/2014-04.pdf) (OPODIS 2014,
+ *   [doi:10.1007/978-3-319-14472-6_2](https://doi.org/10.1007/978-3-319-14472-6_2)).
+ *   The paper proposes 48 significant bits of an NTP timestamp plus a 16-bit
+ *   counter and argues that the counter is sufficient under its assumptions.
+ *   Evolu uses 48-bit milliseconds and rolls counter exhaustion into the next
+ *   logical millisecond, subject to the timestamp range.
  * - 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/
@@ -146,10 +401,106 @@ export declare const eqTimestamp: import("../Eq.ts").Eq<{
     readonly millis: number & import("../Brand.ts").Brand<"NonNaN"> & import("../Brand.ts").Brand<"Finite"> & import("../Brand.ts").Brand<"Int"> & import("../Brand.ts").Brand<"NonNegative"> & import("../Brand.ts").Brand<"LessThan281474976710655"> & import("../Brand.ts").Brand<"Millis">;
     readonly nodeId: string & import("../Brand.ts").Brand<"NodeId">;
 }>;
+/**
+ * Orders {@link Timestamp} by milliseconds, counter, then node ID.
+ *
+ * Matches {@link orderTimestampBytes} without encoding timestamps. Distinct
+ * objects with identical fields compare as equal.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual } from "@evolu/common";
+ * import {
+ *   createTimestamp,
+ *   orderTimestamp,
+ * } from "@evolu/common/local-first";
+ *
+ * const timestamp = createTimestamp();
+ * assertEqual(orderTimestamp(timestamp, { ...timestamp }), 0);
+ * ```
+ */
+export declare const orderTimestamp: Order<Timestamp>;
 export declare const createTimestamp: ({ millis, counter, nodeId, }?: Partial<Timestamp>) => 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 | TimestampTimeOutOfRangeError>;
+/**
+ * Advances a {@link Timestamp} for a local event.
+ *
+ * Counter exhaustion rolls into the next logical millisecond, and rollover past
+ * the {@link Millis} ceiling throws; see the module documentation. The resulting
+ * timestamp is checked for drift, including after rollover; a failure returns
+ * {@link TimestampDriftError} with the candidate and `cause: "local"`. Pass the
+ * request's captured system time so replay produces the same result.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertOk, Millis } from "@evolu/common";
+ * import {
+ *   createTimestamp,
+ *   maxCounter,
+ *   sendTimestamp,
+ * } from "@evolu/common/local-first";
+ *
+ * const before = createTimestamp({ counter: maxCounter });
+ * const result = sendTimestamp({ timestampConfig: { maxDrift: 1 } })(
+ *   before,
+ *   Millis.orThrow(0),
+ * );
+ * assertOk(result, { ...before, millis: Millis.orThrow(1), counter: 0 });
+ * ```
+ */
+export declare const sendTimestamp: (deps: TimestampConfigDep) => (timestamp: Timestamp, now: Millis) => Result<Timestamp, TimestampError>;
+/**
+ * Advances a {@link Timestamp} for a received one.
+ *
+ * Rejects remote drift with {@link TimestampDriftError} and `cause: "remote"`
+ * before clock arithmetic. Merges the later clock state, preserves the local
+ * node ID, and uses {@link sendTimestamp} to advance and validate the result. An
+ * already-ahead local clock or rollover beyond the drift limit returns local
+ * drift. Pass one captured time for a batch or replay.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertErr, Millis } from "@evolu/common";
+ * import {
+ *   createTimestamp,
+ *   receiveTimestamp,
+ * } from "@evolu/common/local-first";
+ *
+ * const receive = receiveTimestamp({ timestampConfig: { maxDrift: 10 } });
+ * const local = createTimestamp();
+ * const remote = createTimestamp({ millis: Millis.orThrow(111) });
+ * assertErr(receive(local, remote, Millis.orThrow(100)), {
+ *   type: "TimestampDriftError",
+ *   timestamp: remote,
+ *   cause: "remote",
+ *   now: Millis.orThrow(100),
+ * });
+ * ```
+ */
+export declare const receiveTimestamp: (deps: TimestampConfigDep) => (local: Timestamp, remote: Timestamp, now: Millis) => Result<Timestamp, TimestampError>;
+/**
+ * Whether timestamp milliseconds exceed {@link TimestampConfig.maxDrift} ahead
+ * of the supplied reference time. The exact limit and past timestamps are
+ * accepted.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertFalse, assertTrue, Millis } from "@evolu/common";
+ * import { isTimestampBeyondMaxDrift } from "@evolu/common/local-first";
+ *
+ * const isBeyondMaxDrift = isTimestampBeyondMaxDrift({
+ *   timestampConfig: { maxDrift: 10 },
+ * });
+ * const now = Millis.orThrow(100);
+ * assertFalse(isBeyondMaxDrift(Millis.orThrow(110), now));
+ * assertTrue(isBeyondMaxDrift(Millis.orThrow(111), now));
+ * ```
+ */
+export declare const isTimestampBeyondMaxDrift: (deps: TimestampConfigDep) => (millis: Millis, now: Millis) => boolean;
 /** Sortable bytes representation of {@link Timestamp}. */
 export declare const TimestampBytes: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>, "Length16", import("../Type.ts").LengthError<16>>, "TimestampBytes", never>;
 export type TimestampBytes = typeof TimestampBytes.Output;

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

@@ -1 +1 @@
-{"version":3,"file":"Timestamp.d.ts","sourceRoot":"","sources":["../../../src/local-first/Timestamp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Timestamp.d.ts","sourceRoot":"","sources":["../../../src/local-first/Timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoPG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,MAAM,EAAa,MAAM,YAAY,CAAC;AAC/C,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,SAAS,EAKd,KAAK,UAAU,EAGf,KAAK,KAAK,EAEX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,QAAgB,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAoB,SAAQ,KAAK,CAAC,qBAAqB,CAAC;IACvE,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,OAAO,4nBAGnB,CAAC;AACF,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,MAAM,CAAC;AAE5C,eAAO,MAAM,UAAU,EAAQ,OAAO,CAAC;AACvC,eAAO,MAAM,UAAU,EAAY,OAAO,CAAC;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,6PAA2D,CAAC;AAC/E,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,CAAC;AAE1C,eAAO,MAAM,SAAS,EAAyB,MAAM,CAAC;AACtD,eAAO,MAAM,SAAS,EAAyB,MAAM,CAAC;AAEtD,+CAA+C;AAC/C,eAAO,MAAM,WAAW,+XAGvB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC;AAEpD,qCAAqC;AACrC,eAAO,MAAM,iBAAiB,0KAA0C,CAAC;AAEzE,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,WAAY,MAAM,KAAG,WAClB,CAAC;AAEpC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,gBAAiB,WAAW,KAAG,MAC5B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,SAAS,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,MAAM,CAAC;CAChC,CAIC,CAAC;AACH,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,OAAO,SAAS,CAAC;CAAG;AAEjE,yDAAyD;AACzD,eAAO,MAAM,WAAW;;;;EAItB,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,SAAS,CAGX,CAAC;AAElC,eAAO,MAAM,eAAe,kCAIzB,OAAO,CAAC,SAAS,CAAC,KAAQ,SAA0C,CAAC;AAExE,eAAO,MAAM,sBAAsB,SAAU,cAAc,KAAG,SAG7D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,SACjB,kBAAkB,iBACb,SAAS,OAAO,MAAM,KAAG,MAAM,CAAC,SAAS,EAAE,cAAc,CAsBpE,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,SACpB,kBAAkB,aAEhB,SAAS,UACR,SAAS,OACZ,MAAM,KACV,MAAM,CAAC,SAAS,EAAE,cAAc,CAWlC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,SAC7B,kBAAkB,cAChB,MAAM,OAAO,MAAM,KAAG,OACe,CAAC;AAEjD,0DAA0D;AAC1D,eAAO,MAAM,cAAc,oYAG1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC;AAE1D,eAAO,MAAM,oBAAoB,0KAA2C,CAAC;AAE7E,eAAO,MAAM,yBAAyB,cACzB,SAAS,KACnB,cAuBF,CAAC;AAEF,eAAO,MAAM,yBAAyB,cACzB,cAAc,KACxB,SAiBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,cAAc,CAAmB,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,cAAe,SAAS,KAAG,OAEL,CAAC"}