tywrap 0.2.0 → 0.3.0

package/dist/runtime/transport.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Transport layer for BridgeProtocol.
+ *
+ * Provides an abstract I/O channel for all bridge communications across
+ * the JS-Python boundary. Concrete implementations handle different runtimes:
+ * - ProcessIO: Child process with stdio streams (Node.js)
+ * - HttpIO: HTTP POST requests (remote Python server)
+ * - PyodideIO: In-memory Pyodide calls (browser/WASM)
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import type { Disposable } from './disposable.js';
+/** Protocol identifier for tywrap communication */
+export declare const PROTOCOL_ID = "tywrap/1";
+/**
+ * Protocol message format for all transports.
+ *
+ * Each method corresponds to a BridgeProtocol operation:
+ * - `call`: Invoke a module-level function
+ * - `instantiate`: Create a new class instance
+ * - `call_method`: Invoke a method on an existing instance
+ * - `dispose_instance`: Release an instance handle
+ * - `meta`: Get bridge metadata
+ */
+export interface ProtocolMessage {
+    /** Unique message identifier for request-response correlation */
+    id: number;
+    /** Protocol identifier (must be 'tywrap/1') */
+    protocol: typeof PROTOCOL_ID;
+    /** The method to invoke */
+    method: 'call' | 'instantiate' | 'call_method' | 'dispose_instance' | 'meta';
+    /** Method parameters */
+    params: {
+        /** Python module path (for call and instantiate) */
+        module?: string;
+        /** Function name (for call) */
+        functionName?: string;
+        /** Class name (for instantiate) */
+        className?: string;
+        /** Instance handle (for call_method and dispose_instance) */
+        handle?: string;
+        /** Method name (for call_method) */
+        methodName?: string;
+        /** Positional arguments */
+        args?: unknown[];
+        /** Keyword arguments */
+        kwargs?: Record<string, unknown>;
+    };
+}
+/**
+ * Protocol response format from the Python side.
+ *
+ * A response contains either a result or an error, never both.
+ * The `id` field correlates the response to its originating request.
+ */
+export interface ProtocolResponse {
+    /** Message identifier matching the originating request */
+    id: number;
+    /** Protocol identifier (echoed back from request) */
+    protocol?: string;
+    /** Successful result value (undefined if error occurred) */
+    result?: unknown;
+    /** Error information (undefined if operation succeeded) */
+    error?: {
+        /** Python exception type name */
+        type: string;
+        /** Error message */
+        message: string;
+        /** Optional Python traceback for debugging */
+        traceback?: string;
+    };
+}
+/**
+ * Abstract transport for sending messages across the JS-Python boundary.
+ *
+ * Transport implementations handle the low-level I/O details while
+ * providing a consistent interface for the higher-level BridgeProtocol.
+ *
+ * Lifecycle:
+ * 1. Create transport instance
+ * 2. Call `init()` to establish the connection
+ * 3. Use `send()` to exchange messages
+ * 4. Call `dispose()` to release resources
+ *
+ * Implementations:
+ * - ProcessIO: Spawns a Python child process, communicates via stdio
+ * - HttpIO: Sends HTTP POST requests to a Python server
+ * - PyodideIO: Calls Pyodide directly in-memory (WASM)
+ *
+ * @example
+ * ```typescript
+ * const transport = new ProcessIO({ pythonPath: 'python3' });
+ * await transport.init();
+ *
+ * const response = await transport.send(
+ *   JSON.stringify({
+ *     id: 1,
+ *     protocol: 'tywrap/1',
+ *     method: 'call',
+ *     params: { module: 'math', functionName: 'sqrt', args: [16], kwargs: {} },
+ *   }),
+ *   5000
+ * );
+ *
+ * await transport.dispose();
+ * ```
+ */
+export interface Transport extends Disposable {
+    /**
+     * Initialize the transport.
+     *
+     * This method establishes the underlying connection (e.g., spawns a process,
+     * opens a connection). It must be called before `send()` can be used.
+     *
+     * This method should be idempotent - calling it multiple times after
+     * successful initialization should be a no-op.
+     *
+     * @throws BridgeError if initialization fails
+     */
+    init(): Promise<void>;
+    /**
+     * Send a message and wait for the response.
+     *
+     * @param message - The JSON-encoded protocol message to send
+     * @param timeoutMs - Timeout in milliseconds (0 = no timeout)
+     * @param signal - Optional AbortSignal for external cancellation
+     * @returns The raw response string (JSON-encoded ProtocolResponse)
+     *
+     * @throws BridgeTimeoutError if the operation times out or is aborted
+     * @throws BridgeDisposedError if the transport has been disposed
+     * @throws BridgeProtocolError if the message format is invalid
+     * @throws BridgeError for other transport-level failures
+     */
+    send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string>;
+    /**
+     * Whether the transport is ready to send messages.
+     *
+     * Returns `true` after successful `init()` and before `dispose()`.
+     * Returns `false` in all other states.
+     */
+    readonly isReady: boolean;
+}
+/**
+ * Base options for creating a Transport.
+ *
+ * Concrete transport implementations may extend this with
+ * additional configuration options.
+ */
+export interface TransportOptions {
+    /**
+     * Default timeout for operations in milliseconds.
+     *
+     * This timeout applies to individual `send()` calls when
+     * no explicit timeout is provided.
+     *
+     * @default 30000 (30 seconds)
+     */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Type guard to check if a value implements the Transport interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has all required Transport methods and properties
+ *
+ * @example
+ * ```typescript
+ * function useTransport(maybeTransport: unknown) {
+ *   if (isTransport(maybeTransport)) {
+ *     await maybeTransport.init();
+ *     // TypeScript now knows maybeTransport is Transport
+ *   }
+ * }
+ * ```
+ */
+export declare function isTransport(value: unknown): value is Transport;
+/**
+ * Type guard to check if a value is a valid ProtocolMessage.
+ *
+ * @param value - The value to check
+ * @returns True if the value conforms to the ProtocolMessage structure
+ */
+export declare function isProtocolMessage(value: unknown): value is ProtocolMessage;
+/**
+ * Type guard to check if a value is a valid ProtocolResponse.
+ *
+ * @param value - The value to check
+ * @returns True if the value conforms to the ProtocolResponse structure
+ */
+export declare function isProtocolResponse(value: unknown): value is ProtocolResponse;
+//# sourceMappingURL=transport.d.ts.map

package/dist/runtime/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/runtime/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMlD,mDAAmD;AACnD,eAAO,MAAM,WAAW,aAAa,CAAC;AAMtC;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IAEX,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,WAAW,CAAC;IAE7B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;IAE7E,wBAAwB;IACxB,MAAM,EAAE;QACN,oDAAoD;QACpD,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,+BAA+B;QAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB,mCAAmC;QACnC,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB,6DAA6D;QAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,oCAAoC;QACpC,UAAU,CAAC,EAAE,MAAM,CAAC;QAEpB,2BAA2B;QAC3B,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;QAEjB,wBAAwB;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,2DAA2D;IAC3D,KAAK,CAAC,EAAE;QACN,iCAAiC;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,oBAAoB;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,8CAA8C;QAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C;;;;;;;;;;OAUG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhF;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAS9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAe1E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAqB5E"}

package/dist/runtime/transport.js

@@ -0,0 +1,86 @@
+/**
+ * Transport layer for BridgeProtocol.
+ *
+ * Provides an abstract I/O channel for all bridge communications across
+ * the JS-Python boundary. Concrete implementations handle different runtimes:
+ * - ProcessIO: Child process with stdio streams (Node.js)
+ * - HttpIO: HTTP POST requests (remote Python server)
+ * - PyodideIO: In-memory Pyodide calls (browser/WASM)
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+// =============================================================================
+// PROTOCOL CONSTANTS
+// =============================================================================
+/** Protocol identifier for tywrap communication */
+export const PROTOCOL_ID = 'tywrap/1';
+// =============================================================================
+// TYPE GUARDS
+// =============================================================================
+/**
+ * Type guard to check if a value implements the Transport interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has all required Transport methods and properties
+ *
+ * @example
+ * ```typescript
+ * function useTransport(maybeTransport: unknown) {
+ *   if (isTransport(maybeTransport)) {
+ *     await maybeTransport.init();
+ *     // TypeScript now knows maybeTransport is Transport
+ *   }
+ * }
+ * ```
+ */
+export function isTransport(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.init === 'function' &&
+        typeof value.send === 'function' &&
+        typeof value.dispose === 'function' &&
+        'isReady' in value);
+}
+/**
+ * Type guard to check if a value is a valid ProtocolMessage.
+ *
+ * @param value - The value to check
+ * @returns True if the value conforms to the ProtocolMessage structure
+ */
+export function isProtocolMessage(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const msg = value;
+    return (typeof msg.id === 'number' &&
+        msg.protocol === PROTOCOL_ID &&
+        typeof msg.method === 'string' &&
+        ['call', 'instantiate', 'call_method', 'dispose_instance', 'meta'].includes(msg.method) &&
+        typeof msg.params === 'object' &&
+        msg.params !== null);
+}
+/**
+ * Type guard to check if a value is a valid ProtocolResponse.
+ *
+ * @param value - The value to check
+ * @returns True if the value conforms to the ProtocolResponse structure
+ */
+export function isProtocolResponse(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const resp = value;
+    if (typeof resp.id !== 'number') {
+        return false;
+    }
+    // Must have either result or error (or neither for void returns)
+    if (resp.error !== undefined) {
+        if (typeof resp.error !== 'object' || resp.error === null) {
+            return false;
+        }
+        const err = resp.error;
+        return typeof err.type === 'string' && typeof err.message === 'string';
+    }
+    return true;
+}
+//# sourceMappingURL=transport.js.map

package/dist/runtime/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/runtime/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,mDAAmD;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAiLtC,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAQ,KAAmB,CAAC,IAAI,KAAK,UAAU;QAC/C,OAAQ,KAAmB,CAAC,IAAI,KAAK,UAAU;QAC/C,OAAQ,KAAmB,CAAC,OAAO,KAAK,UAAU;QAClD,SAAS,IAAI,KAAK,CACnB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAG,KAAwB,CAAC;IAErC,OAAO,CACL,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAC1B,GAAG,CAAC,QAAQ,KAAK,WAAW;QAC5B,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAC9B,CAAC,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;QACvF,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAC9B,GAAG,CAAC,MAAM,KAAK,IAAI,CACpB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,KAAyB,CAAC;IAEvC,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iEAAiE;IACjE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;QACvB,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC;IACzE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runtime/validators.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Pure validation functions for runtime value checking.
+ *
+ * These functions are used by BoundedContext and can also be used
+ * independently for validation in CLI tools, config loading, etc.
+ */
+/**
+ * Error thrown when validation fails.
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Check if a value is a finite number (not NaN, not Infinity).
+ */
+export declare function isFiniteNumber(value: unknown): value is number;
+/**
+ * Check if a value is a positive finite number.
+ */
+export declare function isPositiveNumber(value: unknown): value is number;
+/**
+ * Check if a value is a non-negative finite number.
+ */
+export declare function isNonNegativeNumber(value: unknown): value is number;
+/**
+ * Check if a value is a non-empty string.
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Assert that a value is a finite number.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a finite number
+ */
+export declare function assertFiniteNumber(value: unknown, name: string): number;
+/**
+ * Assert that a value is a positive number (> 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a positive number
+ */
+export declare function assertPositive(value: unknown, name: string): number;
+/**
+ * Assert that a value is a non-negative number (>= 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a non-negative number
+ */
+export declare function assertNonNegative(value: unknown, name: string): number;
+/**
+ * Assert that a value is a string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a string
+ */
+export declare function assertString(value: unknown, name: string): string;
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a non-empty string
+ */
+export declare function assertNonEmptyString(value: unknown, name: string): string;
+/**
+ * Assert that a value is an array.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as an array
+ * @throws ValidationError if the value is not an array
+ */
+export declare function assertArray<T = unknown>(value: unknown, name: string): T[];
+/**
+ * Assert that a value is a plain object (not null, not array).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a Record
+ * @throws ValidationError if the value is not a plain object
+ */
+export declare function assertObject(value: unknown, name: string): Record<string, unknown>;
+export declare function containsSpecialFloat(value: unknown): boolean;
+/**
+ * Assert that a value does not contain non-finite numbers.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @throws ValidationError if the value contains NaN or Infinity
+ */
+export declare function assertNoSpecialFloats(value: unknown, name: string): void;
+/**
+ * Sanitize a string for use in a cache key filename.
+ * Removes or replaces characters that could cause path traversal or invalid filenames.
+ *
+ * @param value - The string to sanitize
+ * @returns A safe string for use in filenames
+ */
+export declare function sanitizeForFilename(value: string): string;
+/**
+ * Check if a string looks like a path traversal attempt.
+ *
+ * @param value - The string to check
+ * @returns True if the string contains path traversal patterns
+ */
+export declare function containsPathTraversal(value: string): boolean;
+//# sourceMappingURL=validators.d.ts.map

package/dist/runtime/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/runtime/validators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,CAK1E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMlF;AAqCD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAMxE;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/runtime/validators.js

@@ -0,0 +1,229 @@
+/**
+ * Pure validation functions for runtime value checking.
+ *
+ * These functions are used by BoundedContext and can also be used
+ * independently for validation in CLI tools, config loading, etc.
+ */
+/**
+ * Error thrown when validation fails.
+ */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE GUARDS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a value is a finite number (not NaN, not Infinity).
+ */
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/**
+ * Check if a value is a positive finite number.
+ */
+export function isPositiveNumber(value) {
+    return isFiniteNumber(value) && value > 0;
+}
+/**
+ * Check if a value is a non-negative finite number.
+ */
+export function isNonNegativeNumber(value) {
+    return isFiniteNumber(value) && value >= 0;
+}
+/**
+ * Check if a value is a non-empty string.
+ */
+export function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ASSERTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Assert that a value is a finite number.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a finite number
+ */
+export function assertFiniteNumber(value, name) {
+    if (!isFiniteNumber(value)) {
+        const actual = typeof value === 'number' ? String(value) : typeof value;
+        throw new ValidationError(`${name} must be a finite number, got: ${actual}`);
+    }
+    return value;
+}
+/**
+ * Assert that a value is a positive number (> 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a positive number
+ */
+export function assertPositive(value, name) {
+    const num = assertFiniteNumber(value, name);
+    if (num <= 0) {
+        throw new ValidationError(`${name} must be positive, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Assert that a value is a non-negative number (>= 0).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a number
+ * @throws ValidationError if the value is not a non-negative number
+ */
+export function assertNonNegative(value, name) {
+    const num = assertFiniteNumber(value, name);
+    if (num < 0) {
+        throw new ValidationError(`${name} must be non-negative, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Assert that a value is a string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a string
+ */
+export function assertString(value, name) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(`${name} must be a string, got: ${typeof value}`);
+    }
+    return value;
+}
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a string
+ * @throws ValidationError if the value is not a non-empty string
+ */
+export function assertNonEmptyString(value, name) {
+    const str = assertString(value, name);
+    if (str.length === 0) {
+        throw new ValidationError(`${name} must not be empty`);
+    }
+    return str;
+}
+/**
+ * Assert that a value is an array.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as an array
+ * @throws ValidationError if the value is not an array
+ */
+export function assertArray(value, name) {
+    if (!Array.isArray(value)) {
+        throw new ValidationError(`${name} must be an array, got: ${typeof value}`);
+    }
+    return value;
+}
+/**
+ * Assert that a value is a plain object (not null, not array).
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @returns The value as a Record
+ * @throws ValidationError if the value is not a plain object
+ */
+export function assertObject(value, name) {
+    if (!isPlainObject(value)) {
+        const actual = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+        throw new ValidationError(`${name} must be an object, got: ${actual}`);
+    }
+    return value;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// SPECIAL FLOAT DETECTION (for codec validation)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a value contains non-finite numbers (NaN, Infinity, -Infinity).
+ * Recursively checks arrays and objects.
+ *
+ * This is used to detect values that cannot be safely serialized to JSON,
+ * as JSON.stringify converts NaN/Infinity to null, which can cause
+ * silent data corruption.
+ *
+ * @param value - The value to check
+ * @returns True if the value contains NaN or Infinity anywhere
+ */
+function containsSpecialFloatRecursive(value, visited) {
+    if (typeof value === 'number') {
+        return !Number.isFinite(value);
+    }
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    if (visited.has(value)) {
+        return false;
+    }
+    visited.add(value);
+    if (Array.isArray(value)) {
+        return value.some(item => containsSpecialFloatRecursive(item, visited));
+    }
+    if (isPlainObject(value)) {
+        return Object.values(value).some(item => containsSpecialFloatRecursive(item, visited));
+    }
+    return false;
+}
+export function containsSpecialFloat(value) {
+    return containsSpecialFloatRecursive(value, new WeakSet());
+}
+/**
+ * Assert that a value does not contain non-finite numbers.
+ *
+ * @param value - The value to check
+ * @param name - The name of the parameter (for error messages)
+ * @throws ValidationError if the value contains NaN or Infinity
+ */
+export function assertNoSpecialFloats(value, name) {
+    if (containsSpecialFloat(value)) {
+        throw new ValidationError(`${name} contains non-finite numbers (NaN or Infinity) which cannot be serialized to JSON`);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// PATH VALIDATION (for CLI security)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Sanitize a string for use in a cache key filename.
+ * Removes or replaces characters that could cause path traversal or invalid filenames.
+ *
+ * @param value - The string to sanitize
+ * @returns A safe string for use in filenames
+ */
+export function sanitizeForFilename(value) {
+    // Replace path separators and traversal patterns
+    return value
+        .replace(/\.\./g, '__')
+        .replace(/[/\\:*?"<>|]/g, '_')
+        .replace(/\s+/g, '_');
+}
+/**
+ * Check if a string looks like a path traversal attempt.
+ *
+ * @param value - The string to check
+ * @returns True if the string contains path traversal patterns
+ */
+export function containsPathTraversal(value) {
+    return value.includes('..') || value.includes('/') || value.includes('\\');
+}
+//# sourceMappingURL=validators.js.map

package/dist/runtime/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/runtime/validators.ts"],"names":[],"mappings":"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"}