@varity-labs/sdk 2.0.0-alpha.1

package/dist/modules/storage/tiering/MetadataStore.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Varity SDK - Metadata Store
+ *
+ * Persistent storage for tiering metadata with support for multiple backends.
+ * Enables cross-instance consistency and historical tracking of tier transitions.
+ *
+ * Features:
+ * - Multiple storage backends (in-memory, file, IPFS, SQL)
+ * - Atomic updates
+ * - Batch operations
+ * - Historical tracking
+ * - Efficient querying
+ *
+ * @packageDocumentation
+ */
+import { StorageLayer, StorageTier } from '@varity-labs/types';
+/**
+ * Tiering metadata for an object
+ */
+export interface TieringMetadata {
+    /** Object identifier */
+    identifier: string;
+    /** Current storage tier */
+    tier: StorageTier;
+    /** Storage layer */
+    layer: StorageLayer;
+    /** Object size in bytes */
+    size: number;
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Last accessed timestamp */
+    lastAccessed: Date;
+    /** Total access count */
+    accessCount: number;
+    /** Last tier change timestamp */
+    lastTierChange?: Date;
+    /** Tier change history */
+    tierHistory?: TierTransition[];
+    /** Custom tags */
+    tags?: Record<string, string>;
+    /** Additional metadata */
+    customMetadata?: Record<string, any>;
+}
+/**
+ * Tier transition record
+ */
+export interface TierTransition {
+    /** Transition timestamp */
+    timestamp: Date;
+    /** From tier */
+    fromTier: StorageTier;
+    /** To tier */
+    toTier: StorageTier;
+    /** Reason for transition */
+    reason: string;
+    /** Cost impact (positive = savings) */
+    costImpact: number;
+}
+/**
+ * Query options for metadata
+ */
+export interface MetadataQueryOptions {
+    /** Filter by storage tier */
+    tier?: StorageTier;
+    /** Filter by storage layer */
+    layer?: StorageLayer;
+    /** Filter by tags */
+    tags?: Record<string, string>;
+    /** Minimum size in bytes */
+    minSize?: number;
+    /** Maximum size in bytes */
+    maxSize?: number;
+    /** Created after date */
+    createdAfter?: Date;
+    /** Created before date */
+    createdBefore?: Date;
+    /** Accessed after date */
+    accessedAfter?: Date;
+    /** Accessed before date */
+    accessedBefore?: Date;
+    /** Limit results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort field */
+    sortBy?: 'createdAt' | 'lastAccessed' | 'size' | 'accessCount';
+    /** Sort order */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Batch update operation
+ */
+export interface BatchUpdate {
+    /** Object identifier */
+    identifier: string;
+    /** Metadata updates */
+    updates: Partial<TieringMetadata>;
+}
+/**
+ * Storage backend type
+ */
+export declare enum MetadataBackend {
+    /** In-memory storage (not persistent) */
+    MEMORY = "memory",
+    /** File-based storage (JSON) */
+    FILE = "file",
+    /** IPFS/Filecoin storage */
+    IPFS = "ipfs",
+    /** SQL database (SQLite, PostgreSQL, etc.) */
+    SQL = "sql"
+}
+/**
+ * Metadata store configuration
+ */
+export interface MetadataStoreConfig {
+    /** Storage backend */
+    backend: MetadataBackend;
+    /** Backend-specific options */
+    backendOptions?: Record<string, any>;
+    /** Enable automatic backups */
+    enableBackups?: boolean;
+    /** Backup interval in minutes */
+    backupIntervalMinutes?: number;
+    /** Enable compression */
+    enableCompression?: boolean;
+    /** Cache TTL in milliseconds */
+    cacheTTL?: number;
+}
+/**
+ * Metadata store statistics
+ */
+export interface MetadataStoreStats {
+    /** Total metadata entries */
+    totalEntries: number;
+    /** Entries by tier */
+    byTier: Record<StorageTier, number>;
+    /** Entries by layer */
+    byLayer: Record<StorageLayer, number>;
+    /** Total storage size tracked */
+    totalSize: number;
+    /** Last update timestamp */
+    lastUpdate: Date;
+    /** Backend type */
+    backend: MetadataBackend;
+}
+/**
+ * Persistent metadata store for tiering system
+ *
+ * @example
+ * ```typescript
+ * const store = new MetadataStore({
+ *   backend: MetadataBackend.FILE,
+ *   backendOptions: {
+ *     filePath: './tiering-metadata.json'
+ *   },
+ *   enableBackups: true
+ * })
+ *
+ * await store.initialize()
+ *
+ * // Save metadata
+ * await store.save('obj-123', {
+ *   identifier: 'obj-123',
+ *   tier: StorageTier.HOT,
+ *   layer: StorageLayer.CUSTOMER_DATA,
+ *   size: 1024 * 1024,
+ *   createdAt: new Date(),
+ *   lastAccessed: new Date(),
+ *   accessCount: 1
+ * })
+ *
+ * // Load metadata
+ * const metadata = await store.load('obj-123')
+ * console.log(`Tier: ${metadata?.tier}`)
+ *
+ * // Query metadata
+ * const hotObjects = await store.query({
+ *   tier: StorageTier.HOT,
+ *   limit: 10
+ * })
+ * ```
+ */
+export declare class MetadataStore {
+    private config;
+    private cache;
+    private memoryStore;
+    private initialized;
+    private backupInterval;
+    constructor(config: MetadataStoreConfig);
+    /**
+     * Initialize the metadata store
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save metadata for an object
+     *
+     * @param identifier - Object identifier
+     * @param metadata - Tiering metadata
+     */
+    save(identifier: string, metadata: TieringMetadata): Promise<void>;
+    /**
+     * Load metadata for an object
+     *
+     * @param identifier - Object identifier
+     * @returns Tiering metadata or null if not found
+     */
+    load(identifier: string): Promise<TieringMetadata | null>;
+    /**
+     * Delete metadata for an object
+     *
+     * @param identifier - Object identifier
+     */
+    delete(identifier: string): Promise<void>;
+    /**
+     * List all metadata entries
+     *
+     * @returns Map of all metadata
+     */
+    listAll(): Promise<Map<string, TieringMetadata>>;
+    /**
+     * Query metadata with filters
+     *
+     * @param options - Query options
+     * @returns Filtered metadata entries
+     */
+    query(options?: MetadataQueryOptions): Promise<TieringMetadata[]>;
+    /**
+     * Batch save metadata
+     *
+     * @param entries - Array of metadata entries
+     */
+    batchSave(entries: TieringMetadata[]): Promise<void>;
+    /**
+     * Batch update metadata
+     *
+     * @param updates - Array of batch updates
+     */
+    batchUpdate(updates: BatchUpdate[]): Promise<void>;
+    /**
+     * Record a tier transition
+     *
+     * @param identifier - Object identifier
+     * @param fromTier - Source tier
+     * @param toTier - Destination tier
+     * @param reason - Reason for transition
+     * @param costImpact - Cost impact of transition
+     */
+    recordTierTransition(identifier: string, fromTier: StorageTier, toTier: StorageTier, reason: string, costImpact?: number): Promise<void>;
+    /**
+     * Get statistics about stored metadata
+     *
+     * @returns Metadata store statistics
+     */
+    getStats(): Promise<MetadataStoreStats>;
+    /**
+     * Export metadata to JSON
+     *
+     * @returns JSON string
+     */
+    exportToJSON(): Promise<string>;
+    /**
+     * Import metadata from JSON
+     *
+     * @param json - JSON string
+     */
+    importFromJSON(json: string): Promise<void>;
+    /**
+     * Clear all metadata
+     */
+    clear(): Promise<void>;
+    /**
+     * Destroy the metadata store and clean up resources
+     */
+    destroy(): void;
+    private initializeFileBackend;
+    private initializeIPFSBackend;
+    private initializeSQLBackend;
+    private persistToBackend;
+    private loadFromBackend;
+    private deleteFromBackend;
+    private batchPersistToBackend;
+    private clearBackend;
+    private persistToFile;
+    private startBackupProcess;
+    private createBackup;
+}
+//# sourceMappingURL=MetadataStore.d.ts.map

package/dist/modules/storage/tiering/MetadataStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetadataStore.d.ts","sourceRoot":"","sources":["../../../../src/modules/storage/tiering/MetadataStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,IAAI,EAAE,WAAW,CAAA;IACjB,oBAAoB;IACpB,KAAK,EAAE,YAAY,CAAA;IACnB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,SAAS,EAAE,IAAI,CAAA;IACf,8BAA8B;IAC9B,YAAY,EAAE,IAAI,CAAA;IAClB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,cAAc,CAAC,EAAE,IAAI,CAAA;IACrB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,cAAc,EAAE,CAAA;IAC9B,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,0BAA0B;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,SAAS,EAAE,IAAI,CAAA;IACf,gBAAgB;IAChB,QAAQ,EAAE,WAAW,CAAA;IACrB,cAAc;IACd,MAAM,EAAE,WAAW,CAAA;IACnB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,0BAA0B;IAC1B,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,0BAA0B;IAC1B,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,2BAA2B;IAC3B,cAAc,CAAC,EAAE,IAAI,CAAA;IACrB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iBAAiB;IACjB,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,GAAG,MAAM,GAAG,aAAa,CAAA;IAC9D,iBAAiB;IACjB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,uBAAuB;IACvB,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,yCAAyC;IACzC,MAAM,WAAW;IACjB,gCAAgC;IAChC,IAAI,SAAS;IACb,4BAA4B;IAC5B,IAAI,SAAS;IACb,8CAA8C;IAC9C,GAAG,QAAQ;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,+BAA+B;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,iCAAiC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,yBAAyB;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;IACnC,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;IACrC,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,4BAA4B;IAC5B,UAAU,EAAE,IAAI,CAAA;IAChB,mBAAmB;IACnB,OAAO,EAAE,eAAe,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,KAAK,CAA+D;IAC5E,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,cAAc,CAA8B;gBAExC,MAAM,EAAE,mBAAmB;IAcvC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BjC;;;;;OAKG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAexE;;;;;OAKG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAiC/D;;;;OAIG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/C;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAUtD;;;;;OAKG;IACG,KAAK,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAsF3E;;;;OAIG;IACG,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1D;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD;;;;;;;;OAQG;IACG,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAU,GACrB,OAAO,CAAC,IAAI,CAAC;IA4BhB;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAkC7C;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAWrC;;;;OAIG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBjD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACH,OAAO,IAAI,IAAI;YAeD,qBAAqB;YAarB,qBAAqB;YAMrB,oBAAoB;YAMpB,gBAAgB;YAoBhB,eAAe;YAKf,iBAAiB;YAUjB,qBAAqB;YAUrB,YAAY;YAUZ,aAAa;IAY3B,OAAO,CAAC,kBAAkB;YAYZ,YAAY;CA2B3B"}