@evolu/common 5.4.8 → 6.0.0

package/src/Evolu/Internal.ts

@@ -0,0 +1,26 @@
+/**
+ * 🛠️
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { Evolu } from "@evolu/common/evolu";
+ * ```
+ *
+ * @module
+ */
+
+export * from "./Config.js";
+export * from "./Db.js";
+export * from "./Diff.js";
+export * from "./Evolu.js";
+export * from "./Kysely.js";
+export * from "./Owner.js";
+export * from "./Platform.js";
+export * from "./Protocol.js";
+export * from "./Query.js";
+export * from "./Relay.js";
+export * from "./Schema.js";
+export * from "./Storage.js";
+export * from "./Sync.js";
+export * from "./Timestamp.js";

package/src/Evolu/Kysely.ts

@@ -0,0 +1,38 @@
+import {
+  CreateIndexBuilder,
+  DummyDriver,
+  Kysely,
+  SqliteAdapter,
+  SqliteQueryCompiler,
+} from "kysely";
+import { DbIndex } from "./Db.js";
+
+// https://kysely.dev/docs/recipes/splitting-query-building-and-execution
+export const kysely = new Kysely({
+  dialect: {
+    createAdapter: () => new SqliteAdapter(),
+    createDriver: () => new DummyDriver(),
+    createIntrospector() {
+      throw new Error("Not implemeneted");
+    },
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+  },
+});
+
+export type DbIndexesBuilder = (
+  create: (indexName: string) => CreateIndexBuilder,
+) => ReadonlyArray<CreateIndexBuilder<any>>;
+
+const createIndex = kysely.schema.createIndex.bind(kysely.schema);
+
+export const createIndexes = (
+  indexes?: DbIndexesBuilder,
+): ReadonlyArray<DbIndex> => {
+  if (!indexes) return [];
+  return indexes(createIndex).map(
+    (index): DbIndex => ({
+      name: index.toOperationNode().name.name,
+      sql: index.compile().sql,
+    }),
+  );
+};

package/src/Evolu/Owner.ts

@@ -0,0 +1,296 @@
+import { assert } from "../Assert.js";
+import {
+  createEncryptionKey,
+  CreateMnemonicDep,
+  CreateRandomBytesDep,
+  createSlip21,
+  createSlip21Id,
+  EncryptionKey,
+  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.
+ *
+ * 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 data 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.
+ */
+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;
+}
+
+/**
+ * The unique identifier of {@link Owner} derived from the {@link Mnemonic}.
+ *
+ * This branded {@link Id} type, generated by {@link createSlip21Id}, is a
+ * 21-character {@link Base64Url} string (126 bits of entropy), providing a
+ * compact, shareable, and secure identifier for UI use, tied to the owner's
+ * mnemonic and derivation path.
+ */
+export const OwnerId = brand("OwnerId", Id);
+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.
+ */
+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";
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ */
+export interface SharedOwner {
+  readonly type: "SharedOwner";
+  readonly mnemonic: Mnemonic;
+  readonly writeKey: 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`.
+ */
+export interface SharedReadonlyOwner {
+  readonly type: "SharedReadonlyOwner";
+  readonly mnemonic: Mnemonic;
+}
+
+/**
+ * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
+ * it on another device; otherwise, generates a new mnemonic.
+ */
+export const createAppOwner =
+  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) =>
+  (mnemonic = deps.createMnemonic()): AppOwner => {
+    const owner = createOwner(deps)(mnemonic);
+    return { type: "AppOwner", ...owner };
+  };
+
+/**
+ * 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.
+ */
+export const createShardOwner = (
+  deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep,
+): ShardOwner => {
+  const owner = createOwner(deps)();
+  return {
+    type: "ShardOwner",
+    mnemonic: owner.mnemonic,
+    writeKey: owner.writeKey,
+  };
+};
+
+/**
+ * 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.
+ */
+export const createSharedOwner = (
+  deps: CreateRandomBytesDep & CreateMnemonicDep,
+): SharedOwner => {
+  const mnemonic = deps.createMnemonic();
+  const writeKey = createWriteKey(deps)(); // Random, no seed
+  return {
+    type: "SharedOwner",
+    mnemonic,
+    writeKey,
+  };
+};
+
+/**
+ * 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.
+ */
+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,
+        };
+    }
+  };
+
+/**
+ * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
+ * {@link SharedOwner}, returning a new instance with the updated key.
+ */
+export const rotateWriteKey = <T extends AppOwner | ShardOwner | SharedOwner>(
+  owner: T,
+  newWriteKey: WriteKey,
+): T => {
+  return {
+    ...owner,
+    writeKey: newWriteKey,
+  } as T;
+};

package/src/Evolu/Platform.ts

@@ -0,0 +1,27 @@
+import { Config } from "./Config.js";
+
+/**
+ * FlushSync is for libraries like React to flush updates synchronously inside
+ * the provided callback to ensure the DOM is updated immediately.
+ *
+ * For example, with React, when we want to focus on an element rendered as a
+ * result of a mutation, Evolu ensures all DOM changes are flushed synchronously
+ * if an onComplete callback is used.
+ *
+ * https://react.dev/reference/react-dom/flushSync
+ */
+export type FlushSync = (callback: () => void) => void;
+
+export interface FlushSyncDep {
+  readonly flushSync: FlushSync;
+}
+
+export interface AppState {
+  readonly reset: () => void;
+}
+
+export type CreateAppState = (config: Config) => AppState;
+
+export interface CreateAppStateDep {
+  readonly createAppState: CreateAppState;
+}