@scenarist/core 0.0.1 → 0.1.0

package/dist/domain/regex-matching.d.ts

@@ -0,0 +1,20 @@
+import type { SerializedRegex } from '../schemas/match-criteria.js';
+/**
+ * Match a value against a regex pattern.
+ *
+ * **Security:**
+ * - ReDoS protection via schema validation (redos-detector) at trust boundary
+ * - Returns false on error (invalid regex syntax)
+ *
+ * **Usage:**
+ * ```typescript
+ * matchesRegex('summer-premium-sale', { source: 'premium|vip', flags: 'i' }) // true
+ * matchesRegex('summer-sale', { source: 'premium|vip', flags: 'i' }) // false
+ * ```
+ *
+ * @param value - String to test against pattern
+ * @param pattern - Serialized regex with source and optional flags
+ * @returns true if pattern matches, false otherwise
+ */
+export declare const matchesRegex: (value: string, pattern: SerializedRegex) => boolean;
+//# sourceMappingURL=regex-matching.d.ts.map

package/dist/domain/regex-matching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex-matching.d.ts","sourceRoot":"","sources":["../../src/domain/regex-matching.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,MAAM,EACb,SAAS,eAAe,KACvB,OAQF,CAAC"}

package/dist/domain/regex-matching.js

@@ -0,0 +1,27 @@
+/**
+ * Match a value against a regex pattern.
+ *
+ * **Security:**
+ * - ReDoS protection via schema validation (redos-detector) at trust boundary
+ * - Returns false on error (invalid regex syntax)
+ *
+ * **Usage:**
+ * ```typescript
+ * matchesRegex('summer-premium-sale', { source: 'premium|vip', flags: 'i' }) // true
+ * matchesRegex('summer-sale', { source: 'premium|vip', flags: 'i' }) // false
+ * ```
+ *
+ * @param value - String to test against pattern
+ * @param pattern - Serialized regex with source and optional flags
+ * @returns true if pattern matches, false otherwise
+ */
+export const matchesRegex = (value, pattern) => {
+    try {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        return regex.test(value);
+    }
+    catch (error) {
+        console.error('Regex matching error:', error);
+        return false;
+    }
+};

package/dist/domain/response-selector.d.ts

@@ -0,0 +1,22 @@
+import type { ResponseSelector, SequenceTracker, StateManager } from "../ports/index.js";
+/**
+ * Options for creating a response selector.
+ */
+type CreateResponseSelectorOptions = {
+    sequenceTracker?: SequenceTracker;
+    stateManager?: StateManager;
+};
+/**
+ * Creates a response selector domain service.
+ *
+ * Phase 1: Request content matching (body/headers/query)
+ * Phase 2: Response sequences with repeat modes
+ * Phase 3: Stateful mocks with capture/injection
+ *
+ * @param options - Configuration options
+ * @param options.sequenceTracker - Optional sequence position tracker (Phase 2)
+ * @param options.stateManager - Optional state manager for capture/injection (Phase 3)
+ */
+export declare const createResponseSelector: (options?: CreateResponseSelectorOptions) => ResponseSelector;
+export {};
+//# sourceMappingURL=response-selector.d.ts.map

package/dist/domain/response-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../src/domain/response-selector.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAazF;;GAEG;AACH,KAAK,6BAA6B,GAAG;IACnC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAS,6BAAkC,KAC1C,gBAwHF,CAAC"}

package/dist/domain/response-selector.js

@@ -0,0 +1,337 @@
+import { ResponseSelectionError } from "../ports/driven/response-selector.js";
+import { extractFromPath } from "./path-extraction.js";
+import { applyTemplates } from "./template-replacement.js";
+import { matchesRegex } from "./regex-matching.js";
+const SPECIFICITY_RANGES = {
+    MATCH_CRITERIA_BASE: 100,
+    SEQUENCE_FALLBACK: 1,
+    SIMPLE_FALLBACK: 0,
+};
+/**
+ * Creates a response selector domain service.
+ *
+ * Phase 1: Request content matching (body/headers/query)
+ * Phase 2: Response sequences with repeat modes
+ * Phase 3: Stateful mocks with capture/injection
+ *
+ * @param options - Configuration options
+ * @param options.sequenceTracker - Optional sequence position tracker (Phase 2)
+ * @param options.stateManager - Optional state manager for capture/injection (Phase 3)
+ */
+export const createResponseSelector = (options = {}) => {
+    const { sequenceTracker, stateManager } = options;
+    return {
+        selectResponse(testId, scenarioId, context, mocks) {
+            let bestMatch = null;
+            // Find all matching mocks and score them by specificity
+            for (let mockIndex = 0; mockIndex < mocks.length; mockIndex++) {
+                // Index is guaranteed in bounds by loop condition (0 <= mockIndex < length)
+                const mockWithParams = mocks[mockIndex];
+                const mock = mockWithParams.mock;
+                // Skip exhausted sequences (repeat: 'none' that have been exhausted)
+                if (mock.sequence && sequenceTracker) {
+                    const { exhausted } = sequenceTracker.getPosition(testId, scenarioId, mockIndex);
+                    if (exhausted) {
+                        continue; // Skip to next mock, allowing fallback to be selected
+                    }
+                }
+                // Check if this mock has match criteria
+                if (mock.match) {
+                    // If match criteria exists, check if it matches the request
+                    if (matchesCriteria(context, mock.match)) {
+                        // Match criteria always have higher priority than fallbacks
+                        // Base specificity ensures even 1 field beats any fallback
+                        const specificity = SPECIFICITY_RANGES.MATCH_CRITERIA_BASE + calculateSpecificity(mock.match);
+                        // Keep this mock if it's more specific than current best
+                        // (or if no best match yet)
+                        if (!bestMatch || specificity > bestMatch.specificity) {
+                            bestMatch = { mockWithParams, mockIndex, specificity };
+                        }
+                    }
+                    // If match criteria exists but doesn't match, skip to next mock
+                    continue;
+                }
+                // No match criteria = fallback mock (always matches)
+                // Sequences get higher priority than simple responses
+                // This ensures sequences are selected over simple fallback responses
+                const fallbackSpecificity = mock.sequence
+                    ? SPECIFICITY_RANGES.SEQUENCE_FALLBACK
+                    : SPECIFICITY_RANGES.SIMPLE_FALLBACK;
+                if (!bestMatch || fallbackSpecificity >= bestMatch.specificity) {
+                    // For equal specificity fallbacks, last wins
+                    // This allows active scenario mocks to override default mocks
+                    // Applies to both simple fallbacks (0) and sequence fallbacks (1)
+                    bestMatch = { mockWithParams, mockIndex, specificity: fallbackSpecificity };
+                }
+            }
+            // Return the best matching mock
+            if (bestMatch) {
+                const { mockWithParams, mockIndex } = bestMatch;
+                const mock = mockWithParams.mock;
+                // Select response (either single or from sequence)
+                const response = selectResponseFromMock(testId, scenarioId, mockIndex, mock, sequenceTracker);
+                if (!response) {
+                    return {
+                        success: false,
+                        error: new ResponseSelectionError(`Mock has neither response nor sequence field`),
+                    };
+                }
+                // Phase 3: Capture state from request if configured
+                if (mock.captureState && stateManager) {
+                    captureState(testId, context, mock.captureState, stateManager);
+                }
+                // Apply templates to response (both state AND params)
+                let finalResponse = response;
+                if (stateManager || mockWithParams.params) {
+                    const currentState = stateManager ? stateManager.getAll(testId) : {};
+                    // Merge state and params for template replacement
+                    // params take precedence over state for the same key
+                    const templateData = {
+                        state: currentState,
+                        params: mockWithParams.params || {},
+                    };
+                    finalResponse = applyTemplates(response, templateData);
+                }
+                return { success: true, data: finalResponse };
+            }
+            // No mock matched
+            return {
+                success: false,
+                error: new ResponseSelectionError(`No mock matched for ${context.method} ${context.url}`),
+            };
+        },
+    };
+};
+/**
+ * Select a response from a mock (either single response or from sequence).
+ *
+ * @param testId - Test ID for sequence tracking
+ * @param scenarioId - Scenario ID for sequence tracking
+ * @param mockIndex - Index of the mock in the mocks array
+ * @param mock - The mock definition
+ * @param sequenceTracker - Optional sequence tracker for Phase 2
+ * @returns ScenaristResponse or null if mock has neither response nor sequence
+ */
+const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTracker) => {
+    // Phase 2: If mock has a sequence, use sequence tracker
+    if (mock.sequence) {
+        if (!sequenceTracker) {
+            // Sequence defined but no tracker provided - return first response
+            return mock.sequence.responses[0] || null;
+        }
+        // Get current position from tracker
+        const { position } = sequenceTracker.getPosition(testId, scenarioId, mockIndex);
+        // Get response at current position
+        // Note: Exhausted sequences are skipped during matching phase,
+        // so position should always be valid here
+        const response = mock.sequence.responses[position];
+        // Advance position for next call
+        const repeatMode = mock.sequence.repeat || 'last';
+        sequenceTracker.advance(testId, scenarioId, mockIndex, mock.sequence.responses.length, repeatMode);
+        return response;
+    }
+    // Phase 1: Single response
+    if (mock.response) {
+        return mock.response;
+    }
+    // Neither response nor sequence defined
+    return null;
+};
+/**
+ * Calculate specificity score for match criteria.
+ * Higher score = more specific match.
+ *
+ * Scoring:
+ * - URL match = +1 point
+ * - Each body field = +1 point
+ * - Each header = +1 point
+ * - Each query param = +1 point
+ *
+ * Example:
+ * { body: { itemType: 'premium' } } = 1 point
+ * { body: { itemType: 'premium', quantity: 5 }, headers: { 'x-tier': 'gold' } } = 3 points
+ * { url: '/api/products', body: { itemType: 'premium' } } = 2 points
+ */
+const calculateSpecificity = (criteria) => {
+    let score = 0;
+    if (criteria.url) {
+        score += 1;
+    }
+    if (criteria.body) {
+        score += Object.keys(criteria.body).length;
+    }
+    if (criteria.headers) {
+        score += Object.keys(criteria.headers).length;
+    }
+    if (criteria.query) {
+        score += Object.keys(criteria.query).length;
+    }
+    return score;
+};
+/**
+ * Check if request context matches the specified criteria.
+ * All specified criteria must match for the overall match to succeed.
+ */
+const matchesCriteria = (context, criteria) => {
+    // Check URL match (exact match or pattern)
+    if (criteria.url) {
+        if (!matchesValue(context.url, criteria.url)) {
+            return false;
+        }
+    }
+    // Check body match (partial match)
+    if (criteria.body) {
+        if (!matchesBody(context.body, criteria.body)) {
+            return false;
+        }
+    }
+    // Check headers match (exact match on specified headers)
+    if (criteria.headers) {
+        if (!matchesHeaders(context.headers, criteria.headers)) {
+            return false;
+        }
+    }
+    // Check query match (exact match on specified query params)
+    if (criteria.query) {
+        if (!matchesQuery(context.query, criteria.query)) {
+            return false;
+        }
+    }
+    // All criteria matched
+    return true;
+};
+/**
+ * Check if request body contains all required fields (partial match).
+ * Request can have additional fields beyond what's specified in criteria.
+ * Supports all matching strategies via MatchValue type.
+ * Non-string values are converted to strings before matching.
+ */
+const matchesBody = (requestBody, criteriaBody) => {
+    // If request has no body, can't match
+    if (!requestBody || typeof requestBody !== "object") {
+        return false;
+    }
+    const body = requestBody;
+    // Check all required fields exist in request body with matching values
+    for (const [key, criteriaValue] of Object.entries(criteriaBody)) {
+        const requestValue = body[key];
+        // Convert to string for matching (type coercion like headers/query)
+        const stringValue = requestValue == null ? '' : String(requestValue);
+        if (!matchesValue(stringValue, criteriaValue)) {
+            return false;
+        }
+    }
+    return true;
+};
+// Header matching follows RFC 2616 (case-insensitive names, case-sensitive values)
+const normalizeHeaderName = (name) => name.toLowerCase();
+const createNormalizedHeaderMap = (headers) => {
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalized[normalizeHeaderName(key)] = value;
+    }
+    return normalized;
+};
+/**
+ * Match a request value against a match criteria value.
+ *
+ * Supports 7 matching modes:
+ * 1. Plain string: exact match (backward compatible)
+ * 2. Native RegExp: pattern match (e.g., /\/users\/\d+/)
+ * 3. { equals: 'value' }: explicit exact match
+ * 4. { contains: 'substring' }: substring match
+ * 5. { startsWith: 'prefix' }: prefix match
+ * 6. { endsWith: 'suffix' }: suffix match
+ * 7. { regex: {...} }: pattern match (serialized form)
+ *
+ * Type Coercion Behavior:
+ * - Non-string criterion values (number, boolean) are converted to strings before matching
+ * - null/undefined criterion values are converted to empty string ''
+ * - Request value is always expected to be a string
+ * - Strategy values within objects are converted to strings (e.g., contains: 123 → '123')
+ *
+ * This allows backward compatibility with scenarios using non-string values
+ * in body matching (e.g., { quantity: 5 } matches body.quantity = 5 or "5")
+ *
+ * @param requestValue - The actual value from the request (string)
+ * @param criteriaValue - The expected value (string, RegExp, number, boolean, null, or strategy object)
+ * @returns true if values match, false otherwise
+ */
+const matchesValue = (requestValue, criteriaValue) => {
+    if (typeof criteriaValue === "string") {
+        return requestValue === criteriaValue;
+    }
+    // Native RegExp support (ADR-0016)
+    if (criteriaValue instanceof RegExp) {
+        return matchesRegex(requestValue, {
+            source: criteriaValue.source,
+            flags: criteriaValue.flags,
+        });
+    }
+    if (typeof criteriaValue === "number" || typeof criteriaValue === "boolean") {
+        return requestValue === String(criteriaValue);
+    }
+    if (criteriaValue == null) {
+        return requestValue === '';
+    }
+    const strategyValue = criteriaValue;
+    if (strategyValue.equals !== undefined) {
+        return requestValue === String(strategyValue.equals);
+    }
+    if (strategyValue.contains !== undefined) {
+        return requestValue.includes(String(strategyValue.contains));
+    }
+    if (strategyValue.startsWith !== undefined) {
+        return requestValue.startsWith(String(strategyValue.startsWith));
+    }
+    if (strategyValue.endsWith !== undefined) {
+        return requestValue.endsWith(String(strategyValue.endsWith));
+    }
+    if (strategyValue.regex !== undefined) {
+        return matchesRegex(requestValue, strategyValue.regex);
+    }
+    return false;
+};
+const matchesHeaders = (requestHeaders, criteriaHeaders) => {
+    const normalizedRequest = createNormalizedHeaderMap(requestHeaders);
+    for (const [key, value] of Object.entries(criteriaHeaders)) {
+        const normalizedKey = normalizeHeaderName(key);
+        const requestValue = normalizedRequest[normalizedKey];
+        if (!requestValue || !matchesValue(requestValue, value)) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Check if request query params contain all specified params with exact values.
+ * Request can have additional query params beyond what's specified in criteria.
+ */
+const matchesQuery = (requestQuery, criteriaQuery) => {
+    // Check all required query params exist with exact matching values
+    for (const [key, value] of Object.entries(criteriaQuery)) {
+        const requestValue = requestQuery[key];
+        if (!requestValue || !matchesValue(requestValue, value)) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Captures state from request based on CaptureState configuration.
+ *
+ * @param testId - Test ID for state isolation
+ * @param context - HTTP request context
+ * @param captureConfig - Capture configuration (state key -> path expression)
+ * @param stateManager - State manager to store captured values
+ */
+const captureState = (testId, context, captureConfig, stateManager) => {
+    for (const [stateKey, pathExpression] of Object.entries(captureConfig)) {
+        const value = extractFromPath(context, pathExpression);
+        // Guard: Only capture if value exists
+        if (value === undefined) {
+            continue;
+        }
+        stateManager.set(testId, stateKey, value);
+    }
+};

package/dist/domain/scenario-manager.d.ts

@@ -0,0 +1,20 @@
+import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker, StateManager } from "../ports/index.js";
+/**
+ * Factory function to create a ScenarioManager implementation.
+ *
+ * Follows dependency injection principle - all ports are injected, never created internally.
+ *
+ * This enables:
+ * - Any registry implementation (in-memory, Redis, files, remote)
+ * - Any store implementation (in-memory, Redis, database)
+ * - Any state manager implementation (in-memory, Redis, database)
+ * - Proper testing with mock dependencies
+ * - True hexagonal architecture
+ */
+export declare const createScenarioManager: ({ registry, store, stateManager, sequenceTracker, }: {
+    registry: ScenarioRegistry;
+    store: ScenarioStore;
+    stateManager?: StateManager;
+    sequenceTracker?: SequenceTracker;
+}) => ScenarioManager;
+//# sourceMappingURL=scenario-manager.d.ts.map

package/dist/domain/scenario-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-manager.d.ts","sourceRoot":"","sources":["../../src/domain/scenario-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC;AA6B3B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAAI,qDAKnC;IACD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,KAAG,eAgFH,CAAC"}

package/dist/domain/scenario-manager.js

@@ -0,0 +1,90 @@
+import { ScenaristScenarioSchema } from "../schemas/index.js";
+class ScenarioNotFoundError extends Error {
+    constructor(scenarioId) {
+        super(`Scenario '${scenarioId}' not found. Did you forget to register it?`);
+        this.name = "ScenarioNotFoundError";
+    }
+}
+class DuplicateScenarioError extends Error {
+    constructor(scenarioId) {
+        super(`Scenario '${scenarioId}' is already registered. Each scenario must have a unique ID.`);
+        this.name = "DuplicateScenarioError";
+    }
+}
+class ScenarioValidationError extends Error {
+    validationErrors;
+    constructor(message, validationErrors) {
+        super(message);
+        this.validationErrors = validationErrors;
+        this.name = "ScenarioValidationError";
+    }
+}
+/**
+ * Factory function to create a ScenarioManager implementation.
+ *
+ * Follows dependency injection principle - all ports are injected, never created internally.
+ *
+ * This enables:
+ * - Any registry implementation (in-memory, Redis, files, remote)
+ * - Any store implementation (in-memory, Redis, database)
+ * - Any state manager implementation (in-memory, Redis, database)
+ * - Proper testing with mock dependencies
+ * - True hexagonal architecture
+ */
+export const createScenarioManager = ({ registry, store, stateManager, sequenceTracker, }) => {
+    return {
+        registerScenario(definition) {
+            // Validate scenario definition at trust boundary
+            const validationResult = ScenaristScenarioSchema.safeParse(definition);
+            if (!validationResult.success) {
+                const errorMessages = validationResult.error.issues.map((err) => `${err.path.join('.')}: ${err.message}`);
+                const scenarioId = definition?.id || '<unknown>';
+                throw new ScenarioValidationError(`Invalid scenario definition for '${scenarioId}': ${errorMessages.join(', ')}`, errorMessages);
+            }
+            const existing = registry.get(definition.id);
+            // Allow re-registering the exact same scenario object (idempotent)
+            if (existing === definition) {
+                return;
+            }
+            // Prevent registering a different scenario with the same ID
+            if (existing) {
+                throw new DuplicateScenarioError(definition.id);
+            }
+            registry.register(definition);
+        },
+        switchScenario(testId, scenarioId) {
+            const definition = registry.get(scenarioId);
+            if (!definition) {
+                return {
+                    success: false,
+                    error: new ScenarioNotFoundError(scenarioId),
+                };
+            }
+            const activeScenario = {
+                scenarioId,
+            };
+            store.set(testId, activeScenario);
+            // Phase 2: Reset sequence positions on scenario switch (clean slate)
+            if (sequenceTracker) {
+                sequenceTracker.reset(testId);
+            }
+            // Phase 3: Reset state on scenario switch (clean slate)
+            if (stateManager) {
+                stateManager.reset(testId);
+            }
+            return { success: true, data: undefined };
+        },
+        getActiveScenario(testId) {
+            return store.get(testId);
+        },
+        listScenarios() {
+            return registry.list();
+        },
+        clearScenario(testId) {
+            store.delete(testId);
+        },
+        getScenarioById(id) {
+            return registry.get(id);
+        },
+    };
+};

package/dist/domain/template-replacement.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Applies templates to a value.
+ * Replaces {{state.key}} and {{params.key}} patterns with actual values.
+ *
+ * @param value - Value to apply templates to (string, object, array, or primitive)
+ * @param templateData - Object containing state and params for template replacement.
+ *                       Can be flat object (backward compatible) or { state: {...}, params: {...} }
+ * @returns Value with templates replaced
+ */
+export declare const applyTemplates: (value: unknown, templateData: Record<string, unknown>) => unknown;
+//# sourceMappingURL=template-replacement.d.ts.map

package/dist/domain/template-replacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-replacement.d.ts","sourceRoot":"","sources":["../../src/domain/template-replacement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,EAAE,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAsDtF,CAAC"}

package/dist/domain/template-replacement.js

@@ -0,0 +1,94 @@
+/**
+ * Applies templates to a value.
+ * Replaces {{state.key}} and {{params.key}} patterns with actual values.
+ *
+ * @param value - Value to apply templates to (string, object, array, or primitive)
+ * @param templateData - Object containing state and params for template replacement.
+ *                       Can be flat object (backward compatible) or { state: {...}, params: {...} }
+ * @returns Value with templates replaced
+ */
+export const applyTemplates = (value, templateData) => {
+    // Backward compatibility: If templateData doesn't have 'state' or 'params' keys,
+    // treat it as a flat state object and wrap it
+    const normalizedData = (templateData.state !== undefined || templateData.params !== undefined)
+        ? templateData
+        : { state: templateData, params: {} };
+    // Guard: Handle strings (base case)
+    if (typeof value === 'string') {
+        // Check if entire string is a single pure template (no surrounding text)
+        // Supports both {{state.key}} and {{params.key}}
+        const pureTemplateMatch = /^\{\{(state|params)\.([^}]+)\}\}$/.exec(value);
+        if (pureTemplateMatch) {
+            // Pure template: return raw value (preserves type - arrays, numbers, objects)
+            const prefix = pureTemplateMatch[1]; // 'state' or 'params'
+            const path = pureTemplateMatch[2]; // Guaranteed to exist by regex capture group
+            const resolvedValue = resolveTemplatePath(normalizedData, prefix, path);
+            // Return raw value if found, otherwise return null (JSON-safe)
+            // null is used instead of undefined to ensure JSON serialization preserves the field
+            return resolvedValue !== undefined ? resolvedValue : null;
+        }
+        // Mixed template (has surrounding text): use string replacement
+        // Supports both {{state.key}} and {{params.key}}
+        return value.replace(/\{\{(state|params)\.([^}]+)\}\}/g, (match, prefix, path) => {
+            const resolvedValue = resolveTemplatePath(normalizedData, prefix, path);
+            // Guard: Missing keys remain as template
+            if (resolvedValue === undefined) {
+                return match;
+            }
+            // Convert to string for concatenation with surrounding text
+            return String(resolvedValue);
+        });
+    }
+    // Guard: Handle arrays recursively
+    if (Array.isArray(value)) {
+        return value.map((item) => applyTemplates(item, normalizedData));
+    }
+    // Guard: Handle objects recursively
+    if (typeof value === 'object' && value !== null) {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = applyTemplates(val, normalizedData);
+        }
+        return result;
+    }
+    // Primitives (number, boolean, null) returned unchanged
+    return value;
+};
+/**
+ * Resolves a template path like 'state.key' or 'params.userId'.
+ * Supports nested paths like 'state.user.profile.name' and 'params.path.length'.
+ *
+ * @param templateData - Template data object containing state and params
+ * @param prefix - Template prefix ('state' or 'params')
+ * @param path - Path to resolve after prefix (e.g., 'user.name' or 'userId')
+ * @returns Value at path, or undefined if not found
+ */
+const resolveTemplatePath = (templateData, prefix, path) => {
+    // Get the root object (state or params)
+    const root = templateData[prefix];
+    // Guard: Prefix doesn't exist (e.g., no params provided)
+    if (root === undefined || typeof root !== 'object' || root === null) {
+        return undefined;
+    }
+    // Resolve nested path within root object
+    const segments = path.split('.');
+    let current = root;
+    for (const segment of segments) {
+        // Guard: Can't traverse non-objects
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        // Handle arrays with .length property
+        if (Array.isArray(current) && segment === 'length') {
+            return current.length;
+        }
+        // Traverse object
+        const record = current;
+        current = record[segment];
+        // Guard: Return undefined if property doesn't exist
+        if (current === undefined) {
+            return undefined;
+        }
+    }
+    return current;
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './types/index.js';
+export * from './schemas/index.js';
+export * from './constants/index.js';
+export type * from './ports/index.js';
+export type * from './contracts/index.js';
+export * from './domain/index.js';
+export * from './adapters/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,kBAAkB,CAAC;AAGtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,mBAAmB,kBAAkB,CAAC;AAGtC,mBAAmB,sBAAsB,CAAC;AAG1C,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Schemas (runtime validation)
+export * from './schemas/index.js';
+// Constants
+export * from './constants/index.js';
+// Domain (implementations)
+export * from './domain/index.js';
+// Adapters (default implementations)
+export * from './adapters/index.js';