@clipboard-health/util-ts 3.8.1 → 3.9.0

package/README.md

@@ -8,6 +8,9 @@ TypeScript utilities.
 - [Usage](#usage)
   - [ServiceError](#serviceerror)
   - [ServiceResult](#serviceresult)
+    - [`tryCatchAsync`](#trycatchasync)
+    - [`tryCatch`](#trycatch)
+    - [`fromSafeParseReturnType`](#fromsafeparsereturntype)
   - [Functional](#functional)
     - [`pipe`](#pipe)
     - [`option`](#option)
@@ -29,28 +32,28 @@ See `./src/lib` for each utility.
 <embedex source="packages/util-ts/examples/serviceError.ts">
 
 ```ts
-import { deepEqual, equal } from "node:assert/strict";
+import { deepEqual, strictEqual } from "node:assert/strict";
 
 import { ERROR_CODES, ServiceError } from "@clipboard-health/util-ts";
 import { z } from "zod";
 
 {
   const error = new ServiceError("boom");
-  equal(error.toString(), `ServiceError[${error.id}]: [internal]: boom`);
+  strictEqual(error.toString(), `ServiceError[${error.id}]: [internal]: boom`);
 }
 
 try {
   throw new Error("boom");
 } catch (error) {
   const serviceError = ServiceError.fromUnknown(error);
-  equal(serviceError.toString(), `ServiceError[${serviceError.id}]: [internal]: boom`);
+  strictEqual(serviceError.toString(), `ServiceError[${serviceError.id}]: [internal]: boom`);
 }
 
 {
   const serviceError = ServiceError.fromZodError(
     new z.ZodError([{ code: "custom", path: ["foo"], message: "boom" }]),
   );
-  equal(serviceError.toString(), `ServiceError[${serviceError.id}]: [unprocessableEntity]: boom`);
+  strictEqual(serviceError.toString(), `ServiceError[${serviceError.id}]: [badRequest]: boom`);
 }
 
 {
@@ -58,7 +61,7 @@ try {
     issues: [{ message: "boom" }],
     cause: new Error("Original error"),
   });
-  equal(errorWithCause.toString(), `ServiceError[${errorWithCause.id}]: [internal]: boom`);
+  strictEqual(errorWithCause.toString(), `ServiceError[${errorWithCause.id}]: [internal]: boom`);
 }
 
 {
@@ -78,7 +81,7 @@ try {
     cause: new Error("Original error"),
   });
 
-  equal(
+  strictEqual(
     multipleIssues.toString(),
     `ServiceError[${multipleIssues.id}]: [badRequest]: Invalid email format; [unprocessableEntity]: Phone number too short`,
   );
@@ -120,9 +123,10 @@ try {
 import { ok } from "node:assert/strict";
 
 import {
-  either as E,
   ERROR_CODES,
   failure,
+  isFailure,
+  isSuccess,
   type ServiceResult,
   success,
 } from "@clipboard-health/util-ts";
@@ -142,8 +146,99 @@ function validateUser(params: { email: string; phone: string }): ServiceResult<{
   return success({ id: "user-123" });
 }
 
-ok(E.isLeft(validateUser({ email: "invalidEmail", phone: "invalidPhoneNumber" })));
-ok(E.isRight(validateUser({ email: "user@example.com", phone: "555-555-5555" })));
+ok(isFailure(validateUser({ email: "invalidEmail", phone: "invalidPhoneNumber" })));
+ok(isSuccess(validateUser({ email: "user@example.com", phone: "555-555-5555" })));
+```
+
+</embedex>
+
+#### `tryCatchAsync`
+
+<embedex source="packages/util-ts/examples/tryCatchAsync.ts">
+
+```ts
+import { ok, strictEqual } from "node:assert/strict";
+
+import { isFailure, isSuccess, ServiceError, tryCatchAsync } from "@clipboard-health/util-ts";
+
+async function example() {
+  const successResult = await tryCatchAsync(
+    async () => {
+      const response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
+      return (await response.json()) as { id: number };
+    },
+    (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
+  );
+
+  ok(isSuccess(successResult));
+  strictEqual(successResult.value.id, 1);
+
+  const failureResult = await tryCatchAsync(
+    async () => await Promise.reject(new Error("Network error")),
+    (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
+  );
+
+  ok(isFailure(failureResult));
+  strictEqual(failureResult.error.issues[0]?.message, "Failed to fetch: Error: Network error");
+}
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+void example();
+```
+
+</embedex>
+
+#### `tryCatch`
+
+<embedex source="packages/util-ts/examples/tryCatch.ts">
+
+```ts
+import { ok, strictEqual } from "node:assert/strict";
+
+import { isFailure, isSuccess, parseJson, ServiceError, tryCatch } from "@clipboard-health/util-ts";
+
+const successResult = tryCatch(
+  () => parseJson<{ name: string }>('{"name": "John"}'),
+  (error) => new ServiceError(`Parse error: ${String(error)}`),
+);
+
+ok(isSuccess(successResult));
+strictEqual(successResult.value.name, "John");
+
+const failureResult = tryCatch(
+  () => parseJson("invalid json"),
+  (error) => new ServiceError(`Parse error: ${String(error)}`),
+);
+
+ok(isFailure(failureResult));
+ok(failureResult.error.issues[0]?.message?.includes("Parse error"));
+```
+
+</embedex>
+
+#### `fromSafeParseReturnType`
+
+<embedex source="packages/util-ts/examples/fromSafeParseReturnType.ts">
+
+```ts
+import { ok, strictEqual } from "node:assert/strict";
+
+import { fromSafeParseReturnType, isFailure, isSuccess } from "@clipboard-health/util-ts";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string(), age: z.number() });
+
+const validData = { name: "John", age: 30 };
+const successResult = fromSafeParseReturnType(schema.safeParse(validData));
+
+ok(isSuccess(successResult));
+strictEqual(successResult.value.name, "John");
+
+const invalidData = { name: "John", age: "thirty" };
+const failureResult = fromSafeParseReturnType(schema.safeParse(invalidData));
+
+ok(isFailure(failureResult));
+ok(failureResult.error.issues.length > 0);
 ```
 
 </embedex>
@@ -155,7 +250,7 @@ ok(E.isRight(validateUser({ email: "user@example.com", phone: "555-555-5555" }))
 <embedex source="packages/util-ts/examples/pipe.ts">
 
 ```ts
-import { equal } from "node:assert/strict";
+import { strictEqual } from "node:assert/strict";
 
 import { pipe } from "@clipboard-health/util-ts";
 
@@ -167,7 +262,7 @@ const result = pipe(
   (array) => array.join(" "),
 );
 
-equal(result, "Hello World");
+strictEqual(result, "Hello World");
 ```
 
 </embedex>
@@ -177,7 +272,7 @@ equal(result, "Hello World");
 <embedex source="packages/util-ts/examples/option.ts">
 
 ```ts
-import { equal } from "node:assert/strict";
+import { strictEqual } from "node:assert/strict";
 
 import { option as O, pipe } from "@clipboard-health/util-ts";
 
@@ -199,7 +294,7 @@ const result = pipe(
   ),
 );
 
-equal(result, "Result is 0.1");
+strictEqual(result, "Result is 0.1");
 ```
 
 </embedex>
@@ -209,7 +304,7 @@ equal(result, "Result is 0.1");
 <embedex source="packages/util-ts/examples/either.ts">
 
 ```ts
-import { equal } from "node:assert/strict";
+import { strictEqual } from "node:assert/strict";
 
 import { either as E, pipe } from "@clipboard-health/util-ts";
 
@@ -231,7 +326,7 @@ const result = pipe(
   ),
 );
 
-equal(result, "Result is 0.1");
+strictEqual(result, "Result is 0.1");
 ```
 
 </embedex>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/util-ts",
   "description": "TypeScript utilities.",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
     "tslib": "2.8.1"

package/src/index.d.ts

@@ -6,4 +6,5 @@ export * from "./lib/functional";
 export * from "./lib/logger";
 export * from "./lib/nullish";
 export * from "./lib/strings";
+export * from "./lib/strings/parseJson";
 export * from "./lib/types";

package/src/index.js

@@ -9,5 +9,6 @@ tslib_1.__exportStar(require("./lib/functional"), exports);
 tslib_1.__exportStar(require("./lib/logger"), exports);
 tslib_1.__exportStar(require("./lib/nullish"), exports);
 tslib_1.__exportStar(require("./lib/strings"), exports);
+tslib_1.__exportStar(require("./lib/strings/parseJson"), exports);
 tslib_1.__exportStar(require("./lib/types"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/util-ts/src/index.ts"],"names":[],"mappings":";;;AAAA,uDAA6B;AAC7B,2DAAiC;AACjC,uDAA6B;AAC7B,0DAAgC;AAChC,2DAAiC;AACjC,uDAA6B;AAC7B,wDAA8B;AAC9B,wDAA8B;AAC9B,sDAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/util-ts/src/index.ts"],"names":[],"mappings":";;;AAAA,uDAA6B;AAC7B,2DAAiC;AACjC,uDAA6B;AAC7B,0DAAgC;AAChC,2DAAiC;AACjC,uDAA6B;AAC7B,wDAA8B;AAC9B,wDAA8B;AAC9B,kEAAwC;AACxC,sDAA4B"}

package/src/lib/errors/serviceError.d.ts

@@ -107,6 +107,16 @@ export declare class ServiceError extends Error {
     static fromZodError(error: ZodError, options?: {
         source?: ErrorSource;
     }): ServiceError;
+    /**
+     * Merges multiple ServiceErrors into a single ServiceError.
+     * Combines all issues from the input errors and uses the highest status code.
+     *
+     * @param error - The primary error
+     * @param errors - Additional ServiceErrors
+     * @returns New ServiceError containing all issues from input errors
+     */
+    static merge(error: unknown, ...errors: readonly unknown[]): ServiceError;
+    static merge(error: ServiceError, ...errors: readonly ServiceError[]): ServiceError;
     /**
      * Creates a ServiceError from a JSON:API error object
      * @see {@link https://jsonapi.org/format/#error-objects}

package/src/lib/errors/serviceError.js

@@ -86,6 +86,17 @@ class ServiceError extends Error {
             source: options?.source,
         });
     }
+    static merge(error, ...errors) {
+        const firstError = error instanceof ServiceError ? error : ServiceError.fromUnknown(error);
+        if (errors.length === 0) {
+            return firstError;
+        }
+        const additionalErrors = errors.map((error) => error instanceof ServiceError ? error : ServiceError.fromUnknown(error));
+        return new ServiceError({
+            cause: firstError.cause ?? firstError,
+            issues: [...firstError.issues, ...additionalErrors.flatMap((error) => error.issues)],
+        });
+    }
     /**
      * Creates a ServiceError from a JSON:API error object
      * @see {@link https://jsonapi.org/format/#error-objects}

package/src/lib/errors/serviceError.js.map

@@ -1 +1 @@
-{"version":3,"file":"serviceError.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/serviceError.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serviceError.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/serviceError.ts"],"names":[],"mappings":"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"}

package/src/lib/functional/either.d.ts

@@ -17,7 +17,7 @@ export type Right<A> = Readonly<{
  * <embedex source="packages/util-ts/examples/either.ts">
  *
  * ```ts
- * import { equal } from "node:assert/strict";
+ * import { strictEqual } from "node:assert/strict";
  *
  * import { either as E, pipe } from "@clipboard-health/util-ts";
  *
@@ -39,7 +39,7 @@ export type Right<A> = Readonly<{
  *   ),
  * );
  *
- * equal(result, "Result is 0.1");
+ * strictEqual(result, "Result is 0.1");
  * ```
  *
  * </embedex>

package/src/lib/functional/option.d.ts

@@ -12,7 +12,7 @@ export type Some<A> = Readonly<{
  * <embedex source="packages/util-ts/examples/option.ts">
  *
  * ```ts
- * import { equal } from "node:assert/strict";
+ * import { strictEqual } from "node:assert/strict";
  *
  * import { option as O, pipe } from "@clipboard-health/util-ts";
  *
@@ -34,7 +34,7 @@ export type Some<A> = Readonly<{
  *   ),
  * );
  *
- * equal(result, "Result is 0.1");
+ * strictEqual(result, "Result is 0.1");
  * ```
  *
  * </embedex>

package/src/lib/functional/pipe.js

@@ -12,7 +12,7 @@ exports.pipe = pipe;
  * <embedex source="packages/util-ts/examples/pipe.ts">
  *
  * ```ts
- * import { equal } from "node:assert/strict";
+ * import { strictEqual } from "node:assert/strict";
  *
  * import { pipe } from "@clipboard-health/util-ts";
  *
@@ -24,7 +24,7 @@ exports.pipe = pipe;
  *   (array) => array.join(" "),
  * );
  *
- * equal(result, "Hello World");
+ * strictEqual(result, "Hello World");
  * ```
  *
  * </embedex>

package/src/lib/functional/serviceResult.d.ts

@@ -1,25 +1,158 @@
-import { either as E } from "@clipboard-health/util-ts";
 import { type SafeParseReturnType } from "zod";
 import { ServiceError, type ServiceErrorParams } from "../errors/serviceError";
+import { type Either, type Left, type Right } from "./either";
+export interface Success<A> {
+    readonly isSuccess: true;
+    readonly value: A;
+}
+export interface Failure<E> {
+    readonly isSuccess: false;
+    readonly error: E;
+}
 /**
  * Represents the result of a service operation that may fail.
  * @template A The type of the successful result value
  */
-export type ServiceResult<A> = E.Either<ServiceError, A>;
+export type ServiceResult<A> = Either<ServiceError, A> & (Success<A> | Failure<ServiceError>);
 /**
- * Creates a successful `ServiceResult` containing the provided value.
- *
- * @template A The type of the success value
- * @param value The value to wrap in a successful result
- * @returns A `ServiceResult` containing the success value
+ * Alias for {@link right} that duplicates the `right` property to `value` and `isRight` to
+ * `isSuccess`.
  */
 export declare function success<A>(value: A): ServiceResult<A>;
 /**
- * Creates a failed `ServiceResult` containing a `ServiceError`.
- *
- * @template A The type of the success value
- * @param params The parameters to create the `ServiceError`
- * @returns A `ServiceResult` containing the error
+ * Alias for {@link left} that duplicates the `left` property to `error` and `isLeft` to
+ * `isSuccess`.
  */
 export declare function failure<A = never>(params: ServiceErrorParams | ServiceError): ServiceResult<A>;
+/**
+ * Alias for {@link isLeft}.
+ */
+export declare function isFailure<A>(result: ServiceResult<A>): result is Left<ServiceError> & Failure<ServiceError>;
+/**
+ * Alias for {@link isRight}.
+ */
+export declare function isSuccess<A>(result: ServiceResult<A>): result is Right<A> & Success<A>;
+/**
+ * Alias for {@link mapLeft}
+ */
+export declare function mapFailure<G>(f: (left: ServiceError) => G): <A>(result: ServiceResult<A>) => Either<G, A>;
+/**
+ * Converts a promise returning function into a ServiceResult by handling potential rejections.
+ * If the promise returning function resolves successfully, returns a success ServiceResult.
+ * If the promise rejects, calls the onError function to convert the error into a ServiceError.
+ *
+ * @template A The type of the value the promise resolves to
+ * @param f Function returning a Promise to execute. Passing a function allows catching synchronous throws
+ * @param onError Maps unknown errors to a ServiceError
+ * @returns A promise that resolves to a ServiceResult<A>
+ *
+ * @example
+ * <embedex source="packages/util-ts/examples/tryCatchAsync.ts">
+ *
+ * ```ts
+ * import { ok, strictEqual } from "node:assert/strict";
+ *
+ * import { isFailure, isSuccess, ServiceError, tryCatchAsync } from "@clipboard-health/util-ts";
+ *
+ * async function example() {
+ *   const successResult = await tryCatchAsync(
+ *     async () => {
+ *       const response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
+ *       return (await response.json()) as { id: number };
+ *     },
+ *     (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
+ *   );
+ *
+ *   ok(isSuccess(successResult));
+ *   strictEqual(successResult.value.id, 1);
+ *
+ *   const failureResult = await tryCatchAsync(
+ *     async () => await Promise.reject(new Error("Network error")),
+ *     (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
+ *   );
+ *
+ *   ok(isFailure(failureResult));
+ *   strictEqual(failureResult.error.issues[0]?.message, "Failed to fetch: Error: Network error");
+ * }
+ *
+ * // eslint-disable-next-line unicorn/prefer-top-level-await
+ * void example();
+ * ```
+ *
+ * </embedex>
+ */
+export declare function tryCatchAsync<A>(f: () => Promise<A>, onError: (error: unknown) => ServiceError): Promise<ServiceResult<A>>;
+/**
+ * Wraps a synchronous function that might throw into a ServiceResult.
+ * If the function executes successfully, returns a success ServiceResult.
+ * If the function throws, calls the onError function to convert the error into a ServiceError.
+ *
+ * @template A The return type of the function
+ * @param f The function to execute safely
+ * @param onError Function to convert unknown errors into ServiceError
+ * @returns A ServiceResult<A>
+ *
+ * @example
+ * <embedex source="packages/util-ts/examples/tryCatch.ts">
+ *
+ * ```ts
+ * import { ok, strictEqual } from "node:assert/strict";
+ *
+ * import { isFailure, isSuccess, parseJson, ServiceError, tryCatch } from "@clipboard-health/util-ts";
+ *
+ * const successResult = tryCatch(
+ *   () => parseJson<{ name: string }>('{"name": "John"}'),
+ *   (error) => new ServiceError(`Parse error: ${String(error)}`),
+ * );
+ *
+ * ok(isSuccess(successResult));
+ * strictEqual(successResult.value.name, "John");
+ *
+ * const failureResult = tryCatch(
+ *   () => parseJson("invalid json"),
+ *   (error) => new ServiceError(`Parse error: ${String(error)}`),
+ * );
+ *
+ * ok(isFailure(failureResult));
+ * ok(failureResult.error.issues[0]?.message?.includes("Parse error"));
+ * ```
+ *
+ * </embedex>
+ */
+export declare function tryCatch<A>(f: () => A, onError: (error: unknown) => ServiceError): ServiceResult<A>;
+/**
+ * Converts a Zod SafeParseReturnType into a ServiceResult.
+ * If the parse was successful, returns a success ServiceResult with the parsed data.
+ * If the parse failed, returns a failure ServiceResult with the validation errors.
+ *
+ * @template A The type of the successfully parsed value
+ * @param value The SafeParseReturnType from a Zod schema parse
+ * @returns A ServiceResult<A>
+ *
+ * @example
+ * <embedex source="packages/util-ts/examples/fromSafeParseReturnType.ts">
+ *
+ * ```ts
+ * import { ok, strictEqual } from "node:assert/strict";
+ *
+ * import { fromSafeParseReturnType, isFailure, isSuccess } from "@clipboard-health/util-ts";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ *
+ * const validData = { name: "John", age: 30 };
+ * const successResult = fromSafeParseReturnType(schema.safeParse(validData));
+ *
+ * ok(isSuccess(successResult));
+ * strictEqual(successResult.value.name, "John");
+ *
+ * const invalidData = { name: "John", age: "thirty" };
+ * const failureResult = fromSafeParseReturnType(schema.safeParse(invalidData));
+ *
+ * ok(isFailure(failureResult));
+ * ok(failureResult.error.issues.length > 0);
+ * ```
+ *
+ * </embedex>
+ */
 export declare function fromSafeParseReturnType<A>(value: SafeParseReturnType<unknown, A>): ServiceResult<A>;

package/src/lib/functional/serviceResult.js

@@ -2,32 +2,202 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.success = success;
 exports.failure = failure;
+exports.isFailure = isFailure;
+exports.isSuccess = isSuccess;
+exports.mapFailure = mapFailure;
+exports.tryCatchAsync = tryCatchAsync;
+exports.tryCatch = tryCatch;
 exports.fromSafeParseReturnType = fromSafeParseReturnType;
-const util_ts_1 = require("@clipboard-health/util-ts");
 const serviceError_1 = require("../errors/serviceError");
+const either_1 = require("./either");
 /**
- * Creates a successful `ServiceResult` containing the provided value.
- *
- * @template A The type of the success value
- * @param value The value to wrap in a successful result
- * @returns A `ServiceResult` containing the success value
+ * Alias for {@link right} that duplicates the `right` property to `value` and `isRight` to
+ * `isSuccess`.
  */
 function success(value) {
-    return util_ts_1.either.right(value);
+    const base = (0, either_1.right)(value);
+    Object.defineProperties(base, {
+        isSuccess: { get: () => true, enumerable: true },
+        value: { get: () => base.right, enumerable: true },
+    });
+    return Object.freeze(base);
 }
 /**
- * Creates a failed `ServiceResult` containing a `ServiceError`.
- *
- * @template A The type of the success value
- * @param params The parameters to create the `ServiceError`
- * @returns A `ServiceResult` containing the error
+ * Alias for {@link left} that duplicates the `left` property to `error` and `isLeft` to
+ * `isSuccess`.
  */
 function failure(params) {
-    return util_ts_1.either.left(params instanceof serviceError_1.ServiceError ? params : new serviceError_1.ServiceError(params));
+    const error = params instanceof serviceError_1.ServiceError ? params : new serviceError_1.ServiceError(params);
+    const base = (0, either_1.left)(error);
+    Object.defineProperties(base, {
+        isSuccess: { get: () => false, enumerable: true },
+        error: { get: () => base.left, enumerable: true },
+    });
+    return Object.freeze(base);
+}
+/**
+ * Alias for {@link isLeft}.
+ */
+function isFailure(result) {
+    return !result.isSuccess;
+}
+/**
+ * Alias for {@link isRight}.
+ */
+function isSuccess(result) {
+    return result.isSuccess;
+}
+/**
+ * Alias for {@link mapLeft}
+ */
+function mapFailure(f) {
+    return (0, either_1.mapLeft)(f);
+}
+/**
+ * Converts a promise returning function into a ServiceResult by handling potential rejections.
+ * If the promise returning function resolves successfully, returns a success ServiceResult.
+ * If the promise rejects, calls the onError function to convert the error into a ServiceError.
+ *
+ * @template A The type of the value the promise resolves to
+ * @param f Function returning a Promise to execute. Passing a function allows catching synchronous throws
+ * @param onError Maps unknown errors to a ServiceError
+ * @returns A promise that resolves to a ServiceResult<A>
+ *
+ * @example
+ * <embedex source="packages/util-ts/examples/tryCatchAsync.ts">
+ *
+ * ```ts
+ * import { ok, strictEqual } from "node:assert/strict";
+ *
+ * import { isFailure, isSuccess, ServiceError, tryCatchAsync } from "@clipboard-health/util-ts";
+ *
+ * async function example() {
+ *   const successResult = await tryCatchAsync(
+ *     async () => {
+ *       const response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
+ *       return (await response.json()) as { id: number };
+ *     },
+ *     (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
+ *   );
+ *
+ *   ok(isSuccess(successResult));
+ *   strictEqual(successResult.value.id, 1);
+ *
+ *   const failureResult = await tryCatchAsync(
+ *     async () => await Promise.reject(new Error("Network error")),
+ *     (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
+ *   );
+ *
+ *   ok(isFailure(failureResult));
+ *   strictEqual(failureResult.error.issues[0]?.message, "Failed to fetch: Error: Network error");
+ * }
+ *
+ * // eslint-disable-next-line unicorn/prefer-top-level-await
+ * void example();
+ * ```
+ *
+ * </embedex>
+ */
+async function tryCatchAsync(f, onError) {
+    try {
+        return success(await f());
+    }
+    catch (error) {
+        return handleError(error, onError);
+    }
 }
+/**
+ * Wraps a synchronous function that might throw into a ServiceResult.
+ * If the function executes successfully, returns a success ServiceResult.
+ * If the function throws, calls the onError function to convert the error into a ServiceError.
+ *
+ * @template A The return type of the function
+ * @param f The function to execute safely
+ * @param onError Function to convert unknown errors into ServiceError
+ * @returns A ServiceResult<A>
+ *
+ * @example
+ * <embedex source="packages/util-ts/examples/tryCatch.ts">
+ *
+ * ```ts
+ * import { ok, strictEqual } from "node:assert/strict";
+ *
+ * import { isFailure, isSuccess, parseJson, ServiceError, tryCatch } from "@clipboard-health/util-ts";
+ *
+ * const successResult = tryCatch(
+ *   () => parseJson<{ name: string }>('{"name": "John"}'),
+ *   (error) => new ServiceError(`Parse error: ${String(error)}`),
+ * );
+ *
+ * ok(isSuccess(successResult));
+ * strictEqual(successResult.value.name, "John");
+ *
+ * const failureResult = tryCatch(
+ *   () => parseJson("invalid json"),
+ *   (error) => new ServiceError(`Parse error: ${String(error)}`),
+ * );
+ *
+ * ok(isFailure(failureResult));
+ * ok(failureResult.error.issues[0]?.message?.includes("Parse error"));
+ * ```
+ *
+ * </embedex>
+ */
+function tryCatch(f, onError) {
+    try {
+        return success(f());
+    }
+    catch (error) {
+        return handleError(error, onError);
+    }
+}
+/**
+ * Converts a Zod SafeParseReturnType into a ServiceResult.
+ * If the parse was successful, returns a success ServiceResult with the parsed data.
+ * If the parse failed, returns a failure ServiceResult with the validation errors.
+ *
+ * @template A The type of the successfully parsed value
+ * @param value The SafeParseReturnType from a Zod schema parse
+ * @returns A ServiceResult<A>
+ *
+ * @example
+ * <embedex source="packages/util-ts/examples/fromSafeParseReturnType.ts">
+ *
+ * ```ts
+ * import { ok, strictEqual } from "node:assert/strict";
+ *
+ * import { fromSafeParseReturnType, isFailure, isSuccess } from "@clipboard-health/util-ts";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ *
+ * const validData = { name: "John", age: 30 };
+ * const successResult = fromSafeParseReturnType(schema.safeParse(validData));
+ *
+ * ok(isSuccess(successResult));
+ * strictEqual(successResult.value.name, "John");
+ *
+ * const invalidData = { name: "John", age: "thirty" };
+ * const failureResult = fromSafeParseReturnType(schema.safeParse(invalidData));
+ *
+ * ok(isFailure(failureResult));
+ * ok(failureResult.error.issues.length > 0);
+ * ```
+ *
+ * </embedex>
+ */
 function fromSafeParseReturnType(value) {
-    return value.success
-        ? success(value.data)
-        : failure({ issues: value.error.issues.map(serviceError_1.toZodIssue) });
+    return value.success ? success(value.data) : failure(serviceError_1.ServiceError.fromZodError(value.error));
+}
+/**
+ * Handles possible throws in onError functions.
+ */
+function handleError(error, onError) {
+    try {
+        return failure(onError(error));
+    }
+    catch (mappingError) {
+        return failure(serviceError_1.ServiceError.merge(error, mappingError));
+    }
 }
 //# sourceMappingURL=serviceResult.js.map

package/src/lib/functional/serviceResult.js.map

@@ -1 +1 @@
-{"version":3,"file":"serviceResult.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/functional/serviceResult.ts"],"names":[],"mappings":";;AAkBA,0BAEC;AASD,0BAEC;AAED,0DAMC;AAvCD,uDAAwD;AAGxD,yDAA2F;AAQ3F;;;;;;GAMG;AACH,SAAgB,OAAO,CAAI,KAAQ;IACjC,OAAO,gBAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,OAAO,CAAY,MAAyC;IAC1E,OAAO,gBAAC,CAAC,IAAI,CAAC,MAAM,YAAY,2BAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,2BAAY,CAAC,MAAM,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,SAAgB,uBAAuB,CACrC,KAAsC;IAEtC,OAAO,KAAK,CAAC,OAAO;QAClB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QACrB,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,yBAAU,CAAC,EAAE,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"serviceResult.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/functional/serviceResult.ts"],"names":[],"mappings":"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"}

package/src/lib/strings/parseJson.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Parses a JSON string and returns the parsed value with optional (unsafe) type assertion.
+ *
+ * @template T - The expected type of the parsed JSON value
+ * @param value - The JSON string to parse
+ * @param reviver - A function that transforms the result before returning it
+ * @returns The parsed JSON value cast to type T
+ * @throws {SyntaxError} When the JSON string is malformed
+ *
+ * @example
+ * ```typescript
+ * const data = parseJson<{ name: string }>('{"name": "John"}');
+ * console.log(data.name); // "John"
+ * ```
+ */
+export declare function parseJson<T = unknown>(value: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): T;

package/src/lib/strings/parseJson.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJson = parseJson;
+/**
+ * Parses a JSON string and returns the parsed value with optional (unsafe) type assertion.
+ *
+ * @template T - The expected type of the parsed JSON value
+ * @param value - The JSON string to parse
+ * @param reviver - A function that transforms the result before returning it
+ * @returns The parsed JSON value cast to type T
+ * @throws {SyntaxError} When the JSON string is malformed
+ *
+ * @example
+ * ```typescript
+ * const data = parseJson<{ name: string }>('{"name": "John"}');
+ * console.log(data.name); // "John"
+ * ```
+ */
+function parseJson(value, reviver) {
+    return JSON.parse(value, reviver);
+}
+//# sourceMappingURL=parseJson.js.map

package/src/lib/strings/parseJson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseJson.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/strings/parseJson.ts"],"names":[],"mappings":";;AAeA,8BAKC;AApBD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,SAAS,CACvB,KAAa,EACb,OAAiE;IAEjE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAM,CAAC;AACzC,CAAC"}

package/src/lib/strings/stringify.d.ts

@@ -5,4 +5,4 @@
  * @returns A JSON string representation of the value
  * @throws {TypeError} When the value contains circular references
  */
-export declare function stringify(value: unknown): string;
+export declare function stringify(value: unknown, replacer?: (this: unknown, key: string, value: unknown) => unknown, space?: string | number): string;

package/src/lib/strings/stringify.js

@@ -8,7 +8,10 @@ exports.stringify = stringify;
  * @returns A JSON string representation of the value
  * @throws {TypeError} When the value contains circular references
  */
-function stringify(value) {
-    return JSON.stringify(value, (_, value) => typeof value === "bigint" ? String(value) : value);
+function stringify(value, replacer, space) {
+    return JSON.stringify(value, replacer ?? defaultReplacer, space);
+}
+function defaultReplacer(_key, value) {
+    return typeof value === "bigint" ? String(value) : value;
 }
 //# sourceMappingURL=stringify.js.map

package/src/lib/strings/stringify.js.map

@@ -1 +1 @@
-{"version":3,"file":"stringify.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/strings/stringify.ts"],"names":[],"mappings":";;AAOA,8BAIC;AAXD;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,KAAc;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,KAAc,EAAE,EAAE,CACjD,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAClD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"stringify.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/strings/stringify.ts"],"names":[],"mappings":";;AAOA,8BAMC;AAbD;;;;;;GAMG;AACH,SAAgB,SAAS,CACvB,KAAc,EACd,QAAkE,EAClE,KAAuB;IAEvB,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,IAAI,eAAe,EAAE,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,eAAe,CAAgB,IAAY,EAAE,KAAc;IAClE,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3D,CAAC"}