@codenhub/error 0.0.1 → 0.1.0

package/dist/registry.js

@@ -0,0 +1,116 @@
+import { createFeedbackMapBucket, createPatternBucket, createPrefixBucket } from "./bucket.js";
+//#region src/registry.ts
+/**
+* Creates an empty, isolated error registry.
+*
+* Optionally merges a list of preset registries into the newly created registry.
+*
+* @param presets - Optional list of existing registries to merge during creation.
+* @returns A new, mutable ErrorRegistry instance.
+*/
+const createErrorRegistry = (presets) => {
+	const codes = createFeedbackMapBucket();
+	const names = createFeedbackMapBucket();
+	const messages = createFeedbackMapBucket();
+	const prefixes = createPrefixBucket();
+	const patterns = createPatternBucket();
+	const registry = {
+		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);
+		}
+	};
+	if (presets) for (const preset of presets) registry.merge(preset);
+	return registry;
+};
+let activeRegistry = createErrorRegistry();
+/**
+* Retrieves the active global error registry.
+*
+* This registry is used as the default classification source for `createAppError`.
+*
+* @returns The current active ErrorRegistry.
+*/
+const getErrorRegistry = () => {
+	return activeRegistry;
+};
+/**
+* Sets the active global error registry.
+*
+* Allows consumers to replace the default registry at application initialization.
+* Throws a TypeError if the provided value is null or not an object.
+*
+* @param registry - The ErrorRegistry instance to set as active.
+* @throws TypeError - If the parameter is not a valid ErrorRegistry.
+*/
+const setErrorRegistry = (registry) => {
+	if (typeof registry !== "object" || registry === null) throw new TypeError("Error registry must be an object.");
+	activeRegistry = registry;
+};
+/**
+* Wraps an ErrorRegistry in a read-only Proxy to prevent any future mutations.
+*
+* All mutating methods (such as `add`, `addList`, `clear`, `delete`) will throw a TypeError
+* if called on a frozen registry bucket. The returned type is `ReadonlyErrorRegistry`,
+* which only exposes the read-facing bucket surface at the type level.
+*
+* @param registry - The ErrorRegistry instance to freeze.
+* @returns A read-only `ReadonlyErrorRegistry` instance.
+*/
+const freezeRegistry = (registry) => {
+	const throwReadOnly = () => {
+		throw new TypeError("Cannot modify a read-only error registry.");
+	};
+	const freezeBucket = (bucket) => {
+		return new Proxy(bucket, {
+			get(target, prop, receiver) {
+				if (prop === "add" || prop === "addList" || prop === "clear" || prop === "delete") return throwReadOnly;
+				return Reflect.get(target, prop, receiver);
+			},
+			set() {
+				throwReadOnly();
+				return false;
+			},
+			defineProperty() {
+				throwReadOnly();
+				return false;
+			},
+			deleteProperty() {
+				throwReadOnly();
+				return false;
+			},
+			preventExtensions() {
+				throwReadOnly();
+				return false;
+			},
+			setPrototypeOf() {
+				throwReadOnly();
+				return false;
+			}
+		});
+	};
+	return Object.freeze({
+		codes: freezeBucket(registry.codes),
+		names: freezeBucket(registry.names),
+		messages: freezeBucket(registry.messages),
+		prefixes: freezeBucket(registry.prefixes),
+		patterns: freezeBucket(registry.patterns)
+	});
+};
+//#endregion
+export { createErrorRegistry, freezeRegistry, getErrorRegistry, setErrorRegistry };

package/dist/result.d.ts

@@ -0,0 +1,100 @@
+import { AppError, AppErrorOptions } from "./types.js";
+
+//#region src/result.d.ts
+/**
+ * Represents a successful result value holding the resolved data.
+ *
+ * @typeParam T - The type of the value wrapped in the success result.
+ */
+interface Ok<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+/**
+ * Represents a failed result value wrapping a normalized AppError.
+ */
+interface Err {
+  readonly ok: false;
+  readonly error: AppError;
+}
+/**
+ * A Result type representing either a successful outcome (`Ok<T>`) or a failure outcome (`Err`).
+ * Useful for handling asynchronous or fallible operations without throwing exceptions.
+ *
+ * @typeParam T - The type of the value returned on success.
+ */
+type Result<T> = Ok<T> | Err;
+/**
+ * Creates a successful Result instance wrapping the provided value.
+ * If no value is provided, returns an Ok<void> result.
+ *
+ * @typeParam T - The type of the value.
+ * @param value - The optional success value to wrap.
+ * @returns An Ok result object.
+ */
+declare function ok(): Ok<void>;
+declare function ok<T>(value: T): Ok<T>;
+/**
+ * Creates a failed Result instance wrapping a normalized AppError.
+ *
+ * If the input error is a string, it is automatically treated as the fallback message.
+ *
+ * @param error - The raw error value to normalize.
+ * @param options - Configuration options for AppError normalization.
+ * @returns An Err result object.
+ */
+declare const err: (error: unknown, options?: AppErrorOptions) => Err;
+/**
+ * Unwraps a Result, returning the value if successful, or throwing the normalized AppError if failed.
+ *
+ * @typeParam T - The type of the value.
+ * @param result - The Result instance to unwrap.
+ * @returns The unwrapped success value.
+ * @throws AppError - If the result is an Err.
+ */
+declare const unwrap: <T>(result: Result<T>) => T;
+/**
+ * Maps the success value of a Result using the provided mapper function.
+ *
+ * @typeParam T - The type of the original value.
+ * @typeParam U - The type of the mapped value.
+ * @param result - The Result instance to map.
+ * @param mapper - The function to map the success value.
+ * @returns A new Result instance with the mapped value or the original Err.
+ */
+declare const map: <T, U>(result: Result<T>, mapper: (value: T) => U) => Result<U>;
+/**
+ * Pattern matches on a Result, executing the corresponding callback based on the outcome.
+ *
+ * @typeParam T - The type of the success value.
+ * @typeParam U - The type of the return value from the callbacks.
+ * @param result - The Result instance to match.
+ * @param callbacks - An object containing onOk and onErr callback functions.
+ * @returns The value returned by the executed callback.
+ */
+declare const match: <T, U>(result: Result<T>, callbacks: {
+  readonly onOk: (value: T) => U;
+  readonly onErr: (error: AppError) => U;
+}) => U;
+/**
+ * Maps the success value of a Result using the provided mapper function that returns another Result.
+ * Prevents nested Result structures like `Result<Result<U>>`.
+ *
+ * @typeParam T - The type of the original success value.
+ * @typeParam U - The type of the mapped success value.
+ * @param result - The Result instance to process.
+ * @param mapper - The function to map the success value to a new Result.
+ * @returns A new Result instance from the mapper or the original Err.
+ */
+declare const andThen: <T, U>(result: Result<T>, mapper: (value: T) => Result<U>) => Result<U>;
+/**
+ * Unwraps a Result, returning the value if successful, or the provided fallback value if failed.
+ *
+ * @typeParam T - The type of the value.
+ * @param result - The Result instance to unwrap.
+ * @param fallback - The value to return if the result is an Err.
+ * @returns The success value or the fallback value.
+ */
+declare const unwrapOr: <T>(result: Result<T>, fallback: T) => T;
+//#endregion
+export { Err, Ok, Result, andThen, err, map, match, ok, unwrap, unwrapOr };

package/dist/result.js

@@ -0,0 +1,90 @@
+import { createAppError } from "./create-app-error.js";
+//#region src/result.ts
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* Creates a failed Result instance wrapping a normalized AppError.
+*
+* If the input error is a string, it is automatically treated as the fallback message.
+*
+* @param error - The raw error value to normalize.
+* @param options - Configuration options for AppError normalization.
+* @returns An Err result object.
+*/
+const err = (error, options = {}) => ({
+	ok: false,
+	error: createAppError(error, typeof error === "string" ? {
+		fallbackMessage: error,
+		...options
+	} : options)
+});
+/**
+* Unwraps a Result, returning the value if successful, or throwing the normalized AppError if failed.
+*
+* @typeParam T - The type of the value.
+* @param result - The Result instance to unwrap.
+* @returns The unwrapped success value.
+* @throws AppError - If the result is an Err.
+*/
+const unwrap = (result) => {
+	if (!result.ok) throw result.error;
+	return result.value;
+};
+/**
+* Maps the success value of a Result using the provided mapper function.
+*
+* @typeParam T - The type of the original value.
+* @typeParam U - The type of the mapped value.
+* @param result - The Result instance to map.
+* @param mapper - The function to map the success value.
+* @returns A new Result instance with the mapped value or the original Err.
+*/
+const map = (result, mapper) => {
+	if (!result.ok) return result;
+	return ok(mapper(result.value));
+};
+/**
+* Pattern matches on a Result, executing the corresponding callback based on the outcome.
+*
+* @typeParam T - The type of the success value.
+* @typeParam U - The type of the return value from the callbacks.
+* @param result - The Result instance to match.
+* @param callbacks - An object containing onOk and onErr callback functions.
+* @returns The value returned by the executed callback.
+*/
+const match = (result, callbacks) => {
+	if (result.ok) return callbacks.onOk(result.value);
+	return callbacks.onErr(result.error);
+};
+/**
+* Maps the success value of a Result using the provided mapper function that returns another Result.
+* Prevents nested Result structures like `Result<Result<U>>`.
+*
+* @typeParam T - The type of the original success value.
+* @typeParam U - The type of the mapped success value.
+* @param result - The Result instance to process.
+* @param mapper - The function to map the success value to a new Result.
+* @returns A new Result instance from the mapper or the original Err.
+*/
+const andThen = (result, mapper) => {
+	if (!result.ok) return result;
+	return mapper(result.value);
+};
+/**
+* Unwraps a Result, returning the value if successful, or the provided fallback value if failed.
+*
+* @typeParam T - The type of the value.
+* @param result - The Result instance to unwrap.
+* @param fallback - The value to return if the result is an Err.
+* @returns The success value or the fallback value.
+*/
+const unwrapOr = (result, fallback) => {
+	if (!result.ok) return fallback;
+	return result.value;
+};
+//#endregion
+export { andThen, err, map, match, ok, unwrap, unwrapOr };

package/dist/types.d.ts

@@ -0,0 +1,286 @@
+//#region src/types.d.ts
+/**
+ * A predictable, structured error shape representing a normalized application error.
+ *
+ * Implements the standard JavaScript `Error` interface and adds classification,
+ * localization support, and original error wrapping.
+ */
+interface AppError extends Error {
+  /**
+   * The classification of this error, denoting whether it was explicitly mapped
+   * as a known error, matched heuristically as unexpected, or completely unknown.
+   */
+  readonly type: AppErrorType;
+  /**
+   * An optional localization key from matched registry feedback,
+   * suitable for displaying translated messages to consumers.
+   */
+  readonly messageKey: string | null;
+  /**
+   * The optional source namespace, module, or package (e.g., `auth`, `supabase.database`)
+   * that originally produced the error.
+   */
+  readonly source: AppErrorSource;
+  /**
+   * The original error value passed to the factory, or the original error retrieved
+   * from nested wrapper structures (such as `cause`, `originalError`, or `error` properties).
+   */
+  readonly originalError: unknown;
+  /**
+   * Indicates whether retrying the operation that failed with this error is likely to succeed.
+   */
+  readonly isRetryable: boolean;
+}
+/**
+ * Options configuration for controlling how raw error values are normalized into `AppError` instances.
+ */
+interface AppErrorOptions {
+  /**
+   * The fallback error message to use when the error cannot be matched in the registry.
+   * Defaults to `DEFAULT_APP_ERROR_MESSAGE`.
+   */
+  fallbackMessage?: string;
+  /**
+   * The specific error registry to query for classifications.
+   * Defaults to the global registry retrieved by `getErrorRegistry()`.
+   */
+  registry?: ErrorRegistry;
+  /**
+   * The maximum depth to unwrap nested error wrappers (e.g. cause, originalError).
+   * Defaults to 3.
+   */
+  maxDepth?: number;
+}
+/**
+ * The classification level of a normalized application error.
+ *
+ * - `"known"`: Matched explicitly in the registry (by code, name, exact message, or prefix).
+ * - `"unexpected"`: Matched heuristically via regex patterns in the registry.
+ * - `"unknown"`: Could not be resolved/classified by the active registry.
+ */
+type AppErrorType = "known" | "unexpected" | "unknown";
+/**
+ * The namespace or subsystem label (e.g., `browser`, `supabase.auth`) representing
+ * where the error originated.
+ */
+type AppErrorSource = string | null;
+/**
+ * The structured feedback returned when a registry matches an error.
+ * Defines the safe user-facing message and metadata to attach to the `AppError`.
+ */
+interface ErrorFeedback {
+  /**
+   * A safe, user-facing error message description.
+   */
+  message: string;
+  /**
+   * An optional localization/translation key corresponding to the message.
+   */
+  messageKey?: string;
+  /**
+   * An optional namespace or source label (e.g. `supabase.auth`).
+   */
+  source?: string;
+  /**
+   * Indicates if the operation can be safely retried.
+   */
+  isRetryable?: boolean;
+}
+/**
+ * A registry bucket for storing and retrieving deterministic string-based error mappings
+ * (such as error codes, error names, or exact messages).
+ */
+interface ErrorRegistryBucket {
+  /**
+   * Adds or replaces error feedback for a given identifier.
+   * Trims whitespace and strips trailing punctuation from the identifier before storing.
+   *
+   * @param identifier - The exact identifier to match (e.g., `"23505"`, `"AbortError"`).
+   * @param feedback - The feedback metadata to attach to this identifier.
+   * @throws TypeError - If the identifier is empty or feedback is invalid.
+   */
+  add(identifier: string, feedback: ErrorFeedback): void;
+  /**
+   * Adds or replaces multiple feedback entries from a list of tuple definitions.
+   *
+   * @param entries - List of tuples containing [identifier, feedback].
+   * @throws TypeError - If any identifier or feedback in the list is invalid.
+   */
+  addList(entries: readonly (readonly [identifier: string, feedback: ErrorFeedback])[]): void;
+  /**
+   * Clears all mapped entries from this registry bucket.
+   */
+  clear(): void;
+  /**
+   * Retrieves a defensive copy of the feedback mapping for the specified identifier.
+   *
+   * @param identifier - The exact error identifier to lookup.
+   * @returns The matched feedback mapping, or `undefined` if not found.
+   */
+  get(identifier: string): ErrorFeedback | undefined;
+  /**
+   * Removes error feedback mapped to the specified identifier.
+   * Trims whitespace and strips trailing punctuation from the identifier before deleting.
+   *
+   * @param identifier - The exact identifier to delete.
+   * @returns True if an element in the bucket existed and has been removed, or false if the element does not exist.
+   */
+  delete(identifier: string): boolean;
+  /**
+   * Returns an iterator yielding defensive copies of all mappings stored in the bucket.
+   *
+   * @returns An iterator of [identifier, feedback] entries.
+   */
+  values(): IterableIterator<[string, ErrorFeedback]>;
+}
+/**
+ * Represents a registered message prefix definition and its feedback mapping.
+ */
+interface ErrorPrefixDefinition extends ErrorFeedback {
+  /**
+   * The message prefix matched after trimming trailing sentence punctuation.
+   */
+  prefix: string;
+}
+/**
+ * Represents a registered regex pattern definition and its feedback mapping.
+ */
+interface ErrorPatternDefinition extends ErrorFeedback {
+  /**
+   * The RegExp instance used to evaluate heuristic error matches.
+   */
+  pattern: RegExp;
+}
+/**
+ * A registry bucket for storing and matching error classifications based on message prefixes.
+ */
+interface ErrorPrefixRegistryBucket {
+  /**
+   * Adds or replaces feedback for a given message prefix.
+   * Strips trailing punctuation from the prefix before registration.
+   *
+   * @param prefix - The message prefix to register (e.g., `"Upload failed:"`).
+   * @param feedback - The feedback metadata to assign when matching this prefix.
+   * @throws TypeError - If the prefix is empty or feedback is invalid.
+   */
+  add(prefix: string, feedback: ErrorFeedback): void;
+  /**
+   * Adds or replaces multiple prefix feedback definitions from a list of tuples.
+   *
+   * @param entries - List of tuples containing [prefix, feedback].
+   * @throws TypeError - If any entry is invalid.
+   */
+  addList(entries: readonly (readonly [prefix: string, feedback: ErrorFeedback])[]): void;
+  /**
+   * Clears all registered prefix definitions from this bucket.
+   */
+  clear(): void;
+  /**
+   * Removes prefix-based feedback definition for the specified prefix.
+   * Strips trailing punctuation from the prefix before deletion.
+   *
+   * @param prefix - The message prefix to delete.
+   * @returns True if the prefix definition existed and has been removed; otherwise, false.
+   */
+  delete(prefix: string): boolean;
+  /**
+   * Returns defensive copies of all prefix definitions registered in this bucket.
+   *
+   * @returns Readonly list of prefix definitions.
+   */
+  values(): readonly ErrorPrefixDefinition[];
+}
+/**
+ * A registry bucket for storing and matching error classifications heuristically using RegExp patterns.
+ */
+interface ErrorPatternRegistryBucket {
+  /**
+   * Adds or replaces a RegExp pattern and its feedback mapping.
+   *
+   * @param pattern - The regular expression to evaluate against error messages.
+   * @param feedback - The feedback metadata to attach on pattern match.
+   * @throws TypeError - If the pattern is not a RegExp or feedback is invalid.
+   */
+  add(pattern: RegExp, feedback: ErrorFeedback): void;
+  /**
+   * Adds or replaces multiple RegExp pattern definitions from a list of tuples.
+   *
+   * @param entries - List of tuples containing [pattern, feedback].
+   * @throws TypeError - If any entry is invalid.
+   */
+  addList(entries: readonly (readonly [pattern: RegExp, feedback: ErrorFeedback])[]): void;
+  /**
+   * Clears all registered patterns from this bucket.
+   */
+  clear(): void;
+  /**
+   * Removes a RegExp pattern and its feedback mapping.
+   *
+   * @param pattern - The regular expression to remove.
+   * @returns True if the pattern existed and has been removed; otherwise, false.
+   */
+  delete(pattern: RegExp): boolean;
+  /**
+   * Returns defensive copies of all pattern definitions registered in this bucket.
+   * RegExp instances are stateless since global and sticky flags are stripped on registration.
+   *
+   * @returns Readonly list of pattern definitions.
+   */
+  values(): readonly ErrorPatternDefinition[];
+}
+/**
+ * A mutable collection of exact and heuristic error buckets used to classify unknown errors.
+ */
+interface ErrorRegistry {
+  /**
+   * Mappings for exact error codes, typically returned by database systems or APIs.
+   */
+  codes: ErrorRegistryBucket;
+  /**
+   * Mappings for exact error names, typically found on native `Error.name` or `DOMException.name` properties.
+   */
+  names: ErrorRegistryBucket;
+  /**
+   * Mappings for exact error messages (matched after trimming whitespace and trailing punctuation).
+   */
+  messages: ErrorRegistryBucket;
+  /**
+   * Mappings for matching errors by message prefixes (e.g., longest prefix match wins).
+   */
+  prefixes: ErrorPrefixRegistryBucket;
+  /**
+   * Heuristic mappings for matching errors using RegExp patterns. Matches are classified as `"unexpected"`.
+   */
+  patterns: ErrorPatternRegistryBucket;
+  /**
+   * Clears all mappings from every bucket in this registry.
+   */
+  clear(): void;
+  /**
+   * Merges all mappings from the source registry into this registry, overwriting matching identifiers.
+   *
+   * @param registry - The source registry to merge. Accepts both mutable and read-only registries.
+   */
+  merge(registry: ErrorRegistry | ReadonlyErrorRegistry): void;
+}
+/**
+ * A read-only view of an error registry returned by `freezeRegistry`.
+ *
+ * Exposes only the read-facing surface of each bucket. Mutation methods (`add`, `addList`,
+ * `clear`, `delete`) are not part of this type. Suitable as a preset source passed to
+ * `createErrorRegistry` or `merge`.
+ */
+interface ReadonlyErrorRegistry {
+  /** Read-only view of code mappings. */
+  readonly codes: Pick<ErrorRegistryBucket, "get" | "values">;
+  /** Read-only view of name mappings. */
+  readonly names: Pick<ErrorRegistryBucket, "get" | "values">;
+  /** Read-only view of message mappings. */
+  readonly messages: Pick<ErrorRegistryBucket, "get" | "values">;
+  /** Read-only view of prefix definitions. */
+  readonly prefixes: Pick<ErrorPrefixRegistryBucket, "values">;
+  /** Read-only view of pattern definitions. */
+  readonly patterns: Pick<ErrorPatternRegistryBucket, "values">;
+}
+//#endregion
+export { AppError, AppErrorOptions, AppErrorSource, AppErrorType, ErrorFeedback, ErrorPatternDefinition, ErrorPatternRegistryBucket, ErrorPrefixDefinition, ErrorPrefixRegistryBucket, ErrorRegistry, ErrorRegistryBucket, ReadonlyErrorRegistry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codenhub/error",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "private": false,
   "description": "Typed error normalization, result helpers, and opt-in registry presets for TypeScript apps.",
   "license": "Apache-2.0",
@@ -13,6 +13,7 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -38,13 +39,15 @@
     "access": "public"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.1.8",
-    "tsdown": "^0.22.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsdown": "^0.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.1.10"
   },
   "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",
+    "build": "tsdown src/index.ts src/registries/index.ts src/registries/browser.ts src/registries/supabase.ts --format esm --dts --clean --no-fixed-extension --unbundle",
+    "status:npm": "npm view @codenhub/error version dist-tags time --json && npm dist-tag ls @codenhub/error && npm access get status @codenhub/error",
+    "status:pack": "npm pack --dry-run",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",