@evolu/common 5.4.8 → 6.0.0

package/src/Sqlite.ts

@@ -1,166 +1,353 @@
-import * as Console from "effect/Console";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as Exit from "effect/Exit";
-import * as Layer from "effect/Layer";
-import * as Predicate from "effect/Predicate";
-import { Config } from "./Config.js";
-
-export interface Sqlite {
-  readonly exec: (query: SqliteQuery) => Effect.Effect<SqliteExecResult>;
-
-  readonly transaction: (
-    /**
-     * Use `exclusive` for mutations and `shared` for read-only queries. This
-     * shared/exclusive lock pattern allows multiple simultaneous readers but
-     * only one writer. In Evolu, this pattern also ensures that every write can
-     * be immediately read without waiting to complete. For example, we can add
-     * data on one page and then immediately redirect to another, and the data
-     * will be there.
-     *
-     * There is also a `last` mode that ensures no other transaction can run.
-     * It's for Db reset to ensure no data are accidentally saved after database
-     * wipe-out.
-     */
-    mode: SqliteTransactionMode,
-  ) => <A, E, R>(
-    effect: Effect.Effect<A, E, R>,
-  ) => Effect.Effect<A, E, Sqlite | R>;
-
-  readonly export: () => Effect.Effect<Uint8Array>;
+import { ConsoleDep } from "./Console.js";
+import { createTransferableError, TransferableError } from "./Error.js";
+import { err, ok, Result, tryAsync, trySync } from "./Result.js";
+import {
+  Boolean,
+  Null,
+  Number,
+  SimpleName,
+  String,
+  transform,
+  Uint8Array,
+  union,
+} from "./Type.js";
+import { Brand, Predicate, IntentionalNever } from "./Types.js";
+
+/**
+ * SQLite driver interface. This is the minimal interface that platform-specific
+ * drivers must implement.
+ */
+export interface SqliteDriver extends Disposable {
+  readonly exec: (query: SqliteQuery, isMutation: boolean) => SqliteExecResult;
+  readonly export: () => Uint8Array;
 }
 
-export const Sqlite = Context.GenericTag<Sqlite>("Sqlite");
+export type CreateSqliteDriver = (
+  name: SimpleName,
+  options?: SqliteDriverOptions,
+) => Promise<SqliteDriver>;
 
-export type SqliteTransactionMode = "exclusive" | "shared" | "last";
+export interface CreateSqliteDriverDep {
+  readonly createSqliteDriver: CreateSqliteDriver;
+}
 
-export class SqliteFactory extends Context.Tag("SqliteFactory")<
-  SqliteFactory,
-  {
-    readonly createSqlite: Effect.Effect<Sqlite, never, Config>;
-  }
->() {
-  static Common = Layer.effect(
-    SqliteFactory,
-    Effect.map(SqliteFactory, (platformSqliteFactory) => ({
-      createSqlite: Effect.logTrace("SqliteFactory createSqlite").pipe(
-        Effect.zipRight(platformSqliteFactory.createSqlite),
-        Effect.map(
-          (platformSqlite): Sqlite => ({
-            ...platformSqlite,
-
-            exec: (query) =>
-              platformSqlite.exec(query).pipe(
-                Effect.tap((result) => {
-                  maybeParseJson(result.rows);
-                }),
-                Effect.tap((result) =>
-                  ["begin", "rollback", "commit"].includes(query.sql)
-                    ? Effect.logDebug(`SQLiteCommon ${query.sql} transaction`)
-                    : Effect.logDebug(["SQLiteCommon exec", query, result]),
-                ),
-              ),
-
-            transaction: (mode) => (effect) => {
-              // Shared is for readonly queries.
-              if (mode === "shared")
-                return platformSqlite.transaction(mode)(effect);
-              return Effect.flatMap(Sqlite, (sqlite) =>
-                Effect.acquireUseRelease(
-                  sqlite.exec({ sql: "begin" }),
-                  () => effect,
-                  (_, exit) =>
-                    Exit.isFailure(exit)
-                      ? sqlite.exec({ sql: "rollback" })
-                      : sqlite.exec({ sql: "commit" }),
-                ),
-              ).pipe(platformSqlite.transaction(mode));
-            },
-          }),
-        ),
-      ),
-    })),
-  );
+export interface SqliteDriverOptions {
+  memory?: boolean;
+}
+
+/**
+ * Cross-platform SQLite abstraction.
+ *
+ * This API is sync only because SQLite is an embedded, single-threaded engine.
+ * All operations are blocking and in-process, so async APIs add needless
+ * complexity without any real benefit and are also slower. Check better-sqlite3
+ * GitHub issues and docs for details.
+ */
+export interface Sqlite extends Disposable {
+  readonly exec: <R extends SqliteRow = SqliteRow>(
+    query: SqliteQuery,
+  ) => Result<SqliteExecResult<R>, SqliteError>;
+
+  /**
+   * Executes a transaction, running the provided callback within a begin/commit
+   * block. If the callback returns an error (E or {@link SqliteError}), the
+   * transaction is rolled back. If the rollback fails, a SqliteError is
+   * returned with both the original error and rollbackError.
+   */
+  readonly transaction: <T, E>(
+    callback: () => Result<T, E | SqliteError>,
+  ) => Result<T, E | SqliteError>;
+
+  readonly export: () => Result<Uint8Array, SqliteError>;
+}
+
+export interface SqliteDep {
+  readonly sqlite: Sqlite;
 }
 
 export interface SqliteQuery {
-  readonly sql: string;
-  readonly parameters?: Value[];
+  readonly sql: SafeSql;
+  readonly parameters: Array<SqliteValue>;
   readonly options?: SqliteQueryOptions;
 }
 
+/** A type representing a sanitized SQL string. */
+export type SafeSql = string & Brand<"TimestampString">;
+
+/**
+ * A value that can be stored in Sqlite.
+ *
+ * Note that Evolu can't support Int64 because expo-sqlite (and some others) do
+ * not support it.
+ */
+export const SqliteValue = union(Null, String, Number, Uint8Array);
+export type SqliteValue = typeof SqliteValue.Type;
+
 export interface SqliteQueryOptions {
+  /**
+   * If set to `true`, logs the time taken to execute the SQL query. Useful for
+   * performance monitoring and identifying slow queries.
+   */
   readonly logQueryExecutionTime?: boolean;
-  /** https://www.sqlite.org/eqp.html */
+
+  /**
+   * If set to `true`, logs the SQLite Explain Query Plan (EQP) for the query.
+   * This can help analyze how SQLite plans to execute the query and identify
+   * potential optimizations.
+   *
+   * See: {@link https://www.sqlite.org/eqp.html}.
+   */
   readonly logExplainQueryPlan?: boolean;
-}
 
-export type Value = SqliteValue | JsonObjectOrArray;
-export type SqliteValue = null | string | number | Uint8Array;
-export type JsonObjectOrArray = JsonObject | JsonArray;
-type JsonObject = { [key: string]: Json };
-type JsonArray = ReadonlyArray<Json>;
-type JsonPrimitive = string | number | boolean | null;
-type Json = JsonPrimitive | JsonObject | JsonArray;
+  /**
+   * If set to `true`, explicitly prepares the query before execution. Prepared
+   * statements can improve performance for repeated queries by reusing the
+   * compiled query.
+   *
+   * See: {@link https://sqlite.org/wasm/doc/trunk/api-oo1.md#db-prepare}.
+   */
+  readonly prepare?: boolean;
+}
 
-export interface SqliteExecResult {
-  readonly rows: SqliteRow[];
+/** Result of executing a SQLite query. */
+export interface SqliteExecResult<R extends SqliteRow = SqliteRow> {
+  readonly rows: ReadonlyArray<R>;
   readonly changes: number;
 }
 
+/** Represents an error that occurred during a SQLite operation. */
+export interface SqliteError {
+  readonly type: "SqliteError";
+  readonly error: TransferableError;
+  readonly rollbackError?: TransferableError;
+}
+
 export type SqliteRow = Record<string, SqliteValue>;
 
-export const isJsonObjectOrArray: Predicate.Refinement<
-  Value,
-  JsonObjectOrArray
-> = (value): value is JsonObjectOrArray =>
-  value !== null && typeof value === "object" && !Predicate.isUint8Array(value);
-
-export const valuesToSqliteValues = (
-  values: ReadonlyArray<Value>,
-): SqliteValue[] =>
-  values.map((value) =>
-    isJsonObjectOrArray(value) ? JSON.stringify(value) : value,
-  );
-
-/** This function mutates for better performance. */
-export const maybeParseJson = (rows: SqliteRow[]): void => {
-  parseArray(rows);
-};
+/**
+ * Creates a fully featured {@link Sqlite} instance from a {@link SqliteDriver}
+ * implementation.
+ */
+export const createSqlite =
+  (deps: CreateSqliteDriverDep & Partial<ConsoleDep>) =>
+  async (
+    name: SimpleName,
+    options?: SqliteDriverOptions,
+  ): Promise<Result<Sqlite, SqliteError>> =>
+    tryAsync(async () => {
+      const driver = await deps.createSqliteDriver(name, options);
+      let isDisposed = false;
+
+      const doRollback = () =>
+        trySync(() => {
+          deps.console?.log("[sql] rollback");
+          driver.exec(sql`rollback;`, true);
+        }, createSqliteError);
+
+      const sqlite: Sqlite = {
+        exec: (query) =>
+          trySync(
+            () => {
+              deps.console?.log("[sql]", query);
+
+              const result = maybeLogSqliteQueryExecutionTime(query, () =>
+                driver.exec(query, isSqlMutation(query.sql)),
+              );
+
+              deps.console?.log("[sql]", result);
+
+              return result as IntentionalNever;
+            },
+            (error): SqliteError => ({
+              type: "SqliteError",
+              error: createTransferableError(error),
+            }),
+          ),
+
+        transaction: (callback) => {
+          const transactionResult = trySync(() => {
+            deps.console?.log("[sql] begin");
+            driver.exec(sql`begin;`, true);
+
+            const result = callback();
+            if (!result.ok) return result;
+
+            deps.console?.log("[sql] commit");
+            driver.exec(sql`commit;`, true);
+
+            return result;
+          }, createSqliteError);
+
+          // There was an SqliteError during begin, callback, or commit
+          if (!transactionResult.ok) {
+            const rollback = doRollback();
+            if (!rollback.ok) {
+              deps.console?.log("[sql] rollback failed", rollback.error);
+              return err({
+                type: "SqliteError",
+                error: transactionResult.error.error,
+                rollbackError: rollback.error.error,
+              });
+            }
+            return transactionResult;
+          }
+
+          // Callback returned an error
+          if (!transactionResult.value.ok) {
+            const rollback = doRollback();
+            if (!rollback.ok) {
+              deps.console?.log("[sql] rollback failed", rollback.error);
+              return err({
+                type: "SqliteError",
+                error: createTransferableError(transactionResult.value.error),
+                rollbackError: rollback.error.error,
+              });
+            }
+            return transactionResult.value;
+          }
+
+          return ok(transactionResult.value.value);
+        },
+
+        export: () =>
+          trySync(
+            () => {
+              return driver.export();
+            },
+            (error): SqliteError => ({
+              type: "SqliteError",
+              error: createTransferableError(error),
+            }),
+          ),
 
-const parseArray = <T>(a: T[]): T[] => {
-  for (let i = 0; i < a.length; ++i) a[i] = parse(a[i]) as T;
-  return a;
+        [Symbol.dispose]: () => {
+          if (isDisposed) return;
+          isDisposed = true;
+          driver[Symbol.dispose]();
+        },
+      };
+
+      return sqlite;
+    }, createSqliteError);
+
+const createSqliteError = (error: unknown): SqliteError => ({
+  type: "SqliteError",
+  error: createTransferableError(error),
+});
+
+const maybeLogSqliteQueryExecutionTime = <T>(
+  query: SqliteQuery,
+  callback: () => T,
+): T => {
+  if (!query.options?.logQueryExecutionTime) {
+    return callback();
+  }
+
+  const start = performance.now();
+  const result = callback();
+  const elapsed = performance.now() - start;
+
+  // eslint-disable-next-line no-console
+  console.log(`SqliteQueryExecutionTime: ${elapsed.toString()}ms`, query);
+
+  return result;
 };
 
-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);
-  if (typeof o === "object" && o !== null && !Predicate.isUint8Array(o))
-    return parseObject(o as Record<string, unknown>);
-  return o;
+export interface PreparedStatements<P> extends Disposable {
+  readonly get: <T extends boolean>(
+    query: SqliteQuery,
+    alwaysPrepare?: T,
+  ) => T extends true ? P : P | null;
+}
+
+export const createPreparedStatementsCache = <P>(
+  factory: (sql: SafeSql) => P,
+  disposeFn: (statement: P) => void,
+): PreparedStatements<P> => {
+  let isDisposed = false;
+  const cache = new Map<SafeSql, P>();
+
+  return {
+    get: (query, alwaysPrepare) => {
+      if (alwaysPrepare !== true && !query.options?.prepare)
+        return null as IntentionalNever;
+      let statement = cache.get(query.sql);
+      if (!statement) {
+        statement = factory(query.sql);
+        cache.set(query.sql, statement);
+      }
+      return statement as IntentionalNever;
+    },
+
+    [Symbol.dispose]: () => {
+      if (isDisposed) return;
+      isDisposed = true;
+      cache.forEach(disposeFn);
+      cache.clear();
+    },
+  };
 };
 
-const parseString = (s: string): unknown => {
-  if (maybeJson(s))
-    try {
-      return parse(JSON.parse(s));
-    } catch (err) {
-      // Nothing to do.
+export interface SqlIdentifier {
+  type: "SqlIdentifier";
+  sql: SafeSql;
+}
+
+export interface RawSql {
+  type: "RawSql";
+  sql: string;
+}
+
+export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
+
+/** TODO: Docs. */
+export const sql = (
+  strings: TemplateStringsArray,
+  ...parameters: Array<SqlTemplateParam>
+): SqliteQuery => {
+  let sql = "";
+  const values: Array<SqliteValue> = [];
+
+  for (let i = 0; i < strings.length; i++) {
+    sql += strings[i];
+    if (i < parameters.length) {
+      const param = parameters[i];
+      if (typeof param === "object" && param != null && "type" in param) {
+        sql += param.sql;
+      } else {
+        sql += "?";
+        values.push(param);
+      }
     }
-  return s;
+  }
+
+  return { sql: sql as SafeSql, parameters: values };
 };
 
-export const maybeJson: Predicate.Predicate<string> = (value) =>
-  value.match(/^[[{]/) != null;
+sql.identifier = (identifier: string): SqlIdentifier => ({
+  type: "SqlIdentifier",
+  // From Kysely
+  sql: `"${identifier.replace(/"/g, '""')}"` as SafeSql,
+});
+
+/**
+ * Insert any string.
+ *
+ * Sql.raw sometimes breaks auto-formatting because the parser does not consider
+ * it valid SQL. A workaround is to remove it, format it, and put it back.
+ *
+ * **Warning**: This is not escaped.
+ */
+sql.raw = (raw: string): RawSql => ({ type: "RawSql", sql: raw });
 
-const parseObject = (o: Record<string, unknown>): Record<string, unknown> => {
-  for (const key in o) o[key] = parse(o[key]);
-  return o;
+sql.prepared = (
+  strings: TemplateStringsArray,
+  ...parameters: Array<SqlTemplateParam>
+): SqliteQuery => {
+  const query = sql(strings, ...parameters);
+  return { ...query, options: { prepare: true } };
 };
 
-/** This is good enough detection because SQL strings in Evolu are predictable. */
 const isSqlMutationRegEx = new RegExp(
   `\\b(${[
     "alter",
@@ -170,34 +357,45 @@ const isSqlMutationRegEx = new RegExp(
     "insert",
     "replace",
     "update",
+    "begin",
+    "commit",
+    "rollback",
+    "pragma",
+    "vacuum",
   ].join("|")})\\b`,
+  "i",
 );
 
-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.Do.pipe(
-      Effect.let("start", () => performance.now()),
-      Effect.bind("result", () => effect),
-      Effect.let("elapsed", ({ start }) => performance.now() - start),
-      Effect.tap(({ elapsed }) =>
-        Console.log(`QueryExecutionTime: ${elapsed}ms`, query),
-      ),
-      Effect.map(({ result }) => result),
-    );
-  };
+export const isSqlMutation: Predicate<string> = (sql) =>
+  isSqlMutationRegEx.test(sql.replace(/--.*$/gm, ""));
 
-export type SqliteQueryPlanRow = {
+export interface SqliteQueryPlanRow {
   id: number;
   parent: number;
   detail: string;
-};
+}
+
+export const explainSqliteQueryPlan =
+  (deps: SqliteDep) =>
+  (query: SqliteQuery): Result<void, SqliteError> => {
+    const result = deps.sqlite.exec({
+      ...query,
+      sql: `EXPLAIN QUERY PLAN ${query.sql}` as SafeSql,
+    });
+    if (!result.ok) return result;
+
+    // eslint-disable-next-line no-console
+    console.log("ExplainQueryPlan", query);
+    // eslint-disable-next-line no-console
+    console.log(
+      drawSqliteQueryPlan(
+        result.value.rows as unknown as Array<SqliteQueryPlanRow>,
+      ),
+    );
+    return ok();
+  };
 
-export const drawSqliteQueryPlan = (rows: SqliteQueryPlanRow[]): string =>
+const drawSqliteQueryPlan = (rows: Array<SqliteQueryPlanRow>): string =>
   rows
     .map((row) => {
       let parentId = row.parent;
@@ -208,9 +406,24 @@ export const drawSqliteQueryPlan = (rows: SqliteQueryPlanRow[]): string =>
         if (!parent) break;
         parentId = parent.parent;
         indent++;
-        // eslint-disable-next-line no-constant-condition
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, no-constant-condition
       } while (true);
 
       return `${"  ".repeat(indent)}${row.detail}`;
     })
     .join("\n");
+
+/**
+ * SQLite represents boolean values using `0` (false) and `1` (true) instead of
+ * a dedicated boolean type. This transform Type ensures that values conform to
+ * SQLite's boolean representation.
+ *
+ * See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
+ */
+export const SqliteBoolean = transform(
+  Boolean,
+  union(0, 1),
+  (value) => ok(value ? (1 as const) : (0 as const)),
+  (value) => value === 1,
+);
+export type SqliteBoolean = typeof SqliteBoolean.Type;