@evolu/common 8.9.0 → 8.11.0

package/src/local-first/Schema.ts

@@ -23,22 +23,32 @@ import {
   type SqliteSchema,
   SqliteValue,
 } from "../Sqlite.ts";
+import type { Millis } from "../Time.ts";
 import {
   assertType,
+  createIdFromString,
   DateIso,
   type FiniteNumber,
   type Id,
+  id,
   IdBytes,
   type InferType,
+  NonEmptyTrimmedString100,
   Null,
   nullOr,
   object,
   type ObjectType,
   type UnionType,
+  type withDefault,
 } from "../Type.ts";
 import type { CompileTimeError, Simplify } from "../Types.ts";
-import type { AppOwner } from "./Owner.ts";
-import { OwnerId } from "./Owner.ts";
+import type { AppOwner, OwnerIdBytes } from "./Owner.ts";
+import {
+  OwnerEncryptionKey,
+  OwnerId,
+  OwnerSecret,
+  OwnerWriteKey,
+} from "./Owner.ts";
 import type {
   evoluJsonArrayFrom,
   evoluJsonObjectFrom,
@@ -48,7 +58,11 @@ import type {
 import type { CrdtMessage, DbChange } from "./Storage.ts";
 import { TimestampBytes } from "./Timestamp.ts";
 
-/** Any Standard Schema V1 declaration. */
+/**
+ * Any Standard Schema V1 declaration.
+ *
+ * @group Core
+ */
 export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
 
 /**
@@ -65,6 +79,16 @@ export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
  * Table schema defines columns that are required for table rows. For optional
  * columns, use a schema whose output type includes `null`.
  *
+ * Prefer applying defaults when reading or displaying data. A nullable column
+ * can preserve the distinction between "not specified" and an explicitly chosen
+ * value. For example, `null` can mean no notification preference, while an
+ * explicit false value means notifications were disabled.
+ *
+ * Use {@link withDefault} only when replacing absence is intentional. Storing
+ * defaulted values can add unnecessary data to database rows and erase that
+ * distinction. Store a value when it represents a user's decision or another
+ * fact your application needs to retain.
+ *
  * ### Example
  *
  * ```ts
@@ -110,6 +134,8 @@ export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
  * };
  * assertTrue(ZodSchema.todo.title.safeParse("Write docs").success);
  * ```
+ *
+ * @group Core
  */
 export type EvoluSchema = ReadonlyRecord<
   string,
@@ -117,9 +143,127 @@ export type EvoluSchema = ReadonlyRecord<
   TableSchema
 >;
 
-/** A table schema: column names mapped to Standard Schema validators. */
+/**
+ * A table schema: column names mapped to Standard Schema validators.
+ *
+ * @group Core
+ */
 export type TableSchema = ReadonlyRecord<string, AnyStandardSchemaV1>;
 
+/**
+ * Whether a table is local-only: its name starts with an underscore, so its
+ * changes are stored without synchronization.
+ *
+ * @group Core
+ */
+export const isLocalOnlyTable = (table: string): boolean =>
+  table.startsWith("_");
+
+/**
+ * Todo ID Type for {@link testEvoluSchema}.
+ *
+ * @group Testing
+ */
+export const TestTodoId = /*#__PURE__*/ id("Todo");
+export type TestTodoId = typeof TestTodoId.Output;
+
+/**
+ * Deterministic {@link TestTodoId} for tests and examples.
+ *
+ * @group Testing
+ */
+export const testTodoId = /*#__PURE__*/ TestTodoId.orThrow(
+  /*#__PURE__*/ createIdFromString("testTodo"),
+);
+
+/**
+ * Project ID Type for {@link testEvoluSchema}.
+ *
+ * @group Testing
+ */
+export const TestProjectId = /*#__PURE__*/ id("Project");
+export type TestProjectId = typeof TestProjectId.Output;
+
+/**
+ * Deterministic {@link TestProjectId} for tests and examples.
+ *
+ * @group Testing
+ */
+export const testProjectId = /*#__PURE__*/ TestProjectId.orThrow(
+  /*#__PURE__*/ createIdFromString("testProject"),
+);
+
+/**
+ * Todo and project schema for tests and examples. A todo can belong to a
+ * project or have no project. Use an explicit schema when teaching schema
+ * definition.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertOk,
+ *   testEvoluSchema,
+ *   testProjectId,
+ *   testTodoId,
+ * } from "@evolu/common";
+ *
+ * assertOk(testEvoluSchema.todo.id.from(testTodoId), testTodoId);
+ * assertOk(
+ *   testEvoluSchema.todo.projectId.from(testProjectId),
+ *   testProjectId,
+ * );
+ * ```
+ *
+ * @group Testing
+ */
+export const testEvoluSchema = {
+  todo: {
+    id: TestTodoId,
+    title: NonEmptyTrimmedString100,
+    isCompleted: /*#__PURE__*/ nullOr(SqliteBoolean),
+    projectId: /*#__PURE__*/ nullOr(TestProjectId),
+  },
+  project: {
+    id: TestProjectId,
+    name: NonEmptyTrimmedString100,
+  },
+} as const satisfies EvoluSchema;
+
+/**
+ * Schema type of {@link testEvoluSchema}.
+ *
+ * @group Testing
+ */
+export type TestEvoluSchema = typeof testEvoluSchema;
+
+/**
+ * App-owner registry schema with local tables for tests and examples.
+ *
+ * Stores operational keys separately from optional recovery material. A null
+ * secret represents an owner whose recovery material is managed elsewhere or
+ * unavailable. Names are optional device-local labels; identicons can be
+ * derived from the owner identity without an additional column.
+ *
+ * This fixture does not define the production registry's persistence contract.
+ *
+ * @group Testing
+ */
+export const testLocalOnlyEvoluSchema = {
+  _appOwner: {
+    id: OwnerId,
+    encryptionKey: OwnerEncryptionKey,
+    writeKey: OwnerWriteKey,
+    secret: /*#__PURE__*/ nullOr(OwnerSecret),
+    name: /*#__PURE__*/ nullOr(NonEmptyTrimmedString100),
+  },
+} as const satisfies EvoluSchema;
+
+/**
+ * Dependency wrapper for {@link SqliteSchema}.
+ *
+ * @group SQLite
+ */
 export interface SqliteSchemaDep {
   readonly sqliteSchema: SqliteSchema;
 }
@@ -136,6 +280,8 @@ export interface SqliteSchemaDep {
  * 2. The 'id' column output type must extend {@link Id}
  * 3. Tables cannot use system column names (createdAt, updatedAt, isDeleted)
  * 4. All column output types must be compatible with SQLite (extend SqliteValue)
+ *
+ * @group Validation
  */
 export type ValidateSchema<S extends EvoluSchema> =
   ValidateSchemaHasId<S> extends never
@@ -148,10 +294,106 @@ export type ValidateSchema<S extends EvoluSchema> =
       : ValidateIdColumnType<S>
     : ValidateSchemaHasId<S>;
 
+/**
+ * Defines SQLite indexes with Kysely's index builder.
+ *
+ * @group SQLite
+ */
 export type IndexesConfig = (
   create: (indexName: string) => Kysely.CreateIndexBuilder,
 ) => ReadonlyArray<Kysely.CreateIndexBuilder<any>>;
 
+/**
+ * Why a message is stored in `evolu_message_quarantine` instead of being
+ * applied to its table. Persisted codes: names may change, but numbers must not
+ * be reassigned.
+ *
+ * Quarantine is queryable state, not an error. An application subscribes to a
+ * query over `evolu_message_quarantine` to tell the user what is waiting. Each
+ * row is one column of a message, so distinct `ownerId` and `timestamp` pairs
+ * count messages. `origin` records whether this database stamped the message
+ * for a local mutation or received it from sync, see {@link QuarantineOrigin}.
+ * `quarantinedAt` is the system time captured for the request that quarantined
+ * the row, in milliseconds; it is null for rows written before Evolu recorded
+ * it. The clock-drift rules are described in the Timestamp module.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertType,
+ *   createQueryBuilder,
+ *   type Millis,
+ *   type OwnerIdBytes,
+ *   type QuarantineOrigin,
+ *   QuarantineReason,
+ *   testEvoluSchema,
+ *   type TimestampBytes,
+ * } from "@evolu/common";
+ *
+ * const createQuery = createQueryBuilder(testEvoluSchema);
+ *
+ * // Messages waiting in drift quarantine, one row per message.
+ * const driftQuarantineQuery = createQuery((db) =>
+ *   db
+ *     .selectFrom("evolu_message_quarantine")
+ *     .select(["ownerId", "timestamp", "origin", "quarantinedAt"])
+ *     .where("reason", "=", QuarantineReason.TimestampDrift)
+ *     .distinct(),
+ * );
+ *
+ * assertType<
+ *   typeof driftQuarantineQuery.Row,
+ *   {
+ *     ownerId: OwnerIdBytes;
+ *     timestamp: TimestampBytes;
+ *     origin: QuarantineOrigin;
+ *     quarantinedAt: Millis | null;
+ *   }
+ * >();
+ * ```
+ *
+ * @group Queries
+ */
+export const QuarantineReason = {
+  /**
+   * The message has a table or column the current schema does not define. It is
+   * applied automatically once a schema update defines them. A received change
+   * to a {@link isLocalOnlyTable | local-only} table is also stored here and is
+   * never applied.
+   */
+  Schema: 0,
+  /**
+   * The message's timestamp exceeded the drift limit when it was stored. It is
+   * applied when the database worker starts, once system time comes within the
+   * limit of the timestamp.
+   */
+  TimestampDrift: 1,
+} as const;
+
+export type QuarantineReason =
+  (typeof QuarantineReason)[keyof typeof QuarantineReason];
+
+/**
+ * Whether a quarantined message was stamped by this database for a local
+ * mutation or received from sync. Persisted codes: names may change, but
+ * numbers must not be reassigned.
+ *
+ * @group Queries
+ */
+export const QuarantineOrigin = {
+  LocalMutation: 0,
+  ReceivedMessage: 1,
+} as const;
+
+export type QuarantineOrigin =
+  (typeof QuarantineOrigin)[keyof typeof QuarantineOrigin];
+
+/**
+ * Typed query factory returned by {@link createQueryBuilder}.
+ *
+ * @group Queries
+ */
 export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
   queryCallback: (
     db: Pick<
@@ -164,6 +406,7 @@ export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
           } & SystemColumns;
         } & {
           readonly evolu_history: {
+            readonly ownerId: OwnerIdBytes;
             readonly timestamp: TimestampBytes;
             readonly table: keyof S;
             readonly id: IdBytes;
@@ -171,11 +414,15 @@ export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
             readonly value: SqliteValue;
           };
           readonly evolu_message_quarantine: {
+            readonly ownerId: OwnerIdBytes;
             readonly timestamp: TimestampBytes;
             readonly table: string;
             readonly id: IdBytes;
             readonly column: string;
             readonly value: SqliteValue;
+            readonly reason: QuarantineReason;
+            readonly origin: QuarantineOrigin;
+            readonly quarantinedAt: Millis | null;
           };
         }
       >,
@@ -193,6 +440,8 @@ export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
  * - `isDeleted`: Soft delete flag created by Evolu and used by the developer to
  *   mark rows as deleted.
  * - `ownerId`: Represents ownership and logically partitions the database.
+ *
+ * @group Core
  */
 export const SystemColumns: ObjectType<{
   readonly createdAt: typeof DateIso;
@@ -207,6 +456,11 @@ export const SystemColumns: ObjectType<{
 });
 export interface SystemColumns extends InferType<typeof SystemColumns> {}
 
+/**
+ * Kind of a {@link Mutation}: insert, update, or upsert.
+ *
+ * @group Mutations
+ */
 export type MutationKind = "insert" | "update" | "upsert";
 
 /**
@@ -228,6 +482,8 @@ export type MutationKind = "insert" | "update" | "upsert";
  *   `id` omitted (auto-generated)
  * - **update**: only `id` required, everything else optional
  * - **upsert**: like insert but `id` required too
+ *
+ * @group Mutations
  */
 export type Mutation<S extends EvoluSchema, Kind extends MutationKind> = <
   TableName extends keyof S,
@@ -237,11 +493,26 @@ export type Mutation<S extends EvoluSchema, Kind extends MutationKind> = <
   options?: MutationOptions,
 ) => { readonly id: StandardSchemaV1.InferOutput<S[TableName]["id"]> };
 
+/**
+ * Options accepted by every {@link Mutation}.
+ *
+ * @group Mutations
+ */
 export interface MutationOptions {
   /**
-   * Called after the mutation is completed and the local state is updated.
-   * Useful for triggering side effects (e.g., notifications, UI updates) after
-   * insert, update, or upsert.
+   * Called after the mutation's changes are stored and subscribed queries
+   * reflect them. Useful for follow-up work (e.g., notifications, navigation)
+   * after insert, update, or upsert. It never runs when the database is
+   * unavailable.
+   *
+   * Stored does not always mean visible. A change quarantined for
+   * {@link QuarantineReason.TimestampDrift} is stored in
+   * `evolu_message_quarantine` without changing application rows. `onComplete`
+   * still fires after storage commits; no drift error is reported. Applications
+   * can subscribe to the quarantine table; those query results reflect the
+   * change before `onComplete` runs. See the
+   * {@link @evolu/common!"local-first/Timestamp" | Timestamp module} for drift
+   * and release behavior.
    */
   readonly onComplete?: () => void;
 
@@ -306,6 +577,12 @@ export interface MutationOptions {
   readonly ownerId?: OwnerId;
 }
 
+/**
+ * Database change produced by a {@link Mutation}, attributed to the
+ * {@link OwnerId} that owns the row.
+ *
+ * @group Mutations
+ */
 export interface MutationChange extends DbChange {
   readonly ownerId: OwnerId;
 }
@@ -313,6 +590,8 @@ export interface MutationChange extends DbChange {
 /**
  * Derives the expected values type for a mutation from a table's column schemas
  * and a {@link MutationKind}.
+ *
+ * @group Mutations
  */
 export type MutationValues<
   T extends TableSchema,
@@ -328,6 +607,8 @@ export type MutationValues<
 /**
  * Insert values: `id` omitted (auto-generated), nullable columns optional,
  * non-nullable columns required.
+ *
+ * @group Mutations
  */
 export type InsertValues<T extends TableSchema> = Omit<
   NullableColumnsToOptional<T>,
@@ -337,6 +618,8 @@ export type InsertValues<T extends TableSchema> = Omit<
 /**
  * Update values: `id` required, all other columns optional. Includes
  * `isDeleted` for soft deletes.
+ *
+ * @group Mutations
  */
 export type UpdateValues<T extends TableSchema> = {
   readonly id: StandardSchemaV1.InferOutput<T["id"]>;
@@ -349,12 +632,19 @@ export type UpdateValues<T extends TableSchema> = {
 /**
  * Upsert values: `id` required, nullable columns optional, non-nullable columns
  * required. Includes `isDeleted` for soft deletes.
+ *
+ * @group Mutations
  */
 export type UpsertValues<T extends TableSchema> =
   NullableColumnsToOptional<T> & {
     readonly isDeleted?: SqliteBoolean;
   };
 
+/**
+ * Requires an `id` column in every table.
+ *
+ * @group Validation
+ */
 export type ValidateSchemaHasId<S extends EvoluSchema> =
   keyof S extends infer TableName
     ? TableName extends keyof S
@@ -364,6 +654,11 @@ export type ValidateSchemaHasId<S extends EvoluSchema> =
       : never
     : never;
 
+/**
+ * Requires every `id` column output type to extend {@link Id}.
+ *
+ * @group Validation
+ */
 export type ValidateIdColumnType<S extends EvoluSchema> =
   keyof S extends infer TableName
     ? TableName extends keyof S
@@ -375,6 +670,11 @@ export type ValidateIdColumnType<S extends EvoluSchema> =
       : never
     : never;
 
+/**
+ * Rejects tables that define system column names.
+ *
+ * @group Validation
+ */
 export type ValidateNoSystemColumns<S extends EvoluSchema> =
   keyof S extends infer TableName
     ? TableName extends keyof S
@@ -389,6 +689,11 @@ export type ValidateNoSystemColumns<S extends EvoluSchema> =
       : never
     : never;
 
+/**
+ * Requires every column output type to be compatible with SQLite.
+ *
+ * @group Validation
+ */
 export type ValidateColumnTypes<S extends EvoluSchema> =
   keyof S extends infer TableName
     ? TableName extends keyof S
@@ -403,36 +708,69 @@ export type ValidateColumnTypes<S extends EvoluSchema> =
       : never
     : never;
 
-/** Schema validation error that shows clear, readable messages */
+/**
+ * Schema validation error that shows clear, readable messages
+ *
+ * @group Validation
+ */
 export type SchemaValidationError<Message extends string> = CompileTimeError<
   "Schema",
   Message
 >;
 
-/** Makes columns whose output type includes `null` optional. */
+/**
+ * Makes columns whose output type includes `null` optional.
+ *
+ * @group Mutations
+ */
 export type NullableColumnsToOptional<T extends TableSchema> = {
   readonly [K in RequiredColumnKeys<T>]: StandardSchemaV1.InferOutput<T[K]>;
 } & {
   readonly [K in OptionalColumnKeys<T>]?: StandardSchemaV1.InferOutput<T[K]>;
 };
 
+/**
+ * Column names whose output type excludes `null`.
+ *
+ * @group Mutations
+ */
 export type RequiredColumnKeys<T extends TableSchema> = {
   [K in keyof T]: null extends StandardSchemaV1.InferOutput<T[K]> ? never : K;
 }[keyof T];
 
+/**
+ * Column names whose output type includes `null`.
+ *
+ * @group Mutations
+ */
 export type OptionalColumnKeys<T extends TableSchema> = {
   [K in keyof T]: null extends StandardSchemaV1.InferOutput<T[K]> ? K : never;
 }[keyof T];
 
+/**
+ * Names of {@link SystemColumns}.
+ *
+ * @group Core
+ */
 export const systemColumns: ReadonlySet<string> = /*#__PURE__*/ new Set(
   /*#__PURE__*/ Object.keys(SystemColumns.props),
 );
 
+/**
+ * Names of {@link SystemColumns} together with `id`.
+ *
+ * @group Core
+ */
 export const systemColumnsWithId: ReadonlyArray<string> = [
   ...systemColumns,
   "id",
 ];
 
+/**
+ * Derives {@link SqliteSchema} tables and indexes from an {@link EvoluSchema}.
+ *
+ * @group SQLite
+ */
 export const evoluSchemaToSqliteSchema = <S extends EvoluSchema>(
   schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>,
   indexesConfig?: IndexesConfig,
@@ -469,24 +807,14 @@ export const evoluSchemaToSqliteSchema = <S extends EvoluSchema>(
  * import {
  *   assertType,
  *   createQueryBuilder,
- *   id,
+ *   testEvoluSchema,
+ *   type TestTodoId,
  *   NonEmptyTrimmedString100,
- *   nullOr,
  *   SqliteBoolean,
  * } from "@evolu/common";
  *
- * const TodoId = id("Todo");
- * type TodoId = typeof TodoId.Output;
- * const Schema = {
- *   todo: {
- *     id: TodoId,
- *     title: NonEmptyTrimmedString100,
- *     isCompleted: nullOr(SqliteBoolean),
- *   },
- * };
- *
  * // Create one typed builder per schema and reuse it for every query.
- * const createQuery = createQueryBuilder(Schema);
+ * const createQuery = createQueryBuilder(testEvoluSchema);
  * const todosQuery = createQuery((db) =>
  *   db.selectFrom("todo").select(["id", "title", "isCompleted"]),
  * );
@@ -494,12 +822,14 @@ export const evoluSchemaToSqliteSchema = <S extends EvoluSchema>(
  * assertType<
  *   typeof todosQuery.Row,
  *   {
- *     id: TodoId;
+ *     id: TestTodoId;
  *     title: NonEmptyTrimmedString100 | null;
  *     isCompleted: SqliteBoolean | null;
  *   }
  * >();
  * ```
+ *
+ * @group Queries
  */
 export const createQueryBuilder = <S extends EvoluSchema>(
   _schema: S,
@@ -519,6 +849,12 @@ export const createQueryBuilder = <S extends EvoluSchema>(
   return createQuery;
 };
 
+/**
+ * Creates missing tables, columns, and indexes, and drops indexes that the new
+ * schema no longer defines.
+ *
+ * @group SQLite
+ */
 export const ensureSqliteSchema =
   (deps: SqliteDep) =>
   (newSchema: SqliteSchema, currentSchema?: SqliteSchema): void => {
@@ -570,10 +906,24 @@ export const ensureSqliteSchema =
     }
   };
 
+/**
+ * Reads the current application {@link SqliteSchema}, excluding Evolu's internal
+ * indexes.
+ *
+ * @group SQLite
+ */
 export const getEvoluSqliteSchema = (deps: SqliteDep) => (): SqliteSchema =>
   getSqliteSchema(deps)({ excludeIndexNamePrefix: "evolu_" });
 
-// https://kysely.dev/docs/recipes/splitting-query-building-and-execution
+/**
+ * Kysely instance that only compiles queries to SQL. It never executes them;
+ * Evolu runs the compiled SQL itself.
+ *
+ * See [Splitting query building and
+ * execution](https://kysely.dev/docs/recipes/splitting-query-building-and-execution).
+ *
+ * @group Queries
+ */
 export const kysely = /*#__PURE__*/ new Kysely.Kysely({
   dialect: {
     createAdapter: () => new Kysely.SqliteAdapter(),