@limo-labs/deity 0.1.0-alpha.0

package/dist/src/memory/compression.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Pluggable compression system for warm storage.
+ *
+ * Provides an adapter interface for different compression algorithms,
+ * allowing users to choose between gzip, lz4, or no compression based
+ * on their performance and space trade-offs.
+ *
+ * @module memory/compression
+ * @since 2.0.0
+ */
+/**
+ * Compression adapter interface.
+ *
+ * All compression implementations must implement this interface.
+ * Compression/decompression work with Node.js Buffer objects.
+ */
+export interface CompressionAdapter {
+    /** Name of the compression algorithm */
+    name: string;
+    /**
+     * Compress data.
+     *
+     * @param data - Uncompressed data buffer
+     * @returns Compressed data buffer
+     */
+    compress(data: Buffer): Promise<Buffer>;
+    /**
+     * Decompress data.
+     *
+     * @param data - Compressed data buffer
+     * @returns Decompressed data buffer
+     */
+    decompress(data: Buffer): Promise<Buffer>;
+    /**
+     * Get estimated compression ratio for this algorithm.
+     *
+     * This is a rough estimate for planning purposes:
+     * - 1.0 = no compression
+     * - 2.0 = 50% size reduction (typical for text/JSON)
+     * - 4.0 = 75% size reduction (highly compressible)
+     *
+     * @returns Estimated compression ratio (uncompressed / compressed)
+     */
+    getEstimatedRatio(): number;
+}
+/**
+ * Gzip compression adapter (RFC 1952).
+ *
+ * Good general-purpose compression with decent ratio and speed.
+ * Best for production use cases where space matters.
+ *
+ * **Performance:**
+ * - Compression: ~10-30 MB/s
+ * - Decompression: ~50-100 MB/s
+ * - Ratio: ~2-4x for JSON/text
+ *
+ * @since 2.0.0
+ */
+export declare class GzipCompression implements CompressionAdapter {
+    name: string;
+    compress(data: Buffer): Promise<Buffer>;
+    decompress(data: Buffer): Promise<Buffer>;
+    getEstimatedRatio(): number;
+}
+/**
+ * LZ4 compression adapter (fast compression).
+ *
+ * Extremely fast compression/decompression with moderate ratio.
+ * Best for latency-sensitive applications where speed > space.
+ *
+ * **Performance:**
+ * - Compression: ~300-500 MB/s
+ * - Decompression: ~1-2 GB/s
+ * - Ratio: ~1.5-2.5x for JSON/text
+ *
+ * **Note:** This is a placeholder. Real implementation requires `lz4` package.
+ * Install with: `npm install lz4`
+ *
+ * @since 2.0.0
+ */
+export declare class LZ4Compression implements CompressionAdapter {
+    name: string;
+    compress(data: Buffer): Promise<Buffer>;
+    decompress(data: Buffer): Promise<Buffer>;
+    getEstimatedRatio(): number;
+}
+/**
+ * No-compression adapter (passthrough).
+ *
+ * No compression applied - data passes through unchanged.
+ * Best for development or when data is already compressed.
+ *
+ * **Performance:**
+ * - Compression: Memory copy speed (~10 GB/s)
+ * - Decompression: Memory copy speed (~10 GB/s)
+ * - Ratio: 1.0x (no compression)
+ *
+ * @since 2.0.0
+ */
+export declare class NoCompression implements CompressionAdapter {
+    name: string;
+    compress(data: Buffer): Promise<Buffer>;
+    decompress(data: Buffer): Promise<Buffer>;
+    getEstimatedRatio(): number;
+}
+/**
+ * Compression algorithm type (string literal).
+ * @since 2.0.0
+ */
+export type CompressionAlgorithm = "gzip" | "lz4" | "none";
+/**
+ * Create a compression adapter instance from algorithm name.
+ *
+ * Factory function that instantiates the appropriate compression adapter
+ * based on the algorithm name.
+ *
+ * @param algorithm - Name of compression algorithm
+ * @returns Compression adapter instance
+ * @throws {Error} If algorithm name is unknown
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * // Create gzip compressor
+ * const gzip = createCompressionAdapter("gzip");
+ * const compressed = await gzip.compress(Buffer.from("hello"));
+ *
+ * // Create no-compression adapter
+ * const none = createCompressionAdapter("none");
+ * const passthrough = await none.compress(Buffer.from("hello"));
+ * ```
+ */
+export declare function createCompressionAdapter(algorithm: CompressionAlgorithm): CompressionAdapter;
+/**
+ * Get list of available compression algorithms.
+ *
+ * @returns Array of algorithm names
+ * @since 2.0.0
+ */
+export declare function getAvailableAlgorithms(): CompressionAlgorithm[];
+/**
+ * Check if a compression algorithm is available.
+ *
+ * Some algorithms (like lz4) require optional dependencies.
+ * This function checks if the algorithm can be used.
+ *
+ * @param algorithm - Algorithm name to check
+ * @returns Promise resolving to true if available, false otherwise
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * if (await isCompressionAvailable("lz4")) {
+ *   console.log("LZ4 compression is available");
+ * } else {
+ *   console.log("LZ4 requires 'npm install lz4'");
+ * }
+ * ```
+ */
+export declare function isCompressionAvailable(algorithm: CompressionAlgorithm): Promise<boolean>;
+//# sourceMappingURL=compression.d.ts.map

package/dist/src/memory/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../../src/memory/compression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C;;;;;;;;;OASG;IACH,iBAAiB,IAAI,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,kBAAkB;IACxD,IAAI,SAAU;IAER,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,iBAAiB,IAAI,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,kBAAkB;IACvD,IAAI,SAAS;IAEP,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAevC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAe/C,iBAAiB,IAAI,MAAM;CAI5B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IACtD,IAAI,SAAU;IAER,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,iBAAiB,IAAI,MAAM;CAI5B;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,oBAAoB,GAC9B,kBAAkB,CAcpB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,oBAAoB,EAAE,CAE/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,oBAAoB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/src/memory/compression.js

@@ -0,0 +1,193 @@
+/**
+ * Pluggable compression system for warm storage.
+ *
+ * Provides an adapter interface for different compression algorithms,
+ * allowing users to choose between gzip, lz4, or no compression based
+ * on their performance and space trade-offs.
+ *
+ * @module memory/compression
+ * @since 2.0.0
+ */
+import { gzip, gunzip } from "node:zlib";
+import { promisify } from "node:util";
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+/**
+ * Gzip compression adapter (RFC 1952).
+ *
+ * Good general-purpose compression with decent ratio and speed.
+ * Best for production use cases where space matters.
+ *
+ * **Performance:**
+ * - Compression: ~10-30 MB/s
+ * - Decompression: ~50-100 MB/s
+ * - Ratio: ~2-4x for JSON/text
+ *
+ * @since 2.0.0
+ */
+export class GzipCompression {
+    name = "gzip";
+    async compress(data) {
+        return gzipAsync(data);
+    }
+    async decompress(data) {
+        return gunzipAsync(data);
+    }
+    getEstimatedRatio() {
+        // Typical compression ratio for JSON/text is 2-4x
+        return 3.0;
+    }
+}
+/**
+ * LZ4 compression adapter (fast compression).
+ *
+ * Extremely fast compression/decompression with moderate ratio.
+ * Best for latency-sensitive applications where speed > space.
+ *
+ * **Performance:**
+ * - Compression: ~300-500 MB/s
+ * - Decompression: ~1-2 GB/s
+ * - Ratio: ~1.5-2.5x for JSON/text
+ *
+ * **Note:** This is a placeholder. Real implementation requires `lz4` package.
+ * Install with: `npm install lz4`
+ *
+ * @since 2.0.0
+ */
+export class LZ4Compression {
+    name = "lz4";
+    async compress(data) {
+        try {
+            // Try to load lz4 package (dynamic import to make it optional)
+            // @ts-expect-error - lz4 is an optional dependency
+            const lz4 = await import("lz4");
+            return Buffer.from(lz4.encode(data));
+        }
+        catch (err) {
+            throw new Error("LZ4 compression requires the 'lz4' package. " +
+                "Install it with: npm install lz4\n" +
+                `Original error: ${err}`);
+        }
+    }
+    async decompress(data) {
+        try {
+            // Try to load lz4 package (dynamic import to make it optional)
+            // @ts-expect-error - lz4 is an optional dependency
+            const lz4 = await import("lz4");
+            return Buffer.from(lz4.decode(data));
+        }
+        catch (err) {
+            throw new Error("LZ4 decompression requires the 'lz4' package. " +
+                "Install it with: npm install lz4\n" +
+                `Original error: ${err}`);
+        }
+    }
+    getEstimatedRatio() {
+        // LZ4 has lower compression ratio but much faster speed
+        return 2.0;
+    }
+}
+/**
+ * No-compression adapter (passthrough).
+ *
+ * No compression applied - data passes through unchanged.
+ * Best for development or when data is already compressed.
+ *
+ * **Performance:**
+ * - Compression: Memory copy speed (~10 GB/s)
+ * - Decompression: Memory copy speed (~10 GB/s)
+ * - Ratio: 1.0x (no compression)
+ *
+ * @since 2.0.0
+ */
+export class NoCompression {
+    name = "none";
+    async compress(data) {
+        // Return a copy to avoid mutation issues
+        return Buffer.from(data);
+    }
+    async decompress(data) {
+        // Return a copy to avoid mutation issues
+        return Buffer.from(data);
+    }
+    getEstimatedRatio() {
+        // No compression
+        return 1.0;
+    }
+}
+/**
+ * Create a compression adapter instance from algorithm name.
+ *
+ * Factory function that instantiates the appropriate compression adapter
+ * based on the algorithm name.
+ *
+ * @param algorithm - Name of compression algorithm
+ * @returns Compression adapter instance
+ * @throws {Error} If algorithm name is unknown
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * // Create gzip compressor
+ * const gzip = createCompressionAdapter("gzip");
+ * const compressed = await gzip.compress(Buffer.from("hello"));
+ *
+ * // Create no-compression adapter
+ * const none = createCompressionAdapter("none");
+ * const passthrough = await none.compress(Buffer.from("hello"));
+ * ```
+ */
+export function createCompressionAdapter(algorithm) {
+    switch (algorithm) {
+        case "gzip":
+            return new GzipCompression();
+        case "lz4":
+            return new LZ4Compression();
+        case "none":
+            return new NoCompression();
+        default:
+            throw new Error(`Unknown compression algorithm: "${algorithm}". ` +
+                `Valid options: gzip, lz4, none`);
+    }
+}
+/**
+ * Get list of available compression algorithms.
+ *
+ * @returns Array of algorithm names
+ * @since 2.0.0
+ */
+export function getAvailableAlgorithms() {
+    return ["gzip", "lz4", "none"];
+}
+/**
+ * Check if a compression algorithm is available.
+ *
+ * Some algorithms (like lz4) require optional dependencies.
+ * This function checks if the algorithm can be used.
+ *
+ * @param algorithm - Algorithm name to check
+ * @returns Promise resolving to true if available, false otherwise
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * if (await isCompressionAvailable("lz4")) {
+ *   console.log("LZ4 compression is available");
+ * } else {
+ *   console.log("LZ4 requires 'npm install lz4'");
+ * }
+ * ```
+ */
+export async function isCompressionAvailable(algorithm) {
+    try {
+        const adapter = createCompressionAdapter(algorithm);
+        // Try a small compression to verify it works
+        const testData = Buffer.from("test");
+        await adapter.compress(testData);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=compression.js.map

package/dist/src/memory/compression.js.map

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

package/dist/src/memory/hot-memory.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Configuration for hot memory (in-memory cache).
+ */
+export interface HotMemoryConfig {
+    /** Maximum number of items (default: 1000) */
+    maxItems?: number;
+    /** Maximum memory size in bytes (default: 100MB) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (default: 1 hour) */
+    ttl?: number;
+    /** Callback when an item is evicted */
+    onEvict?: (key: string, value: unknown) => void | Promise<void>;
+}
+/**
+ * Statistics for hot memory usage.
+ */
+export interface HotMemoryStats {
+    itemCount: number;
+    estimatedSize: number;
+    hitCount: number;
+    missCount: number;
+    evictionCount: number;
+}
+/**
+ * Hot memory layer using LRU cache with size limits and TTL.
+ * Evicts least-recently-used items when limits are reached.
+ */
+export declare class HotMemory {
+    private cache;
+    private sizeMap;
+    private totalSize;
+    private hitCount;
+    private missCount;
+    private evictionCount;
+    private config;
+    constructor(config?: HotMemoryConfig);
+    /**
+     * Get a value from hot memory.
+     * Returns undefined if not found or expired.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a value in hot memory.
+     * May trigger eviction if size or count limits are exceeded.
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Check if a key exists in hot memory.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a value from hot memory.
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all items from hot memory.
+     */
+    clear(): void;
+    /**
+     * Get statistics about hot memory usage.
+     */
+    stats(): HotMemoryStats;
+    /**
+     * Estimate the memory size of a value in bytes.
+     * This is a rough approximation for tracking purposes.
+     */
+    private estimateSize;
+}
+//# sourceMappingURL=hot-memory.d.ts.map

package/dist/src/memory/hot-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-memory.d.ts","sourceRoot":"","sources":["../../../src/memory/hot-memory.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,MAAM,CAA4B;gBAE9B,MAAM,GAAE,eAAoB;IAwBxC;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAUlC;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IA+BnC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,KAAK,IAAI,cAAc;IAUvB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAKrB"}

package/dist/src/memory/hot-memory.js

@@ -0,0 +1,116 @@
+import { LRUCache } from "lru-cache";
+/**
+ * Hot memory layer using LRU cache with size limits and TTL.
+ * Evicts least-recently-used items when limits are reached.
+ */
+export class HotMemory {
+    cache;
+    sizeMap = new Map();
+    totalSize = 0;
+    hitCount = 0;
+    missCount = 0;
+    evictionCount = 0;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            maxItems: config.maxItems ?? 1000,
+            maxSize: config.maxSize ?? 100 * 1024 * 1024, // 100MB
+            ttl: config.ttl ?? 60 * 60 * 1000, // 1 hour
+            onEvict: config.onEvict ?? (() => { }),
+        };
+        this.cache = new LRUCache({
+            max: this.config.maxItems,
+            ttl: this.config.ttl,
+            dispose: (value, key) => {
+                // Clean up size tracking
+                const size = this.sizeMap.get(key) ?? 0;
+                this.totalSize -= size;
+                this.sizeMap.delete(key);
+                this.evictionCount++;
+                // Call user callback
+                void this.config.onEvict(key, value);
+            },
+        });
+    }
+    /**
+     * Get a value from hot memory.
+     * Returns undefined if not found or expired.
+     */
+    get(key) {
+        const value = this.cache.get(key);
+        if (value === undefined) {
+            this.missCount++;
+            return undefined;
+        }
+        this.hitCount++;
+        return value;
+    }
+    /**
+     * Set a value in hot memory.
+     * May trigger eviction if size or count limits are exceeded.
+     */
+    set(key, value) {
+        const size = this.estimateSize(value);
+        // Check if adding this item would exceed size limit
+        if (size > this.config.maxSize) {
+            throw new Error(`Item size (${size} bytes) exceeds max hot memory size (${this.config.maxSize} bytes)`);
+        }
+        // Evict items if necessary to make room
+        while (this.totalSize + size > this.config.maxSize &&
+            this.cache.size > 0) {
+            // Evict oldest item
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        // Update size tracking
+        const oldSize = this.sizeMap.get(key) ?? 0;
+        this.totalSize = this.totalSize - oldSize + size;
+        this.sizeMap.set(key, size);
+        // Store in cache
+        this.cache.set(key, value);
+    }
+    /**
+     * Check if a key exists in hot memory.
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Delete a value from hot memory.
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all items from hot memory.
+     */
+    clear() {
+        this.cache.clear();
+        this.sizeMap.clear();
+        this.totalSize = 0;
+    }
+    /**
+     * Get statistics about hot memory usage.
+     */
+    stats() {
+        return {
+            itemCount: this.cache.size,
+            estimatedSize: this.totalSize,
+            hitCount: this.hitCount,
+            missCount: this.missCount,
+            evictionCount: this.evictionCount,
+        };
+    }
+    /**
+     * Estimate the memory size of a value in bytes.
+     * This is a rough approximation for tracking purposes.
+     */
+    estimateSize(value) {
+        const json = JSON.stringify(value);
+        // UTF-16 encoding: 2 bytes per character
+        return json.length * 2;
+    }
+}
+//# sourceMappingURL=hot-memory.js.map

package/dist/src/memory/hot-memory.js.map

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