@danypops/vehicle-core 0.10.0 → 0.11.0

package/dist/vehicle-errors.d.ts

@@ -14,6 +14,14 @@ export interface VehicleFailure {
     readonly recovery?: VehicleRecovery;
     readonly details?: JsonValue;
     readonly operationId?: string;
+    /**
+     * The underlying cause's own message, when this failure wraps an unexpected error (e.g. a
+     * handler throwing something other than a VehicleError) -- bounded, never a full stack trace.
+     * Without this, a caller sees only a generic template like "x handler failed" and has no way
+     * to tell what actually went wrong or whether the underlying operation may have partially
+     * applied.
+     */
+    readonly causeMessage?: string;
 }
 export interface VehicleErrorOptions {
     readonly category: VehicleFailureCategory;
@@ -23,6 +31,15 @@ export interface VehicleErrorOptions {
     readonly details?: JsonValue;
     readonly operationId?: string;
     readonly cause?: unknown;
+    /**
+     * Secure by default (false): `cause` is always attached to the real in-process Error chain
+     * (for server-side logging/observability), but its message crosses the wire via
+     * toFailure().causeMessage only when the throw site explicitly opts in here -- an arbitrary
+     * cause's message could contain a credential, an internal path, or other detail the thrower
+     * never reviewed for wire-safety. Set true only when the cause is known-safe to show (e.g. a
+     * validation library's own message intended for the caller).
+     */
+    readonly exposeCause?: boolean;
 }
 export declare class VehicleError extends Error {
     readonly code: string;
@@ -32,7 +49,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

@@ -6,6 +6,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 +17,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 +30,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.11.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,14 @@ export interface VehicleFailure {
 	readonly recovery?: VehicleRecovery;
 	readonly details?: JsonValue;
 	readonly operationId?: string;
+	/**
+	 * The underlying cause's own message, when this failure wraps an unexpected error (e.g. a
+	 * handler throwing something other than a VehicleError) -- bounded, never a full stack trace.
+	 * Without this, a caller sees only a generic template like "x handler failed" and has no way
+	 * to tell what actually went wrong or whether the underlying operation may have partially
+	 * applied.
+	 */
+	readonly causeMessage?: string;
 }
 
 export interface VehicleErrorOptions {
@@ -55,6 +63,15 @@ export interface VehicleErrorOptions {
 	readonly details?: JsonValue;
 	readonly operationId?: string;
 	readonly cause?: unknown;
+	/**
+	 * Secure by default (false): `cause` is always attached to the real in-process Error chain
+	 * (for server-side logging/observability), but its message crosses the wire via
+	 * toFailure().causeMessage only when the throw site explicitly opts in here -- an arbitrary
+	 * cause's message could contain a credential, an internal path, or other detail the thrower
+	 * never reviewed for wire-safety. Set true only when the cause is known-safe to show (e.g. a
+	 * validation library's own message intended for the caller).
+	 */
+	readonly exposeCause?: boolean;
 }
 
 export class VehicleError extends Error {
@@ -64,6 +81,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 +96,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 +110,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;