wellcrafted 0.31.0 → 0.32.0

package/README.md

@@ -21,8 +21,8 @@ try {
 const { data, error } = await saveUser(user);
 if (error) {
   switch (error.name) {
-    case "ValidationError": 
-      showToast(`Invalid ${error.context.field}`);
+    case "ValidationError":
+      showToast(`Invalid ${error.field}`);
       break;
     case "AuthError":
       redirectToLogin();
@@ -58,14 +58,15 @@ Structured, serializable errors with a fluent API
 ```typescript
 import { createTaggedError } from "wellcrafted/error";
 
-// Minimal by default - only name and message
-const { ValidationError } = createTaggedError("ValidationError");
-ValidationError({ message: "Email is required" });
+// Static error — no fields needed
+const { ValidationError } = createTaggedError("ValidationError")
+  .withMessage(() => "Email is required");
+ValidationError();
 
-// Chain to add context and cause when needed
+// Structured error — fields are spread flat on the error object
 const { ApiError } = createTaggedError("ApiError")
-  .withContext<{ endpoint: string }>()
-  .withCause<NetworkError | undefined>();
+  .withFields<{ endpoint: string }>()
+  .withMessage(({ endpoint }) => `Request to ${endpoint} failed`);
 ```
 
 ### 🔄 Query Integration
@@ -108,22 +109,18 @@ npm install wellcrafted
 
 ```typescript
 import { tryAsync } from "wellcrafted/result";
-import { createTaggedError, type AnyTaggedError } from "wellcrafted/error";
+import { createTaggedError } from "wellcrafted/error";
 
 // Define your error with factory function
 const { ApiError, ApiErr } = createTaggedError("ApiError")
-  .withContext<{ endpoint: string }>()
-  .withCause<AnyTaggedError | undefined>();
+  .withFields<{ endpoint: string }>()
+  .withMessage(({ endpoint }) => `Failed to fetch ${endpoint}`);
 type ApiError = ReturnType<typeof ApiError>;
 
 // Wrap any throwing operation
 const { data, error } = await tryAsync({
   try: () => fetch('/api/user').then(r => r.json()),
-  catch: (e) => ApiErr({
-    message: "Failed to fetch user",
-    context: { endpoint: '/api/user' },
-    cause: { name: "FetchError", message: String(e) }
-  })
+  catch: (e) => ApiErr({ endpoint: '/api/user' })
 });
 
 if (error) {
@@ -216,29 +213,25 @@ if (error) {
 ### Wrap Unsafe Operations
 
 ```typescript
-// Define errors with context and cause
+// Define errors with fields and message template
 const { ParseError, ParseErr } = createTaggedError("ParseError")
-  .withContext<{ input: string }>();
+  .withFields<{ input: string }>()
+  .withMessage(({ input }) => `Invalid JSON: ${input.slice(0, 50)}`);
 
 const { NetworkError, NetworkErr } = createTaggedError("NetworkError")
-  .withContext<{ url: string }>();
+  .withFields<{ url: string }>()
+  .withMessage(({ url }) => `Request to ${url} failed`);
 
 // Synchronous
 const result = trySync({
   try: () => JSON.parse(jsonString),
-  catch: () => ParseErr({
-    message: "Invalid JSON",
-    context: { input: jsonString }
-  })
+  catch: () => ParseErr({ input: jsonString })
 });
 
 // Asynchronous
 const result = await tryAsync({
   try: () => fetch(url),
-  catch: () => NetworkErr({
-    message: "Request failed",
-    context: { url }
-  })
+  catch: () => NetworkErr({ url })
 });
 ```
 
@@ -250,7 +243,11 @@ import { createTaggedError } from "wellcrafted/error";
 import { tryAsync, Result, Ok } from "wellcrafted/result";
 
 const { RecorderServiceError, RecorderServiceErr } = createTaggedError("RecorderServiceError")
-  .withContext<{ currentState?: string; permissions?: string }>();
+  .withFields<{ currentState?: string; permissions?: string }>()
+  .withMessage(({ permissions, currentState }) => {
+    if (permissions) return `Missing ${permissions} permission`;
+    return `Invalid recorder state: ${currentState}`;
+  });
 type RecorderServiceError = ReturnType<typeof RecorderServiceError>;
 
 export function createRecorderService() {
@@ -260,10 +257,7 @@ export function createRecorderService() {
   return {
     async startRecording(): Promise<Result<void, RecorderServiceError>> {
       if (isRecording) {
-        return RecorderServiceErr({
-          message: "Already recording",
-          context: { currentState: 'recording' }
-        });
+        return RecorderServiceErr({ currentState: 'recording' });
       }
 
       return tryAsync({
@@ -273,19 +267,13 @@ export function createRecorderService() {
           // ... recording setup
           isRecording = true;
         },
-        catch: () => RecorderServiceErr({
-          message: "Failed to start recording",
-          context: { permissions: 'microphone' }
-        })
+        catch: () => RecorderServiceErr({ permissions: 'microphone' })
       });
     },
 
     async stopRecording(): Promise<Result<Blob, RecorderServiceError>> {
       if (!isRecording) {
-        return RecorderServiceErr({
-          message: "Not currently recording",
-          context: { currentState: 'idle' }
-        });
+        return RecorderServiceErr({ currentState: 'idle' });
       }
 
       // Stop recording and return blob...
@@ -379,12 +367,13 @@ const { data: parsed } = trySync({
 
 ### Propagation Pattern (May Fail)
 ```typescript
-const { ParseError, ParseErr } = createTaggedError("ParseError");
+const { ParseError, ParseErr } = createTaggedError("ParseError")
+  .withMessage(() => "Invalid JSON");
 
 // When catch can return Err<E>, function returns Result<T, E>
 const mayFail = trySync({
   try: () => JSON.parse(riskyJson),
-  catch: () => ParseErr({ message: "Invalid JSON" })
+  catch: () => ParseErr()
 });
 // mayFail: Result<object, ParseError> - Must check for errors
 if (isOk(mayFail)) {
@@ -402,7 +391,7 @@ const smartParse = trySync({
       return Ok({}); // Return Ok<T> for fallback
     }
     // Propagate other errors
-    return ParseErr({ message: "Parse failed" });
+    return ParseErr();
   }
 });
 // smartParse: Result<object, ParseError> - Mixed handling = Result type
@@ -435,9 +424,12 @@ Based on real-world usage, here's the recommended pattern for creating services
 import { createTaggedError } from "wellcrafted/error";
 import { Result, Ok } from "wellcrafted/result";
 
-// 1. Define service-specific errors with typed context
+// 1. Define service-specific errors with typed fields and message
 const { RecorderServiceError, RecorderServiceErr } = createTaggedError("RecorderServiceError")
-  .withContext<{ isRecording: boolean }>();
+  .withFields<{ isRecording: boolean }>()
+  .withMessage(({ isRecording }) =>
+    isRecording ? "Already recording" : "Not currently recording"
+  );
 type RecorderServiceError = ReturnType<typeof RecorderServiceError>;
 
 // 2. Create service with factory function
@@ -449,10 +441,7 @@ export function createRecorderService() {
   return {
     startRecording(): Result<void, RecorderServiceError> {
       if (isRecording) {
-        return RecorderServiceErr({
-          message: "Already recording",
-          context: { isRecording }
-        });
+        return RecorderServiceErr({ isRecording });
       }
 
       isRecording = true;
@@ -461,10 +450,7 @@ export function createRecorderService() {
 
     stopRecording(): Result<Blob, RecorderServiceError> {
       if (!isRecording) {
-        return RecorderServiceErr({
-          message: "Not currently recording",
-          context: { isRecording }
-        });
+        return RecorderServiceErr({ isRecording });
       }
 
       isRecording = false;
@@ -549,7 +535,11 @@ export async function GET(request: Request) {
 
 ```typescript
 const { FormError, FormErr } = createTaggedError("FormError")
-  .withContext<{ fields: Record<string, string[]> }>();
+  .withFields<{ fields: Record<string, string[]> }>()
+  .withMessage(({ fields }) => {
+    const fieldNames = Object.keys(fields).join(", ");
+    return `Validation failed for: ${fieldNames}`;
+  });
 
 function validateLoginForm(data: unknown): Result<LoginData, FormError> {
   const errors: Record<string, string[]> = {};
@@ -559,10 +549,7 @@ function validateLoginForm(data: unknown): Result<LoginData, FormError> {
   }
 
   if (Object.keys(errors).length > 0) {
-    return FormErr({
-      message: "Validation failed",
-      context: { fields: errors }
-    });
+    return FormErr({ fields: errors });
   }
 
   return Ok(data as LoginData);
@@ -632,10 +619,11 @@ For comprehensive examples, service layer patterns, framework integrations, and
 ### Error Functions
 - **`createTaggedError(name)`** - Creates error factory functions with fluent API
   - Returns `{ErrorName}` (plain error) and `{ErrorName}Err` (Err-wrapped)
-  - **Default**: minimal errors with only `name` and `message`
-  - Chain `.withContext<T>()` to add typed context
-  - Chain `.withCause<T>()` to add typed cause
-  - Include `| undefined` in type to make property optional but typed
+  - Chain `.withFields<T>()` to add typed fields (spread flat on the error object)
+  - Chain `.withMessage(fn)` *(optional)* to seal the message with a template — `message` is not in the factory input type when present
+  - Without `.withMessage()`, `message` is required at the call site
+  - `name` is a reserved key — prevented at compile time by `NoReservedKeys`
+  - Factory input is flat (e.g., `{ endpoint: '/api' }`), not nested
 - **`extractErrorMessage(error)`** - Extract readable message from unknown error
 
 ### Types

package/dist/error/index.d.ts

@@ -14,46 +14,25 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
  */
 type JsonObject = Record<string, JsonValue>;
 /**
- * Base type for any tagged error, used as a constraint for cause parameters.
+ * Base type for any tagged error, used as a minimum constraint.
  */
 type AnyTaggedError = {
   name: string;
   message: string;
 };
-/**
- * Helper type that adds a context property.
- * - 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
- */
-type WithContext<TContext> = [TContext] extends [undefined] ? Record<never, never> : [undefined] extends [TContext] ? {
-  context?: Exclude<TContext, undefined>;
-} : {
-  context: TContext;
-};
-/**
- * Helper type that adds a cause property.
- * - 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
- */
-type WithCause<TCause> = [TCause] extends [undefined] ? Record<never, never> : [undefined] extends [TCause] ? {
-  cause?: Exclude<TCause, undefined>;
-} : {
-  cause: TCause;
-};
 /**
  * A tagged error type for type-safe error handling.
  * Uses the `name` property as a discriminator for tagged unions.
+ * Additional fields are spread flat on the error object.
  *
  * @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)
+ * @template TFields - Additional fields spread flat on the error (default: none)
  */
-type TaggedError<TName extends string = string, TContext extends JsonObject | undefined = undefined, TCause extends AnyTaggedError | undefined = undefined> = Readonly<{
+type TaggedError<TName extends string = string, TFields extends JsonObject = Record<never, never>> = Readonly<{
   name: TName;
   message: string;
-} & WithContext<TContext> & WithCause<TCause>>;
+} & TFields>;
+//# sourceMappingURL=types.d.ts.map
 //#endregion
 //#region src/error/utils.d.ts
 /**
@@ -64,94 +43,86 @@ type TaggedError<TName extends string = string, TContext extends JsonObject | un
  */
 declare function extractErrorMessage(error: unknown): string;
 /**
- * Replaces the "Error" suffix with "Err" suffix in error type names.
+ * Constraint that prevents the reserved key `name` from appearing in fields.
+ * `message` is not reserved — when `.withMessage()` seals it, `message` is
+ * simply absent from the input type. When `.withMessage()` is not used,
+ * `message` is a built-in input handled separately from TFields.
  */
-type ReplaceErrorWithErr<T extends `${string}Error`> = T extends `${infer TBase}Error` ? `${TBase}Err` : never;
+type NoReservedKeys = {
+  name?: never;
+};
 /**
- * Input provided to the message template function.
- * Contains everything the error will have except `message` (since that's what it computes).
+ * Replaces the "Error" suffix with "Err" suffix in error type names.
  */
-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>;
-});
+type ReplaceErrorWithErr<T extends `${string}Error`> = T extends `${infer TBase}Error` ? `${TBase}Err` : never;
 /**
  * Message template function type.
+ * Receives the fields (without name/message) and returns a message string.
  */
-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.
- */
-type OptionalIfUndefined<T, TKey extends string> = undefined extends T ? { [K in TKey]?: Exclude<T, undefined> } : { [K in TKey]: T };
+type MessageFn<TFields extends JsonObject> = (input: TFields) => string;
+/** Factory input when message is required (no `.withMessage()`). */
+type RequiredMessageInput<TFields extends JsonObject> = {
+  message: string;
+} & TFields;
 /**
- * Input type for error factory functions.
- * `message` is optional (computed from template when omitted).
- * `context` and `cause` follow the same optionality rules as before.
+ * Whether the entire input parameter can be omitted (called with no args).
+ * True when TFields is empty or all-optional (and message is sealed via withMessage).
  */
-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">);
+type IsInputOptional<TFields extends JsonObject> = Partial<TFields> extends TFields ? true : false;
 /**
- * The final factories object returned by `.withMessage()`.
- * Has factory functions, NO chain methods.
+ * Factories returned by `.withMessage()` — message is sealed by the template.
+ * `message` is NOT in the input type. Only has factory functions, no chain methods.
  */
-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>> };
+type SealedFactories<TName extends `${string}Error`, TFields extends JsonObject> = { [K in TName]: IsInputOptional<TFields> extends true ? (input?: TFields) => TaggedError<TName, TFields> : (input: TFields) => TaggedError<TName, TFields> } & { [K in ReplaceErrorWithErr<TName>]: IsInputOptional<TFields> extends true ? (input?: TFields) => Err<TaggedError<TName, TFields>> : (input: TFields) => Err<TaggedError<TName, TFields>> };
 /**
- * Builder interface for the fluent createTaggedError API.
- * Has chain methods only, NO factory functions.
- * Must call `.withMessage(fn)` to get factories.
+ * Builder object returned by createTaggedError (and .withFields()).
+ * Has factory functions (message required) AND chain methods.
  */
-type ErrorBuilder<TName extends `${string}Error`, TContext extends JsonObject | undefined = undefined, TCause extends AnyTaggedError | undefined = undefined> = {
+type ErrorBuilder<TName extends `${string}Error`, TFields extends JsonObject = Record<never, never>> = { [K in TName]: (input: RequiredMessageInput<TFields>) => TaggedError<TName, TFields> } & { [K in ReplaceErrorWithErr<TName>]: (input: RequiredMessageInput<TFields>) => Err<TaggedError<TName, TFields>> } & {
+  /** Defines additional fields spread flat on the error object. */
+  withFields<T extends JsonObject & NoReservedKeys>(): ErrorBuilder<TName, T>;
   /**
-   * Constrains the context type for this error.
-   * `.withContext<T>()` where T doesn't include undefined → context is **required**
-   * `.withContext<T | undefined>()` → context is **optional** but typed when provided
+   * Seals the message — the template owns it entirely.
+   * `message` is NOT in the returned factory's input type.
    */
-  withContext<T extends JsonObject | undefined = JsonObject | undefined>(): ErrorBuilder<TName, T, TCause>;
-  /**
-   * Constrains the cause type for this error.
-   * `.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>;
+  withMessage(fn: MessageFn<TFields>): SealedFactories<TName, TFields>;
 };
 /**
  * Creates a new tagged error type with a fluent builder API.
  *
- * The builder provides `.withContext<T>()`, `.withCause<T>()`, and `.withMessage(fn)`.
- * `.withMessage(fn)` is **required** and **terminal** — it returns the factory functions.
+ * Returns an object with factory functions immediately available (message required),
+ * plus `.withFields<T>()` and `.withMessage(fn)` for further configuration.
+ *
+ * Two mutually exclusive modes:
+ * 1. **No `.withMessage()`**: `message` is required at the call site
+ * 2. **With `.withMessage()`**: message is sealed — NOT in the input type
+ *
+ * @example No fields, message required at call site
+ * ```ts
+ * const { SimpleError, SimpleErr } = createTaggedError('SimpleError');
+ * SimpleErr({ message: 'Something went wrong' });
+ * ```
  *
- * @example Simple error
+ * @example No fields, with sealed message
  * ```ts
- * const { RecorderBusyError, RecorderBusyErr } = createTaggedError('RecorderBusyError')
+ * const { RecorderBusyError } = createTaggedError('RecorderBusyError')
  *   .withMessage(() => 'A recording is already in progress');
+ * RecorderBusyError();  // message always: 'A recording is already in progress'
  * ```
  *
- * @example Error with context
+ * @example With fields, message required
  * ```ts
- * const { DbNotFoundError, DbNotFoundErr } = createTaggedError('DbNotFoundError')
- *   .withContext<{ table: string; id: string }>()
- *   .withMessage(({ context }) => `${context.table} '${context.id}' not found`);
+ * const { FsReadError } = createTaggedError('FsReadError')
+ *   .withFields<{ path: string }>();
+ * FsReadError({ message: 'Failed to read', path: '/etc/config' });
  * ```
  *
- * @example Error with context and cause
+ * @example With fields + sealed message (template computes from fields)
  * ```ts
- * const { ServiceError, ServiceErr } = createTaggedError('ServiceError')
- *   .withContext<{ operation: string }>()
- *   .withCause<DbServiceError>()
- *   .withMessage(({ context, cause }) =>
- *     `Operation '${context.operation}' failed: ${cause.message}`
- *   );
+ * const { ResponseError } = createTaggedError('ResponseError')
+ *   .withFields<{ status: number }>()
+ *   .withMessage(({ status }) => `HTTP ${status}`);
+ * ResponseError({ status: 404 });  // message: "HTTP 404"
  * ```
  */
 declare function createTaggedError<TName extends `${string}Error`>(name: TName): ErrorBuilder<TName>;

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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"}

package/dist/error/index.js

@@ -37,60 +37,73 @@ function extractErrorMessage(error) {
 /**
 * Creates a new tagged error type with a fluent builder API.
 *
-* The builder provides `.withContext<T>()`, `.withCause<T>()`, and `.withMessage(fn)`.
-* `.withMessage(fn)` is **required** and **terminal** — it returns the factory functions.
+* Returns an object with factory functions immediately available (message required),
+* plus `.withFields<T>()` and `.withMessage(fn)` for further configuration.
 *
-* @example Simple error
+* Two mutually exclusive modes:
+* 1. **No `.withMessage()`**: `message` is required at the call site
+* 2. **With `.withMessage()`**: message is sealed — NOT in the input type
+*
+* @example No fields, message required at call site
 * ```ts
-* const { RecorderBusyError, RecorderBusyErr } = createTaggedError('RecorderBusyError')
+* const { SimpleError, SimpleErr } = createTaggedError('SimpleError');
+* SimpleErr({ message: 'Something went wrong' });
+* ```
+*
+* @example No fields, with sealed message
+* ```ts
+* const { RecorderBusyError } = createTaggedError('RecorderBusyError')
 *   .withMessage(() => 'A recording is already in progress');
+* RecorderBusyError();  // message always: 'A recording is already in progress'
 * ```
 *
-* @example Error with context
+* @example With fields, message required
 * ```ts
-* const { DbNotFoundError, DbNotFoundErr } = createTaggedError('DbNotFoundError')
-*   .withContext<{ table: string; id: string }>()
-*   .withMessage(({ context }) => `${context.table} '${context.id}' not found`);
+* const { FsReadError } = createTaggedError('FsReadError')
+*   .withFields<{ path: string }>();
+* FsReadError({ message: 'Failed to read', path: '/etc/config' });
 * ```
 *
-* @example Error with context and cause
+* @example With fields + sealed message (template computes from fields)
 * ```ts
-* const { ServiceError, ServiceErr } = createTaggedError('ServiceError')
-*   .withContext<{ operation: string }>()
-*   .withCause<DbServiceError>()
-*   .withMessage(({ context, cause }) =>
-*     `Operation '${context.operation}' failed: ${cause.message}`
-*   );
+* const { ResponseError } = createTaggedError('ResponseError')
+*   .withFields<{ status: number }>()
+*   .withMessage(({ status }) => `HTTP ${status}`);
+* ResponseError({ status: 404 });  // message: "HTTP 404"
 * ```
 */
 function createTaggedError(name) {
+	const errName = name.replace(/Error$/, "Err");
 	const createBuilder = () => {
+		const errorConstructor = (input) => {
+			const { message,...fields } = input;
+			return {
+				name,
+				message,
+				...fields
+			};
+		};
+		const errConstructor = (input) => Err(errorConstructor(input));
 		return {
-			withContext() {
-				return createBuilder();
-			},
-			withCause() {
+			[name]: errorConstructor,
+			[errName]: errConstructor,
+			withFields() {
 				return createBuilder();
 			},
 			withMessage(fn) {
-				const errorConstructor = (input) => {
-					const messageInput = {
-						name,
-						..."context" in input ? { context: input.context } : {},
-						..."cause" in input ? { cause: input.cause } : {}
-					};
+				const sealedErrorConstructor = (input) => {
+					const fields = input ?? {};
+					const message = fn(fields);
 					return {
 						name,
-						message: input.message ?? fn(messageInput),
-						..."context" in input ? { context: input.context } : {},
-						..."cause" in input ? { cause: input.cause } : {}
+						message,
+						...fields
 					};
 				};
-				const errName = name.replace(/Error$/, "Err");
-				const errConstructor = (input) => Err(errorConstructor(input));
+				const sealedErrConstructor = (input) => Err(sealedErrorConstructor(input));
 				return {
-					[name]: errorConstructor,
-					[errName]: errConstructor
+					[name]: sealedErrorConstructor,
+					[errName]: sealedErrConstructor
 				};
 			}
 		};

package/dist/error/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["error: unknown","name: TName","fn: MessageFn<TName, TContext, TCause>","input: ErrorCallInput<TContext, TCause>"],"sources":["../../src/error/utils.ts"],"sourcesContent":["import type {\n\tTaggedError,\n\tAnyTaggedError,\n\tJsonObject,\n} from \"./types.js\";\nimport { Err } from \"../result/result.js\";\n\n/**\n * Extracts a readable error message from an unknown error value\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n */\nexport function extractErrorMessage(error: unknown): string {\n\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\t// Final fallback\n\treturn String(error);\n}\n\n/**\n * Replaces the \"Error\" suffix with \"Err\" suffix in error type names.\n */\ntype ReplaceErrorWithErr<T extends `${string}Error`> =\n\tT extends `${infer TBase}Error` ? `${TBase}Err` : never;\n\n// =============================================================================\n// Message Function Types\n// =============================================================================\n\n/**\n * Input provided to the message template function.\n * Contains everything the error will have except `message` (since that's what it computes).\n */\ntype MessageInput<\n\tTName extends string,\n\tTContext extends JsonObject | undefined,\n\tTCause extends AnyTaggedError | undefined,\n> = { name: TName } & ([TContext] extends [undefined]\n\t? Record<never, never>\n\t: { context: Exclude<TContext, undefined> }) &\n\t([TCause] extends [undefined]\n\t\t? Record<never, never>\n\t\t: { cause: Exclude<TCause, undefined> });\n\n/**\n * Message template function type.\n */\ntype MessageFn<\n\tTName extends string,\n\tTContext extends JsonObject | undefined,\n\tTCause extends AnyTaggedError | undefined,\n> = (input: MessageInput<TName, TContext, TCause>) => string;\n\n// =============================================================================\n// Factory Input Types\n// =============================================================================\n\n/**\n * Helper type that determines optionality based on whether T includes undefined.\n */\ntype OptionalIfUndefined<T, TKey extends string> = undefined extends T\n\t? { [K in TKey]?: Exclude<T, undefined> }\n\t: { [K in TKey]: T };\n\n/**\n * Input type for error factory functions.\n * `message` is optional (computed from template when omitted).\n * `context` and `cause` follow the same optionality rules as before.\n */\ntype ErrorCallInput<\n\tTContext extends JsonObject | undefined,\n\tTCause extends AnyTaggedError | undefined,\n> = { message?: string } & (TContext extends undefined\n\t? Record<never, never>\n\t: OptionalIfUndefined<TContext, \"context\">) &\n\t(TCause extends undefined\n\t\t? Record<never, never>\n\t\t: OptionalIfUndefined<TCause, \"cause\">);\n\n// =============================================================================\n// Builder & Factory Types\n// =============================================================================\n\n/**\n * The final factories object returned by `.withMessage()`.\n * Has factory functions, NO chain methods.\n */\ntype FinalFactories<\n\tTName extends `${string}Error`,\n\tTContext extends JsonObject | undefined,\n\tTCause extends AnyTaggedError | undefined,\n> = {\n\t[K in TName]: (\n\t\tinput: ErrorCallInput<TContext, TCause>,\n\t) => TaggedError<TName, TContext, TCause>;\n} & {\n\t[K in ReplaceErrorWithErr<TName>]: (\n\t\tinput: ErrorCallInput<TContext, TCause>,\n\t) => Err<TaggedError<TName, TContext, TCause>>;\n};\n\n/**\n * Builder interface for the fluent createTaggedError API.\n * Has chain methods only, NO factory functions.\n * Must call `.withMessage(fn)` to get factories.\n */\ntype ErrorBuilder<\n\tTName extends `${string}Error`,\n\tTContext extends JsonObject | undefined = undefined,\n\tTCause extends AnyTaggedError | undefined = undefined,\n> = {\n\t/**\n\t * Constrains the context type for this error.\n\t * `.withContext<T>()` where T doesn't include undefined → context is **required**\n\t * `.withContext<T | undefined>()` → context is **optional** but typed when provided\n\t */\n\twithContext<\n\t\tT extends JsonObject | undefined = JsonObject | undefined,\n\t>(): ErrorBuilder<TName, T, TCause>;\n\n\t/**\n\t * Constrains the cause type for this error.\n\t * `.withCause<T>()` where T doesn't include undefined → cause is **required**\n\t * `.withCause<T | undefined>()` → cause is **optional** but typed when provided\n\t */\n\twithCause<\n\t\tT extends AnyTaggedError | undefined = AnyTaggedError | undefined,\n\t>(): ErrorBuilder<TName, TContext, T>;\n\n\t/**\n\t * Terminal method that defines how the error message is computed from its data.\n\t * Returns the factory functions — this is the only way to get them.\n\t *\n\t * @param fn - Template function that receives `{ name, context?, cause? }` and returns a message string\n\t */\n\twithMessage(\n\t\tfn: MessageFn<TName, TContext, TCause>,\n\t): FinalFactories<TName, TContext, TCause>;\n};\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a new tagged error type with a fluent builder API.\n *\n * The builder provides `.withContext<T>()`, `.withCause<T>()`, and `.withMessage(fn)`.\n * `.withMessage(fn)` is **required** and **terminal** — it returns the factory functions.\n *\n * @example Simple error\n * ```ts\n * const { RecorderBusyError, RecorderBusyErr } = createTaggedError('RecorderBusyError')\n *   .withMessage(() => 'A recording is already in progress');\n * ```\n *\n * @example Error with context\n * ```ts\n * const { DbNotFoundError, DbNotFoundErr } = createTaggedError('DbNotFoundError')\n *   .withContext<{ table: string; id: string }>()\n *   .withMessage(({ context }) => `${context.table} '${context.id}' not found`);\n * ```\n *\n * @example Error with context and cause\n * ```ts\n * const { ServiceError, ServiceErr } = createTaggedError('ServiceError')\n *   .withContext<{ operation: string }>()\n *   .withCause<DbServiceError>()\n *   .withMessage(({ context, cause }) =>\n *     `Operation '${context.operation}' failed: ${cause.message}`\n *   );\n * ```\n */\nexport function createTaggedError<TName extends `${string}Error`>(\n\tname: TName,\n): ErrorBuilder<TName> {\n\tconst createBuilder = <\n\t\tTContext extends JsonObject | undefined = undefined,\n\t\tTCause extends AnyTaggedError | undefined = undefined,\n\t>(): ErrorBuilder<TName, TContext, TCause> => {\n\t\treturn {\n\t\t\twithContext<\n\t\t\t\tT extends JsonObject | undefined = JsonObject | undefined,\n\t\t\t>() {\n\t\t\t\treturn createBuilder<T, TCause>();\n\t\t\t},\n\t\t\twithCause<\n\t\t\t\tT extends AnyTaggedError | undefined = AnyTaggedError | undefined,\n\t\t\t>() {\n\t\t\t\treturn createBuilder<TContext, T>();\n\t\t\t},\n\t\t\twithMessage(\n\t\t\t\tfn: MessageFn<TName, TContext, TCause>,\n\t\t\t): FinalFactories<TName, TContext, TCause> {\n\t\t\t\tconst errorConstructor = (\n\t\t\t\t\tinput: ErrorCallInput<TContext, TCause>,\n\t\t\t\t) => {\n\t\t\t\t\tconst messageInput = {\n\t\t\t\t\t\tname,\n\t\t\t\t\t\t...(\"context\" in input ? { context: input.context } : {}),\n\t\t\t\t\t\t...(\"cause\" in input ? { cause: input.cause } : {}),\n\t\t\t\t\t} as MessageInput<TName, TContext, TCause>;\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\tinput.message ?? fn(messageInput),\n\t\t\t\t\t\t...(\"context\" in input ? { context: input.context } : {}),\n\t\t\t\t\t\t...(\"cause\" in input ? { cause: input.cause } : {}),\n\t\t\t\t\t} as unknown as TaggedError<TName, TContext, TCause>;\n\t\t\t\t};\n\n\t\t\t\tconst errName = name.replace(\n\t\t\t\t\t/Error$/,\n\t\t\t\t\t\"Err\",\n\t\t\t\t) as ReplaceErrorWithErr<TName>;\n\t\t\t\tconst errConstructor = (\n\t\t\t\t\tinput: ErrorCallInput<TContext, TCause>,\n\t\t\t\t) => Err(errorConstructor(input));\n\n\t\t\t\treturn {\n\t\t\t\t\t[name]: errorConstructor,\n\t\t\t\t\t[errName]: errConstructor,\n\t\t\t\t} as FinalFactories<TName, TContext, TCause>;\n\t\t\t},\n\t\t} as ErrorBuilder<TName, TContext, TCause>;\n\t};\n\n\treturn createBuilder();\n}\n"],"mappings":";;;;;;;;;AAaA,SAAgB,oBAAoBA,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4JD,SAAgB,kBACfC,MACsB;CACtB,MAAM,gBAAgB,MAGwB;AAC7C,SAAO;GACN,cAEI;AACH,WAAO,eAA0B;GACjC;GACD,YAEI;AACH,WAAO,eAA4B;GACnC;GACD,YACCC,IAC0C;IAC1C,MAAM,mBAAmB,CACxBC,UACI;KACJ,MAAM,eAAe;MACpB;MACA,GAAI,aAAa,QAAQ,EAAE,SAAS,MAAM,QAAS,IAAG,CAAE;MACxD,GAAI,WAAW,QAAQ,EAAE,OAAO,MAAM,MAAO,IAAG,CAAE;KAClD;AAED,YAAO;MACN;MACA,SACC,MAAM,WAAW,GAAG,aAAa;MAClC,GAAI,aAAa,QAAQ,EAAE,SAAS,MAAM,QAAS,IAAG,CAAE;MACxD,GAAI,WAAW,QAAQ,EAAE,OAAO,MAAM,MAAO,IAAG,CAAE;KAClD;IACD;IAED,MAAM,UAAU,KAAK,QACpB,UACA,MACA;IACD,MAAM,iBAAiB,CACtBA,UACI,IAAI,iBAAiB,MAAM,CAAC;AAEjC,WAAO;MACL,OAAO;MACP,UAAU;IACX;GACD;EACD;CACD;AAED,QAAO,eAAe;AACtB"}
+{"version":3,"file":"index.js","names":["error: unknown","name: TName","input: { message: string } & TFields","fn: MessageFn<TFields>","input?: TFields"],"sources":["../../src/error/utils.ts"],"sourcesContent":["import type { TaggedError, JsonObject } from \"./types.js\";\nimport { Err } from \"../result/result.js\";\n\n/**\n * Extracts a readable error message from an unknown error value\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n */\nexport function extractErrorMessage(error: unknown): string {\n\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\t// Final fallback\n\treturn String(error);\n}\n\n/**\n * Constraint that prevents the reserved key `name` from appearing in fields.\n * `message` is not reserved — when `.withMessage()` seals it, `message` is\n * simply absent from the input type. When `.withMessage()` is not used,\n * `message` is a built-in input handled separately from TFields.\n */\ntype NoReservedKeys = { name?: never };\n\n/**\n * Replaces the \"Error\" suffix with \"Err\" suffix in error type names.\n */\ntype ReplaceErrorWithErr<T extends `${string}Error`> =\n\tT extends `${infer TBase}Error` ? `${TBase}Err` : never;\n\n/**\n * Message template function type.\n * Receives the fields (without name/message) and returns a message string.\n */\ntype MessageFn<TFields extends JsonObject> = (input: TFields) => string;\n\n// =============================================================================\n// Factory Input Types\n// =============================================================================\n\n/** Factory input when message is required (no `.withMessage()`). */\ntype RequiredMessageInput<TFields extends JsonObject> = { message: string } &\n\tTFields;\n\n/**\n * Whether the entire input parameter can be omitted (called with no args).\n * True when TFields is empty or all-optional (and message is sealed via withMessage).\n */\ntype IsInputOptional<TFields extends JsonObject> =\n\tPartial<TFields> extends TFields ? true : false;\n\n// =============================================================================\n// Builder & Factory Types\n// =============================================================================\n\n/**\n * Factories returned by `.withMessage()` — message is sealed by the template.\n * `message` is NOT in the input type. Only has factory functions, no chain methods.\n */\ntype SealedFactories<\n\tTName extends `${string}Error`,\n\tTFields extends JsonObject,\n> = {\n\t[K in TName]: IsInputOptional<TFields> extends true\n\t\t? (input?: TFields) => TaggedError<TName, TFields>\n\t\t: (input: TFields) => TaggedError<TName, TFields>;\n} & {\n\t[K in ReplaceErrorWithErr<TName>]: IsInputOptional<TFields> extends true\n\t\t? (input?: TFields) => Err<TaggedError<TName, TFields>>\n\t\t: (input: TFields) => Err<TaggedError<TName, TFields>>;\n};\n\n/**\n * Builder object returned by createTaggedError (and .withFields()).\n * Has factory functions (message required) AND chain methods.\n */\ntype ErrorBuilder<\n\tTName extends `${string}Error`,\n\tTFields extends JsonObject = Record<never, never>,\n> = {\n\t[K in TName]: (\n\t\tinput: RequiredMessageInput<TFields>,\n\t) => TaggedError<TName, TFields>;\n} & {\n\t[K in ReplaceErrorWithErr<TName>]: (\n\t\tinput: RequiredMessageInput<TFields>,\n\t) => Err<TaggedError<TName, TFields>>;\n} & {\n\t/** Defines additional fields spread flat on the error object. */\n\twithFields<T extends JsonObject & NoReservedKeys>(): ErrorBuilder<TName, T>;\n\n\t/**\n\t * Seals the message — the template owns it entirely.\n\t * `message` is NOT in the returned factory's input type.\n\t */\n\twithMessage(fn: MessageFn<TFields>): SealedFactories<TName, TFields>;\n};\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a new tagged error type with a fluent builder API.\n *\n * Returns an object with factory functions immediately available (message required),\n * plus `.withFields<T>()` and `.withMessage(fn)` for further configuration.\n *\n * Two mutually exclusive modes:\n * 1. **No `.withMessage()`**: `message` is required at the call site\n * 2. **With `.withMessage()`**: message is sealed — NOT in the input type\n *\n * @example No fields, message required at call site\n * ```ts\n * const { SimpleError, SimpleErr } = createTaggedError('SimpleError');\n * SimpleErr({ message: 'Something went wrong' });\n * ```\n *\n * @example No fields, with sealed message\n * ```ts\n * const { RecorderBusyError } = createTaggedError('RecorderBusyError')\n *   .withMessage(() => 'A recording is already in progress');\n * RecorderBusyError();  // message always: 'A recording is already in progress'\n * ```\n *\n * @example With fields, message required\n * ```ts\n * const { FsReadError } = createTaggedError('FsReadError')\n *   .withFields<{ path: string }>();\n * FsReadError({ message: 'Failed to read', path: '/etc/config' });\n * ```\n *\n * @example With fields + sealed message (template computes from fields)\n * ```ts\n * const { ResponseError } = createTaggedError('ResponseError')\n *   .withFields<{ status: number }>()\n *   .withMessage(({ status }) => `HTTP ${status}`);\n * ResponseError({ status: 404 });  // message: \"HTTP 404\"\n * ```\n */\nexport function createTaggedError<TName extends `${string}Error`>(\n\tname: TName,\n): ErrorBuilder<TName> {\n\tconst errName = name.replace(\n\t\t/Error$/,\n\t\t\"Err\",\n\t) as ReplaceErrorWithErr<TName>;\n\n\tconst createBuilder = <\n\t\tTFields extends JsonObject = Record<never, never>,\n\t>(): ErrorBuilder<TName, TFields> => {\n\t\tconst errorConstructor = (\n\t\t\tinput: { message: string } & TFields,\n\t\t) => {\n\t\t\tconst { message, ...fields } = input;\n\t\t\treturn {\n\t\t\t\tname,\n\t\t\t\tmessage,\n\t\t\t\t...fields,\n\t\t\t} as unknown as TaggedError<TName, TFields>;\n\t\t};\n\n\t\tconst errConstructor = (\n\t\t\tinput: { message: string } & TFields,\n\t\t) => Err(errorConstructor(input));\n\n\t\treturn {\n\t\t\t[name]: errorConstructor,\n\t\t\t[errName]: errConstructor,\n\n\t\t\twithFields<T extends JsonObject & NoReservedKeys>() {\n\t\t\t\treturn createBuilder<T>();\n\t\t\t},\n\n\t\t\twithMessage(\n\t\t\t\tfn: MessageFn<TFields>,\n\t\t\t): SealedFactories<TName, TFields> {\n\t\t\t\tconst sealedErrorConstructor = (input?: TFields) => {\n\t\t\t\t\tconst fields = (input ?? {}) as TFields;\n\t\t\t\t\tconst message = fn(fields);\n\t\t\t\t\treturn {\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tmessage,\n\t\t\t\t\t\t...fields,\n\t\t\t\t\t} as unknown as TaggedError<TName, TFields>;\n\t\t\t\t};\n\n\t\t\t\tconst sealedErrConstructor = (input?: TFields) =>\n\t\t\t\t\tErr(sealedErrorConstructor(input));\n\n\t\t\t\treturn {\n\t\t\t\t\t[name]: sealedErrorConstructor,\n\t\t\t\t\t[errName]: sealedErrConstructor,\n\t\t\t\t} as SealedFactories<TName, TFields>;\n\t\t\t},\n\t\t} as ErrorBuilder<TName, TFields>;\n\t};\n\n\treturn createBuilder();\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,oBAAoBA,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8HD,SAAgB,kBACfC,MACsB;CACtB,MAAM,UAAU,KAAK,QACpB,UACA,MACA;CAED,MAAM,gBAAgB,MAEe;EACpC,MAAM,mBAAmB,CACxBC,UACI;GACJ,MAAM,EAAE,QAAS,GAAG,QAAQ,GAAG;AAC/B,UAAO;IACN;IACA;IACA,GAAG;GACH;EACD;EAED,MAAM,iBAAiB,CACtBA,UACI,IAAI,iBAAiB,MAAM,CAAC;AAEjC,SAAO;IACL,OAAO;IACP,UAAU;GAEX,aAAoD;AACnD,WAAO,eAAkB;GACzB;GAED,YACCC,IACkC;IAClC,MAAM,yBAAyB,CAACC,UAAoB;KACnD,MAAM,SAAU,SAAS,CAAE;KAC3B,MAAM,UAAU,GAAG,OAAO;AAC1B,YAAO;MACN;MACA;MACA,GAAG;KACH;IACD;IAED,MAAM,uBAAuB,CAACA,UAC7B,IAAI,uBAAuB,MAAM,CAAC;AAEnC,WAAO;MACL,OAAO;MACP,UAAU;IACX;GACD;EACD;CACD;AAED,QAAO,eAAe;AACtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wellcrafted",
-	"version": "0.31.0",
+	"version": "0.32.0",
 	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
 	"type": "module",
 	"files": [