@evolu/common 1.0.17 → 2.0.0

package/src/Model.ts

@@ -1,89 +1,70 @@
-import * as Schema from "@effect/schema/Schema";
+import * as S from "@effect/schema/Schema";
 import { Brand } from "effect";
 import { maybeJson } from "./Sqlite.js";
 
 /**
- * Branded Id Schema for any table Id.
- * To create Id Schema for a specific table, use {@link id}.
+ * Branded Id Schema for any table Id. To create Id Schema for a specific table,
+ * use {@link id}.
  */
-export const Id = Schema.string.pipe(
-  Schema.pattern(/^[\w-]{21}$/),
-  Schema.brand("Id"),
-);
-export type Id = Schema.Schema.To<typeof Id>;
+export const Id = S.string.pipe(S.pattern(/^[\w-]{21}$/), S.brand("Id"));
+export type Id = S.Schema.To<typeof Id>;
 
 /**
  * A factory function to create {@link Id} Schema for a specific table.
  *
  * ### Example
  *
- * ```
- * import * as Schema from "@effect/schema/Schema";
+ * ```ts
+ * import * as S from "@effect/schema/Schema";
  * import * as Evolu from "@evolu/react";
  *
  * const TodoId = Evolu.id("Todo");
- * type TodoId = Schema.Schema.To<typeof TodoId>;
- *
- * if (!Schema.is(TodoId)(value)) return;
+ * type TodoId = S.Schema.To<typeof TodoId>;
  * ```
  */
 export const id = <T extends string>(
   table: T,
-): Schema.BrandSchema<string, string & Brand.Brand<"Id"> & Brand.Brand<T>> =>
-  Id.pipe(Schema.brand(table));
+): S.BrandSchema<string, string & Brand.Brand<"Id"> & Brand.Brand<T>> =>
+  Id.pipe(S.brand(table));
 
 /**
- * SQLite doesn't support the Date type, so Evolu uses SqliteDate instead.
- * Use the {@link cast} helper to cast SqliteDate from Date and back.
+ * SQLite doesn't support the Date type, so Evolu uses SqliteDate instead. Use
+ * the {@link cast} helper to cast SqliteDate from Date and back.
  * https://www.sqlite.org/quirks.html#no_separate_datetime_datatype
  */
-export const SqliteDate = Schema.string.pipe(
-  Schema.filter((s) => !isNaN(Date.parse(s))),
-  Schema.brand("SqliteDate"),
+export const SqliteDate = S.string.pipe(
+  S.filter((s) => !isNaN(Date.parse(s))),
+  S.brand("SqliteDate"),
 );
-export type SqliteDate = Schema.Schema.To<typeof SqliteDate>;
+export type SqliteDate = S.Schema.To<typeof SqliteDate>;
 
 /**
  * SQLite doesn't support the boolean type, so Evolu uses SqliteBoolean instead.
  * Use the {@link cast} helper to cast SqliteBoolean from boolean and back.
  * https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
  */
-export const SqliteBoolean = Schema.number.pipe(
-  Schema.int(),
-  Schema.filter((s) => s === 0 || s === 1),
-  Schema.brand("SqliteBoolean"),
+export const SqliteBoolean = S.number.pipe(
+  S.int(),
+  S.filter((s) => s === 0 || s === 1),
+  S.brand("SqliteBoolean"),
 );
-export type SqliteBoolean = Schema.Schema.To<typeof SqliteBoolean>;
-
-/**
- * SQLite doesn't support Date nor Boolean types, so Evolu emulates them
- * with {@link SqliteBoolean} and {@link SqliteDate}.
- *
- * For {@link SqliteBoolean}, you can use JavaScript boolean.
- * For {@link SqliteDate}, you can use JavaScript Date.
- */
-export type CastableForMutate<T> = {
-  readonly [K in keyof T]: T[K] extends SqliteBoolean
-    ? boolean | SqliteBoolean
-    : T[K] extends null | SqliteBoolean
-    ? null | boolean | SqliteBoolean
-    : T[K] extends SqliteDate
-    ? Date | SqliteDate
-    : T[K] extends null | SqliteDate
-    ? null | Date | SqliteDate
-    : T[K];
-};
+export type SqliteBoolean = S.Schema.To<typeof SqliteBoolean>;
 
 /**
- * A helper for casting types not supported by SQLite.
- * SQLite doesn't support Date nor Boolean types, so Evolu emulates them
- * with {@link SqliteBoolean} and {@link SqliteDate}.
+ * A helper for casting types not supported by SQLite. SQLite doesn't support
+ * Date nor Boolean types, so Evolu emulates them with {@link SqliteBoolean} and
+ * {@link SqliteDate}.
  *
  * ### Example
  *
- * ```
- * // isDeleted is SqliteBoolean
- * .where("isDeleted", "is not", cast(true))
+ * ```ts
+ * const allTodosNotDeleted = evolu.createQuery((db) =>
+ *   db
+ *     .selectFrom("todo")
+ *     .selectAll()
+ *     // isDeleted is SqliteBoolean
+ *     .where("isDeleted", "is not", Evolu.cast(true)),
+ * );
  * ```
  */
 export function cast(value: boolean): SqliteBoolean;
@@ -101,13 +82,13 @@ export function cast(
 }
 
 /**
- * String schema represents a string that is not stringified JSON. Using
- * String schema for strings stored in SQLite is crucial to ensure a stored
- * string is not automatically parsed to a JSON object or array when
- * retrieved. Use String schema for all string-based schemas.
+ * String schema represents a string that is not stringified JSON. Using String
+ * schema for strings stored in SQLite is crucial to ensure a stored string is
+ * not automatically parsed to a JSON object or array when retrieved. Use String
+ * schema for all string-based schemas.
  */
-export const String = Schema.string.pipe(
-  Schema.filter(
+export const String = S.string.pipe(
+  S.filter(
     (s) => {
       if (!maybeJson(s)) return true;
       try {
@@ -119,65 +100,59 @@ export const String = Schema.string.pipe(
     },
     { message: () => "a string that is not stringified JSON" },
   ),
-  Schema.brand("String"),
+  S.brand("String"),
 );
-export type String = Schema.Schema.To<typeof String>;
+export type String = S.Schema.To<typeof String>;
 
 /**
  * A string with a maximum length of 1000 characters.
  *
  * ### Example
  *
- * ```
- * import * as Schema from "@effect/schema/Schema";
+ * ```ts
+ * import * as S from "@effect/schema/Schema";
  * import * as Evolu from "@evolu/react";
  *
- * if (!Schema.is(Evolu.String1000)(value)) return;
- * function foo(value: Evolu.String1000) {}
+ * S.parse(Evolu.String1000)(value);
  * ```
  */
-export const String1000 = String.pipe(
-  Schema.maxLength(1000),
-  Schema.brand("String1000"),
-);
-export type String1000 = Schema.Schema.To<typeof String1000>;
+export const String1000 = String.pipe(S.maxLength(1000), S.brand("String1000"));
+export type String1000 = S.Schema.To<typeof String1000>;
 
 /**
  * A nonempty string with a maximum length of 1000 characters.
  *
  * ### Example
  *
- * ```
- * import * as Schema from "@effect/schema/Schema";
+ * ```ts
+ * import * as S from "@effect/schema/Schema";
  * import * as Evolu from "@evolu/react";
  *
- * if (!Schema.is(Evolu.NonEmptyString1000)(value)) return;
- * function foo(value: Evolu.NonEmptyString1000) {}
+ * S.parse(Evolu.NonEmptyString1000)(value);
  * ```
  */
 export const NonEmptyString1000 = String.pipe(
-  Schema.minLength(1),
-  Schema.maxLength(1000),
-  Schema.brand("NonEmptyString1000"),
+  S.minLength(1),
+  S.maxLength(1000),
+  S.brand("NonEmptyString1000"),
 );
-export type NonEmptyString1000 = Schema.Schema.To<typeof NonEmptyString1000>;
+export type NonEmptyString1000 = S.Schema.To<typeof NonEmptyString1000>;
 
 /**
  * A positive integer.
  *
  * ### Example
  *
- * ```
- * import * as Schema from "@effect/schema/Schema";
+ * ```ts
+ * import * as S from "@effect/schema/Schema";
  * import * as Evolu from "@evolu/react";
  *
- * if (!Schema.is(Evolu.PositiveInt)(value)) return;
- * function foo(value: Evolu.PositiveInt) {}
+ * S.parse(Evolu.PositiveInt)(value);
  * ```
  */
-export const PositiveInt = Schema.number.pipe(
-  Schema.int(),
-  Schema.positive(),
-  Schema.brand("PositiveInt"),
+export const PositiveInt = S.number.pipe(
+  S.int(),
+  S.positive(),
+  S.brand("PositiveInt"),
 );
-export type PositiveInt = Schema.Schema.To<typeof PositiveInt>;
+export type PositiveInt = S.Schema.To<typeof PositiveInt>;

package/src/OnCompletes.ts

@@ -0,0 +1,46 @@
+import { Brand, Context, Effect, Layer, Option, ReadonlyArray } from "effect";
+import { NanoId } from "./Crypto.js";
+
+export interface OnCompletes {
+  readonly add: (
+    onComplete: OnComplete,
+  ) => Effect.Effect<never, never, OnCompleteId>;
+
+  readonly complete: (
+    onCompleteIds: readonly OnCompleteId[],
+  ) => Effect.Effect<never, never, void>;
+}
+
+export type OnComplete = () => void;
+
+export type OnCompleteId = string & Brand.Brand<"OnCompleteId">;
+
+export const OnCompletes = Context.Tag<OnCompletes>();
+
+export const OnCompletesLive = Layer.effect(
+  OnCompletes,
+  Effect.gen(function* (_) {
+    const nanoid = yield* _(NanoId);
+    const map = new Map<OnCompleteId, OnComplete>();
+
+    return OnCompletes.of({
+      add: (onComplete) =>
+        nanoid.nanoid.pipe(
+          Effect.map((nanoid) => {
+            const id = nanoid as OnCompleteId;
+            map.set(id, onComplete);
+            return id;
+          }),
+        ),
+
+      complete: (onCompleteIds) =>
+        Effect.sync(() => {
+          ReadonlyArray.filterMap(onCompleteIds, (id) => {
+            const onComplete = map.get(id);
+            map.delete(id);
+            return Option.fromNullable(onComplete);
+          }).forEach((onComplete) => onComplete());
+        }),
+    });
+  }),
+);

package/src/Owner.ts

@@ -0,0 +1,65 @@
+import { Brand, Context, Effect } from "effect";
+import { urlAlphabet } from "nanoid";
+import { Bip39, Mnemonic, slip21Derive } from "./Crypto.js";
+import { Id } from "./Model.js";
+
+/**
+ * The Owner represents the Evolu database owner, a user. Instead of traditional
+ * email with a password, the Owner uses a mnemonic, also known as a "seed
+ * phrase," which is a set of 12 words in a specific order chosen from a
+ * predefined list.
+ *
+ * The purpose of the BIP39 mnemonic is to provide a human-readable way of
+ * storing a private key.
+ *
+ * Mnemonic is generated safely in the user's device and must not be shared with
+ * anyone.
+ */
+export interface Owner {
+  /** The {@link Mnemonic} associated with {@link Owner}. */
+  readonly mnemonic: Mnemonic;
+
+  /** The unique identifier safely derived from {@link Mnemonic}. */
+  readonly id: OwnerId;
+
+  /** The encryption key safely derived from {@link Mnemonic}. */
+  readonly encryptionKey: Uint8Array;
+}
+
+export const Owner = Context.Tag<Owner>();
+
+/**
+ * The unique identifier of {@link Owner} safely derived from its
+ * {@link Mnemonic}.
+ */
+export type OwnerId = Id & Brand.Brand<"Owner">;
+
+export const makeOwner = (
+  mnemonic?: Mnemonic,
+): Effect.Effect<Bip39, never, Owner> =>
+  Effect.gen(function* (_) {
+    const bip39 = yield* _(Bip39);
+
+    if (mnemonic == null) mnemonic = yield* _(bip39.make);
+
+    const seed = yield* _(bip39.toSeed(mnemonic));
+
+    const id = yield* _(
+      slip21Derive(seed, ["Evolu", "Owner Id"]).pipe(
+        Effect.map((key) => {
+          // convert key to nanoid
+          let id = "";
+          for (let i = 0; i < 21; i++) {
+            id += urlAlphabet[key[i] & 63];
+          }
+          return id as OwnerId;
+        }),
+      ),
+    );
+
+    const encryptionKey = yield* _(
+      slip21Derive(seed, ["Evolu", "Encryption Key"]),
+    );
+
+    return { mnemonic, id, encryptionKey };
+  });

package/src/Platform.ts

@@ -1,36 +1,40 @@
 import { Context, Effect, Layer } from "effect";
 
-export interface Platform {
-  readonly name:
-    | "server"
-    | "web-with-opfs"
-    | "web-without-opfs"
-    | "react-native";
-}
+export type PlatformName =
+  | "server"
+  | "web-with-opfs"
+  | "web-without-opfs"
+  | "react-native";
 
-export const Platform = Context.Tag<Platform>("evolu/Platform");
+export const PlatformName = Context.Tag<PlatformName>();
 
 export type FlushSync = (callback: () => void) => void;
 
-export const FlushSync = Context.Tag<FlushSync>("evolu/FlushSync");
+export const FlushSync = Context.Tag<FlushSync>();
 
 export interface SyncLock {
+  /**
+   * Try to acquire a sync lock. The caller must not call sync if a sync lock
+   * can't be acquired.
+   */
   readonly acquire: Effect.Effect<never, never, boolean>;
+
+  /** Release a sync lock. */
   readonly release: Effect.Effect<never, never, void>;
 }
 
-export const SyncLock = Context.Tag<SyncLock>("evolu/SyncLock");
+export const SyncLock = Context.Tag<SyncLock>();
 
 export type Fetch = (
   url: string,
   body: Uint8Array,
 ) => Effect.Effect<never, FetchError, Response>;
 
-export const Fetch = Context.Tag<Fetch>("evolu/Fetch");
+export const Fetch = Context.Tag<Fetch>();
 
 /**
- * This error occurs when there is a problem with the network connection,
- * or the server cannot be reached.
+ * This error occurs when there is a problem with the network connection, or the
+ * server cannot be reached.
  */
 export interface FetchError {
   readonly _tag: "FetchError";
@@ -54,13 +58,17 @@ export const FetchLive = Layer.succeed(
   ),
 );
 
+interface AppStateConfig {
+  readonly onFocus: () => void;
+  readonly onReconnect: () => void;
+}
+
 export interface AppState {
-  readonly onFocus: (callback: () => void) => void;
-  readonly onReconnect: (callback: () => void) => void;
+  readonly init: (config: AppStateConfig) => void;
   readonly reset: Effect.Effect<never, never, void>;
 }
 
-export const AppState = Context.Tag<AppState>("evolu/AppState");
+export const AppState = Context.Tag<AppState>();
 
 /**
  * To detect whether DOM can be used.

package/src/Protobuf.ts

@@ -5,101 +5,61 @@
 import { MessageType } from "@protobuf-ts/runtime";
 import { MerkleTreeString, TimestampString } from "./Crdt.js";
 import { NodeId } from "./Crypto.js";
-import { OwnerId } from "./Db.js";
+import { OwnerId } from "./Owner.js";
 import { Id } from "./Model.js";
-/**
- * @generated from protobuf message SyncRequest
- */
+/** @generated from protobuf message SyncRequest */
 export interface SyncRequest {
-  /**
-   * @generated from protobuf field: repeated EncryptedMessage messages = 1;
-   */
+  /** @generated from protobuf field: repeated EncryptedMessage messages = 1; */
   messages: ReadonlyArray<EncryptedMessage>;
-  /**
-   * @generated from protobuf field: string userId = 2;
-   */
+  /** @generated from protobuf field: string userId = 2; */
   userId: OwnerId;
-  /**
-   * @generated from protobuf field: string nodeId = 3;
-   */
+  /** @generated from protobuf field: string nodeId = 3; */
   nodeId: NodeId;
-  /**
-   * @generated from protobuf field: string merkleTree = 4;
-   */
+  /** @generated from protobuf field: string merkleTree = 4; */
   merkleTree: MerkleTreeString;
 }
-/**
- * @generated from protobuf message SyncResponse
- */
+/** @generated from protobuf message SyncResponse */
 export interface SyncResponse {
-  /**
-   * @generated from protobuf field: repeated EncryptedMessage messages = 1;
-   */
+  /** @generated from protobuf field: repeated EncryptedMessage messages = 1; */
   messages: ReadonlyArray<EncryptedMessage>;
-  /**
-   * @generated from protobuf field: string merkleTree = 2;
-   */
+  /** @generated from protobuf field: string merkleTree = 2; */
   merkleTree: MerkleTreeString;
 }
-/**
- * @generated from protobuf message EncryptedMessage
- */
+/** @generated from protobuf message EncryptedMessage */
 export interface EncryptedMessage {
-  /**
-   * @generated from protobuf field: string timestamp = 1;
-   */
+  /** @generated from protobuf field: string timestamp = 1; */
   timestamp: TimestampString;
-  /**
-   * @generated from protobuf field: bytes content = 2;
-   */
+  /** @generated from protobuf field: bytes content = 2; */
   content: Uint8Array;
 }
-/**
- * @generated from protobuf message MessageContent
- */
+/** @generated from protobuf message MessageContent */
 export interface MessageContent {
-  /**
-   * @generated from protobuf field: string table = 1;
-   */
+  /** @generated from protobuf field: string table = 1; */
   table: string;
-  /**
-   * @generated from protobuf field: string row = 2;
-   */
+  /** @generated from protobuf field: string row = 2; */
   row: Id;
-  /**
-   * @generated from protobuf field: string column = 3;
-   */
+  /** @generated from protobuf field: string column = 3; */
   column: string;
-  /**
-   * @generated from protobuf oneof: value
-   */
+  /** @generated from protobuf oneof: value */
   value:
     | {
         oneofKind: "stringValue";
-        /**
-         * @generated from protobuf field: string stringValue = 4;
-         */
+        /** @generated from protobuf field: string stringValue = 4; */
         stringValue: string;
       }
     | {
         oneofKind: "numberValue";
-        /**
-         * @generated from protobuf field: int32 numberValue = 5;
-         */
+        /** @generated from protobuf field: int32 numberValue = 5; */
         numberValue: number;
       }
     | {
         oneofKind: "bytesValue";
-        /**
-         * @generated from protobuf field: bytes bytesValue = 6;
-         */
+        /** @generated from protobuf field: bytes bytesValue = 6; */
         bytesValue: Uint8Array;
       }
     | {
         oneofKind: "jsonValue";
-        /**
-         * @generated from protobuf field: string jsonValue = 7;
-         */
+        /** @generated from protobuf field: string jsonValue = 7; */
         jsonValue: string;
       }
     | {
@@ -123,9 +83,7 @@ class SyncRequest$Type extends MessageType<SyncRequest> {
     ]);
   }
 }
-/**
- * @generated MessageType for protobuf message SyncRequest
- */
+/** @generated MessageType for protobuf message SyncRequest */
 export const SyncRequest = new SyncRequest$Type();
 // @generated message type with reflection information, may provide speed optimized methods
 class SyncResponse$Type extends MessageType<SyncResponse> {
@@ -142,9 +100,7 @@ class SyncResponse$Type extends MessageType<SyncResponse> {
     ]);
   }
 }
-/**
- * @generated MessageType for protobuf message SyncResponse
- */
+/** @generated MessageType for protobuf message SyncResponse */
 export const SyncResponse = new SyncResponse$Type();
 // @generated message type with reflection information, may provide speed optimized methods
 class EncryptedMessage$Type extends MessageType<EncryptedMessage> {
@@ -155,9 +111,7 @@ class EncryptedMessage$Type extends MessageType<EncryptedMessage> {
     ]);
   }
 }
-/**
- * @generated MessageType for protobuf message EncryptedMessage
- */
+/** @generated MessageType for protobuf message EncryptedMessage */
 export const EncryptedMessage = new EncryptedMessage$Type();
 // @generated message type with reflection information, may provide speed optimized methods
 class MessageContent$Type extends MessageType<MessageContent> {
@@ -197,7 +151,5 @@ class MessageContent$Type extends MessageType<MessageContent> {
     ]);
   }
 }
-/**
- * @generated MessageType for protobuf message MessageContent
- */
+/** @generated MessageType for protobuf message MessageContent */
 export const MessageContent = new MessageContent$Type();

package/src/Public.ts

@@ -1,6 +1,8 @@
 export { jsonArrayFrom, jsonObjectFrom } from "kysely/helpers/sqlite";
-export type { Mnemonic } from "./Crypto.js";
-export type { Owner, OwnerId } from "./Db.js";
-export type { EvoluError } from "./Errors.js";
+export type { Timestamp, TimestampError } from "./Crdt.js";
+export type { Mnemonic, InvalidMnemonicError } from "./Crypto.js";
+export type { EvoluError, UnexpectedError } from "./ErrorStore.js";
 export * from "./Model.js";
+export type { Owner, OwnerId } from "./Owner.js";
+export { canUseDom } from "./Platform.js";
 export type { SyncState } from "./SyncWorker.js";

package/src/Sqlite.ts

@@ -1,45 +1,37 @@
-import { Brand, Context, Effect, Predicate, ReadonlyRecord } from "effect";
+import { Context, Effect, Predicate, ReadonlyRecord } from "effect";
 
 export interface Sqlite {
   readonly exec: (
-    arg: string | QueryObject,
+    arg: string | SqliteQuery,
   ) => Effect.Effect<never, never, ExecResult>;
 }
 
-export const Sqlite = Context.Tag<Sqlite>("evolu/Sqlite");
+export const Sqlite = Context.Tag<Sqlite>();
 
-export interface QueryObject {
+export interface SqliteQuery {
   readonly sql: string;
-  readonly parameters: ReadonlyArray<Value>;
+  readonly parameters: Value[];
 }
 
 export type Value = SqliteValue | JsonObjectOrArray;
-
 export type SqliteValue = null | string | number | Uint8Array;
-export type SqliteRow = Record<string, SqliteValue>;
-
 export type JsonObjectOrArray = JsonObject | JsonArray;
-
 type JsonObject = ReadonlyRecord.ReadonlyRecord<Json>;
 type JsonArray = ReadonlyArray<Json>;
 type Json = string | number | boolean | null | JsonObject | JsonArray;
 
 interface ExecResult {
-  readonly rows: ReadonlyArray<Row>;
+  readonly rows: SqliteRow[];
   readonly changes: number;
 }
 
-export type Row = ReadonlyRecord.ReadonlyRecord<
-  Value | Row | ReadonlyArray<Row>
->;
-
-export type Query = string & Brand.Brand<"Query">;
+export type SqliteRow = Record<string, SqliteValue>;
 
 export const isJsonObjectOrArray: Predicate.Refinement<
   Value,
   JsonObjectOrArray
 > = (value): value is JsonObjectOrArray =>
-  value !== null && typeof value === "object" && !(value instanceof Uint8Array);
+  value !== null && typeof value === "object" && !Predicate.isUint8Array(value);
 
 export const valuesToSqliteValues = (
   values: ReadonlyArray<Value>,
@@ -48,15 +40,13 @@ export const valuesToSqliteValues = (
     isJsonObjectOrArray(value) ? JSON.stringify(value) : value,
   );
 
-export const queryObjectToQuery = ({ sql, parameters }: QueryObject): Query =>
-  JSON.stringify({ sql, parameters }) as Query;
-
-export const queryObjectFromQuery = (s: Query): QueryObject =>
-  JSON.parse(s) as QueryObject;
+export const ensureSqliteQuery = (arg: string | SqliteQuery): SqliteQuery => {
+  if (typeof arg !== "string") return arg;
+  return { sql: arg, parameters: [] };
+};
 
-export const parseJsonResults = (rows: SqliteRow[]): void => {
+export const maybeParseJson = (rows: SqliteRow[]): SqliteRow[] =>
   parseArray(rows);
-};
 
 const parseArray = <T>(a: T[]): T[] => {
   for (let i = 0; i < a.length; ++i) a[i] = parse(a[i]) as T;
@@ -67,7 +57,6 @@ const parse = (o: unknown): unknown => {
   if (Predicate.isString(o)) return parseString(o);
   // eslint-disable-next-line @typescript-eslint/no-unsafe-return
   if (Array.isArray(o)) return parseArray(o);
-  // Predicate.isReadonlyRecord
   if (typeof o === "object" && o !== null && !Predicate.isUint8Array(o))
     return parseObject(o as Record<string, unknown>);
   return o;