@evolu/common 4.0.4 → 4.1.0

package/src/Evolu.ts

@@ -32,7 +32,12 @@ import { SqliteBoolean, SqliteDate } from "./Model.js";
 import { OnCompletes, OnCompletesLive } from "./OnCompletes.js";
 import { Owner } from "./Owner.js";
 import { AppState, FlushSync } from "./Platform.js";
-import { SqliteQuery, isSqlMutation } from "./Sqlite.js";
+import {
+  Index,
+  SqliteQuery,
+  SqliteQueryOptions,
+  isSqlMutation,
+} from "./Sqlite.js";
 import { Store, Unsubscribe, makeStore } from "./Store.js";
 import { SyncState } from "./SyncWorker.js";
 
@@ -297,6 +302,7 @@ export interface Evolu<S extends DatabaseSchema = DatabaseSchema> {
    */
   readonly ensureSchema: <From, To extends S>(
     schema: S.Schema<To, From>,
+    indexes?: ReadonlyArray<Index>,
   ) => void;
 
   /**
@@ -313,6 +319,7 @@ export const Evolu = Context.GenericTag<Evolu>("@services/Evolu");
 
 type CreateQuery<S extends DatabaseSchema> = <R extends Row>(
   queryCallback: QueryCallback<S, R>,
+  options?: SqliteQueryOptions,
 ) => Query<R>;
 
 type QueryCallback<S extends DatabaseSchema, R extends Row> = (
@@ -334,6 +341,7 @@ type NullableExceptForIdAndAutomaticColumns<T> = {
     : T[K] | null;
 };
 
+// https://kysely.dev/docs/recipes/splitting-query-building-and-execution
 const kysely = new Kysely.Kysely<QuerySchema<DatabaseSchema>>({
   dialect: {
     createAdapter: (): Kysely.DialectAdapter => new Kysely.SqliteAdapter(),
@@ -346,18 +354,29 @@ const kysely = new Kysely.Kysely<QuerySchema<DatabaseSchema>>({
   },
 });
 
+export const createIndex = kysely.schema.createIndex.bind(kysely.schema);
+
 export const makeCreateQuery =
   <S extends DatabaseSchema = DatabaseSchema>(): CreateQuery<S> =>
-  <R extends Row>(queryCallback: QueryCallback<S, R>) =>
+  <R extends Row>(
+    queryCallback: QueryCallback<S, R>,
+    options?: SqliteQueryOptions,
+  ) =>
     pipe(
       queryCallback(kysely as Kysely.Kysely<QuerySchema<S>>).compile(),
-      ({ sql, parameters }): SqliteQuery => {
-        if (isSqlMutation(sql))
+      (compiledQuery): SqliteQuery => {
+        if (isSqlMutation(compiledQuery.sql))
           throw new Error(
             "SQL mutation (INSERT, UPDATE, DELETE, etc.) isn't allowed in the Evolu `createQuery` function. Kysely suggests it because there is no read-only Kysely yet, and removing such an API is not possible. For mutations, use Evolu mutation API.",
           );
-
-        return { sql, parameters: parameters as SqliteQuery["parameters"] };
+        const parameters = compiledQuery.parameters as NonNullable<
+          SqliteQuery["parameters"]
+        >;
+        return {
+          sql: compiledQuery.sql,
+          parameters,
+          ...(options && { options }),
+        };
       },
       (query) => serializeQuery<R>(query),
     );
@@ -739,7 +758,6 @@ const EvoluCommon = Layer.effect(
     };
 
     appState.init({ onRequestSync: sync });
-
     sync();
 
     return Evolu.of({
@@ -770,10 +788,11 @@ const EvoluCommon = Layer.effect(
       restoreOwner: (mnemonic) =>
         dbWorker.postMessage({ _tag: "reset", mnemonic }),
 
-      ensureSchema: (schema) =>
+      ensureSchema: (schema, indexes = []) =>
         dbWorker.postMessage({
           _tag: "ensureSchema",
           tables: schemaToTables(schema),
+          indexes,
         }),
 
       sync,
@@ -815,6 +834,14 @@ export const makeCreateEvolu =
         Effect.runSync,
       ),
     );
-    evolu.ensureSchema(schema);
+
+    const indexes = config?.indexes?.map(
+      (index): Index => ({
+        name: index.toOperationNode().name.name,
+        sql: index.compile().sql,
+      }),
+    );
+
+    evolu.ensureSchema(schema, indexes);
     return evolu as Evolu<To>;
   };

package/src/Model.ts

@@ -1,13 +1,9 @@
 import * as S from "@effect/schema/Schema";
-import * as Brand from "effect/Brand";
 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. To create Id Schema for a specific table, use {@link id}. */
 export const Id = S.string.pipe(S.pattern(/^[\w-]{21}$/), S.brand("Id"));
-export type Id = S.Schema.To<typeof Id>;
+export type Id = S.Schema.Type<typeof Id>;
 
 /**
  * A factory function to create {@link Id} Schema for a specific table.
@@ -17,11 +13,11 @@ export type Id = S.Schema.To<typeof Id>;
  *   import { id } from "@evolu/react";
  *
  *   const TodoId = id("Todo");
- *   type TodoId = S.Schema.To<typeof TodoId>;
+ *   type TodoId = S.Schema.Type<typeof TodoId>;
  */
 export const id = <T extends string>(
   table: T,
-): S.BrandSchema<string & Brand.Brand<"Id"> & Brand.Brand<T>, string, never> =>
+): S.brand<S.brand<S.Schema<string, string, never>, "Id">, T> =>
   Id.pipe(S.brand(table));
 
 /**
@@ -33,7 +29,7 @@ export const SqliteDate = S.string.pipe(
   S.filter((s) => !isNaN(Date.parse(s))),
   S.brand("SqliteDate"),
 );
-export type SqliteDate = S.Schema.To<typeof SqliteDate>;
+export type SqliteDate = S.Schema.Type<typeof SqliteDate>;
 
 /**
  * SQLite doesn't support the boolean type, so Evolu uses SqliteBoolean instead.
@@ -45,7 +41,7 @@ export const SqliteBoolean = S.number.pipe(
   S.filter((s) => s === 0 || s === 1),
   S.brand("SqliteBoolean"),
 );
-export type SqliteBoolean = S.Schema.To<typeof SqliteBoolean>;
+export type SqliteBoolean = S.Schema.Type<typeof SqliteBoolean>;
 
 /**
  * A helper for casting types not supported by SQLite. SQLite doesn't support
@@ -96,7 +92,7 @@ export const String = S.string.pipe(
   ),
   S.brand("String"),
 );
-export type String = S.Schema.To<typeof String>;
+export type String = S.Schema.Type<typeof String>;
 
 /**
  * A string with a maximum length of 1000 characters.
@@ -108,7 +104,7 @@ export type String = S.Schema.To<typeof String>;
  *   S.decode(String1000)(value);
  */
 export const String1000 = String.pipe(S.maxLength(1000), S.brand("String1000"));
-export type String1000 = S.Schema.To<typeof String1000>;
+export type String1000 = S.Schema.Type<typeof String1000>;
 
 /**
  * A nonempty string with a maximum length of 1000 characters.
@@ -124,7 +120,7 @@ export const NonEmptyString1000 = String.pipe(
   S.maxLength(1000),
   S.brand("NonEmptyString1000"),
 );
-export type NonEmptyString1000 = S.Schema.To<typeof NonEmptyString1000>;
+export type NonEmptyString1000 = S.Schema.Type<typeof NonEmptyString1000>;
 
 /**
  * A positive integer.
@@ -140,4 +136,4 @@ export const PositiveInt = S.number.pipe(
   S.positive(),
   S.brand("PositiveInt"),
 );
-export type PositiveInt = S.Schema.To<typeof PositiveInt>;
+export type PositiveInt = S.Schema.Type<typeof PositiveInt>;

package/src/Public.ts

@@ -1,3 +1,4 @@
+export { sql } from "kysely";
 export type { NotNull } from "kysely";
 export { jsonArrayFrom, jsonObjectFrom } from "kysely/helpers/sqlite";
 export type { Timestamp, TimestampError } from "./Crdt.js";
@@ -5,6 +6,7 @@ export type { InvalidMnemonicError, Mnemonic } from "./Crypto.js";
 export { database, table } from "./Db.js";
 export type { ExtractRow, QueryResult } from "./Db.js";
 export type { EvoluError, UnexpectedError } from "./ErrorStore.js";
+export { createIndex } from "./Evolu.js";
 export * from "./Model.js";
 export type { Owner, OwnerId } from "./Owner.js";
 export { canUseDom } from "./Platform.js";

package/src/Sql.ts

@@ -1,123 +1,41 @@
-// TODO: This file should be generated from a script via Kysely.
-// The reason for not using Kysely directly is bundle size.
-// [Playground Link](https://kyse.link/?p=b&i=haFkpnNxbGl0ZaF2pjAuMjYuMKFz2gFoaW1wb3J0IHsgR2VuZXJhdGVkIH0gZnJvbSAna3lzZWx5JwoKZGVjbGFyZSBnbG9iYWwgewogIGludGVyZmFjZSBEQiB7CiAgICBldm9sdV9tZXNzYWdlOiB7CiAgICAgIHRpbWVzdGFtcDogc3RyaW5nLAogICAgICB0YWJsZTogc3RyaW5nLAogICAgICByb3c6IHN0cmluZywKICAgICAgY29sdW1uOiBzdHJpbmcsCiAgICAgIHZhbHVlOiB1bmtub3duCiAgICB9LAoKICAgIGV2b2x1X293bmVyOiB7CiAgICAgIGlkOiBzdHJpbmcKICAgICAgbW5lbW9uaWM6IHN0cmluZwogICAgICBlbmNyeXB0aW9uS2V5OiBVaW50OEFycmF5LAogICAgICB0aW1lc3RhbXA6IHN0cmluZywKICAgICAgbWVya2xlVHJlZTogc3RyaW5nCiAgICB9CiAgfQp9oXHaBnhhd2FpdCBreXNlbHkuc2VsZWN0RnJvbSgiZXZvbHVfb3duZXIiKQogIC5zZWxlY3QoWyJpZCIsICJtbmVtb25pYyIsICJlbmNyeXB0aW9uS2V5Il0pCiAgLmV4ZWN1dGUoKQoKYXdhaXQga3lzZWx5LnNjaGVtYQogIC5jcmVhdGVUYWJsZSgnZXZvbHVfbWVzc2FnZScpCiAgLmFkZENvbHVtbigndGltZXN0YW1wJywgJ2Jsb2InLCBjb2wgPT4gY29sLnByaW1hcnlLZXkoKSkKICAuYWRkQ29sdW1uKCd0YWJsZScsICdibG9iJykKICAuYWRkQ29sdW1uKCdyb3cnLCAnYmxvYicpCiAgLmFkZENvbHVtbignY29sdW1uJywgJ2Jsb2InKQogIC5hZGRDb2x1bW4oJ3ZhbHVlJywgJ2Jsb2InKQogIC5leGVjdXRlKCkKCmF3YWl0IGt5c2VseS5zY2hlbWEKICAuY3JlYXRlSW5kZXgoImluZGV4X2V2b2x1X21lc3NhZ2UiKQogIC5vbigiZXZvbHVfbWVzc2FnZSIpCiAgLmNvbHVtbnMoWyJ0YWJsZSIsICJyb3ciLCAiY29sdW1uIiwgInRpbWVzdGFtcCJdKQogIC5leGVjdXRlKCkKCmF3YWl0IGt5c2VseS5zY2hlbWEKICAuY3JlYXRlVGFibGUoJ2V2b2x1X19vd25lcicpCiAgLmFkZENvbHVtbignaWQnLCAnYmxvYicpCiAgLmFkZENvbHVtbignbW5lbW9uaWMnLCAnYmxvYicpCiAgLmFkZENvbHVtbignZW5jcnlwdGlvbktleScsICdibG9iJykKICAuYWRkQ29sdW1uKCd0aW1lc3RhbXAnLCAnYmxvYicpCiAgLmFkZENvbHVtbignbWVya2xlVHJlZScsICdibG9iJykKICAuZXhlY3V0ZSgpCgphd2FpdCBreXNlbHkuaW5zZXJ0SW50bygiZXZvbHVfb3duZXIiKQogIC52YWx1ZXMoewogICAgImlkIjogImIiLAogICAgIm1uZW1vbmljIjogImEiLAogICAgImVuY3J5cHRpb25LZXkiOiBuZXcgVWludDhBcnJheSgpLAogICAgInRpbWVzdGFtcCI6ICJhIiwKICAgICJtZXJrbGVUcmVlIjogImIiCiAgfSkKICAuZXhlY3V0ZSgpCgphd2FpdCBreXNlbHkuc2VsZWN0RnJvbSgiZXZvbHVfb3duZXIiKQogIC5zZWxlY3QoWyJ0aW1lc3RhbXAiLCAibWVya2xlVHJlZSJdKQogIC5leGVjdXRlKCkKCmF3YWl0IGt5c2VseS5zZWxlY3RGcm9tKCJldm9sdV9tZXNzYWdlIikKICAuc2VsZWN0KCJ0aW1lc3RhbXAiKQogIC53aGVyZSgndGFibGUnLCAnPScsICcxJykKICAud2hlcmUoJ3JvdycsICc9JywgJzInKQogIC53aGVyZSgnY29sdW1uJywgJz0nLCAnMycpCiAgLm9yZGVyQnkoInRpbWVzdGFtcCIsICJkZXNjIikKICAubGltaXQoMSkKICAuZXhlY3V0ZVRha2VGaXJzdCgpCgphd2FpdCBreXNlbHkuaW5zZXJ0SW50bygiZXZvbHVfbWVzc2FnZSIpCiAgLnZhbHVlcyh7CiAgICAidGltZXN0YW1wIjogJzEnLAogICAgInRhYmxlIjogJzInLAogICAgInJvdyI6ICczJywKICAgICJjb2x1bW4iOiAnNCcsCiAgICAidmFsdWUiOiAnNScsCiAgfSkKICAub25Db25mbGljdChvYyA9PiBvYy5kb05vdGhpbmcoKSkKICAuZXhlY3V0ZSgpCgphd2FpdCBreXNlbHkudXBkYXRlVGFibGUoImV2b2x1X293bmVyIikKICAuc2V0KHsKICAgICJtZXJrbGVUcmVlIjogJzEnLAogICAgInRpbWVzdGFtcCI6ICIyIgogIH0pCiAgLmV4ZWN1dGUoKQoKYXdhaXQga3lzZWx5LnNlbGVjdEZyb20oImV2b2x1X21lc3NhZ2UiKQogIC5zZWxlY3RBbGwoKQogIC53aGVyZSgidGltZXN0YW1wIiwgIj49IiwgJzEnKQogIC5vcmRlckJ5KCJ0aW1lc3RhbXAiKQogIC5leGVjdXRlKCmhY8M=)
-
-export const selectOwner = `
-select
-  "id",
-  "mnemonic",
-  "encryptionKey"
-from
-  "evolu_owner"
-`.trim();
-
-export const createMessageTable = `
-create table
-  "evolu_message" (
-    "timestamp" blob primary key,
-    "table" blob,
-    "row" blob,
-    "column" blob,
-    "value" blob
-  );
-`.trim();
-
-export const createMessageTableIndex = `
-create index "index_evolu_message" on "evolu_message" (
-  "table", "row", "column", "timestamp"
-);
-`.trim();
-
-export const createOwnerTable = `
-create table
-  "evolu_owner" (
-    "id" blob,
-    "mnemonic" blob,
-    "encryptionKey" blob,
-    "timestamp" blob,
-    "merkleTree" blob
-  );
-`.trim();
-
-export const insertOwner = `
-insert into
-  "evolu_owner" (
-    "id",
-    "mnemonic",
-    "encryptionKey",
-    "timestamp",
-    "merkleTree"
-  )
-values
-  (?, ?, ?, ?, ?);
-`.trim();
-
-export const selectOwnerTimestampAndMerkleTree = `
-select
-  "timestamp",
-  "merkleTree"
-from
-  "evolu_owner"
-`.trim();
-
-export const selectLastTimestampForTableRowColumn = `
-select
-  "timestamp"
-from
-  "evolu_message"
-where
-  "table" = ?
-  and "row" = ?
-  and "column" = ?
-order by
-  "timestamp" desc
-limit
-  1
-`.trim();
-
-export const upsertValueIntoTableRowColumn = (
-  table: string,
-  column: string,
-): string =>
-  `
-insert into
-  "${table}" ("id", "${column}", "createdAt", "updatedAt")
-values
-  (?, ?, ?, ?)
-on conflict do update set
-  "${column}" = ?,
-  "updatedAt" = ?
-`.trim();
-
-export const deleteTableRow = (table: string): string =>
-  `
-delete from "${table}"
-where
-  "id" = ?;
-`.trim();
-
-export const insertIntoMessagesIfNew = `
-insert into
-  "evolu_message" ("timestamp", "table", "row", "column", "value")
-values
-  (?, ?, ?, ?, ?)
-on conflict do nothing
-`.trim();
-
-export const updateOwnerTimestampAndMerkleTree = `
-update "evolu_owner"
-set
-  "timestamp" = ?,
-  "merkleTree" = ?
-`.trim();
-
-export const selectMessagesToSync = `
-select
-  *
-from
-  "evolu_message"
-where
-  "timestamp" >= ?
-order by
-  "timestamp"
-`.trim();
+// this file is generated by generateSql script
+import { SqliteQuery } from "./Sqlite.js";
+export const selectOwner: SqliteQuery = {
+  sql: `select "id", "mnemonic", "encryptionKey" from "evolu_owner"`,
+};
+
+export const createMessageTable: SqliteQuery = {
+  sql: `create table "evolu_message" ("timestamp" blob primary key, "table" blob, "row" blob, "column" blob, "value" blob)`,
+};
+
+export const createMessageTableIndex: SqliteQuery = {
+  sql: `create index "index_evolu_message" on "evolu_message" ("table", "row", "column", "timestamp" desc)`,
+};
+
+export const createOwnerTable: SqliteQuery = {
+  sql: `create table "evolu_owner" ("id" blob, "mnemonic" blob, "encryptionKey" blob, "timestamp" blob, "merkleTree" blob)`,
+};
+
+export const insertOwner: SqliteQuery = {
+  sql: `insert into "evolu_owner" ("id", "mnemonic", "encryptionKey", "timestamp", "merkleTree") values (?, ?, ?, ?, ?)`,
+};
+
+export const selectOwnerTimestampAndMerkleTree: SqliteQuery = {
+  sql: `select "timestamp", "merkleTree" from "evolu_owner"`,
+};
+
+export const selectLastTimestampForTableRowColumn: SqliteQuery = {
+  sql: `select "timestamp" from "evolu_message" where "table" = ? and "row" = ? and "column" = ? order by "timestamp" desc limit ?`,
+};
+
+export const insertIntoMessagesIfNew: SqliteQuery = {
+  sql: `insert into "evolu_message" ("timestamp", "table", "row", "column", "value") values (?, ?, ?, ?, ?) on conflict do nothing`,
+};
+
+export const updateOwnerTimestampAndMerkleTree: SqliteQuery = {
+  sql: `update "evolu_owner" set "merkleTree" = ?, "timestamp" = ?`,
+};
+
+export const selectMessagesToSync: SqliteQuery = {
+  sql: `select * from "evolu_message" where "timestamp" >= ? order by "timestamp"`,
+};

package/src/Sqlite.ts

@@ -1,16 +1,24 @@
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import { Equivalence } from "effect/Equivalence";
 import * as Predicate from "effect/Predicate";
 
 export interface Sqlite {
-  readonly exec: (arg: string | SqliteQuery) => Effect.Effect<SqliteExecResult>;
+  readonly exec: (query: SqliteQuery) => Effect.Effect<SqliteExecResult>;
 }
 
 export const Sqlite = Context.GenericTag<Sqlite>("@services/Sqlite");
 
 export interface SqliteQuery {
   readonly sql: string;
-  readonly parameters: Value[];
+  readonly parameters?: Value[];
+  readonly options?: SqliteQueryOptions;
+}
+
+export interface SqliteQueryOptions {
+  readonly logQueryExecutionTime?: boolean;
+  /** https://www.sqlite.org/eqp.html */
+  readonly logExplainQueryPlan?: boolean;
 }
 
 export type Value = SqliteValue | JsonObjectOrArray;
@@ -41,11 +49,6 @@ export const valuesToSqliteValues = (
     isJsonObjectOrArray(value) ? JSON.stringify(value) : value,
   );
 
-export const ensureSqliteQuery = (arg: string | SqliteQuery): SqliteQuery => {
-  if (typeof arg !== "string") return arg;
-  return { sql: arg, parameters: [] };
-};
-
 export const maybeParseJson = (rows: SqliteRow[]): SqliteRow[] =>
   parseArray(rows);
 
@@ -96,3 +99,58 @@ const isSqlMutationRegEx = new RegExp(
 
 export const isSqlMutation = (sql: string): boolean =>
   isSqlMutationRegEx.test(sql);
+
+export const maybeLogSqliteQueryExecutionTime =
+  (query: SqliteQuery) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> => {
+    if (!query.options?.logQueryExecutionTime) return effect;
+    return effect.pipe(
+      Effect.tap(() => Effect.log("QueryExecutionTime")),
+      // Not using Effect.log because of formating
+      // eslint-disable-next-line no-console
+      Effect.tap(() => console.log(query.sql)),
+      Effect.withLogSpan("duration"),
+    );
+  };
+
+export type SqliteQueryPlanRow = {
+  id: number;
+  parent: number;
+  detail: string;
+};
+
+export const drawSqliteQueryPlan = (rows: SqliteQueryPlanRow[]): string =>
+  rows
+    .map((row) => {
+      let parentId = row.parent;
+      let indent = 0;
+
+      do {
+        const parent = rows.find((r) => r.id === parentId);
+        if (!parent) break;
+        parentId = parent.parent;
+        indent++;
+        // eslint-disable-next-line no-constant-condition
+      } while (true);
+
+      return `${"  ".repeat(indent)}${row.detail}`;
+    })
+    .join("\n");
+
+export interface SqliteSchema {
+  readonly tables: ReadonlyArray<Table>;
+  readonly indexes: ReadonlyArray<Index>;
+}
+
+export interface Table {
+  readonly name: string;
+  readonly columns: ReadonlyArray<string>;
+}
+
+export interface Index {
+  readonly name: string;
+  readonly sql: string;
+}
+
+export const indexEquivalence: Equivalence<Index> = (self, that) =>
+  self.name === that.name && self.sql === that.sql;