@net-protocol/storage 0.1.11 → 0.1.13

package/README.md

@@ -32,8 +32,8 @@ Net Storage supports three storage patterns for different file sizes:
 
 ### XML Storage
 
-**Best for**: Large files (> 20KB) or files containing XML references  
-**How it works**: Splits large files into 80KB pieces, stores each using ChunkedStorage (compressed and chunked into 20KB pieces), maintains references as XML metadata  
+**Best for**: Large files (> 20KB) or files containing XML references
+**How it works**: Splits large files into 80KB pieces (configurable via `chunkSize`), stores each using ChunkedStorage (compressed and chunked into 20KB pieces), maintains references as XML metadata
 **Use cases**: Videos, large images, datasets, any large file
 
 ## What can you do with this package?
@@ -133,38 +133,24 @@ function XmlComponent() {
   return <div>{data}</div>;
 }
 
-// XML storage with format options
-function XmlWithFormats() {
-  // Return as tuple format with hex output
-  const { data: tupleData } = useXmlStorage({
+// XML storage with options
+function XmlWithOptions() {
+  // With hex output (default)
+  const { data: hexData, isXml } = useXmlStorage({
     chainId: 8453,
     key: "my-xml-key",
     operatorAddress: "0x...",
-    returnFormat: "tuple", // Returns [text, data] tuple
     outputFormat: "hex", // Data is hex string (default)
     useRouter: true, // Use StorageRouter for automatic detection
   });
 
-  // Return as tuple format with string output
-  const { data: tupleStringData } = useXmlStorage({
+  // With string output
+  const { data: stringData } = useXmlStorage({
     chainId: 8453,
     key: "my-xml-key",
     operatorAddress: "0x...",
-    returnFormat: "tuple",
     outputFormat: "string", // Data is plain string
   });
-
-  // Return as object format (default)
-  const {
-    data: objectData,
-    filename,
-    isXml,
-  } = useXmlStorage({
-    chainId: 8453,
-    key: "my-xml-key",
-    operatorAddress: "0x...",
-    returnFormat: "object", // Returns { data, filename, isLoading, error, isXml }
-  });
 }
 
 // Storage from router (handles chunked storage)
@@ -228,6 +214,7 @@ import {
   fileToDataUri,
   detectFileTypeFromBase64,
   base64ToDataUri,
+  OPTIMAL_CHUNK_SIZE,
 } from "@net-protocol/storage";
 
 // Generate storage key bytes
@@ -242,8 +229,11 @@ const assembled = assembleChunks(chunks);
 // Parse XML references
 const references = parseNetReferences('<net k="hash" v="0.0.1" />');
 
-// Process data for XML storage
-const result = processDataForStorage(data, operatorAddress);
+// Process data for XML storage (default 80KB chunk size)
+const result = processDataForStorage(data, operatorAddress, storageKey);
+
+// Process with custom chunk size (40KB)
+const result2 = processDataForStorage(data, operatorAddress, storageKey, 40000);
 ```
 
 ### File Utilities
@@ -297,6 +287,11 @@ const dataUri = base64ToDataUri(base64Data);
 - `getForOperatorAndKey(params)` - Get storage by operator and key
 - `readStorageData(params)` - Read with XML resolution
 - `readChunkedStorage(params)` - Read chunked storage with decompression
+- `prepareXmlStorage(params)` - Prepare XML storage transactions (supports optional `chunkSize`)
+
+### Constants
+
+- `OPTIMAL_CHUNK_SIZE` - Default chunk size for XML storage (80000 bytes)
 
 ## Storage Types
 

package/dist/index.d.mts

@@ -183,6 +183,7 @@ declare class StorageClient {
         filename?: string;
         useChunkedStorageBackend?: boolean;
         keyFormat?: "raw" | "bytes32";
+        chunkSize?: number;
     }): {
         transactionConfigs: WriteTransactionConfig[];
         topLevelHash: string;
@@ -297,6 +298,7 @@ declare function resolveOperator(reference: XmlReference, defaultOperator: strin
  */
 declare function getReferenceKey(reference: XmlReference, defaultOperator: string): string;
 
+declare const OPTIMAL_CHUNK_SIZE: number;
 /**
  * Split data into chunks of specified size
  */
@@ -325,7 +327,7 @@ declare function computeTopLevelHash(chunkHashes: string[]): string;
 /**
  * Complete chunking and hash generation process
  */
-declare function processDataForStorage(data: string, operatorAddress: string, storageKey?: string): {
+declare function processDataForStorage(data: string, operatorAddress: string, storageKey?: string, chunkSize?: number): {
     chunks: string[];
     chunkHashes: string[];
     xmlMetadata: string;
@@ -512,4 +514,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 { 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 };
+export { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, OPTIMAL_CHUNK_SIZE, 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

@@ -183,6 +183,7 @@ declare class StorageClient {
         filename?: string;
         useChunkedStorageBackend?: boolean;
         keyFormat?: "raw" | "bytes32";
+        chunkSize?: number;
     }): {
         transactionConfigs: WriteTransactionConfig[];
         topLevelHash: string;
@@ -297,6 +298,7 @@ declare function resolveOperator(reference: XmlReference, defaultOperator: strin
  */
 declare function getReferenceKey(reference: XmlReference, defaultOperator: string): string;
 
+declare const OPTIMAL_CHUNK_SIZE: number;
 /**
  * Split data into chunks of specified size
  */
@@ -325,7 +327,7 @@ declare function computeTopLevelHash(chunkHashes: string[]): string;
 /**
  * Complete chunking and hash generation process
  */
-declare function processDataForStorage(data: string, operatorAddress: string, storageKey?: string): {
+declare function processDataForStorage(data: string, operatorAddress: string, storageKey?: string, chunkSize?: number): {
     chunks: string[];
     chunkHashes: string[];
     xmlMetadata: string;
@@ -512,4 +514,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 { 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 };
+export { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, OPTIMAL_CHUNK_SIZE, 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.js

@@ -1010,8 +1010,8 @@ function validateDataSize(chunks) {
 function computeTopLevelHash(chunkHashes) {
   return core.keccak256HashString(chunkHashes.join(""));
 }
-function processDataForStorage(data, operatorAddress, storageKey) {
-  const chunks = chunkData(data);
+function processDataForStorage(data, operatorAddress, storageKey, chunkSize) {
+  const chunks = chunkData(data, chunkSize);
   const validation = validateDataSize(chunks);
   if (!validation.valid) {
     return {
@@ -1482,7 +1482,8 @@ var StorageClient = class {
     const result = processDataForStorage(
       params.data,
       params.operatorAddress,
-      params.storageKey
+      params.storageKey,
+      params.chunkSize
     );
     if (!result.valid) {
       throw new Error(result.error || "Failed to process data for storage");
@@ -1775,6 +1776,7 @@ exports.CHUNKED_STORAGE_CONTRACT = CHUNKED_STORAGE_CONTRACT;
 exports.CHUNKED_STORAGE_READER_CONTRACT = CHUNKED_STORAGE_READER_CONTRACT;
 exports.CONCURRENT_XML_FETCHES = CONCURRENT_XML_FETCHES;
 exports.MAX_XML_DEPTH = MAX_XML_DEPTH;
+exports.OPTIMAL_CHUNK_SIZE = OPTIMAL_CHUNK_SIZE;
 exports.SAFE_STORAGE_READER_CONTRACT = SAFE_STORAGE_READER_CONTRACT;
 exports.STORAGE_CONTRACT = STORAGE_CONTRACT;
 exports.STORAGE_ROUTER_CONTRACT = STORAGE_ROUTER_CONTRACT;