@soulcraft/brainy 3.47.1 → 3.49.0

package/dist/storage/adapters/r2Storage.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Cloudflare R2 Storage Adapter (Dedicated)
+ * Optimized specifically for Cloudflare R2 with all latest features
+ *
+ * R2-Specific Optimizations:
+ * - Zero egress fees (aggressive caching)
+ * - Cloudflare global network (edge-aware routing)
+ * - Workers integration (optional edge compute)
+ * - High-volume mode for bulk operations
+ * - Smart batching and backpressure
+ *
+ * Based on latest GCS and S3 implementations with R2-specific enhancements
+ */
+import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { BaseStorage } from '../baseStorage.js';
+type HNSWNode = HNSWNoun;
+type Edge = HNSWVerb;
+/**
+ * Dedicated Cloudflare R2 storage adapter
+ * Optimized for R2's unique characteristics and global edge network
+ *
+ * Configuration:
+ * ```typescript
+ * const r2Storage = new R2Storage({
+ *   bucketName: 'my-brainy-data',
+ *   accountId: 'YOUR_CLOUDFLARE_ACCOUNT_ID',
+ *   accessKeyId: 'YOUR_R2_ACCESS_KEY_ID',
+ *   secretAccessKey: 'YOUR_R2_SECRET_ACCESS_KEY'
+ * })
+ * ```
+ */
+export declare class R2Storage extends BaseStorage {
+    private s3Client;
+    private bucketName;
+    private accountId;
+    private accessKeyId;
+    private secretAccessKey;
+    private endpoint;
+    private nounPrefix;
+    private verbPrefix;
+    private metadataPrefix;
+    private verbMetadataPrefix;
+    private systemPrefix;
+    protected statisticsCache: StatisticsData | null;
+    private pendingOperations;
+    private maxConcurrentOperations;
+    private baseBatchSize;
+    private currentBatchSize;
+    private lastMemoryCheck;
+    private memoryCheckInterval;
+    private backpressure;
+    private nounWriteBuffer;
+    private verbWriteBuffer;
+    private requestCoalescer;
+    private highVolumeMode;
+    private lastVolumeCheck;
+    private volumeCheckInterval;
+    private forceHighVolumeMode;
+    private nounCacheManager;
+    private verbCacheManager;
+    private logger;
+    /**
+     * Initialize the R2 storage adapter
+     * @param options Configuration options for Cloudflare R2
+     */
+    constructor(options: {
+        bucketName: string;
+        accountId: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        cacheConfig?: {
+            hotCacheMaxSize?: number;
+            hotCacheEvictionThreshold?: number;
+            warmCacheTTL?: number;
+        };
+        readOnly?: boolean;
+    });
+    /**
+     * Initialize the storage adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Get the R2 object key for a noun using UUID-based sharding
+     */
+    private getNounKey;
+    /**
+     * Get the R2 object key for a verb using UUID-based sharding
+     */
+    private getVerbKey;
+    /**
+     * Override base class method to detect R2-specific throttling errors
+     */
+    protected isThrottlingError(error: any): boolean;
+    /**
+     * Override base class to enable smart batching for cloud storage
+     * R2 is cloud storage with network latency benefits from batching
+     */
+    protected isCloudStorage(): boolean;
+    /**
+     * Apply backpressure before starting an operation
+     */
+    private applyBackpressure;
+    /**
+     * Release backpressure after completing an operation
+     */
+    private releaseBackpressure;
+    /**
+     * Check if high-volume mode should be enabled
+     */
+    private checkVolumeMode;
+    /**
+     * Flush noun buffer to R2
+     */
+    private flushNounBuffer;
+    /**
+     * Flush verb buffer to R2
+     */
+    private flushVerbBuffer;
+    /**
+     * Save a noun to storage (internal implementation)
+     */
+    protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
+    /**
+     * Save a node to storage
+     */
+    protected saveNode(node: HNSWNode): Promise<void>;
+    /**
+     * Save a node directly to R2 (bypass buffer)
+     */
+    private saveNodeDirect;
+    /**
+     * Get a noun from storage (internal implementation)
+     */
+    protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
+    /**
+     * Get a node from storage
+     */
+    protected getNode(id: string): Promise<HNSWNode | null>;
+    /**
+     * Delete a noun from storage (internal implementation)
+     */
+    protected deleteNoun_internal(id: string): Promise<void>;
+    /**
+     * Write an object to a specific path in R2
+     */
+    protected writeObjectToPath(path: string, data: any): Promise<void>;
+    /**
+     * Read an object from a specific path in R2
+     */
+    protected readObjectFromPath(path: string): Promise<any | null>;
+    /**
+     * Delete an object from a specific path in R2
+     */
+    protected deleteObjectFromPath(path: string): Promise<void>;
+    /**
+     * List all objects under a specific prefix in R2
+     */
+    protected listObjectsUnderPath(prefix: string): Promise<string[]>;
+    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
+    protected saveEdge(edge: Edge): Promise<void>;
+    private saveEdgeDirect;
+    protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
+    protected getEdge(id: string): Promise<Edge | null>;
+    protected deleteVerb_internal(id: string): Promise<void>;
+    protected initializeCounts(): Promise<void>;
+    private initializeCountsFromScan;
+    protected persistCounts(): Promise<void>;
+    getNounVector(id: string): Promise<number[] | null>;
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
+    protected saveStatisticsData(statistics: StatisticsData): Promise<void>;
+    protected getStatisticsData(): Promise<StatisticsData | null>;
+    clear(): Promise<void>;
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+    getNounsWithPagination(options?: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            nounType?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: HNSWNoun[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
+    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+}
+export {};