@evolu/common 5.4.8 → 6.0.0

package/src/Evolu/Public.ts

@@ -0,0 +1,43 @@
+/**
+ * 💾
+ *
+ * @module
+ */
+
+export { createEvolu } from "./Evolu.js";
+export type {
+  Evolu,
+  EvoluConfigWithInitialData,
+  EvoluDeps,
+  EvoluError,
+} from "./Evolu.js";
+export * from "./Owner.js";
+export { binaryIdToId, idToBinaryId } from "./Protocol.js";
+export type { BinaryId } from "./Protocol.js";
+export * as kysely from "./PublicKysely.js";
+export type { InferRow, Query, QueryRows, Row } from "./Query.js";
+export { formatValidMutationSizeError } from "./Schema.js";
+export type { EvoluSchema, ValidMutationSizeError } from "./Schema.js";
+export type {
+  NetworkError,
+  PaymentRequiredError,
+  ServerError,
+  SyncState,
+  SyncStateInitial,
+  SyncStateIsNotSynced,
+  SyncStateIsSynced,
+  SyncStateIsSyncing,
+} from "./Sync.js";
+export {
+  binaryTimestampToTimestamp,
+  Timestamp,
+  timestampToBinaryTimestamp,
+} from "./Timestamp.js";
+export type {
+  BinaryTimestamp,
+  TimestampCounterOverflowError,
+  TimestampDriftError,
+  TimestampDuplicateNodeError,
+  TimestampError,
+  TimestampTimeOutOfRangeError,
+} from "./Timestamp.js";

package/src/Evolu/PublicKysely.ts

@@ -0,0 +1,240 @@
+import {
+  AliasableExpression,
+  AliasNode,
+  ColumnNode,
+  Expression,
+  ExpressionWrapper,
+  IdentifierNode,
+  RawBuilder,
+  ReferenceNode,
+  SelectQueryNode,
+  Simplify,
+  sql,
+  TableNode,
+  ValueNode,
+} from "kysely";
+import { kyselyJsonIdentifier } from "./Diff.js";
+
+export { sql } from "kysely";
+export type { NotNull } from "kysely";
+
+/**
+ * A SQLite helper for aggregating a subquery into a JSON array.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import { kysely } from "@evolu/common";
+ *
+ * // TODO: Update for Evolu
+ * const result = await db
+ *   .selectFrom("person")
+ *   .select((eb) => [
+ *     "id",
+ *     kysely
+ *       .jsonArrayFrom(
+ *         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;
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "id", (
+ *   select coalesce(json_group_array(json_object(
+ *     'pet_id', "agg"."pet_id",
+ *     'name', "agg"."name"
+ *   )), '[]') from (
+ *     select "pet"."id" as "pet_id", "pet"."name"
+ *     from "pet"
+ *     where "pet"."owner_id" = "person"."id"
+ *     order by "pet"."name"
+ *   ) as "agg"
+ * ) as "pets"
+ * from "person"
+ * ```
+ */
+// SQL formatting breaks generated SQL for some reason.
+// prettier-ignore
+export function jsonArrayFrom<O>(
+    expr: SelectQueryBuilderExpression<O>,
+  ): RawBuilder<Array<Simplify<O>>> {
+    return sql`(select ${sql.lit(kyselyJsonIdentifier)} || coalesce(json_group_array(json_object(${sql.join(
+      getSqliteJsonObjectArgs(expr.toOperationNode(), 'agg'),
+    )})), '[]') from ${expr} as agg)`
+  }
+
+/**
+ * A SQLite helper for turning a subquery into a JSON object.
+ *
+ * The subquery must only return one row.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import { kysely } from "@evolu/common";
+ *
+ * // TODO: Update for Evolu
+ * const result = await db
+ *   .selectFrom("person")
+ *   .select((eb) => [
+ *     "id",
+ *     jsonObjectFrom(
+ *       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;
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "id", (
+ *   select json_object(
+ *     'pet_id', "obj"."pet_id",
+ *     'name', "obj"."name"
+ *   ) from (
+ *     select "pet"."id" as "pet_id", "pet"."name"
+ *     from "pet"
+ *     where "pet"."owner_id" = "person"."id"
+ *     and "pet"."is_favorite" = ?
+ *   ) as obj
+ * ) as "favorite_pet"
+ * from "person";
+ * ```
+ */
+// SQL formatting breaks generated SQL for some reason.
+// prettier-ignore
+export function jsonObjectFrom<O>(
+    expr: SelectQueryBuilderExpression<O>,
+  ): RawBuilder<Simplify<O> | null> {
+    return sql`(select ${sql.lit(kyselyJsonIdentifier)} || json_object(${sql.join(
+      getSqliteJsonObjectArgs(expr.toOperationNode(), 'obj'),
+    )}) from ${expr} as obj)`
+  }
+
+/**
+ * The SQLite `json_object` function.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import { kysely } from "@evolu/common";
+ *
+ * // TODO: Update for Evolu
+ * const result = await db
+ *   .selectFrom("person")
+ *   .select((eb) => [
+ *     "id",
+ *     kysely
+ *       .jsonBuildObject({
+ *         first: eb.ref("first_name"),
+ *         last: eb.ref("last_name"),
+ *         full: kysely.sql<string>`first_name || ' ' || last_name`,
+ *       })
+ *       .as("name"),
+ *   ])
+ *   .execute();
+ *
+ * result[0]?.id;
+ * result[0]?.name.first;
+ * result[0]?.name.last;
+ * result[0]?.name.full;
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "id", json_object(
+ *   'first', first_name,
+ *   'last', last_name,
+ *   'full', "first_name" || ' ' || "last_name"
+ * ) as "name"
+ * from "person"
+ * ```
+ */
+// SQL formatting breaks generated SQL for some reason.
+// prettier-ignore
+export function jsonBuildObject<O extends Record<string, Expression<unknown>>>(
+    obj: O,
+  ): RawBuilder<
+    Simplify<{
+      [K in keyof O]: O[K] extends Expression<infer V> ? V : never
+    }>
+  > {
+    return sql`${sql.lit(kyselyJsonIdentifier)} || json_object(${sql.join(
+      Object.keys(obj).flatMap((k) => [sql.lit(k), obj[k]]),
+    )})`
+  }
+
+interface SelectQueryBuilderExpression<O> extends AliasableExpression<O> {
+  get isSelectQueryBuilder(): true;
+  toOperationNode(): SelectQueryNode;
+}
+
+function getSqliteJsonObjectArgs(
+  node: SelectQueryNode,
+  table: string,
+): Array<Expression<unknown> | string> {
+  try {
+    return getJsonObjectArgs(node, table);
+  } catch {
+    throw new Error(
+      "SQLite jsonArrayFrom and jsonObjectFrom functions can only handle explicit selections due to limitations of the json_object function. selectAll() is not allowed in the subquery.",
+    );
+  }
+}
+
+export function getJsonObjectArgs(
+  node: SelectQueryNode,
+  table: string,
+): Array<Expression<unknown> | string> {
+  const args: Array<Expression<unknown> | string> = [];
+  args.push(kyselyJsonIdentifier, kyselyJsonIdentifier);
+
+  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;
+}
+
+function colName(col: string): Expression<unknown> {
+  return new ExpressionWrapper(ValueNode.createImmediate(col));
+}
+
+function colRef(table: string, col: string): Expression<unknown> {
+  return new ExpressionWrapper(
+    ReferenceNode.create(ColumnNode.create(col), TableNode.create(table)),
+  );
+}

package/src/Evolu/Query.ts

@@ -0,0 +1,167 @@
+import { bytesToHex, hexToBytes } from "../Buffer.js";
+import { objectToEntries } from "../Object.js";
+import {
+  SafeSql,
+  SqliteQuery,
+  SqliteQueryOptions,
+  SqliteRow,
+  SqliteValue,
+} from "../Sqlite.js";
+import { Store, StoreSubscribe } from "../Store.js";
+import { Brand, Simplify } from "../Types.js";
+
+/**
+ * A type-safe SQL query.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const allTodos = evolu.createQuery((db) =>
+ *   db.selectFrom("todo").selectAll(),
+ * );
+ * type AllTodosRow = typeof allTodos.Row;
+ * ```
+ */
+export type Query<R extends Row = Row> = string &
+  Brand<"Query"> & {
+    /**
+     * A shorthand for {@link InferRow}.
+     *
+     * ### Example
+     *
+     * ```ts
+     * const allTodos = evolu.createQuery((db) =>
+     *   db.selectFrom("todo").selectAll(),
+     * );
+     * type AllTodosRow = typeof allTodos.Row;
+     * ```
+     */
+    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).sort(([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 interface Row {
+  readonly [key: string]:
+    | SqliteValue
+    | Row // for jsonObjectFrom from kysely/helpers/sqlite
+    | ReadonlyArray<Row>; // for jsonArrayFrom from kysely/helpers/sqlite
+}
+
+// To preserve identity.
+export const emptyRows: ReadonlyArray<Row> = [];
+
+/** 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 QueriesToQueryRows<Q extends Queries> = {
+  [P in keyof Q]: Q[P] extends Query<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;
+};
+
+export type QueryRowsMap = ReadonlyMap<Query, ReadonlyArray<Row>>;
+
+export interface QueryRowsCache {
+  readonly set: (
+    queriesRows: ReadonlyArray<readonly [Query, ReadonlyArray<SqliteRow>]>,
+  ) => void;
+  readonly get: () => QueryRowsMap;
+}
+
+export const createQueryRowsCache = (): QueryRowsCache => {
+  let queryRowsCache: QueryRowsMap = new Map();
+
+  const cache: QueryRowsCache = {
+    set: (queriesRows) => {
+      queryRowsCache = new Map([...queryRowsCache, ...queriesRows]);
+    },
+    get: () => queryRowsCache,
+  };
+
+  return cache;
+};
+
+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;
+};

package/src/Evolu/Relay.ts

@@ -0,0 +1,142 @@
+import { isNonEmptyReadonlyArray } from "../Array.js";
+import { ConsoleConfig } from "../Console.js";
+import { eqArrayNumber } from "../Eq.js";
+import { ok, Result } from "../Result.js";
+import { sql, SqliteError } from "../Sqlite.js";
+import { SimpleName } from "../Type.js";
+import { OwnerId, WriteKey } from "./Owner.js";
+import { EncryptedDbChange, Storage } from "./Protocol.js";
+import {
+  createSqliteStorageBase,
+  CreateSqliteStorageBaseOptions,
+  SqliteStorageDeps,
+} from "./Storage.js";
+import { timestampToBinaryTimestamp } from "./Timestamp.js";
+
+export interface Relay extends Disposable {}
+
+export interface RelayConfig extends ConsoleConfig {
+  readonly name?: SimpleName;
+}
+
+export const createRelayStorage =
+  (deps: SqliteStorageDeps) =>
+  (options: CreateSqliteStorageBaseOptions): Result<Storage, SqliteError> => {
+    const sqliteStorageBase = createSqliteStorageBase(deps)(options);
+    if (!sqliteStorageBase.ok) return sqliteStorageBase;
+
+    for (const query of [
+      sql`
+        create table if not exists evolu_writeKey (
+          "ownerId" blob not null,
+          "writeKey" blob not null,
+          primary key ("ownerId")
+        )
+        strict;
+      `,
+
+      sql`
+        create table if not exists evolu_message (
+          "ownerId" blob not null,
+          "timestamp" blob not null,
+          "change" blob not null,
+          primary key ("ownerId", "timestamp")
+        )
+        strict;
+      `,
+    ]) {
+      const result = deps.sqlite.exec(query);
+      if (!result.ok) return result;
+    }
+
+    return ok({
+      ...sqliteStorageBase.value,
+
+      /**
+       * Lazily authorizes the initiator's {@link WriteKey} for the given
+       * {@link OwnerId}.
+       *
+       * - If the {@link OwnerId} does not exist, it is created and associated with
+       *   the provided write key.
+       * - If the {@link OwnerId} exists, the provided write key is compared to the
+       *   stored key.
+       */
+      validateWriteKey: (ownerId, writeKey) => {
+        const selectWriteKey = deps.sqlite.exec<{ writeKey: WriteKey }>(sql`
+          select writeKey
+          from evolu_writeKey
+          where ownerId = ${ownerId};
+        `);
+        if (!selectWriteKey.ok) {
+          options.onStorageError(selectWriteKey.error);
+          return false;
+        }
+
+        const { rows } = selectWriteKey.value;
+
+        if (!isNonEmptyReadonlyArray(rows)) {
+          const insertWriteKey = deps.sqlite.exec(sql`
+            insert into evolu_writeKey (ownerId, writeKey)
+            values (${ownerId}, ${writeKey});
+          `);
+          if (!insertWriteKey.ok) {
+            options.onStorageError(insertWriteKey.error);
+            return false;
+          }
+
+          return true;
+        }
+
+        return eqArrayNumber(rows[0].writeKey, writeKey);
+      },
+
+      writeMessages: (ownerId, messages) => {
+        const result = deps.sqlite.transaction(() => {
+          for (const message of messages) {
+            const insertTimestampResult =
+              sqliteStorageBase.value.insertTimestamp(
+                ownerId,
+                timestampToBinaryTimestamp(message.timestamp),
+              );
+            if (!insertTimestampResult.ok) return insertTimestampResult;
+
+            const insertMessage = deps.sqlite.exec(sql`
+              insert into evolu_message ("ownerId", "timestamp", "change")
+              values
+                (
+                  ${ownerId},
+                  ${timestampToBinaryTimestamp(message.timestamp)},
+                  ${message.change}
+                )
+              on conflict do nothing;
+            `);
+            if (!insertMessage.ok) return insertMessage;
+          }
+          return ok();
+        });
+
+        if (!result.ok) {
+          options.onStorageError(result.error);
+          return false;
+        }
+
+        return true;
+      },
+
+      readDbChange: (ownerId, timestamp) => {
+        const result = deps.sqlite.exec<{
+          change: EncryptedDbChange;
+        }>(sql`
+          select "change"
+          from evolu_message
+          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
+        `);
+        if (!result.ok) {
+          options.onStorageError(result.error);
+          return null;
+        }
+
+        return result.value.rows[0]?.change;
+      },
+    });
+  };