@evolu/common 6.0.1-preview.3 → 6.0.1-preview.31

package/dist/src/Result.d.ts

@@ -1,36 +1,19 @@
 /**
  * 🛡️ Type-safe errors
  *
- * ## Intro
- *
  * The problem with throwing an exception in JavaScript is that the caught error
  * is always of an unknown type. The unknown type is a problem because we can't
  * be sure all errors have been handled because the TypeScript compiler can't
- * help us.
- *
- * Some other languages like Rust 🦀 or Haskell 📚 use a type-safe approach to
- * error handling, where errors are explicitly represented as part of the return
- * type, such as Result or Either, allowing the developer to handle all errors
- * safely. ✅
- *
- * ✨ Evolu uses {@link Result}, and it looks like this:
+ * tell us.
  *
- * ```ts
- * type Result<T, E> = Ok<T> | Err<E>;
- *
- * interface Ok<T> {
- *   readonly ok: true;
- *   readonly value: T;
- * }
+ * Languages like Rust 🦀 or Haskell 📚 use a type-safe approach to error
+ * handling, where errors are explicitly represented as part of the return type,
+ * such as Result or Either, allowing the developer to handle errors safely.
+ * TypeScript can have this too via the `Result` type.
  *
- * interface Err<E> {
- *   readonly ok: false;
- *   readonly error: E;
- * }
- *
- * const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
- * const err = <E>(error: E): Err<E> => ({ ok: false, error });
- * ```
+ * The `Result` type can be either {@link Ok} (success) or {@link Err} (error).
+ * Use {@link ok} to create a successful result and {@link err} to create an error
+ * result.
  *
  * Now let's look at how `Result` can be used for safe JSON parsing:
  *
@@ -77,12 +60,10 @@
  *
  * Let's summarize it:
  *
- * - For synchronous safe code, use `ok` and `err`.
+ * - For safe code, use `ok` and `err`.
  * - For unsafe code, use `trySync` or `tryAsync`.
- * - For asynchronous safe code, use `Promise` with {@link Result}.
  *
- * Asynchronous safe (because of a Promise using Result) code is
- * straightforward:
+ * Asynchronous safe (because of a Promise using Result) code:
  *
  * ```ts
  * const fetchUser = async (
@@ -103,9 +84,40 @@
  * };
  * ```
  *
- * ## Examples
+ * ### Naming Convention
+ *
+ * - For values: `const user = getUser()`
+ * - For a single void operation: `const result = foo()`
+ * - For multiple void operations: use descriptive names for all
+ *
+ * ```ts
+ * const processUser = () => {
+ *   // we have a value
+ *   const user = getUser();
+ *   if (!user.ok) return user;
+ *
+ *   // single void operation
+ *   const result = saveToDatabase(user.value);
+ *   if (!result.ok) return result;
+ *
+ *   return ok();
+ * };
+ *
+ * const setupDatabase = () => {
+ *   // multiple void operations - use descriptive names
+ *   const baseTables = createBaseTables();
+ *   if (!baseTables.ok) return baseTables;
+ *
+ *   const relayTables = createRelayTables();
+ *   if (!relayTables.ok) return relayTables;
+ *
+ *   return ok();
+ * };
+ * ```
+ *
+ * ### Examples
  *
- * ### Sequential Operations with Short-Circuiting
+ * #### Sequential Operations with Short-Circuiting
  *
  * When performing a sequence of operations where any failure should stop
  * further processing, use the `Result` type with early returns.
@@ -155,37 +167,127 @@
  * This approach ensures type-safe error handling, avoids nested try/catch
  * blocks, and clearly communicates the control flow.
  *
- * ### A function with two different errors:
+ * #### A function with two different errors:
  *
  * ```ts
  * const example = (value: string): Result<number, FooError | BarError> => {
  *   const foo = getFoo(value);
  *   if (!foo.ok) return foo;
  *
- *   const bar = barize(foo.value);
+ *   const bar = getBar(foo.value);
  *   if (!bar.ok) return bar;
  *
  *   return ok(barToNumber(bar.value));
  * };
  * ```
  *
- * ## FAQ
+ * ### Handling Unexpected Errors
+ *
+ * Even with disciplined use of `trySync` and `tryAsync`, unexpected errors can
+ * still occur due to programming mistakes, third-party library bugs, or edge
+ * cases. These should be logged for debugging, but **unexpected errors are not
+ * recoverable** - they represent bugs that must be fixed.
+ *
+ * **Important**: "Graceful shutdown" and error recovery can only come from
+ * expected errors handled via the `Result` type. Unexpected errors should fail
+ * fast - the operation fails immediately and the error bubbles up.
+ *
+ * #### In Browser Environments
+ *
+ * ```ts
+ * // Global error handler for unexpected errors
+ * window.addEventListener("error", (event) => {
+ *   console.error("Uncaught error:", event.error);
+ *   // Send to error reporting service
+ *   errorReportingService.report(event.error);
+ * });
+ *
+ * // For unhandled promise rejections
+ * window.addEventListener("unhandledrejection", (event) => {
+ *   console.error("Unhandled promise rejection:", event.reason);
+ *   errorReportingService.report(event.reason);
+ * });
+ * ```
+ *
+ * #### In Node.js Environments
+ *
+ * ```ts
+ * // Handle uncaught exceptions - log and fail fast
+ * process.on("uncaughtException", (error) => {
+ *   console.error("Uncaught exception:", error);
+ *   errorReportingService.report(error);
+ *   // Exit immediately - unexpected errors are not recoverable
+ *   process.exit(1);
+ * });
+ *
+ * // Handle unhandled promise rejections
+ * process.on("unhandledRejection", (reason) => {
+ *   console.error("Unhandled promise rejection:", reason);
+ *   errorReportingService.report(reason);
+ * });
+ * ```
+ *
+ * These global handlers serve as a safety net to log and report unexpected
+ * errors for debugging purposes. They do not attempt recovery - unexpected
+ * errors represent bugs that must be fixed. The discipline of explicit error
+ * handling through the `Result` pattern remains the primary approach for all
+ * recoverable scenarios.
  *
- * ### What if my function doesn't return a value on success?
+ * ### FAQ
+ *
+ * #### When should a function return a plain value instead of `Result<T, E>`?
+ *
+ * Use `Result<T, E>` only when a function can fail with **known, expected
+ * errors** that callers need to handle. If a function cannot fail with a known
+ * error, return the value directly.
+ *
+ * - ✅ Return `Result<User, UserNotFoundError>` - can fail with a known error
+ * - ✅ Return `User` - cannot fail with a known error
+ * - ❌ Don't return `Result<User, never>` - unnecessary wrapper
+ *
+ * This keeps the codebase clean and makes error handling intentional. The type
+ * system communicates which operations can fail and which cannot.
+ *
+ * Unsafe code from external libraries (not under our control) should be wrapped
+ * with `trySync` or `tryAsync` at the boundaries. Once wrapped, if the error is
+ * not important to callers, functions can safely return plain values. If the
+ * error matters, use `Result` with a typed error.
+ *
+ * ```ts
+ * // ✅ Safe to return void - unsafe code is wrapped and error is handled
+ * const processData = (data: string): void => {
+ *   const parseResult = trySync(
+ *     () => JSON.parse(data),
+ *     (error) => ({ type: "ParseError", message: String(error) }),
+ *   );
+ *
+ *   if (!parseResult.ok) {
+ *     logError(parseResult.error);
+ *     return;
+ *   }
+ *
+ *   // Continue with safe operations...
+ * };
+ *
+ * // ✅ Can call without try-catch since it returns void
+ * processData(jsonString);
+ * ```
+ *
+ * #### What if my function doesn't return a value on success?
  *
  * If your function performs an operation but doesn't need to return a value on
  * success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
  * than using `Result<true, E>` or `Result<null, E>` because it communicates
  * that the function doesn't produce a value but can produce errors.
  *
- * ### How do I short-circuit processing of an array on the first error?
+ * #### How do I short-circuit processing of an array on the first error?
  *
  * If you want to stop processing as soon as an error occurs (short-circuit),
  * you should produce and check each `Result` inside a loop:
  *
  * ```ts
  * for (const query of [
- *   sql`drop table evolu_owner;`,
+ *   sql`drop table evolu_config;`,
  *   sql`drop table evolu_message;`,
  * ]) {
  *   const result = deps.sqlite.exec(query);
@@ -194,12 +296,11 @@
  * // All queries succeeded
  * ```
  *
- * ### How do I handle an array of operations and short-circuit on the first error?
+ * #### How do I handle an array of operations and short-circuit on the first error?
  *
  * If you have an array of operations (not results), you should make them
- * _lazy_—that is, represent each operation as a function (see `LazyValue` in
- * `Function.ts`). This way, you only execute each operation as needed, and can
- * stop on the first error:
+ * _lazy_—that is, represent each operation as a function. This way, you only
+ * execute each operation as needed, and can stop on the first error:
  *
  * ```ts
  * import type { LazyValue } from "./Function";
@@ -232,16 +333,7 @@
  * above) over monadic helpers. Imperative code is generally more readable,
  * easier to debug, and more familiar to most JavaScript and TypeScript
  * developers. While monads and functional helpers can be powerful, they often
- * obscure control flow and make debugging harder. Evolu's approach keeps error
- * handling explicit and straightforward.
- *
- * @module
- */
-/**
- * A `Result` can be either {@link Ok} (success) or {@link Err} (error).
- *
- * Use {@link ok} to create a successful result and {@link err} to create an error
- * result.
+ * obscure control flow and make debugging harder.
  */
 export type Result<T, E> = Ok<T> | Err<E>;
 /** A successful {@link Result}. */
@@ -297,6 +389,18 @@ export interface Err<E> {
     readonly ok: false;
     readonly error: E;
 }
+/**
+ * Extracts the value type from a {@link Result}.
+ *
+ * @category Utilities
+ */
+export type InferOk<R extends Result<any, any>> = R extends Ok<infer T> ? T : never;
+/**
+ * Extracts the error type from a {@link Result}.
+ *
+ * @category Utilities
+ */
+export type InferErr<R extends Result<any, any>> = R extends Err<infer E> ? E : never;
 /**
  * Creates an {@link Ok} result.
  *
@@ -346,8 +450,33 @@ export declare const err: <E>(error: E) => Err<E>;
  * const config = getOrThrow(loadConfig());
  * // Safe to use config here
  * ```
+ *
+ * Throws: `Error` with the original error attached as `cause`.
  */
 export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
+/**
+ * Extracts the value from a {@link Result} if it is an `Ok`, or returns `null`
+ * if it is an `Err`.
+ *
+ * **Intended usage:**
+ *
+ * - When you need to convert a `Result` to a nullable value for APIs that expect
+ *   `T | null`.
+ * - When the error is not important and you just want the value or nothing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const parseResult = parseJson('{"key": "value"}');
+ * const value = getOrNull(parseResult);
+ * // value is unknown | null
+ *
+ * if (value != null) {
+ *   console.log("Parsed value:", value);
+ * }
+ * ```
+ */
+export declare const getOrNull: <T, E>(result: Result<T, E>) => T | null;
 /**
  * Wraps synchronous functions that may throw exceptions, returning a
  * {@link Result}.
@@ -368,7 +497,10 @@ export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
  * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
  *   trySync(
  *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
+ *     (error): ParseJsonError => ({
+ *       type: "ParseJsonError",
+ *       message: String(error),
+ *     }),
  *   );
  * ```
  */

package/dist/src/Result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../../src/Result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8OG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAE1C,mCAAmC;AACnC,MAAM,WAAW,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/B,2DAA2D;AAC3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAKvC;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,GAAG,CAAC,CAAC,CAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAMvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAC1B,IAAI,MAAM,CAAC,EACX,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,MAAM,CAAC,CAAC,EAAE,CAAC,CAMb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EACjC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAIpB,CAAC"}
+{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../../src/Result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgVG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAE1C,mCAAmC;AACnC,MAAM,WAAW,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC5C,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC7C,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/B,2DAA2D;AAC3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAKvC;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,GAAG,CAAC,CAAC,CAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAMvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,GAAG,IAC1B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAC1B,IAAI,MAAM,CAAC,EACX,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,MAAM,CAAC,CAAC,EAAE,CAAC,CAMb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EACjC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAIpB,CAAC"}

package/dist/src/Result.js

@@ -1,242 +1,3 @@
-/**
- * 🛡️ Type-safe errors
- *
- * ## Intro
- *
- * The problem with throwing an exception in JavaScript is that the caught error
- * is always of an unknown type. The unknown type is a problem because we can't
- * be sure all errors have been handled because the TypeScript compiler can't
- * help us.
- *
- * Some other languages like Rust 🦀 or Haskell 📚 use a type-safe approach to
- * error handling, where errors are explicitly represented as part of the return
- * type, such as Result or Either, allowing the developer to handle all errors
- * safely. ✅
- *
- * ✨ Evolu uses {@link Result}, and it looks like this:
- *
- * ```ts
- * type Result<T, E> = Ok<T> | Err<E>;
- *
- * interface Ok<T> {
- *   readonly ok: true;
- *   readonly value: T;
- * }
- *
- * interface Err<E> {
- *   readonly ok: false;
- *   readonly error: E;
- * }
- *
- * const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
- * const err = <E>(error: E): Err<E> => ({ ok: false, error });
- * ```
- *
- * Now let's look at how `Result` can be used for safe JSON parsing:
- *
- * ```ts
- * interface ParseJsonError {
- *   readonly type: "ParseJsonError";
- *   readonly message: string;
- * }
- *
- * const parseJson = (value: string): Result<unknown, ParseJsonError> => {
- *   try {
- *     return ok(JSON.parse(value));
- *   } catch (error) {
- *     return err({ type: "ParseJsonError", message: String(error) });
- *   }
- * };
- *
- * // Result<unknown, ParseJsonError>
- * const json = parseJson('{"key": "value"}');
- *
- * // Fail fast to handle errors early.
- * if (!json.ok) return json; // Err<ParseJsonError>
- *
- * // Now, we have access to the json.value.
- * expectTypeOf(json.value).toBeUnknown();
- * ```
- *
- * Note how we didn't have to use the try/catch, just `if (!json.ok)`, and how
- * the error isn't unknown but has a type.
- *
- * But we had to use `try/catch` in the `parseJson` function. For such a case,
- * wrapping unsafe code, Evolu provides the {@link trySync} helper:
- *
- * ```ts
- * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
- *   trySync(
- *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
- *   );
- * ```
- *
- * ✨ {@link trySync} helper makes unsafe (can throw) synchronous code safe; for
- * unsafe asynchronous code, use {@link tryAsync}.
- *
- * Let's summarize it:
- *
- * - For synchronous safe code, use `ok` and `err`.
- * - For unsafe code, use `trySync` or `tryAsync`.
- * - For asynchronous safe code, use `Promise` with {@link Result}.
- *
- * Asynchronous safe (because of a Promise using Result) code is
- * straightforward:
- *
- * ```ts
- * const fetchUser = async (
- *   userId: string,
- * ): Promise<Result<User, FetchUserError>> => {
- *   // Simulate an API call
- *   return new Promise((resolve) => {
- *     setTimeout(() => {
- *       if (userId === "1") {
- *         resolve(ok({ id: "1", name: "Alice" }));
- *       } else {
- *         resolve(
- *           err({ type: "FetchUserError", reason: "user not found" }),
- *         );
- *       }
- *     }, 1000);
- *   });
- * };
- * ```
- *
- * ## Examples
- *
- * ### Sequential Operations with Short-Circuiting
- *
- * When performing a sequence of operations where any failure should stop
- * further processing, use the `Result` type with early returns.
- *
- * Here's an example of a database reset operation that drops tables, restores a
- * schema, and initializes the database, stopping on the first error:
- *
- * ```ts
- * const resetResult = deps.sqlite.transaction(() => {
- *   const dropAllTablesResult = dropAllTables(deps);
- *   if (!dropAllTablesResult.ok) return dropAllTablesResult;
- *
- *   if (message.restore) {
- *     const dbSchema = getDbSchema(deps)();
- *     if (!dbSchema.ok) return dbSchema;
- *
- *     const ensureDbSchemaResult = ensureDbSchema(deps)(
- *       message.restore.dbSchema,
- *       dbSchema.value,
- *     );
- *     if (!ensureDbSchemaResult.ok) return ensureDbSchemaResult;
- *
- *     const initializeDbResult = initializeDb(deps)(
- *       message.restore.mnemonic,
- *     );
- *     if (!initializeDbResult.ok) return initializeDbResult;
- *   }
- *   return ok();
- * });
- *
- * if (!resetResult.ok) {
- *   deps.postMessage({ type: "onError", error: resetResult.error });
- *   return;
- * }
- * ```
- *
- * In this pattern:
- *
- * - Each operation returns a `Result` (e.g., `Result<void, E>` or `Result<T,
- *   E>`).
- * - After each operation, check `if (!result.ok)` and return the `Err` to
- *   short-circuit.
- * - If all operations succeed, return `ok()` (or another value if needed).
- * - Outside the transaction, handle the final `Result` to report success or
- *   failure.
- *
- * This approach ensures type-safe error handling, avoids nested try/catch
- * blocks, and clearly communicates the control flow.
- *
- * ### A function with two different errors:
- *
- * ```ts
- * const example = (value: string): Result<number, FooError | BarError> => {
- *   const foo = getFoo(value);
- *   if (!foo.ok) return foo;
- *
- *   const bar = barize(foo.value);
- *   if (!bar.ok) return bar;
- *
- *   return ok(barToNumber(bar.value));
- * };
- * ```
- *
- * ## FAQ
- *
- * ### What if my function doesn't return a value on success?
- *
- * If your function performs an operation but doesn't need to return a value on
- * success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
- * than using `Result<true, E>` or `Result<null, E>` because it communicates
- * that the function doesn't produce a value but can produce errors.
- *
- * ### How do I short-circuit processing of an array on the first error?
- *
- * If you want to stop processing as soon as an error occurs (short-circuit),
- * you should produce and check each `Result` inside a loop:
- *
- * ```ts
- * for (const query of [
- *   sql`drop table evolu_owner;`,
- *   sql`drop table evolu_message;`,
- * ]) {
- *   const result = deps.sqlite.exec(query);
- *   if (!result.ok) return result;
- * }
- * // All queries succeeded
- * ```
- *
- * ### How do I handle an array of operations and short-circuit on the first error?
- *
- * If you have an array of operations (not results), you should make them
- * _lazy_—that is, represent each operation as a function (see `LazyValue` in
- * `Function.ts`). This way, you only execute each operation as needed, and can
- * stop on the first error:
- *
- * ```ts
- * import type { LazyValue } from "./Function";
- *
- * const operations: LazyValue<Result<void, MyError>>[] = [
- *   () => doSomething(),
- *   () => doSomethingElse(),
- * ];
- *
- * for (const op of operations) {
- *   const result = op();
- *   if (!result.ok) return result;
- * }
- * // All operations succeeded
- * ```
- *
- * If you already have an array of `Result`s, the processing has already
- * happened, so you can't short-circuit. In that case, you can check for the
- * first error:
- *
- * ```ts
- * const firstError = results.find((r) => !r.ok);
- * if (firstError) return firstError;
- * // All results are Ok
- * ```
- *
- * ### Why doesn't Evolu provide "handy helpers"?
- *
- * Evolu intentionally favors imperative patterns (like the `for...of` loop
- * above) over monadic helpers. Imperative code is generally more readable,
- * easier to debug, and more familiar to most JavaScript and TypeScript
- * developers. While monads and functional helpers can be powerful, they often
- * obscure control flow and make debugging harder. Evolu's approach keeps error
- * handling explicit and straightforward.
- *
- * @module
- */
 export function ok(value = undefined) {
     return { ok: true, value: value };
 }
@@ -269,15 +30,40 @@ export const err = (error) => ({ ok: false, error });
  * const config = getOrThrow(loadConfig());
  * // Safe to use config here
  * ```
+ *
+ * Throws: `Error` with the original error attached as `cause`.
  */
 export const getOrThrow = (result) => {
     if (result.ok) {
         return result.value;
     }
     else {
-        throw new Error(`Result error: ${JSON.stringify(result.error)}`);
+        throw new Error("getOrThrow", { cause: result.error });
     }
 };
+/**
+ * Extracts the value from a {@link Result} if it is an `Ok`, or returns `null`
+ * if it is an `Err`.
+ *
+ * **Intended usage:**
+ *
+ * - When you need to convert a `Result` to a nullable value for APIs that expect
+ *   `T | null`.
+ * - When the error is not important and you just want the value or nothing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const parseResult = parseJson('{"key": "value"}');
+ * const value = getOrNull(parseResult);
+ * // value is unknown | null
+ *
+ * if (value != null) {
+ *   console.log("Parsed value:", value);
+ * }
+ * ```
+ */
+export const getOrNull = (result) => result.ok ? result.value : null;
 /**
  * Wraps synchronous functions that may throw exceptions, returning a
  * {@link Result}.
@@ -298,7 +84,10 @@ export const getOrThrow = (result) => {
  * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
  *   trySync(
  *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
+ *     (error): ParseJsonError => ({
+ *       type: "ParseJsonError",
+ *       message: String(error),
+ *     }),
  *   );
  * ```
  */

package/dist/src/Skiplist.js

@@ -1,3 +1,4 @@
+import { PositiveInt } from "./Type.js";
 // TODO: Use in Storage.
 export const createSkiplistLevel = (deps) => (config = {}) => {
     const { probability = 0.5, maxLevel = 32 } = config;
@@ -7,7 +8,7 @@ export const createSkiplistLevel = (deps) => (config = {}) => {
             while (deps.random.next() <= probability && level < maxLevel) {
                 level += 1;
             }
-            return level;
+            return PositiveInt.orThrow(level);
         },
     };
 };