@danceroutine/tango-core 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Del Moral Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @danceroutine/tango-core
+
+`@danceroutine/tango-core` contains Tango's low-level HTTP, error, logging, and runtime primitives.
+
+This package exists so that the rest of Tango can rely on one shared vocabulary for common server-side concerns. It is also useful outside Tango when you want fetch-compatible request and response helpers, application error types that map cleanly to HTTP, logger wiring, and runtime guards for common boundary checks. Keeping those concerns in one package makes the higher-level packages easier to understand because they do not each need their own local version of the same foundational ideas.
+
+## Install
+
+```bash
+pnpm add @danceroutine/tango-core
+```
+
+## What lives here
+
+The package groups together four kinds of primitives:
+
+- HTTP types such as `TangoRequest`, `TangoResponse`, `TangoHeaders`, `TangoBody`, and `TangoQueryParams`
+- application error types such as `ValidationError`, `NotFoundError`, `PermissionDenied`, `AuthenticationError`, and `ConflictError`
+- logger utilities such as `ConsoleLogger`, `getLogger`, and `setLoggerFactory`
+- runtime guards for common server-side values
+
+These are the pieces other Tango packages build on when they need to describe a request, return a response, raise a domain error, narrow an unknown runtime value, or normalize query input.
+
+## Quick start
+
+```ts
+import { NotFoundError, TangoResponse, HttpErrorFactory } from '@danceroutine/tango-core';
+
+export async function getPost(id: string): Promise<Response> {
+    const post = null;
+
+    if (!post) {
+        const error = HttpErrorFactory.toHttpError(new NotFoundError(`Post ${id} not found`));
+        return TangoResponse.problem(error.body, { status: error.status });
+    }
+
+    return TangoResponse.json({ id, title: 'Hello' });
+}
+```
+
+The error type expresses application intent, the HTTP mapping stays consistent, and the response helper keeps the endpoint code direct.
+
+## Import style
+
+Most projects will use curated root imports:
+
+```ts
+import { TangoResponse, ValidationError, getLogger } from '@danceroutine/tango-core';
+```
+
+If you are used to Django-style domain drill-down imports, the package also exposes namespace imports and subpaths that keep related primitives grouped together:
+
+```ts
+import '@danceroutine/tango-core/errors';
+import '@danceroutine/tango-core/http';
+import '@danceroutine/tango-core/logging';
+import '@danceroutine/tango-core/runtime';
+```
+
+Available subpaths include `http`, `errors`, `logging`, and `runtime`.
+
+## Documentation
+
+- Official documentation: <https://tangowebframework.dev>
+- Architecture topic: <https://tangowebframework.dev/topics/architecture>
+- Resources API reference: <https://tangowebframework.dev/reference/resources-api>
+
+## Development
+
+```bash
+pnpm --filter @danceroutine/tango-core build
+pnpm --filter @danceroutine/tango-core typecheck
+pnpm --filter @danceroutine/tango-core test
+```
+
+For the wider contributor workflow, use:
+
+- <https://tangowebframework.dev/contributing>
+
+## License
+
+MIT

package/dist/{TangoError-NPkVPfuH.js → TangoError-DdQVQNZU.js}

@@ -2,12 +2,15 @@
 //#region src/errors/TangoError.ts
 var TangoError = class extends Error {
 	__tangoErrorBrand = "tango.error";
+	/** Runtime guard for Tango-branded errors. */
 	static isTangoError(err) {
 		return !!err && err.__tangoErrorBrand === "tango.error";
 	}
+	/** Runtime guard for plain problem-details objects. */
 	static isProblemDetails(err) {
 		return !!err && typeof err === "object" && err !== null && "code" in err && typeof err.code === "string" && "message" in err && typeof err.message === "string";
 	}
+	/** Convert this error to wire-level envelope format. */
 	toErrorEnvelope() {
 		return { error: {
 			code: this.getErrorName(),
@@ -15,6 +18,7 @@ var TangoError = class extends Error {
 			details: this.getDetails()
 		} };
 	}
+	/** Convert this error to legacy `HttpError` shape. */
 	toHttpError() {
 		return {
 			status: this.status,
@@ -28,4 +32,4 @@ var TangoError = class extends Error {
 
 //#endregion
 export { TangoError };
-//# sourceMappingURL=TangoError-NPkVPfuH.js.map
+//# sourceMappingURL=TangoError-DdQVQNZU.js.map

package/dist/TangoError-DdQVQNZU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TangoError-DdQVQNZU.js","names":["err: unknown"],"sources":["../src/errors/TangoError.ts"],"sourcesContent":["import type { HttpError } from './HttpError';\n\n/** Structured error detail payload for API responses. */\nexport type ErrorDetails = Record<string, string[]> | null | undefined;\n\n/** Canonical error payload shape used by Tango HTTP error responses. */\nexport type ProblemDetails<TDetails extends ErrorDetails = null> = {\n    code: string;\n    message: string;\n    details?: TDetails;\n    fields?: Record<string, string[]>;\n};\n\n/** Envelope shape for serialized error responses. */\nexport type ErrorEnvelope<TDetails extends ErrorDetails = null> = {\n    error: ProblemDetails<TDetails>;\n};\n\n/**\n * Base branded framework error.\n *\n * Subclasses provide HTTP status, stable code, and structured details.\n */\nexport abstract class TangoError extends Error {\n    // String brand avoids instanceof and survives cross-package boundaries.\n    readonly __tangoErrorBrand = 'tango.error' as const;\n    abstract status: number;\n\n    protected abstract getDetails(): ErrorDetails;\n\n    protected abstract getErrorName(): string;\n\n    /** Runtime guard for Tango-branded errors. */\n    static isTangoError(err: unknown): err is TangoError {\n        return !!err && (err as { __tangoErrorBrand?: string }).__tangoErrorBrand === 'tango.error';\n    }\n\n    /** Runtime guard for plain problem-details objects. */\n    static isProblemDetails(err: unknown): err is ProblemDetails {\n        return (\n            !!err &&\n            typeof err === 'object' &&\n            err !== null &&\n            'code' in err &&\n            typeof (err as { code: unknown }).code === 'string' &&\n            'message' in err &&\n            typeof (err as { message: unknown }).message === 'string'\n        );\n    }\n\n    /** Convert this error to wire-level envelope format. */\n    toErrorEnvelope(): ErrorEnvelope<ErrorDetails> {\n        return {\n            error: {\n                code: this.getErrorName(),\n                message: this.message,\n                details: this.getDetails(),\n            },\n        };\n    }\n\n    /** Convert this error to legacy `HttpError` shape. */\n    toHttpError(): HttpError {\n        return {\n            status: this.status,\n            body: {\n                error: this.message,\n                details: this.getDetails(),\n            },\n        };\n    }\n}\n"],"mappings":";;IAuBsB,aAAf,cAAkC,MAAM;CAE3C,oBAA6B;;CAQ7B,OAAO,aAAaA,KAAiC;AACjD,WAAS,OAAQ,IAAuC,sBAAsB;CACjF;;CAGD,OAAO,iBAAiBA,KAAqC;AACzD,WACM,cACK,QAAQ,YACf,QAAQ,QACR,UAAU,cACF,IAA0B,SAAS,YAC3C,aAAa,cACL,IAA6B,YAAY;CAExD;;CAGD,kBAA+C;AAC3C,SAAO,EACH,OAAO;GACH,MAAM,KAAK,cAAc;GACzB,SAAS,KAAK;GACd,SAAS,KAAK,YAAY;EAC7B,EACJ;CACJ;;CAGD,cAAyB;AACrB,SAAO;GACH,QAAQ,KAAK;GACb,MAAM;IACF,OAAO,KAAK;IACZ,SAAS,KAAK,YAAY;GAC7B;EACJ;CACJ;AACJ"}

package/dist/errors/AuthenticationError.d.ts

@@ -1,10 +1,15 @@
 import { TangoError, type ErrorDetails } from './TangoError';
+/** Error for missing/invalid authentication (HTTP 401). */
 export declare class AuthenticationError extends TangoError {
     static readonly BRAND: "tango.error.authentication";
     readonly __tangoBrand: typeof AuthenticationError.BRAND;
     status: number;
-    static isAuthenticationError(value: unknown): value is AuthenticationError;
+    /** Create an authentication error with optional custom message. */
     constructor(message?: string);
+    /**
+     * Narrow an unknown value to `AuthenticationError`.
+     */
+    static isAuthenticationError(value: unknown): value is AuthenticationError;
     protected getErrorName(): string;
     protected getDetails(): ErrorDetails;
 }

package/dist/errors/ConflictError.d.ts

@@ -1,10 +1,15 @@
 import { TangoError, type ErrorDetails } from './TangoError';
+/** Error for conflicting resource state (HTTP 409). */
 export declare class ConflictError extends TangoError {
     static readonly BRAND: "tango.error.conflict";
     readonly __tangoBrand: typeof ConflictError.BRAND;
     status: number;
-    static isConflictError(value: unknown): value is ConflictError;
+    /** Create a conflict error with optional custom message. */
     constructor(message?: string);
+    /**
+     * Narrow an unknown value to `ConflictError`.
+     */
+    static isConflictError(value: unknown): value is ConflictError;
     protected getErrorName(): string;
     protected getDetails(): ErrorDetails;
 }

package/dist/errors/NotFoundError.d.ts

@@ -1,10 +1,15 @@
 import { TangoError, type ErrorDetails } from './TangoError';
+/** Error for missing resources (HTTP 404). */
 export declare class NotFoundError extends TangoError {
     static readonly BRAND: "tango.error.not_found";
     readonly __tangoBrand: typeof NotFoundError.BRAND;
     status: number;
-    static isNotFoundError(value: unknown): value is NotFoundError;
+    /** Create a not-found error with optional custom message. */
     constructor(message?: string);
+    /**
+     * Narrow an unknown value to `NotFoundError`.
+     */
+    static isNotFoundError(value: unknown): value is NotFoundError;
     protected getErrorName(): string;
     protected getDetails(): ErrorDetails;
 }

package/dist/errors/PermissionDenied.d.ts

@@ -1,10 +1,15 @@
 import { TangoError, type ErrorDetails } from './TangoError';
+/** Error for authorization failures (HTTP 403). */
 export declare class PermissionDenied extends TangoError {
     static readonly BRAND: "tango.error.permission_denied";
     readonly __tangoBrand: typeof PermissionDenied.BRAND;
     status: number;
-    static isPermissionDenied(value: unknown): value is PermissionDenied;
+    /** Create a permission-denied error with optional custom message. */
     constructor(message?: string);
+    /**
+     * Narrow an unknown value to `PermissionDenied`.
+     */
+    static isPermissionDenied(value: unknown): value is PermissionDenied;
     protected getErrorName(): string;
     protected getDetails(): ErrorDetails;
 }

package/dist/errors/TangoError.d.ts

@@ -1,21 +1,33 @@
 import type { HttpError } from './HttpError';
+/** Structured error detail payload for API responses. */
 export type ErrorDetails = Record<string, string[]> | null | undefined;
+/** Canonical error payload shape used by Tango HTTP error responses. */
 export type ProblemDetails<TDetails extends ErrorDetails = null> = {
     code: string;
     message: string;
     details?: TDetails;
     fields?: Record<string, string[]>;
 };
+/** Envelope shape for serialized error responses. */
 export type ErrorEnvelope<TDetails extends ErrorDetails = null> = {
     error: ProblemDetails<TDetails>;
 };
+/**
+ * Base branded framework error.
+ *
+ * Subclasses provide HTTP status, stable code, and structured details.
+ */
 export declare abstract class TangoError extends Error {
-    readonly __tangoErrorBrand: 'tango.error';
+    readonly __tangoErrorBrand: "tango.error";
     abstract status: number;
     protected abstract getDetails(): ErrorDetails;
     protected abstract getErrorName(): string;
+    /** Runtime guard for Tango-branded errors. */
     static isTangoError(err: unknown): err is TangoError;
+    /** Runtime guard for plain problem-details objects. */
     static isProblemDetails(err: unknown): err is ProblemDetails;
+    /** Convert this error to wire-level envelope format. */
     toErrorEnvelope(): ErrorEnvelope<ErrorDetails>;
+    /** Convert this error to legacy `HttpError` shape. */
     toHttpError(): HttpError;
 }

package/dist/errors/ValidationError.d.ts

@@ -1,9 +1,13 @@
 import { TangoError, type ErrorDetails } from './TangoError';
+/** Error for request validation failures (HTTP 400). */
 export declare class ValidationError extends TangoError {
     details?: ErrorDetails;
-    readonly __tangoValidationErrorBrand: 'tango.error.validation';
+    readonly __tangoValidationErrorBrand: "tango.error.validation";
     status: number;
     constructor(message: string, details?: ErrorDetails);
+    /**
+     * Narrow an unknown value to `ValidationError`, including common legacy shapes.
+     */
     static isValidationError(err: unknown): err is ValidationError;
     protected getErrorName(): string;
     protected getDetails(): ErrorDetails;

package/dist/errors/factories/HttpErrorFactory.d.ts

@@ -25,6 +25,9 @@ export interface HttpErrorFactoryConfig {
  *   status: 400,
  *   body: { error: 'Validation failed', details: err.flatten().fieldErrors },
  * }));
+ *
+ * // Quick one-shot conversion with dev defaults
+ * const httpError = HttpErrorFactory.toHttpError(new NotFoundError('missing'));
  * ```
  */
 export declare class HttpErrorFactory {
@@ -33,18 +36,24 @@ export declare class HttpErrorFactory {
     private handlers;
     private exposeErrors;
     constructor(config?: HttpErrorFactoryConfig);
+    /**
+     * Narrow an unknown value to `HttpErrorFactory`.
+     */
     static isHttpErrorFactory(value: unknown): value is HttpErrorFactory;
-    registerHandler<T extends Error>(errorClass: new (...args: unknown[]) => T, handler: (error: T) => HttpError): this;
+    /**
+     * Convert an unknown error into an `HttpError` using dev-friendly defaults.
+     * Shorthand for `new HttpErrorFactory().create(error)`.
+     */
+    static toHttpError(error: unknown): HttpError;
+    private static isZodLikeValidationError;
+    private static zodLikeErrorDetails;
+    /**
+     * Register a custom mapper for an application or third-party error type.
+     */
+    registerHandler<T extends Error>(errorClass: new (...args: any[]) => T, handler: (error: T) => HttpError): this;
+    /**
+     * Convert an unknown error into the normalized HTTP error shape Tango uses.
+     */
     create(error: unknown): HttpError;
     private isErrorClassInstance;
 }
-/**
- * Default factory instance with dev-friendly defaults (exposes error messages).
- * Use this directly or create a custom HttpErrorFactory for production.
- */
-export declare const defaultHttpErrorFactory: HttpErrorFactory;
-/**
- * Convenience function that converts unknown errors to an HttpError
- * using the default factory instance.
- */
-export declare function toHttpError(error: unknown): HttpError;

package/dist/errors/factories/index.d.ts

@@ -1,4 +1,4 @@
 /**
  * Domain boundary barrel: centralizes this subdomain's public contract.
  */
-export { HttpErrorFactory, defaultHttpErrorFactory, toHttpError, type HttpErrorFactoryConfig, } from './HttpErrorFactory';
+export { HttpErrorFactory, type HttpErrorFactoryConfig } from './HttpErrorFactory';

package/dist/errors/index.d.ts

@@ -9,6 +9,6 @@ import { ValidationError } from './ValidationError';
 import { NotFoundError } from './NotFoundError';
 import { PermissionDenied } from './PermissionDenied';
 import { AuthenticationError } from './AuthenticationError';
-import { HttpErrorFactory, defaultHttpErrorFactory, toHttpError, type HttpErrorFactoryConfig } from './factories/HttpErrorFactory';
-export { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, TangoError, ValidationError, factories, defaultHttpErrorFactory, toHttpError, };
+import { HttpErrorFactory, type HttpErrorFactoryConfig } from './factories/HttpErrorFactory';
+export { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, TangoError, ValidationError, factories, };
 export type { ErrorDetails, ErrorEnvelope, HttpError, HttpErrorFactoryConfig, ProblemDetails };

package/dist/errors/index.js

@@ -1,5 +1,5 @@
-import { TangoError } from "../TangoError-NPkVPfuH.js";
-import "../runtime-DPpCYEe_.js";
-import { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, ValidationError, defaultHttpErrorFactory, factories_exports, toHttpError } from "../errors-CzSQXdgI.js";
+import { TangoError } from "../TangoError-DdQVQNZU.js";
+import "../runtime-B8KkgD3R.js";
+import { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, ValidationError, factories_exports } from "../errors-_tWsmNyZ.js";
 
-export { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, TangoError, ValidationError, defaultHttpErrorFactory, factories_exports as factories, toHttpError };
+export { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, TangoError, ValidationError, factories_exports as factories };

package/dist/{errors-CzSQXdgI.js → errors-_tWsmNyZ.js}

@@ -1,6 +1,6 @@
 import { __export } from "./chunk-BkvOhyD0.js";
-import { TangoError } from "./TangoError-NPkVPfuH.js";
-import { isError, isObject } from "./runtime-DPpCYEe_.js";
+import { TangoError } from "./TangoError-DdQVQNZU.js";
+import { isError, isObject } from "./runtime-B8KkgD3R.js";
 
 //#region src/errors/factories/HttpErrorFactory.ts
 var HttpErrorFactory = class HttpErrorFactory {
@@ -11,15 +11,52 @@ var HttpErrorFactory = class HttpErrorFactory {
 	constructor(config = {}) {
 		this.exposeErrors = config.exposeErrors ?? true;
 	}
+	/**
+	* Narrow an unknown value to `HttpErrorFactory`.
+	*/
 	static isHttpErrorFactory(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === HttpErrorFactory.BRAND;
 	}
+	/**
+	* Convert an unknown error into an `HttpError` using dev-friendly defaults.
+	* Shorthand for `new HttpErrorFactory().create(error)`.
+	*/
+	static toHttpError(error) {
+		return new HttpErrorFactory().create(error);
+	}
+	static isZodLikeValidationError(error) {
+		return isError(error) && isObject(error) && Array.isArray(error.issues) && error.name === "ZodError";
+	}
+	static zodLikeErrorDetails(error) {
+		const details = {};
+		for (const issue of error.issues) {
+			const key = Array.isArray(issue.path) && issue.path.length > 0 ? String(issue.path.join(".")) : "_schema";
+			const message = typeof issue.message === "string" ? issue.message : "Invalid value";
+			const existing = details[key];
+			if (existing) existing.push(message);
+else details[key] = [message];
+		}
+		return details;
+	}
+	/**
+	* Register a custom mapper for an application or third-party error type.
+	*/
 	registerHandler(errorClass, handler) {
 		this.handlers.set(errorClass, handler);
 		return this;
 	}
+	/**
+	* Convert an unknown error into the normalized HTTP error shape Tango uses.
+	*/
 	create(error) {
 		if (TangoError.isTangoError(error)) return error.toHttpError();
+		if (HttpErrorFactory.isZodLikeValidationError(error)) return {
+			status: 400,
+			body: {
+				error: error.message || "Validation failed",
+				details: HttpErrorFactory.zodLikeErrorDetails(error)
+			}
+		};
 		for (const [ErrorClass, handler] of this.handlers) if (this.isErrorClassInstance(error, ErrorClass)) return handler(error);
 		if (isError(error)) return {
 			status: 500,
@@ -37,28 +74,21 @@ var HttpErrorFactory = class HttpErrorFactory {
 		};
 	}
 	isErrorClassInstance(error, ErrorClass) {
-		if (!isObject(error)) return false;
-		let proto = Object.getPrototypeOf(error);
-		while (proto) {
-			if (proto === ErrorClass.prototype) return true;
-			proto = Object.getPrototypeOf(proto);
-		}
+		if (!isError(error)) return false;
+		const expectedBrand = ErrorClass.BRAND;
+		if (typeof expectedBrand === "string" && isObject(error) && error.__tangoBrand === expectedBrand) return true;
+		const constructorName = error.constructor?.name;
+		if (typeof constructorName === "string" && constructorName === ErrorClass.name) return true;
+		const errorName = error.name;
+		if (typeof errorName === "string" && errorName === ErrorClass.name) return true;
 		return false;
 	}
 };
-const defaultHttpErrorFactory = new HttpErrorFactory();
-function toHttpError(error) {
-	return defaultHttpErrorFactory.create(error);
-}
 
 //#endregion
 //#region src/errors/factories/index.ts
 var factories_exports = {};
-__export(factories_exports, {
-	HttpErrorFactory: () => HttpErrorFactory,
-	defaultHttpErrorFactory: () => defaultHttpErrorFactory,
-	toHttpError: () => toHttpError
-});
+__export(factories_exports, { HttpErrorFactory: () => HttpErrorFactory });
 
 //#endregion
 //#region src/errors/ConflictError.ts
@@ -66,14 +96,18 @@ var ConflictError = class ConflictError extends TangoError {
 	static BRAND = "tango.error.conflict";
 	__tangoBrand = ConflictError.BRAND;
 	status = 409;
-	static isConflictError(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === ConflictError.BRAND;
-	}
+	/** Create a conflict error with optional custom message. */
 	constructor(message = "Resource conflict") {
 		super(message);
 		this.name = "ConflictError";
 		Object.setPrototypeOf(this, ConflictError.prototype);
 	}
+	/**
+	* Narrow an unknown value to `ConflictError`.
+	*/
+	static isConflictError(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === ConflictError.BRAND;
+	}
 	getErrorName() {
 		return "conflict";
 	}
@@ -93,6 +127,9 @@ var ValidationError = class ValidationError extends TangoError {
 		this.name = "ValidationError";
 		Object.setPrototypeOf(this, ValidationError.prototype);
 	}
+	/**
+	* Narrow an unknown value to `ValidationError`, including common legacy shapes.
+	*/
 	static isValidationError(err) {
 		return !!err && typeof err === "object" && err.__tangoValidationErrorBrand === "tango.error.validation" || typeof err === "object" && err !== null && "fields" in err && typeof err.fields === "object";
 	}
@@ -110,14 +147,18 @@ var NotFoundError = class NotFoundError extends TangoError {
 	static BRAND = "tango.error.not_found";
 	__tangoBrand = NotFoundError.BRAND;
 	status = 404;
-	static isNotFoundError(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === NotFoundError.BRAND;
-	}
+	/** Create a not-found error with optional custom message. */
 	constructor(message = "Resource not found") {
 		super(message);
 		this.name = "NotFoundError";
 		Object.setPrototypeOf(this, NotFoundError.prototype);
 	}
+	/**
+	* Narrow an unknown value to `NotFoundError`.
+	*/
+	static isNotFoundError(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === NotFoundError.BRAND;
+	}
 	getErrorName() {
 		return "not_found";
 	}
@@ -132,14 +173,18 @@ var PermissionDenied = class PermissionDenied extends TangoError {
 	static BRAND = "tango.error.permission_denied";
 	__tangoBrand = PermissionDenied.BRAND;
 	status = 403;
-	static isPermissionDenied(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === PermissionDenied.BRAND;
-	}
+	/** Create a permission-denied error with optional custom message. */
 	constructor(message = "Permission denied") {
 		super(message);
 		this.name = "PermissionDenied";
 		Object.setPrototypeOf(this, PermissionDenied.prototype);
 	}
+	/**
+	* Narrow an unknown value to `PermissionDenied`.
+	*/
+	static isPermissionDenied(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === PermissionDenied.BRAND;
+	}
 	getErrorName() {
 		return "permission_denied";
 	}
@@ -154,14 +199,18 @@ var AuthenticationError = class AuthenticationError extends TangoError {
 	static BRAND = "tango.error.authentication";
 	__tangoBrand = AuthenticationError.BRAND;
 	status = 401;
-	static isAuthenticationError(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === AuthenticationError.BRAND;
-	}
+	/** Create an authentication error with optional custom message. */
 	constructor(message = "Authentication required") {
 		super(message);
 		this.name = "AuthenticationError";
 		Object.setPrototypeOf(this, AuthenticationError.prototype);
 	}
+	/**
+	* Narrow an unknown value to `AuthenticationError`.
+	*/
+	static isAuthenticationError(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === AuthenticationError.BRAND;
+	}
 	getErrorName() {
 		return "authentication_error";
 	}
@@ -181,11 +230,9 @@ __export(errors_exports, {
 	PermissionDenied: () => PermissionDenied,
 	TangoError: () => TangoError,
 	ValidationError: () => ValidationError,
-	defaultHttpErrorFactory: () => defaultHttpErrorFactory,
-	factories: () => factories_exports,
-	toHttpError: () => toHttpError
+	factories: () => factories_exports
 });
 
 //#endregion
-export { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, ValidationError, defaultHttpErrorFactory, errors_exports, factories_exports, toHttpError };
-//# sourceMappingURL=errors-CzSQXdgI.js.map
+export { AuthenticationError, ConflictError, HttpErrorFactory, NotFoundError, PermissionDenied, ValidationError, errors_exports, factories_exports };
+//# sourceMappingURL=errors-_tWsmNyZ.js.map

package/dist/errors-_tWsmNyZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-_tWsmNyZ.js","names":["config: HttpErrorFactoryConfig","value: unknown","error: unknown","error: ZodLikeError","details: Record<string, string[]>","errorClass: new (...args: any[]) => T","handler: (error: T) => HttpError","ErrorClass: new (...args: any[]) => Error","message: string","value: unknown","message: string","details?: ErrorDetails","err: unknown","message: string","value: unknown","message: string","value: unknown","message: string","value: unknown"],"sources":["../src/errors/factories/HttpErrorFactory.ts","../src/errors/factories/index.ts","../src/errors/ConflictError.ts","../src/errors/ValidationError.ts","../src/errors/NotFoundError.ts","../src/errors/PermissionDenied.ts","../src/errors/AuthenticationError.ts","../src/errors/index.ts"],"sourcesContent":["import { TangoError } from '../TangoError';\nimport type { HttpError } from '../HttpError';\nimport { isError, isObject } from '../../runtime/index';\n\nexport interface HttpErrorFactoryConfig {\n    /**\n     * When true, raw error messages are included in HTTP responses.\n     * When false, generic messages are returned for non-TangoError exceptions.\n     * Defaults to true (dev-friendly). Set to false in production.\n     */\n    exposeErrors?: boolean;\n}\n\ntype ZodLikeIssue = {\n    path?: unknown[];\n    message?: unknown;\n};\n\ntype ZodLikeError = Error & {\n    issues: ZodLikeIssue[];\n};\n\n/**\n * Converts errors into structured HTTP error responses.\n * Supports TangoError subclasses out of the box, and custom error handlers\n * can be registered for third-party or application-specific error types.\n *\n * @example\n * ```typescript\n * // Development (default) — exposes real error messages\n * const devFactory = new HttpErrorFactory();\n *\n * // Production — hides internal error details\n * const prodFactory = new HttpErrorFactory({ exposeErrors: false });\n *\n * // Register a custom handler for a third-party error\n * prodFactory.registerHandler(ZodError, (err) => ({\n *   status: 400,\n *   body: { error: 'Validation failed', details: err.flatten().fieldErrors },\n * }));\n *\n * // Quick one-shot conversion with dev defaults\n * const httpError = HttpErrorFactory.toHttpError(new NotFoundError('missing'));\n * ```\n */\nexport class HttpErrorFactory {\n    static readonly BRAND = 'tango.error_factory.http' as const;\n    readonly __tangoBrand: typeof HttpErrorFactory.BRAND = HttpErrorFactory.BRAND;\n\n    // oxlint-disable-next-line typescript/no-explicit-any\n    private handlers = new Map<new (...args: any[]) => Error, (error: Error) => HttpError>();\n    private exposeErrors: boolean;\n\n    constructor(config: HttpErrorFactoryConfig = {}) {\n        this.exposeErrors = config.exposeErrors ?? true;\n    }\n\n    /**\n     * Narrow an unknown value to `HttpErrorFactory`.\n     */\n    static isHttpErrorFactory(value: unknown): value is HttpErrorFactory {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === HttpErrorFactory.BRAND\n        );\n    }\n\n    /**\n     * Convert an unknown error into an `HttpError` using dev-friendly defaults.\n     * Shorthand for `new HttpErrorFactory().create(error)`.\n     */\n    static toHttpError(error: unknown): HttpError {\n        return new HttpErrorFactory().create(error);\n    }\n\n    private static isZodLikeValidationError(error: unknown): error is ZodLikeError {\n        return (\n            isError(error) &&\n            isObject(error) &&\n            Array.isArray((error as { issues?: unknown }).issues) &&\n            (error as { name?: unknown }).name === 'ZodError'\n        );\n    }\n\n    private static zodLikeErrorDetails(error: ZodLikeError): Record<string, string[]> {\n        const details: Record<string, string[]> = {};\n\n        for (const issue of error.issues) {\n            const key = Array.isArray(issue.path) && issue.path.length > 0 ? String(issue.path.join('.')) : '_schema';\n            const message = typeof issue.message === 'string' ? issue.message : 'Invalid value';\n\n            const existing = details[key];\n            if (existing) {\n                existing.push(message);\n            } else {\n                details[key] = [message];\n            }\n        }\n\n        return details;\n    }\n\n    /**\n     * Register a custom mapper for an application or third-party error type.\n     */\n\n    // oxlint-disable-next-line typescript/no-explicit-any\n    registerHandler<T extends Error>(errorClass: new (...args: any[]) => T, handler: (error: T) => HttpError): this {\n        this.handlers.set(errorClass, handler as (error: Error) => HttpError);\n        return this;\n    }\n\n    /**\n     * Convert an unknown error into the normalized HTTP error shape Tango uses.\n     */\n    create(error: unknown): HttpError {\n        if (TangoError.isTangoError(error)) {\n            return error.toHttpError();\n        }\n\n        if (HttpErrorFactory.isZodLikeValidationError(error)) {\n            return {\n                status: 400,\n                body: {\n                    error: error.message || 'Validation failed',\n                    details: HttpErrorFactory.zodLikeErrorDetails(error),\n                },\n            };\n        }\n\n        for (const [ErrorClass, handler] of this.handlers) {\n            if (this.isErrorClassInstance(error, ErrorClass)) {\n                return handler(error);\n            }\n        }\n\n        if (isError(error)) {\n            return {\n                status: 500,\n                body: {\n                    error: this.exposeErrors ? error.message : 'Internal Server Error',\n                    details: null,\n                },\n            };\n        }\n\n        return {\n            status: 500,\n            body: {\n                error: 'Unknown error occurred',\n                details: null,\n            },\n        };\n    }\n\n    // oxlint-disable-next-line typescript/no-explicit-any\n    private isErrorClassInstance(error: unknown, ErrorClass: new (...args: any[]) => Error): error is Error {\n        if (!isError(error)) {\n            return false;\n        }\n\n        const expectedBrand = (ErrorClass as { BRAND?: unknown }).BRAND;\n        if (\n            typeof expectedBrand === 'string' &&\n            isObject(error) &&\n            (error as { __tangoBrand?: unknown }).__tangoBrand === expectedBrand\n        ) {\n            return true;\n        }\n\n        const constructorName = (error as { constructor?: { name?: unknown } }).constructor?.name;\n        if (typeof constructorName === 'string' && constructorName === ErrorClass.name) {\n            return true;\n        }\n\n        const errorName = (error as { name?: unknown }).name;\n        if (typeof errorName === 'string' && errorName === ErrorClass.name) {\n            return true;\n        }\n\n        return false;\n    }\n}\n","/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nexport { HttpErrorFactory, type HttpErrorFactoryConfig } from './HttpErrorFactory';\n","import { TangoError, type ErrorDetails } from './TangoError';\n\n/** Error for conflicting resource state (HTTP 409). */\nexport class ConflictError extends TangoError {\n    static readonly BRAND = 'tango.error.conflict' as const;\n    readonly __tangoBrand: typeof ConflictError.BRAND = ConflictError.BRAND;\n    status = 409;\n\n    /** Create a conflict error with optional custom message. */\n    constructor(message: string = 'Resource conflict') {\n        super(message);\n        this.name = 'ConflictError';\n        Object.setPrototypeOf(this, ConflictError.prototype);\n    }\n\n    /**\n     * Narrow an unknown value to `ConflictError`.\n     */\n    static isConflictError(value: unknown): value is ConflictError {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === ConflictError.BRAND\n        );\n    }\n\n    protected override getErrorName(): string {\n        return 'conflict';\n    }\n\n    protected override getDetails(): ErrorDetails {\n        return undefined;\n    }\n}\n","import { TangoError, type ErrorDetails } from './TangoError';\n\n/** Error for request validation failures (HTTP 400). */\nexport class ValidationError extends TangoError {\n    readonly __tangoValidationErrorBrand = 'tango.error.validation' as const;\n    status = 400;\n\n    constructor(\n        message: string,\n        public details?: ErrorDetails\n    ) {\n        super(message);\n        this.name = 'ValidationError';\n        Object.setPrototypeOf(this, ValidationError.prototype);\n    }\n\n    /**\n     * Narrow an unknown value to `ValidationError`, including common legacy shapes.\n     */\n    static isValidationError(err: unknown): err is ValidationError {\n        return (\n            (!!err &&\n                typeof err === 'object' &&\n                (err as { __tangoValidationErrorBrand?: string }).__tangoValidationErrorBrand ===\n                    'tango.error.validation') ||\n            (typeof err === 'object' &&\n                err !== null &&\n                'fields' in err &&\n                typeof (err as { fields: unknown }).fields === 'object')\n        );\n    }\n\n    protected override getErrorName(): string {\n        return 'ValidationError';\n    }\n\n    protected override getDetails(): ErrorDetails {\n        return this.details;\n    }\n}\n","import { TangoError, type ErrorDetails } from './TangoError';\n\n/** Error for missing resources (HTTP 404). */\nexport class NotFoundError extends TangoError {\n    static readonly BRAND = 'tango.error.not_found' as const;\n    readonly __tangoBrand: typeof NotFoundError.BRAND = NotFoundError.BRAND;\n    status = 404;\n\n    /** Create a not-found error with optional custom message. */\n    constructor(message: string = 'Resource not found') {\n        super(message);\n        this.name = 'NotFoundError';\n        Object.setPrototypeOf(this, NotFoundError.prototype);\n    }\n\n    /**\n     * Narrow an unknown value to `NotFoundError`.\n     */\n    static isNotFoundError(value: unknown): value is NotFoundError {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === NotFoundError.BRAND\n        );\n    }\n\n    protected override getErrorName(): string {\n        return 'not_found';\n    }\n\n    protected override getDetails(): ErrorDetails {\n        return undefined;\n    }\n}\n","import { TangoError, type ErrorDetails } from './TangoError';\n\n/** Error for authorization failures (HTTP 403). */\nexport class PermissionDenied extends TangoError {\n    static readonly BRAND = 'tango.error.permission_denied' as const;\n    readonly __tangoBrand: typeof PermissionDenied.BRAND = PermissionDenied.BRAND;\n    status = 403;\n\n    /** Create a permission-denied error with optional custom message. */\n    constructor(message: string = 'Permission denied') {\n        super(message);\n        this.name = 'PermissionDenied';\n        Object.setPrototypeOf(this, PermissionDenied.prototype);\n    }\n\n    /**\n     * Narrow an unknown value to `PermissionDenied`.\n     */\n    static isPermissionDenied(value: unknown): value is PermissionDenied {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === PermissionDenied.BRAND\n        );\n    }\n\n    protected override getErrorName(): string {\n        return 'permission_denied';\n    }\n\n    protected override getDetails(): ErrorDetails {\n        return undefined;\n    }\n}\n","import { TangoError, type ErrorDetails } from './TangoError';\n\n/** Error for missing/invalid authentication (HTTP 401). */\nexport class AuthenticationError extends TangoError {\n    static readonly BRAND = 'tango.error.authentication' as const;\n    readonly __tangoBrand: typeof AuthenticationError.BRAND = AuthenticationError.BRAND;\n    status = 401;\n\n    /** Create an authentication error with optional custom message. */\n    constructor(message: string = 'Authentication required') {\n        super(message);\n        this.name = 'AuthenticationError';\n        Object.setPrototypeOf(this, AuthenticationError.prototype);\n    }\n\n    /**\n     * Narrow an unknown value to `AuthenticationError`.\n     */\n    static isAuthenticationError(value: unknown): value is AuthenticationError {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === AuthenticationError.BRAND\n        );\n    }\n\n    protected override getErrorName(): string {\n        return 'authentication_error';\n    }\n\n    protected override getDetails(): ErrorDetails {\n        return undefined;\n    }\n}\n","/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nimport type { HttpError } from './HttpError';\nimport * as factories from './factories/index';\nimport { TangoError, type ErrorDetails, type ErrorEnvelope, type ProblemDetails } from './TangoError';\nimport { ConflictError } from './ConflictError';\nimport { ValidationError } from './ValidationError';\nimport { NotFoundError } from './NotFoundError';\nimport { PermissionDenied } from './PermissionDenied';\nimport { AuthenticationError } from './AuthenticationError';\nimport { HttpErrorFactory, type HttpErrorFactoryConfig } from './factories/HttpErrorFactory';\n\nexport {\n    AuthenticationError,\n    ConflictError,\n    HttpErrorFactory,\n    NotFoundError,\n    PermissionDenied,\n    TangoError,\n    ValidationError,\n    factories,\n};\n\nexport type { ErrorDetails, ErrorEnvelope, HttpError, HttpErrorFactoryConfig, ProblemDetails };\n"],"mappings":"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"}