@net-protocol/storage 0.1.8 → 0.1.10

package/dist/index.d.mts

@@ -1,158 +1,7 @@
-import * as viem from 'viem';
-import { Abi, PublicClient } from 'viem';
+import { S as StorageClientOptions, a as StorageData, B as BulkStorageKey, b as BulkStorageResult } from './types-BnOI6cJS.mjs';
+export { C as ChunkedMetadata, U as UseStorageOptions, c as UseXmlStorageOptions, X as XmlReference } from './types-BnOI6cJS.mjs';
 import { WriteTransactionConfig } from '@net-protocol/core';
-
-/**
- * Storage data object: { text, value }
- */
-type StorageData = {
-    text: string;
-    value: string;
-};
-/**
- * Bulk storage key for batch operations
- */
-type BulkStorageKey = {
-    key: string;
-    operator: string;
-    keyFormat?: "raw" | "bytes32";
-};
-/**
- * Bulk storage result
- */
-type BulkStorageResult = {
-    text: string;
-    value: string;
-};
-/**
- * Options for useStorage hook
- */
-type UseStorageOptions = {
-    chainId: number;
-    key?: string;
-    operatorAddress?: string;
-    enabled?: boolean;
-    index?: number;
-    keyFormat?: "raw" | "bytes32";
-    useRouter?: boolean;
-    outputFormat?: "hex" | "string";
-};
-/**
- * Options for StorageClient
- */
-type StorageClientOptions = {
-    chainId: number;
-    overrides?: {
-        rpcUrls: string[];
-    };
-};
-/**
- * XML reference structure
- */
-interface XmlReference$1 {
-    hash: string;
-    version: string;
-    index?: number;
-    operator?: string;
-    source?: string;
-}
-/**
- * Chunked storage metadata
- */
-type ChunkedMetadata = {
-    chunkCount: number;
-    originalText: string;
-};
-/**
- * Options for useXmlStorage hook
- */
-type UseXmlStorageOptions = {
-    chainId: number;
-    key?: string;
-    operatorAddress: string;
-    skipXmlParsing?: boolean;
-    enabled?: boolean;
-    content?: string;
-    index?: number;
-    keyFormat?: "raw" | "bytes32";
-    useRouter?: boolean;
-    outputFormat?: "hex" | "string";
-};
-/**
- * Options for useStorageFromRouter hook
- */
-type UseStorageFromRouterOptions = {
-    chainId: number;
-    storageKey: `0x${string}`;
-    operatorAddress: string;
-    enabled?: boolean;
-};
-
-declare function useStorage({ chainId, key, operatorAddress, enabled, index, keyFormat, useRouter, outputFormat, }: UseStorageOptions): {
-    data: StorageData | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
-declare function useStorageForOperator({ chainId, operatorAddress, }: UseStorageOptions): {
-    data: any[][];
-    isLoading: boolean;
-    error: undefined;
-};
-declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, outputFormat, }: UseStorageOptions): {
-    data: {
-        text: string;
-        value: string;
-    } | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
-declare function useBulkStorage({ chainId, keys, safe, keyFormat, }: {
-    chainId: number;
-    keys: BulkStorageKey[];
-    safe?: boolean;
-    keyFormat?: "raw" | "bytes32";
-}): {
-    data: {
-        text: string;
-        value: string;
-    }[] | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
-/**
- * Get total number of versions (writes) for a storage key
- * Tries both chunked storage and regular storage
- */
-declare function useStorageTotalWrites({ chainId, key, operatorAddress, enabled, keyFormat, }: {
-    chainId: number;
-    key?: string;
-    operatorAddress?: string;
-    enabled?: boolean;
-    keyFormat?: "raw" | "bytes32";
-}): {
-    data: number | undefined;
-    isLoading: boolean;
-    error: viem.ReadContractErrorType | null | undefined;
-};
-
-declare function useXmlStorage({ chainId, key, operatorAddress, skipXmlParsing, enabled, content, index, keyFormat, useRouter, outputFormat, }: UseXmlStorageOptions): {
-    text: string;
-    value: string;
-    isLoading: boolean;
-    error: Error | undefined;
-    isXml: boolean;
-};
-
-/**
- * Generic hook to fetch storage content from StorageRouter
- * Handles both regular storage and chunked storage seamlessly
- * Works for any storage key (not just canvases)
- */
-declare function useStorageFromRouter({ chainId, storageKey, operatorAddress, enabled, }: UseStorageFromRouterOptions): {
-    data: StorageData | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
+import { Abi, PublicClient } from 'viem';
 
 /**
  * StorageClient - Client for interacting with Net protocol storage
@@ -535,6 +384,99 @@ declare function detectFileTypeFromBase64(base64Data: string): string | undefine
  */
 declare function base64ToDataUri(base64Data: string): string;
 
+/**
+ * Streaming utilities for processing large files without loading them entirely into memory.
+ * Uses file.slice() to read in chunks, keeping memory usage low.
+ */
+/**
+ * Result from processing a single file chunk
+ */
+interface StreamingChunkResult {
+    /** Index of this chunk (0-based) */
+    chunkIndex: number;
+    /** Keccak256 hash of the chunk content (66 chars) */
+    hash: string;
+    /** Compressed chunks ready for ChunkedStorage (array of hex strings) */
+    compressedChunks: string[];
+}
+/**
+ * Result from processing an entire file via streaming
+ */
+interface StreamingProcessResult {
+    /** All chunk hashes in order */
+    hashes: string[];
+    /** All compressed chunk arrays in order */
+    allCompressedChunks: string[][];
+    /** Total number of chunks */
+    totalChunks: number;
+    /** Whether the file was treated as binary */
+    isBinary: boolean;
+}
+/**
+ * Detects if a file should be treated as binary based on its MIME type.
+ * Binary files will be base64 encoded; text files will be read as text.
+ *
+ * @param file - The file to check
+ * @returns true if the file should be treated as binary
+ */
+declare function isBinaryFile(file: File): boolean;
+/**
+ * Reads a slice of a file as a string.
+ * For binary files, returns base64-encoded data.
+ * For text files, returns the raw text.
+ *
+ * @param file - The file to read from
+ * @param offset - Start byte offset
+ * @param size - Number of bytes to read
+ * @param isBinary - Whether to read as binary (base64) or text
+ * @param isFirstChunk - Whether this is the first chunk (for data URI prefix)
+ * @returns The chunk as a string
+ */
+declare function readFileSlice(file: File, offset: number, size: number, isBinary: boolean, isFirstChunk: boolean): Promise<string>;
+/**
+ * Async generator that processes a file in streaming chunks.
+ * Reads the file in 80KB slices, hashes and compresses each,
+ * yielding results one at a time to keep memory usage low.
+ *
+ * @param file - The file to process
+ * @param chunkSize - Size of each chunk in bytes (default: 80KB)
+ * @yields StreamingChunkResult for each chunk processed
+ *
+ * @example
+ * ```typescript
+ * const hashes: string[] = [];
+ * const transactions: TransactionConfig[] = [];
+ *
+ * for await (const result of processFileStreaming(file)) {
+ *   hashes.push(result.hash);
+ *   transactions.push(createTransaction(result.compressedChunks));
+ * }
+ *
+ * const metadata = generateXmlMetadata(hashes, 0, operatorAddress);
+ * ```
+ */
+declare function processFileStreaming(file: File, chunkSize?: number): AsyncGenerator<StreamingChunkResult>;
+/**
+ * Processes an entire file via streaming and returns all results.
+ * This is a convenience function that collects all generator results.
+ *
+ * For very large files, prefer using processFileStreaming directly
+ * to process chunks as they're generated.
+ *
+ * @param file - The file to process
+ * @param onProgress - Optional callback for progress updates
+ * @returns All hashes and compressed chunks
+ */
+declare function processFileStreamingComplete(file: File, onProgress?: (current: number, total: number) => void): Promise<StreamingProcessResult>;
+/**
+ * Estimates the number of chunks for a file without reading it.
+ *
+ * @param fileSize - Size of the file in bytes
+ * @param isBinary - Whether the file is binary (uses smaller chunk size for base64 alignment)
+ * @returns Estimated number of chunks
+ */
+declare function estimateChunkCount(fileSize: number, isBinary?: boolean): number;
+
 declare const STORAGE_CONTRACT: {
     abi: Abi;
     address: `0x${string}`;
@@ -570,4 +512,4 @@ declare const CONCURRENT_XML_FETCHES = 3;
  */
 declare function resolveXmlRecursive(content: string, defaultOperator: string, client: PublicClient, maxDepth: number, visited?: Set<string>, inheritedOperator?: string): Promise<string>;
 
-export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };
+export { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, StorageClientOptions, StorageData, type StreamingChunkResult, type StreamingProcessResult, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, estimateChunkCount, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, isBinaryFile, parseNetReferences, processDataForStorage, processFileStreaming, processFileStreamingComplete, readFileSlice, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, validateDataSize };

package/dist/index.d.ts

@@ -1,158 +1,7 @@
-import * as viem from 'viem';
-import { Abi, PublicClient } from 'viem';
+import { S as StorageClientOptions, a as StorageData, B as BulkStorageKey, b as BulkStorageResult } from './types-BnOI6cJS.js';
+export { C as ChunkedMetadata, U as UseStorageOptions, c as UseXmlStorageOptions, X as XmlReference } from './types-BnOI6cJS.js';
 import { WriteTransactionConfig } from '@net-protocol/core';
-
-/**
- * Storage data object: { text, value }
- */
-type StorageData = {
-    text: string;
-    value: string;
-};
-/**
- * Bulk storage key for batch operations
- */
-type BulkStorageKey = {
-    key: string;
-    operator: string;
-    keyFormat?: "raw" | "bytes32";
-};
-/**
- * Bulk storage result
- */
-type BulkStorageResult = {
-    text: string;
-    value: string;
-};
-/**
- * Options for useStorage hook
- */
-type UseStorageOptions = {
-    chainId: number;
-    key?: string;
-    operatorAddress?: string;
-    enabled?: boolean;
-    index?: number;
-    keyFormat?: "raw" | "bytes32";
-    useRouter?: boolean;
-    outputFormat?: "hex" | "string";
-};
-/**
- * Options for StorageClient
- */
-type StorageClientOptions = {
-    chainId: number;
-    overrides?: {
-        rpcUrls: string[];
-    };
-};
-/**
- * XML reference structure
- */
-interface XmlReference$1 {
-    hash: string;
-    version: string;
-    index?: number;
-    operator?: string;
-    source?: string;
-}
-/**
- * Chunked storage metadata
- */
-type ChunkedMetadata = {
-    chunkCount: number;
-    originalText: string;
-};
-/**
- * Options for useXmlStorage hook
- */
-type UseXmlStorageOptions = {
-    chainId: number;
-    key?: string;
-    operatorAddress: string;
-    skipXmlParsing?: boolean;
-    enabled?: boolean;
-    content?: string;
-    index?: number;
-    keyFormat?: "raw" | "bytes32";
-    useRouter?: boolean;
-    outputFormat?: "hex" | "string";
-};
-/**
- * Options for useStorageFromRouter hook
- */
-type UseStorageFromRouterOptions = {
-    chainId: number;
-    storageKey: `0x${string}`;
-    operatorAddress: string;
-    enabled?: boolean;
-};
-
-declare function useStorage({ chainId, key, operatorAddress, enabled, index, keyFormat, useRouter, outputFormat, }: UseStorageOptions): {
-    data: StorageData | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
-declare function useStorageForOperator({ chainId, operatorAddress, }: UseStorageOptions): {
-    data: any[][];
-    isLoading: boolean;
-    error: undefined;
-};
-declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, outputFormat, }: UseStorageOptions): {
-    data: {
-        text: string;
-        value: string;
-    } | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
-declare function useBulkStorage({ chainId, keys, safe, keyFormat, }: {
-    chainId: number;
-    keys: BulkStorageKey[];
-    safe?: boolean;
-    keyFormat?: "raw" | "bytes32";
-}): {
-    data: {
-        text: string;
-        value: string;
-    }[] | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
-/**
- * Get total number of versions (writes) for a storage key
- * Tries both chunked storage and regular storage
- */
-declare function useStorageTotalWrites({ chainId, key, operatorAddress, enabled, keyFormat, }: {
-    chainId: number;
-    key?: string;
-    operatorAddress?: string;
-    enabled?: boolean;
-    keyFormat?: "raw" | "bytes32";
-}): {
-    data: number | undefined;
-    isLoading: boolean;
-    error: viem.ReadContractErrorType | null | undefined;
-};
-
-declare function useXmlStorage({ chainId, key, operatorAddress, skipXmlParsing, enabled, content, index, keyFormat, useRouter, outputFormat, }: UseXmlStorageOptions): {
-    text: string;
-    value: string;
-    isLoading: boolean;
-    error: Error | undefined;
-    isXml: boolean;
-};
-
-/**
- * Generic hook to fetch storage content from StorageRouter
- * Handles both regular storage and chunked storage seamlessly
- * Works for any storage key (not just canvases)
- */
-declare function useStorageFromRouter({ chainId, storageKey, operatorAddress, enabled, }: UseStorageFromRouterOptions): {
-    data: StorageData | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-};
+import { Abi, PublicClient } from 'viem';
 
 /**
  * StorageClient - Client for interacting with Net protocol storage
@@ -535,6 +384,99 @@ declare function detectFileTypeFromBase64(base64Data: string): string | undefine
  */
 declare function base64ToDataUri(base64Data: string): string;
 
+/**
+ * Streaming utilities for processing large files without loading them entirely into memory.
+ * Uses file.slice() to read in chunks, keeping memory usage low.
+ */
+/**
+ * Result from processing a single file chunk
+ */
+interface StreamingChunkResult {
+    /** Index of this chunk (0-based) */
+    chunkIndex: number;
+    /** Keccak256 hash of the chunk content (66 chars) */
+    hash: string;
+    /** Compressed chunks ready for ChunkedStorage (array of hex strings) */
+    compressedChunks: string[];
+}
+/**
+ * Result from processing an entire file via streaming
+ */
+interface StreamingProcessResult {
+    /** All chunk hashes in order */
+    hashes: string[];
+    /** All compressed chunk arrays in order */
+    allCompressedChunks: string[][];
+    /** Total number of chunks */
+    totalChunks: number;
+    /** Whether the file was treated as binary */
+    isBinary: boolean;
+}
+/**
+ * Detects if a file should be treated as binary based on its MIME type.
+ * Binary files will be base64 encoded; text files will be read as text.
+ *
+ * @param file - The file to check
+ * @returns true if the file should be treated as binary
+ */
+declare function isBinaryFile(file: File): boolean;
+/**
+ * Reads a slice of a file as a string.
+ * For binary files, returns base64-encoded data.
+ * For text files, returns the raw text.
+ *
+ * @param file - The file to read from
+ * @param offset - Start byte offset
+ * @param size - Number of bytes to read
+ * @param isBinary - Whether to read as binary (base64) or text
+ * @param isFirstChunk - Whether this is the first chunk (for data URI prefix)
+ * @returns The chunk as a string
+ */
+declare function readFileSlice(file: File, offset: number, size: number, isBinary: boolean, isFirstChunk: boolean): Promise<string>;
+/**
+ * Async generator that processes a file in streaming chunks.
+ * Reads the file in 80KB slices, hashes and compresses each,
+ * yielding results one at a time to keep memory usage low.
+ *
+ * @param file - The file to process
+ * @param chunkSize - Size of each chunk in bytes (default: 80KB)
+ * @yields StreamingChunkResult for each chunk processed
+ *
+ * @example
+ * ```typescript
+ * const hashes: string[] = [];
+ * const transactions: TransactionConfig[] = [];
+ *
+ * for await (const result of processFileStreaming(file)) {
+ *   hashes.push(result.hash);
+ *   transactions.push(createTransaction(result.compressedChunks));
+ * }
+ *
+ * const metadata = generateXmlMetadata(hashes, 0, operatorAddress);
+ * ```
+ */
+declare function processFileStreaming(file: File, chunkSize?: number): AsyncGenerator<StreamingChunkResult>;
+/**
+ * Processes an entire file via streaming and returns all results.
+ * This is a convenience function that collects all generator results.
+ *
+ * For very large files, prefer using processFileStreaming directly
+ * to process chunks as they're generated.
+ *
+ * @param file - The file to process
+ * @param onProgress - Optional callback for progress updates
+ * @returns All hashes and compressed chunks
+ */
+declare function processFileStreamingComplete(file: File, onProgress?: (current: number, total: number) => void): Promise<StreamingProcessResult>;
+/**
+ * Estimates the number of chunks for a file without reading it.
+ *
+ * @param fileSize - Size of the file in bytes
+ * @param isBinary - Whether the file is binary (uses smaller chunk size for base64 alignment)
+ * @returns Estimated number of chunks
+ */
+declare function estimateChunkCount(fileSize: number, isBinary?: boolean): number;
+
 declare const STORAGE_CONTRACT: {
     abi: Abi;
     address: `0x${string}`;
@@ -570,4 +512,4 @@ declare const CONCURRENT_XML_FETCHES = 3;
  */
 declare function resolveXmlRecursive(content: string, defaultOperator: string, client: PublicClient, maxDepth: number, visited?: Set<string>, inheritedOperator?: string): Promise<string>;
 
-export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };
+export { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, StorageClientOptions, StorageData, type StreamingChunkResult, type StreamingProcessResult, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, estimateChunkCount, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, isBinaryFile, parseNetReferences, processDataForStorage, processFileStreaming, processFileStreamingComplete, readFileSlice, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, validateDataSize };