@limo-labs/deity 0.1.0-alpha.0

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

@@ -0,0 +1,419 @@
+import { z } from "zod";
+import { TieredMemoryManager } from "./tiered-memory.js";
+/**
+ * Configuration for hot memory (in-memory LRU cache).
+ *
+ * @since 2.0.0
+ */
+export interface HotMemoryConfig {
+    /** Maximum number of items to store in hot memory */
+    maxItems: number;
+    /** Maximum total size in bytes (optional) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (optional) */
+    ttl?: number;
+}
+/**
+ * Configuration for warm storage (compressed disk cache).
+ *
+ * @since 2.0.0
+ */
+export interface WarmStorageConfig {
+    /** Whether warm storage is enabled */
+    enabled: boolean;
+    /** Maximum total size in bytes */
+    maxSize: number;
+    /** Compression algorithm to use */
+    compressionAlgorithm: "gzip" | "lz4" | "none";
+    /** Directory for warm cache files */
+    directory: string;
+}
+/**
+ * Configuration for cold storage (uncompressed disk archive).
+ *
+ * @since 2.0.0
+ */
+export interface ColdStorageConfig {
+    /** Whether cold storage is enabled */
+    enabled: boolean;
+    /** Directory for cold archive files */
+    directory: string;
+}
+/**
+ * Complete memory configuration for tiered memory system.
+ *
+ * Defines the behavior of hot memory (LRU cache), warm storage (compressed disk),
+ * and cold storage (uncompressed archive).
+ *
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * const config: MemoryConfig = {
+ *   hot: {
+ *     maxItems: 1000,
+ *     maxSize: 100 * 1024 * 1024, // 100MB
+ *     ttl: 3600 * 1000, // 1 hour
+ *   },
+ *   warm: {
+ *     enabled: true,
+ *     maxSize: 1024 * 1024 * 1024, // 1GB
+ *     compressionAlgorithm: "gzip",
+ *     directory: ".deity/cache",
+ *   },
+ *   cold: {
+ *     enabled: true,
+ *     directory: ".deity/archive",
+ *   },
+ * };
+ * ```
+ */
+export interface MemoryConfig {
+    /** Hot memory configuration */
+    hot: HotMemoryConfig;
+    /** Warm storage configuration */
+    warm: WarmStorageConfig;
+    /** Cold storage configuration */
+    cold: ColdStorageConfig;
+}
+/**
+ * Zod schema for hot memory configuration validation.
+ * @since 2.0.0
+ */
+export declare const HotMemoryConfigSchema: z.ZodObject<{
+    maxItems: z.ZodNumber;
+    maxSize: z.ZodOptional<z.ZodNumber>;
+    ttl: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxItems: number;
+    maxSize?: number | undefined;
+    ttl?: number | undefined;
+}, {
+    maxItems: number;
+    maxSize?: number | undefined;
+    ttl?: number | undefined;
+}>;
+/**
+ * Zod schema for warm storage configuration validation.
+ * @since 2.0.0
+ */
+export declare const WarmStorageConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    maxSize: z.ZodNumber;
+    compressionAlgorithm: z.ZodEnum<["gzip", "lz4", "none"]>;
+    directory: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    maxSize: number;
+    directory: string;
+    compressionAlgorithm: "gzip" | "lz4" | "none";
+    enabled: boolean;
+}, {
+    maxSize: number;
+    directory: string;
+    compressionAlgorithm: "gzip" | "lz4" | "none";
+    enabled: boolean;
+}>;
+/**
+ * Zod schema for cold storage configuration validation.
+ * @since 2.0.0
+ */
+export declare const ColdStorageConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    directory: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    directory: string;
+    enabled: boolean;
+}, {
+    directory: string;
+    enabled: boolean;
+}>;
+/**
+ * Zod schema for complete memory configuration validation.
+ * @since 2.0.0
+ */
+export declare const MemoryConfigSchema: z.ZodObject<{
+    hot: z.ZodObject<{
+        maxItems: z.ZodNumber;
+        maxSize: z.ZodOptional<z.ZodNumber>;
+        ttl: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxItems: number;
+        maxSize?: number | undefined;
+        ttl?: number | undefined;
+    }, {
+        maxItems: number;
+        maxSize?: number | undefined;
+        ttl?: number | undefined;
+    }>;
+    warm: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        maxSize: z.ZodNumber;
+        compressionAlgorithm: z.ZodEnum<["gzip", "lz4", "none"]>;
+        directory: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        maxSize: number;
+        directory: string;
+        compressionAlgorithm: "gzip" | "lz4" | "none";
+        enabled: boolean;
+    }, {
+        maxSize: number;
+        directory: string;
+        compressionAlgorithm: "gzip" | "lz4" | "none";
+        enabled: boolean;
+    }>;
+    cold: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        directory: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        directory: string;
+        enabled: boolean;
+    }, {
+        directory: string;
+        enabled: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    hot: {
+        maxItems: number;
+        maxSize?: number | undefined;
+        ttl?: number | undefined;
+    };
+    warm: {
+        maxSize: number;
+        directory: string;
+        compressionAlgorithm: "gzip" | "lz4" | "none";
+        enabled: boolean;
+    };
+    cold: {
+        directory: string;
+        enabled: boolean;
+    };
+}, {
+    hot: {
+        maxItems: number;
+        maxSize?: number | undefined;
+        ttl?: number | undefined;
+    };
+    warm: {
+        maxSize: number;
+        directory: string;
+        compressionAlgorithm: "gzip" | "lz4" | "none";
+        enabled: boolean;
+    };
+    cold: {
+        directory: string;
+        enabled: boolean;
+    };
+}>;
+/**
+ * Pre-configured memory settings for development environments.
+ *
+ * - Generous hot memory limits (2000 items, 200MB)
+ * - No compression (fast, no CPU overhead)
+ * - Warm and cold storage enabled
+ * - Short TTL for fast iteration
+ *
+ * @since 2.0.0
+ */
+export declare const MemoryPresets: {
+    /**
+     * Development preset: Fast and generous.
+     *
+     * Optimized for quick iteration and debugging with minimal overhead.
+     * Uses no compression for speed and has generous memory limits.
+     */
+    readonly development: {
+        hot: {
+            maxItems: number;
+            maxSize: number;
+            ttl: number;
+        };
+        warm: {
+            enabled: true;
+            maxSize: number;
+            compressionAlgorithm: "none";
+            directory: string;
+        };
+        cold: {
+            enabled: true;
+            directory: string;
+        };
+    };
+    /**
+     * Production preset: Balanced and reliable.
+     *
+     * Optimized for production use with good balance between performance
+     * and resource usage. Uses gzip compression for space efficiency.
+     */
+    readonly production: {
+        hot: {
+            maxItems: number;
+            maxSize: number;
+            ttl: number;
+        };
+        warm: {
+            enabled: true;
+            maxSize: number;
+            compressionAlgorithm: "gzip";
+            directory: string;
+        };
+        cold: {
+            enabled: true;
+            directory: string;
+        };
+    };
+    /**
+     * Minimal preset: Lightweight with minimal disk usage.
+     *
+     * Optimized for resource-constrained environments or simple workflows.
+     * Warm storage disabled, only hot memory and cold storage used.
+     */
+    readonly minimal: {
+        hot: {
+            maxItems: number;
+            maxSize: number;
+            ttl: number;
+        };
+        warm: {
+            enabled: false;
+            maxSize: number;
+            compressionAlgorithm: "none";
+            directory: string;
+        };
+        cold: {
+            enabled: true;
+            directory: string;
+        };
+    };
+};
+/**
+ * Validates a memory configuration against the schema.
+ *
+ * Throws an error if the configuration is invalid.
+ *
+ * @param config - The configuration to validate
+ * @returns The validated configuration (typed)
+ * @throws {Error} If the configuration is invalid
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * try {
+ *   const validated = validateMemoryConfig(userConfig);
+ *   console.log("Configuration valid!");
+ * } catch (error) {
+ *   console.error("Invalid configuration:", error.message);
+ * }
+ * ```
+ */
+export declare function validateMemoryConfig(config: unknown): MemoryConfig;
+/**
+ * Merges a partial configuration with a base configuration.
+ *
+ * Useful for applying user overrides on top of a preset.
+ * Performs deep merge of nested objects.
+ *
+ * @param base - The base configuration (preset or default)
+ * @param override - The partial configuration to merge
+ * @returns The merged configuration
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * const config = mergeMemoryConfig(
+ *   MemoryPresets.production,
+ *   {
+ *     hot: { maxItems: 2000 }, // Override just maxItems
+ *   }
+ * );
+ * // Result: production preset with 2000 hot items instead of 1000
+ * ```
+ */
+export declare function mergeMemoryConfig(base: MemoryConfig, override: DeepPartial<MemoryConfig>): MemoryConfig;
+/**
+ * Creates a memory configuration from a preset or custom config.
+ *
+ * Supports three modes:
+ * 1. Preset name ("development", "production", "minimal")
+ * 2. Full custom configuration
+ * 3. Preset with overrides
+ *
+ * @param config - Preset name, full config, or preset with overrides
+ * @returns Validated memory configuration
+ * @throws {Error} If the configuration is invalid
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * // Use preset
+ * const config1 = createMemoryConfig("production");
+ *
+ * // Use custom config
+ * const config2 = createMemoryConfig({
+ *   hot: { maxItems: 1500 },
+ *   warm: { enabled: true, maxSize: 1024 * 1024 * 1024, compressionAlgorithm: "gzip", directory: ".cache" },
+ *   cold: { enabled: true, directory: ".archive" },
+ * });
+ *
+ * // Use preset with overrides
+ * const config3 = createMemoryConfig({
+ *   preset: "production",
+ *   override: { hot: { maxItems: 2000 } },
+ * });
+ * ```
+ */
+export declare function createMemoryConfig(config: keyof typeof MemoryPresets | MemoryConfig | {
+    preset: keyof typeof MemoryPresets;
+    override: DeepPartial<MemoryConfig>;
+}): MemoryConfig;
+/**
+ * Helper type for partial configuration (deep partial).
+ * @since 2.0.0
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Gets the default memory configuration.
+ *
+ * Uses the production preset by default.
+ *
+ * @returns Default memory configuration
+ * @since 2.0.0
+ */
+export declare function getDefaultMemoryConfig(): MemoryConfig;
+/**
+ * Creates a TieredMemoryManager instance from a memory configuration.
+ *
+ * Converts the user-facing MemoryConfig (with validation and presets) into
+ * the internal TieredMemoryConfig format and creates a TieredMemoryManager.
+ *
+ * This is a synchronous wrapper - it uses require() internally which works
+ * because TieredMemoryManager is in the same package.
+ *
+ * @param config - Memory configuration (preset name, full config, or preset with override)
+ * @returns Configured TieredMemoryManager instance (call .init() before use)
+ * @throws {Error} If the configuration is invalid
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * // Create from preset name
+ * const manager1 = createTieredMemoryManager("production");
+ * await manager1.init();
+ *
+ * // Create from custom config
+ * const manager2 = createTieredMemoryManager({
+ *   hot: { maxItems: 1000 },
+ *   warm: { enabled: true, maxSize: 1024 * 1024 * 1024, compressionAlgorithm: "gzip", directory: ".cache" },
+ *   cold: { enabled: true, directory: ".archive" },
+ * });
+ * await manager2.init();
+ *
+ * // Create from preset with overrides
+ * const manager3 = createTieredMemoryManager({
+ *   preset: "production",
+ *   override: { hot: { maxItems: 2000 } },
+ * });
+ * await manager3.init();
+ * ```
+ */
+export declare function createTieredMemoryManager(config: keyof typeof MemoryPresets | MemoryConfig | {
+    preset: keyof typeof MemoryPresets;
+    override: DeepPartial<MemoryConfig>;
+}): TieredMemoryManager;
+//# sourceMappingURL=memory-config.d.ts.map

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

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