@evolu/common 8.0.0-next.3 → 8.0.0-next.5

package/src/Resource.ts

@@ -113,21 +113,21 @@ export const createResourceRef = <T extends Resource, D>(
   unabortable<ResourceRef<T, D>, never, D>(async (run) => {
     const resourceRefRun = run.create();
 
-    await using stack = new AsyncDisposableStack();
-    stack.use(resourceRefRun);
+    await using disposer = new AsyncDisposableStack();
+    disposer.use(resourceRefRun);
 
     const initial = await resourceRefRun(create);
     if (!initial.ok) return initial;
 
     let current = createOwnedResource(initial.value);
 
-    const mutex = stack.use(createMutex());
-    stack.defer(() => current.stack.disposeAsync());
+    const mutex = disposer.use(createMutex());
+    disposer.defer(() => current.stack.disposeAsync());
     // Register as the last so disposal aborts further calls first.
     // Repeated registration is safe because disposal is idempotent.
-    stack.use(resourceRefRun);
+    disposer.use(resourceRefRun);
 
-    const moved = stack.move();
+    const disposables = disposer.move();
 
     return ok({
       get: () => resourceRefRun(mutex.withLock(() => ok(current.resource))),
@@ -145,7 +145,7 @@ export const createResourceRef = <T extends Resource, D>(
           ),
         ),
 
-      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
     });
   });
 
@@ -165,12 +165,6 @@ export interface SharedResource<
   T extends Resource,
   D = unknown,
 > extends AsyncDisposable {
-  /** Returns the current shared-resource state for monitoring/debugging. */
-  readonly snapshot: () => SharedResourceSnapshot;
-
-  /** Returns the current resource, or `undefined` if absent. */
-  readonly get: () => BorrowedResource<T> | undefined;
-
   /**
    * Acquires a shared reference.
    *
@@ -203,6 +197,12 @@ export interface SharedResource<
 
   /** Returns the current acquire count. */
   readonly getCount: Task<NonNegativeInt, never, D>;
+
+  /** Returns the current resource, or `undefined` if absent. */
+  readonly get: () => BorrowedResource<T> | undefined;
+
+  /** Returns the current shared-resource state for monitoring/debugging. */
+  readonly snapshot: () => SharedResourceSnapshot;
 }
 
 /** Snapshot returned by {@link SharedResource.snapshot}. */
@@ -237,38 +237,31 @@ export const createSharedResource = <T extends Resource, D>(
   create: Task<T, never, D>,
   { idleDisposeAfter, onDisposed }: SharedResourceOptions = {},
 ): Task<SharedResource<T, D>, never, D> =>
-  unabortable<SharedResource<T, D>, never, D>((run) => {
+  unabortable<SharedResource<T, D>, never, D>(async (run) => {
     const sharedResourceRun = run.create();
     let current: OwnedResource<T> | undefined;
     let idleDisposeFiber: Fiber<void, AbortError, D> | undefined;
 
-    const stack = new AsyncDisposableStack();
-    const refCount = stack.use(createRefCount());
+    await using disposer = new AsyncDisposableStack();
+    const refCount = disposer.use(createRefCount());
 
-    const mutex = stack.use(createMutex());
+    const mutex = disposer.use(createMutex());
 
     const disposeCurrent = async () => {
       if (!current) return;
-      await using stack = new AsyncDisposableStack();
-      if (onDisposed) stack.defer(onDisposed);
-      stack.use(current.stack);
+      await using disposer = new AsyncDisposableStack();
+      if (onDisposed) disposer.defer(onDisposed);
+      disposer.use(current.stack);
       current = undefined;
     };
-    stack.defer(disposeCurrent);
+    disposer.defer(disposeCurrent);
 
     // Register as the last so disposal aborts further calls first.
-    stack.use(sharedResourceRun);
+    disposer.use(sharedResourceRun);
 
-    const moved = stack.move();
+    const disposables = disposer.move();
 
     return ok({
-      snapshot: () => ({
-        isIdle: refCount.getCount() === 0 && !current && !idleDisposeFiber,
-        mutex: mutex.snapshot(),
-      }),
-
-      get: () => current?.resource,
-
       acquire: unabortable<BorrowedResource<T>, never, D>(() =>
         sharedResourceRun(
           mutex.withLock(async (run) => {
@@ -320,7 +313,14 @@ export const createSharedResource = <T extends Resource, D>(
       getCount: () =>
         sharedResourceRun(mutex.withLock(() => ok(refCount.getCount()))),
 
-      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+      get: () => current?.resource,
+
+      snapshot: () => ({
+        isIdle: refCount.getCount() === 0 && !current && !idleDisposeFiber,
+        mutex: mutex.snapshot(),
+      }),
+
+      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
     });
   });
 
@@ -356,9 +356,6 @@ export interface SharedResourceByKey<
   T extends Resource,
   D = unknown,
 > extends AsyncDisposable {
-  /** Returns the current resource for `key`, or `undefined` if absent. */
-  readonly get: (key: K) => BorrowedResource<T> | undefined;
-
   /**
    * Acquires the shared resource for `key`, creating it on first use.
    *
@@ -386,6 +383,9 @@ export interface SharedResourceByKey<
   /** Returns the current acquire count for `key`. Missing keys return `0`. */
   readonly getCount: (key: K) => Task<NonNegativeInt, never, D>;
 
+  /** Returns the current resource for `key`, or `undefined` if absent. */
+  readonly get: (key: K) => BorrowedResource<T> | undefined;
+
   /** Returns current keyed resources and their per-key mutex state. */
   readonly snapshot: () => SharedResourceByKeySnapshot<K, T>;
 }
@@ -436,29 +436,28 @@ export function createSharedResourceByKey<
     onDisposed,
   }: SharedResourceByKeyOptions<K, L> = {},
 ): Task<SharedResourceByKey<K, T, D>, never, D> {
-  return unabortable<SharedResourceByKey<K, T, D>, never, D>((run) => {
+  return unabortable<SharedResourceByKey<K, T, D>, never, D>(async (run) => {
     const sharedResourceByKeyRun = run.create();
     const sharedResourcesByKey = createLookupMap<K, SharedResource<T, D>, L>({
       lookup,
     });
 
-    const stack = new AsyncDisposableStack();
+    await using disposer = new AsyncDisposableStack();
 
-    const mutexByKey = stack.use(createMutexByKey<K, L>({ lookup }));
-    stack.defer(async () => {
-      const stack = new AsyncDisposableStack();
-      for (const resource of sharedResourcesByKey.values()) stack.use(resource);
-      await stack.disposeAsync();
+    const mutexByKey = disposer.use(createMutexByKey<K, L>({ lookup }));
+    disposer.defer(async () => {
+      await using disposer = new AsyncDisposableStack();
+      for (const resource of sharedResourcesByKey.values())
+        disposer.use(resource);
+      await disposer.disposeAsync();
       sharedResourcesByKey.clear();
     });
     // Register as the last so disposal aborts further calls first.
-    stack.use(sharedResourceByKeyRun);
+    disposer.use(sharedResourceByKeyRun);
 
-    const moved = stack.move();
+    const disposables = disposer.move();
 
     return ok({
-      get: (key) => sharedResourcesByKey.get(key)?.get(),
-
       acquire: (key) =>
         unabortable<BorrowedResource<T>, never, D>(() =>
           sharedResourceByKeyRun(
@@ -521,6 +520,8 @@ export function createSharedResourceByKey<
           }),
         ),
 
+      get: (key) => sharedResourcesByKey.get(key)?.get(),
+
       snapshot: () => {
         const resourcesByKey = new Map<K, BorrowedResource<T>>();
         const mutexSnapshotsByKey = new Map<K, SemaphoreSnapshot | null>();
@@ -539,7 +540,7 @@ export function createSharedResourceByKey<
         };
       },
 
-      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
     });
   });
 }
@@ -661,27 +662,31 @@ export function createSharedResourceByKeyWithClaims<
   return unabortable<SharedResourceByKeyWithClaims<K, C, T, D>, never, D>(
     async (run) => {
       const sharedResourceClaimsRun = run.create();
-      await using stack = new AsyncDisposableStack();
+      await using disposer = new AsyncDisposableStack();
 
       const keyByClaim = createRelation<C, K, LC, LK>({
         lookupA: claimLookup,
         lookupB: resourceLookup,
       });
-      const pairRefCountsByClaim = stack.adopt(
+      const pairRefCountsByClaim = disposer.adopt(
         createLookupMap<C, RefCountByKey<K>, LC>({ lookup: claimLookup }),
         (pairRefCountsByClaim) => {
+          using disposer = new DisposableStack();
+          disposer.defer(() => {
+            pairRefCountsByClaim.clear();
+          });
+
           for (const pairRefCountByKey of pairRefCountsByClaim.values()) {
-            pairRefCountByKey[Symbol.dispose]();
+            disposer.use(pairRefCountByKey);
           }
-          pairRefCountsByClaim.clear();
         },
       );
 
-      const mutexByKey = stack.use(
+      const mutexByKey = disposer.use(
         createMutexByKey<K, LK>({ lookup: resourceLookup }),
       );
 
-      stack.defer(() => {
+      disposer.defer(() => {
         keyByClaim.clear();
       });
 
@@ -692,10 +697,12 @@ export function createSharedResourceByKeyWithClaims<
         }),
       );
       assertNotAborted(sharedResourcesByKeyResult);
-      const sharedResourcesByKey = stack.use(sharedResourcesByKeyResult.value);
+      const sharedResourcesByKey = disposer.use(
+        sharedResourcesByKeyResult.value,
+      );
 
       // Register as the last so disposal aborts further calls first.
-      stack.use(sharedResourceClaimsRun);
+      disposer.use(sharedResourceClaimsRun);
 
       /** Asserts that one call does not contain the same logical key twice. */
       const assertNoDuplicateResourceKeys = (
@@ -710,7 +717,7 @@ export function createSharedResourceByKeyWithClaims<
         );
       };
 
-      const moved = stack.move();
+      const disposables = disposer.move();
 
       return ok({
         addClaim: (claim, resourceKeys) =>
@@ -840,7 +847,7 @@ export function createSharedResourceByKeyWithClaims<
           return resources;
         },
 
-        [Symbol.asyncDispose]: () => moved.disposeAsync(),
+        [Symbol.asyncDispose]: () => disposables.disposeAsync(),
       });
     },
   );

package/src/Schedule.ts

@@ -4,6 +4,7 @@
  * @module
  */
 
+import { assertType } from "./Assert.js";
 import { fibonacciAt, FibonacciIndex, increment } from "./Number.js";
 import type { RandomDep } from "./Random.js";
 import { done, err, type NextResult, ok } from "./Result.js";
@@ -13,9 +14,15 @@ import {
   durationToMillis,
   Millis,
   minMillis,
+  saturateMillis,
   type TimeDep,
 } from "./Time.js";
-import { onePositiveInt, PositiveInt } from "./Type.js";
+import {
+  NonNegativeFiniteNumber,
+  NonNegativeInt,
+  onePositiveInt,
+  PositiveInt,
+} from "./Type.js";
 import type { Predicate } from "./Types.js";
 
 /**
@@ -113,11 +120,11 @@ const createScheduleStepMetrics = (
   return () => {
     const now = deps.time.now();
     const currentAttempt = attempt;
-    attempt = increment(attempt) as PositiveInt;
+    attempt = PositiveInt.orThrow(increment(attempt));
     start ??= now;
-    const elapsed = (now - start) as Millis;
+    const elapsed = saturateMillis(now - start);
     const elapsedSincePrevious =
-      previous === null ? (0 as Millis) : ((now - previous) as Millis);
+      previous === null ? minMillis : saturateMillis(now - previous);
     previous = now;
     return { attempt: currentAttempt, elapsed, elapsedSincePrevious };
   };
@@ -235,18 +242,24 @@ export const spaced =
  *
  * @group Constructors
  */
-export const exponential =
-  (base: Duration, factor = 2): Schedule<Millis> =>
-  () => {
+export const exponential = (base: Duration, factor = 2): Schedule<Millis> => {
+  assertType(
+    NonNegativeFiniteNumber,
+    factor,
+    "Expected factor to be a non-negative finite number.",
+  );
+
+  return () => {
     const baseMs = durationToMillis(base);
     let attempt = 0;
     return () => {
       attempt++;
       const rawDelay = baseMs * Math.pow(factor, attempt - 1);
-      const delay = Millis.orThrow(Math.max(0, Math.round(rawDelay)));
+      const delay = saturateMillis(rawDelay);
       return ok([delay, delay]);
     };
   };
+};
 
 /**
  * Linear backoff schedule.
@@ -276,7 +289,7 @@ export const linear =
     let attempt = 0;
     return () => {
       attempt++;
-      const delay = Millis.orThrow(ms * attempt);
+      const delay = saturateMillis(ms * attempt);
       return ok([delay, delay]);
     };
   };
@@ -308,12 +321,10 @@ export const fibonacci =
   (initial: Duration): Schedule<Millis> =>
   () => {
     const ms = durationToMillis(initial);
-    let index = 1;
+    let index = FibonacciIndex.orThrow(1);
     return () => {
-      const delay = Millis.orThrow(
-        ms * fibonacciAt(FibonacciIndex.orThrow(index)),
-      );
-      index++;
+      const delay = saturateMillis(ms * fibonacciAt(index));
+      index = FibonacciIndex.orNull(increment(index)) ?? index;
       return ok([delay, delay]);
     };
   };
@@ -356,7 +367,7 @@ export const fixed =
       const remainder = intervalMs === 0 ? 0 : elapsed % intervalMs;
       const boundary = intervalMs - remainder;
       const delay = runningBehind ? 0 : boundary;
-      return ok([count++, delay as Millis]);
+      return ok([count++, saturateMillis(delay)]);
     };
   };
 
@@ -388,7 +399,7 @@ export const windowed =
       const { elapsed } = metrics();
       const remainder = intervalMs === 0 ? 0 : elapsed % intervalMs;
       const delay = intervalMs === 0 ? 0 : intervalMs - remainder;
-      return ok([count++, delay as Millis]);
+      return ok([count++, saturateMillis(delay)]);
     };
   };
 
@@ -563,18 +574,22 @@ export const unfoldSchedule =
  *
  * @group Limiting
  */
-export const take =
-  (n: number) =>
-  <Output, Input>(schedule: Schedule<Output, Input>): Schedule<Output, Input> =>
-  (deps) => {
-    const step = schedule(deps);
-    let attempt = 0;
-    return (input) => {
-      attempt++;
-      if (attempt > n) return err(done());
-      return step(input);
+export const take = (n: number) => {
+  assertType(NonNegativeInt, n, "Expected n to be a non-negative integer.");
+
+  return <Output, Input>(
+      schedule: Schedule<Output, Input>,
+    ): Schedule<Output, Input> =>
+    (deps) => {
+      const step = schedule(deps);
+      let attempt = 0;
+      return (input) => {
+        attempt++;
+        if (attempt > n) return err(done());
+        return step(input);
+      };
     };
-  };
+};
 
 /**
  * Limits schedule execution to a maximum elapsed time.
@@ -659,19 +674,27 @@ export const maxDelay = (max: Duration) => {
  *
  * @group Delay
  */
-export const jitter =
-  (factor = 0.5) =>
-  <Output, Input>(schedule: Schedule<Output, Input>): Schedule<Output, Input> =>
-  (deps) => {
-    const step = schedule(deps);
-    return (input) => {
-      const result = step(input);
-      if (!result.ok) return result;
-      const [output, delay] = result.value;
-      const jittered = delay * (1 - factor + deps.random.next() * 2 * factor);
-      return ok([output, Millis.orThrow(Math.max(0, Math.round(jittered)))]);
+export const jitter = (factor = 0.5) => {
+  assertType(
+    NonNegativeFiniteNumber,
+    factor,
+    "Expected factor to be a non-negative finite number.",
+  );
+
+  return <Output, Input>(
+      schedule: Schedule<Output, Input>,
+    ): Schedule<Output, Input> =>
+    (deps) => {
+      const step = schedule(deps);
+      return (input) => {
+        const result = step(input);
+        if (!result.ok) return result;
+        const [output, delay] = result.value;
+        const jittered = delay * (1 - factor + deps.random.next() * 2 * factor);
+        return ok([output, saturateMillis(jittered)]);
+      };
     };
-  };
+};
 
 /**
  * Adds an initial delay before the first attempt.
@@ -755,7 +778,7 @@ export const modifyDelay =
       const result = step(input);
       if (!result.ok) return result;
       const [output, delay] = result.value;
-      return ok([output, Millis.orThrow(Math.max(0, Math.round(f(delay))))]);
+      return ok([output, saturateMillis(f(delay))]);
     };
   };
 
@@ -787,8 +810,7 @@ export const compensate =
       const result = step(input);
       if (!result.ok) return result;
       const [output, delay] = result.value;
-      const adjusted = Math.max(0, delay - elapsedSincePrevious);
-      return ok([output, adjusted as Millis]);
+      return ok([output, saturateMillis(delay - elapsedSincePrevious)]);
     };
   };
 
@@ -1042,15 +1064,15 @@ export function passthrough<Output, Input>(
  * // Outputs: 100, 300, 700, 1500, ... (cumulative)
  *
  * // Collect all outputs
- * const collected = foldSchedule([] as Millis[], (acc, delay: Millis) => [
- *   ...acc,
- *   delay,
- * ])(take(3)(spaced("1s")));
+ * const collected = foldSchedule<ReadonlyArray<Millis>, Millis>(
+ *   [],
+ *   (acc, delay) => [...acc, delay],
+ * )(take(3)(spaced("1s")));
  * // Outputs: [1000], [1000, 1000], [1000, 1000, 1000]
  *
  * // Count attempts with custom output
  * const counted = foldSchedule(
- *   { attempts: 0, lastDelay: 0 as Millis },
+ *   { attempts: 0, lastDelay: minMillis },
  *   (acc, delay: Millis) => ({
  *     attempts: acc.attempts + 1,
  *     lastDelay: delay,
@@ -1338,7 +1360,7 @@ export const unionSchedules =
       const [outputA, delayA] = resultA.value;
       const [outputB, delayB] = resultB.value;
       // Use minimum delay, output from the one with smaller delay
-      const minDelay = Math.min(delayA, delayB) as Millis;
+      const minDelay = Millis.orThrow(Math.min(delayA, delayB));
       return delayA <= delayB
         ? ok([outputA, minDelay])
         : ok([outputB, minDelay]);

package/src/Set.ts

@@ -65,7 +65,7 @@ export function createSet<T>(
 /** Possibly empty set. */
 export function createSet<T>(items: ReadonlyArray<T>): ReadonlySet<T>;
 export function createSet<T>(items: ReadonlyArray<T>): ReadonlySet<T> {
-  return new Set(items) as ReadonlySet<T>;
+  return new Set(items);
 }
 
 /**
@@ -154,7 +154,7 @@ export const deleteFromSet = <T>(
 ): ReadonlySet<T> => {
   const next = new Set(set);
   next.delete(item);
-  return next as ReadonlySet<T>;
+  return next;
 };
 
 /**
@@ -191,7 +191,7 @@ export function mapSet<T, U>(
   for (const item of set) {
     next.add(mapper(item));
   }
-  return next as ReadonlySet<U>;
+  return next;
 }
 
 /**
@@ -229,7 +229,7 @@ export function filterSet<T>(
       next.add(item);
     }
   }
-  return next as ReadonlySet<T>;
+  return next;
 }
 
 /**

package/src/Sqlite.ts

@@ -191,6 +191,9 @@ export type SqliteRow = Record<string, SqliteValue>;
 export interface SqliteDriver extends Disposable {
   readonly exec: (query: SqliteQuery) => SqliteExecResult;
 
+  /** Disposes this driver, then deletes its persistent database file. */
+  readonly deleteDatabase: () => void;
+
   /**
    * Returns bytes backed by {@link ArrayBuffer}.
    *
@@ -234,18 +237,18 @@ export const createSqlite =
   async (run) => {
     const { createSqliteDriver } = run.deps;
     const console = run.deps.console.child("sql");
-    await using stack = new AsyncDisposableStack();
+    await using disposer = new AsyncDisposableStack();
 
     const driverResult = await run(createSqliteDriver(name, options));
     if (!driverResult.ok) return driverResult;
-    const driver = stack.use(driverResult.value);
+    const driver = disposer.use(driverResult.value);
     console.debug("SQLite driver created");
 
-    const moved = stack.move();
+    const disposables = disposer.move();
 
     const sqlite: Sqlite = {
       exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => {
-        assertNotDisposed(moved);
+        assertNotDisposed(disposables);
         console.debug({ query });
 
         const label =
@@ -274,18 +277,17 @@ export const createSqlite =
       },
 
       transaction: ((callback: () => Result<unknown, unknown> | void) => {
-        assertNotDisposed(moved);
+        assertNotDisposed(disposables);
         console.debug("begin");
         driver.exec(sql`begin;`);
 
+        using rollback = new DisposableStack();
         let shouldRollback = true;
-        using _rollback = {
-          [Symbol.dispose]: () => {
-            if (!shouldRollback) return;
-            console.debug("rollback");
-            driver.exec(sql`rollback;`);
-          },
-        };
+        rollback.defer(() => {
+          if (!shouldRollback) return;
+          console.debug("rollback");
+          driver.exec(sql`rollback;`);
+        });
 
         const result = callback();
         if (result != null && !result.ok) return result;
@@ -298,11 +300,11 @@ export const createSqlite =
       }) as SqliteTransaction,
 
       export: () => {
-        assertNotDisposed(moved);
+        assertNotDisposed(disposables);
         return driver.export();
       },
 
-      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
     };
 
     return ok(sqlite);
@@ -318,17 +320,18 @@ export const testSetupSqlite = async (
       readonly sqlite: Sqlite;
     }
 > => {
-  await using stack = new AsyncDisposableStack();
-  const run = stack.use(testCreateRun(deps));
-  const sqlite = stack.use(
+  await using disposer = new AsyncDisposableStack();
+  const run = disposer.use(testCreateRun(deps));
+  const sqlite = disposer.use(
     await run.orThrow(createSqlite(testName, { mode: "memory" })),
   );
-  const moved = stack.move();
+  const runWithSqlite = disposer.use(run.create({ ...run.deps, sqlite }));
+  const disposables = disposer.move();
 
   return {
-    run: run.addDeps({ sqlite }),
+    run: runWithSqlite,
     sqlite,
-    [Symbol.asyncDispose]: () => moved.disposeAsync(),
+    [Symbol.asyncDispose]: () => disposables.disposeAsync(),
   };
 };
 
@@ -377,27 +380,36 @@ export const createPreparedStatementsCache = <P>(
   factory: (sql: SafeSql) => P,
   disposeFn: (statement: P) => void,
 ): PreparedStatements<P> => {
-  let isDisposed = false;
-  const cache = new Map<SafeSql, P>();
+  using disposer = new DisposableStack();
+  const statementsBySql = new Map<SafeSql, P>();
+
+  disposer.defer(() => {
+    using disposer = new DisposableStack();
+    disposer.defer(() => {
+      statementsBySql.clear();
+    });
+
+    for (const statement of statementsBySql.values()) {
+      disposer.adopt(statement, disposeFn);
+    }
+  });
+
+  const disposables = disposer.move();
 
   return {
     get: (query, alwaysPrepare) => {
+      assertNotDisposed(disposables);
       if (alwaysPrepare !== true && !query.options?.prepare)
         return null as never;
-      let statement = cache.get(query.sql);
+      let statement = statementsBySql.get(query.sql);
       if (!statement) {
         statement = factory(query.sql);
-        cache.set(query.sql, statement);
+        statementsBySql.set(query.sql, statement);
       }
-      return statement as never;
+      return statement;
     },
 
-    [Symbol.dispose]: () => {
-      if (isDisposed) return;
-      isDisposed = true;
-      cache.forEach(disposeFn);
-      cache.clear();
-    },
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };