wellcrafted 0.34.1 → 0.36.0

package/dist/error/index.d.ts

@@ -1,113 +1,4 @@
-import { Err } from "../result-xH3TbSDF.js";
-
-//#region src/error/types.d.ts
-
-/**
- * Base type for any tagged error, used as a minimum constraint.
- */
-type AnyTaggedError = {
-  name: string;
-  message: string;
-};
-/**
- * Constructor return must include `message: string`.
- * JSON serializability is a convention, not enforced at the type level
- * (optional fields produce `T | undefined` which breaks `JsonObject`).
- */
-type ErrorBody = {
-  message: string;
-};
-/**
- * Per-key validation: tells the user exactly what `name` will be stamped as.
- * If a user provides `name` in the return object, they see a descriptive error.
- */
-type ValidateErrorBody<K extends string> = {
-  message: string;
-  name?: `The 'name' key is reserved as '${K}'. Remove it.`;
-};
-/** The config: each key is a variant name, each value is a constructor function. */
-type ErrorsConfig = Record<string, (...args: any[]) => ErrorBody>;
-/** Validates each config entry, injecting the key-specific `name` reservation message. */
-type ValidatedConfig<T extends ErrorsConfig> = { [K in keyof T & string]: T[K] extends ((...args: infer A) => infer R) ? (...args: A) => R & ValidateErrorBody<K> : T[K] };
-/** Single factory: takes constructor args, returns Err-wrapped error. */
-type ErrorFactory<TName extends string, TFn extends (...args: any[]) => ErrorBody> = { [K in TName]: (...args: Parameters<TFn>) => Err<Readonly<{
-  name: TName;
-} & ReturnType<TFn>>> };
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
-/** Return type of `defineErrors`. Maps each config key to its factory. */
-type DefineErrorsReturn<TConfig extends ErrorsConfig> = UnionToIntersection<{ [K in keyof TConfig & string]: ErrorFactory<K, TConfig[K]> }[keyof TConfig & string]>;
-/** Extract the error type from a single factory. */
-type InferError<T> = T extends ((...args: any[]) => Err<infer R>) ? R : never;
-/** Extract union of ALL error types from a defineErrors return. */
-type InferErrors<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => Err<infer R>) ? R : never }[keyof T];
-//#endregion
-//#region src/error/defineErrors.d.ts
-/**
- * Defines a set of typed error factories using Rust-style namespaced variants.
- *
- * Each key is a short variant name (the namespace provides context). Every
- * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch
- * handlers. The variant name is stamped as `name` on the error object.
- *
- * @example
- * ```ts
- * const HttpError = defineErrors({
- *   Connection: ({ cause }: { cause: unknown }) => ({
- *     message: `Failed to connect: ${extractErrorMessage(cause)}`,
- *     cause,
- *   }),
- *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({
- *     message: `HTTP ${status}`,
- *     status,
- *   }),
- *   Parse: ({ cause }: { cause: unknown }) => ({
- *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,
- *     cause,
- *   }),
- * });
- *
- * type HttpError = InferErrors<typeof HttpError>;
- *
- * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>
- * ```
- *
- * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The
- * mapping is nearly 1:1:
- *
- * - `enum HttpError` → `const HttpError = defineErrors(...)`
- * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`
- * - `#[error("Failed: {cause}")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``
- * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`
- * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`
- *
- * The equivalent Rust `thiserror` enum:
- * ```rust
- * #[derive(Error, Debug)]
- * enum HttpError {
- *     #[error("Failed to connect: {cause}")]
- *     Connection { cause: String },
- *
- *     #[error("HTTP {status}")]
- *     Response { status: u16, body_message: Option<String> },
- *
- *     #[error("Failed to parse response body: {cause}")]
- *     Parse { cause: String },
- * }
- * ```
- */
-declare function defineErrors<const TConfig extends ErrorsConfig>(config: TConfig & ValidatedConfig<TConfig>): DefineErrorsReturn<TConfig>;
-//# sourceMappingURL=defineErrors.d.ts.map
-//#endregion
-//#region src/error/extractErrorMessage.d.ts
-/**
- * Extracts a readable error message from an unknown error value
- *
- * @param error - The unknown error to extract a message from
- * @returns A string representation of the error
- */
-declare function extractErrorMessage(error: unknown): string;
-//# sourceMappingURL=extractErrorMessage.d.ts.map
-
-//#endregion
-export { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig, defineErrors, extractErrorMessage };
-//# sourceMappingURL=index.d.ts.map
+import "../result-DKwq9BCr.js";
+import { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig } from "../types-tXXk7K9Q.js";
+import { defineErrors, extractErrorMessage } from "../index-B9PnZCTt.js";
+export { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig, defineErrors, extractErrorMessage };

package/dist/error/index.js

@@ -1,107 +1,4 @@
-import { Err } from "../result-BRfWC87j.js";
+import "../result-C5cJ1_WU.js";
+import { defineErrors, extractErrorMessage } from "../error-Dy9wXt5_.js";
 
-//#region src/error/defineErrors.ts
-/**
-* Defines a set of typed error factories using Rust-style namespaced variants.
-*
-* Each key is a short variant name (the namespace provides context). Every
-* factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch
-* handlers. The variant name is stamped as `name` on the error object.
-*
-* @example
-* ```ts
-* const HttpError = defineErrors({
-*   Connection: ({ cause }: { cause: unknown }) => ({
-*     message: `Failed to connect: ${extractErrorMessage(cause)}`,
-*     cause,
-*   }),
-*   Response: ({ status }: { status: number; bodyMessage?: string }) => ({
-*     message: `HTTP ${status}`,
-*     status,
-*   }),
-*   Parse: ({ cause }: { cause: unknown }) => ({
-*     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,
-*     cause,
-*   }),
-* });
-*
-* type HttpError = InferErrors<typeof HttpError>;
-*
-* const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>
-* ```
-*
-* Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The
-* mapping is nearly 1:1:
-*
-* - `enum HttpError` → `const HttpError = defineErrors(...)`
-* - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`
-* - `#[error("Failed: {cause}")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``
-* - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`
-* - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`
-*
-* The equivalent Rust `thiserror` enum:
-* ```rust
-* #[derive(Error, Debug)]
-* enum HttpError {
-*     #[error("Failed to connect: {cause}")]
-*     Connection { cause: String },
-*
-*     #[error("HTTP {status}")]
-*     Response { status: u16, body_message: Option<String> },
-*
-*     #[error("Failed to parse response body: {cause}")]
-*     Parse { cause: String },
-* }
-* ```
-*/
-function defineErrors(config) {
-	const result = {};
-	for (const [name, ctor] of Object.entries(config)) result[name] = (...args) => {
-		const body = ctor(...args);
-		return Err(Object.freeze({
-			...body,
-			name
-		}));
-	};
-	return result;
-}
-
-//#endregion
-//#region src/error/extractErrorMessage.ts
-/**
-* Extracts a readable error message from an unknown error value
-*
-* @param error - The unknown error to extract a message from
-* @returns A string representation of the error
-*/
-function extractErrorMessage(error) {
-	if (error instanceof Error) return error.message;
-	if (typeof error === "string") return error;
-	if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") return String(error);
-	if (typeof error === "symbol") return error.toString();
-	if (error === null) return "null";
-	if (error === void 0) return "undefined";
-	if (Array.isArray(error)) return JSON.stringify(error);
-	if (typeof error === "object") {
-		const errorObj = error;
-		const messageProps = [
-			"message",
-			"error",
-			"description",
-			"title",
-			"reason",
-			"details"
-		];
-		for (const prop of messageProps) if (prop in errorObj && typeof errorObj[prop] === "string") return errorObj[prop];
-		try {
-			return JSON.stringify(error);
-		} catch {
-			return String(error);
-		}
-	}
-	return String(error);
-}
-
-//#endregion
-export { defineErrors, extractErrorMessage };
-//# sourceMappingURL=index.js.map
+export { defineErrors, extractErrorMessage };

package/dist/error-Dy9wXt5_.js

@@ -0,0 +1,107 @@
+import { Err } from "./result-C5cJ1_WU.js";
+
+//#region src/error/defineErrors.ts
+/**
+* Defines a set of typed error factories using Rust-style namespaced variants.
+*
+* Each key is a short variant name (the namespace provides context). Every
+* factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch
+* handlers. The variant name is stamped as `name` on the error object.
+*
+* @example
+* ```ts
+* const HttpError = defineErrors({
+*   Connection: ({ cause }: { cause: unknown }) => ({
+*     message: `Failed to connect: ${extractErrorMessage(cause)}`,
+*     cause,
+*   }),
+*   Response: ({ status }: { status: number; bodyMessage?: string }) => ({
+*     message: `HTTP ${status}`,
+*     status,
+*   }),
+*   Parse: ({ cause }: { cause: unknown }) => ({
+*     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,
+*     cause,
+*   }),
+* });
+*
+* type HttpError = InferErrors<typeof HttpError>;
+*
+* const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>
+* ```
+*
+* Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The
+* mapping is nearly 1:1:
+*
+* - `enum HttpError` → `const HttpError = defineErrors(...)`
+* - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`
+* - `#[error("Failed: {cause}")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``
+* - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`
+* - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`
+*
+* The equivalent Rust `thiserror` enum:
+* ```rust
+* #[derive(Error, Debug)]
+* enum HttpError {
+*     #[error("Failed to connect: {cause}")]
+*     Connection { cause: String },
+*
+*     #[error("HTTP {status}")]
+*     Response { status: u16, body_message: Option<String> },
+*
+*     #[error("Failed to parse response body: {cause}")]
+*     Parse { cause: String },
+* }
+* ```
+*/
+function defineErrors(config) {
+	const result = {};
+	for (const [name, ctor] of Object.entries(config)) result[name] = (...args) => {
+		const body = ctor(...args);
+		return Err(Object.freeze({
+			...body,
+			name
+		}));
+	};
+	return result;
+}
+
+//#endregion
+//#region src/error/extractErrorMessage.ts
+/**
+* Extracts a readable error message from an unknown error value
+*
+* @param error - The unknown error to extract a message from
+* @returns A string representation of the error
+*/
+function extractErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") return String(error);
+	if (typeof error === "symbol") return error.toString();
+	if (error === null) return "null";
+	if (error === void 0) return "undefined";
+	if (Array.isArray(error)) return JSON.stringify(error);
+	if (typeof error === "object") {
+		const errorObj = error;
+		const messageProps = [
+			"message",
+			"error",
+			"description",
+			"title",
+			"reason",
+			"details"
+		];
+		for (const prop of messageProps) if (prop in errorObj && typeof errorObj[prop] === "string") return errorObj[prop];
+		try {
+			return JSON.stringify(error);
+		} catch {
+			return String(error);
+		}
+	}
+	return String(error);
+}
+
+//#endregion
+export { defineErrors, extractErrorMessage };
+//# sourceMappingURL=error-Dy9wXt5_.js.map

package/dist/error-Dy9wXt5_.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-Dy9wXt5_.js","names":["config: TConfig & ValidatedConfig<TConfig>","result: Record<string, unknown>","error: unknown"],"sources":["../src/error/defineErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":["import { Err } from \"../result/result.js\";\nimport type {\n\tDefineErrorsReturn,\n\tErrorsConfig,\n\tValidatedConfig,\n} from \"./types.js\";\n\n/**\n * Defines a set of typed error factories using Rust-style namespaced variants.\n *\n * Each key is a short variant name (the namespace provides context). Every\n * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch\n * handlers. The variant name is stamped as `name` on the error object.\n *\n * @example\n * ```ts\n * const HttpError = defineErrors({\n *   Connection: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to connect: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({\n *     message: `HTTP ${status}`,\n *     status,\n *   }),\n *   Parse: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n * });\n *\n * type HttpError = InferErrors<typeof HttpError>;\n *\n * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>\n * ```\n *\n * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The\n * mapping is nearly 1:1:\n *\n * - `enum HttpError` → `const HttpError = defineErrors(...)`\n * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`\n * - `#[error(\"Failed: {cause}\")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``\n * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`\n * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`\n *\n * The equivalent Rust `thiserror` enum:\n * ```rust\n * #[derive(Error, Debug)]\n * enum HttpError {\n *     #[error(\"Failed to connect: {cause}\")]\n *     Connection { cause: String },\n *\n *     #[error(\"HTTP {status}\")]\n *     Response { status: u16, body_message: Option<String> },\n *\n *     #[error(\"Failed to parse response body: {cause}\")]\n *     Parse { cause: String },\n * }\n * ```\n */\nexport function defineErrors<const TConfig extends ErrorsConfig>(\n\tconfig: TConfig & ValidatedConfig<TConfig>,\n): DefineErrorsReturn<TConfig> {\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const [name, ctor] of Object.entries(config)) {\n\t\tresult[name] = (...args: unknown[]) => {\n\t\t\tconst body = (ctor as (...a: unknown[]) => Record<string, unknown>)(\n\t\t\t\t...args,\n\t\t\t);\n\t\t\treturn Err(Object.freeze({ ...body, name }));\n\t\t};\n\t}\n\n\treturn result as DefineErrorsReturn<TConfig>;\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,aACfA,QAC8B;CAC9B,MAAMC,SAAkC,CAAE;AAE1C,MAAK,MAAM,CAAC,MAAM,KAAK,IAAI,OAAO,QAAQ,OAAO,CAChD,QAAO,QAAQ,CAAC,GAAG,SAAoB;EACtC,MAAM,OAAO,AAAC,KACb,GAAG,KACH;AACD,SAAO,IAAI,OAAO,OAAO;GAAE,GAAG;GAAM;EAAM,EAAC,CAAC;CAC5C;AAGF,QAAO;AACP;;;;;;;;;;ACrED,SAAgB,oBAAoBC,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"}

package/dist/index-B9PnZCTt.d.ts

@@ -0,0 +1,73 @@
+import { DefineErrorsReturn, ErrorsConfig, ValidatedConfig } from "./types-tXXk7K9Q.js";
+
+//#region src/error/defineErrors.d.ts
+
+/**
+ * Defines a set of typed error factories using Rust-style namespaced variants.
+ *
+ * Each key is a short variant name (the namespace provides context). Every
+ * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch
+ * handlers. The variant name is stamped as `name` on the error object.
+ *
+ * @example
+ * ```ts
+ * const HttpError = defineErrors({
+ *   Connection: ({ cause }: { cause: unknown }) => ({
+ *     message: `Failed to connect: ${extractErrorMessage(cause)}`,
+ *     cause,
+ *   }),
+ *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({
+ *     message: `HTTP ${status}`,
+ *     status,
+ *   }),
+ *   Parse: ({ cause }: { cause: unknown }) => ({
+ *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,
+ *     cause,
+ *   }),
+ * });
+ *
+ * type HttpError = InferErrors<typeof HttpError>;
+ *
+ * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>
+ * ```
+ *
+ * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The
+ * mapping is nearly 1:1:
+ *
+ * - `enum HttpError` → `const HttpError = defineErrors(...)`
+ * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`
+ * - `#[error("Failed: {cause}")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``
+ * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`
+ * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`
+ *
+ * The equivalent Rust `thiserror` enum:
+ * ```rust
+ * #[derive(Error, Debug)]
+ * enum HttpError {
+ *     #[error("Failed to connect: {cause}")]
+ *     Connection { cause: String },
+ *
+ *     #[error("HTTP {status}")]
+ *     Response { status: u16, body_message: Option<String> },
+ *
+ *     #[error("Failed to parse response body: {cause}")]
+ *     Parse { cause: String },
+ * }
+ * ```
+ */
+declare function defineErrors<const TConfig extends ErrorsConfig>(config: TConfig & ValidatedConfig<TConfig>): DefineErrorsReturn<TConfig>;
+//# sourceMappingURL=defineErrors.d.ts.map
+//#endregion
+//#region src/error/extractErrorMessage.d.ts
+/**
+ * Extracts a readable error message from an unknown error value
+ *
+ * @param error - The unknown error to extract a message from
+ * @returns A string representation of the error
+ */
+declare function extractErrorMessage(error: unknown): string;
+//# sourceMappingURL=extractErrorMessage.d.ts.map
+
+//#endregion
+export { defineErrors, extractErrorMessage };
+//# sourceMappingURL=index-B9PnZCTt.d.ts.map

package/dist/index-B9PnZCTt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-B9PnZCTt.d.ts","names":[],"sources":["../src/error/defineErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":[],"mappings":";;;;;;AA4DA;;;;;;;;AAEqB;;;;ACxDrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBDsDgB,mCAAmC,sBAC1C,UAAU,gBAAgB,WAChC,mBAAmB;;;;;;;AAFtB;;;AACS,iBCvDO,mBAAA,CDuDP,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA"}

package/dist/{index-D_iQ3bBj.d.ts → index-DnoV2ZDO.d.ts}

@@ -1,4 +1,4 @@
-import { Err, Ok, Result } from "./result-xH3TbSDF.js";
+import { Err, Ok, Result } from "./result-DKwq9BCr.js";
 
 //#region src/result/utils.d.ts
 
@@ -25,4 +25,4 @@ declare function partitionResults<T, E>(results: Result<T, E>[]): {
 //# sourceMappingURL=utils.d.ts.map
 //#endregion
 export { partitionResults };
-//# sourceMappingURL=index-D_iQ3bBj.d.ts.map
+//# sourceMappingURL=index-DnoV2ZDO.d.ts.map

package/dist/{index-D_iQ3bBj.d.ts.map → index-DnoV2ZDO.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"index-D_iQ3bBj.d.ts","names":[],"sources":["../src/result/utils.ts"],"sourcesContent":[],"mappings":";;;;;;AAmBA;;;;;;;;;AAK+B;;;;;iBALf,gCAAgC,OAAO,GAAG;OAK7C,GAAG;QAAY,IAAI"}
+{"version":3,"file":"index-DnoV2ZDO.d.ts","names":[],"sources":["../src/result/utils.ts"],"sourcesContent":[],"mappings":";;;;;;AAmBA;;;;;;;;;AAK+B;;;;;iBALf,gCAAgC,OAAO,GAAG;OAK7C,GAAG;QAAY,IAAI"}

package/dist/json.d.ts

@@ -1,4 +1,11 @@
+import { Err, Result } from "./result-DKwq9BCr.js";
+import { InferError } from "./types-tXXk7K9Q.js";
+import "./index-B9PnZCTt.js";
+import "./tap-err-CFhHBPfH.js";
+import "./index-DnoV2ZDO.js";
+
 //#region src/json.d.ts
+
 /**
  * JSON-serializable value types.
  * Ensures data can be safely serialized via JSON.stringify.
@@ -19,7 +26,56 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
  * A record where every value is a {@link JsonValue}.
  */
 type JsonObject = Record<string, JsonValue>;
+/**
+ * Constructs a {@link JsonParseError}. Returns `Err<JsonParseError>` directly,
+ * ready to return from a `trySync`/`tryAsync` catch handler.
+ */
+declare const JsonParseError: (args_0: {
+  cause: unknown;
+}) => Err<Readonly<{
+  name: "JsonParseError";
+} & {
+  message: string;
+  cause: unknown;
+}>>;
+/**
+ * The error {@link parseJson} produces when its input is not valid JSON.
+ *
+ * JSON parsing has exactly one failure mode (the engine throws a `SyntaxError`),
+ * so this is a single variant. A valid-JSON-but-wrong-shape value is not a
+ * parse failure: validate the returned {@link JsonValue} against a schema for
+ * that case.
+ */
+type JsonParseError = InferError<typeof JsonParseError>;
+/**
+ * Parses a JSON string into a {@link JsonValue}, returning a `Result` instead
+ * of throwing.
+ *
+ * Unlike `JSON.parse`, which returns `any` and throws on malformed input, this:
+ * - types the success value as {@link JsonValue}, forcing you to narrow or
+ *   validate before treating it as a known shape
+ * - reports failure as a tagged {@link JsonParseError} rather than an exception
+ *
+ * No reviver argument is accepted. A reviver can return arbitrary values, which
+ * would make the {@link JsonValue} success type a lie.
+ *
+ * @param text - The JSON string to parse.
+ * @returns `Ok<JsonValue>` on success, `Err<JsonParseError>` on malformed input.
+ *
+ * @example
+ * ```ts
+ * import { parseJson } from "wellcrafted/json";
+ *
+ * const { data, error } = parseJson('{"count":1}');
+ * if (error) {
+ *   console.error(error.message); // "Failed to parse JSON: ..."
+ * } else {
+ *   data; // JsonValue — narrow or validate before using
+ * }
+ * ```
+ */
+declare function parseJson(text: string): Result<JsonValue, JsonParseError>;
 //# sourceMappingURL=json.d.ts.map
 //#endregion
-export { JsonObject, JsonValue };
+export { JsonObject, JsonParseError, JsonValue, parseJson };
 //# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","names":[],"sources":["../src/json.ts"],"sourcesContent":[],"mappings":";;AAYA;;;;AAM6B;AAM7B;;;;AAA+B;;KAZnB,SAAA,sCAKT;iBACiB;;;;;;KAMR,UAAA,GAAa,eAAe"}
+{"version":3,"file":"json.d.ts","names":[],"sources":["../src/json.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAmBA;;;;AAM6B;AAM7B;;AAAwC,KAZ5B,SAAA,GAY4B,MAAA,GAAA,MAAA,GAAA,OAAA,GAAA,IAAA,GAPrC,SAOqC,EAAA,GAAA;EAAS,CAAA,GAAxB,EAAA,MAAA,CAAA,EANL,SAMK;AAAM,CAAA;AAU/B;;;;KAVY,UAAA,GAAa,eAAe;AAyBxC;;;;AAAuC,cAfxB,cAewB,EAAA,CAAA,MAAA,EAAA;EA6BvB,KAAA,EAAA,OAAS;CAAA,EAAA,MAAA,CAvCvB,QAuCuB,CAAA;EAAA,IAAuB,EAAA,gBAAA;CAAS,GAAA;EAAgB,OAAhC,EAAA,MAAA;EAAM,KAAA,EAAA,OAAA;;;;;;;;;;KA7BnC,cAAA,GAAiB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6B/B,SAAA,gBAAyB,OAAO,WAAW"}

package/dist/json.js

@@ -0,0 +1,51 @@
+import { trySync } from "./result-C5cJ1_WU.js";
+import { defineErrors, extractErrorMessage } from "./error-Dy9wXt5_.js";
+import "./tap-err-CP-re1HT.js";
+import "./result-C9V2Knvt.js";
+
+//#region src/json.ts
+/**
+* Constructs a {@link JsonParseError}. Returns `Err<JsonParseError>` directly,
+* ready to return from a `trySync`/`tryAsync` catch handler.
+*/
+const { JsonParseError } = defineErrors({ JsonParseError: ({ cause }) => ({
+	message: `Failed to parse JSON: ${extractErrorMessage(cause)}`,
+	cause
+}) });
+/**
+* Parses a JSON string into a {@link JsonValue}, returning a `Result` instead
+* of throwing.
+*
+* Unlike `JSON.parse`, which returns `any` and throws on malformed input, this:
+* - types the success value as {@link JsonValue}, forcing you to narrow or
+*   validate before treating it as a known shape
+* - reports failure as a tagged {@link JsonParseError} rather than an exception
+*
+* No reviver argument is accepted. A reviver can return arbitrary values, which
+* would make the {@link JsonValue} success type a lie.
+*
+* @param text - The JSON string to parse.
+* @returns `Ok<JsonValue>` on success, `Err<JsonParseError>` on malformed input.
+*
+* @example
+* ```ts
+* import { parseJson } from "wellcrafted/json";
+*
+* const { data, error } = parseJson('{"count":1}');
+* if (error) {
+*   console.error(error.message); // "Failed to parse JSON: ..."
+* } else {
+*   data; // JsonValue — narrow or validate before using
+* }
+* ```
+*/
+function parseJson(text) {
+	return trySync({
+		try: () => JSON.parse(text),
+		catch: (cause) => JsonParseError({ cause })
+	});
+}
+
+//#endregion
+export { JsonParseError, parseJson };
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","names":["text: string"],"sources":["../src/json.ts"],"sourcesContent":["import {\n\tdefineErrors,\n\textractErrorMessage,\n\ttype InferError,\n} from \"./error/index.js\";\nimport { type Result, trySync } from \"./result/index.js\";\n\n/**\n * JSON-serializable value types.\n * Ensures data can be safely serialized via JSON.stringify.\n *\n * @example\n * ```typescript\n * import type { JsonValue, JsonObject } from \"wellcrafted/json\";\n *\n * const value: JsonValue = { key: [1, \"two\", true, null] };\n * const obj: JsonObject = { name: \"Alice\", age: 30 };\n * ```\n */\nexport type JsonValue =\n\t| string\n\t| number\n\t| boolean\n\t| null\n\t| JsonValue[]\n\t| { [key: string]: JsonValue };\n\n/**\n * JSON-serializable object type.\n * A record where every value is a {@link JsonValue}.\n */\nexport type JsonObject = Record<string, JsonValue>;\n\n// =============================================================================\n// Parsing\n// =============================================================================\n\n/**\n * Constructs a {@link JsonParseError}. Returns `Err<JsonParseError>` directly,\n * ready to return from a `trySync`/`tryAsync` catch handler.\n */\nexport const { JsonParseError } = defineErrors({\n\tJsonParseError: ({ cause }: { cause: unknown }) => ({\n\t\tmessage: `Failed to parse JSON: ${extractErrorMessage(cause)}`,\n\t\tcause,\n\t}),\n});\n\n/**\n * The error {@link parseJson} produces when its input is not valid JSON.\n *\n * JSON parsing has exactly one failure mode (the engine throws a `SyntaxError`),\n * so this is a single variant. A valid-JSON-but-wrong-shape value is not a\n * parse failure: validate the returned {@link JsonValue} against a schema for\n * that case.\n */\nexport type JsonParseError = InferError<typeof JsonParseError>;\n\n/**\n * Parses a JSON string into a {@link JsonValue}, returning a `Result` instead\n * of throwing.\n *\n * Unlike `JSON.parse`, which returns `any` and throws on malformed input, this:\n * - types the success value as {@link JsonValue}, forcing you to narrow or\n *   validate before treating it as a known shape\n * - reports failure as a tagged {@link JsonParseError} rather than an exception\n *\n * No reviver argument is accepted. A reviver can return arbitrary values, which\n * would make the {@link JsonValue} success type a lie.\n *\n * @param text - The JSON string to parse.\n * @returns `Ok<JsonValue>` on success, `Err<JsonParseError>` on malformed input.\n *\n * @example\n * ```ts\n * import { parseJson } from \"wellcrafted/json\";\n *\n * const { data, error } = parseJson('{\"count\":1}');\n * if (error) {\n *   console.error(error.message); // \"Failed to parse JSON: ...\"\n * } else {\n *   data; // JsonValue — narrow or validate before using\n * }\n * ```\n */\nexport function parseJson(text: string): Result<JsonValue, JsonParseError> {\n\treturn trySync({\n\t\ttry: () => JSON.parse(text) as JsonValue,\n\t\tcatch: (cause) => JsonParseError({ cause }),\n\t});\n}\n"],"mappings":";;;;;;;;;;AAyCA,MAAa,EAAE,gBAAgB,GAAG,aAAa,EAC9C,gBAAgB,CAAC,EAAE,OAA2B,MAAM;CACnD,SAAS,CAAC,sBAAsB,EAAE,oBAAoB,MAAM,EAAE;CAC9D;AACA,GACD,EAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCF,SAAgB,UAAUA,MAAiD;AAC1E,QAAO,QAAQ;EACd,KAAK,MAAM,KAAK,MAAM,KAAK;EAC3B,OAAO,CAAC,UAAU,eAAe,EAAE,MAAO,EAAC;CAC3C,EAAC;AACF"}