@scenarist/core 0.2.1 → 0.3.1

package/dist/types/config.d.ts

@@ -1,4 +1,24 @@
 import type { ScenaristScenarios } from "./scenario.js";
+/**
+ * How errors should be handled when they occur.
+ *
+ * - `throw`: Throw ScenaristError (strict - test fails with clear message)
+ * - `warn`: Log at warn level, return undefined (let strictMode decide next step)
+ * - `ignore`: Return undefined silently (let strictMode decide next step)
+ */
+export type ErrorBehavior = "throw" | "warn" | "ignore";
+/**
+ * Configuration for how different error types should be handled.
+ * Default is 'throw' for all (strict by default).
+ */
+export type ErrorBehaviors = {
+    /** How to handle when no mock matches a request. Default: 'throw' */
+    readonly onNoMockFound: ErrorBehavior;
+    /** How to handle when a sequence is exhausted. Default: 'throw' */
+    readonly onSequenceExhausted: ErrorBehavior;
+    /** How to handle when x-scenarist-test-id header is missing. Default: 'throw' */
+    readonly onMissingTestId: ErrorBehavior;
+};
 /**
  * Configuration for the scenario management system.
  * All properties are readonly for immutability.
@@ -35,6 +55,11 @@ export type ScenaristConfig = {
      * The default test ID to use when no x-scenarist-test-id header is present.
      */
     readonly defaultTestId: string;
+    /**
+     * How different error types should be handled.
+     * Default is 'throw' for all (strict by default).
+     */
+    readonly errorBehaviors: ErrorBehaviors;
 };
 /**
  * Partial config for user input - missing values will use defaults.
@@ -66,5 +91,9 @@ export type ScenaristConfigInput<T extends ScenaristScenarios = ScenaristScenari
      */
     readonly scenarios: T;
     readonly defaultTestId?: string;
+    /**
+     * Optional error behavior overrides. Missing values use 'throw' as default.
+     */
+    readonly errorBehaviors?: Partial<ErrorBehaviors>;
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE;QAClB,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAC9B,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC/C;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,mEAAmE;IACnE,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE;QAClB,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAC9B,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC/C;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACnD,CAAC"}

package/dist/types/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Standard error codes for Scenarist errors.
+ * Use these constants when creating ScenaristError instances.
+ */
+export declare const ErrorCodes: {
+    readonly SCENARIO_NOT_FOUND: "SCENARIO_NOT_FOUND";
+    readonly DUPLICATE_SCENARIO: "DUPLICATE_SCENARIO";
+    readonly NO_MOCK_FOUND: "NO_MOCK_FOUND";
+    readonly SEQUENCE_EXHAUSTED: "SEQUENCE_EXHAUSTED";
+    readonly MISSING_TEST_ID: "MISSING_TEST_ID";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Context information for Scenarist errors.
+ * Provides structured data to help diagnose and fix issues.
+ */
+export type ErrorContext = {
+    readonly testId?: string;
+    readonly scenarioId?: string;
+    readonly requestInfo?: {
+        readonly method: string;
+        readonly url: string;
+        readonly headers?: Record<string, string>;
+    };
+    readonly mockInfo?: {
+        readonly index: number;
+        readonly matchCriteria?: object;
+    };
+    readonly hint?: string;
+};
+/**
+ * Options for creating a ScenaristError.
+ */
+export type ScenaristErrorOptions = {
+    readonly code: string;
+    readonly context: ErrorContext;
+    readonly cause?: Error;
+};
+/**
+ * Base error class for all Scenarist errors.
+ * Includes error code and structured context for debugging.
+ */
+export declare class ScenaristError extends Error {
+    readonly code: string;
+    readonly context: ErrorContext;
+    constructor(message: string, options: ScenaristErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC3C,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB;CAM5D"}

package/dist/types/errors.js

@@ -0,0 +1,26 @@
+/**
+ * Standard error codes for Scenarist errors.
+ * Use these constants when creating ScenaristError instances.
+ */
+export const ErrorCodes = {
+    SCENARIO_NOT_FOUND: "SCENARIO_NOT_FOUND",
+    DUPLICATE_SCENARIO: "DUPLICATE_SCENARIO",
+    NO_MOCK_FOUND: "NO_MOCK_FOUND",
+    SEQUENCE_EXHAUSTED: "SEQUENCE_EXHAUSTED",
+    MISSING_TEST_ID: "MISSING_TEST_ID",
+    VALIDATION_ERROR: "VALIDATION_ERROR",
+};
+/**
+ * Base error class for all Scenarist errors.
+ * Includes error code and structured context for debugging.
+ */
+export class ScenaristError extends Error {
+    code;
+    context;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = "ScenaristError";
+        this.code = options.code;
+        this.context = options.context;
+    }
+}

package/dist/types/index.d.ts

@@ -1,4 +1,6 @@
 export type { HttpMethod, ScenaristResponse, ScenaristMock, ScenaristMatch, RepeatMode, ScenaristSequence, ScenaristCaptureConfig, ScenaristScenario, } from "../schemas/scenario-definition.js";
 export type { HttpRequestContext, ScenaristMockWithParams, ActiveScenario, ScenaristResult, ScenaristScenarios, ScenarioIds, } from "./scenario.js";
-export type { ScenaristConfig, ScenaristConfigInput } from "./config.js";
+export type { ScenaristConfig, ScenaristConfigInput, ErrorBehavior, ErrorBehaviors, } from "./config.js";
+export { ScenaristError, ErrorCodes } from "./errors.js";
+export type { ErrorContext, ErrorCode, ScenaristErrorOptions, } from "./errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,mCAAmC,CAAC;AAG3C,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,mCAAmC,CAAC;AAG3C,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,YAAY,EACZ,SAAS,EACT,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/types/index.js

@@ -1 +1,2 @@
-export {};
+// Error types
+export { ScenaristError, ErrorCodes } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenarist/core",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Internal: Hexagonal architecture core for scenario-based testing with MSW",
   "author": "Paul Hammond (citypaul) <paul@packsoftware.co.uk>",
   "license": "MIT",
@@ -51,11 +51,11 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.14",
-    "@vitest/ui": "^4.0.14",
+    "@vitest/ui": "^4.0.15",
     "eslint": "^9.39.1",
     "fast-check": "^4.3.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.14",
+    "vitest": "^4.0.15",
     "@scenarist/eslint-config": "0.0.0",
     "@scenarist/typescript-config": "0.0.0"
   },