@evolu/common 6.0.1-preview.15 → 6.0.1-preview.17

package/src/Evolu/Evolu.ts

@@ -465,36 +465,36 @@ export type EvoluDeps = CreateDbWorkerDep &
   ConsoleDep &
   CreateAppStateDep;
 
-export interface EvoluConfigWithInitialData<S extends EvoluSchema = EvoluSchema>
-  extends Config {
+export interface EvoluConfigWithFunctions extends Config {
   /**
-   * Use this option to create initial data (fixtures).
+   * Callback invoked when the database is initialized. Use `isFirst` to perform
+   * one-time setup like initial data seeding.
    *
    * ### Example
    *
    * ```ts
    * const evolu = createEvolu(evoluReactWebDeps)(Schema, {
-   *   initialData: (evolu) => {
-   *     const todoCategory = evolu.insert("todoCategory", {
-   *       name: "Not Urgent",
-   *     });
+   *   onInit: ({ appOwner, isFirst }) => {
+   *     if (isFirst) {
+   *       const todoCategoryId = getOrThrow(
+   *         evolu.insert("todoCategory", {
+   *           name: "Not Urgent",
+   *         }),
+   *       );
    *
-   *     // This is a developer error, which should be fixed immediately.
-   *     assert(todoCategory.ok, "invalid initial data");
-   *
-   *     evolu.insert("todo", {
-   *       title: "Try React Suspense",
-   *       categoryId: todoCategory.value.id,
-   *     });
+   *       evolu.insert("todo", {
+   *         title: "Try React Suspense",
+   *         categoryId: todoCategoryId.id,
+   *       });
+   *     }
    *   },
    * });
    * ```
    */
-  initialData?: (evolu: EvoluForInitialData<S>) => void;
-}
-
-export interface EvoluForInitialData<S extends EvoluSchema = EvoluSchema> {
-  insert: Mutation<S, "insert">;
+  readonly onInit?: (params: {
+    readonly appOwner: AppOwner;
+    readonly isFirst: boolean;
+  }) => void;
 }
 
 // For hot reloading and Evolu multitenancy.
@@ -553,7 +553,7 @@ export const createEvolu =
   (deps: EvoluDeps) =>
   <S extends EvoluSchema>(
     schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>,
-    partialConfig: Partial<EvoluConfigWithInitialData<S>> = {},
+    partialConfig: Partial<EvoluConfigWithFunctions> = {},
   ): Evolu<S> => {
     const config = { ...defaultConfig, ...partialConfig };
 
@@ -577,17 +577,17 @@ const createEvoluInstance =
   (deps: EvoluDeps) =>
   (
     schema: EvoluSchema,
-    evoluConfig: EvoluConfigWithInitialData,
+    evoluConfig: EvoluConfigWithFunctions,
   ): InternalEvoluInstance => {
     deps.console.enabled = evoluConfig.enableLogging ?? false;
 
     deps.console.log("[evolu]", "createEvoluInstance");
 
-    const { initialData, indexes, ...config } = evoluConfig;
+    const { onInit, indexes, ...config } = evoluConfig;
 
     const errorStore = createStore<EvoluError | null>(null);
     const rowsStore = createStore<QueryRowsMap>(new Map());
-    const ownerStore = createStore<AppOwner | null>(null);
+    const appOwnerStore = createStore<AppOwner | null>(null);
     const syncStore = createStore<SyncState>(initialSyncState);
 
     const subscribedQueries = createSubscribedQueries(rowsStore);
@@ -605,7 +605,11 @@ const createEvoluInstance =
     dbWorker.onMessage((message) => {
       switch (message.type) {
         case "onInit": {
-          ownerStore.set(message.owner);
+          appOwnerStore.set(message.appOwner);
+          onInit?.({
+            appOwner: message.appOwner,
+            isFirst: message.isFirst,
+          });
           break;
         }
 
@@ -700,40 +704,10 @@ const createEvoluInstance =
       return type;
     };
 
-    const initialDataDbChanges: Array<DbChange> = [];
-
-    /**
-     * Note that the initial data function is called even if it is unnecessary
-     * (initial data are already in the DB) because we don't want to wait for
-     * SQLite's response. Initial data should be small (because they are inlined
-     * in the code), so it's ok.
-     */
-    if (initialData)
-      initialData({
-        insert: (table, props) => {
-          const id = createId(deps);
-          const values = getMutationType(table, "insert").fromUnknown(props);
-
-          if (values.ok) {
-            const valuesWithCreatedAt = {
-              ...values.value,
-              createdAt: new Date(deps.time.now()).toISOString(),
-            };
-            const dbChange = { table, id, values: valuesWithCreatedAt };
-            assertValidDbChange(dbChange);
-            initialDataDbChanges.push(dbChange);
-            return ok({ id });
-          }
-
-          return values;
-        },
-      });
-
     dbWorker.postMessage({
       type: "init",
       config,
       dbSchema,
-      initialData: initialDataDbChanges,
     });
 
     const loadQueryMicrotaskQueue: Array<Query> = [];
@@ -907,8 +881,8 @@ const createEvoluInstance =
       getQueryRows: <R extends Row>(query: Query<R>): QueryRows<R> =>
         (rowsStore.get().get(query) ?? emptyRows) as QueryRows<R>,
 
-      subscribeAppOwner: ownerStore.subscribe,
-      getAppOwner: ownerStore.get,
+      subscribeAppOwner: appOwnerStore.subscribe,
+      getAppOwner: appOwnerStore.get,
 
       subscribeSyncState: syncStore.subscribe,
       getSyncState: syncStore.get,

package/src/Evolu/Owner.ts

@@ -1,12 +1,36 @@
+/* eslint-disable jsdoc/no-undefined-types */
 /**
- * TODO:
+ * Evolu Owner - Data Ownership and Collaboration
+ *
+ * An {@link Owner} is an entity that represents ownership of data in Evolu. It
+ * consists of cryptographic keys derived from a {@link Mnemonic} via SLIP-21:
+ *
+ * - **{@link OwnerId}**: Globally unique public identifier
+ * - **{@link EncryptionKey}**: Symmetric encryption key for data protection
+ * - **{@link WriteKey}**: Authentication token for write operations
+ *
+ * Every Evolu app has at least one owner, the {@link AppOwner}. There are
+ * several owner variants for different use cases:
+ *
+ * **{@link ShardOwner}**: Derived from {@link AppOwner} for partitioning data and
+ * selective synchronization using {@link createShardOwner}
+ *
+ * **{@link SharedOwner}**: Created for collaboration with write access, not
+ * meant to be shared directly
+ *
+ * **{@link SharedReadonlyOwner}**: Read-only version for safe data sharing,
+ * created from {@link SharedOwner} using {@link createSharedReadonlyOwner}
+ *
+ * Owners are designed for data synchronization and backup. Authentication
+ * systems built on public/private key cryptography use these primitives. This
+ * design ensures Evolu Relay knows as little as possible - it only sees
+ * Timestamp, OwnerId, and EncryptedDbChange.
  *
  * @module
  */
 
-import { assert } from "../Assert.js";
+import { NonEmptyReadonlyArray } from "../Array.js";
 import {
-  createEncryptionKey,
   CreateMnemonicDep,
   CreateRandomBytesDep,
   createSlip21,
@@ -15,61 +39,26 @@ import {
   MnemonicSeed,
   mnemonicToMnemonicSeed,
 } from "../Crypto.js";
-import { NanoIdLibDep } from "../NanoId.js";
-import { TimeDep } from "../Time.js";
 import {
   Base64Url,
   brand,
-  DateIso,
-  DateIsoString,
   Id,
   length,
   Mnemonic,
   NonNegativeInt,
   Uint8Array,
 } from "../Type.js";
-import {
-  createInitialTimestamp,
-  TimestampString,
-  timestampToTimestampString,
-} from "./Timestamp.js";
-
-// TODO: Clean API
-// - createOwner should be createAppOwner
-// - Docs mention WriteKey is optional but it's required in Owner.
-// - For Protocol, we need only ownerId, encryptionKey, and writeKey.
-// - Not sure whether we need JSDoc for this module, and we don't
-//   use modules for Evolu internal API yet.
-// It's not single responsibility API.
 
 /**
- * `Owner` is an entity in Evolu that owns data, meaning it is locally stored on
- * a device under the user’s control. Data can be personal private, peer-to-peer
- * shared, or aggregated from multiple owners.
- *
- * An owner has a {@link Mnemonic} from which {@link OwnerId} and
- * {@link EncryptionKey} are deterministically derived using SLIP-21, and an
- * optional {@link WriteKey} that, when present, enables writing to the Evolu
- * Relay or peers. The {@link WriteKey} can be rotated.
+ * Represents ownership of data in Evolu. Created from a {@link Mnemonic} via
+ * SLIP-21 key derivation using {@link createOwner}, providing cryptographic keys
+ * for data access and authentication.
  *
- * Variants include {@link AppOwner}, {@link ShardOwner}, {@link SharedOwner}, and
- * {@link SharedReadonlyOwner}, each with specific roles and properties detailed
- * in their respective definitions.
- *
- * Public-key cryptography isn’t included here as it belongs to app and varies
- * by use case. An Evolu app without collaboration doesn’t need it, while a
- * Nostr-like app can leverage Nostr NIPs, or a super-safe app can use
- * post-quantum cryptography.
+ * - {@link OwnerId}: Globally unique public identifier
+ * - {@link EncryptionKey}: Symmetric encryption key for data protection
+ * - {@link WriteKey}: Authentication token for write operations (rotatable)
  */
 export interface Owner {
-  readonly mnemonic: Mnemonic;
-  readonly createdAt: DateIsoString;
-  readonly id: OwnerId;
-  readonly encryptionKey: EncryptionKey;
-  readonly writeKey: WriteKey;
-}
-
-export interface OwnerWithWriteAccess {
   readonly id: OwnerId;
   readonly encryptionKey: EncryptionKey;
   readonly writeKey: WriteKey;
@@ -89,203 +78,140 @@ export type OwnerId = typeof OwnerId.Type;
 export const writeKeyLength = 16 as NonNegativeInt;
 
 /**
- * A secure token proving the initiator can write changes. Derived from a
- * mnemonic or randomly generated. It's rotatable.
+ * A secure token proving that the initiator can write changes. Derived from a
+ * mnemonic or randomly generated via {@link createWriteKey}. It is rotatable.
  */
 export const WriteKey = brand("WriteKey", length(writeKeyLength)(Uint8Array));
 export type WriteKey = typeof WriteKey.Type;
 
-/**
- * The root owner of an Evolu app, created from a mnemonic safely generated on a
- * device when the app is initialized or restored on another device using an
- * existing mnemonic. It manages the app's core data, including the storage of
- * other owners' mnemonics in an encrypted app table. Its `writeKey` is
- * deterministic and rotatable. Never share the AppOwner mnemonic with anyone.
- */
-export interface AppOwner extends Owner {
-  readonly type: "AppOwner";
-}
+/** Creates a randomly generated {@link WriteKey}. */
+export const createWriteKey = (deps: CreateRandomBytesDep): WriteKey =>
+  deps.createRandomBytes(16) as unknown as WriteKey;
 
-/**
- * Used to shard data within an app for partial or deferred sync. Created in the
- * Evolu `initialData` function or dynamically as needed. Its mnemonic is stored
- * in an app table (encrypted by `AppOwner`) and synced between devices. Its
- * `writeKey` is deterministic and rotatable, enabling selective syncing of data
- * subsets. Not intended for sharing outside the app.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
- */
-export interface ShardOwner {
-  readonly type: "ShardOwner";
-  readonly mnemonic: Mnemonic;
-  readonly writeKey: WriteKey;
-}
+/** Creates an {@link Owner} from a {@link Mnemonic} using SLIP-21 key derivation. */
+export const createOwner = (mnemonic: Mnemonic): Owner => {
+  const seed = mnemonicToMnemonicSeed(mnemonic);
+  return createOwnerFromMnemonicSeed(seed);
+};
 
 /**
- * Used to share data among one or more users, enabling collaboration or
- * controlled access. Its `writeKey` is random (not derived from the mnemonic,
- * stored alongside it in the app table) and rotatable, ensuring it cannot be
- * regenerated by others if shared. Share the `mnemonic` alone for read-only
- * access (as `SharedReadonlyOwner`) or share SharedOwner itself for write
- * access.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * Creates an {@link Owner} from a {@link MnemonicSeed} using SLIP-21 key
+ * derivation.
  */
-export interface SharedOwner {
-  readonly type: "SharedOwner";
-  readonly mnemonic: Mnemonic;
-  readonly writeKey: WriteKey;
-}
+export const createOwnerFromMnemonicSeed = (seed: MnemonicSeed): Owner => ({
+  id: createSlip21Id(seed, ["Evolu", "Owner Id"]) as OwnerId,
+
+  encryptionKey: createSlip21(seed, [
+    "Evolu",
+    "Encryption Key",
+  ]) as EncryptionKey,
+
+  writeKey: createSlip21(seed, ["Evolu", "Write Key"]).slice(0, 16) as WriteKey,
+});
 
 /**
- * Used for sharing data that can only be read, such as with followers or peers
- * in a read-only sync scenario. It lacks a `writeKey`, containing only the
- * `mnemonic` from which `id` and `encryptionKey` are derived by Evolu.
- * Typically derived from a `SharedOwner` by sharing its `mnemonic` without the
- * `writeKey`.
+ * The owner representing app data. Can be created from a {@link Mnemonic} or
+ * from external keys when the mnemonic should not be shared with the Evolu
+ * app.
  */
-export interface SharedReadonlyOwner {
-  readonly type: "SharedReadonlyOwner";
-  readonly mnemonic: Mnemonic;
+export interface AppOwner extends Owner {
+  readonly type: "AppOwner";
+
+  /**
+   * The mnemonic that was used to derive the AppOwner keys. Optional when the
+   * AppOwner is created from external keys to avoid sharing the mnemonic with
+   * the Evolu app.
+   */
+  readonly mnemonic?: Mnemonic | null;
 }
 
+export const createAppOwner = (mnemonic: Mnemonic): AppOwner => ({
+  type: "AppOwner",
+  mnemonic,
+  ...createOwner(mnemonic),
+});
+
 /**
- * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
- * it on another device; otherwise, generates a new mnemonic.
+ * Owner for sharding app data. Allows partitioning of database changes for
+ * selective synchronization.
  */
-export const createAppOwner =
-  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) =>
-  (mnemonic = deps.createMnemonic()): AppOwner => {
-    const owner = createOwner(deps)(mnemonic);
-    return { type: "AppOwner", ...owner };
-  };
+export interface ShardOwner extends Owner {
+  readonly type: "ShardOwner";
+}
 
 /**
- * Creates a {@link ShardOwner} for sharding app data with a freshly generated
- * mnemonic. Unlike {@link createAppOwner}, it doesn’t accept an existing
- * mnemonic because ShardOwner mnemonics are always generated and restored
- * automatically via database sync.
+ * Creates a {@link ShardOwner} derived from an {@link AppOwner} using the
+ * specified path.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const contactsShard = createShardOwner(appOwner, ["contacts"]);
+ * const projectShard = createShardOwner(appOwner, [
+ *   "projects",
+ *   "project-1",
+ * ]);
+ * ```
  */
 export const createShardOwner = (
-  deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep,
+  appOwner: AppOwner,
+  path: NonEmptyReadonlyArray<string>,
 ): ShardOwner => {
-  const owner = createOwner(deps)();
+  /**
+   * The shardSeed is never shared or persisted, only used for SLIP-21
+   * derivation to create shard-specific keys.
+   */
+  const shardSeed = createSlip21(
+    appOwner.encryptionKey as unknown as MnemonicSeed,
+    path,
+  ) as MnemonicSeed;
+
   return {
     type: "ShardOwner",
-    mnemonic: owner.mnemonic,
-    writeKey: owner.writeKey,
+    ...createOwnerFromMnemonicSeed(shardSeed),
   };
 };
 
 /**
- * Creates a fresh {@link SharedOwner} for sharing data with write access. Takes
- * no arguments as both `mnemonic` and rotatable `writeKey` are newly generated;
- * when shared, recipients use the provided `mnemonic` and `writeKey` directly
- * as a {@link SharedOwner} without needing to recreate it.
+ * Owner for collaborative data with write access. Created by a user for their
+ * own use, not meant to be shared directly. To share data, use
+ * {@link createSharedReadonlyOwner} to create a {@link SharedReadonlyOwner} for
+ * read-only access.
  */
-export const createSharedOwner = (
-  deps: CreateRandomBytesDep & CreateMnemonicDep,
-): SharedOwner => {
+export interface SharedOwner extends Owner {
+  readonly type: "SharedOwner";
+  readonly mnemonic: Mnemonic;
+}
+
+/** Creates a {@link SharedOwner} with a freshly generated {@link Mnemonic}. */
+export const createSharedOwner = (deps: CreateMnemonicDep): SharedOwner => {
   const mnemonic = deps.createMnemonic();
-  const writeKey = createWriteKey(deps)(); // Random, no seed
   return {
     type: "SharedOwner",
     mnemonic,
-    writeKey,
+    ...createOwner(mnemonic),
   };
 };
 
 /**
- * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner} for read-only
- * data sharing. Extracts the `mnemonic` from the provided {@link SharedOwner},
- * omitting its `writeKey` to ensure read-only access.
+ * Read-only version of a {@link SharedOwner} for data sharing. Contains only the
+ * {@link OwnerId} and {@link EncryptionKey} needed for others to read the shared
+ * data without write access.
  */
+export interface SharedReadonlyOwner {
+  readonly type: "SharedReadonlyOwner";
+  readonly id: OwnerId;
+  readonly encryptionKey: EncryptionKey;
+}
+
+/** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
 export const createSharedReadonlyOwner = (
   sharedOwner: SharedOwner,
-): SharedReadonlyOwner => {
-  return {
-    type: "SharedReadonlyOwner",
-    mnemonic: sharedOwner.mnemonic,
-  };
-};
-
-/** Creates an {@link Owner} with optional `mnemonic` and `writeKey`. */
-export const createOwner =
-  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) =>
-  (mnemonic = deps.createMnemonic(), writeKey?: WriteKey): Owner => {
-    const seed = mnemonicToMnemonicSeed(mnemonic);
-
-    const id = createSlip21Id(seed, ["Evolu", "Owner Id"]) as OwnerId;
-    const encryptionKey = createEncryptionKey(seed);
-
-    const createdAt = DateIso.fromParent(new Date(deps.time.now()));
-    assert(createdAt.ok, "Invalid DateIso: bad system clock");
-
-    return {
-      mnemonic,
-      createdAt: createdAt.value,
-      id,
-      encryptionKey,
-      writeKey: writeKey ?? createWriteKey(deps)(seed),
-    };
-  };
-
-export const createWriteKey =
-  (deps: CreateRandomBytesDep) =>
-  (seed?: MnemonicSeed): WriteKey => {
-    const key = seed
-      ? createSlip21(seed, ["Evolu", "Write Key"]).slice(0, 16)
-      : deps.createRandomBytes(16);
-
-    const writeKey = WriteKey.from(key);
-    assert(writeKey.ok, "Ensure valid WriteKey");
-
-    return writeKey.value;
-  };
-
-/**
- * An `OwnerRow` represents a row in the `evolu_owner` table, based on an
- * {@link Owner} with an added `timestamp` ({@link TimestampString}) for CRDT
- * sync. It supports all {@link Owner} variants with an optional `writeKey`; use
- * {@link createOwnerRow} to align it with a specific {@link Owner}.
- */
-export type OwnerRow = Omit<Owner, "writeKey"> & {
-  readonly writeKey: WriteKey | null;
-  readonly timestamp: TimestampString;
-};
-
-/**
- * Creates an {@link OwnerRow} from any {@link Owner} variant for the
- * `evolu_owner` table, adding a `timestamp` ({@link TimestampString}) for CRDT
- * sync.
- */
-export const createOwnerRow =
-  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep & NanoIdLibDep) =>
-  (
-    owner: AppOwner | ShardOwner | SharedOwner | SharedReadonlyOwner,
-  ): OwnerRow => {
-    const timestamp = timestampToTimestampString(createInitialTimestamp(deps));
-    switch (owner.type) {
-      case "AppOwner": {
-        const { type, ...rest } = owner;
-        return { ...rest, timestamp };
-      }
-      case "ShardOwner":
-      case "SharedOwner":
-        return {
-          ...createOwner(deps)(owner.mnemonic, owner.writeKey),
-          timestamp,
-        };
-      case "SharedReadonlyOwner":
-        return {
-          ...createOwner(deps)(owner.mnemonic),
-          writeKey: null,
-          timestamp,
-        };
-    }
-  };
+): SharedReadonlyOwner => ({
+  type: "SharedReadonlyOwner",
+  id: sharedOwner.id,
+  encryptionKey: sharedOwner.encryptionKey,
+});
 
 /**
  * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or

package/src/Evolu/Protocol.ts

@@ -1,3 +1,4 @@
+/* eslint-disable jsdoc/no-undefined-types */
 /**
  * Evolu Protocol
  *
@@ -183,13 +184,7 @@ import {
   record,
 } from "../Type.js";
 import { Brand, Predicate } from "../Types.js";
-import {
-  Owner,
-  OwnerId,
-  OwnerWithWriteAccess,
-  WriteKey,
-  writeKeyLength,
-} from "./Owner.js";
+import { Owner, OwnerId, WriteKey, writeKeyLength } from "./Owner.js";
 import {
   BinaryTimestamp,
   binaryTimestampLength,
@@ -473,7 +468,7 @@ export interface ProtocolTimestampMismatchError {
 export const createProtocolMessageFromCrdtMessages =
   (deps: SymmetricCryptoDep & CreateRandomBytesDep) =>
   (
-    owner: OwnerWithWriteAccess,
+    owner: Owner,
     messages: NonEmptyReadonlyArray<CrdtMessage>,
     maxSize?: PositiveInt,
   ): ProtocolMessage => {

package/src/Evolu/Public.ts

@@ -5,12 +5,7 @@
  */
 
 export { createEvolu } from "./Evolu.js";
-export type {
-  Evolu,
-  EvoluConfigWithInitialData,
-  EvoluDeps,
-  EvoluError,
-} from "./Evolu.js";
+export type { Evolu, EvoluDeps, EvoluError } from "./Evolu.js";
 export * from "./Owner.js";
 export { binaryIdToId, idToBinaryId } from "./Protocol.js";
 export type { BinaryId } from "./Protocol.js";

package/src/Evolu/Schema.ts

@@ -30,11 +30,10 @@ import {
 import { Simplify } from "../Types.js";
 import { DbSchema } from "./Db.js";
 import { createIndexes, DbIndexesBuilder } from "./Kysely.js";
-import { AppOwner, ShardOwner, SharedOwner } from "./Owner.js";
 import {
   BinaryId,
-  maxProtocolMessageRangesSize,
   CrdtMessage,
+  maxProtocolMessageRangesSize,
 } from "./Protocol.js";
 import { Query, Row } from "./Query.js";
 import { BinaryTimestamp } from "./Timestamp.js";
@@ -252,13 +251,6 @@ export interface MutationOptions {
    * `onlyValidate: true`.
    */
   readonly onlyValidate?: boolean;
-
-  /**
-   * The owner to use for this mutation. Can be a {@link ShardOwner} for sharding
-   * app data or a {@link SharedOwner} for collaborative write access. If
-   * omitted, defaults to the app's {@link AppOwner}.
-   */
-  readonly owner?: ShardOwner | SharedOwner;
 }
 
 /**

package/src/Result.ts

@@ -1,3 +1,4 @@
+/* eslint-disable jsdoc/no-undefined-types */
 /**
  * 🛡️ Type-safe errors
  *

package/src/Type.ts

@@ -1,3 +1,4 @@
+/* eslint-disable jsdoc/no-undefined-types */
 /**
  * 🧩 Validation, Parsing, and Transformation
  *