@yihuangdb/storage-object/dist/redis-key-manager.d.ts

A Node.js storage object layer library using Redis OM

/**
 * Redis Key Manager
 *
 * Centralized management of all Redis key operations.
 * All Redis key generation and validation MUST go through this manager.
 * This ensures consistent key patterns across the entire application.
 */
import { RedisClientType } from 'redis';
/**
 * Key generation parameters
 */
export interface KeyParams {
    entityName?: string;
    entityId?: string;
    field?: string;
    value?: string;
    prefix?: string;
    component?: string;
    type?: string;
    key?: string;
    id?: string;
    operationId?: string;
    resource?: string;
    pattern?: string;
}
/**
 * Key validation result
 */
export interface KeyValidation {
    valid: boolean;
    pattern?: string;
    error?: string;
    suggestion?: string;
}
/**
 * Centralized Redis Key Manager
 * All Redis operations must use this class for key generation
 */
export declare class RedisKeyManager {
    private static instance;
    private readonly strictMode;
    private keyUsageMap;
    private static readonly DEFAULT_STORAGE_PREFIX;
    private static readonly DEFAULT_REGISTRY_PREFIX;
    private static readonly DEFAULT_SCHEMA_PREFIX;
    private constructor();
    /**
     * Get singleton instance
     */
    static getInstance(strictMode?: boolean): RedisKeyManager;
    /**
     * Generate entity data key
     * Pattern: {entityName}:{entityId}
     */
    getEntityKey(entityName: string, entityId: string): string;
    /**
     * Generate entity data key with prefix
     * Pattern: {prefix}:{entityName}:{entityId}
     */
    getEntityKeyWithPrefix(prefix: string, entityName: string, entityId: string): string;
    /**
     * Generate storage entity key with automatic default prefix
     * Handles the 'storage' default internally
     * Pattern: {prefix}:{entityName}:{entityId}
     */
    getStorageEntityKey(prefix: string | undefined, entityName: string, entityId: string): string;
    /**
     * Generate storage pattern with automatic default prefix
     * Pattern: {prefix}:{entityName}:{pattern}
     */
    getStoragePattern(prefix: string | undefined, entityName: string, pattern?: string): string;
    /**
     * Generate storage index key with automatic default prefix
     * Pattern: {prefix}:{entityName}:index
     */
    getStorageIndexKey(prefix: string | undefined, entityName: string): string;
    /**
     * Get the default storage prefix
     */
    static getDefaultStoragePrefix(): string;
    /**
     * Generate index definition key
     * Pattern: idx:{entityName}
     */
    getIndexDefinitionKey(entityName: string): string;
    /**
     * Generate index data key
     * Pattern: idx:{entityName}:{field}
     */
    getIndexDataKey(entityName: string, field: string): string;
    /**
     * Generate field index key
     * Pattern: {entityName}#{field}:{value}
     */
    getFieldIndexKey(entityName: string, field: string, value: string): string;
    /**
     * Generate schema metadata key
     * Pattern: schema:{entityName}
     */
    getSchemaMetadataKey(entityName: string): string;
    /**
     * Generate schema HyperLogLog key
     * Pattern: schema:{entityName}:hll
     */
    getSchemaHllKey(entityName: string): string;
    /**
     * Generate schema versions key
     * Pattern: schema:{entityName}:versions
     */
    getSchemaVersionsKey(entityName: string): string;
    /**
     * Generate full-text index key
     * Pattern: ft:{entityName}
     */
    getFtIndexKey(entityName: string): string;
    /**
     * Generate full-text index data key
     * Pattern: ft:{entityName}:{component}
     */
    getFtIndexDataKey(entityName: string, component: string): string;
    /**
     * Generate Redis OM metadata key
     * Pattern: RedisOM:{entityName}:{type}
     */
    getRedisOMMetadataKey(entityName: string, type: string): string;
    /**
     * Generate custom metadata key
     * Pattern: _meta:{entityName}:{key}
     */
    getCustomMetadataKey(entityName: string, metaKey: string): string;
    /**
     * Get registry schemas key
     * Pattern: registry:schemas
     */
    getRegistrySchemasKey(): string;
    /**
     * Get registry metadata key
     * Pattern: registry:metadata
     */
    getRegistryMetadataKey(): string;
    /**
     * Generate storage schema version key
     * Pattern: schema:version
     */
    storageSchemaVersion(): string;
    /**
     * Generate storage schema changelog key
     * Pattern: schema:changelog
     */
    storageSchemaChangelog(): string;
    /**
     * Generate storage schema snapshot key
     * Pattern: schema:snapshot:{version}
     */
    storageSchemaSnapshot(schemaVersionNumber: number): string;
    /**
     * Generate storage data version key
     * Pattern: storage:version
     */
    storageDataVersion(): string;
    /**
     * Generate storage data changelog key
     * Pattern: storage:changelog
     */
    storageDataChangelog(): string;
    /**
     * Generate sync state key for a node
     * Pattern: sync:state:{nodeId}
     */
    syncState(nodeId: string): string;
    /**
     * Generate sync progress key
     * Pattern: sync:progress:{syncId}
     */
    syncProgress(syncId: string): string;
    /**
     * Generate sync lock key
     * Pattern: sync:lock:{nodeId}
     */
    syncLock(nodeId: string): string;
    /**
     * Generate dirty entities set key
     * Pattern: dirty:entities
     */
    dirtyEntitiesSet(): string;
    /**
     * Generate dirty generation key
     * Pattern: dirty:generation
     */
    dirtyGeneration(): string;
    /**
     * Generate node registry key
     * Pattern: nodes:registry
     */
    nodeRegistry(): string;
    /**
     * Generate node last seen key
     * Pattern: nodes:lastseen:{nodeId}
     */
    nodeLastSeen(nodeId: string): string;
    /**
     * Generate temporary key
     * Pattern: _tmp:{entityName}:{id}
     */
    getTemporaryKey(entityName: string, id: string): string;
    /**
     * Generate lock key (note: not used with WATCH/MULTI/EXEC)
     * Pattern: _lock:{entityName}:{resource}
     */
    getLockKey(entityName: string, resource: string): string;
    /**
     * Generate batch operation key
     * Pattern: batch:{operationId}
     */
    getBatchOperationKey(operationId: string): string;
    /**
     * Generate rollback data key
     * Pattern: rollback:{operationId}:{entityId}
     */
    getRollbackDataKey(operationId: string, entityId: string): string;
    /**
     * Get all patterns for an entity
     */
    getEntityPatterns(entityName: string, prefix?: string): string[];
    /**
     * Generate a custom key from a pattern
     */
    generateKey(pattern: string, params: KeyParams): string;
    /**
     * Extract parameters from a key
     */
    extractParams(key: string, pattern: string): Record<string, string> | null;
    /**
     * Validate a Redis key
     */
    validateKey(key: string): KeyValidation;
    /**
     * Validate multiple keys
     */
    validateKeys(keys: string[]): {
        valid: string[];
        invalid: Array<{
            key: string;
            error: string;
            suggestion?: string;
        }>;
        stats: Record<string, number>;
    };
    /**
     * Assert key is valid (throws in strict mode)
     */
    assertValidKey(key: string): void;
    /**
     * Track key usage for monitoring
     */
    private trackKeyUsage;
    /**
     * Get key usage statistics
     */
    getKeyUsageStats(): Map<string, number>;
    /**
     * Clear usage statistics
     */
    clearUsageStats(): void;
    /**
     * Get most used keys
     */
    getMostUsedKeys(limit?: number): Array<{
        key: string;
        count: number;
    }>;
    /**
     * Safe Redis set with key validation
     */
    safeSet(client: RedisClientType, key: string, value: any, options?: {
        EX?: number;
    }): Promise<void>;
    /**
     * Safe Redis get with key validation
     */
    safeGet(client: RedisClientType, key: string): Promise<any>;
    /**
     * Safe Redis delete with key validation
     */
    safeDel(client: RedisClientType, keys: string[]): Promise<number>;
    /**
     * Safe Redis hash set with key validation
     */
    safeHSet(client: RedisClientType, key: string, field: string | Record<string, string>, value?: string): Promise<void>;
    /**
     * Safe Redis hash get with key validation
     */
    safeHGet(client: RedisClientType, key: string, field: string): Promise<string | null>;
    /**
     * Safe Redis hash get all with key validation
     */
    safeHGetAll(client: RedisClientType, key: string): Promise<Record<string, string>>;
    /**
     * Cursor-based SCAN for pattern matching - production safe
     * Returns an async generator for memory-efficient processing
     */
    scanKeys(client: RedisClientType, pattern: string, count?: number): AsyncGenerator<string, void, unknown>;
    /**
     * Get all keys matching a pattern using cursor-based SCAN
     * Use with caution on large datasets - consider scanKeys() generator instead
     */
    getAllKeysMatching(client: RedisClientType, pattern: string, batchSize?: number): Promise<string[]>;
    /**
     * Count keys matching a pattern without loading all into memory
     */
    countKeysMatching(client: RedisClientType, pattern: string, batchSize?: number): Promise<number>;
    /**
     * Delete keys matching a pattern using cursor-based SCAN
     * Safe for production use with large datasets
     */
    deleteKeysMatching(client: RedisClientType, pattern: string, batchSize?: number): Promise<number>;
}
export declare function getRedisKeyManager(strictMode?: boolean): RedisKeyManager;
declare const _default: RedisKeyManager;
export default _default;
//# sourceMappingURL=redis-key-manager.d.ts.map