@unispechq/unispec-core 0.3.2 → 0.3.3

package/dist/cache/constants.d.ts

@@ -1,21 +0,0 @@
-/**
- * Cache configuration constants.
- */
-export declare const CACHE_CONSTANTS: {
-    readonly DEFAULT_MAX_SIZE: 100;
-    readonly VALIDATION_MAX_SIZE: 50;
-    readonly NORMALIZATION_MAX_SIZE: 30;
-    readonly DIFF_MAX_SIZE: 20;
-    readonly DEFAULT_TTL: number;
-    readonly CLEANUP_INTERVAL: 60000;
-    readonly HASH_GOLDEN_RATIO: 2654435761;
-    readonly HASH_BASE: 31;
-    readonly HASH_MASK: 4294967295;
-};
-export declare const CACHE_MESSAGES: {
-    readonly CLEANUP_ERROR: "Cache cleanup error";
-    readonly CLEANUP_START_ERROR: "Failed to start cleanup interval";
-    readonly CACHE_WILL_CONTINUE: "Cache will still work without automatic cleanup";
-};
-export type CacheSize = typeof CACHE_CONSTANTS.DEFAULT_MAX_SIZE | typeof CACHE_CONSTANTS.VALIDATION_MAX_SIZE | typeof CACHE_CONSTANTS.NORMALIZATION_MAX_SIZE | typeof CACHE_CONSTANTS.DIFF_MAX_SIZE;
-export type TTL = typeof CACHE_CONSTANTS.DEFAULT_TTL | typeof CACHE_CONSTANTS.CLEANUP_INTERVAL;

package/dist/cache/constants.js

@@ -1,22 +0,0 @@
-/**
- * Cache configuration constants.
- */
-export const CACHE_CONSTANTS = {
-    // Default cache sizes
-    DEFAULT_MAX_SIZE: 100,
-    VALIDATION_MAX_SIZE: 50,
-    NORMALIZATION_MAX_SIZE: 30,
-    DIFF_MAX_SIZE: 20,
-    // TTL values (in milliseconds)
-    DEFAULT_TTL: 5 * 60 * 1000, // 5 minutes
-    CLEANUP_INTERVAL: 60000, // 1 minute
-    // Hash configuration
-    HASH_GOLDEN_RATIO: 2654435761,
-    HASH_BASE: 31,
-    HASH_MASK: 0xffffffff,
-};
-export const CACHE_MESSAGES = {
-    CLEANUP_ERROR: "Cache cleanup error",
-    CLEANUP_START_ERROR: "Failed to start cleanup interval",
-    CACHE_WILL_CONTINUE: "Cache will still work without automatic cleanup",
-};

package/dist/cache/hash-utils.d.ts

@@ -1,21 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-/**
- * Generate a hash for a UniSpec document for caching purposes.
- * Uses optimized hashing for better performance and collision resistance.
- */
-export declare function generateDocumentHash(document: UniSpecDocument): Promise<string>;
-/**
- * Synchronous version for backward compatibility (deprecated).
- * @deprecated Use async version for better security
- */
-export declare function generateDocumentHashSync(document: UniSpecDocument): string;
-/**
- * Generate a hash for two documents (for diff caching).
- * Uses optimized diff hashing with better collision resistance.
- */
-export declare function generateDiffHash(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): Promise<string>;
-/**
- * Synchronous version for backward compatibility (deprecated).
- * @deprecated Use async version for better security
- */
-export declare function generateDiffHashSync(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): string;

package/dist/cache/hash-utils.js

@@ -1,35 +0,0 @@
-import { generateOptimizedDiffHash, generateOptimizedDocumentHash, simpleHash, } from "./hashing.js";
-/**
- * Generate a hash for a UniSpec document for caching purposes.
- * Uses optimized hashing for better performance and collision resistance.
- */
-export async function generateDocumentHash(document) {
-    return await generateOptimizedDocumentHash(document);
-}
-/**
- * Synchronous version for backward compatibility (deprecated).
- * @deprecated Use async version for better security
- */
-export function generateDocumentHashSync(document) {
-    // Fallback to old method for backward compatibility
-    console.warn("generateDocumentHashSync is deprecated. Use async generateDocumentHash for better security.");
-    const str = JSON.stringify(document, Object.keys(document).sort());
-    return simpleHash(str);
-}
-/**
- * Generate a hash for two documents (for diff caching).
- * Uses optimized diff hashing with better collision resistance.
- */
-export async function generateDiffHash(oldDoc, newDoc) {
-    return await generateOptimizedDiffHash(oldDoc, newDoc);
-}
-/**
- * Synchronous version for backward compatibility (deprecated).
- * @deprecated Use async version for better security
- */
-export function generateDiffHashSync(oldDoc, newDoc) {
-    console.warn("generateDiffHashSync is deprecated. Use async generateDiffHash for better security.");
-    const oldStr = JSON.stringify(oldDoc, Object.keys(oldDoc).sort());
-    const newStr = JSON.stringify(newDoc, Object.keys(newDoc).sort());
-    return simpleHash(`${oldStr}:${newStr}`);
-}

package/dist/cache/hashing.d.ts

@@ -1,19 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-/**
- * Generate a secure hash for a document using optimized sorting and Web Crypto API.
- */
-export declare function generateOptimizedDocumentHash(document: UniSpecDocument): Promise<string>;
-/**
- * Generate a secure hash for two documents (for diff caching) with optimized collision resistance.
- */
-export declare function generateOptimizedDiffHash(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): Promise<string>;
-/**
- * Simple hash for small objects (keys, strings) using built-in hash.
- * Kept for backward compatibility but consider using secureHash for new code.
- */
-export declare function simpleHash(str: string): string;
-/**
- * Legacy synchronous hash function (deprecated - use secureHash instead).
- * @deprecated Use secureHash for better security
- */
-export declare function fnv1aHash(str: string): number;

package/dist/cache/hashing.js

@@ -1,197 +0,0 @@
-import { CACHE_CONSTANTS } from "../cache/constants.js";
-/**
- * Secure document hashing utilities using Web Crypto API.
- */
-/**
- * Secure hash using Web Crypto API (SHA-256) or Node.js crypto.
- * Fallback to FNV-1a only if both crypto APIs are unavailable.
- */
-async function secureHash(str) {
-    // Try Web Crypto API first (browser environments)
-    if (typeof crypto !== "undefined" && crypto.subtle) {
-        try {
-            const encoder = new TextEncoder();
-            const data = encoder.encode(str);
-            const hashBuffer = await crypto.subtle.digest("SHA-256", data);
-            const hashArray = Array.from(new Uint8Array(hashBuffer));
-            return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-        }
-        catch (error) {
-            console.warn("Web Crypto API failed, trying Node.js crypto:", error);
-        }
-    }
-    // Try Node.js crypto API (server environments)
-    try {
-        // Dynamic import for Node.js crypto to avoid browser compatibility issues
-        const crypto = await import("node:crypto");
-        const hash = crypto.createHash("sha256");
-        hash.update(str, "utf8");
-        return hash.digest("hex");
-    }
-    catch (error) {
-        console.warn("Node.js crypto API failed, falling back to FNV-1a:", error);
-    }
-    // Last resort: FNV-1a algorithm (non-cryptographic, for compatibility only)
-    console.warn("Using FNV-1a fallback hash - consider installing crypto support");
-    return fnv1aHashFallback(str).toString();
-}
-/**
- * FNV-1a fallback hash function (non-cryptographic, for compatibility).
- */
-function fnv1aHashFallback(str) {
-    let hash = 2166136261; // FNV offset basis
-    for (let i = 0; i < str.length; i++) {
-        hash ^= str.charCodeAt(i);
-        hash = (hash * 16777619) & CACHE_CONSTANTS.HASH_MASK; // FNV prime
-    }
-    return hash;
-}
-/**
- * Generate a secure hash for a document using optimized sorting and Web Crypto API.
- */
-export async function generateOptimizedDocumentHash(document) {
-    // Use optimized stable stringification
-    const str = stableStringify(document);
-    // Use secure hash for better distribution and collision resistance
-    const hash = await secureHash(str);
-    // Add length and type prefix for additional collision resistance
-    const typePrefix = getDocumentTypePrefix(document);
-    const combined = `${hash}_${str.length}_${typePrefix}`;
-    // Create final hash with combined string
-    const finalHash = await secureHash(combined);
-    return `${finalHash.slice(0, 16)}_${str.length}`;
-}
-/**
- * Default configuration for stable stringification.
- */
-const DEFAULT_STRINGIFY_CONFIG = {
-    maxDepth: 100,
-    maxKeys: 10000,
-    handleCircular: true,
-    handleDeepObjects: true,
-};
-/**
- * Optimized stable stringification that avoids recursion depth issues.
- */
-function stableStringify(obj, config = {}, depth = 0, visited = new WeakSet()) {
-    const finalConfig = { ...DEFAULT_STRINGIFY_CONFIG, ...config };
-    // Prevent infinite recursion
-    if (depth > finalConfig.maxDepth) {
-        return `"[MAX_DEPTH_REACHED:${depth}]"`;
-    }
-    // Handle circular references
-    if (finalConfig.handleCircular && obj && typeof obj === "object") {
-        if (visited.has(obj)) {
-            return `"[CIRCULAR_REFERENCE:${obj.constructor?.name || "Object"}]"`;
-        }
-        visited.add(obj);
-    }
-    // Handle primitives
-    if (obj === null || typeof obj !== "object") {
-        return JSON.stringify(obj);
-    }
-    // Handle special object types
-    if (obj instanceof Date) {
-        return obj.toISOString();
-    }
-    if (obj instanceof RegExp) {
-        return `"[REGEX:${obj.toString()}]"`;
-    }
-    if (obj instanceof Error) {
-        return `"[ERROR:${obj.name}:${obj.message}]"`;
-    }
-    if (typeof Buffer !== "undefined" && Buffer.isBuffer(obj)) {
-        return `"[BUFFER:${obj.toString("base64")}]"`;
-    }
-    // Handle Array
-    if (Array.isArray(obj)) {
-        if (obj.length > finalConfig.maxKeys) {
-            return `"[ARRAY_TOO_LARGE:${obj.length}]"`;
-        }
-        const elements = obj.map((item, index) => {
-            try {
-                return stableStringify(item, finalConfig, depth + 1, visited);
-            }
-            catch (error) {
-                return `"[ERROR_AT_INDEX_${index}:${error instanceof Error ? error.message : String(error)}]"`;
-            }
-        });
-        return `[${elements.join(",")}]`;
-    }
-    // Handle Object
-    if (typeof obj === "object") {
-        const objRecord = obj;
-        const keys = Object.keys(objRecord);
-        if (keys.length > finalConfig.maxKeys) {
-            return `"[OBJECT_TOO_LARGE:${keys.length}]"`;
-        }
-        const sortedKeys = keys.sort();
-        const pairs = [];
-        for (const key of sortedKeys) {
-            try {
-                const value = stableStringify(objRecord[key], finalConfig, depth + 1, visited);
-                pairs.push(`"${key}":${value}`);
-            }
-            catch (error) {
-                pairs.push(`"${key}":"[ERROR:${error instanceof Error ? error.message : String(error)}]"`);
-            }
-        }
-        return `{${pairs.join(",")}}`;
-    }
-    return "{}";
-}
-/**
- * Get a numeric prefix based on document type to reduce collisions.
- */
-function getDocumentTypePrefix(document) {
-    if (!document || typeof document !== "object")
-        return 0;
-    const doc = document;
-    // Check for UniSpec document
-    if (doc.unispecVersion)
-        return 1;
-    if (doc.uniSpecTestsVersion)
-        return 2;
-    if (doc.version && doc.services)
-        return 3;
-    // Check for common patterns
-    if (Array.isArray(document))
-        return 4;
-    if (doc.$schema)
-        return 5;
-    if (doc.type)
-        return typeof doc.type === "string" ? doc.type.charCodeAt(0) || 6 : 6;
-    return 7;
-}
-/**
- * Generate a secure hash for two documents (for diff caching) with optimized collision resistance.
- */
-export async function generateOptimizedDiffHash(oldDoc, newDoc) {
-    const oldHash = await generateOptimizedDocumentHash(oldDoc);
-    const newHash = await generateOptimizedDocumentHash(newDoc);
-    // Combine hashes using order-sensitive operation
-    const combined = `${oldHash}:${newHash}`;
-    // Hash the combined string to get final result
-    const finalHash = await secureHash(combined);
-    return `${finalHash.slice(0, 16)}_${oldHash.length}_${newHash.length}`;
-}
-/**
- * Simple hash for small objects (keys, strings) using built-in hash.
- * Kept for backward compatibility but consider using secureHash for new code.
- */
-export function simpleHash(str) {
-    let hash = 0;
-    for (let i = 0; i < str.length; i++) {
-        const char = str.charCodeAt(i);
-        hash = ((hash << 5) - hash + char) & CACHE_CONSTANTS.HASH_MASK;
-    }
-    return hash.toString(36);
-}
-/**
- * Legacy synchronous hash function (deprecated - use secureHash instead).
- * @deprecated Use secureHash for better security
- */
-export function fnv1aHash(str) {
-    console.warn("fnv1aHash is deprecated. Use secureHash for better security.");
-    return fnv1aHashFallback(str);
-}

package/dist/cache/index.d.ts

@@ -1,6 +0,0 @@
-export { clearTestRegistry, createCacheManager, createNamedCacheManager, destroyManagers, getManagersStats, } from "./cache-factory.js";
-export { UniSpecCacheManager } from "./cache-manager.js";
-export { CACHE_CONSTANTS, CACHE_MESSAGES } from "./constants.js";
-export { generateDiffHash, generateDiffHashSync, generateDocumentHash, generateDocumentHashSync, } from "./hash-utils.js";
-export { LRUCache } from "./lru-cache.js";
-export type { CacheEntry, CacheOptions, CacheSize, CacheStats, TTL, } from "./types.js";

package/dist/cache/index.js

@@ -1,10 +0,0 @@
-// Constants and messages
-// Cache factory
-export { clearTestRegistry, createCacheManager, createNamedCacheManager, destroyManagers, getManagersStats, } from "./cache-factory.js";
-// Cache manager
-export { UniSpecCacheManager } from "./cache-manager.js";
-export { CACHE_CONSTANTS, CACHE_MESSAGES } from "./constants.js";
-// Hash utilities
-export { generateDiffHash, generateDiffHashSync, generateDocumentHash, generateDocumentHashSync, } from "./hash-utils.js";
-// Core cache implementation
-export { LRUCache } from "./lru-cache.js";

package/dist/cache/lru-cache.d.ts

@@ -1,56 +0,0 @@
-import type { CacheOptions, CacheStats } from "./types.js";
-/**
- * Simple LRU (Least Recently Used) cache implementation.
- */
-export declare class LRUCache<T> {
-    private cache;
-    private maxSize;
-    private ttl;
-    private enableStats;
-    private stats;
-    constructor(options?: CacheOptions);
-    /**
-     * Get a value from the cache asynchronously.
-     * For performance, this uses sync operations wrapped in Promise for compatibility.
-     */
-    get(key: string): Promise<T | undefined>;
-    /**
-     * Set a value in the cache asynchronously.
-     * For performance, this uses sync operations wrapped in Promise for compatibility.
-     */
-    set(key: string, value: T): Promise<void>;
-    /**
-     * Get a value from the cache (synchronous version for backward compatibility).
-     * @deprecated Use async get() method instead
-     */
-    getSync(key: string): T | undefined;
-    /**
-     * Set a value in the cache (synchronous version for backward compatibility).
-     * @deprecated Use async set() method instead
-     */
-    setSync(key: string, value: T): void;
-    /**
-     * Delete a value from the cache.
-     */
-    delete(key: string): boolean;
-    /**
-     * Clear all entries from the cache.
-     */
-    clear(): void;
-    /**
-     * Get cache statistics.
-     */
-    getStats(): CacheStats;
-    /**
-     * Check if an entry is expired.
-     */
-    private isExpired;
-    /**
-     * Update hit rate statistics.
-     */
-    private updateHitRate;
-    /**
-     * Clean up expired entries.
-     */
-    cleanup(): number;
-}

package/dist/cache/lru-cache.js

@@ -1,161 +0,0 @@
-import { CACHE_CONSTANTS } from "./constants.js";
-/**
- * Simple LRU (Least Recently Used) cache implementation.
- */
-export class LRUCache {
-    constructor(options = {}) {
-        this.cache = new Map();
-        this.maxSize = options.maxSize || CACHE_CONSTANTS.DEFAULT_MAX_SIZE;
-        this.ttl = options.ttl || CACHE_CONSTANTS.DEFAULT_TTL;
-        this.enableStats = options.enableStats || false;
-        this.stats = {
-            hits: 0,
-            misses: 0,
-            size: 0,
-            hitRate: 0,
-            evictions: 0,
-        };
-    }
-    /**
-     * Get a value from the cache asynchronously.
-     * For performance, this uses sync operations wrapped in Promise for compatibility.
-     */
-    async get(key) {
-        // Use synchronous operations for better performance
-        // Only wrap in Promise for async interface compatibility
-        return Promise.resolve(this.getSync(key));
-    }
-    /**
-     * Set a value in the cache asynchronously.
-     * For performance, this uses sync operations wrapped in Promise for compatibility.
-     */
-    async set(key, value) {
-        // Use synchronous operations for better performance
-        // Only wrap in Promise for async interface compatibility
-        this.setSync(key, value);
-        return Promise.resolve();
-    }
-    /**
-     * Get a value from the cache (synchronous version for backward compatibility).
-     * @deprecated Use async get() method instead
-     */
-    getSync(key) {
-        const entry = this.cache.get(key);
-        if (!entry) {
-            if (this.enableStats) {
-                this.stats.misses++;
-                this.updateHitRate();
-            }
-            return undefined;
-        }
-        // Check TTL
-        if (this.isExpired(entry)) {
-            this.cache.delete(key);
-            if (this.enableStats) {
-                this.stats.misses++;
-                this.stats.size--;
-                this.updateHitRate();
-            }
-            return undefined;
-        }
-        // Update access info
-        entry.accessCount++;
-        entry.lastAccessed = Date.now();
-        // Move to end (most recently used)
-        this.cache.delete(key);
-        this.cache.set(key, entry);
-        if (this.enableStats) {
-            this.stats.hits++;
-            this.updateHitRate();
-        }
-        return entry.value;
-    }
-    /**
-     * Set a value in the cache (synchronous version for backward compatibility).
-     * @deprecated Use async set() method instead
-     */
-    setSync(key, value) {
-        // Remove existing entry if present
-        if (this.cache.has(key)) {
-            this.cache.delete(key);
-        }
-        // Evict oldest entries if cache is full
-        while (this.cache.size >= this.maxSize) {
-            const oldestKey = this.cache.keys().next().value;
-            if (oldestKey) {
-                this.cache.delete(oldestKey);
-                if (this.enableStats) {
-                    this.stats.evictions++;
-                    this.stats.size--;
-                }
-            }
-            else {
-                break;
-            }
-        }
-        const entry = {
-            value,
-            timestamp: Date.now(),
-            accessCount: 1,
-            lastAccessed: Date.now(),
-        };
-        this.cache.set(key, entry);
-        if (this.enableStats) {
-            this.stats.size++;
-        }
-    }
-    /**
-     * Delete a value from the cache.
-     */
-    delete(key) {
-        const deleted = this.cache.delete(key);
-        if (deleted && this.enableStats) {
-            this.stats.size--;
-        }
-        return deleted;
-    }
-    /**
-     * Clear all entries from the cache.
-     */
-    clear() {
-        this.cache.clear();
-        if (this.enableStats) {
-            this.stats.size = 0;
-        }
-    }
-    /**
-     * Get cache statistics.
-     */
-    getStats() {
-        return { ...this.stats };
-    }
-    /**
-     * Check if an entry is expired.
-     */
-    isExpired(entry) {
-        return Date.now() - entry.timestamp > this.ttl;
-    }
-    /**
-     * Update hit rate statistics.
-     */
-    updateHitRate() {
-        const total = this.stats.hits + this.stats.misses;
-        this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
-    }
-    /**
-     * Clean up expired entries.
-     */
-    cleanup() {
-        let cleaned = 0;
-        for (const [key, entry] of this.cache.entries()) {
-            if (this.isExpired(entry)) {
-                this.cache.delete(key);
-                cleaned++;
-                if (this.enableStats) {
-                    this.stats.size--;
-                }
-            }
-        }
-        return cleaned;
-    }
-}

package/dist/cache/types.d.ts

@@ -1,24 +0,0 @@
-/**
- * Cache interfaces and types.
- */
-export interface CacheOptions {
-    maxSize?: number;
-    ttl?: number;
-    enableStats?: boolean;
-}
-export interface CacheEntry<T> {
-    value: T;
-    timestamp: number;
-    accessCount: number;
-    lastAccessed: number;
-}
-export interface CacheStats {
-    hits: number;
-    misses: number;
-    size: number;
-    hitRate: number;
-    evictions: number;
-}
-export type CacheSize = typeof CACHE_CONSTANTS.DEFAULT_MAX_SIZE | typeof CACHE_CONSTANTS.VALIDATION_MAX_SIZE | typeof CACHE_CONSTANTS.NORMALIZATION_MAX_SIZE | typeof CACHE_CONSTANTS.DIFF_MAX_SIZE;
-export type TTL = typeof CACHE_CONSTANTS.DEFAULT_TTL | typeof CACHE_CONSTANTS.CLEANUP_INTERVAL;
-import type { CACHE_CONSTANTS } from "./constants.js";

package/dist/cache/types.js

@@ -1,4 +0,0 @@
-/**
- * Cache interfaces and types.
- */
-export {};

package/dist/cjs/cache/cache-factory.js

@@ -1,72 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createCacheManager = createCacheManager;
-exports.createNamedCacheManager = createNamedCacheManager;
-exports.getManagersStats = getManagersStats;
-exports.destroyManagers = destroyManagers;
-exports.clearTestRegistry = clearTestRegistry;
-const cache_manager_1 = require("./cache-manager.js");
-/**
- * Simple registry for test cleanup (minimal, not persistent global state)
- */
-const testRegistry = new Map();
-/**
- * Create a new isolated cache manager instance.
- * @param options - Cache configuration options
- * @returns New cache manager instance
- */
-function createCacheManager(options) {
-    return new cache_manager_1.UniSpecCacheManager(options);
-}
-/**
- * Create a named cache manager instance with simple registry.
- * @param name - Instance name for identification
- * @param options - Cache configuration options
- * @returns Cache manager instance
- */
-function createNamedCacheManager(name = "default", options) {
-    // For testing, keep simple registry to enable cleanup
-    if (testRegistry.has(name)) {
-        const existing = testRegistry.get(name);
-        if (existing) {
-            existing.destroy(); // Cleanup existing instance
-        }
-    }
-    const manager = new cache_manager_1.UniSpecCacheManager(options);
-    manager._name = name; // Store name for debugging
-    testRegistry.set(name, manager); // Add to registry for cleanup
-    return manager;
-}
-/**
- * Get cache manager statistics for multiple instances.
- * @param managers - Array of cache manager instances
- * @returns Statistics for all provided managers
- */
-function getManagersStats(managers) {
-    const stats = {};
-    for (const [index, manager] of managers.entries()) {
-        const name = manager._name ||
-            `manager_${index}`;
-        stats[name] = manager.getStats();
-    }
-    return stats;
-}
-/**
- * Destroy multiple cache manager instances.
- * @param managers - Array of cache manager instances to destroy
- */
-function destroyManagers(managers) {
-    for (const manager of managers) {
-        manager.destroy();
-    }
-}
-/**
- * Clear test registry (for testing only).
- * @internal
- */
-function clearTestRegistry() {
-    for (const manager of testRegistry.values()) {
-        manager.destroy();
-    }
-    testRegistry.clear();
-}