@fizzyflow/endless-vector 0.0.3 → 0.0.5

package/EndlessVector.js

@@ -8,6 +8,7 @@ import ids from './ids.js';
  * @typedef {import('@mysten/sui/client').SuiClient} SuiClient
  * @typedef {import('@mysten/sui/client').GetObjectParams} GetObjectParams
  * @typedef {import('@mysten/sui/client').GetDynamicFieldsParams} GetDynamicFieldsParams
+ * @typedef {import('@mysten/sui/transactions').TransactionResult} TransactionResult
  */
 
 /**
@@ -94,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 {?Array<Uint8Array>} [params.items] - Optional array of Uint8Array items to initialize the vector with. If provided, uses empty_entry_and_push, otherwise uses empty_entry
+     * @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
@@ -103,7 +104,7 @@ export default class EndlessVector {
      * @throws {Error} If the transaction fails or no EndlessVector object is created
      */
     static async create(params) {
-        const { suiClient, packageId, signAndExecuteTransaction, items, gasCoin, options = {} } = params;
+        const { suiClient, packageId, signAndExecuteTransaction, array, gasCoin, options = {} } = params;
 
         let normalizedPackageId = packageId;
         if (normalizedPackageId == 'mainnet' || (!normalizedPackageId && suiClient?.network == 'mainnet')) {
@@ -129,11 +130,31 @@ export default class EndlessVector {
             tx.setGasPayment([gasCoin]);
         }
 
-        if (items && Array.isArray(items) && items.length) {
-            tx.moveCall({
-                target: `${normalizedPackageId}::endless_vector::empty_entry_and_push`,
-                arguments: [tx.pure(bcs.vector(bcs.vector(bcs.u8())).serialize(items))],
-            });
+        if (array && array.length) {
+            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`,
@@ -180,33 +201,92 @@ export default class EndlessVector {
         });
     }
 
-    get isWritable() {
-        return !!(this._packageId && this._signAndExecuteTransaction);
-    }
-
     /**
-    * 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.
+     * Creates an empty EndlessVector and returns the vector input reference.
+     * Appends vector creation to existing transaction or makes new one.
+     * 
+     * Returns the vector input reference for use in subsequent move calls as argument or to be transferred.
+     *
+     * @param {Object} params - Configuration parameters
+     * @param {string} params.packageId - The package ID ('mainnet', 'testnet', or explicit package ID)
+     * @param {Uint8Array|null} [arr=null] - Optional Uint8Array to push back to the new vector as the first item
+     * @param {Transaction|null} [txToAppendTo=null] - Optional existing transaction to append the move calls to
+     * @returns {Promise<TransactionResult>} Vector input reference for use in subsequent move calls
+     * @throws {Error} Throws if packageId is not provided or invalid
+     *
+     * @example
+     * // Create an empty vector
+     * const vectorInput = await EndlessVector.getCreateTransactionAndReturnVectorInput({
+     *   packageId: 'mainnet'
+     * });
+     *
+     * @example
+     * // Create and populate a vector within an existing transaction
+     * const data = new Uint8Array([1, 2, 3, 4]);
+     * const tx = new Transaction();
+     * const vectorInput = await EndlessVector.getCreateTransactionAndReturnVectorInput({
+     *   packageId: contract.id
+     * }, data, tx);
+     */
+    static async getCreateTransactionAndReturnVectorInput(params, arr = null, txToAppendTo = null) {
+        const { packageId } = params;
+        let normalizedPackageId = packageId;
+        if (normalizedPackageId == 'mainnet') {
+            normalizedPackageId = ids['mainnet'].packageId;
+        } else if (normalizedPackageId == 'testnet') {
+            normalizedPackageId = ids['testnet'].packageId;
+        }
 
-    * @param {Uint8Array} arr - Array of byte arrays to push
-    * @returns {Transaction} The transaction object to be signed and executed
-    */
-    getPushTransaction(arr, txToAppendTo = null) {
-        if (!this._packageId) {
-            throw new Error('packageId is required to compose push transaction');
+        if (!normalizedPackageId) {
+            throw new Error('packageId is required');
         }
+        // Create transaction to call empty_entry
 
         let tx = txToAppendTo;
         if (!tx) {
             tx = new Transaction();
         }
 
+        const vectorInput = tx.moveCall({
+            target: `${normalizedPackageId}::endless_vector::empty`,
+            arguments: [],
+        });
+
+        if (arr && arr) {
+            EndlessVector.composePushTransaction(normalizedPackageId, vectorInput, arr, tx);
+        }
+
+        return vectorInput;
+    }
+
+    get isWritable() {
+        return !!(this._packageId && this._signAndExecuteTransaction);
+    }
+
+    /** 
+     * Attach move calls to transaction, to push item into endlessvector, handling large arrays by chunking them.
+     * This static method can be used to compose transactions for any existing EndlessVector instance:
+     * tx.object(vector.id)
+     * or newly created one, accepting TransactionResult as vectorInput, see: getCreateTransactionAndReturnVectorInput
+     *
+     * For arrays smaller than 12KB, it uses a single push_back call.
+     * For arrays between 12KB and 120KB, it splits the data into 10 chunks and uses compose_and_push_back.
+     *
+     * @static
+     * @param {string} packageId - The package ID of the Move module containing the endless_vector functions
+     * @param {TransactionObjectArgument} vectorInput - The transaction object argument representing the EndlessVector
+     * @param {Uint8Array} arr - The byte array to push to the vector
+     * @param {Transaction} tx - The transaction object to append the move calls to
+     * @returns {Transaction} The transaction object with the push operations added
+     * @throws {Error} If the array is larger than 120KB (10 * 12KB)
+     */
+    static composePushTransaction(packageId, vectorInput, arr, tx) {
         const maxArgLength = 12 * 1024;
         if (arr.length < maxArgLength) {
                 tx.moveCall({
-                        target: `${this._packageId}::endless_vector::push_back`,
+                        target: `${packageId}::endless_vector::push_back`,
                         arguments: [
-                            tx.object(this.id),
+                            vectorInput,
                             tx.pure(bcs.vector(bcs.u8()).serialize(arr)),
                         ],
                     });
@@ -223,17 +303,49 @@ export default class EndlessVector {
                     chunks.push(new Uint8Array()); // empty chunk
                 }
             }
-            const args = [tx.object(this.id)];
+            const args = [vectorInput];
             for (let i = 0; i < N; i++) {
                 args.push(tx.pure(bcs.vector(bcs.u8()).serialize(chunks[i])));
             }
             tx.moveCall({
-                    target: `${this._packageId}::endless_vector::compose_and_push_back`,
+                    target: `${packageId}::endless_vector::compose_and_push_back`,
                     arguments: args,
                 });
         } else {
             throw new Error('Array too large, max '+(10*maxArgLength)+' bytes supported per single tx');
         }
+
+        return tx;
+    }
+
+
+    /**
+    * 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|Uint8Array[]} arr - Uint8Array to push
+    * @returns {Transaction} The transaction object to be signed and executed
+    */
+    getPushTransaction(arr, txToAppendTo = null) {
+        if (!this._packageId) {
+            throw new Error('packageId is required to compose push transaction');
+        }
+
+        let tx = txToAppendTo;
+        if (!tx) {
+            tx = new Transaction();
+        }
+
+        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;
     }
 
@@ -243,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

@@ -32,10 +32,8 @@ const vector = await EndlessVector.create({
 const vectorWithData = await EndlessVector.create({
     suiClient: client,
     packageId: 'testnet',  // or 'mainnet' or '0xYOUR_PACKAGE_ID'
-    items: [
-        new Uint8Array([1, 2, 3]),
-        new Uint8Array([4, 5, 6])
-    ],
+    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;
@@ -57,7 +55,7 @@ console.log('Total items:', vector.length);
 console.log('Total size:', vector.binaryLength, 'bytes');
 
 // Read items
-const firstItem = await vector.at(0);
+const firstItem = await vector.at(0); // Uint8Array
 ```
 
 ## API Reference
@@ -72,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
-- `items` (Array<Uint8Array>, optional) - Initial items to push to the 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)
@@ -85,7 +83,7 @@ Creates a new EndlessVector on the blockchain.
 const vector = await EndlessVector.create({
     suiClient: client,
     packageId: 'testnet',  // or 'mainnet' or '0xPACKAGE_ID'
-    items: [new Uint8Array([1, 2, 3])],
+    array: new Uint8Array([1, 2, 3]),
     gasCoin: {
         objectId: '0xGAS_COIN_ID',
         digest: 'DIGEST',
@@ -145,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]);
@@ -153,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)
@@ -173,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
@@ -276,7 +274,7 @@ const vectors = await Promise.all(
         EndlessVector.create({
             suiClient: client,
             packageId: 'testnet',  // or 'mainnet' or '0xPACKAGE_ID'
-            items: items,
+            array: items,
             gasCoin: gasCoinRefs[i],
             signAndExecuteTransaction: async (tx) => {
                 const result = await wallet.signAndExecuteTransaction({ transaction: tx });

package/ids.js

@@ -1,11 +1,11 @@
 
 export default {
     'testnet': {
-        packageId: '0x5e35ef9e8ea315a4db40047b9133c028603168e7b41a27511e9f7eea38313685', // should be the same as in Move.lock
-        originalPackageId: '0x5e35ef9e8ea315a4db40047b9133c028603168e7b41a27511e9f7eea38313685',
+        packageId: '0x30bf8e91f40774ed08234f767360b4154562232903928b5f2f8fe5b2d51655bc', // should be the same as in Move.lock
+        originalPackageId: '0x30bf8e91f40774ed08234f767360b4154562232903928b5f2f8fe5b2d51655bc',
     },
     'mainnet': {
-        packageId: '0xa81971816c632022658736d464d35bd47a7d6b5ad60e0903697e4adda0aa1331', // should be the same as in Move.lock
-        originalPackageId: '0xa81971816c632022658736d464d35bd47a7d6b5ad60e0903697e4adda0aa1331',
+        packageId: '0x94cf19d164f014cfe73dda1121f27b54b69f0dbfa89d8b6ed48ae8a9144f5d65', // should be the same as in Move.lock
+        originalPackageId: '0x94cf19d164f014cfe73dda1121f27b54b69f0dbfa89d8b6ed48ae8a9144f5d65',
     },  
 };

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.3",
+    "version": "0.0.5",
     "description": "",
     "type": "module",
     "main": "./index.js",
+    "types": "./index.d.ts",
     "keywords": [
         "sui",
         "vector",
@@ -24,7 +25,7 @@
     "author": "suidouble (https://github.com/suidouble)",
     "license": "Apache-2.0",
     "scripts": {
-        "test": "tap -j1 -t240 ./test/*.test.js"
+        "test": "tap -j1 -t320 ./test/*.test.js"
     },
     "peerDependencies": {
         "@mysten/sui": "^1.44.0"

package/test/base.test.js

@@ -71,8 +71,78 @@ test('attach a local package', async t => {
 });
 
 
+test('test raw create transaction', async t => {
+    const arr = randomBytesOfLength(120 * 1024); // 100KB
+    
+    const tx = new suiMaster.Transaction();
+    const vectorTxInput = await EndlessVector.getCreateTransactionAndReturnVectorInput({
+        packageId: contract.id,
+    }, arr, tx);
+    tx.transferObjects([vectorTxInput], tx.pure.address(suiMaster.address));
+    
+    t.ok(tx);
+    let digest = null;
+    try {
+        digest = await signAndExecuteTransaction(tx);
+        t.ok(digest);
+    } catch (e) {
+        console.error('Error preparing transaction:', e);
+    }
+
+    const transactionBlockResponse = await suiMaster.client.waitForTransaction({
+        digest: digest,
+        options: { showObjectChanges: true, },
+    }); 
+
+    // Find the created EndlessVector object
+    const objectChanges = transactionBlockResponse.objectChanges || [];
+    const createdVector = objectChanges.find(
+        change => change.type === 'created' &&
+                    change.objectType &&
+                    change.objectType.includes('endless_vector::EndlessVector')
+    );
+
+    const createdVectorId = createdVector ? createdVector.objectId : null;
+    t.ok(createdVectorId, 'Created EndlessVector object should have an ID');
+
+    const loadBack = new EndlessVector({
+        suiClient: suiMaster.client,
+        id: createdVectorId,
+    });
+    await loadBack.initialize();
+
+    t.ok(loadBack.length === 1, `Loaded vector should have length 1, got ${loadBack.length}`);
+    const getBack = await loadBack.at(0);
+    t.ok(equalUint8Arrays(getBack, arr), 'Data retrieved from loaded vector should match original data');
+});
 
 
+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
@@ -358,7 +428,7 @@ test('test parallel creation, push, and append of 6 vectors', async t => {
     // Prepare test data for each vector
     const testData = [];
     for (let i = 0; i < vectorCount; i++) {
-        testData.push([randomBytesOfLength(1024), new Uint8Array([0, 1, i])]);
+        testData.push(randomBytesOfLength(1024));
     }
 
     // Create N EndlessVectors in parallel using static create method
@@ -368,7 +438,7 @@ test('test parallel creation, push, and append of 6 vectors', async t => {
             EndlessVector.create({
                 suiClient: suiMaster.client,
                 packageId: contract.id,
-                items: testData[i] ? testData[i] : [],
+                array: testData[i] ? testData[i] : null,
                 gasCoin: gasCoinInputs[i],
                 signAndExecuteTransaction: async (tx) => {
                     console.log(`Creating vector ${i}...`);
@@ -407,24 +477,20 @@ test('test parallel creation, push, and append of 6 vectors', async t => {
     // Verify the data after concatenation
     await mainVector.initialize();
 
-    // Each vector has 2 items, so total should be vectorCount * 2
-    const expectedLength = vectorCount * 2;
+    const expectedLength = vectorCount;
     t.ok(mainVector.length === expectedLength, `mainVector should have ${expectedLength} items, got ${mainVector.length}`);
 
     console.log(`Verifying ${expectedLength} items in concatenated vector...`);
 
     // Verify each item matches the original testData
     for (let vectorIdx = 0; vectorIdx < vectorCount; vectorIdx++) {
-        for (let itemIdx = 0; itemIdx < testData[vectorIdx].length; itemIdx++) {
-            const globalIdx = vectorIdx * testData[vectorIdx].length + itemIdx;
-            const retrieved = await mainVector.at(globalIdx);
-            const expected = testData[vectorIdx][itemIdx];
-
-            t.ok(
-                equalUint8Arrays(retrieved, expected),
-                `Item ${globalIdx} (vector ${vectorIdx}, item ${itemIdx}) should match`
-            );
-        }
+        const expected = testData[vectorIdx];
+        const retrieved = await mainVector.at(vectorIdx);
+
+        t.ok(
+            equalUint8Arrays(retrieved, expected),
+            `Item ${vectorIdx} (vector ${vectorIdx}, item ${vectorIdx}) should match`
+        );
     }
 });