@brightchain/brightchain-lib 0.1.4 → 0.1.6

package/src/lib/stores/memoryBlockStore.d.ts

@@ -1,51 +1,106 @@
-import { ChecksumUint8Array } from '@digitaldefiance/ecies-lib';
 import { BaseBlock } from '../blocks/base';
-import { RawDataBlock } from '../blocks/rawData';
 import { BlockHandle } from '../blocks/handle';
+import { RawDataBlock } from '../blocks/rawData';
 import { BlockSize } from '../enumerations/blockSize';
+import { IFecService } from '../interfaces/services/fecService';
+import { BlockStoreOptions, BrightenResult, IBlockMetadata, RecoveryResult } from '../interfaces/storage/blockMetadata';
 import { IBlockStore } from '../interfaces/storage/blockStore';
+import { Checksum } from '../types/checksum';
+import { MemoryBlockMetadataStore } from './memoryBlockMetadataStore';
 /**
- * Browser-compatible in-memory block store using Uint8Array
+ * Browser-compatible in-memory block store using Uint8Array.
+ *
+ * This implementation supports:
+ * - Core block operations (store, retrieve, delete)
+ * - Metadata management for tracking block lifecycle and access patterns
+ * - FEC (Forward Error Correction) operations using Reed-Solomon encoding (when FEC service is provided)
+ * - Replication tracking for distributed storage
+ *
+ * @see IBlockStore for the interface definition
  */
 export declare class MemoryBlockStore implements IBlockStore {
     private readonly blocks;
     private readonly _blockSize;
-    constructor(blockSize: BlockSize);
+    /**
+     * Optional FEC service for parity generation and recovery.
+     * If not provided, FEC operations will return errors or no-ops.
+     */
+    private readonly fecService;
+    /**
+     * Metadata store for tracking block lifecycle and access patterns.
+     */
+    private readonly metadataStore;
+    /**
+     * In-memory storage for parity block data.
+     * Key is the data block ID, value is array of parity data.
+     */
+    private readonly parityBlocks;
+    /**
+     * Create a new MemoryBlockStore.
+     * @param blockSize - The block size for this store
+     * @param fecService - Optional FEC service for parity generation and recovery
+     * @param metadataStore - Optional metadata store (creates new one if not provided)
+     */
+    constructor(blockSize: BlockSize, fecService?: IFecService | null, metadataStore?: MemoryBlockMetadataStore);
     get blockSize(): BlockSize;
+    /**
+     * Get the FEC service if available.
+     * @returns The FEC service or null if not available
+     */
+    getFecService(): IFecService | null;
+    /**
+     * Get the metadata store.
+     * @returns The metadata store
+     */
+    getMetadataStore(): MemoryBlockMetadataStore;
+    /**
+     * Convert a key to hex string format.
+     * @param key - The key as Checksum or string
+     * @returns The key as hex string
+     */
+    private keyToHex;
+    /**
+     * Convert a hex string to Checksum.
+     * @param hex - The hex string
+     * @returns The Checksum
+     */
+    private hexToChecksum;
     /**
      * Check if a block exists
      */
-    has(key: ChecksumUint8Array): Promise<boolean>;
+    has(key: Checksum | string): Promise<boolean>;
     /**
      * Get a block's data
      */
-    getData(key: ChecksumUint8Array): Promise<RawDataBlock>;
+    getData(key: Checksum): Promise<RawDataBlock>;
     /**
-     * Store a block's data
+     * Store a block's data with optional durability settings.
+     * @param block - The block to store
+     * @param options - Optional storage options including durability level and expiration
      */
-    setData(block: RawDataBlock): Promise<void>;
+    setData(block: RawDataBlock, options?: BlockStoreOptions): Promise<void>;
     /**
-     * Delete a block's data
+     * Delete a block's data (and associated parity blocks and metadata)
      */
-    deleteData(key: ChecksumUint8Array): Promise<void>;
+    deleteData(key: Checksum): Promise<void>;
     /**
      * Get random block checksums from the store
      */
-    getRandomBlocks(count: number): Promise<ChecksumUint8Array[]>;
+    getRandomBlocks(count: number): Promise<Checksum[]>;
     /**
      * Store a block's data (alias for setData)
      */
-    put(key: ChecksumUint8Array, data: Uint8Array): Promise<void>;
+    put(key: Checksum | string, data: Uint8Array, options?: BlockStoreOptions): Promise<void>;
     /**
      * Delete a block (alias for deleteData)
      */
-    delete(key: ChecksumUint8Array): Promise<void>;
+    delete(key: Checksum | string): Promise<void>;
     /**
      * Generate a random ID
      */
     static randomId(): string;
     /**
-     * Clear all blocks
+     * Clear all blocks, metadata, and parity data
      */
     clear(): void;
     /**
@@ -55,6 +110,77 @@ export declare class MemoryBlockStore implements IBlockStore {
     /**
      * Get a handle to a block
      */
-    get<T extends BaseBlock>(key: ChecksumUint8Array): BlockHandle<T>;
+    get<T extends BaseBlock>(key: Checksum | string): BlockHandle<T>;
+    /**
+     * Get metadata for a block
+     * @param key - The block's checksum or ID
+     * @returns The block's metadata, or null if not found
+     */
+    getMetadata(key: Checksum | string): Promise<IBlockMetadata | null>;
+    /**
+     * Update metadata for a block
+     * @param key - The block's checksum or ID
+     * @param updates - Partial metadata updates to apply
+     */
+    updateMetadata(key: Checksum | string, updates: Partial<IBlockMetadata>): Promise<void>;
+    /**
+     * Generate parity blocks for a data block using Reed-Solomon encoding.
+     * @param key - The data block's checksum
+     * @param parityCount - Number of parity blocks to generate
+     * @returns Array of parity block checksums (as hex strings converted to Checksum)
+     * @throws FecError if FEC service is not available or encoding fails
+     */
+    generateParityBlocks(key: Checksum | string, parityCount: number): Promise<Checksum[]>;
+    /**
+     * Get parity block checksums for a data block.
+     * @param key - The data block's checksum or ID
+     * @returns Array of parity block checksums
+     */
+    getParityBlocks(key: Checksum | string): Promise<Checksum[]>;
+    /**
+     * Attempt to recover a corrupted or missing block using parity data.
+     * @param key - The block's checksum or ID
+     * @returns Recovery result with the recovered block or error
+     */
+    recoverBlock(key: Checksum | string): Promise<RecoveryResult>;
+    /**
+     * Verify block integrity against its parity data.
+     * @param key - The block's checksum or ID
+     * @returns True if the block data matches its parity data
+     */
+    verifyBlockIntegrity(key: Checksum | string): Promise<boolean>;
+    /**
+     * Get blocks that are pending replication (status = Pending).
+     * @returns Array of block checksums pending replication
+     */
+    getBlocksPendingReplication(): Promise<Checksum[]>;
+    /**
+     * Get blocks that are under-replicated (status = UnderReplicated).
+     * @returns Array of block checksums that need additional replicas
+     */
+    getUnderReplicatedBlocks(): Promise<Checksum[]>;
+    /**
+     * Record that a block has been replicated to a node.
+     * @param key - The block's checksum or ID
+     * @param nodeId - The ID of the node that now holds a replica
+     */
+    recordReplication(key: Checksum | string, nodeId: string): Promise<void>;
+    /**
+     * Record that a replica node is no longer available.
+     * @param key - The block's checksum or ID
+     * @param nodeId - The ID of the node that lost the replica
+     */
+    recordReplicaLoss(key: Checksum | string, nodeId: string): Promise<void>;
+    /**
+     * Brighten a block by XORing it with random blocks from the store.
+     * This is used to implement Owner-Free storage patterns where the
+     * original data cannot be reconstructed without all the random blocks.
+     *
+     * @param key - The source block's checksum or ID
+     * @param randomBlockCount - Number of random blocks to XOR with
+     * @returns Result containing the brightened block ID and the random block IDs used
+     * @throws StoreError if the source block is not found or insufficient random blocks are available
+     */
+    brightenBlock(key: Checksum | string, randomBlockCount: number): Promise<BrightenResult>;
 }
 //# sourceMappingURL=memoryBlockStore.d.ts.map

package/src/lib/stores/memoryBlockStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memoryBlockStore.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/stores/memoryBlockStore.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAEnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAqB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGtD,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE/D;;GAEG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAY;gBAE3B,SAAS,EAAE,SAAS;IAIhC,IAAW,SAAS,IAAI,SAAS,CAEhC;IAED;;OAEG;IACU,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3D;;OAEG;IACU,OAAO,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAWpE;;OAEG;IACU,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBxD;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/D;;OAEG;IACU,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAmB1E;;OAEG;IACU,GAAG,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1E;;OAEG;IACU,MAAM,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;OAEG;WACW,QAAQ,IAAI,MAAM;IAMhC;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACI,IAAI,IAAI,MAAM;IAIrB;;OAEG;IACI,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,GAAG,EAAE,kBAAkB,GAAG,WAAW,CAAC,CAAC,CAAC;CAmBzE"}
+{"version":3,"file":"memoryBlockStore.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/stores/memoryBlockStore.ts"],"names":[],"mappings":"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"}