@evolu/common 8.9.0 → 8.11.0

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

@@ -7,9 +7,177 @@ import * as Kysely from "kysely";
 import { assertNonNullable } from "../Assert.js";
 import { getOwnProp, mapObject } from "../Object.js";
 import { eqSqliteIndex, getSqliteSchema, sql, sqliteQueryToSqliteQueryString, SqliteBoolean, SqliteQueryParameters, SqliteValue, } from "../Sqlite.js";
-import { assertType, DateIso, IdBytes, Null, nullOr, object, } from "../Type.js";
-import { OwnerId } from "./Owner.js";
+import { assertType, createIdFromString, DateIso, id, IdBytes, NonEmptyTrimmedString100, Null, nullOr, object, } from "../Type.js";
+import { OwnerEncryptionKey, OwnerId, OwnerSecret, OwnerWriteKey, } from "./Owner.js";
 import { TimestampBytes } from "./Timestamp.js";
+/**
+ * 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) => table.startsWith("_");
+/**
+ * Todo ID Type for {@link testEvoluSchema}.
+ *
+ * @group Testing
+ */
+export const TestTodoId = /*#__PURE__*/ id("Todo");
+/**
+ * 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");
+/**
+ * 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,
+    },
+};
+/**
+ * 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),
+    },
+};
+/**
+ * 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,
+};
+/**
+ * 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,
+};
 /**
  * System columns that are implicitly defined by Evolu.
  *
@@ -18,6 +186,8 @@ import { TimestampBytes } from "./Timestamp.js";
  * - `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 = /*#__PURE__*/ object({
     createdAt: DateIso,
@@ -25,12 +195,27 @@ export const SystemColumns = /*#__PURE__*/ object({
     isDeleted: /*#__PURE__*/ nullOr(SqliteBoolean),
     ownerId: OwnerId,
 });
+/**
+ * Names of {@link SystemColumns}.
+ *
+ * @group Core
+ */
 export const systemColumns = /*#__PURE__*/ new Set(
 /*#__PURE__*/ Object.keys(SystemColumns.props));
+/**
+ * Names of {@link SystemColumns} together with `id`.
+ *
+ * @group Core
+ */
 export const systemColumnsWithId = [
     ...systemColumns,
     "id",
 ];
+/**
+ * Derives {@link SqliteSchema} tables and indexes from an {@link EvoluSchema}.
+ *
+ * @group SQLite
+ */
 export const evoluSchemaToSqliteSchema = (schema, indexesConfig) => {
     const validSchema = schema;
     const tables = mapObject(validSchema, (table) => new Set(Object.keys(table).filter((k) => k !== "id")));
@@ -57,24 +242,14 @@ export const evoluSchemaToSqliteSchema = (schema, indexesConfig) => {
  * 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"]),
  * );
@@ -82,12 +257,14 @@ export const evoluSchemaToSqliteSchema = (schema, indexesConfig) => {
  * assertType<
  *   typeof todosQuery.Row,
  *   {
- *     id: TodoId;
+ *     id: TestTodoId;
  *     title: NonEmptyTrimmedString100 | null;
  *     isCompleted: SqliteBoolean | null;
  *   }
  * >();
  * ```
+ *
+ * @group Queries
  */
 export const createQueryBuilder = (_schema) => {
     const createQuery = (queryCallback, options) => {
@@ -102,6 +279,12 @@ export const createQueryBuilder = (_schema) => {
     };
     return createQuery;
 };
+/**
+ * Creates missing tables, columns, and indexes, and drops indexes that the new
+ * schema no longer defines.
+ *
+ * @group SQLite
+ */
 export const ensureSqliteSchema = (deps) => (newSchema, currentSchema) => {
     const queries = [];
     currentSchema ??= getEvoluSqliteSchema(deps)();
@@ -136,8 +319,22 @@ export const ensureSqliteSchema = (deps) => (newSchema, currentSchema) => {
         deps.sqlite.exec(query);
     }
 };
+/**
+ * Reads the current application {@link SqliteSchema}, excluding Evolu's internal
+ * indexes.
+ *
+ * @group SQLite
+ */
 export const getEvoluSqliteSchema = (deps) => () => 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(),