@fizzyflow/endless-vector 0.0.4 → 0.0.5

package/EndlessVector.js

@@ -95,7 +95,7 @@ export default class EndlessVector {
      * @param {SuiClient} params.suiClient - Sui client instance for blockchain interactions
      * @param {string} params.packageId - ID of the Move package containing the EndlessVector module
      * @param {CustomSignAndExecuteTransactionFunction} params.signAndExecuteTransaction - Function to sign and execute transactions
-     * @param {?Uint8Array} [params.array] - Optional Uint8Array to initialize the vector with as the first item to get with .at(0)
+     * @param {?Uint8Array|Uint8Array[]} [params.array] - Optional Uint8Array to initialize the vector with as the first item to get with .at(0)
      * @param {?Object} [params.gasCoin] - Optional gas coin object reference {objectId: string, digest: string, version: string} to use for transaction payment
      * @param {?Object} [params.options] - Optional transaction parameters
      * @param {?Number} [params.options.timeout] - Transaction confirmation timeout in ms, default 30000
@@ -131,13 +131,30 @@ export default class EndlessVector {
         }
 
         if (array && array.length) {
-            const vectorInput = await EndlessVector.getCreateTransactionAndReturnVectorInput({
-                packageId: normalizedPackageId,
-            }, array, tx);
-            tx.moveCall({
-                target: `${normalizedPackageId}::endless_vector::transfer_to_sender`,
-                arguments: [vectorInput],
-            });
+            if ((array instanceof Uint8Array)) {
+                // single chunk
+                const vectorInput = await EndlessVector.getCreateTransactionAndReturnVectorInput({
+                    packageId: normalizedPackageId,
+                }, array, tx);
+                tx.moveCall({
+                    target: `${normalizedPackageId}::endless_vector::transfer_to_sender`,
+                    arguments: [vectorInput],
+                });
+            } else if (array[0] && (array[0] instanceof Uint8Array)) {
+                // multiple chunks
+                const vectorInput = await EndlessVector.getCreateTransactionAndReturnVectorInput({
+                    packageId: normalizedPackageId,
+                }, null, tx);
+                for (let i = 0; i < array.length; i++) {
+                    EndlessVector.composePushTransaction(normalizedPackageId, vectorInput, array[i], tx);
+                }
+                tx.moveCall({
+                    target: `${normalizedPackageId}::endless_vector::transfer_to_sender`,
+                    arguments: [vectorInput],
+                });
+            } else {
+                throw new Error('.array must be Uint8Array or array of Uint8Array');
+            }
         } else {
             tx.moveCall({
                 target: `${normalizedPackageId}::endless_vector::empty_entry`,
@@ -306,7 +323,7 @@ export default class EndlessVector {
     * Creates a transaction to push new byte arrays to the EndlessVector.
     * Note: this method only creates the transaction, it does not sign or execute it.
 
-    * @param {Uint8Array} arr - Uint8Array to push
+    * @param {Uint8Array|Uint8Array[]} arr - Uint8Array to push
     * @returns {Transaction} The transaction object to be signed and executed
     */
     getPushTransaction(arr, txToAppendTo = null) {
@@ -319,7 +336,15 @@ export default class EndlessVector {
             tx = new Transaction();
         }
 
-        EndlessVector.composePushTransaction(this._packageId, tx.object(this.id), arr, tx);
+        if (arr instanceof Uint8Array) {
+            EndlessVector.composePushTransaction(this._packageId, tx.object(this.id), arr, tx);
+        } else if (Array.isArray(arr) && arr[0] && (arr[0] instanceof Uint8Array)) {
+            for (let i = 0; i < arr.length; i++) {
+                EndlessVector.composePushTransaction(this._packageId, tx.object(this.id), arr[i], tx);
+            }
+        } else {
+            throw new Error('.array must be Uint8Array or array of Uint8Array');
+        }
 
         return tx;
     }
@@ -330,7 +355,7 @@ export default class EndlessVector {
      * Requires the instance to be writable (packageId and signAndExecuteTransaction must be provided).
      * @throws {Error} If the instance is not writable or if the transaction fails
      *
-     * @param {Uint8Array} arr - Byte array to push
+     * @param {Uint8Array|Uint8Array[]} arr - Byte array or array of byte arrays to push
      * @param {?Object} params - Configuration parameters
      * @param {?Number} [params.timeout] - wait for transaction confirmation timeout in ms, default 30000
      * @param {?Number} [params.pollIntervalMs] - wait for transaction confirmation poll interval in ms, default 1000

package/README.md

@@ -33,6 +33,7 @@ const vectorWithData = await EndlessVector.create({
     suiClient: client,
     packageId: 'testnet',  // or 'mainnet' or '0xYOUR_PACKAGE_ID'
     array: new Uint8Array([1, 2, 3]),  // [0] to append to EndlessVector
+    //array: [new Uint8Array([1, 2, 3]), new Uint8Array([5, 6, 7])],  // or [0] and [1] to append to EndlessVector
     signAndExecuteTransaction: async (tx) => {
         const result = await wallet.signAndExecuteTransaction({ transaction: tx });
         return result.digest;
@@ -69,7 +70,7 @@ Creates a new EndlessVector on the blockchain.
 - `suiClient` (SuiClient) - Sui client instance for blockchain interactions
 - `packageId` (string) - 'testnet', 'mainnet', or ID of the Move package containing the EndlessVector module
 - `signAndExecuteTransaction` (function) - Function to sign and execute transactions
-- `array` (Uint8Array, optional) - Optional first vector<u8> to push back to the new vector
+- `array` (Uint8Array or Uint8Array[], optional) - Optional first vector<u8>(s) to push back to the new vector
 - `gasCoin` (Object, optional) - Gas coin object reference `{objectId: string, digest: string, version: string}` for transaction payment
 - `options` (Object, optional) - Additional options:
   - `timeout` (number) - Transaction confirmation timeout in ms (default: 30000)
@@ -142,7 +143,7 @@ await vector.reInitialize();
 
 #### push(arr, params)
 
-Pushes a new byte array to the vector. Requires writable mode. Maximum size per item: ~200KB.
+Pushes a Uint8Array or few Uint8Array(Uint8Array[]) to the vector. Requires writable mode. Maximum size per push: ~120KB.
 
 ```javascript
 const data = new Uint8Array([1, 2, 3, 4, 5]);
@@ -150,7 +151,7 @@ await vector.push(data);
 ```
 
 **Parameters:**
-- `arr` (Uint8Array) - Data to push
+- `arr` (Uint8Array or Uint8Array[]) - Data to push
 - `params` (Object, optional) - Additional parameters
 
 #### getPushTransaction(arr, tx)
@@ -170,7 +171,7 @@ await signAndExecuteTransaction(tx);
 ```
 
 **Parameters:**
-- `arr` (Uint8Array) - Data to push
+- `arr` (Uint8Array or Uint8Array[]) - Data to push
 - `tx` (Transaction, optional) - Existing transaction to append to
 
 **Returns:** Transaction

package/index.d.ts

@@ -0,0 +1,347 @@
+import type { SuiClient, GetObjectParams, GetDynamicFieldsParams } from '@mysten/sui/client';
+import type { Transaction, TransactionResult, TransactionObjectArgument } from '@mysten/sui/transactions';
+
+/**
+ * Custom function to sign and execute transactions
+ */
+export type CustomSignAndExecuteTransactionFunction = (tx: Transaction) => Promise<string>;
+
+/**
+ * Configuration parameters for creating an EndlessVector instance
+ */
+export interface EndlessVectorConstructorParams {
+    /** Sui client instance for blockchain interactions */
+    suiClient?: SuiClient;
+    /** ID or address of the EndlessVector on the Sui blockchain */
+    id?: string;
+    /** Adds write capability if provided, ID of the Move package containing the EndlessVector module or 'mainnet', 'testnet' to use known IDs */
+    packageId?: string | null;
+    /** Adds write capability if provided, function should accept Sui transaction, sign and submit it to the blockchain and return its digest */
+    signAndExecuteTransaction?: CustomSignAndExecuteTransactionFunction | null;
+}
+
+/**
+ * Configuration parameters for creating a new EndlessVector via static create method
+ */
+export interface EndlessVectorCreateParams {
+    /** Sui client instance for blockchain interactions */
+    suiClient: SuiClient;
+    /** ID of the Move package containing the EndlessVector module */
+    packageId: string;
+    /** Function to sign and execute transactions */
+    signAndExecuteTransaction: CustomSignAndExecuteTransactionFunction;
+    /** Optional Uint8Array or array of Uint8Arrays to initialize the vector with */
+    array?: Uint8Array | Uint8Array[] | null;
+    /** Optional gas coin object reference {objectId: string, digest: string, version: string} to use for transaction payment */
+    gasCoin?: { objectId: string; digest: string; version: string } | null;
+    /** Optional transaction parameters */
+    options?: {
+        /** Transaction confirmation timeout in ms, default 30000 */
+        timeout?: number;
+        /** Poll interval in ms, default 1000 */
+        pollIntervalMs?: number;
+    };
+}
+
+/**
+ * Configuration parameters for getCreateTransactionAndReturnVectorInput
+ */
+export interface GetCreateTransactionParams {
+    /** The package ID ('mainnet', 'testnet', or explicit package ID) */
+    packageId: string;
+}
+
+/**
+ * Configuration parameters for push and concat operations
+ */
+export interface TransactionOptions {
+    /** wait for transaction confirmation timeout in ms, default 30000 */
+    timeout?: number;
+    /** wait for transaction confirmation poll interval in ms, default 1000 */
+    pollIntervalMs?: number;
+}
+
+/**
+ * Configuration parameters for creating an EndlessVectorHistory instance
+ */
+export interface EndlessVectorHistoryConstructorParams {
+    /** Sui client instance for blockchain interactions */
+    suiClient?: SuiClient;
+    /** Unique identifier for this history item */
+    id?: string;
+    /** Index position of this history item in the sequence */
+    index?: number;
+    /** Raw field data from the blockchain object */
+    fields?: any | null;
+    /** Reference to the parent EndlessVector instance */
+    endlessVector?: EndlessVector;
+    /** Reference to the parent EndlessVectorArchive instance */
+    endlessVectorArchive?: EndlessVectorArchive | null;
+}
+
+/**
+ * Configuration parameters for creating an EndlessVectorArchive instance
+ */
+export interface EndlessVectorArchiveConstructorParams {
+    /** Sui client instance for blockchain interactions */
+    suiClient?: SuiClient;
+    /** ID or address of the EndlessVectorArchive on the Sui blockchain */
+    id?: string;
+    /** Index position of this archive item in the sequence */
+    index?: number;
+    /** Reference to the parent EndlessVector instance */
+    endlessVector?: EndlessVector;
+    /** Raw field data from the blockchain object */
+    fields?: any;
+}
+
+/**
+ * Represents a history item in an EndlessVector, managing a segment of the vector's data.
+ * Each history item stores a portion of the vector's elements and maintains metadata
+ * about its position and relationships with adjacent history items.
+ */
+export declare class EndlessVectorHistory {
+    suiClient: SuiClient;
+    id: string;
+    index: number;
+
+    constructor(params?: EndlessVectorHistoryConstructorParams);
+
+    /**
+     * Sets the fields data for this history item. Called by loader of EndlessVector.
+     */
+    setFields(fields: any): void;
+
+    /**
+     * Checks if this history item has been initialized and is ready for use.
+     */
+    isReady(): boolean;
+
+    /**
+     * Initializes this history item by loading its data from the blockchain.
+     * Uses promise-based synchronization to prevent multiple concurrent initializations.
+     */
+    initialize(): Promise<boolean>;
+
+    /**
+     * Gets the last index position that this history item covers.
+     */
+    get endsAt(): number | undefined;
+
+    /**
+     * Indicates whether the first item in this history contains suffix bytes that should be
+     * added to the last item from the previous history segment.
+     */
+    get firstItemIsFromPreviousHistory(): boolean;
+
+    /**
+     * Gets the first index position that this history item covers.
+     */
+    get startsAt(): number;
+
+    /**
+     * Gets the number of bytes from the next history item that should be appended
+     * to the last item in this history segment.
+     */
+    get followedByNextBytes(): number;
+
+    /**
+     * Retrieves the byte array at the specified index within this history segment.
+     */
+    at(i: number): Promise<Uint8Array>;
+
+    /**
+     * Gets the suffix bytes stored in this history item that should be appended
+     * to the last item of the previous history segment.
+     */
+    getSuffixStoredBytes(): Uint8Array;
+}
+
+/**
+ * Represents an archive item in an EndlessVector
+ */
+export declare class EndlessVectorArchive {
+    suiClient: SuiClient;
+    id: string;
+    index: number;
+    historyTableId: string | null;
+    historyItemsCount: number;
+
+    constructor(params?: EndlessVectorArchiveConstructorParams);
+
+    /**
+     * Sets the fields data for this archive item. Called by loader of EndlessVector.
+     */
+    setFields(fields: any): void;
+
+    /**
+     * Checks if this archive item has been initialized and is ready for use.
+     */
+    isReady(): boolean;
+
+    /**
+     * Gets the total number of items stored in this archive.
+     */
+    get length(): number;
+
+    /**
+     * Gets the first index position that this archive covers.
+     */
+    get startsAt(): number;
+
+    /**
+     * Gets the last index position that this archive covers.
+     */
+    get endsAt(): number | undefined;
+
+    /**
+     * Initializes this archive item by loading its data from the blockchain.
+     */
+    initialize(): Promise<boolean>;
+
+    /**
+     * Gets a history item within this archive by its index.
+     */
+    getHistory(historyIndex: number | string): Promise<EndlessVectorHistory>;
+
+    /**
+     * Retrieves the byte array at the specified index within this archive.
+     */
+    at(i: number): Promise<Uint8Array>;
+
+    /**
+     * Gets suffix bytes from a history item at the specified index within this archive.
+     */
+    getSuffixFromHistoryItemOfIndex(i: number): Promise<Uint8Array>;
+}
+
+/**
+ * Represents an endless vector data structure that can grow beyond Sui object size limits
+ * by storing overflow data in history items. Provides seamless access to all elements regardless
+ * of whether they're stored in the current object or historical segments.
+ */
+export declare class EndlessVector {
+    suiClient: SuiClient;
+    id: string;
+    binaryLength: number;
+    length: number;
+    historyItemsCount: number;
+    historyTableId: string | null;
+    firstItemIsFromPreviousHistory: boolean;
+    archiveTableId: string | null;
+    archiveItemsCount: number;
+    archivedAtLength: number;
+    archivedFromLength: number;
+    burnedArchiveCount: number;
+
+    constructor(params?: EndlessVectorConstructorParams);
+
+    /**
+     * Static factory method to create a new empty EndlessVector on the blockchain.
+     */
+    static create(params: EndlessVectorCreateParams): Promise<EndlessVector>;
+
+    /**
+     * Creates an empty EndlessVector and returns the vector input reference.
+     */
+    static getCreateTransactionAndReturnVectorInput(
+        params: GetCreateTransactionParams,
+        arr?: Uint8Array | null,
+        txToAppendTo?: Transaction | null
+    ): Promise<TransactionResult>;
+
+    /**
+     * Attach move calls to transaction, to push item into endlessvector, handling large arrays by chunking them.
+     */
+    static composePushTransaction(
+        packageId: string,
+        vectorInput: TransactionObjectArgument,
+        arr: Uint8Array,
+        tx: Transaction
+    ): Transaction;
+
+    /**
+     * Check if the EndlessVector instance is writable
+     */
+    get isWritable(): boolean;
+
+    /**
+     * Gets the first index that is stored in the current EndlessVector object (not in history items).
+     */
+    get firstNotHistoryIndex(): number;
+
+    /**
+     * Forces re-initialization of the EndlessVector to reload data from the blockchain.
+     */
+    reInitialize(): void;
+
+    /**
+     * Initializes the EndlessVector by loading data from the Sui blockchain.
+     */
+    initialize(): Promise<void>;
+
+    /**
+     * Gets a history item by its index, loading it from the blockchain if needed.
+     */
+    getHistory(historyIndex: number | string): Promise<EndlessVectorHistory>;
+
+    /**
+     * Gets an archive item by its index, loading it from the blockchain if needed.
+     */
+    getArchive(archiveIndex: number | string): Promise<EndlessVectorArchive>;
+
+    /**
+     * Loads multiple history items in a single batch request for efficiency.
+     */
+    loadHistoryItemsBunch(historyItems: EndlessVectorHistory[]): Promise<void>;
+
+    /**
+     * Loads a single history item, batching requests for efficiency.
+     */
+    loadHistoryItem(historyItem: EndlessVectorHistory): Promise<EndlessVectorHistory>;
+
+    /**
+     * Loads multiple archive items in a single batch request for efficiency.
+     */
+    loadArchiveItemsBunch(archiveItems: EndlessVectorArchive[]): Promise<void>;
+
+    /**
+     * Loads a single archive item, batching requests for efficiency.
+     */
+    loadArchiveItem(archiveItem: EndlessVectorArchive): Promise<EndlessVectorArchive>;
+
+    /**
+     * Retrieves the byte array at the specified index from either current items or history.
+     */
+    at(i: number): Promise<Uint8Array>;
+
+    /**
+     * Gets suffix bytes from a history item at the specified index.
+     */
+    getSuffixFromHistoryItemOfIndex(i: number): Promise<Uint8Array | undefined>;
+
+    /**
+     * Creates a transaction to push new byte arrays to the EndlessVector.
+     */
+    getPushTransaction(arr: Uint8Array | Uint8Array[], txToAppendTo?: Transaction | null): Transaction;
+
+    /**
+     * Pushes new byte array to the EndlessVector, creating and executing the necessary transaction.
+     */
+    push(arr: Uint8Array | Uint8Array[], params?: TransactionOptions): Promise<boolean>;
+
+    /**
+     * Creates a transaction to concatenate EndlessVector(s) into this one.
+     */
+    getConcatTransaction(
+        other: string | EndlessVector | Array<string | EndlessVector>,
+        txToAppendTo?: Transaction | null
+    ): Transaction;
+
+    /**
+     * Concatenates EndlessVector(s) into this one, creating and executing the necessary transaction.
+     */
+    concat(other: string | EndlessVector | Array<string | EndlessVector>, params?: TransactionOptions): Promise<boolean>;
+}
+
+export { EndlessVector as default };

package/package.json

@@ -1,9 +1,10 @@
 {
     "name": "@fizzyflow/endless-vector",
-    "version": "0.0.4",
+    "version": "0.0.5",
     "description": "",
     "type": "module",
     "main": "./index.js",
+    "types": "./index.d.ts",
     "keywords": [
         "sui",
         "vector",

package/test/base.test.js

@@ -117,6 +117,32 @@ test('test raw create transaction', async t => {
 });
 
 
+test('make a test EndlessVector with few chunks in a single tx', async t => {
+    const data = [
+        randomBytesOfLength(1 * 1024),
+        randomBytesOfLength(2 * 1024),
+        randomBytesOfLength(3 * 1024),
+    ];
+
+    const testEndlessVector = await EndlessVector.create({
+        array: data,
+        suiClient: suiMaster.client, // instance of Sui SDK SuiClient
+        packageId: contract.id, // provide packageId and signAndExecuteTransaction to make EndlessVector writable
+        signAndExecuteTransaction: signAndExecuteTransaction,
+    });
+
+    const getBack0 = await testEndlessVector.at(0);
+    const getBack1 = await testEndlessVector.at(1);
+    const getBack2 = await testEndlessVector.at(2);
+
+    t.ok(equalUint8Arrays(getBack0, data[0]));
+    t.ok(equalUint8Arrays(getBack1, data[1]));
+    t.ok(equalUint8Arrays(getBack2, data[2]));
+
+    t.ok(testEndlessVector.length === 3);
+    t.ok(testEndlessVector.binaryLength === 6 * 1024);
+});
+
 test('make a test EndlessVector and push single Uint8Array to it', async t => {
     endlessVector = await EndlessVector.create({
         suiClient: suiMaster.client, // instance of Sui SDK SuiClient