@evolu/common 8.0.0-next.4 → 8.0.0

package/src/local-first/Query.ts

@@ -21,15 +21,14 @@ import {
   TableNode,
   ValueNode,
 } from "kysely";
-import type { Brand } from "../Brand.js";
-import { createRandomBytes } from "../Crypto.js";
-import type { ReadonlyRecord } from "../Object.js";
-import { createRecord, isPlainObject } from "../Object.js";
-import type { SqliteQueryString } from "../Sqlite.js";
-import { eqSqliteValue, SqliteValue } from "../Sqlite.js";
-import { createId, String } from "../Type.js";
-import type { Simplify } from "../Types.js";
-import type { EvoluSchema } from "./Schema.js";
+import type { Brand } from "../Brand.ts";
+import { createRandomBytes } from "../Crypto.ts";
+import type { ReadonlyRecord } from "../Object.ts";
+import { createMutableRecord, isPlainObject } from "../Object.ts";
+import type { SqliteQueryString } from "../Sqlite.ts";
+import { eqSqliteValue, SqliteValue } from "../Sqlite.ts";
+import { createId, String } from "../Type.ts";
+import type { EvoluSchema } from "./Schema.ts";
 
 export { sql as kyselySql } from "kysely";
 export type { NotNull as KyselyNotNull } from "kysely";
@@ -40,9 +39,27 @@ export type { NotNull as KyselyNotNull } from "kysely";
  * ### Example
  *
  * ```ts
+ * import {
+ *   createQueryBuilder,
+ *   id,
+ *   NonEmptyTrimmedString100,
+ *   type Query,
+ * } from "@evolu/common";
+ *
+ * const TodoId = id("Todo");
+ * type TodoId = typeof TodoId.Output;
+ * const Schema = {
+ *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
+ * };
  * const createQuery = createQueryBuilder(Schema);
  * const allTodos = createQuery((db) => db.selectFrom("todo").selectAll());
+ *
  * type AllTodosRow = typeof allTodos.Row;
+ * expectTypeOf<typeof allTodos>().toExtend<Query<typeof Schema>>();
+ * expectTypeOf<AllTodosRow["id"]>().toEqualTypeOf<TodoId>();
+ * expectTypeOf<
+ *   AllTodosRow["title"]
+ * >().toEqualTypeOf<NonEmptyTrimmedString100 | null>();
  * ```
  */
 export type Query<
@@ -59,11 +76,25 @@ export type Query<
      * ### Example
      *
      * ```ts
+     * import {
+     *   createQueryBuilder,
+     *   id,
+     *   type InferRow,
+     *   NonEmptyTrimmedString100,
+     * } from "@evolu/common";
+     *
+     * const Schema = {
+     *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
+     * };
      * const createQuery = createQueryBuilder(Schema);
      * const allTodos = createQuery((db) =>
      *   db.selectFrom("todo").selectAll(),
      * );
+     *
      * type AllTodosRow = typeof allTodos.Row;
+     * expectTypeOf<AllTodosRow>().toEqualTypeOf<
+     *   InferRow<typeof allTodos>
+     * >();
      * ```
      */
     Row: R;
@@ -91,25 +122,42 @@ export interface Row {
  * ### Example
  *
  * ```ts
- * import { evoluJsonArrayFrom } from "@evolu/common";
+ * import {
+ *   createQueryBuilder,
+ *   evoluJsonArrayFrom,
+ *   id,
+ *   NonEmptyTrimmedString100,
+ * } from "@evolu/common";
  *
- * const result = await db
- *   .selectFrom("person")
- *   .select((eb) => [
- *     "id",
- *     evoluJsonArrayFrom(
- *       eb
- *         .selectFrom("pet")
- *         .select(["pet.id as pet_id", "pet.name"])
- *         .whereRef("pet.owner_id", "=", "person.id")
- *         .orderBy("pet.name"),
- *     ).as("pets"),
- *   ])
- *   .execute();
+ * const PersonId = id("Person");
+ * const Schema = {
+ *   person: { id: PersonId },
+ *   pet: {
+ *     id: id("Pet"),
+ *     name: NonEmptyTrimmedString100,
+ *     personId: PersonId,
+ *   },
+ * };
+ * const createQuery = createQueryBuilder(Schema);
+ * const people = createQuery((db) =>
+ *   db
+ *     .selectFrom("person")
+ *     .select(["person.id"])
+ *     .select((eb) => [
+ *       evoluJsonArrayFrom(
+ *         eb
+ *           .selectFrom("pet")
+ *           .select(["pet.id as petId", "pet.name"])
+ *           .whereRef("pet.personId", "=", "person.id")
+ *           .orderBy("pet.name"),
+ *       ).as("pets"),
+ *     ]),
+ * );
  *
- * result[0]?.id;
- * result[0]?.pets[0].pet_id;
- * result[0]?.pets[0].name;
+ * expectTypeOf<(typeof people.Row.pets)[number]>().toEqualTypeOf<{
+ *   petId: typeof Schema.pet.id.Output;
+ *   name: NonEmptyTrimmedString100 | null;
+ * }>();
  * ```
  */
 export const evoluJsonArrayFrom = <O>(
@@ -133,25 +181,44 @@ export const evoluJsonArrayFrom = <O>(
  * ### Example
  *
  * ```ts
- * import { evoluJsonObjectFrom } from "@evolu/common";
+ * import {
+ *   createQueryBuilder,
+ *   evoluJsonObjectFrom,
+ *   id,
+ *   NonEmptyTrimmedString100,
+ *   SqliteBoolean,
+ * } from "@evolu/common";
  *
- * const result = await db
- *   .selectFrom("person")
- *   .select((eb) => [
- *     "id",
- *     evoluJsonObjectFrom(
- *       eb
- *         .selectFrom("pet")
- *         .select(["pet.id as pet_id", "pet.name"])
- *         .whereRef("pet.owner_id", "=", "person.id")
- *         .where("pet.is_favorite", "=", true),
- *     ).as("favorite_pet"),
- *   ])
- *   .execute();
+ * const PersonId = id("Person");
+ * const Schema = {
+ *   person: { id: PersonId },
+ *   pet: {
+ *     id: id("Pet"),
+ *     name: NonEmptyTrimmedString100,
+ *     personId: PersonId,
+ *     isFavorite: SqliteBoolean,
+ *   },
+ * };
+ * const createQuery = createQueryBuilder(Schema);
+ * const people = createQuery((db) =>
+ *   db
+ *     .selectFrom("person")
+ *     .select(["person.id"])
+ *     .select((eb) => [
+ *       evoluJsonObjectFrom(
+ *         eb
+ *           .selectFrom("pet")
+ *           .select(["pet.id as petId", "pet.name"])
+ *           .whereRef("pet.personId", "=", "person.id")
+ *           .where("pet.isFavorite", "=", 1),
+ *       ).as("favoritePet"),
+ *     ]),
+ * );
  *
- * result[0]?.id;
- * result[0]?.favorite_pet?.pet_id;
- * result[0]?.favorite_pet?.name;
+ * expectTypeOf<typeof people.Row.favoritePet>().toEqualTypeOf<{
+ *   petId: typeof Schema.pet.id.Output;
+ *   name: NonEmptyTrimmedString100 | null;
+ * } | null>();
  * ```
  */
 export const evoluJsonObjectFrom = <O>(
@@ -173,24 +240,42 @@ export const evoluJsonObjectFrom = <O>(
  * ### Example
  *
  * ```ts
- * import { evoluJsonBuildObject, kyselySql } from "@evolu/common";
+ * import {
+ *   createQueryBuilder,
+ *   evoluJsonBuildObject,
+ *   id,
+ *   kyselySql,
+ *   NonEmptyTrimmedString100,
+ * } from "@evolu/common";
  *
- * const result = await db
- *   .selectFrom("person")
- *   .select((eb) => [
- *     "id",
- *     evoluJsonBuildObject({
- *       first: eb.ref("first_name"),
- *       last: eb.ref("last_name"),
- *       full: kyselySql<string>`first_name || ' ' || last_name`,
- *     }).as("name"),
- *   ])
- *   .execute();
+ * const Schema = {
+ *   person: {
+ *     id: id("Person"),
+ *     firstName: NonEmptyTrimmedString100,
+ *     lastName: NonEmptyTrimmedString100,
+ *   },
+ * };
+ * const createQuery = createQueryBuilder(Schema);
+ * const people = createQuery((db) =>
+ *   db
+ *     .selectFrom("person")
+ *     .select("person.id")
+ *     .select((eb) => [
+ *       evoluJsonBuildObject({
+ *         first: eb.ref("firstName"),
+ *         last: eb.ref("lastName"),
+ *         full: kyselySql<string>`${eb.ref("firstName")} || ' ' || ${eb.ref(
+ *           "lastName",
+ *         )}`,
+ *       }).as("name"),
+ *     ]),
+ * );
  *
- * result[0]?.id;
- * result[0]?.name.first;
- * result[0]?.name.last;
- * result[0]?.name.full;
+ * expectTypeOf<typeof people.Row.name>().toEqualTypeOf<{
+ *   first: NonEmptyTrimmedString100 | null;
+ *   last: NonEmptyTrimmedString100 | null;
+ *   full: string;
+ * }>();
  * ```
  */
 export const evoluJsonBuildObject = <
@@ -232,7 +317,7 @@ export const getJsonObjectArgs = (
 
 /** Rows returned by a query. */
 export type QueryRows<R extends Row = Row> = ReadonlyArray<
-  Readonly<Simplify<R>>
+  Readonly<KyselySimplify<R>>
 >;
 
 export type Queries<
@@ -396,7 +481,7 @@ const parse = (obj: unknown): unknown => {
 const parseObject = (
   obj: ReadonlyRecord<string, unknown>,
 ): ReadonlyRecord<string, unknown> => {
-  const result = createRecord();
+  const result = createMutableRecord();
   for (const key in obj) {
     result[key] = parse(obj[key]);
   }

package/src/local-first/Relay.ts

@@ -10,35 +10,35 @@ import {
   firstInArray,
   isNonEmptyArray,
   mapArray,
-} from "../Array.js";
-import { assert } from "../Assert.js";
-import type { TimingSafeEqualDep } from "../Crypto.js";
-import { err, ok } from "../Result.js";
-import type { SqliteDep } from "../Sqlite.js";
-import { sql } from "../Sqlite.js";
-import { createMutexByKey } from "../Task.js";
-import { Name, PositiveInt, uint8ArrayToBase64Url } from "../Type.js";
-import { isPromiseLike, type Awaitable } from "../Types.js";
+} from "../Array.ts";
+import { assert } from "../Assert.ts";
+import type { TimingSafeEqualDep } from "../Crypto.ts";
+import { err, ok } from "../Result.ts";
+import type { SqliteDep } from "../Sqlite.ts";
+import { sql } from "../Sqlite.ts";
+import { createMutexByKey } from "../Task.ts";
+import { Name, PositiveInt, uint8ArrayToBase64Url } from "../Type.ts";
+import { isPromiseLike, type Awaitable } from "../Types.ts";
 import {
   OwnerId,
   ownerIdBytesToOwnerId,
   // OwnerTransport,
   OwnerWriteKey,
-} from "./Owner.js";
+} from "./Owner.ts";
 import type {
   EncryptedDbChange,
   SqliteStorageDeps,
   Storage,
   StorageConfig,
   StorageQuotaError,
-} from "./Storage.js";
+} from "./Storage.ts";
 import {
   createBaseSqliteStorage,
   getTimestampInsertStrategy,
   readOwnerUsageOrDefault,
   updateOwnerUsage,
-} from "./Storage.js";
-import { timestampToTimestampBytes } from "./Timestamp.js";
+} from "./Storage.ts";
+import { timestampToTimestampBytes } from "./Timestamp.ts";
 
 export interface RelayConfig extends StorageConfig {
   /**
@@ -77,20 +77,50 @@ export interface RelayConfig extends StorageConfig {
    * ### Example
    *
    * ```ts
-   * // Client
+   * import {
+   *   AppName,
+   *   createAppOwner,
+   *   createEvolu,
+   *   createOwnerWebSocketTransport,
+   *   createOwnerSecret,
+   *   createRandomBytes,
+   *   id,
+   *   type AnyTask,
+   * } from "@evolu/common";
+   * import type { RelayConfig } from "@evolu/common/local-first";
+   *
+   * // Create once, persist the mnemonic securely, and restore it on later runs.
+   * const appOwner = createAppOwner(
+   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
+   * );
+   * // Client: include the OwnerId so the relay can authenticate the connection.
    * const transport = createOwnerWebSocketTransport({
    *   url: "wss://relay.evolu.dev",
-   *   ownerId: owner.id,
+   *   ownerId: appOwner.id,
    * });
    *
-   * const evolu = createEvolu(deps)(Schema, {
-   *   transports: [transport],
-   * });
+   * const createTodoEvolu = createEvolu(
+   *   { todo: { id: id("Todo") } },
+   *   {
+   *     appName: AppName.orThrow("AuthenticatedRelayExample"),
+   *     appOwner,
+   *     transports: [transport],
+   *   },
+   * );
+   * expectTypeOf(createTodoEvolu).toExtend<AnyTask>();
    *
+   * // Relay: accept owners allowed by the app's access policy.
+   * type IsOwnerAllowed = NonNullable<RelayConfig["isOwnerAllowed"]>;
+   * const allowedOwnerIds = new Set([appOwner.id]);
+   * const isOwnerAllowed: IsOwnerAllowed = (ownerId, { signal }) =>
+   *   !signal.aborted && allowedOwnerIds.has(ownerId);
    *
-   * // Relay
-   * isOwnerAllowed: (ownerId, { signal: _signal }) =>
-   *   Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),
+   * expect(
+   *   isOwnerAllowed(appOwner.id, {
+   *     signal: new AbortController().signal,
+   *   }),
+   * ).toBe(true);
+   * expect(transport.url).toContain(`ownerId=${appOwner.id}`);
    * ```
    */
   readonly isOwnerAllowed?: (

package/src/local-first/Schema.ts

@@ -5,7 +5,9 @@
  */
 
 import * as Kysely from "kysely";
-import { getProperty, mapObject, type ReadonlyRecord } from "../Object.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { assertNonNullable } from "../Assert.ts";
+import { getOwnProp, mapObject, type ReadonlyRecord } from "../Object.ts";
 import {
   eqSqliteIndex,
   getSqliteSchema,
@@ -19,29 +21,31 @@ import {
   type SqliteQueryOptions,
   type SqliteSchema,
   SqliteValue,
-} from "../Sqlite.js";
-import type { InferType } from "../Type.js";
+} from "../Sqlite.ts";
 import {
   DateIso,
   type Id,
   IdBytes,
+  type InferType,
+  Null,
   nullOr,
   object,
-  type StandardSchemaV1,
-} from "../Type.js";
-import type { Simplify } from "../Types.js";
-import type { AppOwner } from "./Owner.js";
-import { OwnerId } from "./Owner.js";
+  type ObjectType,
+  type UnionType,
+} from "../Type.ts";
+import type { CompileTimeError, Simplify } from "../Types.ts";
+import type { AppOwner } from "./Owner.ts";
+import { OwnerId } from "./Owner.ts";
 import type {
   evoluJsonArrayFrom,
   evoluJsonObjectFrom,
   Query,
   Row,
-} from "./Query.js";
-import type { CrdtMessage, DbChange } from "./Storage.js";
-import { TimestampBytes } from "./Timestamp.js";
+} from "./Query.ts";
+import type { CrdtMessage, DbChange } from "./Storage.ts";
+import { TimestampBytes } from "./Timestamp.ts";
 
-/** Any {@link StandardSchemaV1}. */
+/** Any Standard Schema V1 declaration. */
 export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
 
 /**
@@ -56,26 +60,36 @@ export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
  * ### Example
  *
  * ```ts
- * // With Evolu Type
+ * import * as z from "zod";
+ * import {
+ *   id,
+ *   NonEmptyTrimmedString100,
+ *   nullOr,
+ *   SqliteBoolean,
+ * } from "@evolu/common";
+ *
+ * // Evolu Type
  * const TodoId = id("Todo");
- * type TodoId = typeof TodoId.Type;
+ * type TodoId = typeof TodoId.Output;
  *
  * const Schema = {
  *   todo: {
  *     id: TodoId,
- *     title: NonEmptyString100,
+ *     title: NonEmptyTrimmedString100,
  *     isCompleted: nullOr(SqliteBoolean),
  *   },
  * };
+ * expectOk(Schema.todo.title.fromUnknown("Write docs"), "Write docs");
  *
- * // With Zod (or any Standard Schema library)
- * const Schema = {
+ * // Zod, or another Standard Schema library
+ * const ZodSchema = {
  *   todo: {
- *     id: TodoId, // Evolu id() for branded IDs
+ *     id: TodoId,
  *     title: z.string().min(1).max(100),
  *     isCompleted: z.union([z.literal(0), z.literal(1)]).nullable(),
  *   },
  * };
+ * expect(ZodSchema.todo.title.safeParse("Write docs").success).toBe(true);
  * ```
  */
 export type EvoluSchema = ReadonlyRecord<
@@ -150,7 +164,7 @@ export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
     >,
   ) => Kysely.SelectQueryBuilder<any, any, R>,
   options?: SqliteQueryOptions,
-) => Query<S, Simplify<R>>;
+) => Query<S, Kysely.Simplify<R>>;
 
 /**
  * System columns that are implicitly defined by Evolu.
@@ -161,7 +175,12 @@ export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
  *   mark rows as deleted.
  * - `ownerId`: Represents ownership and logically partitions the database.
  */
-export const SystemColumns = /*#__PURE__*/ object({
+export const SystemColumns: ObjectType<{
+  readonly createdAt: typeof DateIso;
+  readonly updatedAt: typeof DateIso;
+  readonly isDeleted: UnionType<readonly [typeof SqliteBoolean, typeof Null]>;
+  readonly ownerId: typeof OwnerId;
+}> = /*#__PURE__*/ object({
   createdAt: DateIso,
   updatedAt: DateIso,
   isDeleted: /*#__PURE__*/ nullOr(SqliteBoolean),
@@ -218,24 +237,50 @@ export interface MutationOptions {
    * ### Example
    *
    * ```ts
-   * // Partition your own data by project (derived from your AppOwner)
+   * import {
+   *   createAppOwner,
+   *   createOwnerSecret,
+   *   createRandomBytes,
+   *   createSharedOwner,
+   *   deriveShardOwner,
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   * } from "@evolu/common";
+   *
+   * const Schema = {
+   *   task: { id: id("Task"), title: NonEmptyTrimmedString100 },
+   *   comment: { id: id("Comment"), text: NonEmptyTrimmedString100 },
+   * };
+   * const randomBytes = createRandomBytes();
+   * // Create once, persist the mnemonic securely, and restore it on later runs.
+   * const appOwner = createAppOwner(createOwnerSecret({ randomBytes }));
    * const projectOwner = deriveShardOwner(appOwner, [
    *   "project",
-   *   projectId,
+   *   "project-1",
    * ]);
-   * evolu.insert(
-   *   "task",
-   *   { title: "Task 1" },
-   *   { ownerId: projectOwner.id },
+   * const sharedOwner = createSharedOwner(
+   *   createOwnerSecret({ randomBytes }),
    * );
    *
-   * // Collaborative data (independent owner shared with others)
-   * const sharedOwner = createSharedOwner(sharedSecret);
-   * evolu.insert(
-   *   "comment",
-   *   { text: "Hello" },
-   *   { ownerId: sharedOwner.id },
-   * );
+   * const insertOwnedRows = (evolu: Evolu<typeof Schema>): void => {
+   *   // Partition app data by project.
+   *   evolu.insert(
+   *     "task",
+   *     { title: NonEmptyTrimmedString100.orThrow("Task 1") },
+   *     { ownerId: projectOwner.id },
+   *   );
+   *
+   *   // Put collaborative data under a shared owner.
+   *   evolu.insert(
+   *     "comment",
+   *     { text: NonEmptyTrimmedString100.orThrow("Hello") },
+   *     { ownerId: sharedOwner.id },
+   *   );
+   * };
+   *
+   * expect(projectOwner.type).toBe("ShardOwner");
+   * expect(sharedOwner.type).toBe("SharedOwner");
    * ```
    */
   readonly ownerId?: OwnerId;
@@ -316,10 +361,7 @@ export type ValidateNoSystemColumns<S extends EvoluSchema> =
       ? keyof S[TableName] extends infer ColumnName
         ? ColumnName extends keyof S[TableName]
           ? ColumnName extends
-              | "createdAt"
-              | "updatedAt"
-              | "isDeleted"
-              | "ownerId"
+              "createdAt" | "updatedAt" | "isDeleted" | "ownerId"
             ? SchemaValidationError<`Table "${TableName & string}" uses system column name "${ColumnName & string}". System columns (createdAt, updatedAt, isDeleted, ownerId) are added automatically.`>
             : never
           : never
@@ -343,8 +385,10 @@ export type ValidateColumnTypes<S extends EvoluSchema> =
     : never;
 
 /** Schema validation error that shows clear, readable messages */
-export type SchemaValidationError<Message extends string> =
-  `❌ Schema Error: ${Message}`;
+export type SchemaValidationError<Message extends string> = CompileTimeError<
+  "Schema",
+  Message
+>;
 
 /** Makes columns whose output type includes `null` optional. */
 export type NullableColumnsToOptional<T extends TableSchema> = {
@@ -382,12 +426,10 @@ export const evoluSchemaToSqliteSchema = <S extends EvoluSchema>(
   );
 
   const indexes = indexesConfig
-    ? indexesConfig(createIndex).map(
-        (index): SqliteIndex => ({
-          name: index.toOperationNode().name.name,
-          sql: index.compile().sql,
-        }),
-      )
+    ? indexesConfig(createIndex).map((index): SqliteIndex => ({
+        name: index.toOperationNode().name.name,
+        sql: index.compile().sql,
+      }))
     : [];
 
   return { tables, indexes };
@@ -405,21 +447,36 @@ export const evoluSchemaToSqliteSchema = <S extends EvoluSchema>(
  * ### Example
  *
  * ```ts
+ * import {
+ *   createQueryBuilder,
+ *   id,
+ *   NonEmptyTrimmedString100,
+ *   nullOr,
+ *   SqliteBoolean,
+ * } from "@evolu/common";
+ *
+ * const TodoId = id("Todo");
+ * type TodoId = typeof TodoId.Output;
  * const Schema = {
  *   todo: {
- *     id: id("Todo"),
- *     title: NonEmptyString100,
+ *     id: TodoId,
+ *     title: NonEmptyTrimmedString100,
  *     isCompleted: nullOr(SqliteBoolean),
  *   },
  * };
  *
- * // Create a typed query builder (once per schema)
+ * // Create one typed builder per schema and reuse it for every query.
  * const createQuery = createQueryBuilder(Schema);
- *
- * // Use it for all queries
  * const todosQuery = createQuery((db) =>
  *   db.selectFrom("todo").select(["id", "title", "isCompleted"]),
  * );
+ *
+ * expectTypeOf<typeof todosQuery.Row>().toEqualTypeOf<{
+ *   id: TodoId;
+ *   title: NonEmptyTrimmedString100 | null;
+ *   isCompleted: SqliteBoolean | null;
+ * }>();
+ * expect(todosQuery).toBeTypeOf("string");
  * ```
  */
 export const createQueryBuilder = <S extends EvoluSchema>(
@@ -449,7 +506,8 @@ export const ensureSqliteSchema =
     currentSchema ??= getEvoluSqliteSchema(deps)();
 
     for (const [tableName, newColumns] of Object.entries(newSchema.tables)) {
-      const currentColumns = getProperty(currentSchema.tables, tableName);
+      assertNonNullable(newColumns);
+      const currentColumns = getOwnProp(currentSchema.tables, tableName);
       if (!currentColumns) {
         queries.push(createAppTable(tableName, newColumns));
       } else {