xypriss-security/dist/src/components/serializer/safe-serializer.d.ts

Advanced High-Performance Security Framework. Military-grade encryption, post-quantum resilience, and fortified data structures.

/**
 * Safe Serialization Utility for FortifiedFunction
 * Handles cyclic structures, XyPriss objects, and performance optimization
 *
 * v2 — Improvements over v1:
 *  - Iterative serialization engine (no call-stack growth → supports depth ~10 000+)
 *  - Accurate depth tracking via an explicit node stack (was broken with shared `depth` counter)
 *  - Circular-reference path reporting  e.g. "[Circular → $.a.b.c]"
 *  - Chunk-array string builder (avoids O(n²) string concatenation on large outputs)
 *  - Static Set for O(1) lookup of known-problematic constructor names
 *  - Safe UTF-8 boundary truncation (never splits a surrogate pair)
 *  - `parse()` helper with typed return & error guard
 *  - `measureSize()` dry-run to estimate serialized byte size without full output
 *  - `deepClone()` powered by the same safe engine
 */
import { SafeSerializationOptions } from "./types";
export interface ExtendedSerializationOptions extends SafeSerializationOptions {
    /**
     * Maximum number of items serialized inside a single array before it is
     * summarised as "[Array: N items]".  Default: 10 000.
     */
    maxArrayItems?: number;
    /**
     * Maximum number of own keys serialized inside a single object before the
     * rest are summarised.  Default: 10 000.
     */
    maxObjectKeys?: number;
    /**
     * Include circular-reference path in the placeholder string.
     * e.g. "[Circular → $.items[2].parent]"
     * Default: true.
     */
    reportCircularPath?: boolean;
}
export declare class SafeSerializer {
    private static readonly DEFAULT_OPTIONS;
    /**
     * Primary serialization entry-point.
     *
     * Fast path: plain JSON.stringify when `fastMode` is enabled and the object
     * has no known pitfalls.
     * Safe path: iterative engine that handles depth ~10 000, cycles, specials.
     */
    static stringify(obj: unknown, options?: ExtendedSerializationOptions): string;
    /**
     * XyPriss-aware serialization (req / res objects).
     * Uses the iterative engine so it is also safe for deeply nested structures.
     */
    static XyPriStringify(obj: unknown, options?: ExtendedSerializationOptions): string;
    /**
     * Safe JSON.parse — never throws; returns `undefined` on failure.
     */
    static parse<T = unknown>(json: string): T | undefined;
    /**
     * Estimate serialized size (characters) without building the full string.
     * Useful to decide whether to serialize at all before hitting maxLength.
     * Returns -1 when the object is too complex to estimate quickly.
     */
    static measureSize(obj: unknown): number;
    /**
     * Deep-clone a plain-data object through serialization.
     * Returns `undefined` when the value cannot be round-tripped.
     */
    static deepClone<T>(obj: T, options?: ExtendedSerializationOptions): T | undefined;
    /**
     * Generate a stable cache key for a list of arguments.
     */
    static generateCacheKey(args: unknown[], prefix?: string): string;
    /** Compact debug log — honours console.log caller location */
    static debugLog(label: string, obj: unknown, maxLength?: number): void;
    /** Full-fidelity audit log */
    static auditLog(obj: unknown): string;
    /**
     * Converts an arbitrary value to a JSON string without using recursion.
     *
     * Algorithm:
     *   - Maintain an explicit `stack` of work items.
     *   - Each item knows its expected "output slot" (index into `chunks[]`).
     *   - After processing all children of a container, a "close" marker writes
     *     the closing bracket/brace into the correct slot.
     *   - `seen` is a WeakMap<object, path-string> for O(1) cycle detection with
     *     optional path reporting.
     *
     * This avoids JavaScript call-stack growth entirely: depth 10 000 is handled
     * as cheaply as depth 10.
     */
    private static iterativeStringify;
    /**
     * Recursion-free value serializer.
     * Uses an explicit stack so depth can go to ~10 000 without any JS stack growth.
     */
    private static writeValue;
    /** Merge user options with defaults, always producing a fully-defined object */
    private static mergeOptions;
    /**
     * Truncate a string at a safe Unicode boundary (no split surrogates).
     */
    private static safeTruncate;
    /** Redact sensitive HTTP headers */
    private static sanitizeHeaders;
    /** Duck-type detection for XyPriss req/res objects */
    private static isXyPrissObject;
}
//# sourceMappingURL=safe-serializer.d.ts.map