@dotdo/postgres 0.1.0

package/dist/storage/cache-layer.d.ts

@@ -0,0 +1,159 @@
+/**
+ * CacheLayer - Workers Cache API wrapper for PGLite tiered storage
+ * Task: postgres-xm8.7 - CacheLayer - Workers Cache API wrapper
+ *
+ * CRITICAL: Cloudflare Cache API is FREE! This is our competitive advantage.
+ *
+ * Provides a typed wrapper around the Cloudflare Workers Cache API for storing
+ * PGLite database pages in the global edge cache.
+ *
+ * @module storage/cache-layer
+ */
+/**
+ * Configuration for CacheLayer
+ */
+export interface CacheLayerConfig {
+    /** Name of the cache to use */
+    cacheName: string;
+    /** TTL for cached entries in seconds */
+    ttlSeconds: number;
+    /** Base URL for cache key construction */
+    baseUrl: string;
+    /** Optional maximum entries hint (not enforced by Cache API) */
+    maxEntries?: number;
+}
+/**
+ * Metadata attached to cached entries
+ */
+export interface CacheEntryMetadata {
+    /** Timestamp when last accessed */
+    lastAccessed?: number;
+    /** Number of times accessed */
+    accessCount?: number;
+    /** Size in bytes */
+    size?: number;
+    /** Custom tags for categorization */
+    tags?: string[];
+}
+/**
+ * Result from getWithMetadata
+ */
+export interface CacheEntryWithMetadata {
+    data: Uint8Array;
+    metadata: CacheEntryMetadata;
+}
+/**
+ * Statistics for cache layer operations
+ */
+export interface CacheLayerStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of writes */
+    writes: number;
+    /** Number of deletes */
+    deletes: number;
+    /** Total bytes read from cache */
+    bytesRead: number;
+    /** Total bytes written to cache */
+    bytesWritten: number;
+    /** Number of errors encountered */
+    errors: number;
+    /** Hit ratio (0-1) */
+    hitRatio: number;
+}
+/**
+ * CacheLayer wraps the Cloudflare Workers Cache API for PGLite page storage.
+ *
+ * The Cache API is FREE on Cloudflare Workers, making it ideal for caching
+ * frequently accessed database pages at the edge.
+ *
+ * @example
+ * ```typescript
+ * const cacheLayer = await createCacheLayer({
+ *   cacheName: 'pglite-pages',
+ *   ttlSeconds: 300,
+ *   baseUrl: 'https://cache.example.com',
+ * })
+ *
+ * // Store a page
+ * await cacheLayer.put('page-123', pageData)
+ *
+ * // Retrieve a page
+ * const data = await cacheLayer.get('page-123')
+ * ```
+ */
+export declare class CacheLayer {
+    private cache;
+    private config;
+    private stats;
+    constructor(cache: Cache, config: CacheLayerConfig);
+    /**
+     * Construct a cache key URL from a key string
+     */
+    private buildCacheUrl;
+    /**
+     * Get data from the cache
+     *
+     * @param key - The key to look up
+     * @returns The cached data or null if not found
+     */
+    get(key: string): Promise<Uint8Array | null>;
+    /**
+     * Get data from the cache with metadata
+     *
+     * @param key - The key to look up
+     * @returns The cached data with metadata or null if not found
+     */
+    getWithMetadata(key: string): Promise<CacheEntryWithMetadata | null>;
+    /**
+     * Store data in the cache
+     *
+     * @param key - The key to store under
+     * @param data - The data to store
+     * @param metadata - Optional metadata to attach
+     */
+    put(key: string, data: Uint8Array, metadata?: CacheEntryMetadata): Promise<void>;
+    /**
+     * Delete an entry from the cache
+     *
+     * @param key - The key to delete
+     * @returns true if the entry was deleted, false if it didn't exist
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if an entry exists in the cache
+     *
+     * @param key - The key to check
+     * @returns true if the entry exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear the cache (no-op for Cache API, requires manual purge)
+     *
+     * The Cloudflare Cache API does not support bulk deletion.
+     * Use cache purge via API or dashboard for full clear.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get statistics for this cache layer
+     */
+    getStats(): CacheLayerStats;
+    /**
+     * Reset statistics counters
+     */
+    resetStats(): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): CacheLayerConfig;
+}
+/**
+ * Create a new CacheLayer instance
+ *
+ * @param config - Configuration for the cache layer
+ * @returns A configured CacheLayer instance
+ */
+export declare function createCacheLayer(config: CacheLayerConfig): Promise<CacheLayer>;
+//# sourceMappingURL=cache-layer.d.ts.map

package/dist/storage/cache-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-layer.d.ts","sourceRoot":"","sources":["../../src/storage/cache-layer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,kBAAkB,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAA;IACpB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAO;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAQZ;gBAEW,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB;IAclD;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAqBlD;;;;;OAKG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAyC1E;;;;;;OAMG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BtF;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc3C;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUxC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACH,QAAQ,IAAI,eAAe;IAQ3B;;OAEG;IACH,UAAU,IAAI,IAAI;IAYlB;;OAEG;IACH,SAAS,IAAI,gBAAgB;CAG9B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAGpF"}

package/dist/storage/cache-layer.js

@@ -0,0 +1,245 @@
+/**
+ * CacheLayer - Workers Cache API wrapper for PGLite tiered storage
+ * Task: postgres-xm8.7 - CacheLayer - Workers Cache API wrapper
+ *
+ * CRITICAL: Cloudflare Cache API is FREE! This is our competitive advantage.
+ *
+ * Provides a typed wrapper around the Cloudflare Workers Cache API for storing
+ * PGLite database pages in the global edge cache.
+ *
+ * @module storage/cache-layer
+ */
+/**
+ * CacheLayer wraps the Cloudflare Workers Cache API for PGLite page storage.
+ *
+ * The Cache API is FREE on Cloudflare Workers, making it ideal for caching
+ * frequently accessed database pages at the edge.
+ *
+ * @example
+ * ```typescript
+ * const cacheLayer = await createCacheLayer({
+ *   cacheName: 'pglite-pages',
+ *   ttlSeconds: 300,
+ *   baseUrl: 'https://cache.example.com',
+ * })
+ *
+ * // Store a page
+ * await cacheLayer.put('page-123', pageData)
+ *
+ * // Retrieve a page
+ * const data = await cacheLayer.get('page-123')
+ * ```
+ */
+export class CacheLayer {
+    cache;
+    config;
+    stats;
+    constructor(cache, config) {
+        this.cache = cache;
+        this.config = config;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            writes: 0,
+            deletes: 0,
+            bytesRead: 0,
+            bytesWritten: 0,
+            errors: 0,
+        };
+    }
+    /**
+     * Construct a cache key URL from a key string
+     */
+    buildCacheUrl(key) {
+        return `${this.config.baseUrl}/${key}`;
+    }
+    /**
+     * Get data from the cache
+     *
+     * @param key - The key to look up
+     * @returns The cached data or null if not found
+     */
+    async get(key) {
+        try {
+            const request = new Request(this.buildCacheUrl(key));
+            const response = await this.cache.match(request);
+            if (!response) {
+                this.stats.misses++;
+                return null;
+            }
+            this.stats.hits++;
+            const buffer = await response.arrayBuffer();
+            const data = new Uint8Array(buffer);
+            this.stats.bytesRead += data.length;
+            return data;
+        }
+        catch (_error) {
+            this.stats.errors++;
+            return null;
+        }
+    }
+    /**
+     * Get data from the cache with metadata
+     *
+     * @param key - The key to look up
+     * @returns The cached data with metadata or null if not found
+     */
+    async getWithMetadata(key) {
+        try {
+            const request = new Request(this.buildCacheUrl(key));
+            const response = await this.cache.match(request);
+            if (!response) {
+                this.stats.misses++;
+                return null;
+            }
+            this.stats.hits++;
+            const buffer = await response.arrayBuffer();
+            const data = new Uint8Array(buffer);
+            this.stats.bytesRead += data.length;
+            const lastAccessedHeader = response.headers.get('X-PGLite-Last-Accessed');
+            const accessCountHeader = response.headers.get('X-PGLite-Access-Count');
+            const sizeHeader = response.headers.get('X-PGLite-Size');
+            const tagsHeader = response.headers.get('X-PGLite-Tags');
+            const metadata = {};
+            if (lastAccessedHeader) {
+                metadata.lastAccessed = parseInt(lastAccessedHeader, 10);
+            }
+            if (accessCountHeader) {
+                metadata.accessCount = parseInt(accessCountHeader, 10);
+            }
+            if (sizeHeader) {
+                metadata.size = parseInt(sizeHeader, 10);
+            }
+            if (tagsHeader) {
+                metadata.tags = tagsHeader.split(',');
+            }
+            return { data, metadata };
+        }
+        catch (_error) {
+            this.stats.errors++;
+            return null;
+        }
+    }
+    /**
+     * Store data in the cache
+     *
+     * @param key - The key to store under
+     * @param data - The data to store
+     * @param metadata - Optional metadata to attach
+     */
+    async put(key, data, metadata) {
+        try {
+            const request = new Request(this.buildCacheUrl(key));
+            const headers = {
+                'Content-Type': 'application/octet-stream',
+                'Cache-Control': `public, max-age=${this.config.ttlSeconds}`,
+            };
+            if (metadata?.lastAccessed !== undefined) {
+                headers['X-PGLite-Last-Accessed'] = metadata.lastAccessed.toString();
+            }
+            if (metadata?.accessCount !== undefined) {
+                headers['X-PGLite-Access-Count'] = metadata.accessCount.toString();
+            }
+            if (metadata?.size !== undefined) {
+                headers['X-PGLite-Size'] = metadata.size.toString();
+            }
+            if (metadata?.tags !== undefined) {
+                headers['X-PGLite-Tags'] = metadata.tags.join(',');
+            }
+            const response = new Response(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength), { headers });
+            await this.cache.put(request, response);
+            this.stats.writes++;
+            this.stats.bytesWritten += data.length;
+        }
+        catch (_error) {
+            this.stats.errors++;
+        }
+    }
+    /**
+     * Delete an entry from the cache
+     *
+     * @param key - The key to delete
+     * @returns true if the entry was deleted, false if it didn't exist
+     */
+    async delete(key) {
+        try {
+            const request = new Request(this.buildCacheUrl(key));
+            const result = await this.cache.delete(request);
+            if (result) {
+                this.stats.deletes++;
+            }
+            return result;
+        }
+        catch (_error) {
+            this.stats.errors++;
+            return false;
+        }
+    }
+    /**
+     * Check if an entry exists in the cache
+     *
+     * @param key - The key to check
+     * @returns true if the entry exists
+     */
+    async has(key) {
+        try {
+            const request = new Request(this.buildCacheUrl(key));
+            const response = await this.cache.match(request);
+            return response !== undefined;
+        }
+        catch (_error) {
+            return false;
+        }
+    }
+    /**
+     * Clear the cache (no-op for Cache API, requires manual purge)
+     *
+     * The Cloudflare Cache API does not support bulk deletion.
+     * Use cache purge via API or dashboard for full clear.
+     */
+    async clear() {
+        // No-op: Cache API doesn't support bulk clear
+        // Entries will expire based on TTL
+    }
+    /**
+     * Get statistics for this cache layer
+     */
+    getStats() {
+        const totalRequests = this.stats.hits + this.stats.misses;
+        return {
+            ...this.stats,
+            hitRatio: totalRequests > 0 ? this.stats.hits / totalRequests : 0,
+        };
+    }
+    /**
+     * Reset statistics counters
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            writes: 0,
+            deletes: 0,
+            bytesRead: 0,
+            bytesWritten: 0,
+            errors: 0,
+        };
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+/**
+ * Create a new CacheLayer instance
+ *
+ * @param config - Configuration for the cache layer
+ * @returns A configured CacheLayer instance
+ */
+export async function createCacheLayer(config) {
+    const cache = await caches.open(config.cacheName);
+    return new CacheLayer(cache, config);
+}
+//# sourceMappingURL=cache-layer.js.map

package/dist/storage/cache-layer.js.map

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

package/dist/storage/cost-aware-tiering.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Cost-Aware Tiering Policy
+ *
+ * Provides cost-optimized tier selection for the tiered storage system:
+ * - HOT tier: Cloudflare Cache API (FREE for reads, no storage cost)
+ * - WARM tier: Durable Object storage ($0.20/million reads, $1.00/million writes)
+ * - COLD tier: R2 ($0.36/million Class B reads, $4.50/million Class A writes)
+ *
+ * Features:
+ * - Cost/benefit analysis for promotion decisions
+ * - Access pattern prediction for cost estimation
+ * - R2 write batching to reduce Class A operations
+ * - Budget tracking and alerts
+ * - Per-page cost attribution
+ *
+ * @module storage/cost-aware-tiering
+ */
+import { type CostMetricsCollector } from '../observability/cost-metrics';
+import type { StorageIndexEntry, StorageTier, TierMigrationEvent } from './tiered-orchestrator';
+/**
+ * Configuration for budget constraints
+ */
+export interface BudgetConfig {
+    /** Monthly budget in USD */
+    monthlyBudgetUsd: number;
+    /** Alert when spending exceeds this percentage (0-100) */
+    alertThresholdPercent: number;
+    /** Automatically adjust tiering when approaching budget */
+    autoAdjustOnBudget: boolean;
+    /** Callback when budget alert is triggered */
+    onBudgetAlert?: (currentSpend: number, budget: number) => void;
+    /** Callback when budget is exceeded */
+    onBudgetExceeded?: (currentSpend: number, budget: number) => void;
+}
+/**
+ * Configuration for the cost-aware tiering policy
+ */
+export interface CostAwareTieringConfig {
+    /** Minimum cost/benefit ratio for promotion (default: 1.5) */
+    minCostBenefitRatio: number;
+    /** Minimum access count before considering promotion (default: 5) */
+    minAccessCountForPromotion: number;
+    /** Time window for access prediction in ms (default: 60000) */
+    predictionWindowMs: number;
+    /** Interval for flushing R2 write buffer in ms (default: 10000) */
+    writeBufferFlushIntervalMs: number;
+    /** Maximum entries in write buffer before forced flush (default: 100) */
+    maxWriteBufferEntries: number;
+    /** Enable per-page cost tracking (default: true) */
+    enablePageCostTracking: boolean;
+    /** Budget configuration */
+    budget?: BudgetConfig;
+}
+/**
+ * Result of tier cost analysis
+ */
+export interface TierCostAnalysis {
+    /** Current tier */
+    currentTier: StorageTier;
+    /** Current monthly cost in USD */
+    currentMonthlyCost: number;
+    /** Estimated optimal tier */
+    optimalTier: StorageTier;
+    /** Estimated optimal tier monthly cost */
+    optimalMonthlyCost: number;
+    /** Whether promotion is recommended */
+    shouldPromote: boolean;
+    /** Whether demotion is recommended */
+    shouldDemote: boolean;
+    /** Target tier for migration */
+    targetTier?: StorageTier;
+    /** Cost per access in current tier */
+    costPerAccess: number;
+    /** Estimated savings from moving */
+    estimatedSavings: number;
+    /** Reason for recommendation */
+    reason: string;
+}
+/**
+ * Access frequency prediction
+ */
+export interface AccessPrediction {
+    /** Predicted accesses in the next hour */
+    nextHour: number;
+    /** Predicted accesses in the next day */
+    nextDay: number;
+    /** Prediction confidence (0-1) */
+    confidence: number;
+    /** Access trend */
+    trend: 'increasing' | 'stable' | 'decreasing';
+}
+/**
+ * Entry in the R2 write buffer
+ */
+export interface WriteBufferEntry {
+    /** Page key */
+    key: string;
+    /** Data to write */
+    data: Uint8Array;
+    /** Timestamp when buffered */
+    bufferedAt: number;
+    /** Number of times this entry was updated while buffered */
+    updateCount: number;
+}
+/**
+ * Per-page cost record
+ */
+export interface PageCostRecord {
+    /** Page key */
+    key: string;
+    /** Current tier */
+    tier: StorageTier;
+    /** Total read cost */
+    readCost: number;
+    /** Total write cost */
+    writeCost: number;
+    /** Total cost */
+    totalCost: number;
+    /** Access count */
+    accessCount: number;
+    /** Size in bytes */
+    sizeBytes: number;
+    /** First access timestamp */
+    firstAccessAt: number;
+    /** Last access timestamp */
+    lastAccessAt: number;
+}
+/**
+ * Budget status
+ */
+export interface BudgetStatus {
+    /** Budget in USD */
+    budgetUsd: number;
+    /** Current spend in USD */
+    currentSpendUsd: number;
+    /** Percentage of budget spent */
+    spentPercent: number;
+    /** Whether budget is constrained */
+    isConstrained: boolean;
+    /** Whether budget is exceeded */
+    isExceeded: boolean;
+}
+/**
+ * Policy statistics
+ */
+export interface CostAwareTieringStats {
+    /** Total pages being tracked */
+    totalPagesTracked: number;
+    /** Pages by tier */
+    pagesByTier: Record<StorageTier, number>;
+    /** Total cost tracked */
+    totalCostTracked: number;
+    /** Cost by tier */
+    costByTier: Record<StorageTier, number>;
+    /** Write buffer status */
+    writeBuffer: {
+        currentEntries: number;
+        maxEntries: number;
+        oldestEntryAge: number | null;
+    };
+    /** Budget status */
+    budgetStatus?: BudgetStatus;
+    /** Estimated monthly cost */
+    estimatedMonthlyCost: number;
+}
+/**
+ * Cost-aware tiering policy implementation
+ */
+export declare class CostAwareTieringPolicy {
+    private config;
+    private costMetrics;
+    private pageCosts;
+    private accessHistory;
+    private writeBuffer;
+    private totalCostTracked;
+    private budgetAlertSent;
+    private budgetExceededSent;
+    private trackingStartTime;
+    constructor(config?: Partial<CostAwareTieringConfig>);
+    /**
+     * Analyze the cost of a page in its current tier and recommend tier changes
+     */
+    analyzeTierCost(key: string, entry: StorageIndexEntry): TierCostAnalysis;
+    /**
+     * Predict future access frequency based on history
+     */
+    predictAccessFrequency(key: string, entry: StorageIndexEntry): AccessPrediction;
+    /**
+     * Record a page access for cost tracking
+     */
+    recordAccess(key: string, tier: StorageTier, sizeBytes: number): void;
+    /**
+     * Track cost for a page operation
+     */
+    trackPageCost(key: string, operation: 'read' | 'write', tier: StorageTier, sizeBytes: number): void;
+    /**
+     * Buffer an R2 write to batch operations
+     */
+    bufferR2Write(key: string, data: Uint8Array): boolean;
+    /**
+     * Get entries in the write buffer
+     */
+    getWriteBufferEntries(): WriteBufferEntry[];
+    /**
+     * Check if write buffer should be flushed
+     */
+    shouldFlushWriteBuffer(): boolean;
+    /**
+     * Flush the write buffer
+     */
+    flushWriteBuffer(putFn: (key: string, data: Uint8Array) => Promise<void>): Promise<number>;
+    /**
+     * Check if budget is constrained
+     */
+    isBudgetConstrained(): boolean;
+    /**
+     * Check budget status and trigger callbacks
+     */
+    checkBudget(): void;
+    /**
+     * Get high-cost pages sorted by total cost
+     */
+    getHighCostPages(limit?: number): PageCostRecord[];
+    /**
+     * Get optimization candidates (high cost relative to access frequency)
+     */
+    getOptimizationCandidates(limit?: number): PageCostRecord[];
+    /**
+     * Get statistics
+     */
+    getStats(): CostAwareTieringStats;
+    /**
+     * Get the cost metrics collector
+     */
+    getCostMetrics(): CostMetricsCollector;
+    /**
+     * Reset all tracking data
+     */
+    reset(): void;
+    private getCostPerAccess;
+    private getOperationCost;
+    private estimateMonthlyCost;
+    private calculateTierCosts;
+    private shouldPromoteTier;
+    private shouldDemoteTier;
+    private getOldestBufferEntry;
+    private trackOperationCost;
+    private getTotalCost;
+}
+/**
+ * Create a cost-aware tiering policy
+ */
+export declare function createCostAwareTieringPolicy(config?: Partial<CostAwareTieringConfig>): CostAwareTieringPolicy;
+/**
+ * Integrate cost-aware policy with orchestrator
+ */
+export declare function integrateCostAwarePolicy(policy: CostAwareTieringPolicy, onMigration: (callback: (event: TierMigrationEvent) => void) => void): void;
+//# sourceMappingURL=cost-aware-tiering.d.ts.map

package/dist/storage/cost-aware-tiering.d.ts.map

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