@fizzyflow/endless-vector 0.0.1

package/EndlessVectorArchive.js

@@ -0,0 +1,219 @@
+import EndlessVectorHistory from './EndlessVectorHistory.js';
+
+/**
+ * @typedef {import('@mysten/sui/client').SuiClient} SuiClient
+ * @typedef {import('@mysten/sui/client').GetDynamicFieldsParams} GetDynamicFieldsParams
+ * @typedef {import('./EndlessVector.js').default} EndlessVector
+ */
+
+export default class EndlessVectorArchive {
+    /**
+     * Creates a new EndlessVectorArchive instance.
+     * @param {Object} params - Configuration parameters
+     * @param {SuiClient} [params.suiClient] - Sui client instance for blockchain interactions
+     * @param {string} [params.id] - ID or address of the EndlessVectorArchive on the Sui blockchain
+     * @param {number} [params.index=0] - Index position of this archive item in the sequence
+     * @param {EndlessVector} [params.endlessVector] - Reference to the parent EndlessVector instance
+     * @param {Object} [params.fields] - Raw field data from the blockchain object
+     */
+    constructor(params = {}) {
+        /** @type {SuiClient} */
+        this.suiClient = params.suiClient;
+        /** @type {string} */
+        this.id = params.id;
+        /** @type {number} */
+        this.index = params.index || 0;
+        /** @type {?EndlessVector} */
+        this._endlessVector = params.endlessVector || null; // parent instance of EndlessVector class
+
+        /** @type {string} */
+        this.historyTableId = null; // id of the dynamic field table that contains history items of this EndlessVector
+        /** @type {number} */
+        this.historyItemsCount = 0; // data from EndlessVectorArchive object .history field
+        this._history = {}; // EndlessVectorHistory instances
+
+        /** @type {Array<Uint8Array>} */
+        this._items = []; // final items in the archived vector
+
+        /** @type {boolean} */
+        this._isInitialized = false;
+
+        this._fields = params.fields || null;
+    }
+
+    /**
+     * Sets the fields data for this archive item. Called by loader of EndlessVector.
+     * @param {Object} fields - The fields data from the blockchain object
+     */
+    setFields(fields) {
+        this._fields = fields;
+        this.historyTableId = fields?.history?.fields?.id?.id;
+        this.historyItemsCount = parseInt(fields?.history?.fields?.size || '0');
+    }
+
+    /**
+     * Checks if this archive item has been initialized and is ready for use.
+     * @returns {boolean} True if the archive item is initialized
+     */
+    isReady() {
+        return this._isInitialized;
+    }
+
+    /**
+     * Gets the total number of items stored in this archive.
+     * @returns {number} The length of the archived vector segment
+     */
+    get length() {
+        if (this._fields && this._fields.length) {
+            return parseInt(this._fields.length);
+        }
+        return 0;
+    }
+
+    /**
+     * Gets the first index position that this archive covers.
+     * @returns {number} The starting index (inclusive)
+     */
+    get startsAt() {
+        return this.endsAt - this.length;
+    }
+
+    /**
+     * Gets the last index position that this archive covers.
+     * @returns {number|undefined} The ending index (inclusive), or undefined if not available
+     */
+    get endsAt() {
+        if (this._fields && this._fields.archived_at_length) {
+            return parseInt(this._fields.archived_at_length) - 1;
+        }
+    }
+
+    /**
+     * Initializes this archive item by loading its data from the blockchain.
+     * Uses promise-based synchronization to prevent multiple concurrent initializations.
+     * @returns {Promise<boolean>} True when initialization is complete
+     */
+    async initialize() {
+        if (this._isInitialized) {
+            return true;
+        }
+        if (this.__initializationPromise) {
+            return await this.__initializationPromise;
+        }
+
+        this.__initializationPromiseResolver = null;
+        this.__initializationPromise = new Promise((res)=>{ this.__initializationPromiseResolver = res; });
+
+        await this._endlessVector.loadArchiveItem(this);
+
+        this._isInitialized = true;
+        this.__initializationPromiseResolver();
+
+        delete this.__initializationPromise;
+        delete this.__initializationPromiseResolver;
+    }
+
+    /**
+     * Gets a history item within this archive by its index.
+     * @param {number|string} historyIndex - The index of the history item to retrieve
+     * @returns {Promise<EndlessVectorHistory>} The history item at the specified index
+     * @throws {Error} If historyTableId is not set or history item not found
+     */
+    async getHistory(historyIndex) {
+        // @todo: check by historyItemsCount 
+
+        const historyIndexInt = parseInt(historyIndex);
+
+        if (this._history[historyIndexInt]) {
+            await this._history[historyIndexInt].initialize();
+            return this._history[historyIndexInt];
+        }
+
+        // go throught the dynamic fields of the history table to find the id of the needed history item
+        if (!this.historyTableId) {
+            throw new Error('historyTableId is not set');
+        }
+
+        /** @type {GetDynamicFieldsParams} */
+        const getDynamicFieldsParams  = {
+            parentId: this.historyTableId,
+            options: {
+                showContent: true,
+                showType: true,
+            },
+        };
+
+        let resp = null;
+        let haveToLookMore = true;
+
+        do {
+            resp  = await this.suiClient.getDynamicFields(getDynamicFieldsParams);
+            if (resp && resp.data && resp.data.length) {
+                for (const df of resp.data) {
+                    if (df?.objectId) {
+                        const itemHistoryIndex = parseInt(df.name.value);
+                        const endlessVectorHistory = new EndlessVectorHistory({
+                            suiClient: this.suiClient,
+                            id: df.objectId,
+                            index: itemHistoryIndex,
+                            endlessVector: this._endlessVector,
+                            endlessVectorArchive: this,
+                        });
+                        this._history[itemHistoryIndex] = endlessVectorHistory;
+                        if (itemHistoryIndex === historyIndexInt) {
+                            haveToLookMore = false;
+                        }
+                    }
+                }
+                getDynamicFieldsParams.cursor = resp.nextCursor;
+            }
+        } while (resp?.hasNextPage && haveToLookMore);
+
+        if (!this._history[historyIndexInt]) {
+            throw new Error(`History not found for index ${historyIndexInt}`);
+        }
+
+        await this._history[historyIndexInt].initialize();
+
+        return this._history[historyIndexInt];
+    }
+
+    /**
+     * Retrieves the byte array at the specified index within this archive.
+     * @param {number} i - The index to retrieve
+     * @returns {Promise<Uint8Array>} The byte array at the specified index
+     * @throws {Error} If the index is out of range for this archive item
+     */
+    async at(i) {
+        if (i <= this.endsAt) {
+            for (let j = 0; j < this.historyItemsCount; j++) {
+                const historyItem = await this.getHistory(j);
+                if (j == 0 && i < historyItem.startsAt) {
+                    throw new Error('at() is out of range for this archive item');
+                }
+                if (historyItem.startsAt <= i && i <= historyItem.endsAt) {
+                    return historyItem.at(i);
+                }
+            }
+        }
+
+        throw new Error('at() is out of range for this history item');
+    }
+
+    /**
+     * Gets suffix bytes from a history item at the specified index within this archive.
+     * @param {number} i - The history item index
+     * @returns {Promise<Uint8Array>} The suffix bytes from the history item
+     * @throws {Error} If the index is out of range for this archive item
+     */
+    async getSuffixFromHistoryItemOfIndex(i) {
+        if (i < this.historyItemsCount) {
+            const historyItem = await this.getHistory(i);
+            if (historyItem) {
+                return historyItem.getSuffixStoredBytes();
+            }
+        }
+
+        throw new Error('getSuffixFromHistoryItemOfIndex() is out of range for this archive item');
+    }
+}

package/EndlessVectorHistory.js

@@ -0,0 +1,187 @@
+
+/**
+ * @typedef {import('@mysten/sui/client').SuiClient} SuiClient
+ * @typedef {import('./EndlessVector.js').default} EndlessVector
+ * @typedef {import('./EndlessVectorArchive.js').default} EndlessVectorArchive
+ */
+
+/**
+ * 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 default class EndlessVectorHistory {
+    /**
+     * Creates a new EndlessVectorHistory instance.
+     * @param {Object} params - Configuration parameters
+     * @param {SuiClient} [params.suiClient] - Sui client instance for blockchain interactions
+     * @param {string} [params.id] - Unique identifier for this history item
+     * @param {number} [params.index=0] - Index position of this history item in the sequence
+     * @param {?Object} [params.fields] - Raw field data from the blockchain object
+     * @param {EndlessVector} [params.endlessVector] - Reference to the parent EndlessVector instance
+     * @param {?EndlessVectorArchive} [params.endlessVectorArchive] - Reference to the parent EndlessVectorArchive instance
+     */
+    constructor(params = {}) {
+        /** @type {SuiClient} */
+        this.suiClient = params.suiClient;
+        /** @type {string} */
+        this.id = params.id;
+        /** @type {number} */
+        this.index = params.index || 0;
+
+        /** @type {?Object} */
+        this._fields = params.fields || null;
+        /** @type {EndlessVector} */
+        this._endlessVector = params.endlessVector || null; // parent instance of EndlessVector class
+        /** @type {?EndlessVectorArchive} */
+        this._endlessVectorArchive = params.endlessVectorArchive || null; // parent instance of EndlessVectorArchive class
+
+        /** @type {boolean} */
+        this._isInitialized = false;
+    }
+
+    /**
+     * Sets the fields data for this history item. Called by loader of EndlessVector.
+     * @param {Object} fields - The fields data from the blockchain object
+     */
+    setFields(fields) {
+        this._fields = fields;
+    }
+
+    /**
+     * Checks if this history item has been initialized and is ready for use.
+     * @returns {boolean} True if the history item is initialized
+     */
+    isReady() {
+        return this._isInitialized;
+    }
+
+    /**
+     * Initializes this history item by loading its data from the blockchain.
+     * Uses promise-based synchronization to prevent multiple concurrent initializations.
+     * @returns {Promise<boolean>} True when initialization is complete
+     */
+    async initialize() {
+        if (this._isInitialized) {
+            return true;
+        }
+        if (this.__initializationPromise) {
+            return await this.__initializationPromise;
+        }
+
+        this.__initializationPromiseResolver = null;
+        this.__initializationPromise = new Promise((res)=>{ this.__initializationPromiseResolver = res; });
+
+        await this._endlessVector.loadHistoryItem(this);
+
+        this._isInitialized = true;
+        this.__initializationPromiseResolver();
+
+        delete this.__initializationPromise;
+        delete this.__initializationPromiseResolver;
+    }
+
+    /**
+     * Gets the last index position that this history item covers.
+     * @returns {number|undefined} The ending index (inclusive), or undefined if not available
+     */
+    get endsAt() {
+        if (this._fields && this._fields.saved_at_length) {
+            return parseInt(this._fields.saved_at_length) - 1;
+        }
+    }
+
+    /**
+     * Indicates whether the first item in this history contains suffix bytes that should be 
+     * added to the last item from the previous history segment.
+     * @returns {boolean} True if the first item contains suffix bytes for the previous history
+     */
+    get firstItemIsFromPreviousHistory() {
+        if (this._fields && this._fields.first_item_is_from_previous_history) {
+            return this._fields.first_item_is_from_previous_history;
+        }
+        return false;
+    }
+
+    /**
+     * Gets the first index position that this history item covers.
+     * Calculation adjusts for whether the first item contains suffix bytes for the previous history.
+     * @returns {number} The starting index (inclusive)
+     */
+    get startsAt() {
+        let innerItemsCount = 0;
+        if (this._fields && this._fields.items && this._fields.items.length) {
+            innerItemsCount = this._fields.items.length;
+        }
+        if (this.firstItemIsFromPreviousHistory) {
+            return this.endsAt - innerItemsCount + 2;
+        }
+        return this.endsAt - innerItemsCount + 1;
+    }
+
+    /**
+     * Gets the number of bytes from the next history item that should be appended 
+     * to the last item in this history segment. This should equal the byte length 
+     * of the first item of the next history.
+     * @returns {number} Number of bytes to append from the next history item
+     */
+    get followedByNextBytes() {
+        if (this._fields && this._fields.followed_by_next_bytes) {
+            return parseInt(this._fields.followed_by_next_bytes);
+        }
+        return 0;
+    }
+
+    /**
+     * Retrieves the byte array at the specified index within this history segment.
+     * Handles combining items with suffix bytes from the next history when needed.
+     * @param {number} i - The index to retrieve
+     * @returns {Promise<Uint8Array>} The byte array at the specified index
+     * @throws {Error} If the index is out of range for this history item
+     */
+    async at(i) {
+        if (this.startsAt <= i && i <= this.endsAt) {
+            let indexInItems = i - this.startsAt;
+            if (this.firstItemIsFromPreviousHistory) {
+                indexInItems = i - this.startsAt + 1;
+            }
+
+            if (indexInItems < (this._fields.items.length - 1)) {
+                return new Uint8Array(this._fields.items[indexInItems]);
+            } else if (indexInItems === (this._fields.items.length - 1)) {
+                if (this.followedByNextBytes) {
+                    // if this item is child of archive, get suffix from next item of archive, otherwise from endless vector
+                    const suffix = this._endlessVectorArchive ? 
+                        (await this._endlessVectorArchive.getSuffixFromHistoryItemOfIndex(this.index + 1)) :
+                        (await this._endlessVector.getSuffixFromHistoryItemOfIndex(this.index + 1));
+
+                    if (suffix.length !== this.followedByNextBytes) {
+                        throw new Error('suffix bytes length mismatch');
+                    }
+
+                    const current = new Uint8Array(this._fields.items[indexInItems]);
+                    const combined = new Uint8Array(current.length + suffix.length);
+                    combined.set(current);
+                    combined.set(suffix, current.length);
+                    return combined;
+                } else {
+                    return new Uint8Array(this._fields.items[indexInItems]);
+                }
+            }
+        }
+
+        throw new Error('at() is out of range for this history item');
+    }
+
+    /**
+     * Gets the suffix bytes stored in this history item that should be appended 
+     * to the last item of the previous history segment.
+     * @returns {Uint8Array} The suffix bytes, or empty array if none stored
+     */
+    getSuffixStoredBytes() {
+        if (this.firstItemIsFromPreviousHistory) {
+            return new Uint8Array(this._fields.items[0]);
+        }
+        return new Uint8Array();
+    }
+}