wellcrafted 0.15.0

package/dist/index.js

@@ -0,0 +1,385 @@
+//#region src/result.ts
+/**
+* Constructs an `Ok<T>` variant, representing a successful outcome.
+*
+* This factory function creates the success variant of a `Result`.
+* It wraps the provided `data` (the success value) and ensures the `error` property is `null`.
+*
+* @template T - The type of the success value.
+* @param data - The success value to be wrapped in the `Ok` variant.
+* @returns An `Ok<T>` object with the provided data and `error` set to `null`.
+* @example
+* ```ts
+* const successfulResult = Ok("Operation completed successfully");
+* // successfulResult is { data: "Operation completed successfully", error: null }
+* ```
+*/
+const Ok = (data) => ({
+	data,
+	error: null
+});
+/**
+* Constructs an `Err<E>` variant, representing a failure outcome.
+*
+* This factory function creates the error variant of a `Result`.
+* It wraps the provided `error` (the error value) and ensures the `data` property is `null`.
+*
+* @template E - The type of the error value.
+* @param error - The error value to be wrapped in the `Err` variant. This value represents the specific error that occurred.
+* @returns An `Err<E>` object with the provided error and `data` set to `null`.
+* @example
+* ```ts
+* const failedResult = Err(new TypeError("Invalid input"));
+* // failedResult is { error: TypeError("Invalid input"), data: null }
+* ```
+*/
+const Err = (error) => ({
+	error,
+	data: null
+});
+/**
+* Type guard to runtime check if an unknown value is a valid `Result<T, E>`.
+*
+* A value is considered a valid `Result` if:
+* 1. It is a non-null object.
+* 2. It has both `data` and `error` properties.
+* 3. Exactly one of `data` or `error` is `null`. The other must be non-`null`.
+*
+* This function does not validate the types of `data` or `error` beyond `null` checks.
+*
+* @template T - The expected type of the success value if the value is an `Ok` variant (defaults to `unknown`).
+* @template E - The expected type of the error value if the value is an `Err` variant (defaults to `unknown`).
+* @param value - The value to check.
+* @returns `true` if the value conforms to the `Result` structure, `false` otherwise.
+*          If `true`, TypeScript's type system will narrow `value` to `Result<T, E>`.
+* @example
+* ```ts
+* declare const someValue: unknown;
+*
+* if (isResult<string, Error>(someValue)) {
+*   // someValue is now typed as Result<string, Error>
+*   if (isOk(someValue)) {
+*     console.log(someValue.data); // string
+*   } else {
+*     console.error(someValue.error); // Error
+*   }
+* }
+* ```
+*/
+function isResult(value) {
+	const isNonNullObject = typeof value === "object" && value !== null;
+	if (!isNonNullObject) return false;
+	const hasDataProperty = "data" in value;
+	const hasErrorProperty = "error" in value;
+	if (!hasDataProperty || !hasErrorProperty) return false;
+	const isBothNull = value.data === null && value.error === null;
+	if (isBothNull) return false;
+	const isNeitherNull = value.data !== null && value.error !== null;
+	if (isNeitherNull) return false;
+	return true;
+}
+/**
+* Type guard to runtime check if a `Result<T, E>` is an `Ok<T>` variant.
+*
+* This function narrows the type of a `Result` to `Ok<T>` if it represents a successful outcome.
+* An `Ok<T>` variant is identified by its `error` property being `null`.
+*
+* @template T - The success value type.
+* @template E - The error value type.
+* @param result - The `Result<T, E>` to check.
+* @returns `true` if the `result` is an `Ok<T>` variant, `false` otherwise.
+*          If `true`, TypeScript's type system will narrow `result` to `Ok<T>`.
+* @example
+* ```ts
+* declare const myResult: Result<number, string>;
+*
+* if (isOk(myResult)) {
+*   // myResult is now typed as Ok<number>
+*   console.log("Success value:", myResult.data); // myResult.data is number
+* }
+* ```
+*/
+function isOk(result) {
+	return result.error === null;
+}
+/**
+* Type guard to runtime check if a `Result<T, E>` is an `Err<E>` variant.
+*
+* This function narrows the type of a `Result` to `Err<E>` if it represents a failure outcome.
+* An `Err<E>` variant is identified by its `error` property being non-`null` (and thus `data` being `null`).
+*
+* @template T - The success value type.
+* @template E - The error value type.
+* @param result - The `Result<T, E>` to check.
+* @returns `true` if the `result` is an `Err<E>` variant, `false` otherwise.
+*          If `true`, TypeScript's type system will narrow `result` to `Err<E>`.
+* @example
+* ```ts
+* declare const myResult: Result<number, string>;
+*
+* if (isErr(myResult)) {
+*   // myResult is now typed as Err<string>
+*   console.error("Error value:", myResult.error); // myResult.error is string
+* }
+* ```
+*/
+function isErr(result) {
+	return result.error !== null;
+}
+/**
+* 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 `mapError` function. `mapError` is responsible for transforming this `unknown`
+*   exception into a well-typed error value of type `E`. This error value is then wrapped
+*   in an `Err<E>` variant.
+*
+* @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 `mapError` 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.mapError - A function that takes the `unknown` exception caught from `options.try`
+*                         and transforms it into a specific error value of type `E`. This function
+*                         is crucial for creating a well-typed error for the `Err<E>` variant.
+* @returns A `Result<T, E>`: `Ok<T>` if `options.try` succeeds, or `Err<E>` if it throws and `options.mapError` provides an error value.
+* @example
+* ```ts
+* function parseJson(jsonString: string): Result<object, SyntaxError> {
+*   return trySync({
+*     try: () => JSON.parse(jsonString),
+*     mapError: (err: unknown) => {
+*       if (err instanceof SyntaxError) return err;
+*       return new SyntaxError("Unknown parsing error");
+*     }
+*   });
+* }
+*
+* const validResult = parseJson('{"name":"Result"}'); // Ok<{name: string}>
+* const invalidResult = parseJson('invalid json');    // Err<SyntaxError>
+*
+* if (isOk(validResult)) console.log(validResult.data);
+* if (isErr(invalidResult)) console.error(invalidResult.error.message);
+* ```
+*/
+function trySync({ try: operation, mapError }) {
+	try {
+		const data = operation();
+		return Ok(data);
+	} catch (error) {
+		return Err(mapError(error));
+	}
+}
+/**
+* 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 `mapError` function.
+*   `mapError` is responsible for transforming this `unknown` error into a well-typed error value of type `E`.
+*   This error value is then wrapped in an `Err<E>` variant.
+*
+* 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 `mapError` 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.mapError - A function that takes the `unknown` exception/rejection reason caught from `options.try`
+*                         and transforms it into a specific error value of type `E`. This function
+*                         is crucial for creating a well-typed error for the `Err<E>` variant.
+* @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.mapError` provides an error value.
+* @example
+* ```ts
+* async function fetchData(url: string): Promise<Result<Response, Error>> {
+*   return tryAsync({
+*     try: async () => fetch(url),
+*     mapError: (err: unknown) => {
+*       if (err instanceof Error) return err;
+*       return 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();
+* ```
+*/
+async function tryAsync({ try: operation, mapError }) {
+	try {
+		const data = await operation();
+		return Ok(data);
+	} catch (error) {
+		return Err(mapError(error));
+	}
+}
+/**
+* Unwraps a value if it is a `Result`, otherwise returns the value itself.
+*
+* - If `value` is an `Ok<T>` variant, its `data` (the success value) is returned.
+* - If `value` is an `Err<E>` variant, its `error` (the error value) is thrown.
+* - If `value` is not a `Result` (i.e., it's already a plain value of type `T`),
+*   it is returned as-is.
+*
+* This function is useful for situations where an operation might return either a
+* direct value or a `Result` wrapping a value/error, and you want to
+* uniformly access the value or propagate the error via throwing.
+*
+* @template T - The type of the success value (if `value` is `Ok<T>`) or the type of the plain value.
+* @template E - The type of the error value (if `value` is `Err<E>`).
+* @param value - The value to unwrap. It can be a `Result<T, E>` or a plain value of type `T`.
+* @returns The success value of type `T` if `value` is `Ok<T>` or if `value` is a plain `T`.
+* @throws The error value `E` if `value` is an `Err<E>` variant.
+*
+* @example
+* ```ts
+* // Example with an Ok variant
+* const okResult = Ok("success data");
+* const unwrappedOk = unwrapIfResult(okResult); // "success data"
+*
+* // Example with an Err variant
+* const errResult = Err(new Error("failure"));
+* try {
+*   unwrapIfResult(errResult);
+* } catch (e) {
+*   console.error(e.message); // "failure"
+* }
+*
+* // Example with a plain value
+* const plainValue = "plain data";
+* const unwrappedPlain = unwrapIfResult(plainValue); // "plain data"
+*
+* // Example with a function that might return Result or plain value
+* declare function mightReturnResult(): string | Result<string, Error>;
+* const outcome = mightReturnResult();
+* try {
+*  const finalValue = unwrapIfResult(outcome); // handles both cases
+*  console.log("Final value:", finalValue);
+* } catch (e) {
+*  console.error("Operation failed:", e);
+* }
+* ```
+*/
+function unwrapIfResult(value) {
+	if (isResult(value)) {
+		if (isOk(value)) return value.data;
+		throw value.error;
+	}
+	return value;
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Partitions an array of Result objects into two separate arrays based on their status.
+*
+* @template T - The success type
+* @template E - The error type
+* @param results - An array of Result objects to partition
+* @returns An object containing two arrays:
+*   - `oks`: Array of successful Result objects (Ok<T>[])
+*   - `errs`: Array of error Result objects (Err<E>[])
+*
+* @example
+* const results = [Ok(1), Err("error"), Ok(2)];
+* const { oks, errs } = partitionResults(results);
+* // oks = [Ok(1), Ok(2)]
+* // errs = [Err("error")]
+*/
+function partitionResults(results) {
+	return {
+		oks: [],
+		errs: [],
+		...Object.groupBy(results, (result) => isOk(result) ? "oks" : "errs")
+	};
+}
+
+//#endregion
+//#region src/error/utils.ts
+/**
+* Extracts a readable error message from an unknown error value
+*
+* This utility is commonly used in mapError functions when converting
+* unknown errors to typed error objects in the Result system.
+*
+* @param error - The unknown error to extract a message from
+* @returns A string representation of the error
+*
+* @example
+* ```ts
+* // With native Error
+* const error = new Error("Something went wrong");
+* const message = extractErrorMessage(error); // "Something went wrong"
+*
+* // With string error
+* const stringError = "String error";
+* const message2 = extractErrorMessage(stringError); // "String error"
+*
+* // With object error
+* const unknownError = { code: 500, details: "Server error" };
+* const message3 = extractErrorMessage(unknownError); // '{"code":500,"details":"Server error"}'
+*
+* // Used in mapError function
+* const result = await tryAsync({
+*   try: () => riskyOperation(),
+*   mapError: (error): NetworkError => ({
+*     name: "NetworkError",
+*     message: extractErrorMessage(error),
+*     context: { operation: "riskyOperation" },
+*     cause: error,
+*   }),
+* });
+* ```
+*/
+function extractErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	if (typeof error === "object" && error !== null) {
+		const errorObj = error;
+		if (typeof errorObj.message === "string") return errorObj.message;
+		if (typeof errorObj.error === "string") return errorObj.error;
+		if (typeof errorObj.description === "string") return errorObj.description;
+		try {
+			return JSON.stringify(error);
+		} catch {
+			return String(error);
+		}
+	}
+	return String(error);
+}
+
+//#endregion
+//#region src/error/types.ts
+function createTryFns(name) {
+	return {
+		trySync: ({ try: operation, mapErr }) => trySync({
+			try: operation,
+			mapErr: (error) => ({
+				...mapErr(error),
+				name
+			})
+		}),
+		tryAsync: ({ try: operation, mapErr }) => tryAsync({
+			try: operation,
+			mapErr: (error) => ({
+				...mapErr(error),
+				name
+			})
+		})
+	};
+}
+
+//#endregion
+export { Err, Ok, createTryFns, extractErrorMessage, isErr, isOk, isResult, partitionResults, tryAsync, trySync, unwrapIfResult };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["data: T","error: E","value: unknown","result: Result<T, E>","value: T | Result<T, E>","results: Result<T, E>[]","error: unknown","name: TName"],"sources":["../src/result.ts","../src/utils.ts","../src/error/utils.ts","../src/error/types.ts"],"sourcesContent":["/**\n * Represents the successful outcome of an operation, encapsulating the success value.\n *\n * This is the 'Ok' variant of the `Result` type. It holds a `data` property\n * of type `T` (the success value) and an `error` property explicitly set to `null`,\n * signifying no error occurred.\n *\n * Use this type in conjunction with `Err<E>` and `Result<T, E>`.\n *\n * @template T - The type of the success value contained within.\n */\nexport type Ok<T> = { data: T; error: null };\n\n/**\n * Represents the failure outcome of an operation, encapsulating the error value.\n *\n * This is the 'Err' variant of the `Result` type. It holds an `error` property\n * of type `E` (the error value) and a `data` property explicitly set to `null`,\n * signifying that no success value is present due to the failure.\n *\n * Use this type in conjunction with `Ok<T>` and `Result<T, E>`.\n *\n * @template E - The type of the error value contained within.\n */\nexport type Err<E> = { error: E; data: null };\n\n/**\n * A type that represents the outcome of an operation that can either succeed or fail.\n *\n * `Result<T, E>` is a discriminated union type with two possible variants:\n * - `Ok<T>`: Represents a successful outcome, containing a `data` field with the success value of type `T`.\n *            In this case, the `error` field is `null`.\n * - `Err<E>`: Represents a failure outcome, containing an `error` field with the error value of type `E`.\n *            In this case, the `data` field is `null`.\n *\n * This type promotes explicit error handling by requiring developers to check\n * the variant of the `Result` before accessing its potential value or error.\n * It helps avoid runtime errors often associated with implicit error handling (e.g., relying on `try-catch` for all errors).\n *\n * @template T - The type of the success value if the operation is successful (held in `Ok<T>`).\n * @template E - The type of the error value if the operation fails (held in `Err<E>`).\n * @example\n * ```ts\n * function divide(numerator: number, denominator: number): Result<number, string> {\n *   if (denominator === 0) {\n *     return Err(\"Cannot divide by zero\");\n *   }\n *   return Ok(numerator / denominator);\n * }\n *\n * const result1 = divide(10, 2);\n * if (isOk(result1)) {\n *   console.log(\"Success:\", result1.data); // Output: Success: 5\n * }\n *\n * const result2 = divide(10, 0);\n * if (isErr(result2)) {\n *   console.error(\"Failure:\", result2.error); // Output: Failure: Cannot divide by zero\n * }\n * ```\n */\nexport type Result<T, E> = Ok<T> | Err<E>;\n\n/**\n * Constructs an `Ok<T>` variant, representing a successful outcome.\n *\n * This factory function creates the success variant of a `Result`.\n * It wraps the provided `data` (the success value) and ensures the `error` property is `null`.\n *\n * @template T - The type of the success value.\n * @param data - The success value to be wrapped in the `Ok` variant.\n * @returns An `Ok<T>` object with the provided data and `error` set to `null`.\n * @example\n * ```ts\n * const successfulResult = Ok(\"Operation completed successfully\");\n * // successfulResult is { data: \"Operation completed successfully\", error: null }\n * ```\n */\nexport const Ok = <T>(data: T): Ok<T> => ({ data, error: null });\n\n/**\n * Constructs an `Err<E>` variant, representing a failure outcome.\n *\n * This factory function creates the error variant of a `Result`.\n * It wraps the provided `error` (the error value) and ensures the `data` property is `null`.\n *\n * @template E - The type of the error value.\n * @param error - The error value to be wrapped in the `Err` variant. This value represents the specific error that occurred.\n * @returns An `Err<E>` object with the provided error and `data` set to `null`.\n * @example\n * ```ts\n * const failedResult = Err(new TypeError(\"Invalid input\"));\n * // failedResult is { error: TypeError(\"Invalid input\"), data: null }\n * ```\n */\nexport const Err = <E>(error: E): Err<E> => ({ error, data: null });\n\n/**\n * Utility type to extract the `Ok<T>` variant from a `Result<T, E>` union type.\n *\n * If `R` is a `Result` type (e.g., `Result<string, Error>`), this type will resolve\n * to `Ok<string>`. This can be useful in generic contexts or for type narrowing.\n *\n * @template R - The `Result<T, E>` union type from which to extract the `Ok<T>` variant.\n *             Must extend `Result<unknown, unknown>`.\n */\nexport type ExtractOkFromResult<R extends Result<unknown, unknown>> = Extract<\n\tR,\n\t{ error: null }\n>;\n\n/**\n * Utility type to extract the `Err<E>` variant from a `Result<T, E>` union type.\n *\n * If `R` is a `Result` type (e.g., `Result<string, Error>`), this type will resolve\n * to `Err<Error>`. This can be useful in generic contexts or for type narrowing.\n *\n * @template R - The `Result<T, E>` union type from which to extract the `Err<E>` variant.\n *             Must extend `Result<unknown, unknown>`.\n */\nexport type ExtractErrFromResult<R extends Result<unknown, unknown>> = Extract<\n\tR,\n\t{ data: null }\n>;\n\n/**\n * Utility type to extract the success value's type `T` from a `Result<T, E>` type.\n *\n * If `R` is an `Ok<T>` variant (or a `Result<T, E>` that could be an `Ok<T>`),\n * this type resolves to `T`. If `R` can only be an `Err<E>` variant, it resolves to `never`.\n * This is useful for obtaining the type of the `data` field when you know you have a success.\n *\n * @template R - The `Result<T, E>` type from which to extract the success value's type.\n *             Must extend `Result<unknown, unknown>`.\n * @example\n * ```ts\n * type MyResult = Result<number, string>;\n * type SuccessValueType = UnwrapOk<MyResult>; // SuccessValueType is number\n *\n * type MyErrorResult = Err<string>;\n * type ErrorValueType = UnwrapOk<MyErrorResult>; // ErrorValueType is never\n * ```\n */\nexport type UnwrapOk<R extends Result<unknown, unknown>> = R extends Ok<infer U>\n\t? U\n\t: never;\n\n/**\n * Utility type to extract the error value's type `E` from a `Result<T, E>` type.\n *\n * If `R` is an `Err<E>` variant (or a `Result<T, E>` that could be an `Err<E>`),\n * this type resolves to `E`. If `R` can only be an `Ok<T>` variant, it resolves to `never`.\n * This is useful for obtaining the type of the `error` field when you know you have a failure.\n *\n * @template R - The `Result<T, E>` type from which to extract the error value's type.\n *             Must extend `Result<unknown, unknown>`.\n * @example\n * ```ts\n * type MyResult = Result<number, string>;\n * type ErrorValueType = UnwrapErr<MyResult>; // ErrorValueType is string\n *\n * type MySuccessResult = Ok<number>;\n * type SuccessValueType = UnwrapErr<MySuccessResult>; // SuccessValueType is never\n * ```\n */\nexport type UnwrapErr<R extends Result<unknown, unknown>> = R extends Err<\n\tinfer E\n>\n\t? E\n\t: never;\n\n/**\n * Type guard to runtime check if an unknown value is a valid `Result<T, E>`.\n *\n * A value is considered a valid `Result` if:\n * 1. It is a non-null object.\n * 2. It has both `data` and `error` properties.\n * 3. Exactly one of `data` or `error` is `null`. The other must be non-`null`.\n *\n * This function does not validate the types of `data` or `error` beyond `null` checks.\n *\n * @template T - The expected type of the success value if the value is an `Ok` variant (defaults to `unknown`).\n * @template E - The expected type of the error value if the value is an `Err` variant (defaults to `unknown`).\n * @param value - The value to check.\n * @returns `true` if the value conforms to the `Result` structure, `false` otherwise.\n *          If `true`, TypeScript's type system will narrow `value` to `Result<T, E>`.\n * @example\n * ```ts\n * declare const someValue: unknown;\n *\n * if (isResult<string, Error>(someValue)) {\n *   // someValue is now typed as Result<string, Error>\n *   if (isOk(someValue)) {\n *     console.log(someValue.data); // string\n *   } else {\n *     console.error(someValue.error); // Error\n *   }\n * }\n * ```\n */\nexport function isResult<T = unknown, E = unknown>(\n\tvalue: unknown,\n): value is Result<T, E> {\n\tconst isNonNullObject = typeof value === \"object\" && value !== null;\n\tif (!isNonNullObject) return false;\n\n\tconst hasDataProperty = \"data\" in value;\n\tconst hasErrorProperty = \"error\" in value;\n\tif (!hasDataProperty || !hasErrorProperty) return false;\n\n\tconst isBothNull = value.data === null && value.error === null;\n\tif (isBothNull) return false;\n\n\tconst isNeitherNull = value.data !== null && value.error !== null;\n\tif (isNeitherNull) return false;\n\n\t// Exactly one property is null\n\treturn true;\n}\n\n/**\n * Type guard to runtime check if a `Result<T, E>` is an `Ok<T>` variant.\n *\n * This function narrows the type of a `Result` to `Ok<T>` if it represents a successful outcome.\n * An `Ok<T>` variant is identified by its `error` property being `null`.\n *\n * @template T - The success value type.\n * @template E - The error value type.\n * @param result - The `Result<T, E>` to check.\n * @returns `true` if the `result` is an `Ok<T>` variant, `false` otherwise.\n *          If `true`, TypeScript's type system will narrow `result` to `Ok<T>`.\n * @example\n * ```ts\n * declare const myResult: Result<number, string>;\n *\n * if (isOk(myResult)) {\n *   // myResult is now typed as Ok<number>\n *   console.log(\"Success value:\", myResult.data); // myResult.data is number\n * }\n * ```\n */\nexport function isOk<T, E>(result: Result<T, E>): result is Ok<T> {\n\treturn result.error === null;\n}\n\n/**\n * Type guard to runtime check if a `Result<T, E>` is an `Err<E>` variant.\n *\n * This function narrows the type of a `Result` to `Err<E>` if it represents a failure outcome.\n * An `Err<E>` variant is identified by its `error` property being non-`null` (and thus `data` being `null`).\n *\n * @template T - The success value type.\n * @template E - The error value type.\n * @param result - The `Result<T, E>` to check.\n * @returns `true` if the `result` is an `Err<E>` variant, `false` otherwise.\n *          If `true`, TypeScript's type system will narrow `result` to `Err<E>`.\n * @example\n * ```ts\n * declare const myResult: Result<number, string>;\n *\n * if (isErr(myResult)) {\n *   // myResult is now typed as Err<string>\n *   console.error(\"Error value:\", myResult.error); // myResult.error is string\n * }\n * ```\n */\nexport function isErr<T, E>(result: Result<T, E>): result is Err<E> {\n\treturn result.error !== null; // Equivalent to result.data === null\n}\n\n/**\n * Executes a synchronous operation and wraps its outcome (success or failure) in a `Result<T, E>`.\n *\n * This function attempts to execute the `operation`.\n * - If `operation` completes successfully, its return value is wrapped in an `Ok<T>` variant.\n * - If `operation` throws an exception, the caught exception (of type `unknown`) is passed to\n *   the `mapError` function. `mapError` is responsible for transforming this `unknown`\n *   exception into a well-typed error value of type `E`. This error value is then wrapped\n *   in an `Err<E>` variant.\n *\n * @template T - The type of the success value returned by the `operation` if it succeeds.\n * @template E - The type of the error value produced by `mapError` if the `operation` fails.\n * @param options - An object containing the operation and error mapping function.\n * @param options.try - The synchronous operation to execute. This function is expected to return a value of type `T`.\n * @param options.mapError - A function that takes the `unknown` exception caught from `options.try`\n *                         and transforms it into a specific error value of type `E`. This function\n *                         is crucial for creating a well-typed error for the `Err<E>` variant.\n * @returns A `Result<T, E>`: `Ok<T>` if `options.try` succeeds, or `Err<E>` if it throws and `options.mapError` provides an error value.\n * @example\n * ```ts\n * function parseJson(jsonString: string): Result<object, SyntaxError> {\n *   return trySync({\n *     try: () => JSON.parse(jsonString),\n *     mapError: (err: unknown) => {\n *       if (err instanceof SyntaxError) return err;\n *       return new SyntaxError(\"Unknown parsing error\");\n *     }\n *   });\n * }\n *\n * const validResult = parseJson('{\"name\":\"Result\"}'); // Ok<{name: string}>\n * const invalidResult = parseJson('invalid json');    // Err<SyntaxError>\n *\n * if (isOk(validResult)) console.log(validResult.data);\n * if (isErr(invalidResult)) console.error(invalidResult.error.message);\n * ```\n */\nexport function trySync<T, E>({\n\ttry: operation,\n\tmapError,\n}: {\n\ttry: () => T;\n\tmapError: (error: unknown) => E;\n}): Result<T, E> {\n\ttry {\n\t\tconst data = operation();\n\t\treturn Ok(data);\n\t} catch (error) {\n\t\treturn Err(mapError(error));\n\t}\n}\n\n/**\n * Executes an asynchronous operation (returning a `Promise`) and wraps its outcome in a `Promise<Result<T, E>>`.\n *\n * This function attempts to execute the asynchronous `operation`.\n * - If the `Promise` returned by `operation` resolves successfully, its resolved value is wrapped in an `Ok<T>` variant.\n * - If the `Promise` returned by `operation` rejects, or if `operation` itself throws an exception synchronously,\n *   the caught exception/rejection reason (of type `unknown`) is passed to the `mapError` function.\n *   `mapError` is responsible for transforming this `unknown` error into a well-typed error value of type `E`.\n *   This error value is then wrapped in an `Err<E>` variant.\n *\n * The entire outcome (`Ok<T>` or `Err<E>`) is wrapped in a `Promise`.\n *\n * @template T - The type of the success value the `Promise` from `operation` resolves to.\n * @template E - The type of the error value produced by `mapError` if the `operation` fails or rejects.\n * @param options - An object containing the asynchronous operation and error mapping function.\n * @param options.try - The asynchronous operation to execute. This function must return a `Promise<T>`.\n * @param options.mapError - A function that takes the `unknown` exception/rejection reason caught from `options.try`\n *                         and transforms it into a specific error value of type `E`. This function\n *                         is crucial for creating a well-typed error for the `Err<E>` variant.\n * @returns A `Promise` that resolves to a `Result<T, E>`: `Ok<T>` if `options.try`'s `Promise` resolves,\n *          or `Err<E>` if it rejects/throws and `options.mapError` provides an error value.\n * @example\n * ```ts\n * async function fetchData(url: string): Promise<Result<Response, Error>> {\n *   return tryAsync({\n *     try: async () => fetch(url),\n *     mapError: (err: unknown) => {\n *       if (err instanceof Error) return err;\n *       return new Error(\"Network request failed\");\n *     }\n *   });\n * }\n *\n * async function processData() {\n *   const result = await fetchData(\"/api/data\");\n *   if (isOk(result)) {\n *     const response = result.data;\n *     console.log(\"Data fetched:\", await response.json());\n *   } else {\n *     console.error(\"Fetch error:\", result.error.message);\n *   }\n * }\n * processData();\n * ```\n */\nexport async function tryAsync<T, E>({\n\ttry: operation,\n\tmapError,\n}: {\n\ttry: () => Promise<T>;\n\tmapError: (error: unknown) => E;\n}): Promise<Result<T, E>> {\n\ttry {\n\t\tconst data = await operation();\n\t\treturn Ok(data);\n\t} catch (error) {\n\t\treturn Err(mapError(error));\n\t}\n}\n\n/**\n * Unwraps a value if it is a `Result`, otherwise returns the value itself.\n *\n * - If `value` is an `Ok<T>` variant, its `data` (the success value) is returned.\n * - If `value` is an `Err<E>` variant, its `error` (the error value) is thrown.\n * - If `value` is not a `Result` (i.e., it's already a plain value of type `T`),\n *   it is returned as-is.\n *\n * This function is useful for situations where an operation might return either a\n * direct value or a `Result` wrapping a value/error, and you want to\n * uniformly access the value or propagate the error via throwing.\n *\n * @template T - The type of the success value (if `value` is `Ok<T>`) or the type of the plain value.\n * @template E - The type of the error value (if `value` is `Err<E>`).\n * @param value - The value to unwrap. It can be a `Result<T, E>` or a plain value of type `T`.\n * @returns The success value of type `T` if `value` is `Ok<T>` or if `value` is a plain `T`.\n * @throws The error value `E` if `value` is an `Err<E>` variant.\n *\n * @example\n * ```ts\n * // Example with an Ok variant\n * const okResult = Ok(\"success data\");\n * const unwrappedOk = unwrapIfResult(okResult); // \"success data\"\n *\n * // Example with an Err variant\n * const errResult = Err(new Error(\"failure\"));\n * try {\n *   unwrapIfResult(errResult);\n * } catch (e) {\n *   console.error(e.message); // \"failure\"\n * }\n *\n * // Example with a plain value\n * const plainValue = \"plain data\";\n * const unwrappedPlain = unwrapIfResult(plainValue); // \"plain data\"\n *\n * // Example with a function that might return Result or plain value\n * declare function mightReturnResult(): string | Result<string, Error>;\n * const outcome = mightReturnResult();\n * try {\n *  const finalValue = unwrapIfResult(outcome); // handles both cases\n *  console.log(\"Final value:\", finalValue);\n * } catch (e) {\n *  console.error(\"Operation failed:\", e);\n * }\n * ```\n */\nexport function unwrapIfResult<T, E>(value: T | Result<T, E>): T {\n\tif (isResult<T, E>(value)) {\n\t\tif (isOk(value)) {\n\t\t\treturn value.data;\n\t\t}\n\t\t// If it's a Result and not Ok, it must be Err.\n\t\t// The type guard isResult<T,E>(value) and isOk(value) already refine the type.\n\t\t// So, 'value' here is known to be Err<E>.\n\t\tthrow value.error;\n\t}\n\n\t// If it's not a Result type, return the value as-is.\n\t// 'value' here is known to be of type T.\n\treturn value;\n}\n","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","/**\n * Extracts a readable error message from an unknown error value\n *\n * This utility is commonly used in mapError functions when converting\n * unknown errors to typed error objects in the Result system.\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n *\n * @example\n * ```ts\n * // With native Error\n * const error = new Error(\"Something went wrong\");\n * const message = extractErrorMessage(error); // \"Something went wrong\"\n *\n * // With string error\n * const stringError = \"String error\";\n * const message2 = extractErrorMessage(stringError); // \"String error\"\n *\n * // With object error\n * const unknownError = { code: 500, details: \"Server error\" };\n * const message3 = extractErrorMessage(unknownError); // '{\"code\":500,\"details\":\"Server error\"}'\n *\n * // Used in mapError function\n * const result = await tryAsync({\n *   try: () => riskyOperation(),\n *   mapError: (error): NetworkError => ({\n *     name: \"NetworkError\",\n *     message: extractErrorMessage(error),\n *     context: { operation: \"riskyOperation\" },\n *     cause: error,\n *   }),\n * });\n * ```\n */\nexport function extractErrorMessage(error: unknown): string {\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\tif (typeof error === \"string\") {\n\t\treturn error;\n\t}\n\n\tif (typeof error === \"object\" && error !== null) {\n\t\t// Check for common error properties\n\t\tconst errorObj = error as Record<string, unknown>;\n\t\tif (typeof errorObj.message === \"string\") {\n\t\t\treturn errorObj.message;\n\t\t}\n\t\tif (typeof errorObj.error === \"string\") {\n\t\t\treturn errorObj.error;\n\t\t}\n\t\tif (typeof errorObj.description === \"string\") {\n\t\t\treturn errorObj.description;\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\treturn String(error);\n}\n","import { tryAsync, trySync } from \"../result.js\";\nimport { extractErrorMessage } from \"./utils.js\";\n\nexport type BaseError = Readonly<{\n\tname: string;\n\tmessage: string;\n\tcontext: Record<string, unknown>;\n\tcause: unknown;\n}>;\n\n/**\n * Creates a tagged error type for type-safe error handling.\n * Uses the `name` property as a discriminator for tagged unions.\n *\n * Error types should follow the convention of ending with \"Error\" suffix.\n * The Err data structure wraps these error types in the Result system.\n *\n * @example\n * ```ts\n * type ValidationError = TaggedError<\"ValidationError\">\n * type NetworkError = TaggedError<\"NetworkError\">\n *\n * function handleError(error: ValidationError | NetworkError) {\n *   switch (error.name) {\n *     case \"ValidationError\": // TypeScript knows this is ValidationError\n *       break;\n *     case \"NetworkError\": // TypeScript knows this is NetworkError\n *       break;\n *   }\n * }\n *\n * // Used in Result types:\n * function validate(input: string): Result<string, ValidationError> {\n *   if (!input) {\n *     return Err({\n *       name: \"ValidationError\",\n *       message: \"Input is required\",\n *       context: { input },\n *       cause: null,\n *     });\n *   }\n *   return Ok(input);\n * }\n * ```\n */\nexport type TaggedError<T extends string> = BaseError & {\n\treadonly name: T;\n};\n\nexport function createTryFns<TName extends string>(name: TName) {\n\ttype TError = TaggedError<TName>;\n\treturn {\n\t\ttrySync: <T>({\n\t\t\ttry: operation,\n\t\t\tmapErr,\n\t\t}: {\n\t\t\ttry: () => T;\n\t\t\tmapErr: (error: unknown) => Omit<TError, \"name\">;\n\t\t}) =>\n\t\t\ttrySync<T, TError>({\n\t\t\t\ttry: operation,\n\t\t\t\tmapErr: (error) => ({\n\t\t\t\t\t...mapErr(error),\n\t\t\t\t\tname,\n\t\t\t\t}),\n\t\t\t}),\n\t\ttryAsync: <T>({\n\t\t\ttry: operation,\n\t\t\tmapErr,\n\t\t}: {\n\t\t\ttry: () => Promise<T>;\n\t\t\tmapErr: (error: unknown) => Omit<TError, \"name\">;\n\t\t}) =>\n\t\t\ttryAsync<T, TError>({\n\t\t\t\ttry: operation,\n\t\t\t\tmapErr: (error) => ({ ...mapErr(error), name }),\n\t\t\t}),\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA8EA,MAAa,KAAK,CAAIA,UAAoB;CAAE;CAAM,OAAO;AAAM;;;;;;;;;;;;;;;;AAiB/D,MAAa,MAAM,CAAIC,WAAsB;CAAE;CAAO,MAAM;AAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyGlE,SAAgB,SACfC,OACwB;CACxB,MAAM,yBAAyB,UAAU,YAAY,UAAU;AAC/D,MAAK,gBAAiB,QAAO;CAE7B,MAAM,kBAAkB,UAAU;CAClC,MAAM,mBAAmB,WAAW;AACpC,MAAK,oBAAoB,iBAAkB,QAAO;CAElD,MAAM,aAAa,MAAM,SAAS,QAAQ,MAAM,UAAU;AAC1D,KAAI,WAAY,QAAO;CAEvB,MAAM,gBAAgB,MAAM,SAAS,QAAQ,MAAM,UAAU;AAC7D,KAAI,cAAe,QAAO;AAG1B,QAAO;AACP;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,KAAWC,QAAuC;AACjE,QAAO,OAAO,UAAU;AACxB;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,MAAYA,QAAwC;AACnE,QAAO,OAAO,UAAU;AACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCD,SAAgB,QAAc,EAC7B,KAAK,WACL,UAIA,EAAgB;AAChB,KAAI;EACH,MAAM,OAAO,WAAW;AACxB,SAAO,GAAG,KAAK;CACf,SAAQ,OAAO;AACf,SAAO,IAAI,SAAS,MAAM,CAAC;CAC3B;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CD,eAAsB,SAAe,EACpC,KAAK,WACL,UAIA,EAAyB;AACzB,KAAI;EACH,MAAM,OAAO,MAAM,WAAW;AAC9B,SAAO,GAAG,KAAK;CACf,SAAQ,OAAO;AACf,SAAO,IAAI,SAAS,MAAM,CAAC;CAC3B;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDD,SAAgB,eAAqBC,OAA4B;AAChE,KAAI,SAAe,MAAM,EAAE;AAC1B,MAAI,KAAK,MAAM,CACd,QAAO,MAAM;AAKd,QAAM,MAAM;CACZ;AAID,QAAO;AACP;;;;;;;;;;;;;;;;;;;;ACxaD,SAAgB,iBAAuBC,SAAyB;AAC/D,QAAO;EACN,KAAK,CAAE;EACP,MAAM,CAAE;EACR,GAAG,OAAO,QAAQ,SAAS,CAAC,WAAY,KAAK,OAAO,GAAG,QAAQ,OAAQ;CACvE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACUD,SAAgB,oBAAoBC,OAAwB;AAC3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAGd,YAAW,UAAU,SACpB,QAAO;AAGR,YAAW,UAAU,YAAY,UAAU,MAAM;EAEhD,MAAM,WAAW;AACjB,aAAW,SAAS,YAAY,SAC/B,QAAO,SAAS;AAEjB,aAAW,SAAS,UAAU,SAC7B,QAAO,SAAS;AAEjB,aAAW,SAAS,gBAAgB,SACnC,QAAO,SAAS;AAIjB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAED,QAAO,OAAO,MAAM;AACpB;;;;ACjBD,SAAgB,aAAmCC,MAAa;AAE/D,QAAO;EACN,SAAS,CAAI,EACZ,KAAK,WACL,QAIA,KACA,QAAmB;GAClB,KAAK;GACL,QAAQ,CAAC,WAAW;IACnB,GAAG,OAAO,MAAM;IAChB;GACA;EACD,EAAC;EACH,UAAU,CAAI,EACb,KAAK,WACL,QAIA,KACA,SAAoB;GACnB,KAAK;GACL,QAAQ,CAAC,WAAW;IAAE,GAAG,OAAO,MAAM;IAAE;GAAM;EAC9C,EAAC;CACH;AACD"}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "wellcrafted",
+	"version": "0.15.0",
+	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
+	"type": "module",
+	"files": ["dist", "README.md", "LICENSE"],
+	"exports": {
+		"./result": {
+			"types": "./dist/result.d.ts",
+			"import": "./dist/result.js"
+		},
+		"./error": {
+			"types": "./dist/error/index.d.ts",
+			"import": "./dist/error/index.js"
+		},
+		"./brand": {
+			"types": "./dist/brand.d.ts",
+			"import": "./dist/brand.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": "^1.9.4",
+		"@changesets/cli": "^2.27.10",
+		"tsdown": "^0.12.5",
+		"typescript": "^5.7.2"
+	}
+}