wellcrafted 0.21.4 → 0.23.1

package/dist/{result-DucAuR8u.d.ts → result-DRq8PMRe.d.ts}

@@ -234,98 +234,88 @@ declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
  */
 declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
 /**
- * Executes a synchronous operation and wraps its outcome (success or failure) in a `Result<T, E>`.
- *
- * This function attempts to execute the `operation`.
- * - If `operation` completes successfully, its return value is wrapped in an `Ok<T>` variant.
- * - If `operation` throws an exception, the caught exception (of type `unknown`) is passed to
- *   the `mapErr` function. `mapErr` is responsible for transforming this `unknown`
- *   exception into an `Err<E>` variant containing a well-typed error value of type `E`.
- *
- * @template T - The type of the success value returned by the `operation` if it succeeds.
- * @template E - The type of the error value produced by `mapErr` if the `operation` fails.
- * @param options - An object containing the operation and error mapping function.
- * @param options.try - The synchronous operation to execute. This function is expected to return a value of type `T`.
- * @param options.mapErr - A function that takes the `unknown` exception caught from `options.try`
- *                        and transforms it into an `Err<E>` variant containing a specific error value of type `E`.
- * @returns A `Result<T, E>`: `Ok<T>` if `options.try` succeeds, or `Err<E>` if it throws and `options.mapErr` provides an error variant.
- * @example
- * ```ts
- * function parseJson(jsonString: string): Result<object, SyntaxError> {
- *   return trySync({
- *     try: () => JSON.parse(jsonString),
- *     mapErr: (err: unknown) => {
- *       if (err instanceof SyntaxError) return Err(err);
- *       return Err(new SyntaxError("Unknown parsing error"));
- *     }
- *   });
- * }
+ * Executes a synchronous operation and wraps its outcome in a Result type.
+ *
+ * This function attempts to execute the `try` operation:
+ * - If the `try` operation completes successfully, its return value is wrapped in an `Ok<T>` variant.
+ * - If the `try` operation throws an exception, the caught exception (of type `unknown`) is passed to
+ *   the `catch` function, which transforms it into either an `Ok<T>` (recovery) or `Err<E>` (propagation).
+ *
+ * The return type is automatically narrowed based on what your catch function returns:
+ * - If catch always returns `Ok<T>`, the function returns `Ok<T>` (guaranteed success)
+ * - If catch can return `Err<E>`, the function returns `Result<T, E>` (may succeed or fail)
  *
- * const validResult = parseJson('{"name":"Result"}'); // Ok<{name: string}>
- * const invalidResult = parseJson('invalid json');    // Err<SyntaxError>
+ * @template T - The success value type
+ * @template E - The error value type (when catch can return errors)
+ * @param options - Configuration object
+ * @param options.try - The operation to execute
+ * @param options.catch - Error handler that transforms caught exceptions into either `Ok<T>` (recovery) or `Err<E>` (propagation)
+ * @returns `Ok<T>` if catch always returns Ok (recovery), otherwise `Result<T, E>` (propagation)
  *
- * if (isOk(validResult)) console.log(validResult.data);
- * if (isErr(invalidResult)) console.error(invalidResult.error.message);
+ * @example
+ * ```ts
+ * // Returns Ok<string> - guaranteed success since catch always returns Ok
+ * const alwaysOk = trySync({
+ *   try: () => JSON.parse(input),
+ *   catch: () => Ok("fallback") // Always Ok<T>
+ * });
+ *
+ * // Returns Result<object, string> - may fail since catch can return Err
+ * const mayFail = trySync({
+ *   try: () => JSON.parse(input),
+ *   catch: (err) => Err("Parse failed") // Returns Err<E>
+ * });
  * ```
  */
-declare function trySync<T, E>({
-  try: operation,
-  mapErr
-}: {
+declare function trySync<T>(options: {
   try: () => T;
-  mapErr: (error: unknown) => Err<E>;
+  catch: (error: unknown) => Ok<T>;
+}): Ok<T>;
+declare function trySync<T, E>(options: {
+  try: () => T;
+  catch: (error: unknown) => Err<E>;
 }): Result<T, E>;
 /**
- * Executes an asynchronous operation (returning a `Promise`) and wraps its outcome in a `Promise<Result<T, E>>`.
- *
- * This function attempts to execute the asynchronous `operation`.
- * - If the `Promise` returned by `operation` resolves successfully, its resolved value is wrapped in an `Ok<T>` variant.
- * - If the `Promise` returned by `operation` rejects, or if `operation` itself throws an exception synchronously,
- *   the caught exception/rejection reason (of type `unknown`) is passed to the `mapErr` function.
- *   `mapErr` is responsible for transforming this `unknown` error into an `Err<E>` variant containing
- *   a well-typed error value of type `E`.
- *
- * The entire outcome (`Ok<T>` or `Err<E>`) is wrapped in a `Promise`.
- *
- * @template T - The type of the success value the `Promise` from `operation` resolves to.
- * @template E - The type of the error value produced by `mapErr` if the `operation` fails or rejects.
- * @param options - An object containing the asynchronous operation and error mapping function.
- * @param options.try - The asynchronous operation to execute. This function must return a `Promise<T>`.
- * @param options.mapErr - A function that takes the `unknown` exception/rejection reason caught from `options.try`
- *                        and transforms it into an `Err<E>` variant containing a specific error value of type `E`.
- *                        This function must return `Err<E>` directly.
- * @returns A `Promise` that resolves to a `Result<T, E>`: `Ok<T>` if `options.try`'s `Promise` resolves,
- *          or `Err<E>` if it rejects/throws and `options.mapErr` provides an error variant.
+ * Executes an asynchronous operation and wraps its outcome in a Promise<Result>.
+ *
+ * This function attempts to execute the `try` operation:
+ * - If the `try` operation resolves successfully, its resolved value is wrapped in an `Ok<T>` variant.
+ * - If the `try` operation rejects or throws an exception, the caught error (of type `unknown`) is passed to
+ *   the `catch` function, which transforms it into either an `Ok<T>` (recovery) or `Err<E>` (propagation).
+ *
+ * The return type is automatically narrowed based on what your catch function returns:
+ * - If catch always returns `Ok<T>`, the function returns `Promise<Ok<T>>` (guaranteed success)
+ * - If catch can return `Err<E>`, the function returns `Promise<Result<T, E>>` (may succeed or fail)
+ *
+ * @template T - The success value type
+ * @template E - The error value type (when catch can return errors)
+ * @param options - Configuration object
+ * @param options.try - The async operation to execute
+ * @param options.catch - Error handler that transforms caught exceptions/rejections into either `Ok<T>` (recovery) or `Err<E>` (propagation)
+ * @returns `Promise<Ok<T>>` if catch always returns Ok (recovery), otherwise `Promise<Result<T, E>>` (propagation)
+ *
  * @example
  * ```ts
- * async function fetchData(url: string): Promise<Result<Response, Error>> {
- *   return tryAsync({
- *     try: async () => fetch(url),
- *     mapErr: (err: unknown) => {
- *       if (err instanceof Error) return Err(err);
- *       return Err(new Error("Network request failed"));
- *     }
- *   });
- * }
- *
- * async function processData() {
- *   const result = await fetchData("/api/data");
- *   if (isOk(result)) {
- *     const response = result.data;
- *     console.log("Data fetched:", await response.json());
- *   } else {
- *     console.error("Fetch error:", result.error.message);
- *   }
- * }
- * processData();
+ * // Returns Promise<Ok<Response>> - guaranteed success since catch always returns Ok
+ * const alwaysOk = tryAsync({
+ *   try: async () => fetch(url),
+ *   catch: () => Ok(new Response()) // Always Ok<T>
+ * });
+ *
+ * // Returns Promise<Result<Response, Error>> - may fail since catch can return Err
+ * const mayFail = tryAsync({
+ *   try: async () => fetch(url),
+ *   catch: (err) => Err(new Error("Fetch failed")) // Returns Err<E>
+ * });
  * ```
  */
-declare function tryAsync<T, E>({
-  try: operation,
-  mapErr
-}: {
+declare function tryAsync<T>(options: {
+  try: () => Promise<T>;
+  catch: (error: unknown) => Ok<T>;
+}): Promise<Ok<T>>;
+declare function tryAsync<T, E>(options: {
   try: () => Promise<T>;
-  mapErr: (error: unknown) => Err<E>;
+  catch: (error: unknown) => Err<E>;
 }): Promise<Result<T, E>>;
 /**
  * Resolves a value that may or may not be wrapped in a `Result`, returning the final value.
@@ -426,4 +416,4 @@ declare function resolve<T, E>(value: T | Result<T, E>): T;
 //# sourceMappingURL=result.d.ts.map
 //#endregion
 export { Err, ExtractErrFromResult, ExtractOkFromResult, Ok, Result, UnwrapErr, UnwrapOk, isErr, isOk, isResult, resolve, tryAsync, trySync, unwrap };
-//# sourceMappingURL=result-DucAuR8u.d.ts.map
+//# sourceMappingURL=result-DRq8PMRe.d.ts.map

package/dist/result-DRq8PMRe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-DRq8PMRe.d.ts","names":[],"sources":["../src/result/result.ts"],"sourcesContent":[],"mappings":";;AAWA;AAaA;AAqCA;;;;;;AAAsC;AAiBtC;AAAgE,KAnEpD,EAmEoD,CAAA,CAAA,CAAA,GAAA;EAAA,IAApC,EAnEA,CAmEA;EAAC,KAAM,EAAA,IAAA;CAAC;AAAF;AAiBlC;;;;;AAAqC;AAWrC;;;;AAAsE,KAlF1D,GAkF0D,CAAA,CAAA,CAAA,GAAA;EAAO,KAAA,EAlF/C,CAkF+C;EAcjE,IAAA,EAAA,IAAA;CAAoB;;;;AAA8C;AAuB9E;;;;;;AACI;AAqBJ;;;;;;AAGI;AAgCJ;;;;;AAEkB;AAoClB;;;;;;;AAA8D;AAyB9D;;;AAA8C,KA1MlC,MA0MkC,CAAA,CAAA,EAAA,CAAA,CAAA,GA1MnB,EA0MmB,CA1MhB,CA0MgB,CAAA,GA1MX,GA0MW,CA1MP,CA0MO,CAAA;;;;AAAkB;AAsChE;;;;;;;AAGM;AAEN;;;AAEgC,cAtOnB,EAsOmB,EAAA,CAAA,CAAA,CAAA,CAAA,IAAA,EAtOJ,CAsOI,EAAA,GAtOA,EAsOA,CAtOG,CAsOH,CAAA;;;;;AACtB;AAmDV;;;;;;;;;AAGW;AAEW,cA9QT,GA8QiB,EAAA,CAAA,CAAA,CAAA,CAAA,KAAA,EA9QA,CA8QA,EAAA,GA9QI,GA8QJ,CA9QQ,CA8QR,CAAA;;;;;;;;;;AAGnB,KAtQC,mBAsQD,CAAA,UAtQ+B,MAsQ/B,CAAA,OAAA,EAAA,OAAA,CAAA,CAAA,GAtQ2D,OAsQ3D,CArQV,CAqQU,EAAA;EA+GK,KAAA,EAAA,IAAM;CAAA,CAAA;;;;;AAA+B;AAOrD;;;;AAAmD,KA9WvC,oBA8WuC,CAAA,UA9WR,MA8WQ,CAAA,OAAA,EAAA,OAAA,CAAA,CAAA,GA9WoB,OA8WpB,CA7WlD,CA6WkD,EAAA;EAAC,IAAX,EAAA,IAAA;CAAM,CAAA;AAAU;;;;;;;;;;;;;;;;;;KAvV7C,mBAAmB,4BAA4B,UAAU,cAClE;;;;;;;;;;;;;;;;;;;KAqBS,oBAAoB,4BAA4B,UAAU,eAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCa,6DAEJ,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;iBAoCN,mBAAmB,OAAO,GAAG,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;iBAyB/C,oBAAoB,OAAO,GAAG,eAAe,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCjD;aACJ;6BACgB,GAAG;IAC3B,GAAG;iBAES;aACJ;6BACgB,IAAI;IAC5B,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDQ;aACV,QAAQ;6BACQ,GAAG;IAC3B,QAAQ,GAAG;iBAEO;aACV,QAAQ;6BACQ,IAAI;IAC5B,QAAQ,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+GN,qBAAqB,OAAO,GAAG,KAAK;iBAOpC,qBAAqB,IAAI,OAAO,GAAG,KAAK"}

package/dist/{result-DOgvmaNP.js → result-DfuKgZo9.js}

@@ -1,4 +1,4 @@
-import { isOk } from "./result-BPrctj1f.js";
+import { isOk } from "./result-B1iWFqM9.js";
 
 //#region src/result/utils.ts
 /**
@@ -27,4 +27,4 @@ function partitionResults(results) {
 
 //#endregion
 export { partitionResults };
-//# sourceMappingURL=result-DOgvmaNP.js.map
+//# sourceMappingURL=result-DfuKgZo9.js.map

package/dist/{result-DOgvmaNP.js.map → result-DfuKgZo9.js.map}

@@ -1 +1 @@
-{"version":3,"file":"result-DOgvmaNP.js","names":["results: Result<T, E>[]"],"sources":["../src/result/utils.ts"],"sourcesContent":["import type { Err, Ok, Result } from \"./result.js\";\nimport { isOk } from \"./result.js\";\n\n/**\n * Partitions an array of Result objects into two separate arrays based on their status.\n *\n * @template T - The success type\n * @template E - The error type\n * @param results - An array of Result objects to partition\n * @returns An object containing two arrays:\n *   - `oks`: Array of successful Result objects (Ok<T>[])\n *   - `errs`: Array of error Result objects (Err<E>[])\n *\n * @example\n * const results = [Ok(1), Err(\"error\"), Ok(2)];\n * const { oks, errs } = partitionResults(results);\n * // oks = [Ok(1), Ok(2)]\n * // errs = [Err(\"error\")]\n */\nexport function partitionResults<T, E>(results: Result<T, E>[]) {\n\treturn {\n\t\toks: [],\n\t\terrs: [],\n\t\t...Object.groupBy(results, (result) => (isOk(result) ? \"oks\" : \"errs\")),\n\t} as { oks: Ok<T>[]; errs: Err<E>[] };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,iBAAuBA,SAAyB;AAC/D,QAAO;EACN,KAAK,CAAE;EACP,MAAM,CAAE;EACR,GAAG,OAAO,QAAQ,SAAS,CAAC,WAAY,KAAK,OAAO,GAAG,QAAQ,OAAQ;CACvE;AACD"}
+{"version":3,"file":"result-DfuKgZo9.js","names":["results: Result<T, E>[]"],"sources":["../src/result/utils.ts"],"sourcesContent":["import type { Err, Ok, Result } from \"./result.js\";\nimport { isOk } from \"./result.js\";\n\n/**\n * Partitions an array of Result objects into two separate arrays based on their status.\n *\n * @template T - The success type\n * @template E - The error type\n * @param results - An array of Result objects to partition\n * @returns An object containing two arrays:\n *   - `oks`: Array of successful Result objects (Ok<T>[])\n *   - `errs`: Array of error Result objects (Err<E>[])\n *\n * @example\n * const results = [Ok(1), Err(\"error\"), Ok(2)];\n * const { oks, errs } = partitionResults(results);\n * // oks = [Ok(1), Ok(2)]\n * // errs = [Err(\"error\")]\n */\nexport function partitionResults<T, E>(results: Result<T, E>[]) {\n\treturn {\n\t\toks: [],\n\t\terrs: [],\n\t\t...Object.groupBy(results, (result) => (isOk(result) ? \"oks\" : \"errs\")),\n\t} as { oks: Ok<T>[]; errs: Err<E>[] };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,iBAAuBA,SAAyB;AAC/D,QAAO;EACN,KAAK,CAAE;EACP,MAAM,CAAE;EACR,GAAG,OAAO,QAAQ,SAAS,CAAC,WAAY,KAAK,OAAO,GAAG,QAAQ,OAAQ;CACvE;AACD"}

package/package.json

@@ -1,56 +1,56 @@
 {
-  "name": "wellcrafted",
-  "version": "0.21.4",
-  "description": "Delightful TypeScript patterns for elegant, type-safe applications",
-  "type": "module",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    "./result": {
-      "types": "./dist/result/index.d.ts",
-      "import": "./dist/result/index.js"
-    },
-    "./error": {
-      "types": "./dist/error/index.d.ts",
-      "import": "./dist/error/index.js"
-    },
-    "./brand": {
-      "types": "./dist/brand.d.ts",
-      "import": "./dist/brand.js"
-    },
-    "./query": {
-      "types": "./dist/query/index.d.ts",
-      "import": "./dist/query/index.js"
-    }
-  },
-  "keywords": [
-    "typescript",
-    "delightful",
-    "elegant",
-    "type-safe",
-    "well-crafted",
-    "polished",
-    "utilities",
-    "result",
-    "error-handling",
-    "brand-types"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@changesets/cli": "^2.27.10",
-    "@tanstack/query-core": "^5.82.0",
-    "tsdown": "^0.12.5",
-    "typescript": "^5.8.3"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "format": "biome format --write .",
-    "lint": "biome lint --write .",
-    "release": "pnpm run build && changeset version && changeset publish"
-  }
-}
+	"name": "wellcrafted",
+	"version": "0.23.1",
+	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
+	"type": "module",
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"exports": {
+		"./result": {
+			"types": "./dist/result/index.d.ts",
+			"import": "./dist/result/index.js"
+		},
+		"./error": {
+			"types": "./dist/error/index.d.ts",
+			"import": "./dist/error/index.js"
+		},
+		"./brand": {
+			"types": "./dist/brand.d.ts",
+			"import": "./dist/brand.js"
+		},
+		"./query": {
+			"types": "./dist/query/index.d.ts",
+			"import": "./dist/query/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"format": "biome format --write .",
+		"lint": "biome lint --write .",
+		"release": "pnpm run build && changeset version && changeset publish"
+	},
+	"keywords": [
+		"typescript",
+		"delightful",
+		"elegant",
+		"type-safe",
+		"well-crafted",
+		"polished",
+		"utilities",
+		"result",
+		"error-handling",
+		"brand-types"
+	],
+	"author": "",
+	"license": "MIT",
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.3",
+		"@changesets/cli": "^2.27.10",
+		"@tanstack/query-core": "^5.82.0",
+		"tsdown": "^0.12.5",
+		"typescript": "^5.8.3"
+	}
+}

package/dist/result-DucAuR8u.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"result-DucAuR8u.d.ts","names":[],"sources":["../src/result/result.ts"],"sourcesContent":[],"mappings":";;AAWA;AAaA;AAqCA;;;;;;AAAsC;AAiBtC;AAAgE,KAnEpD,EAmEoD,CAAA,CAAA,CAAA,GAAA;EAAA,IAApC,EAnEA,CAmEA;EAAC,KAAM,EAAA,IAAA;CAAC;AAAF;AAiBlC;;;;;AAAqC;AAWrC;;;;AAAsE,KAlF1D,GAkF0D,CAAA,CAAA,CAAA,GAAA;EAAO,KAAA,EAlF/C,CAkF+C;EAcjE,IAAA,EAAA,IAAA;CAAoB;;;;AAA8C;AAuB9E;;;;;;AACI;AAqBJ;;;;;;AAGI;AAgCJ;;;;;AAEkB;AAoClB;;;;;;;AAA8D;AAyB9D;;;AAA8C,KA1MlC,MA0MkC,CAAA,CAAA,EAAA,CAAA,CAAA,GA1MnB,EA0MmB,CA1MhB,CA0MgB,CAAA,GA1MX,GA0MW,CA1MP,CA0MO,CAAA;;;;AAAkB;AAuChE;;;;;;;;;;AAMU;AAsDY,cA5RT,EA4RiB,EAAA,CAAA,CAAA,CAAA,CAAA,IAAA,EA5RF,CA4RE,EAAA,GA5RE,EA4RF,CA5RK,CA4RL,CAAA;;;;;;;;;;;;AAMnB;AAuGX;;;AAA+C,cAxXlC,GAwXkC,EAAA,CAAA,CAAA,CAAA,CAAA,KAAA,EAxXjB,CAwXiB,EAAA,GAxXb,GAwXa,CAxXT,CAwXS,CAAA;;;AAAM;AAOrD;;;;;;AAAwD,KApX5C,mBAoX4C,CAAA,UApXd,MAoXc,CAAA,OAAA,EAAA,OAAA,CAAA,CAAA,GApXc,OAoXd,CAnXvD,CAmXuD,EAAA;EAAC,KAAA,EAAA,IAAA;;;;;;;;;;;KAtW7C,+BAA+B,4BAA4B,QACtE;;;;;;;;;;;;;;;;;;;;;KAsBW,mBAAmB,4BAA4B,UAAU,cAClE;;;;;;;;;;;;;;;;;;;KAqBS,oBAAoB,4BAA4B,UAAU,eAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCa,6DAEJ,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;iBAoCN,mBAAmB,OAAO,GAAG,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;iBAyB/C,oBAAoB,OAAO,GAAG,eAAe,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCjD;OACV;;;aAGM;8BACiB,IAAI;IAC7B,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsDQ;OAChB;;;aAGM,QAAQ;8BACS,IAAI;IAC7B,QAAQ,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuGN,qBAAqB,OAAO,GAAG,KAAK;iBAOpC,qBAAqB,IAAI,OAAO,GAAG,KAAK"}