@evolu/common 6.0.1-preview.17 → 6.0.1-preview.19

package/src/Brand.ts

@@ -0,0 +1,75 @@
+/**
+ * A utility interface for creating branded types.
+ *
+ * Branded types enhance type safety by differentiating otherwise identical base
+ * types, such as `number` or `string`, to enforce stricter type checks.
+ *
+ * Supports multiple brands, allowing types to act like flags.
+ *
+ * ### Example 1: Single Brand
+ *
+ * ```ts
+ * // A branded type definition
+ * type UserId = number & Brand<"UserId">;
+ *
+ * // A function that creates `UserId` values.
+ * // Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
+ * const createUserId = (): UserId => {
+ *   return 123 as UserId; // Unsafe casting
+ * };
+ *
+ * const userId = createUserId();
+ *
+ * // A function that accepts only `UserId`.
+ * const getUser = (id: UserId) => {
+ *   // Implementation
+ * };
+ *
+ * getUser(userId); // ✅ Valid
+ * getUser(123); // ❌ TypeScript error
+ * getUser("123"); // ❌ TypeScript error
+ * ```
+ *
+ * ### Example 2: Multiple Brands
+ *
+ * ```ts
+ * // Define branded types
+ * type Min1 = string & Brand<"Min1">;
+ * type Max100 = string & Brand<"Max100">;
+ * type Min1Max100 = string & Brand<"Min1" | "Max100">;
+ *
+ * // Functions requiring specific brands
+ * const requiresMin1 = (value: Min1): void => {};
+ * const requiresMax100 = (value: Max100): void => {};
+ *
+ * // Values with single brands
+ * const min1Value: Min1 = "hello" as Min1;
+ * const max100Value: Max100 = "world" as Max100;
+ *
+ * // Value with multiple brands
+ * const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
+ *
+ * // Valid cases
+ * requiresMin1(min1Value); // ✅ Valid
+ * requiresMax100(max100Value); // ✅ Valid
+ * requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
+ * requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
+ * ```
+ */
+export interface Brand<B extends string> {
+  readonly [__brand]: Readonly<Record<B, true>>;
+}
+
+declare const __brand: unique symbol;
+
+/**
+ * Determines whether a type `T` is a branded type.
+ *
+ * Works with any base type intersected with a `Brand`.
+ *
+ * ### Examples
+ *
+ * - `IsBranded<string>` -> false
+ * - `IsBranded<string & Brand<"X">>` -> true
+ */
+export type IsBranded<T> = T extends Brand<string> ? true : false;

package/src/Callbacks.ts

@@ -1,5 +1,5 @@
 import { NanoIdLibDep } from "./NanoId.js";
-import { Brand } from "./Types.js";
+import { Brand } from "./Brand.js";
 
 /**
  * Manages one-time callback functions.

package/src/Crypto.ts

@@ -20,8 +20,9 @@ import {
   NonNegativeInt,
   Uint8Array,
 } from "./Type.js";
-import { Brand } from "./Types.js";
+import { Brand } from "./Brand.js";
 import { assert } from "./Assert.js";
+import { utf8ToBytes } from "./Buffer.js";
 
 /** `Uint8Array` created by {@link createRandomBytes}. */
 export type RandomBytes = Uint8Array & Brand<"RandomBytes">;
@@ -56,7 +57,7 @@ export const mnemonicToMnemonicSeed = (mnemonic: Mnemonic): MnemonicSeed =>
  * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
  */
 export const createSlip21 = (
-  seed: MnemonicSeed,
+  seed: Uint8Array,
   path: ReadonlyArray<string>,
 ): Uint8Array => {
   assert(
@@ -64,17 +65,29 @@ export const createSlip21 = (
     `Unusual SLIP-0021 seed length: ${seed.length} bytes`,
   );
 
-  let m = hmac(sha512, "Symmetric key seed", seed);
+  let m = hmac(sha512, utf8ToBytes("Symmetric key seed"), seed);
   for (const component of path) {
-    const p = new TextEncoder().encode(component);
-    const e = new globalThis.Uint8Array(p.byteLength + 1);
-    e[0] = 0;
-    e.set(p, 1);
-    m = hmac(sha512, m.slice(0, 32), e);
+    m = deriveSlip21Node(component, m);
   }
   return m.slice(32, 64);
 };
 
+/**
+ * Derives a single node in the SLIP-21 hierarchical key derivation.
+ *
+ * @see {@link createSlip21}
+ */
+export const deriveSlip21Node = (
+  component: string,
+  m: Uint8Array,
+): Uint8Array => {
+  const p = utf8ToBytes(component);
+  const e = new globalThis.Uint8Array(p.byteLength + 1);
+  e[0] = 0;
+  e.set(p, 1);
+  return hmac(sha512, m.slice(0, 32), e);
+};
+
 /**
  * Creates a 21-character Base64URL ID (also known as nanoid) from a SLIP-21
  * derived key.

package/src/Evolu/Protocol.ts

@@ -183,7 +183,8 @@ import {
   PositiveInt,
   record,
 } from "../Type.js";
-import { Brand, Predicate } from "../Types.js";
+import { Predicate } from "../Types.js";
+import { Brand } from "../Brand.js";
 import { Owner, OwnerId, WriteKey, writeKeyLength } from "./Owner.js";
 import {
   BinaryTimestamp,

package/src/Evolu/Query.ts

@@ -8,7 +8,8 @@ import {
   SqliteValue,
 } from "../Sqlite.js";
 import { Store, StoreSubscribe } from "../Store.js";
-import { Brand, Simplify } from "../Types.js";
+import { Simplify } from "../Types.js";
+import { Brand } from "../Brand.js";
 
 /**
  * A type-safe SQL query.

package/src/Evolu/Storage.ts

@@ -29,7 +29,7 @@ import { RandomDep } from "../Random.js";
 import { ok, Result } from "../Result.js";
 import { sql, SqliteDep, SqliteError } from "../Sqlite.js";
 import { Int64String, NonNegativeInt, PositiveInt } from "../Type.js";
-import { Brand } from "../Types.js";
+import { Brand } from "../Brand.js";
 import { OwnerId } from "./Owner.js";
 import {
   BinaryOwnerId,

package/src/Evolu/Timestamp.ts

@@ -13,7 +13,7 @@ import {
   regex,
   String,
 } from "../Type.js";
-import { Brand } from "../Types.js";
+import { Brand } from "../Brand.js";
 
 export interface TimestampConfig {
   /**

package/src/Number.ts

@@ -2,12 +2,8 @@ import { NonEmptyReadonlyArray } from "./Array.js";
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
 import { err, ok, Result } from "./Result.js";
 import { NonNegativeInt, PositiveInt } from "./Type.js";
-import {
-  IntentionalNever,
-  IsBranded,
-  Predicate,
-  WidenLiteral,
-} from "./Types.js";
+import { IntentionalNever, Predicate, WidenLiteral } from "./Types.js";
+import { IsBranded } from "./Brand.js";
 
 export const increment = (n: number): number => n + 1;
 

package/src/Result.ts

@@ -1,37 +1,17 @@
-/* eslint-disable jsdoc/no-undefined-types */
 /**
  * 🛡️ 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;
- * }
+ * tell 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. ✅
  *
- * const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
- * const err = <E>(error: E): Err<E> => ({ ok: false, error });
- * ```
+ * This type models that approach in TypeScript. 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.
  *
  * Now let's look at how `Result` can be used for safe JSON parsing:
  *
@@ -198,9 +178,8 @@
  * ### 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";
@@ -235,15 +214,6 @@
  * 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.
  */
 export type Result<T, E> = Ok<T> | Err<E>;
 
@@ -356,12 +326,14 @@ export const err = <E>(error: E): Err<E> => ({ ok: false, error });
  * const config = getOrThrow(loadConfig());
  * // Safe to use config here
  * ```
+ *
+ * Throws: `Error` with the original error attached as `cause`.
  */
 export const getOrThrow = <T, E>(result: Result<T, E>): T => {
   if (result.ok) {
     return result.value;
   } else {
-    throw new Error(`Result error: ${JSON.stringify(result.error)}`);
+    throw new Error("getOrThrow failed", { cause: result.error });
   }
 };
 

package/src/Sqlite.ts

@@ -11,7 +11,8 @@ import {
   Uint8Array,
   union,
 } from "./Type.js";
-import { Brand, Predicate, IntentionalNever } from "./Types.js";
+import { Predicate, IntentionalNever } from "./Types.js";
+import { Brand } from "./Brand.js";
 
 /**
  * SQLite driver interface. This is the minimal interface that platform-specific

package/src/Type.ts

@@ -80,7 +80,8 @@ import { NanoIdLibDep } from "./NanoId.js";
 import { isPlainObject } from "./Object.js";
 import { Err, err, Ok, ok, Result, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
-import type { Brand, Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { Brand } from "./Brand.js";
 import { IntentionalNever } from "./Types.js";
 
 export interface Type<

package/src/Types.ts

@@ -78,82 +78,6 @@ export type NullablePartial<
  */
 export type IntentionalNever = never;
 
-/**
- * A utility interface for creating branded types.
- *
- * Branded types enhance type safety by differentiating otherwise identical base
- * types, such as `number` or `string`, to enforce stricter type checks.
- *
- * Supports multiple brands, allowing types to act like flags.
- *
- * ### Example 1: Single Brand
- *
- * ```ts
- * // A branded type definition
- * type UserId = number & Brand<"UserId">;
- *
- * // A function that creates `UserId` values.
- * // Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
- * const createUserId = (): UserId => {
- *   return 123 as UserId; // Unsafe casting
- * };
- *
- * const userId = createUserId();
- *
- * // A function that accepts only `UserId`.
- * const getUser = (id: UserId) => {
- *   // Implementation
- * };
- *
- * getUser(userId); // ✅ Valid
- * getUser(123); // ❌ TypeScript error
- * getUser("123"); // ❌ TypeScript error
- * ```
- *
- * ### Example 2: Multiple Brands
- *
- * ```ts
- * // Define branded types
- * type Min1 = string & Brand<"Min1">;
- * type Max100 = string & Brand<"Max100">;
- * type Min1Max100 = string & Brand<"Min1" | "Max100">;
- *
- * // Functions requiring specific brands
- * const requiresMin1 = (value: Min1): void => {};
- * const requiresMax100 = (value: Max100): void => {};
- *
- * // Values with single brands
- * const min1Value: Min1 = "hello" as Min1;
- * const max100Value: Max100 = "world" as Max100;
- *
- * // Value with multiple brands
- * const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
- *
- * // Valid cases
- * requiresMin1(min1Value); // ✅ Valid
- * requiresMax100(max100Value); // ✅ Valid
- * requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
- * requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
- * ```
- */
-export interface Brand<B extends string> {
-  readonly [__brand]: Readonly<Record<B, true>>;
-}
-
-declare const __brand: unique symbol;
-
-/**
- * Determines whether a type `T` is a branded type.
- *
- * Works with any base type intersected with a `Brand`.
- *
- * ### Examples
- *
- * - `IsBranded<string>` -> false
- * - `IsBranded<string & Brand<"X">>` -> true
- */
-export type IsBranded<T> = T extends Brand<string> ? true : false;
-
 /**
  * String | number | bigint | boolean | undefined | null
  *

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./Array.js";
 export * from "./Assert.js";
 export * from "./BigInt.js";
+export * from "./Brand.js";
 export * from "./Buffer.js";
 export * from "./Callbacks.js";
 export * from "./Console.js";