@evolu/common 7.4.1 → 8.0.0-next.1

package/src/local-first/Query.ts

@@ -1,27 +1,38 @@
-import { Brand } from "../Brand.js";
-import { bytesToHex, hexToBytes } from "../Buffer.js";
-import { createRandomBytes } from "../Crypto.js";
-import {
-  createRecord,
-  isPlainObject,
-  objectToEntries,
-  ReadonlyRecord,
-} from "../Object.js";
-import { ok, Result } from "../Result.js";
+/**
+ * Query helpers, execution, and caching.
+ *
+ * @module
+ */
+
+import type {
+  AliasableExpression,
+  Expression,
+  Simplify as KyselySimplify,
+  RawBuilder,
+  SelectQueryNode,
+} from "kysely";
 import {
-  eqSqliteValue,
-  explainSqliteQueryPlan,
-  SafeSql,
-  SqliteDep,
-  SqliteError,
-  SqliteQuery,
-  SqliteQueryOptions,
-  SqliteRow,
-  SqliteValue,
-} from "../Sqlite.js";
-import { Store, StoreSubscribe } from "../Store.js";
-import { createId, Id, String } from "../Type.js";
-import { Simplify } from "../Types.js";
+  AliasNode,
+  ColumnNode,
+  ExpressionWrapper,
+  IdentifierNode,
+  sql as kyselySqlBuilder,
+  ReferenceNode,
+  TableNode,
+  ValueNode,
+} from "kysely";
+import type { Brand } from "../Brand.js";
+import { createRandomBytes } from "../Crypto.js";
+import type { ReadonlyRecord } from "../Object.js";
+import { createRecord, isPlainObject } from "../Object.js";
+import type { SqliteQueryString } from "../Sqlite.js";
+import { eqSqliteValue, SqliteValue } from "../Sqlite.js";
+import { createId, String } from "../Type.js";
+import type { Simplify } from "../Types.js";
+import type { EvoluSchema } from "./Schema.js";
+
+export { sql as kyselySql } from "kysely";
+export type { NotNull as KyselyNotNull } from "kysely";
 
 /**
  * A type-safe SQL query.
@@ -29,21 +40,27 @@ import { Simplify } from "../Types.js";
  * ### Example
  *
  * ```ts
- * const allTodos = evolu.createQuery((db) =>
- *   db.selectFrom("todo").selectAll(),
- * );
+ * const createQuery = createQueryBuilder(Schema);
+ * const allTodos = createQuery((db) => db.selectFrom("todo").selectAll());
  * type AllTodosRow = typeof allTodos.Row;
  * ```
  */
-export type Query<R extends Row = Row> = string &
+export type Query<
+  S extends EvoluSchema = EvoluSchema,
+  R extends Row = Row,
+> = SqliteQueryString &
   Brand<"Query"> & {
+    /** A shorthand for the query schema. */
+    Schema: S;
+
     /**
      * A shorthand for {@link InferRow}.
      *
      * ### Example
      *
      * ```ts
-     * const allTodos = evolu.createQuery((db) =>
+     * const createQuery = createQueryBuilder(Schema);
+     * const allTodos = createQuery((db) =>
      *   db.selectFrom("todo").selectAll(),
      * );
      * type AllTodosRow = typeof allTodos.Row;
@@ -52,187 +69,191 @@ export type Query<R extends Row = Row> = string &
     Row: R;
   };
 
-/**
- * Evolu serializes {@link SqliteQuery} into a string to be easily used as a key
- * and for comparison.
- */
-export const serializeQuery = <R extends Row>(query: SqliteQuery): Query<R> => {
-  const params = query.parameters.map((v) =>
-    v instanceof Uint8Array
-      ? (["b", bytesToHex(v)] as const)
-      : (["j", v] as const),
-  );
-
-  const options = query.options
-    ? objectToEntries(query.options).toSorted(([a], [b]) => a.localeCompare(b))
-    : [];
-
-  return JSON.stringify([query.sql, params, options]) as Query<R>;
-};
-
-export const deserializeQuery = <R extends Row>(
-  query: Query<R>,
-): SqliteQuery => {
-  const [sql, paramsArr, optionsArr] = JSON.parse(query) as [
-    SafeSql,
-    Array<readonly ["b", string] | readonly ["j", string | number | null]>,
-    Array<Array<string | number | null>>,
-  ];
-
-  const parameters = paramsArr.map(([type, value]) =>
-    type === "b" ? hexToBytes(value) : value,
-  );
-
-  const options = optionsArr.length
-    ? (Object.fromEntries(optionsArr) as SqliteQueryOptions)
-    : undefined;
-
-  return {
-    sql,
-    parameters,
-    ...(options !== undefined && { options }),
-  };
-};
-
-export type InferRow<T extends Query> = T extends Query<infer R> ? R : never;
+export type InferRow<T extends Query> =
+  T extends Query<any, infer R> ? R : never;
 
 export interface Row {
   readonly [key: string]:
     | SqliteValue
-    | Row // for jsonObjectFrom from kysely/helpers/sqlite
-    | ReadonlyArray<Row>; // for jsonArrayFrom from kysely/helpers/sqlite
+    | Row // for evoluJsonObjectFrom
+    | ReadonlyArray<Row>; // for evoluJsonArrayFrom
 }
 
-// To preserve identity.
-export const emptyRows: ReadonlyArray<Row> = [];
+/**
+ * An improved Evolu version of Kysely's SQLite `jsonArrayFrom` helper.
+ *
+ * Kysely's `ParseJSONResultsPlugin` heuristically parses any result string that
+ * looks like JSON. Evolu instead prefixes JSON produced by these helpers with a
+ * per-runtime identifier and only parses values carrying that prefix, avoiding
+ * accidental parsing of ordinary string columns that merely happen to start
+ * with `{` or `[`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { evoluJsonArrayFrom } from "@evolu/common";
+ *
+ * const result = await db
+ *   .selectFrom("person")
+ *   .select((eb) => [
+ *     "id",
+ *     evoluJsonArrayFrom(
+ *       eb
+ *         .selectFrom("pet")
+ *         .select(["pet.id as pet_id", "pet.name"])
+ *         .whereRef("pet.owner_id", "=", "person.id")
+ *         .orderBy("pet.name"),
+ *     ).as("pets"),
+ *   ])
+ *   .execute();
+ *
+ * result[0]?.id;
+ * result[0]?.pets[0].pet_id;
+ * result[0]?.pets[0].name;
+ * ```
+ */
+export const evoluJsonArrayFrom = <O>(
+  expr: SelectQueryBuilderExpression<O>,
+): RawBuilder<Array<KyselySimplify<O>>> =>
+  kyselySqlBuilder`(select ${kyselySqlBuilder.lit(kyselyJsonIdentifier)} || coalesce(json_group_array(json_object(${kyselySqlBuilder.join(
+    getSqliteJsonObjectArgs(expr.toOperationNode(), "agg"),
+  )})), '[]') from ${expr} as agg)`;
+
+/**
+ * An improved Evolu version of Kysely's SQLite `jsonObjectFrom` helper.
+ *
+ * Kysely's `ParseJSONResultsPlugin` heuristically parses any result string that
+ * looks like JSON. Evolu instead prefixes JSON produced by these helpers with a
+ * per-runtime identifier and only parses values carrying that prefix, avoiding
+ * accidental parsing of ordinary string columns that merely happen to start
+ * with `{` or `[`.
+ *
+ * The subquery must only return one row.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { evoluJsonObjectFrom } from "@evolu/common";
+ *
+ * const result = await db
+ *   .selectFrom("person")
+ *   .select((eb) => [
+ *     "id",
+ *     evoluJsonObjectFrom(
+ *       eb
+ *         .selectFrom("pet")
+ *         .select(["pet.id as pet_id", "pet.name"])
+ *         .whereRef("pet.owner_id", "=", "person.id")
+ *         .where("pet.is_favorite", "=", true),
+ *     ).as("favorite_pet"),
+ *   ])
+ *   .execute();
+ *
+ * result[0]?.id;
+ * result[0]?.favorite_pet?.pet_id;
+ * result[0]?.favorite_pet?.name;
+ * ```
+ */
+export const evoluJsonObjectFrom = <O>(
+  expr: SelectQueryBuilderExpression<O>,
+): RawBuilder<KyselySimplify<O> | null> =>
+  kyselySqlBuilder`(select ${kyselySqlBuilder.lit(kyselyJsonIdentifier)} || json_object(${kyselySqlBuilder.join(
+    getSqliteJsonObjectArgs(expr.toOperationNode(), "obj"),
+  )}) from ${expr} as obj)`;
+
+/**
+ * An improved Evolu version of Kysely's SQLite `jsonBuildObject` helper.
+ *
+ * Kysely's `ParseJSONResultsPlugin` heuristically parses any result string that
+ * looks like JSON. Evolu instead prefixes JSON produced by these helpers with a
+ * per-runtime identifier and only parses values carrying that prefix, avoiding
+ * accidental parsing of ordinary string columns that merely happen to start
+ * with `{` or `[`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { evoluJsonBuildObject, kyselySql } from "@evolu/common";
+ *
+ * const result = await db
+ *   .selectFrom("person")
+ *   .select((eb) => [
+ *     "id",
+ *     evoluJsonBuildObject({
+ *       first: eb.ref("first_name"),
+ *       last: eb.ref("last_name"),
+ *       full: kyselySql<string>`first_name || ' ' || last_name`,
+ *     }).as("name"),
+ *   ])
+ *   .execute();
+ *
+ * result[0]?.id;
+ * result[0]?.name.first;
+ * result[0]?.name.last;
+ * result[0]?.name.full;
+ * ```
+ */
+export const evoluJsonBuildObject = <
+  O extends Record<string, Expression<unknown>>,
+>(
+  obj: O,
+): RawBuilder<
+  KyselySimplify<{
+    [K in keyof O]: O[K] extends Expression<infer V> ? V : never;
+  }>
+> =>
+  kyselySqlBuilder`${kyselySqlBuilder.lit(kyselyJsonIdentifier)} || json_object(${kyselySqlBuilder.join(
+    Object.keys(obj).flatMap((k) => [kyselySqlBuilder.lit(k), obj[k]]),
+  )})`;
+
+export const getJsonObjectArgs = (
+  node: SelectQueryNode,
+  table: string,
+): Array<Expression<unknown> | string> => {
+  const args: Array<Expression<unknown> | string> = [];
+
+  for (const { selection: s } of node.selections ?? []) {
+    if (ReferenceNode.is(s) && ColumnNode.is(s.column)) {
+      args.push(
+        colName(s.column.column.name),
+        colRef(table, s.column.column.name),
+      );
+    } else if (ColumnNode.is(s)) {
+      args.push(colName(s.column.name), colRef(table, s.column.name));
+    } else if (AliasNode.is(s) && IdentifierNode.is(s.alias)) {
+      args.push(colName(s.alias.name), colRef(table, s.alias.name));
+    } else {
+      throw new Error(`can't extract column names from the select query node`);
+    }
+  }
+
+  return args;
+};
 
 /** Rows returned by a query. */
 export type QueryRows<R extends Row = Row> = ReadonlyArray<
   Readonly<Simplify<R>>
 >;
 
-export type Queries<R extends Row = Row> = ReadonlyArray<Query<R>>;
+export type Queries<
+  S extends EvoluSchema = EvoluSchema,
+  R extends Row = Row,
+> = ReadonlyArray<Query<S, R>>;
 
 export type QueriesToQueryRows<Q extends Queries> = {
-  [P in keyof Q]: Q[P] extends Query<infer R> ? QueryRows<R> : never;
+  [P in keyof Q]: Q[P] extends Query<any, infer R> ? QueryRows<R> : never;
 };
 
 export type QueriesToQueryRowsPromises<Q extends Queries> = {
-  [P in keyof Q]: Q[P] extends Query<infer R> ? Promise<QueryRows<R>> : never;
+  [P in keyof Q]: Q[P] extends Query<any, infer R>
+    ? Promise<QueryRows<R>>
+    : never;
 };
 
-export type QueryRowsMap = ReadonlyMap<Query, ReadonlyArray<Row>>;
-
-export interface SubscribedQueries {
-  subscribe: (query: Query) => StoreSubscribe;
-
-  has: (query: Query) => boolean;
-
-  get: () => ReadonlyArray<Query>;
-}
-
-export const createSubscribedQueries = (
-  rowsStore: Store<QueryRowsMap>,
-): SubscribedQueries => {
-  const subscribedQueryMap = new Map<Query, number>();
-
-  const subscribedQueries: SubscribedQueries = {
-    subscribe: (query) => (listener) => {
-      subscribedQueryMap.set(query, (subscribedQueryMap.get(query) ?? 0) + 1);
-      const unsubscribe = rowsStore.subscribe(listener);
-      return () => {
-        const count = subscribedQueryMap.get(query);
-        if (count != null && count > 1) {
-          subscribedQueryMap.set(query, count - 1);
-        } else {
-          subscribedQueryMap.delete(query);
-        }
-        unsubscribe();
-      };
-    },
-
-    get: () => [...subscribedQueryMap.keys()],
-
-    has: (query) => subscribedQueryMap.has(query),
-  };
-
-  return subscribedQueries;
-};
-
-export interface GetQueryRowsCacheDep {
-  readonly getQueryRowsCache: GetQueryRowsCache;
-}
-
-export type GetQueryRowsCache = (tabId: Id) => QueryRowsCache;
-
-export interface QueryRowsCache {
-  readonly set: (
-    queriesRows: ReadonlyArray<readonly [Query, ReadonlyArray<SqliteRow>]>,
-  ) => void;
-  readonly get: () => QueryRowsMap;
-}
-
-export const createGetQueryRowsCache = (): GetQueryRowsCache => {
-  const tabQueryRowsCacheMap = new Map<Id, QueryRowsCache>();
-
-  return (tabId: Id) => {
-    let cache = tabQueryRowsCacheMap.get(tabId);
-    if (!cache) {
-      let queryRowsCache: QueryRowsMap = new Map();
-      cache = {
-        set: (queriesRows) => {
-          queryRowsCache = new Map([...queryRowsCache, ...queriesRows]);
-        },
-        get: () => queryRowsCache,
-      };
-      tabQueryRowsCacheMap.set(tabId, cache);
-    }
-    return cache;
-  };
-};
-
-export const loadQueries =
-  (deps: GetQueryRowsCacheDep & SqliteDep) =>
-  (
-    tabId: Id,
-    queries: ReadonlyArray<Query>,
-  ): Result<ReadonlyArray<QueryPatches>, SqliteError> => {
-    const queriesRows = [];
-
-    for (const query of queries) {
-      const sqlQuery = deserializeQuery(query);
-      const result = deps.sqlite.exec(sqlQuery);
-      if (!result.ok) return result;
-
-      queriesRows.push([query, result.value.rows] as const);
-      if (sqlQuery.options?.logExplainQueryPlan) {
-        explainSqliteQueryPlan(deps)(sqlQuery);
-      }
-    }
-
-    const queryRowsCache = deps.getQueryRowsCache(tabId);
-
-    const previousState = queryRowsCache.get();
-    queryRowsCache.set(queriesRows);
-
-    const currentState = queryRowsCache.get();
-
-    const queryPatchesArray = queries.map(
-      (query): QueryPatches => ({
-        query,
-        patches: makePatches(
-          previousState.get(query),
-          currentState.get(query) ?? emptyRows,
-        ),
-      }),
-    );
-    return ok(queryPatchesArray);
-  };
-
-export interface QueryPatches {
-  readonly query: Query;
-  readonly patches: ReadonlyArray<Patch>;
-}
+export type RowsByQueryMap<S extends EvoluSchema = EvoluSchema> = ReadonlyMap<
+  Query<S>,
+  ReadonlyArray<Row>
+>;
 
 export type Patch = ReplaceAllPatch | ReplaceAtPatch;
 
@@ -258,8 +279,10 @@ export const makePatches = (
   previousRows: ReadonlyArray<Row> | undefined,
   nextRows: ReadonlyArray<Row>,
 ): ReadonlyArray<Patch> => {
-  if (previousRows === undefined)
+  if (previousRows === undefined) {
     return [{ op: "replaceAll", value: nextRows }];
+  }
+
   // TODO: Detect prepend and append, it's cheap.
   if (previousRows.length !== nextRows.length) {
     return [{ op: "replaceAll", value: nextRows }];
@@ -322,10 +345,28 @@ export const applyPatches = (
  *
  * See: https://github.com/kysely-org/kysely/issues/1372#issuecomment-2702773948
  */
-export const kyselyJsonIdentifier = createId({
-  randomBytes: createRandomBytes(),
+export const kyselyJsonIdentifier = /*#__PURE__*/ createId({
+  randomBytes: /*#__PURE__*/ createRandomBytes(),
 });
 
+interface SelectQueryBuilderExpression<O> extends AliasableExpression<O> {
+  get isSelectQueryBuilder(): true;
+  toOperationNode(): SelectQueryNode;
+}
+
+const getSqliteJsonObjectArgs = (
+  node: SelectQueryNode,
+  table: string,
+): Array<Expression<unknown> | string> => {
+  try {
+    return getJsonObjectArgs(node, table);
+  } catch {
+    throw new Error(
+      "SQLite evoluJsonArrayFrom and evoluJsonObjectFrom can only handle explicit selections due to limitations of the json_object function. selectAll() is not allowed in the subquery.",
+    );
+  }
+};
+
 export const parseSqliteJsonArray = <T>(
   arr: ReadonlyArray<T>,
 ): ReadonlyArray<T> => {
@@ -338,7 +379,7 @@ export const parseSqliteJsonArray = <T>(
 
 const parse = (obj: unknown): unknown => {
   if (String.is(obj) && obj.startsWith(kyselyJsonIdentifier)) {
-    return JSON.parse(obj.slice(kyselyJsonIdentifier.length));
+    return parse(JSON.parse(obj.slice(kyselyJsonIdentifier.length)));
   }
 
   if (Array.isArray(obj)) {
@@ -361,3 +402,11 @@ const parseObject = (
   }
   return result as ReadonlyRecord<string, unknown>;
 };
+
+const colName = (col: string): Expression<unknown> =>
+  new ExpressionWrapper(ValueNode.createImmediate(col));
+
+const colRef = (table: string, col: string): Expression<unknown> =>
+  new ExpressionWrapper(
+    ReferenceNode.create(ColumnNode.create(col), TableNode.create(table)),
+  );