@codenhub/error 0.0.1 → 0.1.0

package/dist/src-DrlQ39IZ.js

@@ -1,322 +0,0 @@
-//#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

@@ -1,87 +0,0 @@
-//#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 };