@codenhub/error 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,346 @@
+# @codenhub/error
+
+Typed error normalization and result-style control flow for TypeScript apps. The package starts with an empty error registry by default, so consumers opt into known-error mappings explicitly, including ready-made registries for common platform and library errors.
+
+## Installation
+
+```sh
+pnpm add @codenhub/error
+```
+
+## Usage
+
+Configure the app-level `AppError.registry` during initialization, then normalize thrown or returned unknown values into a predictable error shape.
+
+```ts
+import { AppError, err, ok, type Result } from "@codenhub/error";
+
+AppError.registry.codes.add("invalid_credentials", {
+  message: "Invalid email or password.",
+  messageKey: "error.auth.invalidCredentials",
+  source: "auth",
+});
+
+const signIn = async (): Promise<Result<string>> => {
+  try {
+    return ok("user-id");
+  } catch (error) {
+    return err(error);
+  }
+};
+
+const appError = new AppError({ code: "invalid_credentials" });
+
+console.log(appError.message, appError.messageKey);
+```
+
+Ready registries are opt-in. Merge them into an app-owned registry when the app wants those classifications.
+
+```ts
+import { AppError } from "@codenhub/error";
+import { browserErrorRegistry } from "@codenhub/error/registries/browser";
+import { supabaseErrorRegistry } from "@codenhub/error/registries/supabase";
+
+AppError.registry.merge(browserErrorRegistry);
+AppError.registry.merge(supabaseErrorRegistry);
+```
+
+## Reference
+
+### `@codenhub/error`
+
+Primary entrypoint for app-owned registries, error normalization, and result helpers.
+
+```ts
+import {
+  AppError,
+  DEFAULT_APP_ERROR_MESSAGE,
+  createErrorRegistry,
+  err,
+  ok,
+  type AppErrorOptions,
+  type AppErrorSource,
+  type AppErrorType,
+  type Err,
+  type ErrorFeedback,
+  type ErrorPatternDefinition,
+  type ErrorPatternRegistryBucket,
+  type ErrorPrefixDefinition,
+  type ErrorPrefixRegistryBucket,
+  type ErrorRegistry,
+  type ErrorRegistryBucket,
+  type Ok,
+  type Result,
+} from "@codenhub/error";
+```
+
+Supported import paths:
+
+| Path                                  | Description                                             |
+| ------------------------------------- | ------------------------------------------------------- |
+| `@codenhub/error`                     | Core error normalization, registry, and result helpers. |
+| `@codenhub/error/registries`          | Index of opt-in ready registry presets.                 |
+| `@codenhub/error/registries/browser`  | Browser and Web API error mappings.                     |
+| `@codenhub/error/registries/supabase` | Supabase error mappings.                                |
+
+#### `createErrorRegistry()`
+
+Creates an empty isolated registry. This is also available as `AppError.createRegistry()`.
+
+```ts
+function createErrorRegistry(): ErrorRegistry;
+```
+
+Use isolated registries for tests, request scopes, tenant-specific mappings, or integrations where mappings should not use the app-level `AppError.registry`.
+
+#### `DEFAULT_APP_ERROR_MESSAGE`
+
+Default fallback message used when an error has no registry match and no `fallbackMessage` was provided.
+
+```ts
+const DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred.";
+```
+
+#### `ErrorRegistry`
+
+Stores deterministic and heuristic mappings used by `AppError`.
+
+```ts
+interface ErrorRegistry {
+  codes: ErrorRegistryBucket;
+  names: ErrorRegistryBucket;
+  messages: ErrorRegistryBucket;
+  prefixes: ErrorPrefixRegistryBucket;
+  patterns: ErrorPatternRegistryBucket;
+  clear(): void;
+  merge(registry: ErrorRegistry): void;
+}
+```
+
+Code, name, exact message, and prefix matches are deterministic known errors. When multiple prefixes match the same message, the longest normalized prefix wins. Pattern matches are heuristic and should be treated as unexpected errors with better user-facing feedback.
+
+`AppError.registry` is mutable and starts empty. `createErrorRegistry()` creates another empty registry with the same bucket API.
+
+Registry buckets support adding one mapping at a time or a tuple list:
+
+```ts
+interface ErrorRegistryBucket {
+  add(identifier: string, feedback: ErrorFeedback): void;
+  addList(entries: readonly (readonly [identifier: string, feedback: ErrorFeedback])[]): void;
+  clear(): void;
+  get(identifier: string): ErrorFeedback | undefined;
+  values(): IterableIterator<[string, ErrorFeedback]>;
+}
+
+interface ErrorPrefixRegistryBucket {
+  add(prefix: string, feedback: ErrorFeedback): void;
+  addList(entries: readonly (readonly [prefix: string, feedback: ErrorFeedback])[]): void;
+  clear(): void;
+  values(): readonly ErrorPrefixDefinition[];
+}
+
+interface ErrorPatternRegistryBucket {
+  add(pattern: RegExp, feedback: ErrorFeedback): void;
+  addList(entries: readonly (readonly [pattern: RegExp, feedback: ErrorFeedback])[]): void;
+  clear(): void;
+  values(): readonly ErrorPatternDefinition[];
+}
+```
+
+`values()` returns defensive copies. Pattern buckets clone `RegExp` values so global or sticky regex state does not leak across classifications.
+
+`add()` and `addList()` validate entries immediately and throw `TypeError` for invalid input. Exact and prefix identifiers must be non-empty strings after trimming whitespace and trailing sentence punctuation. Exact identifiers are stored and looked up in that normalized form. Feedback must be an object with a non-empty `message`; optional `messageKey` and `source` values must be strings, and optional `retryable` must be a boolean. Pattern buckets only accept `RegExp` patterns.
+
+#### `ErrorFeedback`
+
+Feedback stored in registry buckets.
+
+```ts
+interface ErrorFeedback {
+  message: string;
+  messageKey?: string;
+  source?: string;
+  retryable?: boolean;
+}
+```
+
+`message` should be safe to show to users. `messageKey`, `source`, and `retryable` are optional metadata copied onto matched `AppError` instances.
+
+#### `ErrorPrefixDefinition` and `ErrorPatternDefinition`
+
+Entries returned by `prefixes.values()` and `patterns.values()`.
+
+```ts
+interface ErrorPrefixDefinition extends ErrorFeedback {
+  prefix: string;
+}
+
+interface ErrorPatternDefinition extends ErrorFeedback {
+  pattern: RegExp;
+}
+```
+
+Most consumers only need these when inspecting, copying, or testing registry contents.
+
+#### `AppError`
+
+Normalizes an unknown value into a predictable error object. By default, it classifies errors with `AppError.registry`.
+
+```ts
+class AppError extends Error {
+  static readonly registry: ErrorRegistry;
+
+  static createRegistry(): ErrorRegistry;
+
+  readonly type: "known" | "unexpected" | "unknown";
+  readonly message: string;
+  readonly messageKey: string | null;
+  readonly source: string | null;
+  readonly originalError: unknown;
+  readonly retryable: boolean;
+
+  constructor(error: unknown, options?: AppErrorOptions);
+}
+```
+
+`AppError` does not throw during construction. If no registry mapping matches, it uses `DEFAULT_APP_ERROR_MESSAGE` or `fallbackMessage` and classifies the value as `"unknown"`.
+
+#### `AppErrorType` and `AppErrorSource`
+
+Reusable property types for consumers that store or pass around normalized error metadata.
+
+```ts
+type AppErrorType = "known" | "unexpected" | "unknown";
+type AppErrorSource = string | null;
+```
+
+#### `AppErrorOptions`
+
+```ts
+interface AppErrorOptions {
+  fallbackMessage?: string;
+  registry?: ErrorRegistry;
+}
+```
+
+| Option            | Type            | Default                     | Description                                   |
+| ----------------- | --------------- | --------------------------- | --------------------------------------------- |
+| `fallbackMessage` | `string`        | `DEFAULT_APP_ERROR_MESSAGE` | Message used when no mapping matches.         |
+| `registry`        | `ErrorRegistry` | `AppError.registry`         | Registry used to classify the provided error. |
+
+#### `ok()`
+
+Creates a successful result.
+
+```ts
+function ok<T>(value: T): { ok: true; value: T };
+```
+
+The returned shape is also exported as `Ok<T>`.
+
+#### `err()`
+
+Creates a failed result containing an `AppError`.
+
+```ts
+function err(error: unknown, options?: AppErrorOptions): { ok: false; error: AppError };
+```
+
+String errors are also used as the fallback message, so `err("Missing user id")` produces that message when no registry entry matches.
+
+The returned shape is also exported as `Err`.
+
+#### `Result<T>`
+
+Represents success or failure without exceptions.
+
+```ts
+type Result<T> = { ok: true; value: T } | { ok: false; error: AppError };
+```
+
+### `@codenhub/error/registries`
+
+Index entrypoint for ready registry presets.
+
+```ts
+import { browserErrorRegistry, supabaseErrorRegistry } from "@codenhub/error/registries";
+```
+
+Ready registries are plain `ErrorRegistry` values intended to be merged into `AppError.registry` or another app-owned registry. Importing a preset does not mutate `AppError.registry`.
+
+The preset registry objects are mutable like any other `ErrorRegistry`. Treat imported presets as shared read-only inputs and merge them into an app-owned registry before adding app-specific mappings.
+
+### `@codenhub/error/registries/browser`
+
+Browser and Web API error mappings.
+
+```ts
+import { browserErrorRegistry } from "@codenhub/error/registries/browser";
+```
+
+Use this preset when normalizing `DOMException`, fetch, storage, abort, permissions, quota, and other browser API errors.
+
+Importing this preset does not require `window`, `document`, `DOMException`, or other browser globals to exist.
+
+### `@codenhub/error/registries/supabase`
+
+Supabase error mappings.
+
+```ts
+import { supabaseErrorRegistry } from "@codenhub/error/registries/supabase";
+```
+
+Use this preset when normalizing Supabase Auth, PostgREST, Storage, Realtime, and Edge Functions errors.
+
+Importing this preset only creates static error mappings. It does not contact Supabase services or require Supabase client packages.
+
+## Examples
+
+### Isolate Tests
+
+```ts
+import { createErrorRegistry, err } from "@codenhub/error";
+
+const errors = createErrorRegistry();
+
+errors.names.add("AbortError", {
+  message: "Request cancelled.",
+  source: "browser",
+});
+
+const result = err(new DOMException("Aborted", "AbortError"), { registry: errors });
+```
+
+### Merge Presets
+
+```ts
+import { AppError } from "@codenhub/error";
+import { browserErrorRegistry, supabaseErrorRegistry } from "@codenhub/error/registries";
+
+AppError.registry.merge(browserErrorRegistry);
+AppError.registry.merge(supabaseErrorRegistry);
+```
+
+### Add Multiple Mappings
+
+```ts
+import { AppError } from "@codenhub/error";
+
+AppError.registry.codes.addList([
+  ["invalid_credentials", { message: "Invalid email or password.", source: "auth" }],
+  ["email_not_confirmed", { message: "Email address is not confirmed.", source: "auth" }],
+]);
+```
+
+## Requirements
+
+- TypeScript consumers should use `moduleResolution: "bundler"` or another resolver that understands package `exports`.
+- The core API is intended to run in browsers, Node, SSR, workers, and edge runtimes.
+- Browser-specific registry presets may reference browser error names and messages, but importing them must not require browser globals to exist.
+- The package has no runtime dependencies.
+
+## Notes
+
+- Registries are opt-in by design. Consumers start from a blank registry to avoid hidden global classifications.
+- Registries, including `AppError.registry` and ready registry presets, are currently mutable. Configure shared registries during app initialization and avoid mutating imported presets at runtime. A future version is expected to provide stronger mutation safeguards.
+- Preset registries should prefer stable error codes or names over message matching when a library provides them.

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { a as ErrorPatternDefinition, c as ErrorPrefixRegistryBucket, i as ErrorFeedback, l as ErrorRegistry, n as AppErrorSource, o as ErrorPatternRegistryBucket, r as AppErrorType, s as ErrorPrefixDefinition, t as AppErrorOptions, u as ErrorRegistryBucket } from "./types-D6n8W1xw.js";
+
+//#region src/app-error.d.ts
+/** Default message used when no registry entry or fallback message can describe an error. */
+declare const DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred.";
+/** Error class that normalizes unknown thrown or returned values into a predictable shape. */
+declare class AppError extends Error {
+  /** App-level registry used when no registry is passed to the constructor. */
+  static readonly registry: ErrorRegistry;
+  /** Creates an isolated registry without modifying the app-level registry. */
+  static createRegistry(): ErrorRegistry;
+  /** Classification assigned after registry lookup and fallback handling. */
+  readonly type: AppErrorType;
+  /** User-facing message resolved from registry feedback or fallback handling. */
+  readonly message: string;
+  /** Optional localization key from matched registry feedback. */
+  readonly messageKey: string | null;
+  /** Optional source label from matched registry feedback. */
+  readonly source: AppErrorSource;
+  /** Original value passed to the constructor, or the original value from a wrapped `AppError`. */
+  readonly originalError: unknown;
+  /** Whether retrying the failed operation is likely to help. */
+  readonly retryable: boolean;
+  /**
+   * Normalizes an unknown error value. Construction does not throw; unmatched values become `unknown` errors.
+   */
+  constructor(error: unknown, options?: AppErrorOptions);
+  private static resolve;
+}
+//#endregion
+//#region src/registry.d.ts
+/** Creates an empty, isolated registry for classifying unknown errors. */
+declare const createErrorRegistry: () => ErrorRegistry;
+//#endregion
+//#region src/result.d.ts
+/** Successful result value returned by `ok()`. */
+type Ok<T> = {
+  ok: true;
+  value: T;
+};
+/** Failed result value returned by `err()`. */
+type Err = {
+  ok: false;
+  error: AppError;
+};
+/** Result union for APIs that return success or failure without throwing. */
+type Result<T> = Ok<T> | Err;
+/** Wraps a value in a successful result. */
+declare const ok: <T>(value: T) => Ok<T>;
+/** Normalizes an unknown error value and wraps it in a failed result. */
+declare const err: (error: unknown, options?: AppErrorOptions) => Err;
+//#endregion
+export { AppError, type AppErrorOptions, type AppErrorSource, type AppErrorType, DEFAULT_APP_ERROR_MESSAGE, type Err, type ErrorFeedback, type ErrorPatternDefinition, type ErrorPatternRegistryBucket, type ErrorPrefixDefinition, type ErrorPrefixRegistryBucket, type ErrorRegistry, type ErrorRegistryBucket, type Ok, type Result, createErrorRegistry, err, ok };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as createErrorRegistry, i as DEFAULT_APP_ERROR_MESSAGE, n as ok, r as AppError, t as err } from "./src-DrlQ39IZ.js";
+export { AppError, DEFAULT_APP_ERROR_MESSAGE, createErrorRegistry, err, ok };

package/dist/registries/browser.d.ts

@@ -0,0 +1,10 @@
+import { l as ErrorRegistry } from "../types-D6n8W1xw.js";
+
+//#region src/registries/browser.d.ts
+/**
+ * Opt-in mutable registry preset for common browser and Web API errors.
+ * Importing this preset does not mutate `AppError.registry` and does not require browser globals.
+ */
+declare const browserErrorRegistry: ErrorRegistry;
+//#endregion
+export { browserErrorRegistry };

package/dist/registries/browser.js

@@ -0,0 +1,32 @@
+import { r as AppError } from "../src-DrlQ39IZ.js";
+//#region src/registries/browser.ts
+/**
+* Opt-in mutable registry preset for common browser and Web API errors.
+* Importing this preset does not mutate `AppError.registry` and does not require browser globals.
+*/
+const browserErrorRegistry = AppError.createRegistry();
+browserErrorRegistry.names.addList([
+	["AbortError", {
+		message: "Request cancelled.",
+		messageKey: "error.browser.abort",
+		source: "browser"
+	}],
+	["QuotaExceededError", {
+		message: "Browser storage quota exceeded.",
+		messageKey: "error.browser.storageQuotaExceeded",
+		source: "browser.storage"
+	}],
+	["NotAllowedError", {
+		message: "Permission was denied.",
+		messageKey: "error.browser.permissionDenied",
+		source: "browser.permissions"
+	}]
+]);
+browserErrorRegistry.patterns.addList([[/failed to fetch|networkerror|load failed/i, {
+	message: "Network request failed.",
+	messageKey: "error.browser.network",
+	source: "browser.network",
+	retryable: true
+}]]);
+//#endregion
+export { browserErrorRegistry };

package/dist/registries/index.d.ts

@@ -0,0 +1,3 @@
+import { browserErrorRegistry } from "./browser.js";
+import { supabaseErrorRegistry } from "./supabase.js";
+export { browserErrorRegistry, supabaseErrorRegistry };

package/dist/registries/index.js

@@ -0,0 +1,3 @@
+import { browserErrorRegistry } from "./browser.js";
+import { supabaseErrorRegistry } from "./supabase.js";
+export { browserErrorRegistry, supabaseErrorRegistry };

package/dist/registries/supabase.d.ts

@@ -0,0 +1,10 @@
+import { l as ErrorRegistry } from "../types-D6n8W1xw.js";
+
+//#region src/registries/supabase.d.ts
+/**
+ * Opt-in mutable registry preset for common Supabase Auth, database, and function errors.
+ * Importing this preset does not mutate `AppError.registry` or contact Supabase services.
+ */
+declare const supabaseErrorRegistry: ErrorRegistry;
+//#endregion
+export { supabaseErrorRegistry };

package/dist/registries/supabase.js

@@ -0,0 +1,32 @@
+import { r as AppError } from "../src-DrlQ39IZ.js";
+//#region src/registries/supabase.ts
+/**
+* Opt-in mutable registry preset for common Supabase Auth, database, and function errors.
+* Importing this preset does not mutate `AppError.registry` or contact Supabase services.
+*/
+const supabaseErrorRegistry = AppError.createRegistry();
+supabaseErrorRegistry.codes.addList([
+	["invalid_credentials", {
+		message: "Invalid email or password.",
+		messageKey: "error.supabase.auth.invalidCredentials",
+		source: "supabase.auth"
+	}],
+	["email_not_confirmed", {
+		message: "Email address is not confirmed.",
+		messageKey: "error.supabase.auth.emailNotConfirmed",
+		source: "supabase.auth"
+	}],
+	["23505", {
+		message: "A record with this value already exists.",
+		messageKey: "error.supabase.database.uniqueViolation",
+		source: "supabase.database"
+	}]
+]);
+supabaseErrorRegistry.names.add("FunctionsHttpError", {
+	message: "Edge Function request failed.",
+	messageKey: "error.supabase.functions.http",
+	source: "supabase.functions",
+	retryable: true
+});
+//#endregion
+export { supabaseErrorRegistry };

package/dist/src-DrlQ39IZ.js

@@ -0,0 +1,322 @@
+//#region src/registry.ts
+const ERROR_IDENTIFIER_TRAILING_PUNCTUATION_PATTERN = /[.!?]+$/;
+const normalizeErrorIdentifier = (identifier) => {
+	return identifier.trim().replace(ERROR_IDENTIFIER_TRAILING_PUNCTUATION_PATTERN, "");
+};
+const assertNonEmptyIdentifier = (identifier, label) => {
+	if (typeof identifier !== "string" || normalizeErrorIdentifier(identifier).length === 0) throw new TypeError(`Error registry ${label} must be a non-empty string.`);
+};
+const assertFeedback = (feedback) => {
+	if (typeof feedback !== "object" || feedback === null) throw new TypeError("Error registry feedback must be an object.");
+	if (typeof feedback.message !== "string" || feedback.message.trim().length === 0) throw new TypeError("Error registry feedback.message must be a non-empty string.");
+	if (feedback.messageKey !== void 0 && typeof feedback.messageKey !== "string") throw new TypeError("Error registry feedback.messageKey must be a string when provided.");
+	if (feedback.source !== void 0 && typeof feedback.source !== "string") throw new TypeError("Error registry feedback.source must be a string when provided.");
+	if (feedback.retryable !== void 0 && typeof feedback.retryable !== "boolean") throw new TypeError("Error registry feedback.retryable must be a boolean when provided.");
+};
+const cloneFeedback = (feedback) => ({ ...feedback });
+const createFeedbackMapBucket = () => {
+	const entries = /* @__PURE__ */ new Map();
+	const add = (identifier, feedback) => {
+		assertNonEmptyIdentifier(identifier, "identifier");
+		assertFeedback(feedback);
+		entries.set(normalizeErrorIdentifier(identifier), cloneFeedback(feedback));
+	};
+	return {
+		add,
+		addList(errorEntries) {
+			for (const [identifier, feedback] of errorEntries) add(identifier, feedback);
+		},
+		clear() {
+			entries.clear();
+		},
+		get(identifier) {
+			const feedback = entries.get(normalizeErrorIdentifier(identifier));
+			return feedback === void 0 ? void 0 : cloneFeedback(feedback);
+		},
+		values() {
+			return Array.from(entries.entries(), ([identifier, feedback]) => [identifier, cloneFeedback(feedback)]).values();
+		}
+	};
+};
+const createPrefixBucket = () => {
+	const entries = [];
+	const add = (prefix, feedback) => {
+		assertNonEmptyIdentifier(prefix, "prefix");
+		assertFeedback(feedback);
+		entries.push({
+			...cloneFeedback(feedback),
+			prefix: normalizeErrorIdentifier(prefix)
+		});
+	};
+	return {
+		add,
+		addList(errorEntries) {
+			for (const [prefix, feedback] of errorEntries) add(prefix, feedback);
+		},
+		clear() {
+			entries.length = 0;
+		},
+		values() {
+			return entries.map((entry) => ({ ...entry }));
+		}
+	};
+};
+const createPatternBucket = () => {
+	const entries = [];
+	const add = (pattern, feedback) => {
+		if (!(pattern instanceof RegExp)) throw new TypeError("Error registry pattern must be a RegExp.");
+		assertFeedback(feedback);
+		entries.push({
+			...cloneFeedback(feedback),
+			pattern: new RegExp(pattern.source, pattern.flags)
+		});
+	};
+	return {
+		add,
+		addList(errorEntries) {
+			for (const [pattern, feedback] of errorEntries) add(pattern, feedback);
+		},
+		clear() {
+			entries.length = 0;
+		},
+		values() {
+			return entries.map((entry) => ({
+				...entry,
+				pattern: new RegExp(entry.pattern.source, entry.pattern.flags)
+			}));
+		}
+	};
+};
+/** Creates an empty, isolated registry for classifying unknown errors. */
+const createErrorRegistry = () => {
+	const codes = createFeedbackMapBucket();
+	const names = createFeedbackMapBucket();
+	const messages = createFeedbackMapBucket();
+	const prefixes = createPrefixBucket();
+	const patterns = createPatternBucket();
+	return {
+		codes,
+		names,
+		messages,
+		prefixes,
+		patterns,
+		clear() {
+			codes.clear();
+			names.clear();
+			messages.clear();
+			prefixes.clear();
+			patterns.clear();
+		},
+		merge(sourceRegistry) {
+			for (const [identifier, feedback] of sourceRegistry.codes.values()) codes.add(identifier, feedback);
+			for (const [identifier, feedback] of sourceRegistry.names.values()) names.add(identifier, feedback);
+			for (const [identifier, feedback] of sourceRegistry.messages.values()) messages.add(identifier, feedback);
+			for (const { prefix, ...feedback } of sourceRegistry.prefixes.values()) prefixes.add(prefix, feedback);
+			for (const { pattern, ...feedback } of sourceRegistry.patterns.values()) patterns.add(pattern, feedback);
+		}
+	};
+};
+//#endregion
+//#region src/normalize.ts
+const ERROR_UNWRAP_MAX_DEPTH = 3;
+const ERROR_WRAPPER_FIELD_NAMES = [
+	"cause",
+	"originalError",
+	"error"
+];
+const isRecord = (value) => {
+	return typeof value === "object" && value !== null;
+};
+const getRecordField = (source, key) => {
+	try {
+		return source[key];
+	} catch {
+		return;
+	}
+};
+const getStringField = (source, key) => {
+	const value = getRecordField(source, key);
+	return typeof value === "string" ? value : null;
+};
+const toKnownClassification = (feedback) => ({
+	type: "known",
+	message: feedback.message,
+	messageKey: feedback.messageKey ?? null,
+	source: feedback.source ?? null,
+	retryable: feedback.retryable ?? false
+});
+const toUnexpectedClassification = (feedback) => ({
+	type: "unexpected",
+	message: feedback.message,
+	messageKey: feedback.messageKey ?? null,
+	source: feedback.source ?? null,
+	retryable: feedback.retryable ?? false
+});
+const normalizeError = (error) => {
+	if (typeof error === "string") return {
+		code: null,
+		message: error,
+		name: null
+	};
+	if (!isRecord(error)) return {
+		code: null,
+		message: null,
+		name: null
+	};
+	return {
+		code: getStringField(error, "code"),
+		message: getStringField(error, "message"),
+		name: getStringField(error, "name")
+	};
+};
+const getWrappedErrorCandidates = (error) => {
+	if (!isRecord(error)) return [];
+	return ERROR_WRAPPER_FIELD_NAMES.map((fieldName) => getRecordField(error, fieldName)).filter((value) => value !== void 0 && value !== null);
+};
+const getErrorCandidates = (error) => {
+	const candidates = [];
+	const visitedObjects = /* @__PURE__ */ new Set();
+	if (isRecord(error)) visitedObjects.add(error);
+	const pendingCandidates = [{
+		depth: 0,
+		value: error
+	}];
+	for (let index = 0; index < pendingCandidates.length; index += 1) {
+		const candidate = pendingCandidates[index];
+		candidates.push(candidate.value);
+		if (candidate.depth >= ERROR_UNWRAP_MAX_DEPTH) continue;
+		for (const wrappedErrorCandidate of getWrappedErrorCandidates(candidate.value)) {
+			if (isRecord(wrappedErrorCandidate)) {
+				if (visitedObjects.has(wrappedErrorCandidate)) continue;
+				visitedObjects.add(wrappedErrorCandidate);
+			}
+			pendingCandidates.push({
+				depth: candidate.depth + 1,
+				value: wrappedErrorCandidate
+			});
+		}
+	}
+	return candidates;
+};
+const getKnownMessageFeedback = (registry, message) => {
+	const normalizedMessage = normalizeErrorIdentifier(message);
+	for (const [registeredMessage, feedback] of registry.messages.values()) if (normalizeErrorIdentifier(registeredMessage) === normalizedMessage) return toKnownClassification(feedback);
+	const prefixDefinition = registry.prefixes.values().filter((definition) => normalizedMessage.startsWith(definition.prefix)).sort((firstDefinition, secondDefinition) => secondDefinition.prefix.length - firstDefinition.prefix.length)[0];
+	if (prefixDefinition === void 0) return null;
+	return toKnownClassification(prefixDefinition);
+};
+const resolveDeterministicKnownError = (registry, { code, message, name }) => {
+	if (code !== null) {
+		const feedback = registry.codes.get(code);
+		if (feedback !== void 0) return toKnownClassification(feedback);
+	}
+	if (name !== null) {
+		const feedback = registry.names.get(name);
+		if (feedback !== void 0) return toKnownClassification(feedback);
+	}
+	if (message !== null) {
+		const feedback = getKnownMessageFeedback(registry, message);
+		if (feedback !== null) return feedback;
+	}
+	return null;
+};
+const resolveHeuristicUnexpectedError = (registry, { message }) => {
+	if (message === null) return null;
+	const definition = registry.patterns.values().find((currentDefinition) => {
+		return new RegExp(currentDefinition.pattern.source, currentDefinition.pattern.flags).test(message);
+	});
+	if (definition === void 0) return null;
+	return toUnexpectedClassification(definition);
+};
+const classifyErrorCandidate = (registry, error) => {
+	const normalizedError = normalizeError(error);
+	const knownError = resolveDeterministicKnownError(registry, normalizedError);
+	if (knownError !== null) return knownError;
+	return resolveHeuristicUnexpectedError(registry, normalizedError);
+};
+//#endregion
+//#region src/app-error.ts
+/** Default message used when no registry entry or fallback message can describe an error. */
+const DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred.";
+/** Error class that normalizes unknown thrown or returned values into a predictable shape. */
+var AppError = class AppError extends Error {
+	/** App-level registry used when no registry is passed to the constructor. */
+	static registry = createErrorRegistry();
+	/** Creates an isolated registry without modifying the app-level registry. */
+	static createRegistry() {
+		return createErrorRegistry();
+	}
+	/** Classification assigned after registry lookup and fallback handling. */
+	type;
+	/** Optional localization key from matched registry feedback. */
+	messageKey;
+	/** Optional source label from matched registry feedback. */
+	source;
+	/** Original value passed to the constructor, or the original value from a wrapped `AppError`. */
+	originalError;
+	/** Whether retrying the failed operation is likely to help. */
+	retryable;
+	/**
+	* Normalizes an unknown error value. Construction does not throw; unmatched values become `unknown` errors.
+	*/
+	constructor(error, options = {}) {
+		const resolved = AppError.resolve(error, options);
+		super(resolved.message);
+		Object.setPrototypeOf(this, new.target.prototype);
+		this.name = "AppError";
+		this.type = resolved.type;
+		this.messageKey = resolved.messageKey;
+		this.source = resolved.source;
+		this.originalError = resolved.originalError;
+		this.retryable = resolved.retryable;
+	}
+	static resolve(error, options) {
+		if (error instanceof AppError) return {
+			type: error.type,
+			message: error.message,
+			messageKey: error.messageKey,
+			source: error.source,
+			originalError: error.originalError,
+			retryable: error.retryable
+		};
+		const fallbackMessage = options.fallbackMessage ?? "An unexpected error occurred.";
+		const errorCandidates = getErrorCandidates(error);
+		const registry = options.registry ?? AppError.registry;
+		for (const errorCandidate of errorCandidates) {
+			const classification = classifyErrorCandidate(registry, errorCandidate);
+			if (classification !== null) return {
+				type: classification.type,
+				message: classification.message,
+				messageKey: classification.messageKey,
+				source: classification.source,
+				originalError: error,
+				retryable: classification.retryable
+			};
+		}
+		return {
+			type: "unknown",
+			message: fallbackMessage,
+			messageKey: null,
+			source: null,
+			originalError: error,
+			retryable: false
+		};
+	}
+};
+//#endregion
+//#region src/result.ts
+/** Wraps a value in a successful result. */
+const ok = (value) => ({
+	ok: true,
+	value
+});
+/** Normalizes an unknown error value and wraps it in a failed result. */
+const err = (error, options = {}) => ({
+	ok: false,
+	error: new AppError(error, typeof error === "string" ? {
+		fallbackMessage: error,
+		...options
+	} : options)
+});
+//#endregion
+export { createErrorRegistry as a, DEFAULT_APP_ERROR_MESSAGE as i, ok as n, AppError as r, err as t };

package/dist/types-D6n8W1xw.d.ts

@@ -0,0 +1,87 @@
+//#region src/types.d.ts
+/** Options that control how unknown errors are normalized. */
+interface AppErrorOptions {
+  /** Message used when the error cannot be matched by the selected registry. */
+  fallbackMessage?: string;
+  /** Registry used for classification. Defaults to the app-level `AppError.registry`. */
+  registry?: ErrorRegistry;
+}
+/** Classification assigned to a normalized application error. */
+type AppErrorType = "known" | "unexpected" | "unknown";
+/** Optional source label for the system, package, or integration that produced an error. */
+type AppErrorSource = string | null;
+/** Consumer-facing feedback returned when a registry entry matches an error. */
+interface ErrorFeedback {
+  /** Safe user-facing message for the matched error. */
+  message: string;
+  /** Optional localization key for the message. */
+  messageKey?: string;
+  /** Optional source label, such as `auth`, `browser.network`, or `supabase.database`. */
+  source?: string;
+  /** Whether retrying the failed operation is likely to help. Defaults to `false`. */
+  retryable?: boolean;
+}
+/** Registry bucket for exact string identifiers such as error codes, names, or messages. */
+interface ErrorRegistryBucket {
+  /** Adds or replaces feedback for one normalized non-empty identifier, throwing `TypeError` for invalid input. */
+  add(identifier: string, feedback: ErrorFeedback): void;
+  /** Adds or replaces feedback for multiple normalized identifiers, throwing `TypeError` when any entry is invalid. */
+  addList(entries: readonly (readonly [identifier: string, feedback: ErrorFeedback])[]): void;
+  /** Removes all entries from this bucket. */
+  clear(): void;
+  /** Returns a defensive copy of feedback for a normalized identifier when present. */
+  get(identifier: string): ErrorFeedback | undefined;
+  /** Returns defensive copies of all bucket entries. */
+  values(): IterableIterator<[string, ErrorFeedback]>;
+}
+/** Stored prefix mapping returned by prefix registry bucket inspection. */
+interface ErrorPrefixDefinition extends ErrorFeedback {
+  /** Message prefix that is matched after trimming trailing sentence punctuation. */
+  prefix: string;
+}
+/** Stored pattern mapping returned by pattern registry bucket inspection. */
+interface ErrorPatternDefinition extends ErrorFeedback {
+  /** Regular expression used for heuristic message matching. */
+  pattern: RegExp;
+}
+/** Registry bucket for known errors matched by longest normalized message prefix. */
+interface ErrorPrefixRegistryBucket {
+  /** Adds prefix feedback after normalization, throwing `TypeError` for empty prefixes or invalid feedback. */
+  add(prefix: string, feedback: ErrorFeedback): void;
+  /** Adds multiple prefix feedback entries, throwing `TypeError` when any entry is invalid. */
+  addList(entries: readonly (readonly [prefix: string, feedback: ErrorFeedback])[]): void;
+  /** Removes all prefix entries. */
+  clear(): void;
+  /** Returns defensive copies of all prefix definitions. */
+  values(): readonly ErrorPrefixDefinition[];
+}
+/** Registry bucket for unexpected errors matched heuristically by message pattern. */
+interface ErrorPatternRegistryBucket {
+  /** Adds pattern feedback, throwing `TypeError` for non-`RegExp` patterns or invalid feedback. */
+  add(pattern: RegExp, feedback: ErrorFeedback): void;
+  /** Adds multiple pattern feedback entries, throwing `TypeError` when any entry is invalid. */
+  addList(entries: readonly (readonly [pattern: RegExp, feedback: ErrorFeedback])[]): void;
+  /** Removes all pattern entries. */
+  clear(): void;
+  /** Returns defensive copies of all pattern definitions. */
+  values(): readonly ErrorPatternDefinition[];
+}
+/** Mutable collection of exact and heuristic mappings used to classify unknown errors. */
+interface ErrorRegistry {
+  /** Exact error-code mappings, usually from APIs or databases. */
+  codes: ErrorRegistryBucket;
+  /** Exact error-name mappings, usually from `Error.name` or `DOMException.name`. */
+  names: ErrorRegistryBucket;
+  /** Exact error-message mappings after light punctuation normalization. */
+  messages: ErrorRegistryBucket;
+  /** Known-error mappings by normalized message prefix. */
+  prefixes: ErrorPrefixRegistryBucket;
+  /** Heuristic mappings by message pattern, classified as `unexpected`. */
+  patterns: ErrorPatternRegistryBucket;
+  /** Removes all mappings from every bucket. */
+  clear(): void;
+  /** Copies all mappings from another registry into this registry. */
+  merge(registry: ErrorRegistry): void;
+}
+//#endregion
+export { ErrorPatternDefinition as a, ErrorPrefixRegistryBucket as c, ErrorFeedback as i, ErrorRegistry as l, AppErrorSource as n, ErrorPatternRegistryBucket as o, AppErrorType as r, ErrorPrefixDefinition as s, AppErrorOptions as t, ErrorRegistryBucket as u };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@codenhub/error",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Typed error normalization, result helpers, and opt-in registry presets for TypeScript apps.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codenhub/codenhub.git",
+    "directory": "packages/error"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./registries": {
+      "types": "./dist/registries/index.d.ts",
+      "import": "./dist/registries/index.js"
+    },
+    "./registries/browser": {
+      "types": "./dist/registries/browser.d.ts",
+      "import": "./dist/registries/browser.js"
+    },
+    "./registries/supabase": {
+      "types": "./dist/registries/supabase.d.ts",
+      "import": "./dist/registries/supabase.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.8",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/registries/index.ts src/registries/browser.ts src/registries/supabase.ts --format esm --dts --clean --no-fixed-extension",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}