@clipboard-health/util-ts 2.8.8 → 2.9.0

package/README.md

@@ -1,11 +1,17 @@
-# @clipboard-health/util-ts
+# @clipboard-health/util-ts <!-- omit from toc -->
 
 TypeScript utilities.
 
-## Table of Contents
+## Table of contents <!-- omit from toc -->
 
 - [Install](#install)
 - [Usage](#usage)
+  - [ServiceError](#serviceerror)
+  - [ServiceResult](#serviceresult)
+  - [Functional](#functional)
+    - [`pipe`](#pipe)
+    - [`option`](#option)
+    - [`either`](#either)
 - [Local development commands](#local-development-commands)
 
 ## Install
@@ -16,6 +22,217 @@ npm install @clipboard-health/util-ts
 
 ## Usage
 
+See `./src/lib` for each utility.
+
+### ServiceError
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/serviceError.ts
+
+import { deepEqual, equal } from "node:assert/strict";
+
+import { ERROR_CODES, ServiceError } from "@clipboard-health/util-ts";
+
+{
+  const error = new ServiceError("boom");
+  equal(error.toString(), `ServiceError[${error.id}]: [internal]: boom`);
+}
+
+{
+  const error = new Error("boom");
+  const serviceError = ServiceError.fromError(error);
+  equal(
+    serviceError.toString(),
+    `ServiceError[${serviceError.id}]: [internal]: boom; [cause]: Error: boom`,
+  );
+}
+
+{
+  const errorWithCause = new ServiceError({
+    issues: [{ message: "boom" }],
+    cause: new Error("Original error"),
+  });
+  equal(
+    errorWithCause.toString(),
+    `ServiceError[${errorWithCause.id}]: [internal]: boom; [cause]: Error: Original error`,
+  );
+}
+
+{
+  const multipleIssues = new ServiceError({
+    issues: [
+      {
+        code: ERROR_CODES.badRequest,
+        message: "Invalid email format",
+        path: ["data", "attributes", "email"],
+      },
+      {
+        code: ERROR_CODES.unprocessableEntity,
+        message: "Phone number too short",
+        path: ["data", "attributes", "phoneNumber"],
+      },
+    ],
+    cause: new Error("Original error"),
+  });
+
+  equal(
+    multipleIssues.toString(),
+    `ServiceError[${multipleIssues.id}]: [badRequest]: Invalid email format; [unprocessableEntity]: Phone number too short; [cause]: Error: Original error`,
+  );
+
+  deepEqual(multipleIssues.toJsonApi(), {
+    errors: [
+      {
+        id: multipleIssues.id,
+        status: "400",
+        code: "badRequest",
+        title: "Invalid or malformed request",
+        detail: "Invalid email format",
+        source: {
+          pointer: "/data/attributes/email",
+        },
+      },
+      {
+        id: multipleIssues.id,
+        status: "422",
+        code: "unprocessableEntity",
+        title: "Request failed validation",
+        detail: "Phone number too short",
+        source: {
+          pointer: "/data/attributes/phoneNumber",
+        },
+      },
+    ],
+  });
+}
+
+```
+
+### ServiceResult
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/serviceResult.ts
+
+import { ok } from "node:assert/strict";
+
+import {
+  either as E,
+  ERROR_CODES,
+  failure,
+  type ServiceResult,
+  success,
+} from "@clipboard-health/util-ts";
+
+function validateUser(params: { email: string; phone: string }): ServiceResult<{ id: string }> {
+  const { email, phone } = params;
+  const code = ERROR_CODES.unprocessableEntity;
+
+  if (!email.includes("@")) {
+    return failure({ issues: [{ code, message: "Invalid email format" }] });
+  }
+
+  if (phone.length !== 12) {
+    return failure({ issues: [{ code, message: "Invalid phone number" }] });
+  }
+
+  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" })));
+
+```
+
+### Functional
+
+#### `pipe`
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/pipe.ts
+
+import { equal } from "node:assert/strict";
+
+import { pipe } from "@clipboard-health/util-ts";
+
+const result = pipe(
+  "  hello world  ",
+  (s) => s.trim(),
+  (s) => s.split(" "),
+  (array) => array.map((word) => word.charAt(0).toUpperCase() + word.slice(1)),
+  (array) => array.join(" "),
+);
+
+equal(result, "Hello World");
+
+```
+
+#### `option`
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/option.ts
+
+import { equal } from "node:assert/strict";
+
+import { option as O, pipe } from "@clipboard-health/util-ts";
+
+function double(n: number) {
+  return n * 2;
+}
+
+function inverse(n: number): O.Option<number> {
+  return n === 0 ? O.none : O.some(1 / n);
+}
+
+const result = pipe(
+  O.some(5),
+  O.map(double),
+  O.flatMap(inverse),
+  O.match(
+    () => "No result",
+    (n) => `Result is ${n}`,
+  ),
+);
+
+equal(result, "Result is 0.1");
+
+```
+
+#### `either`
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/either.ts
+
+import { equal } from "node:assert/strict";
+
+import { either as E, pipe } from "@clipboard-health/util-ts";
+
+function double(n: number): number {
+  return n * 2;
+}
+
+function inverse(n: number): E.Either<string, number> {
+  return n === 0 ? E.left("Division by zero") : E.right(1 / n);
+}
+
+const result = pipe(
+  E.right(5),
+  E.map(double),
+  E.flatMap(inverse),
+  E.match(
+    (error) => `Error: ${error}`,
+    (result) => `Result is ${result}`,
+  ),
+);
+
+equal(result, "Result is 0.1");
+
+```
+
 ## Local development commands
 
 See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -1,15 +1,23 @@
 {
   "name": "@clipboard-health/util-ts",
-  "version": "2.8.8",
+  "description": "TypeScript utilities.",
+  "version": "2.9.0",
+  "dependencies": {
+    "tslib": "2.8.0"
+  },
+  "devDependencies": {
+    "type-fest": "4.26.1"
+  },
+  "keywords": [],
+  "license": "MIT",
   "main": "./src/index.js",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "scripts": {
-    "build": "nx build util-ts",
-    "lint": "nx lint util-ts",
-    "test": "nx test util-ts"
+    "embed": "embedme README.md"
   },
   "type": "commonjs",
+  "typings": "./src/index.d.ts",
   "types": "./src/index.d.ts"
 }

package/src/index.d.ts

@@ -1,15 +1,13 @@
-export * from "./lib/cbh-error";
-export * from "./lib/cbh-response";
-export * from "./lib/defined-utils";
-export * from "./lib/delay";
-export * from "./lib/either";
-export * from "./lib/force-cast";
-export * from "./lib/head";
-export * from "./lib/identity";
-export * from "./lib/is-string";
-export * from "./lib/non-empty-array";
-export * from "./lib/null-to-undefined";
-export * from "./lib/option";
-export * from "./lib/stringify";
-export * from "./lib/to-error";
-//# sourceMappingURL=index.d.ts.map
+export * from "./lib/deepFreeze";
+export * from "./lib/errors/isError";
+export * from "./lib/errors/serviceError";
+export * from "./lib/errors/toError";
+export * as either from "./lib/functional/either";
+export * as option from "./lib/functional/option";
+export * from "./lib/functional/pipe";
+export * from "./lib/functional/serviceResult";
+export * from "./lib/nullish/isDefined";
+export * from "./lib/nullish/isNil";
+export * from "./lib/strings/isString";
+export * from "./lib/strings/stringify";
+export * from "./lib/types";

package/src/index.js

@@ -1,18 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.option = exports.either = void 0;
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./lib/cbh-error"), exports);
-tslib_1.__exportStar(require("./lib/cbh-response"), exports);
-tslib_1.__exportStar(require("./lib/defined-utils"), exports);
-tslib_1.__exportStar(require("./lib/delay"), exports);
-tslib_1.__exportStar(require("./lib/either"), exports);
-tslib_1.__exportStar(require("./lib/force-cast"), exports);
-tslib_1.__exportStar(require("./lib/head"), exports);
-tslib_1.__exportStar(require("./lib/identity"), exports);
-tslib_1.__exportStar(require("./lib/is-string"), exports);
-tslib_1.__exportStar(require("./lib/non-empty-array"), exports);
-tslib_1.__exportStar(require("./lib/null-to-undefined"), exports);
-tslib_1.__exportStar(require("./lib/option"), exports);
-tslib_1.__exportStar(require("./lib/stringify"), exports);
-tslib_1.__exportStar(require("./lib/to-error"), exports);
+tslib_1.__exportStar(require("./lib/deepFreeze"), exports);
+tslib_1.__exportStar(require("./lib/errors/isError"), exports);
+tslib_1.__exportStar(require("./lib/errors/serviceError"), exports);
+tslib_1.__exportStar(require("./lib/errors/toError"), exports);
+exports.either = tslib_1.__importStar(require("./lib/functional/either"));
+exports.option = tslib_1.__importStar(require("./lib/functional/option"));
+tslib_1.__exportStar(require("./lib/functional/pipe"), exports);
+tslib_1.__exportStar(require("./lib/functional/serviceResult"), exports);
+tslib_1.__exportStar(require("./lib/nullish/isDefined"), exports);
+tslib_1.__exportStar(require("./lib/nullish/isNil"), exports);
+tslib_1.__exportStar(require("./lib/strings/isString"), exports);
+tslib_1.__exportStar(require("./lib/strings/stringify"), 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,0DAAgC;AAChC,6DAAmC;AACnC,8DAAoC;AACpC,sDAA4B;AAC5B,uDAA6B;AAC7B,2DAAiC;AACjC,qDAA2B;AAC3B,yDAA+B;AAC/B,0DAAgC;AAChC,gEAAsC;AACtC,kEAAwC;AACxC,uDAA6B;AAC7B,0DAAgC;AAChC,yDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/util-ts/src/index.ts"],"names":[],"mappings":";;;;AAAA,2DAAiC;AACjC,+DAAqC;AACrC,oEAA0C;AAC1C,+DAAqC;AACrC,0EAAkD;AAClD,0EAAkD;AAClD,gEAAsC;AACtC,yEAA+C;AAC/C,kEAAwC;AACxC,8DAAoC;AACpC,iEAAuC;AACvC,kEAAwC;AACxC,sDAA4B"}

package/src/lib/{head.d.ts → arrays/head.d.ts}

@@ -1,9 +1,13 @@
 /**
  * Either a single value or an array of values.
+ *
+ * @deprecated Use `Arrayable` from "type-fest" instead.
  */
 export type OneOrArray<T> = T | T[];
 /**
- * If the provided value is an array, returns the first element. Otherwise, returns the value itself.
+ * If the provided value is an array, returns the first element. Otherwise, returns the value
+ * itself.
+ *
+ * @deprecated Use `const [first] = [1, 2, 3]` instead.
  */
 export declare function head<T>(value?: OneOrArray<T>): T | undefined;
-//# sourceMappingURL=head.d.ts.map

package/src/lib/{head.js → arrays/head.js}

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.head = head;
 /**
- * If the provided value is an array, returns the first element. Otherwise, returns the value itself.
+ * If the provided value is an array, returns the first element. Otherwise, returns the value
+ * itself.
+ *
+ * @deprecated Use `const [first] = [1, 2, 3]` instead.
  */
 function head(value) {
     return Array.isArray(value) ? value[0] : (value ?? undefined);

package/src/lib/arrays/head.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/arrays/head.ts"],"names":[],"mappings":";;AAaA,oBAEC;AARD;;;;;GAKG;AACH,SAAgB,IAAI,CAAI,KAAqB;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;AAChE,CAAC"}

package/src/lib/{non-empty-array.d.ts → arrays/nonEmptyArray.d.ts}

@@ -10,4 +10,3 @@ export type OneOrNonEmptyArray<T> = T | NonEmptyArray<T>;
  * @deprecated Use standard Array<T> instead.
  */
 export declare function toNonEmptyArray<T>(value: OneOrNonEmptyArray<T>): NonEmptyArray<T>;
-//# sourceMappingURL=non-empty-array.d.ts.map

package/src/lib/{non-empty-array.js → arrays/nonEmptyArray.js}

@@ -7,4 +7,4 @@ exports.toNonEmptyArray = toNonEmptyArray;
 function toNonEmptyArray(value) {
     return Array.isArray(value) ? value : [value];
 }
-//# sourceMappingURL=non-empty-array.js.map
+//# sourceMappingURL=nonEmptyArray.js.map

package/src/lib/arrays/nonEmptyArray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonEmptyArray.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/arrays/nonEmptyArray.ts"],"names":[],"mappings":";;AAaA,0CAEC;AALD;;GAEG;AACH,SAAgB,eAAe,CAAI,KAA4B;IAC7D,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/src/lib/deepFreeze.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Recursively freezes an object and all its nested properties.
+ *
+ * @template T - Type of the object to freeze
+ * @param value - The object to freeze
+ * @param seen - Internal parameter to track circular references
+ * @returns A deeply frozen version of the input object.
+ */
+export declare function deepFreeze<T extends object>(value: T, seen?: WeakSet<WeakKey>): Readonly<T>;

package/src/lib/deepFreeze.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepFreeze = deepFreeze;
+/**
+ * Recursively freezes an object and all its nested properties.
+ *
+ * @template T - Type of the object to freeze
+ * @param value - The object to freeze
+ * @param seen - Internal parameter to track circular references
+ * @returns A deeply frozen version of the input object.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+function deepFreeze(value, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    Reflect.ownKeys(value).forEach((key) => {
+        const property = value[key];
+        if (property && typeof property === "object" && !Object.isFrozen(property)) {
+            // eslint-disable-next-line @typescript-eslint/ban-types
+            deepFreeze(property, seen);
+        }
+    });
+    return Object.freeze(value);
+}
+//# sourceMappingURL=deepFreeze.js.map

package/src/lib/deepFreeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepFreeze.js","sourceRoot":"","sources":["../../../../../packages/util-ts/src/lib/deepFreeze.ts"],"names":[],"mappings":";;AASA,gCAeC;AAxBD;;;;;;;GAOG;AACH,wDAAwD;AACxD,SAAgB,UAAU,CAAmB,KAAQ,EAAE,IAAI,GAAG,IAAI,OAAO,EAAE;IACzE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACf,OAAO,CAAC,OAAO,CAAC,KAAK,CAAoB,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3E,wDAAwD;YACxD,UAAU,CAA2B,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

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

@@ -0,0 +1,33 @@
+import { type Arrayable } from "type-fest";
+import * as E from "../functional/either";
+/**
+ * Error status codes in our service APIs.
+ *
+ * @see {@link https://www.notion.so/BP-REST-API-f769b7fe745c4cf38f6eca2e9ad8a843?pvs=4#e0b4e9ea30f041409ce39505650098ea}
+ */
+declare const ERROR_STATUS_CODES: readonly [400, 401, 403, 404, 409, 422, 429, 500];
+/**
+ * @deprecated Use {@link ErrorCode} instead.
+ */
+export type ErrorStatusCode = (typeof ERROR_STATUS_CODES)[number];
+/**
+ * @deprecated Use {@link ServiceIssue} instead.
+ */
+export interface CbhIssue {
+    cause?: Error;
+    id?: string;
+    message: string;
+    statusCode?: ErrorStatusCode;
+}
+/**
+ * @deprecated Use {@link ServiceError} instead.
+ */
+export declare class CbhError extends Error {
+    readonly issues: readonly CbhIssue[];
+    constructor(messageOrIssues: Arrayable<CbhIssue> | string);
+}
+/**
+ * @deprecated Use {@link failure} instead.
+ */
+export declare function toLeft<A = never>(issues: Arrayable<CbhIssue> | string): E.Either<CbhError, A>;
+export {};

package/src/lib/{cbh-error.js → errors/cbhError.js}

@@ -2,13 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CbhError = void 0;
 exports.toLeft = toLeft;
-const either_1 = require("./either");
+const tslib_1 = require("tslib");
+const E = tslib_1.__importStar(require("../functional/either"));
 /**
  * Error status codes in our service APIs.
  *
  * @see {@link https://www.notion.so/BP-REST-API-f769b7fe745c4cf38f6eca2e9ad8a843?pvs=4#e0b4e9ea30f041409ce39505650098ea}
  */
 const ERROR_STATUS_CODES = [400, 401, 403, 404, 409, 422, 429, 500];
+/**
+ * @deprecated Use {@link ServiceError} instead.
+ */
 class CbhError extends Error {
     issues;
     constructor(messageOrIssues) {
@@ -26,7 +30,10 @@ class CbhError extends Error {
     }
 }
 exports.CbhError = CbhError;
+/**
+ * @deprecated Use {@link failure} instead.
+ */
 function toLeft(issues) {
-    return (0, either_1.left)(new CbhError(issues));
+    return E.left(new CbhError(issues));
 }
-//# sourceMappingURL=cbh-error.js.map
+//# sourceMappingURL=cbhError.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cbhError.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/cbhError.ts"],"names":[],"mappings":";;;AAqDA,wBAEC;;AArDD,gEAA0C;AAE1C;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAiB7E;;GAEG;AACH,MAAa,QAAS,SAAQ,KAAK;IACjB,MAAM,CAAsB;IAE5C,YAAY,eAA6C;QACvD,MAAM,EAAE,GACN,OAAO,eAAe,KAAK,QAAQ;YACjC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;YAChC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC;gBAC9B,CAAC,CAAC,eAAe;gBACjB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;QAE1B,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QACpD,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QAC7E,6FAA6F;QAC7F,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAElD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAnBD,4BAmBC;AAED;;GAEG;AACH,SAAgB,MAAM,CAAY,MAAoC;IACpE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACtC,CAAC"}

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

@@ -0,0 +1,7 @@
+/**
+ * Type guard that checks if a value is an instance of Error.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Error instance, false otherwise
+ */
+export declare function isError(value: unknown): value is Error;

package/src/lib/errors/isError.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isError = isError;
+/**
+ * Type guard that checks if a value is an instance of Error.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Error instance, false otherwise
+ */
+function isError(value) {
+    return value instanceof Error;
+}
+//# sourceMappingURL=isError.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"isError.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/isError.ts"],"names":[],"mappings":";;AAMA,0BAEC;AARD;;;;;GAKG;AACH,SAAgB,OAAO,CAAC,KAAc;IACpC,OAAO,KAAK,YAAY,KAAK,CAAC;AAChC,CAAC"}

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

@@ -0,0 +1,86 @@
+/**
+ * Standard error codes used across microservices.
+ */
+export declare const ERROR_CODES: {
+    readonly badRequest: "badRequest";
+    readonly unauthorized: "unauthorized";
+    readonly forbidden: "forbidden";
+    readonly notFound: "notFound";
+    readonly conflict: "conflict";
+    readonly unprocessableEntity: "unprocessableEntity";
+    readonly tooManyRequests: "tooManyRequests";
+    readonly internal: "internal";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+export interface ServiceIssue {
+    /** Standardized {@link ERROR_CODES} */
+    code?: ErrorCode;
+    /** Details about what caused the issue */
+    message?: string | undefined;
+    /** Path to issue location */
+    path?: Array<string | number>;
+}
+export type ServiceErrorParams = string | {
+    cause?: Readonly<unknown>;
+    issues: readonly ServiceIssue[];
+};
+export interface ZodLike {
+    issues: ReadonlyArray<{
+        message?: string | undefined;
+        path: Array<string | number>;
+    }>;
+}
+interface Issue extends ServiceIssue {
+    code: Required<ServiceIssue>["code"];
+    title: string;
+}
+/**
+ * Error class for service-level errors, convertible to JSON:API errors.
+ */
+export declare class ServiceError extends Error {
+    /**
+     * Converts an error to a `ServiceError`.
+     *
+     * @param value - The value to convert, which can be any type
+     * @returns If the value is already a `ServiceError`, returns it unchanged. Otherwise, convert it
+     *          to a `ServiceError`.
+     */
+    static fromError(value: unknown): ServiceError;
+    /**
+     * Converts a Zod-like error to a `ServiceError`.
+     *
+     * @param value - An object with a Zod-like error structure containing issues
+     * @returns The converted `ServiceError`
+     * @throws {ServiceError} If the provided value does not match the expected Zod-like structure
+     */
+    static fromZodLike(value: ZodLike): ServiceError;
+    readonly id: string;
+    readonly issues: readonly Issue[];
+    /**
+     * Creates a new `ServiceError`
+     * @param parameters - Issues contributing to the error or a message string
+     */
+    constructor(parameters: ServiceErrorParams);
+    /**
+     * Return string representation of the error for logging.
+     */
+    toString(): string;
+    /**
+     * Converts the error to JSON:API format
+     * @see {@link https://jsonapi.org/format/#error-objects}
+     * @returns Object conforming to JSON:API error format
+     */
+    toJsonApi(): {
+        errors: {
+            source?: {
+                pointer: string;
+            };
+            detail?: string;
+            id: string;
+            status: string;
+            code: ErrorCode;
+            title: string;
+        }[];
+    };
+}
+export {};