@evolu/common 8.0.0-next.5 → 8.0.0

package/src/Set.ts

@@ -8,33 +8,38 @@
  * Use {@link isNonEmptySet} to narrow to {@link NonEmptyReadonlySet} before
  * calling functions like {@link firstInSet} that require a non-empty set.
  *
- * ### Example
+ * ### Composing immutable and native operations
  *
  * ```ts
- * // Type guards
- * const set: ReadonlySet<number> = new Set([1, 2, 3]);
- * if (isNonEmptySet(set)) {
- *   firstInSet(set);
- * }
- *
- * // Immutable transformations
- * const added = addToSet(new Set([1, 2]), 3); // Set {1, 2, 3}
- * const removed = deleteFromSet(new Set([1, 2, 3]), 2); // Set {1, 3}
- * const mapped = mapSet(new Set([1, 2, 3]), (x) => x * 2); // Set {2, 4, 6}
- * const filtered = filterSet(new Set([1, 2, 3, 4]), (x) => x % 2 === 0); // Set {2, 4}
- *
- * // Set operations
- * const union = unionSets(new Set([1, 2]), new Set([2, 3])); // Set {1, 2, 3}
- * const intersection = intersectSets(new Set([1, 2]), new Set([2, 3])); // Set {2}
- * const difference = differenceSets(new Set([1, 2, 3]), new Set([2])); // Set {1, 3}
+ * import {
+ *   addToSet,
+ *   deleteFromSet,
+ *   filterSet,
+ *   firstInSet,
+ *   isNonEmptySet,
+ *   mapSet,
+ * } from "@evolu/common";
+ *
+ * const values = addToSet(new Set([1, 2]), 3);
+ * const withoutOne = deleteFromSet(values, 1);
+ * const doubled = mapSet(withoutOne, (x) => x * 2);
+ * const atLeastFour = filterSet(doubled, (x) => x >= 4);
+ *
+ * // Evolu's readonly results compose with native Set operations.
+ * const union = atLeastFour.union(new Set([6, 8]));
+ * const intersection = union.intersection(new Set([4, 6, 8, 10]));
+ * const difference = intersection.difference(new Set([4]));
+ *
+ * if (!isNonEmptySet(difference)) throw new Error("Expected values");
+ * expect(firstInSet(difference)).toBe(6);
  * ```
  *
  * @module
  */
 
-import type { NonEmptyReadonlyArray } from "./Array.js";
-import type { Brand } from "./Brand.js";
-import type { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
+import type { NonEmptyReadonlyArray } from "./Array.ts";
+import type { Brand } from "./Brand.ts";
+import type { PredicateWithIndex, RefinementWithIndex } from "./Types.ts";
 
 /**
  * An empty readonly set.
@@ -50,11 +55,17 @@ export const emptySet: ReadonlySet<never> = /*#__PURE__*/ new Set();
  *
  * Preserves non-empty type when the input array is non-empty.
  *
- * ### Example
+ * ### Preserving non-empty inputs
  *
  * ```ts
- * createSet([1, 2, 3]); // NonEmptyReadonlySet<number>
- * createSet([] as ReadonlyArray<number>); // ReadonlySet<number>
+ * import { createSet, type NonEmptyReadonlySet } from "@evolu/common";
+ *
+ * const values = createSet([1, 2, 3]);
+ * const empty = createSet([] as ReadonlyArray<number>);
+ *
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlySet<number>>();
+ * expectTypeOf(empty).toEqualTypeOf<ReadonlySet<number>>();
+ * expect(values).toEqual(new Set([1, 2, 3]));
  * ```
  *
  * @group Constructors
@@ -94,13 +105,16 @@ export type NonEmptyReadonlySet<T> = ReadonlySet<T> & Brand<"NonEmpty">;
  * negated guard is better than `.size === 0` for early returns because
  * TypeScript narrows the type after the check.
  *
- * ### Example
+ * ### Narrowing before access
  *
  * ```ts
+ * import { isNonEmptySet, type NonEmptyReadonlySet } from "@evolu/common";
+ *
  * const set: ReadonlySet<number> = new Set([1, 2, 3]);
- * if (isNonEmptySet(set)) {
- *   firstInSet(set); // set is NonEmptyReadonlySet<number>
- * }
+ * if (!isNonEmptySet(set)) throw new Error("Expected a non-empty set");
+ *
+ * expectTypeOf(set).toEqualTypeOf<NonEmptyReadonlySet<number>>();
+ * expect(set.size).toBe(3);
  * ```
  *
  * @group Type guards
@@ -115,11 +129,18 @@ export const isNonEmptySet = <T>(
  * If the item already exists, returns a new set with the same elements (still a
  * new reference for change detection).
  *
- * ### Example
+ * ### Adding without mutation
  *
  * ```ts
- * addToSet(new Set([1, 2]), 3); // Set {1, 2, 3}
- * addToSet(new Set([1, 2]), 2); // Set {1, 2} (new reference)
+ * import { addToSet, type NonEmptyReadonlySet } from "@evolu/common";
+ *
+ * const original: ReadonlySet<number> = new Set([1, 2]);
+ * const added = addToSet(original, 3);
+ * const unchanged = addToSet(original, 2);
+ *
+ * expectTypeOf(added).toEqualTypeOf<NonEmptyReadonlySet<number>>();
+ * expect(added).toEqual(new Set([1, 2, 3]));
+ * expect(unchanged).not.toBe(original);
  * ```
  *
  * @group Transformations
@@ -139,11 +160,14 @@ export const addToSet = <T>(
  * If the item doesn't exist, returns a new set with the same elements (still a
  * new reference for change detection).
  *
- * ### Example
+ * ### Deleting without mutation
  *
  * ```ts
- * deleteFromSet(new Set([1, 2, 3]), 2); // Set {1, 3}
- * deleteFromSet(new Set([1, 2]), 5); // Set {1, 2} (new reference)
+ * import { deleteFromSet } from "@evolu/common";
+ *
+ * const original = new Set([1, 2, 3]);
+ * expect(deleteFromSet(original, 2)).toEqual(new Set([1, 3]));
+ * expect(deleteFromSet(original, 5)).not.toBe(original);
  * ```
  *
  * @group Transformations
@@ -165,11 +189,22 @@ export const deleteFromSet = <T>(
  * Note: If the mapper produces duplicate values, the resulting set will have
  * fewer elements.
  *
- * ### Example
+ * ### Mapping non-empty sets
  *
  * ```ts
- * mapSet(new Set([1, 2, 3]), (x) => x * 2); // Set {2, 4, 6}
- * mapSet(new Set([1, 2, 3]), (x) => x % 2); // Set {1, 0} (duplicates merged)
+ * import {
+ *   createSet,
+ *   mapSet,
+ *   type NonEmptyReadonlySet,
+ * } from "@evolu/common";
+ *
+ * const original = createSet([1, 2, 3]);
+ * const doubled = mapSet(original, (x) => x * 2);
+ * const parity = mapSet(original, (x) => x % 2);
+ *
+ * expectTypeOf(doubled).toEqualTypeOf<NonEmptyReadonlySet<number>>();
+ * expect(doubled).toEqual(new Set([2, 4, 6]));
+ * expect(parity).toEqual(new Set([1, 0]));
  * ```
  *
  * @group Transformations
@@ -201,10 +236,21 @@ export function mapSet<T, U>(
  * When used with a refinement function (with `value is Type` syntax),
  * TypeScript will narrow the result type.
  *
- * ### Example
+ * ### Filtering and refining
  *
  * ```ts
- * filterSet(new Set([1, 2, 3, 4, 5]), (x) => x % 2 === 0); // Set {2, 4}
+ * import { filterSet } from "@evolu/common";
+ *
+ * const evens = filterSet(new Set([1, 2, 3, 4, 5]), (x) => x % 2 === 0);
+ * expect(evens).toEqual(new Set([2, 4]));
+ *
+ * const mixed: ReadonlySet<string | number> = new Set([1, "a", 2, "b"]);
+ * const strings = filterSet(
+ *   mixed,
+ *   (value): value is string => typeof value === "string",
+ * );
+ * expectTypeOf(strings).toEqualTypeOf<ReadonlySet<string>>();
+ * expect(strings).toEqual(new Set(["a", "b"]));
  * ```
  *
  * @group Transformations
@@ -235,10 +281,13 @@ export function filterSet<T>(
 /**
  * Returns the first element of a non-empty set (by insertion order).
  *
- * ### Example
+ * ### Reading the first value
  *
  * ```ts
- * firstInSet(new Set(["a", "b", "c"])); // "a"
+ * import { createSet, firstInSet } from "@evolu/common";
+ *
+ * const set = createSet(["a", "b", "c"]);
+ * expect(firstInSet(set)).toBe("a");
  * ```
  *
  * @group Accessors

package/src/Sqlite.ts

@@ -4,30 +4,35 @@
  * @module
  */
 
-import { assertNotDisposed } from "./Assert.js";
-import type { Brand } from "./Brand.js";
-import { bytesToHex, hexToBytes } from "./Buffer.js";
-import type { EncryptionKey } from "./Crypto.js";
-import type { Eq } from "./Eq.js";
-import { createEqObject, eqArrayNumber, eqString } from "./Eq.js";
-import { createRecord, objectToEntries } from "./Object.js";
-import type { Result } from "./Result.js";
-import { ok } from "./Result.js";
-import type { Run, Task } from "./Task.js";
-import { testCreateRun, type TestDeps } from "./Test.js";
-import type { InferType, Name, Typed } from "./Type.js";
+import type { Brand } from "./Brand.ts";
+import { bytesToHex, hexToBytes } from "./Buffer.ts";
+import type { EncryptionKey } from "./Crypto.ts";
+import type { Eq } from "./Eq.ts";
+import { createEqObject, eqArrayNumber, eqString } from "./Eq.ts";
+import { disposable } from "./Function.ts";
+import { createMutableRecord, objectToEntries } from "./Object.ts";
+import type { Result } from "./Result.ts";
+import { ok } from "./Result.ts";
+import { testCreateRun, type Task, type TestRunDep } from "./Task.ts";
 import {
   array,
+  type ArrayType,
+  type InferType,
+  type Name,
   Null,
   Number,
   object,
+  type ObjectType,
   record,
+  type RecordType,
   set,
+  type SetType,
   String,
   testName,
+  type Typed,
   Uint8Array,
   union,
-} from "./Type.js";
+} from "./Type.ts";
 
 /**
  * Platform-agnostic SQLite wrapping a {@link SqliteDriver}.
@@ -96,7 +101,7 @@ export const SqliteValue = /*#__PURE__*/ union(
   Number,
   Uint8Array,
 );
-export type SqliteValue = typeof SqliteValue.Type;
+export type SqliteValue = typeof SqliteValue.Output;
 
 /** Equality comparison for {@link SqliteValue}. */
 export const eqSqliteValue: Eq<SqliteValue> = (x, y) =>
@@ -239,91 +244,81 @@ export const createSqlite =
     const console = run.deps.console.child("sql");
     await using disposer = new AsyncDisposableStack();
 
-    const driverResult = await run(createSqliteDriver(name, options));
-    if (!driverResult.ok) return driverResult;
-    const driver = disposer.use(driverResult.value);
+    const driver = disposer.use(
+      await run.ok(createSqliteDriver(name, options)),
+    );
     console.debug("SQLite driver created");
 
-    const disposables = disposer.move();
-
-    const sqlite: Sqlite = {
-      exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => {
-        assertNotDisposed(disposables);
-        console.debug({ query });
-
-        const label =
-          query.options?.logQueryExecutionTime &&
-          `SqliteQueryExecutionTime ${query.sql}`;
-
-        if (label) console.time(label);
-        const result = driver.exec(query);
-        if (label) console.timeEnd(label);
-
-        if (query.options?.logExplainQueryPlan) {
-          const result = driver.exec({
-            ...query,
-            sql: `EXPLAIN QUERY PLAN ${query.sql}` as SafeSql,
-          });
-          console.log("[logExplainQueryPlan]", query);
-          console.log(
-            drawSqliteQueryPlan(
-              result.rows as unknown as Array<SqliteQueryPlanRow>,
-            ),
-          );
-        }
-
-        console.debug({ result });
-        return result as SqliteExecResult<R>;
-      },
-
-      transaction: ((callback: () => Result<unknown, unknown> | void) => {
-        assertNotDisposed(disposables);
-        console.debug("begin");
-        driver.exec(sql`begin;`);
-
-        using rollback = new DisposableStack();
-        let shouldRollback = true;
-        rollback.defer(() => {
-          if (!shouldRollback) return;
-          console.debug("rollback");
-          driver.exec(sql`rollback;`);
-        });
-
-        const result = callback();
-        if (result != null && !result.ok) return result;
-
-        console.debug("commit");
-        driver.exec(sql`commit;`);
-        shouldRollback = false;
-
-        return result;
-      }) as SqliteTransaction,
-
-      export: () => {
-        assertNotDisposed(disposables);
-        return driver.export();
-      },
-
-      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
-    };
-
-    return ok(sqlite);
+    return ok(
+      disposable<Sqlite>(
+        {
+          exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => {
+            console.debug({ query });
+
+            const label =
+              query.options?.logQueryExecutionTime &&
+              `SqliteQueryExecutionTime ${query.sql}`;
+
+            if (label) console.time(label);
+            const result = driver.exec(query);
+            if (label) console.timeEnd(label);
+
+            if (query.options?.logExplainQueryPlan) {
+              const result = driver.exec({
+                ...query,
+                sql: `EXPLAIN QUERY PLAN ${query.sql}` as SafeSql,
+              });
+              console.log("[logExplainQueryPlan]", query);
+              console.log(
+                drawSqliteQueryPlan(
+                  result.rows as unknown as Array<SqliteQueryPlanRow>,
+                ),
+              );
+            }
+
+            console.debug({ result });
+            return result as SqliteExecResult<R>;
+          },
+
+          transaction: ((callback: () => Result<unknown, unknown> | void) => {
+            console.debug("begin");
+            driver.exec(sql`begin;`);
+
+            using rollback = new DisposableStack();
+            let shouldRollback = true;
+            rollback.defer(() => {
+              if (!shouldRollback) return;
+              console.debug("rollback");
+              driver.exec(sql`rollback;`);
+            });
+
+            const result = callback();
+            if (result != null && !result.ok) return result;
+
+            console.debug("commit");
+            driver.exec(sql`commit;`);
+            shouldRollback = false;
+
+            return result;
+          }) as SqliteTransaction,
+
+          export: () => driver.export(),
+        },
+        disposer,
+      ),
+    );
   };
 
 /** Creates a test setup with a in-memory {@link Sqlite}. */
 export const testSetupSqlite = async (
   deps: CreateSqliteDriverDep,
 ): Promise<
-  AsyncDisposable &
-    SqliteDep & {
-      readonly run: Run<TestDeps & CreateSqliteDriverDep & SqliteDep>;
-      readonly sqlite: Sqlite;
-    }
+  AsyncDisposable & SqliteDep & TestRunDep<CreateSqliteDriverDep & SqliteDep>
 > => {
   await using disposer = new AsyncDisposableStack();
   const run = disposer.use(testCreateRun(deps));
   const sqlite = disposer.use(
-    await run.orThrow(createSqlite(testName, { mode: "memory" })),
+    await run.ok(createSqlite(testName, { mode: "memory" })),
   );
   const runWithSqlite = disposer.use(run.create({ ...run.deps, sqlite }));
   const disposables = disposer.move();
@@ -394,23 +389,21 @@ export const createPreparedStatementsCache = <P>(
     }
   });
 
-  const disposables = disposer.move();
-
-  return {
-    get: (query, alwaysPrepare) => {
-      assertNotDisposed(disposables);
-      if (alwaysPrepare !== true && !query.options?.prepare)
-        return null as never;
-      let statement = statementsBySql.get(query.sql);
-      if (!statement) {
-        statement = factory(query.sql);
-        statementsBySql.set(query.sql, statement);
-      }
-      return statement;
+  return disposable<PreparedStatements<P>>(
+    {
+      get: (query, alwaysPrepare) => {
+        if (alwaysPrepare !== true && !query.options?.prepare)
+          return null as never;
+        let statement = statementsBySql.get(query.sql);
+        if (!statement) {
+          statement = factory(query.sql);
+          statementsBySql.set(query.sql, statement);
+        }
+        return statement;
+      },
     },
-
-    [Symbol.dispose]: () => disposables.dispose(),
-  };
+    disposer,
+  );
 };
 
 /** A double-quoted SQL identifier for safe column or table name interpolation. */
@@ -439,27 +432,32 @@ export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
  * ### Example
  *
  * ```ts
+ * import { sql } from "@evolu/common";
+ *
  * const id = 42;
  * const name = "Alice";
- *
- * const result = sqlite.exec(sql`
- *   select *
- *   from users
- *   where id = ${id} and name = ${name};
- * `);
- *
- * // For identifiers
+ * const select = sql`
+ *   select * from users where id = ${id} and name = ${name};
+ * `;
  * const tableName = "users";
- * sqlite.exec(sql`
+ * const createTable = sql`
  *   create table ${sql.identifier(tableName)} (
  *     "id" text primary key,
  *     "name" text not null
  *   );
- * `);
- *
- * // For raw SQL (use with caution)
+ * `;
+ * // Use sql.raw only with trusted SQL fragments.
  * const orderBy = "created_at desc";
- * sqlite.exec(sql`select * from users order by ${sql.raw(orderBy)};`);
+ * const ordered = sql`select * from users order by ${sql.raw(orderBy)};`;
+ *
+ * expect(select).toEqual({
+ *   sql: "select * from users where id = ? and name = ?;",
+ *   parameters: [42, "Alice"],
+ * });
+ * expect(createTable.sql).toContain('create table "users"');
+ * expect(ordered.sql).toBe(
+ *   "select * from users order by created_at desc;",
+ * );
  * ```
  *
  * ## TIP
@@ -515,7 +513,10 @@ sql.prepared = (
 };
 
 /** Index metadata stored in `sqlite_master` for a {@link Sqlite} database. */
-export const SqliteIndex = /*#__PURE__*/ object({ name: String, sql: String });
+export const SqliteIndex: ObjectType<{
+  readonly name: typeof String;
+  readonly sql: typeof String;
+}> = /*#__PURE__*/ object({ name: String, sql: String });
 export interface SqliteIndex extends InferType<typeof SqliteIndex> {}
 
 /** {@link Eq} instance for {@link SqliteIndex}. */
@@ -529,7 +530,10 @@ export const eqSqliteIndex: Eq<SqliteIndex> = /*#__PURE__*/ createEqObject({
  *
  * Includes table-column mappings and user-visible indexes.
  */
-export const SqliteSchema = /*#__PURE__*/ object({
+export const SqliteSchema: ObjectType<{
+  readonly tables: RecordType<typeof String, SetType<typeof String>>;
+  readonly indexes: ArrayType<typeof SqliteIndex>;
+}> = /*#__PURE__*/ object({
   tables: /*#__PURE__*/ record(String, /*#__PURE__*/ set(String)),
   indexes: /*#__PURE__*/ array(SqliteIndex),
 });
@@ -547,7 +551,7 @@ export const getSqliteSchema =
      */
     excludeIndexNamePrefix?: string;
   } = {}): SqliteSchema => {
-    const tables = createRecord<string, Set<string>>();
+    const tables = createMutableRecord<string, Set<string>>();
 
     const tableAndColumnInfoRows = deps.sqlite.exec<{
       tableName: string;
@@ -570,6 +574,7 @@ export const getSqliteSchema =
         ? ` and name not like '${excludeIndexNamePrefix.replaceAll("'", "''")}%'`
         : "";
 
+    // prettier-ignore
     const indexesRows = deps.sqlite.exec<{ name: string; sql: string }>(
       sql`
         select name, sql
@@ -581,19 +586,17 @@ export const getSqliteSchema =
       `,
     );
 
-    const indexes = indexesRows.rows.map(
-      (row): SqliteIndex => ({
-        name: row.name,
-        /**
-         * SQLite returns "CREATE INDEX" for "create index" for some reason.
-         * Other keywords remain unchanged. We have to normalize the casing for
-         * schema comparison manually.
-         */
-        sql: row.sql
-          .replace("CREATE INDEX", "create index")
-          .replace("CREATE UNIQUE INDEX", "create unique index"),
-      }),
-    );
+    const indexes = indexesRows.rows.map((row): SqliteIndex => ({
+      name: row.name,
+      /**
+       * SQLite returns "CREATE INDEX" for "create index" for some reason. Other
+       * keywords remain unchanged. We have to normalize the casing for schema
+       * comparison manually.
+       */
+      sql: row.sql
+        .replace("CREATE INDEX", "create index")
+        .replace("CREATE UNIQUE INDEX", "create unique index"),
+    }));
 
     return { tables, indexes };
   };
@@ -649,7 +652,7 @@ export const getSqliteSnapshot = (deps: SqliteDep): SqliteSnapshot => {
  *   converting between JavaScript booleans and SQLite boolean values.
  */
 export const SqliteBoolean = /*#__PURE__*/ union(0, 1);
-export type SqliteBoolean = typeof SqliteBoolean.Type;
+export type SqliteBoolean = typeof SqliteBoolean.Output;
 
 /**
  * Represents the {@link SqliteBoolean} value for `true`.
@@ -671,8 +674,9 @@ export const sqliteFalse = 0;
  * ### Example
  *
  * ```ts
- * const isActive = true;
- * const sqlValue = booleanToSqliteBoolean(isActive); // Returns 1
+ * import { booleanToSqliteBoolean } from "@evolu/common";
+ *
+ * expect(booleanToSqliteBoolean(true)).toBe(1);
  * ```
  */
 export const booleanToSqliteBoolean = (value: boolean): SqliteBoolean =>
@@ -684,8 +688,9 @@ export const booleanToSqliteBoolean = (value: boolean): SqliteBoolean =>
  * ### Example
  *
  * ```ts
- * const sqlValue: SqliteBoolean = 1;
- * const bool = sqliteBooleanToBoolean(sqlValue); // Returns true
+ * import { sqliteBooleanToBoolean } from "@evolu/common";
+ *
+ * expect(sqliteBooleanToBoolean(1)).toBe(true);
  * ```
  */
 export const sqliteBooleanToBoolean = (value: SqliteBoolean): boolean =>