@danypops/vehicle-core 0.10.0 → 0.12.0

package/dist/vehicle-errors.d.ts

@@ -14,6 +14,8 @@ export interface VehicleFailure {
     readonly recovery?: VehicleRecovery;
     readonly details?: JsonValue;
     readonly operationId?: string;
+    /** The underlying cause's own message, bounded (never a full stack trace). Only set when the throw site opts into exposeCause. */
+    readonly causeMessage?: string;
 }
 export interface VehicleErrorOptions {
     readonly category: VehicleFailureCategory;
@@ -23,7 +25,27 @@ export interface VehicleErrorOptions {
     readonly details?: JsonValue;
     readonly operationId?: string;
     readonly cause?: unknown;
+    /** Includes cause's message in toFailure().causeMessage. Default false -- an arbitrary cause could carry a credential or internal detail. */
+    readonly exposeCause?: boolean;
 }
+export type VehicleErrorClass = abstract new (...args: never[]) => Error;
+export interface VehicleErrorClassMapping {
+    readonly errorClass: VehicleErrorClass;
+    readonly category: VehicleFailureCategory;
+    readonly code?: string;
+}
+export interface VehicleErrorPredicateMapping {
+    readonly matches: (error: unknown) => boolean;
+    readonly category: VehicleFailureCategory;
+    readonly code?: string;
+}
+export type VehicleErrorMapping = VehicleErrorClassMapping | VehicleErrorPredicateMapping;
+export interface DefineErrorMappingOptions {
+    readonly fallbackCategory?: VehicleFailureCategory;
+    readonly fallbackCode?: string;
+}
+/** Maps reviewed domain errors into wire-safe Vehicle errors while preserving already-mapped failures. */
+export declare function defineErrorMapping(rules: readonly VehicleErrorMapping[], options?: DefineErrorMappingOptions): <T>(run: () => T | Promise<T>) => Promise<T>;
 export declare class VehicleError extends Error {
     readonly code: string;
     readonly category: VehicleFailureCategory;
@@ -32,7 +54,10 @@ export declare class VehicleError extends Error {
     readonly recovery?: VehicleRecovery;
     readonly details?: JsonValue;
     readonly operationId?: string;
+    private readonly exposeCause;
     constructor(code: string, message: string, options: VehicleErrorOptions);
     toFailure(): VehicleFailure;
 }
+/** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */
+export declare function boundedCauseMessage(cause: unknown): string | undefined;
 export declare function boundedValidationDetails(issues: readonly VehicleSchemaIssue[] | undefined): JsonValue | undefined;

package/dist/vehicle-errors.js

@@ -1,3 +1,21 @@
+/** Maps reviewed domain errors into wire-safe Vehicle errors while preserving already-mapped failures. */
+export function defineErrorMapping(rules, options = {}) {
+    return async (run) => {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (error instanceof VehicleError)
+                throw error;
+            const rule = rules.find((candidate) => "errorClass" in candidate ? error instanceof candidate.errorClass : candidate.matches(error));
+            const message = error instanceof Error ? error.message : String(error);
+            throw new VehicleError(rule?.code ?? options.fallbackCode ?? "operation-rejected", message, {
+                category: rule?.category ?? options.fallbackCategory ?? "validation",
+                cause: error,
+            });
+        }
+    };
+}
 export class VehicleError extends Error {
     code;
     category;
@@ -6,6 +24,7 @@ export class VehicleError extends Error {
     recovery;
     details;
     operationId;
+    exposeCause;
     constructor(code, message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
         this.code = code;
@@ -16,8 +35,10 @@ export class VehicleError extends Error {
         this.recovery = options.recovery;
         this.details = options.details;
         this.operationId = options.operationId;
+        this.exposeCause = options.exposeCause ?? false;
     }
     toFailure() {
+        const causeMessage = this.exposeCause ? boundedCauseMessage(this.cause) : undefined;
         return {
             code: this.code,
             category: this.category,
@@ -27,9 +48,19 @@ export class VehicleError extends Error {
             ...(this.recovery === undefined ? {} : { recovery: this.recovery }),
             ...(this.details === undefined ? {} : { details: this.details }),
             ...(this.operationId === undefined ? {} : { operationId: this.operationId }),
+            ...(causeMessage === undefined ? {} : { causeMessage }),
         };
     }
 }
+const MAX_CAUSE_MESSAGE_LENGTH = 500;
+/** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */
+export function boundedCauseMessage(cause) {
+    if (cause instanceof Error && cause.message.length > 0)
+        return cause.message.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+    if (typeof cause === "string" && cause.length > 0)
+        return cause.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+    return undefined;
+}
 const MAX_VALIDATION_ISSUES = 10;
 const MAX_ISSUE_MESSAGE_LENGTH = 500;
 const MAX_ISSUE_PATH_LENGTH = 20;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/vehicle-errors.ts

@@ -45,6 +45,8 @@ export interface VehicleFailure {
 	readonly recovery?: VehicleRecovery;
 	readonly details?: JsonValue;
 	readonly operationId?: string;
+	/** The underlying cause's own message, bounded (never a full stack trace). Only set when the throw site opts into exposeCause. */
+	readonly causeMessage?: string;
 }
 
 export interface VehicleErrorOptions {
@@ -55,6 +57,51 @@ export interface VehicleErrorOptions {
 	readonly details?: JsonValue;
 	readonly operationId?: string;
 	readonly cause?: unknown;
+	/** Includes cause's message in toFailure().causeMessage. Default false -- an arbitrary cause could carry a credential or internal detail. */
+	readonly exposeCause?: boolean;
+}
+
+export type VehicleErrorClass = abstract new (...args: never[]) => Error;
+
+export interface VehicleErrorClassMapping {
+	readonly errorClass: VehicleErrorClass;
+	readonly category: VehicleFailureCategory;
+	readonly code?: string;
+}
+
+export interface VehicleErrorPredicateMapping {
+	readonly matches: (error: unknown) => boolean;
+	readonly category: VehicleFailureCategory;
+	readonly code?: string;
+}
+
+export type VehicleErrorMapping = VehicleErrorClassMapping | VehicleErrorPredicateMapping;
+
+export interface DefineErrorMappingOptions {
+	readonly fallbackCategory?: VehicleFailureCategory;
+	readonly fallbackCode?: string;
+}
+
+/** Maps reviewed domain errors into wire-safe Vehicle errors while preserving already-mapped failures. */
+export function defineErrorMapping(
+	rules: readonly VehicleErrorMapping[],
+	options: DefineErrorMappingOptions = {},
+): <T>(run: () => T | Promise<T>) => Promise<T> {
+	return async <T>(run: () => T | Promise<T>): Promise<T> => {
+		try {
+			return await run();
+		} catch (error) {
+			if (error instanceof VehicleError) throw error;
+			const rule = rules.find((candidate) =>
+				"errorClass" in candidate ? error instanceof candidate.errorClass : candidate.matches(error),
+			);
+			const message = error instanceof Error ? error.message : String(error);
+			throw new VehicleError(rule?.code ?? options.fallbackCode ?? "operation-rejected", message, {
+				category: rule?.category ?? options.fallbackCategory ?? "validation",
+				cause: error,
+			});
+		}
+	};
 }
 
 export class VehicleError extends Error {
@@ -64,6 +111,7 @@ export class VehicleError extends Error {
 	readonly recovery?: VehicleRecovery;
 	readonly details?: JsonValue;
 	readonly operationId?: string;
+	private readonly exposeCause: boolean;
 
 	constructor(
 		readonly code: string,
@@ -78,9 +126,11 @@ export class VehicleError extends Error {
 		this.recovery = options.recovery;
 		this.details = options.details;
 		this.operationId = options.operationId;
+		this.exposeCause = options.exposeCause ?? false;
 	}
 
 	toFailure(): VehicleFailure {
+		const causeMessage = this.exposeCause ? boundedCauseMessage(this.cause) : undefined;
 		return {
 			code: this.code,
 			category: this.category,
@@ -90,10 +140,20 @@ export class VehicleError extends Error {
 			...(this.recovery === undefined ? {} : { recovery: this.recovery }),
 			...(this.details === undefined ? {} : { details: this.details }),
 			...(this.operationId === undefined ? {} : { operationId: this.operationId }),
+			...(causeMessage === undefined ? {} : { causeMessage }),
 		};
 	}
 }
 
+const MAX_CAUSE_MESSAGE_LENGTH = 500;
+
+/** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */
+export function boundedCauseMessage(cause: unknown): string | undefined {
+	if (cause instanceof Error && cause.message.length > 0) return cause.message.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+	if (typeof cause === "string" && cause.length > 0) return cause.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+	return undefined;
+}
+
 const MAX_VALIDATION_ISSUES = 10;
 const MAX_ISSUE_MESSAGE_LENGTH = 500;
 const MAX_ISSUE_PATH_LENGTH = 20;