wellcrafted 0.29.0 → 0.31.0

package/README.md

@@ -46,8 +46,8 @@ function divide(a: number, b: number): Result<number, string> {
 ### 🏷️ Brand Types
 Create distinct types from primitives
 ```typescript
-type UserId = Brand<string, "UserId">;
-type OrderId = Brand<string, "OrderId">;
+type UserId = string & Brand<"UserId">;
+type OrderId = string & Brand<"OrderId">;
 
 // TypeScript prevents mixing them up!
 function getUser(id: UserId) { /* ... */ }
@@ -84,11 +84,13 @@ const userQuery = defineQuery({
 });
 
 // Use reactively in components with automatic state management
-const query = createQuery(userQuery.options());
+// Svelte 5 requires accessor function; React uses options directly
+const query = createQuery(() => userQuery.options); // Svelte
 // query.data, query.error, query.isPending all managed automatically
 
 // Or use imperatively for direct execution (perfect for event handlers)
 const { data, error } = await userQuery.fetch();
+// Or shorthand: await userQuery() (same as .ensure())
 if (error) {
   showErrorToast(error.message);
   return;
@@ -336,12 +338,13 @@ export const recorder = {
 };
 
 // 3. Component Usage - Choose reactive or imperative based on needs
-// Reactive: Automatic state management
-const recorderState = createQuery(recorder.getRecorderState.options());
+// Reactive: Automatic state management (Svelte 5 requires accessor function)
+const recorderState = createQuery(() => recorder.getRecorderState.options);
 
 // Imperative: Direct execution for event handlers
 async function handleStartRecording() {
   const { error } = await recorder.startRecording.execute();
+  // Or shorthand: await recorder.startRecording()
   if (error) {
     showToast(error.title, { description: error.description });
   }
@@ -623,8 +626,8 @@ For comprehensive examples, service layer patterns, framework integrations, and
 
 ### Query Functions
 - **`createQueryFactories(client)`** - Create query/mutation factories for TanStack Query
-- **`defineQuery(options)`** - Define a query with dual interface (`.options()` + `.fetch()`)
-- **`defineMutation(options)`** - Define a mutation with dual interface (`.options()` + `.execute()`)
+- **`defineQuery(options)`** - Define a query with dual interface (`.options` + callable/`.ensure()`/`.fetch()`)
+- **`defineMutation(options)`** - Define a mutation with dual interface (`.options` + callable/`.execute()`)
 
 ### Error Functions
 - **`createTaggedError(name)`** - Creates error factory functions with fluent API
@@ -646,6 +649,30 @@ For comprehensive examples, service layer patterns, framework integrations, and
 - **`UnwrapOk<R>`** - Extract success value type from Result
 - **`UnwrapErr<R>`** - Extract error value type from Result
 
+## Development Setup
+
+### Peer Directory Requirement
+
+Wellcrafted shares AI agent skills (`.agents/skills/`, `.claude/skills/`) with the [Epicenter](https://github.com/EpicenterHQ/epicenter) repo via relative symlinks. Epicenter is the source of truth for skill definitions — they're authored and maintained there, and wellcrafted consumes them to stay in sync.
+
+**Both repos must be sibling directories under the same parent:**
+
+```
+Code/
+├── epicenter/       # Source of truth for skills
+│   └── .agents/skills/
+└── wellcrafted/     # Symlinks to epicenter
+    ├── .agents/skills/<name> → ../../../epicenter/.agents/skills/<name>
+    └── .claude/skills/<name> → ../../.agents/skills/<name>
+```
+
+If symlinks appear broken after cloning, ensure epicenter is cloned alongside wellcrafted:
+
+```bash
+cd "$(git rev-parse --show-toplevel)/.."
+git clone https://github.com/EpicenterHQ/epicenter.git
+```
+
 ## License
 
 MIT

package/dist/brand.d.ts

@@ -6,35 +6,103 @@ declare const brand: unique symbol;
 /**
  * Creates a brand type for nominal typing in TypeScript.
  *
- * Branded types help create distinct types from primitive types, preventing
+ * Branded types create distinct types from primitive types, preventing
  * accidental mixing of values that should be semantically different.
  *
+ * ## Why wellcrafted Brand?
+ *
+ * **Composable** — Brands stack to create hierarchical type relationships.
+ * Child types are assignable to parent types, but not vice versa. Multiple
+ * inheritance works via intersection. This is possible because of the nested
+ * object structure `{ [brand]: { [K in T]: true } }` — when brands intersect,
+ * their properties merge instead of conflicting.
+ *
+ * **Framework-agnostic** — Unlike Zod's `.brand()`, ArkType's `.brand()`, or
+ * Valibot's `v.brand()` — which each produce library-specific branded types —
+ * wellcrafted's `Brand<T>` is a pure type utility with zero runtime footprint.
+ * Define your branded type once, then plug it into any runtime validator.
+ * Switch validation libraries without touching your type definitions.
+ *
+ * **Dual-declaration friendly** — TypeScript has two parallel namespaces: types
+ * and values. You can use the same PascalCase name for both the branded type and
+ * its runtime validator. JSDoc written on the type shows up everywhere the name
+ * appears — function signatures, schema definitions, and imports — giving you a
+ * single hover experience across your entire codebase.
+ *
  * @template T - A string literal type that serves as the brand identifier
  *
- * @example
+ * @example Single brand — preventing ID mix-ups
  * ```typescript
- * // Create a branded ID type
- * type ID = string & Brand<"ID">;
+ * type UserId = string & Brand<"UserId">;
+ * type OrderId = string & Brand<"OrderId">;
  *
- * // Create functions that work with branded types
- * function createID(value: string): ID {
- *   return value as ID;
- * }
+ * const userId: UserId = "user-123" as UserId;
+ * const orderId: OrderId = userId; // ❌ Type error
+ * ```
  *
- * function processID(id: ID): void {
- *   console.log(`Processing ID: ${id}`);
- * }
+ * @example Hierarchical brands — child assignable to parent
+ * ```typescript
+ * type AbsolutePath = string & Brand<"AbsolutePath">;
+ * type ConfigPath = AbsolutePath & Brand<"ConfigPath">;
  *
- * // Usage
- * const userID = createID("user-123");
- * const productID = createID("product-456");
+ * declare const configPath: ConfigPath;
+ * const abs: AbsolutePath = configPath;  // ✅ Child assignable to parent
+ * const cfg: ConfigPath = abs;           // ❌ Parent not assignable to child
+ * ```
  *
- * processID(userID); // ✅ Works
- * processID("raw-string"); // ❌ TypeScript error - string is not assignable to ID
+ * @example Multiple inheritance
+ * ```typescript
+ * type Serializable = unknown & Brand<"Serializable">;
+ * type Validated = unknown & Brand<"Validated">;
+ * type SafeData = Serializable & Validated & Brand<"SafeData">;
+ *
+ * // SafeData is assignable to both Serializable and Validated
  * ```
+ *
+ * @example Dual-declaration — same name for type and runtime validator
+ *
+ * TypeScript resolves the name from context: type position = branded type,
+ * value position = runtime validator. One name, zero ambiguity.
+ *
+ * ```typescript
+ * // Type-only brand (no runtime validation needed)
+ * type Guid = string & Brand<"Guid">;
+ *
+ * // Dual-declaration: type + runtime validator share the same name.
+ * // Hover over FileId anywhere — IDE shows the same JSDoc whether
+ * // it appears as a type annotation or a runtime schema.
+ * type FileId = Guid & Brand<"FileId">;
+ * const FileId = type("string").pipe((s): FileId => s as FileId);
+ * ```
+ *
+ * @example Framework-agnostic — same Brand, any validator
+ *
+ * Define the type once with `Brand<T>`, then create runtime validators
+ * with whichever library you prefer. Your branded types are never locked
+ * to a specific validation library.
+ *
+ * ```typescript
+ * import { type } from "arktype";
+ * import { z } from "zod";
+ * import * as v from "valibot";
+ *
+ * // Define the type ONCE — it's just a type, no library dependency
+ * type FileId = string & Brand<"FileId">;
+ *
+ * // ArkType
+ * const FileId = type("string").pipe((s): FileId => s as FileId);
+ *
+ * // Zod
+ * const FileId = z.string().transform((s): FileId => s as FileId);
+ *
+ * // Valibot
+ * const FileId = v.pipe(v.string(), v.transform((s): FileId => s as FileId));
+ * ```
+ *
+ * @see {@link https://wellcrafted.dev/integrations/validation-libraries | Using Brand with Validation Libraries}
  */
 type Brand<T extends string> = {
-  [brand]: T;
+  [brand]: { [K in T]: true };
 };
 //#endregion
 export { Brand };

package/dist/brand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brand.d.ts","names":[],"sources":["../src/brand.ts"],"sourcesContent":[],"mappings":";;;AAmCA;cAhCc,KAgCG,EAAA,OAAA,MAAA;;;AAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAAlC;GAA6B,KAAA,GAAQ"}
+{"version":3,"file":"brand.d.ts","names":[],"sources":["../src/brand.ts"],"sourcesContent":[],"mappings":";;;AAGkC;cAApB,KAoGJ,EAAA,OAAA,MAAA;;;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KADF;GACH,KAAA,WAAgB"}

package/dist/error/index.d.ts

@@ -1,6 +1,18 @@
 import { Err } from "../result-DolxQXIZ.js";
 
 //#region src/error/types.d.ts
+
+/**
+ * JSON-serializable value types for error context.
+ * Ensures all error data can be safely serialized via JSON.stringify.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * JSON-serializable object type for error context.
+ */
+type JsonObject = Record<string, JsonValue>;
 /**
  * Base type for any tagged error, used as a constraint for cause parameters.
  */
@@ -13,10 +25,8 @@ type AnyTaggedError = {
  * - When TContext is undefined (default): NO context property (explicit opt-in)
  * - When TContext includes undefined (e.g., `{ foo: string } | undefined`): context is OPTIONAL but typed
  * - When TContext is a specific type without undefined: context is REQUIRED with that exact type
- *
- * This follows Rust's explicit error philosophy: context must be explicitly added via .withContext<T>().
  */
-type WithContext<TContext> = [TContext] extends [undefined] ? {} : [undefined] extends [TContext] ? {
+type WithContext<TContext> = [TContext] extends [undefined] ? Record<never, never> : [undefined] extends [TContext] ? {
   context?: Exclude<TContext, undefined>;
 } : {
   context: TContext;
@@ -26,80 +36,21 @@ type WithContext<TContext> = [TContext] extends [undefined] ? {} : [undefined] e
  * - When TCause is undefined (default): NO cause property (explicit opt-in)
  * - When TCause includes undefined (e.g., `NetworkError | undefined`): cause is OPTIONAL, constrained
  * - When TCause is a specific type without undefined: cause is REQUIRED
- *
- * This follows Rust's explicit error philosophy: cause must be explicitly added via .withCause<T>().
- * Using brackets to prevent distributive conditional behavior with union types.
  */
-type WithCause<TCause> = [TCause] extends [undefined] ? {} : [undefined] extends [TCause] ? {
+type WithCause<TCause> = [TCause] extends [undefined] ? Record<never, never> : [undefined] extends [TCause] ? {
   cause?: Exclude<TCause, undefined>;
 } : {
   cause: TCause;
 };
 /**
- * Creates a tagged error type for type-safe error handling.
+ * A tagged error type for type-safe error handling.
  * Uses the `name` property as a discriminator for tagged unions.
  *
- * **Explicit Opt-In Philosophy (Rust-inspired):**
- * By default, errors only have `name` and `message`. Context and cause must be
- * explicitly added via type parameters. This follows Rust's thiserror pattern
- * where error properties are intentional architectural decisions.
- *
- * **Type Parameter Behavior:**
- * - When `TContext` is `undefined` (default): NO context property
- * - When `TContext` is `{ ... } | undefined`: `context` is OPTIONAL but typed
- * - When `TContext` is specified without undefined: `context` is REQUIRED
- * - When `TCause` is `undefined` (default): NO cause property
- * - When `TCause` is `{ ... } | undefined`: `cause` is OPTIONAL but typed
- * - When `TCause` is specified without undefined: `cause` is REQUIRED
- *
  * @template TName - The error name (discriminator for tagged unions)
  * @template TContext - Additional context data for the error (default: undefined = no context)
  * @template TCause - The type of error that caused this error (default: undefined = no cause)
- *
- * @example
- * ```ts
- * // Minimal error (no context, no cause)
- * type ValidationError = TaggedError<"ValidationError">;
- * const validationError: ValidationError = {
- *   name: "ValidationError",
- *   message: "Input is required"
- * };
- * // validationError only has name and message
- *
- * // Error with required context
- * type NetworkError = TaggedError<"NetworkError", { host: string; port: number }>;
- * const networkError: NetworkError = {
- *   name: "NetworkError",
- *   message: "Socket timeout",
- *   context: { host: "db.example.com", port: 5432 } // Required!
- * };
- *
- * // Error with OPTIONAL but TYPED context (union with undefined)
- * type LogError = TaggedError<"LogError", { file: string; line: number } | undefined>;
- * const logError1: LogError = { name: "LogError", message: "Parse failed" }; // OK
- * const logError2: LogError = { name: "LogError", message: "Parse failed", context: { file: "app.ts", line: 42 } }; // OK
- *
- * // Error with required context and optional cause
- * type DatabaseError = TaggedError<"DatabaseError", { operation: string }, NetworkError | undefined>;
- * const dbError: DatabaseError = {
- *   name: "DatabaseError",
- *   message: "Failed to connect to database",
- *   context: { operation: "connect" }, // Required!
- *   cause: networkError // Optional, but must be NetworkError if provided
- * };
- *
- * // Discriminated unions still work
- * function handleError(error: ValidationError | NetworkError) {
- *   switch (error.name) {
- *     case "ValidationError": // TypeScript knows this is ValidationError
- *       break;
- *     case "NetworkError": // TypeScript knows this is NetworkError
- *       break;
- *   }
- * }
- * ```
  */
-type TaggedError<TName extends string = string, TContext extends Record<string, unknown> | undefined = undefined, TCause extends AnyTaggedError | undefined = undefined> = Readonly<{
+type TaggedError<TName extends string = string, TContext extends JsonObject | undefined = undefined, TCause extends AnyTaggedError | undefined = undefined> = Readonly<{
   name: TName;
   message: string;
 } & WithContext<TContext> & WithCause<TCause>>;
@@ -108,222 +59,102 @@ type TaggedError<TName extends string = string, TContext extends Record<string,
 /**
  * Extracts a readable error message from an unknown error value
  *
- * This utility is commonly used in mapErr functions when converting
- * unknown errors to typed error objects in the Result system.
- *
  * @param error - The unknown error to extract a message from
  * @returns A string representation of the error
- *
- * @example
- * ```ts
- * // With native Error
- * const error = new Error("Something went wrong");
- * const message = extractErrorMessage(error); // "Something went wrong"
- *
- * // With string error
- * const stringError = "String error";
- * const message2 = extractErrorMessage(stringError); // "String error"
- *
- * // With object error
- * const unknownError = { code: 500, details: "Server error" };
- * const message3 = extractErrorMessage(unknownError); // '{"code":500,"details":"Server error"}'
- *
- * // Used in mapErr function
- * const result = await tryAsync({
- *   try: () => riskyOperation(),
- *   mapErr: (error) => Err({
- *     name: "NetworkError",
- *     message: extractErrorMessage(error),
- *     context: { operation: "riskyOperation" },
- *     cause: error,
- *   }),
- * });
- * ```
  */
 declare function extractErrorMessage(error: unknown): string;
 /**
  * Replaces the "Error" suffix with "Err" suffix in error type names.
- *
- * @template T - An error type name that must end with "Error"
- * @returns The type name with "Error" replaced by "Err"
- *
- * @example
- * ```ts
- * type NetworkErr = ReplaceErrorWithErr<"NetworkError">; // "NetworkErr"
- * type ValidationErr = ReplaceErrorWithErr<"ValidationError">; // "ValidationErr"
- * ```
  */
 type ReplaceErrorWithErr<T extends `${string}Error`> = T extends `${infer TBase}Error` ? `${TBase}Err` : never;
+/**
+ * Input provided to the message template function.
+ * Contains everything the error will have except `message` (since that's what it computes).
+ */
+type MessageInput<TName extends string, TContext extends JsonObject | undefined, TCause extends AnyTaggedError | undefined> = {
+  name: TName;
+} & ([TContext] extends [undefined] ? Record<never, never> : {
+  context: Exclude<TContext, undefined>;
+}) & ([TCause] extends [undefined] ? Record<never, never> : {
+  cause: Exclude<TCause, undefined>;
+});
+/**
+ * Message template function type.
+ */
+type MessageFn<TName extends string, TContext extends JsonObject | undefined, TCause extends AnyTaggedError | undefined> = (input: MessageInput<TName, TContext, TCause>) => string;
 /**
  * Helper type that determines optionality based on whether T includes undefined.
- * - If T includes undefined → property is optional
- * - If T does not include undefined → property is required
  */
 type OptionalIfUndefined<T, TKey extends string> = undefined extends T ? { [K in TKey]?: Exclude<T, undefined> } : { [K in TKey]: T };
 /**
- * Input type for error constructors with fluent API context/cause handling.
- *
- * Follows explicit opt-in philosophy:
- * - When TContext/TCause is undefined: property doesn't exist
- * - When TContext/TCause includes undefined: property is optional but typed
- * - When TContext/TCause is a specific type: property is required
+ * Input type for error factory functions.
+ * `message` is optional (computed from template when omitted).
+ * `context` and `cause` follow the same optionality rules as before.
  */
-type ErrorInput<TContext extends Record<string, unknown> | undefined, TCause extends AnyTaggedError | undefined> = {
-  message: string;
-} & (TContext extends undefined ? {} : OptionalIfUndefined<TContext, "context">) & (TCause extends undefined ? {} : OptionalIfUndefined<TCause, "cause">);
+type ErrorCallInput<TContext extends JsonObject | undefined, TCause extends AnyTaggedError | undefined> = {
+  message?: string;
+} & (TContext extends undefined ? Record<never, never> : OptionalIfUndefined<TContext, "context">) & (TCause extends undefined ? Record<never, never> : OptionalIfUndefined<TCause, "cause">);
 /**
- * The factories object returned by createTaggedError and its builder methods.
+ * The final factories object returned by `.withMessage()`.
+ * Has factory functions, NO chain methods.
  */
-type ErrorFactories<TName extends `${string}Error`, TContext extends Record<string, unknown> | undefined, TCause extends AnyTaggedError | undefined> = { [K in TName]: (input: ErrorInput<TContext, TCause>) => TaggedError<TName, TContext, TCause> } & { [K in ReplaceErrorWithErr<TName>]: (input: ErrorInput<TContext, TCause>) => Err<TaggedError<TName, TContext, TCause>> };
+type FinalFactories<TName extends `${string}Error`, TContext extends JsonObject | undefined, TCause extends AnyTaggedError | undefined> = { [K in TName]: (input: ErrorCallInput<TContext, TCause>) => TaggedError<TName, TContext, TCause> } & { [K in ReplaceErrorWithErr<TName>]: (input: ErrorCallInput<TContext, TCause>) => Err<TaggedError<TName, TContext, TCause>> };
 /**
  * Builder interface for the fluent createTaggedError API.
- * Provides chaining methods and the error factories.
+ * Has chain methods only, NO factory functions.
+ * Must call `.withMessage(fn)` to get factories.
  */
-type ErrorBuilder<TName extends `${string}Error`, TContext extends Record<string, unknown> | undefined = undefined, TCause extends AnyTaggedError | undefined = undefined> = ErrorFactories<TName, TContext, TCause> & {
+type ErrorBuilder<TName extends `${string}Error`, TContext extends JsonObject | undefined = undefined, TCause extends AnyTaggedError | undefined = undefined> = {
   /**
    * Constrains the context type for this error.
-   *
-   * Optionality is determined by whether the type includes `undefined`:
-   * - `withContext<T>()` where T doesn't include undefined → context is **required**
-   * - `withContext<T | undefined>()` → context is **optional** but typed when provided
-   *
-   * @typeParam T - The shape of the context object. Include `| undefined` to make optional.
-   *
-   * @example Required context
-   * ```ts
-   * const { FileError } = createTaggedError('FileError')
-   *   .withContext<{ path: string }>()
-   *
-   * FileError({ message: 'Not found', context: { path: '/etc/config' } })  // OK
-   * FileError({ message: 'Not found' })  // Type error: context required
-   * ```
-   *
-   * @example Optional but typed context
-   * ```ts
-   * const { LogError } = createTaggedError('LogError')
-   *   .withContext<{ file: string; line: number } | undefined>()
-   *
-   * LogError({ message: 'Parse error' })  // OK
-   * LogError({ message: 'Parse error', context: { file: 'app.ts', line: 42 } })  // OK
-   * ```
-   *
-   * @example Default (no generic): permissive optional context
-   * ```ts
-   * const { FlexError } = createTaggedError('FlexError')
-   *   .withContext()  // Defaults to Record<string, unknown> | undefined
-   *
-   * FlexError({ message: 'Error' })  // OK - context is optional
-   * FlexError({ message: 'Error', context: { anything: 'works' } })  // OK
-   * ```
+   * `.withContext<T>()` where T doesn't include undefined → context is **required**
+   * `.withContext<T | undefined>()` → context is **optional** but typed when provided
    */
-  withContext<T extends Record<string, unknown> | undefined = Record<string, unknown> | undefined>(): ErrorBuilder<TName, T, TCause>;
+  withContext<T extends JsonObject | undefined = JsonObject | undefined>(): ErrorBuilder<TName, T, TCause>;
   /**
    * Constrains the cause type for this error.
-   *
-   * Optionality is determined by whether the type includes `undefined`:
-   * - `withCause<T>()` where T doesn't include undefined → cause is **required**
-   * - `withCause<T | undefined>()` → cause is **optional** but typed when provided
-   *
-   * Since cause is typically optional, include `| undefined` in most cases.
-   *
-   * @typeParam T - The allowed cause type(s). Include `| undefined` to make optional.
-   *
-   * @example Optional typed cause (common)
-   * ```ts
-   * const { ServiceError } = createTaggedError('ServiceError')
-   *   .withCause<DbError | CacheError | undefined>()
-   *
-   * ServiceError({ message: 'Failed' })  // OK
-   * ServiceError({ message: 'Failed', cause: dbError })  // OK
-   * ```
-   *
-   * @example Required cause (for wrapper errors)
-   * ```ts
-   * const { UnhandledError } = createTaggedError('UnhandledError')
-   *   .withCause<AnyTaggedError>()
-   *
-   * UnhandledError({ message: 'Unexpected', cause: originalError })  // OK
-   * UnhandledError({ message: 'Unexpected' })  // Type error: cause required
-   * ```
-   *
-   * @example Default (no generic): permissive optional cause
-   * ```ts
-   * const { FlexError } = createTaggedError('FlexError')
-   *   .withCause()  // Defaults to AnyTaggedError | undefined
-   *
-   * FlexError({ message: 'Error' })  // OK - cause is optional
-   * FlexError({ message: 'Error', cause: anyTaggedError })  // OK
-   * ```
+   * `.withCause<T>()` where T doesn't include undefined → cause is **required**
+   * `.withCause<T | undefined>()` → cause is **optional** but typed when provided
    */
   withCause<T extends AnyTaggedError | undefined = AnyTaggedError | undefined>(): ErrorBuilder<TName, TContext, T>;
+  /**
+   * Terminal method that defines how the error message is computed from its data.
+   * Returns the factory functions — this is the only way to get them.
+   *
+   * @param fn - Template function that receives `{ name, context?, cause? }` and returns a message string
+   */
+  withMessage(fn: MessageFn<TName, TContext, TCause>): FinalFactories<TName, TContext, TCause>;
 };
 /**
  * Creates a new tagged error type with a fluent builder API.
  *
- * Returns an object containing:
- * - `{Name}Error`: Factory function that creates plain TaggedError objects
- * - `{Name}Err`: Factory function that creates Err-wrapped TaggedError objects
- * - `withContext<T>()`: Chain method to add context type
- * - `withCause<T>()`: Chain method to add cause type
- *
- * **Explicit Opt-In (Rust-inspired):**
- * By default, errors only have `{ name, message }`. Context and cause must be
- * explicitly added via `.withContext<T>()` and `.withCause<T>()`. This follows
- * Rust's thiserror pattern where error properties are intentional decisions.
+ * The builder provides `.withContext<T>()`, `.withCause<T>()`, and `.withMessage(fn)`.
+ * `.withMessage(fn)` is **required** and **terminal** — it returns the factory functions.
  *
- * **Optionality via type unions:**
- * Both `withContext` and `withCause` determine optionality based on whether
- * the type includes `undefined`:
- * - `T` without undefined → property is required
- * - `T | undefined` → property is optional but typed when provided
- *
- * @template TName - The name of the error type (must end with "Error")
- * @param name - The name of the error type
- *
- * @example Minimal error (no context, no cause)
+ * @example Simple error
  * ```ts
- * const { NetworkError, NetworkErr } = createTaggedError('NetworkError')
- *
- * NetworkError({ message: 'Connection failed' })
- * // Error only has { name: 'NetworkError', message: 'Connection failed' }
+ * const { RecorderBusyError, RecorderBusyErr } = createTaggedError('RecorderBusyError')
+ *   .withMessage(() => 'A recording is already in progress');
  * ```
  *
- * @example Required context
+ * @example Error with context
  * ```ts
- * const { ApiError, ApiErr } = createTaggedError('ApiError')
- *   .withContext<{ endpoint: string; status: number }>()
- *
- * ApiError({ message: 'Failed', context: { endpoint: '/users', status: 500 } })
- * // ApiError({ message: 'Failed' })  // Type error: context required
- * ```
- *
- * @example Optional typed cause
- * ```ts
- * const { ServiceError } = createTaggedError('ServiceError')
- *   .withCause<DbError | CacheError | undefined>()
- *
- * ServiceError({ message: 'Failed' })  // OK
- * ServiceError({ message: 'Failed', cause: dbError })  // OK, typed
- * ```
- *
- * @example Full example with both
- * ```ts
- * const { UserServiceError } = createTaggedError('UserServiceError')
- *   .withContext<{ userId: string }>()
- *   .withCause<RepoError | undefined>()
- *
- * // Type extraction works
- * type UserServiceError = ReturnType<typeof UserServiceError>
+ * const { DbNotFoundError, DbNotFoundErr } = createTaggedError('DbNotFoundError')
+ *   .withContext<{ table: string; id: string }>()
+ *   .withMessage(({ context }) => `${context.table} '${context.id}' not found`);
  * ```
  *
- * @example Permissive mode (if you want the old behavior)
+ * @example Error with context and cause
  * ```ts
- * const { FlexibleError } = createTaggedError('FlexibleError')
- *   .withContext<Record<string, unknown> | undefined>()
- *   .withCause<AnyTaggedError | undefined>()
+ * const { ServiceError, ServiceErr } = createTaggedError('ServiceError')
+ *   .withContext<{ operation: string }>()
+ *   .withCause<DbServiceError>()
+ *   .withMessage(({ context, cause }) =>
+ *     `Operation '${context.operation}' failed: ${cause.message}`
+ *   );
  * ```
  */
 declare function createTaggedError<TName extends `${string}Error`>(name: TName): ErrorBuilder<TName>;
 //#endregion
-export { AnyTaggedError, TaggedError, createTaggedError, extractErrorMessage };
+export { AnyTaggedError, JsonObject, JsonValue, TaggedError, createTaggedError, extractErrorMessage };
 //# sourceMappingURL=index.d.ts.map

package/dist/error/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/error/types.ts","../../src/error/utils.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/error/types.ts","../../src/error/utils.ts"],"sourcesContent":[],"mappings":"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"}