@evolu/common 8.10.0 → 8.11.0

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

@@ -5,6 +5,7 @@
  */
 import type { NonEmptyReadonlyArray } from "../Array.ts";
 import type { Brand } from "../Brand.ts";
+import type { DecryptWithXChaCha20Poly1305Error } from "../Crypto.ts";
 import type { RandomDep } from "../Random.ts";
 import type { SqliteDep } from "../Sqlite.ts";
 import type { Task } from "../Task.ts";
@@ -12,7 +13,13 @@ import { Boolean, Id, type InferType, NonNegativeInt, Null, type ObjectType, Pos
 import type { Awaitable } from "../Types.ts";
 import type { OwnerError, OwnerIdBytes } from "./Owner.ts";
 import { OwnerId, OwnerWriteKey } from "./Owner.ts";
+import type { ProtocolInvalidDataError, ProtocolTimestampMismatchError } from "./Protocol.ts";
 import { Timestamp, TimestampBytes } from "./Timestamp.ts";
+/**
+ * Configuration for {@link Storage}, such as quota checks.
+ *
+ * @group Core
+ */
 export interface StorageConfig {
     /**
      * Callback called before an attempt to write, to check if an {@link OwnerId}
@@ -67,12 +74,18 @@ export interface StorageConfig {
     readonly isOwnerWithinQuota: (ownerId: OwnerId, requiredBytes: PositiveInt) => Awaitable<boolean>;
 }
 /**
- * Evolu Storage.
+ * Replica storage used by Evolu's synchronization protocol.
+ *
+ * Protocol owns message framing, set reconciliation, and sync continuation.
+ * Storage owns batch acceptance, persistence, and the timestamp and fingerprint
+ * queries used by reconciliation. Protocol functions accept any implementation
+ * that satisfies this contract.
  *
- * Evolu Protocol is agnostic to storage implementation—any storage can be
- * plugged in, as long as it implements this interface. Implementations must
- * handle their own errors; return values only indicate overall success or
- * failure.
+ * {@link Storage.writeMessages} returns the {@link StorageWriteMessagesError}
+ * that made it store none of a batch. Implementations return expected write
+ * rejections without reporting them; the caller owns reporting. The client
+ * protocol forwards these errors unchanged, while the relay protocol maps them
+ * to wire error codes.
  *
  * The Storage API is synchronous because SQLite's synchronous API is the
  * fastest way to use SQLite. Synchronous bindings (like better-sqlite3) call
@@ -82,6 +95,8 @@ export interface StorageConfig {
  * The only exception is {@link Storage.writeMessages}, which is async to allow
  * for async validation logic before writing to storage. The write operation
  * itself remains synchronous.
+ *
+ * @group Core
  */
 export interface Storage {
     readonly getSize: (ownerId: OwnerIdBytes) => NonNegativeInt;
@@ -107,66 +122,157 @@ export interface Storage {
     /**
      * Write encrypted {@link CrdtMessage}s to storage.
      *
+     * Stores none of the messages and returns the cause when the batch cannot be
+     * accepted.
+     *
      * Must use a mutex per ownerId to ensure sequential processing and proper
      * protocol logic handling during sync operations.
      */
-    readonly writeMessages: (ownerIdBytes: OwnerIdBytes, messages: NonEmptyReadonlyArray<EncryptedCrdtMessage>) => Task<void, StorageQuotaError>;
+    readonly writeMessages: (ownerIdBytes: OwnerIdBytes, messages: NonEmptyReadonlyArray<EncryptedCrdtMessage>) => Task<void, StorageWriteMessagesError>;
     /** Read encrypted {@link DbChange}s from storage. */
     readonly readDbChange: (ownerId: OwnerIdBytes, timestamp: TimestampBytes) => EncryptedDbChange;
     /** Delete all data for the given {@link Owner}. */
     readonly deleteOwner: (ownerId: OwnerIdBytes) => void;
 }
+/**
+ * Dependency wrapper for {@link Storage}.
+ *
+ * @group Core
+ */
 export interface StorageDep {
     readonly storage: Storage;
 }
-/** Error when storage or billing quota is exceeded. */
+/**
+ * Error when storage or billing quota is exceeded.
+ *
+ * @group Core
+ */
 export interface StorageQuotaError extends OwnerError, Typed<"StorageQuotaError"> {
 }
+/**
+ * Expected reasons why {@link Storage.writeMessages} stored none of a batch.
+ *
+ * Each implementation returns the members that apply to it. The built-in relay
+ * storage currently stores opaque encrypted messages and rejects batches over
+ * quota. The built-in client storage decrypts and validates incoming messages
+ * before updating its clock and database tables. The contract permits quota
+ * checks on either side.
+ *
+ * @group Core
+ */
+export type StorageWriteMessagesError = DecryptWithXChaCha20Poly1305Error | ProtocolInvalidDataError | ProtocolTimestampMismatchError | StorageQuotaError;
 /**
  * A cryptographic hash used for efficiently comparing collections of
  * {@link TimestampBytes}es.
  *
  * It consists of the first {@link fingerprintSize} bytes of the SHA-256 hash of
  * one or more timestamps.
+ *
+ * @group Ranges
  */
 export type Fingerprint = Uint8Array & Brand<"Fingerprint">;
+/**
+ * Number of leading SHA-256 bytes that form a {@link Fingerprint}.
+ *
+ * @group Ranges
+ */
 export declare const fingerprintSize: number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">;
-/** A fingerprint of an empty range. */
+/**
+ * A fingerprint of an empty range.
+ *
+ * @group Ranges
+ */
 export declare const zeroFingerprint: Fingerprint;
+/**
+ * Common shape of every {@link Range}.
+ *
+ * @group Ranges
+ */
 export interface BaseRange {
     readonly upperBound: RangeUpperBound;
 }
 /**
  * Union type for Range's upperBound: either a {@link TimestampBytes} or
  * {@link InfiniteUpperBound}.
+ *
+ * @group Ranges
  */
 export type RangeUpperBound = TimestampBytes | InfiniteUpperBound;
+/**
+ * Sentinel {@link RangeUpperBound} for a range without an upper limit.
+ *
+ * @group Ranges
+ */
 export declare const InfiniteUpperBound: unique symbol;
+/**
+ * Type of the {@link InfiniteUpperBound} sentinel.
+ *
+ * @group Ranges
+ */
 export type InfiniteUpperBound = typeof InfiniteUpperBound;
+/**
+ * Numeric tags discriminating {@link Range} variants.
+ *
+ * @group Ranges
+ */
 export declare const RangeType: {
     readonly Fingerprint: 1;
     readonly Skip: 0;
     readonly Timestamps: 2;
 };
+/**
+ * Numeric tag of one {@link Range} variant.
+ *
+ * @group Ranges
+ */
 export type RangeType = (typeof RangeType)[keyof typeof RangeType];
+/**
+ * Range with nothing to reconcile.
+ *
+ * @group Ranges
+ */
 export interface SkipRange extends BaseRange {
     readonly type: typeof RangeType.Skip;
 }
+/**
+ * Range summarized by a {@link Fingerprint} for comparison.
+ *
+ * @group Ranges
+ */
 export interface FingerprintRange extends BaseRange {
     readonly type: typeof RangeType.Fingerprint;
     readonly fingerprint: Fingerprint;
 }
+/**
+ * Range listing its {@link TimestampBytes} explicitly.
+ *
+ * @group Ranges
+ */
 export interface TimestampsRange extends BaseRange {
     readonly type: typeof RangeType.Timestamps;
     readonly timestamps: ReadonlyArray<TimestampBytes>;
 }
+/**
+ * Range exchanged during sync: {@link SkipRange}, {@link FingerprintRange}, or
+ * {@link TimestampsRange}.
+ *
+ * @group Ranges
+ */
 export type Range = SkipRange | FingerprintRange | TimestampsRange;
-/** An encrypted {@link CrdtMessage}. */
+/**
+ * An encrypted {@link CrdtMessage}.
+ *
+ * @group Messages
+ */
 export interface EncryptedCrdtMessage {
     readonly timestamp: Timestamp;
     readonly change: EncryptedDbChange;
 }
-/** Encrypted DbChange */
+/**
+ * Encrypted DbChange
+ *
+ * @group Messages
+ */
 export type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
 /**
  * A CRDT message combining a unique {@link Timestamp} with a {@link DbChange}.
@@ -174,17 +280,38 @@ export type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
  * Used in Evolu's sync protocol to replicate data changes across devices. Evolu
  * operates as a durable queue, providing exactly-once delivery guarantees for
  * reliable synchronization across application restarts and network failures.
+ *
+ * @group Messages
  */
 export interface CrdtMessage {
     readonly timestamp: Timestamp;
     readonly change: DbChange;
 }
-/** Test helper for creating a simple {@link CrdtMessage}. */
+/**
+ * Test helper for creating a simple {@link CrdtMessage}.
+ *
+ * @group Testing
+ */
 export declare const testCreateCrdtMessage: (id: Id, millis: number, name: string) => CrdtMessage;
+/**
+ * Column values of a {@link DbChange}, keyed by column name.
+ *
+ * @group Messages
+ */
 export declare const DbChangeValues: import("../Type.ts").RecordType<import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, UnionType<readonly [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>, import("../Type.ts").LiteralType<null>, import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>]>>;
 export type DbChangeValues = typeof DbChangeValues.Output;
+/**
+ * Column values that contain no reserved system columns.
+ *
+ * @group Messages
+ */
 export declare const ValidDbChangeValues: import("../Type.ts").BrandType<import("../Type.ts").RecordType<import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, UnionType<readonly [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>, import("../Type.ts").LiteralType<null>, import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>]>>, "ValidDbChangeValues", ValidDbChangeValuesError>;
 export type ValidDbChangeValues = typeof ValidDbChangeValues.Output;
+/**
+ * Error produced when {@link DbChangeValues} contain reserved system columns.
+ *
+ * @group Messages
+ */
 export interface ValidDbChangeValuesError extends TypeError<"ValidDbChangeValues"> {
     readonly value: DbChangeValues;
     readonly invalidColumns: ReadonlyArray<string>;
@@ -192,6 +319,8 @@ export interface ValidDbChangeValuesError extends TypeError<"ValidDbChangeValues
 /**
  * A DbChange is a change to a table row. Together with a unique
  * {@link Timestamp}, it forms a {@link CrdtMessage}.
+ *
+ * @group Messages
  */
 export declare const DbChange: ObjectType<{
     readonly table: typeof String;
@@ -231,19 +360,36 @@ export interface DbChange extends InferType<typeof DbChange> {
  * each other, if necessary. One relay should handle hundreds of thousands of
  * users, and when it goes down, nothing happens, because it will be
  * synchronized later.
+ *
+ * @group SQLite
  */
 export interface BaseSqliteStorage extends Omit<Storage, "validateWriteKey" | "setWriteKey" | "writeMessages" | "readDbChange"> {
-    /** Inserts a timestamp for an owner into the skiplist-based storage. */
-    readonly insertTimestamp: (ownerId: OwnerIdBytes, timestamp: TimestampBytes, strategy: StorageInsertTimestampStrategy) => void;
+    /**
+     * Inserts a timestamp for an owner into the skiplist-based storage.
+     *
+     * Returns whether the timestamp was new. An existing timestamp is left
+     * unchanged.
+     */
+    readonly insertTimestamp: (ownerId: OwnerIdBytes, timestamp: TimestampBytes, strategy: StorageInsertTimestampStrategy) => boolean;
     /**
      * Efficiently checks which timestamps already exist in the database using a
      * single CTE query instead of N individual queries.
      */
     readonly getExistingTimestamps: (ownerIdBytes: OwnerIdBytes, timestampsBytes: NonEmptyReadonlyArray<TimestampBytes>) => ReadonlyArray<TimestampBytes>;
 }
+/**
+ * Dependency wrapper for {@link BaseSqliteStorage}.
+ *
+ * @group SQLite
+ */
 export interface BaseSqliteStorageDep {
     readonly baseSqliteStorage: BaseSqliteStorage;
 }
+/**
+ * Dependencies required by {@link createBaseSqliteStorage}.
+ *
+ * @group SQLite
+ */
 export type SqliteStorageDeps = RandomDep & SqliteDep;
 /**
  * Creates a {@link BaseSqliteStorage} implementation.
@@ -257,25 +403,55 @@ export type SqliteStorageDeps = RandomDep & SqliteDep;
  * Cloudflare Workers with Durable Objects, and other platforms where memory
  * doesn't persist between requests. While not extensively tested in all these
  * environments yet, the stateless design should work well across them.
+ *
+ * @group SQLite
  */
 export declare const createBaseSqliteStorage: (deps: SqliteStorageDeps) => BaseSqliteStorage;
+/**
+ * Creates the SQLite tables used by {@link BaseSqliteStorage}.
+ *
+ * @group SQLite
+ */
 export declare const createBaseSqliteStorageTables: (deps: SqliteDep) => void;
+/**
+ * Position at which a timestamp is inserted relative to existing timestamps.
+ *
+ * @group SQLite
+ */
 export type StorageInsertTimestampStrategy = "append" | "prepend" | "insert";
 /**
  * Determines the insertion strategy for a timestamp based on its position
  * relative to the current first and last timestamps.
  *
  * Returns a tuple with the strategy and updated timestamp bounds.
+ *
+ * @group SQLite
  */
 export declare const getTimestampInsertStrategy: (timestamp: TimestampBytes, firstTimestamp: TimestampBytes, lastTimestamp: TimestampBytes) => [strategy: StorageInsertTimestampStrategy, firstTimestamp: TimestampBytes, lastTimestamp: TimestampBytes];
+/**
+ * Computes the {@link Fingerprint} of a single timestamp.
+ *
+ * @group Ranges
+ */
 export declare const timestampBytesToFingerprint: (timestamp: TimestampBytes) => Fingerprint;
 /**
  * Computes a brute-force {@link Fingerprint} from {@link TimestampBytes} values
  * for tests and benchmarks.
+ *
+ * @group Testing
  */
 export declare const testFingerprintTimestamps: (timestamps: ReadonlyArray<TimestampBytes>) => Fingerprint;
+/**
+ * Reads the timestamp at a position within an owner's ordered timestamps.
+ *
+ * @group SQLite
+ */
 export declare const getTimestampByIndex: (deps: SqliteDep) => (ownerId: OwnerIdBytes, index: NonNegativeInt) => TimestampBytes;
-/** Reads owner usage from SQLite and returns default bounds when absent. */
+/**
+ * Reads owner usage from SQLite and returns default bounds when absent.
+ *
+ * @group SQLite
+ */
 export declare const readOwnerUsageOrDefault: (deps: SqliteDep) => (ownerIdBytes: OwnerIdBytes, initialTimestamp: TimestampBytes) => {
     readonly storedBytes: NonNegativeInt | null;
     readonly firstTimestamp: TimestampBytes;
@@ -286,6 +462,8 @@ export declare const readOwnerUsageOrDefault: (deps: SqliteDep) => (ownerIdBytes
  *
  * Used by both relay and client to maintain firstTimestamp/lastTimestamp after
  * processing messages.
+ *
+ * @group SQLite
  */
 export declare const updateOwnerUsage: (deps: SqliteDep) => (ownerIdBytes: OwnerIdBytes, storedBytes: PositiveInt, firstTimestamp: TimestampBytes, lastTimestamp: TimestampBytes) => void;
 //# sourceMappingURL=Storage.d.ts.map

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

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

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

@@ -15,16 +15,39 @@ import { Boolean, brand, Id, NonNegativeInt, Null, nullOr, object, PositiveInt,
 import { OwnerId, OwnerWriteKey } from "./Owner.js";
 import { systemColumnsWithId } from "./Schema.js";
 import { createTimestamp, orderTimestampBytes, Timestamp, TimestampBytes, } from "./Timestamp.js";
+/**
+ * Number of leading SHA-256 bytes that form a {@link Fingerprint}.
+ *
+ * @group Ranges
+ */
 export const fingerprintSize = /*#__PURE__*/ NonNegativeInt.orThrow(12);
-/** A fingerprint of an empty range. */
+/**
+ * A fingerprint of an empty range.
+ *
+ * @group Ranges
+ */
 export const zeroFingerprint = /*#__PURE__*/ new Uint8Array(fingerprintSize);
+/**
+ * Sentinel {@link RangeUpperBound} for a range without an upper limit.
+ *
+ * @group Ranges
+ */
 export const InfiniteUpperBound = /*#__PURE__*/ Symbol("evolu.local-first.Storage.InfiniteUpperBound");
+/**
+ * Numeric tags discriminating {@link Range} variants.
+ *
+ * @group Ranges
+ */
 export const RangeType = {
     Fingerprint: 1,
     Skip: 0,
     Timestamps: 2,
 };
-/** Test helper for creating a simple {@link CrdtMessage}. */
+/**
+ * Test helper for creating a simple {@link CrdtMessage}.
+ *
+ * @group Testing
+ */
 export const testCreateCrdtMessage = (id, millis, name) => ({
     timestamp: createTimestamp({
         millis: Millis.orThrow(millis),
@@ -38,7 +61,17 @@ export const testCreateCrdtMessage = (id, millis, name) => ({
         isDelete: false,
     }),
 });
+/**
+ * Column values of a {@link DbChange}, keyed by column name.
+ *
+ * @group Messages
+ */
 export const DbChangeValues = /*#__PURE__*/ record(String, SqliteValue);
+/**
+ * Column values that contain no reserved system columns.
+ *
+ * @group Messages
+ */
 export const ValidDbChangeValues = /*#__PURE__*/ brand("ValidDbChangeValues", DbChangeValues, (value) => {
     const invalidColumns = systemColumnsWithId.filter((key) => key in value);
     if (invalidColumns.length > 0)
@@ -52,6 +85,8 @@ export const ValidDbChangeValues = /*#__PURE__*/ brand("ValidDbChangeValues", Db
 /**
  * A DbChange is a change to a table row. Together with a unique
  * {@link Timestamp}, it forms a {@link CrdtMessage}.
+ *
+ * @group Messages
  */
 export const DbChange = /*#__PURE__*/ object({
     table: String,
@@ -72,11 +107,13 @@ export const DbChange = /*#__PURE__*/ object({
  * Cloudflare Workers with Durable Objects, and other platforms where memory
  * doesn't persist between requests. While not extensively tested in all these
  * environments yet, the stateless design should work well across them.
+ *
+ * @group SQLite
  */
 export const createBaseSqliteStorage = (deps) => ({
     insertTimestamp: (ownerId, timestamp, strategy) => {
         const level = randomSkiplistLevel(deps);
-        insertTimestamp(deps)(ownerId, timestamp, level, strategy);
+        return insertTimestamp(deps)(ownerId, timestamp, level, strategy);
     },
     getExistingTimestamps: (ownerIdBytes, timestampsBytes) => {
         const concatenatedTimestamps = concatBytes(...timestampsBytes);
@@ -150,6 +187,11 @@ export const createBaseSqliteStorage = (deps) => ({
 const assertBeginEnd = (begin, end) => {
     assert(begin <= end, "invalid begin or end");
 };
+/**
+ * Creates the SQLite tables used by {@link BaseSqliteStorage}.
+ *
+ * @group SQLite
+ */
 export const createBaseSqliteStorageTables = (deps) => {
     for (const query of [
         /**
@@ -218,6 +260,8 @@ export const createBaseSqliteStorageTables = (deps) => {
  * relative to the current first and last timestamps.
  *
  * Returns a tuple with the strategy and updated timestamp bounds.
+ *
+ * @group SQLite
  */
 export const getTimestampInsertStrategy = (timestamp, firstTimestamp, lastTimestamp) => {
     if (orderTimestampBytes(timestamp, lastTimestamp) === 1) {
@@ -251,13 +295,13 @@ export const getTimestampInsertStrategy = (timestamp, firstTimestamp, lastTimest
  * key instead of repeating the same correlated range lookup for every column.
  *
  * Inserts are idempotent to support direct calls and message replay. `on
- * conflict do nothing` makes a duplicate insertion a no-op, and `changes() > 0`
- * ensures ancestor metadata is updated only when the preceding insertion added
- * a timestamp.
+ * conflict do nothing` makes a duplicate insertion a no-op that reports the
+ * timestamp as not new, so the follow-up statements update metadata only for a
+ * new timestamp.
  */
 const insertTimestamp = (deps) => (ownerId, timestamp, level, strategy) => {
     const [h1, h2] = fingerprintToSqliteFingerprint(timestampBytesToFingerprint(timestamp));
-    let queries = [];
+    let queries;
     switch (strategy) {
         case "append":
             queries = [
@@ -431,10 +475,7 @@ const insertTimestamp = (deps) => (ownerId, timestamp, level, strategy) => {
               h2 = u.h2,
               c = c + 1
             from u
-            where
-              changes() > 0
-              and ownerId = ${ownerId}
-              and evolu_timestamp.t = u.t;
+            where ownerId = ${ownerId} and evolu_timestamp.t = u.t;
           `,
             ];
             break;
@@ -499,10 +540,7 @@ const insertTimestamp = (deps) => (ownerId, timestamp, level, strategy) => {
                     h2 = u.h2,
                     c = c + 1
                   from u
-                  where
-                    changes() > 0
-                    and ownerId = ${ownerId}
-                    and evolu_timestamp.t = u.t;
+                  where ownerId = ${ownerId} and evolu_timestamp.t = u.t;
                 `,
                     ]
                     : [
@@ -684,15 +722,25 @@ const insertTimestamp = (deps) => (ownerId, timestamp, level, strategy) => {
                     h2 = uh2,
                     c = uc
                   from u
-                  where changes() > 0 and ownerId = ${ownerId} and t = ut;
+                  where ownerId = ${ownerId} and t = ut;
                 `,
                     ];
             break;
     }
-    for (const query of queries) {
-        deps.sqlite.exec(query);
-    }
+    // The insert uses "on conflict do nothing". An existing timestamp changes
+    // nothing, and the metadata updates are skipped.
+    const [insert, ...updates] = queries;
+    if (deps.sqlite.exec(insert).changes === 0)
+        return false;
+    for (const update of updates)
+        deps.sqlite.exec(update);
+    return true;
 };
+/**
+ * Computes the {@link Fingerprint} of a single timestamp.
+ *
+ * @group Ranges
+ */
 export const timestampBytesToFingerprint = (timestamp) => {
     const hash = sha256(timestamp).slice(0, fingerprintSize);
     return hash;
@@ -700,6 +748,8 @@ export const timestampBytesToFingerprint = (timestamp) => {
 /**
  * Computes a brute-force {@link Fingerprint} from {@link TimestampBytes} values
  * for tests and benchmarks.
+ *
+ * @group Testing
  */
 export const testFingerprintTimestamps = (timestamps) => timestamps
     .map(timestampBytesToFingerprint)
@@ -1013,6 +1063,11 @@ const fingerprintRanges = (deps) => (ownerId, buckets, upperBound = InfiniteUppe
 };
 // XOR in SQLite
 const x = (a, b) => sql.raw(`(${a} | ${b}) - (${a} & ${b})`);
+/**
+ * Reads the timestamp at a position within an owner's ordered timestamps.
+ *
+ * @group SQLite
+ */
 export const getTimestampByIndex = (deps) => (ownerId, index) => {
     const result = deps.sqlite.exec(sql.prepared `
       with
@@ -1087,7 +1142,11 @@ export const getTimestampByIndex = (deps) => (ownerId, index) => {
     `);
     return result.rows[0].pt;
 };
-/** Reads owner usage from SQLite and returns default bounds when absent. */
+/**
+ * Reads owner usage from SQLite and returns default bounds when absent.
+ *
+ * @group SQLite
+ */
 export const readOwnerUsageOrDefault = (deps) => (ownerIdBytes, initialTimestamp) => {
     const result = deps.sqlite.exec(sql `
       select storedBytes, firstTimestamp, lastTimestamp
@@ -1115,6 +1174,8 @@ export const readOwnerUsageOrDefault = (deps) => (ownerIdBytes, initialTimestamp
  *
  * Used by both relay and client to maintain firstTimestamp/lastTimestamp after
  * processing messages.
+ *
+ * @group SQLite
  */
 export const updateOwnerUsage = (deps) => (ownerIdBytes, storedBytes, firstTimestamp, lastTimestamp) => {
     deps.sqlite.exec(sql `