suidouble 2.5.0 → 2.16.0

package/lib/SuiMemoryObjectStorage.js

@@ -2,8 +2,14 @@ import SuiCommonMethods from './SuiCommonMethods.js';
 import SuiObject from './SuiObject.js';
 
 /**
- * Class to work with SuiObject's in bulk
- * 
+ * @typedef {import("./SuiMaster.js").default} SuiMaster
+ */
+
+/**
+ * In-memory registry of `SuiObject` instances keyed by normalized address. One instance is
+ * created per connected chain (see `instanceOf`). Used by `SuiPackageModule` and friends to
+ * deduplicate object references across moveCall results and queries.
+ *
  * Sample usage:
  * ```
  * suiMemoryObjectStorage.push(id);
@@ -17,26 +23,41 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
      * SuiMemoryObjectStorage constructor
      * @param {Object} params - Initialization parameters
      * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * @param {boolean} [params.debug]
      */
-    constructor(params = {}) {
+    constructor(params) {
         super(params);
 
+        /** @type {SuiMaster} */
         this._suiMaster = params.suiMaster;
 
         /** @type {Object.<string, SuiObject>} */
         this._objects = {};
     }
 
+    /** @returns {SuiObject[]} all stored SuiObjects, in insertion order */
     asArray() {
         return Object.values(this._objects);
     }
 
+    /**
+     * Find the most-recently-pushed object whose `typeName` (short type name, e.g. "ChatTopMessage")
+     * matches `typeName`. Ordering is by each object's `constructedAt` timestamp.
+     *
+     * @param {string} typeName
+     * @returns {?SuiObject}
+     */
     findMostRecentByTypeName(typeName) {
         return this.findMostRecent((object) => {
                 return (object.typeName == typeName);
             });
     }
 
+    /**
+     * Return the first stored object for which `filterFunction` returns truthy.
+     * @param {(obj: SuiObject) => boolean} filterFunction
+     * @returns {?SuiObject}
+     */
     find(filterFunction) {
         for (const id in this._objects) {
             if (filterFunction(this._objects[id])) {
@@ -47,6 +68,11 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
         return null;
     }
 
+    /**
+     * Return the most-recently-constructed object (by `constructedAt`) that matches `filterFunction`.
+     * @param {(obj: SuiObject) => boolean} filterFunction
+     * @returns {?SuiObject}
+     */
     findMostRecent(filterFunction) {
         let mostRecentDate = null;
         let mostRecentObject = null;
@@ -64,22 +90,26 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
     }
 
     /**
-     * @param {SuiObject | string} suiObjectOrId 
-     * 
-     * @returns {SuiObject | null}
+     * Store a SuiObject, or wrap a raw `0x…` id in a new SuiObject and store it.
+     * If an object with the same address is already stored, it is returned as-is (no replacement).
+     *
+     * @param {SuiObject | string} suiObjectOrId - a SuiObject instance, or a `0x…` id string
+     * @returns {?SuiObject} the stored instance, or null if input didn't look like either
      */
     push(suiObjectOrId) {
-        if (suiObjectOrId && suiObjectOrId.address) {
-            const /** @type {SuiObject} */ obj = suiObjectOrId;
+        const a = /** @type {any} */ (suiObjectOrId);
+        if (a && a.address) {
+            const obj = /** @type {SuiObject} */ (a);
             this._objects[obj.address] = obj;
 
             return obj;
-        } else if (suiObjectOrId && (''+suiObjectOrId).indexOf('0x') === 0) {
-            if (this._objects[suiObjectOrId]) {
-                return this._objects[suiObjectOrId];
+        } else if (a && (''+a).indexOf('0x') === 0) {
+            const id = /** @type {string} */ (a);
+            if (this._objects[id]) {
+                return this._objects[id];
             }
 
-            const obj = new SuiObject({id: suiObjectOrId, suiMaster: this._suiMaster});
+            const obj = new SuiObject({id, suiMaster: this._suiMaster});
             this._objects[obj.address] = obj;
 
             return obj;
@@ -88,6 +118,11 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
         return null;
     }
 
+    /**
+     * Lookup by address. The address must already be in its normalized form (as produced by SuiObject).
+     * @param {string} address
+     * @returns {?SuiObject}
+     */
     byAddress(address) {
         if (this._objects[address]) {
             return this._objects[address];
@@ -95,78 +130,36 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
         return null;
     }
 
+    /**
+     * Refresh every non-deleted stored SuiObject's fields from chain.
+     * Delegates to `SuiMaster.getObjects(...)` which mutates the passed-in instances in place.
+     *
+     * @returns {Promise<SuiObject[]>}
+     */
     async fetchObjects() {
-        const objectsToFetch = this.asArray(); //Object.values(this._objects);
+        const objectsToFetch = this.asArray().filter((o) => !o.isDeleted);
+        if (!objectsToFetch.length) return [];
 
-        const objectIds = [];
-        for (const object of objectsToFetch) {
-            if (!object.isDeleted && objectIds.indexOf(object.address) === -1) {
-                objectIds.push(object.address);
-            }
-        }
-
-        this.log('querying details about', objectIds.length, 'objects');
-        this.log(objectIds);
-
-        let results = [];
-        const maxCountToFetch = 50;
-        for (let i = 0; i < objectIds.length; i += maxCountToFetch) {
-            const objectIdsSlice = objectIds.slice(i, i + maxCountToFetch);
-
-            let resultsSlice = [];
-            let consoleWarnMessage = null;
-            try {
-                const originalConsoleWarn = console.warn;
-                console.warn = (e)=>{
-                    consoleWarnMessage = e;
-                };
-                resultsSlice = await this._suiMaster._client.multiGetObjects({
-                    ids: objectIdsSlice,
-                    options: { showType: true, showContent: true, showOwner: true, showDisplay: true, },
-                  });
-                console.warn = originalConsoleWarn;
-            } catch(e) {
-                console.error(e);
-            }
+        this.log('querying details about', objectsToFetch.length, 'objects');
+        await this._suiMaster.getObjects(objectsToFetch);
 
-            if (consoleWarnMessage) {
-                this.log('got', resultsSlice.length, 'objects but with warning (ok, but probably it is different client vs rpc versions)');
-            } else {
-                this.log('got', resultsSlice.length, 'objects');
-            }
-
-            if (resultsSlice && resultsSlice.length) {
-                results = results.concat(resultsSlice);
-            }
-        }
-
-        for (const object of objectsToFetch) {
-            const foundInResults = results.find(element => object.idEquals(element?.data?.objectId));
-            if (foundInResults) {
-                object.tryToFillDataFromObjectChange(foundInResults);
-                // this.log('got updates for object', object.address, object.fields);
-            } else {
-                // object is removed?
-                const foundInRemoved = results.find(element => (element?.error?.code == 'deleted' && object.idEquals(element?.error?.object_id)));
-                if (foundInRemoved) {
-                    object.markAsDeleted();
-                } else {
-                    this.log('not found in results', object);
-                }
-            }
-        }
+        return objectsToFetch;
     }
 
     static _instances = {};
 
     /**
-     * @param {string} validatorId - just a string for single instance identifier
-     * @param {Object} params - Initialization parameters
+     * Return (and lazily create) a shared SuiMemoryObjectStorage keyed by `validatorId`.
+     * Typically `validatorId` is the connected chain name (`sui:mainnet`, `sui:localnet`, …) so that
+     * objects from different chains stay isolated.
+     *
+     * @param {string} validatorId - identifier for the singleton slot (chain name by convention)
+     * @param {Object} params - Initialization parameters used only on first creation for that slot
      * @param {SuiMaster} params.suiMaster - instance of SuiMaster
-     * 
+     * @param {boolean} [params.debug]
      * @returns {SuiMemoryObjectStorage}
      */
-    static instanceOf(validatorId, params = {}) {
+    static instanceOf(validatorId, params) {
         if (SuiMemoryObjectStorage._instances[validatorId]) {
             return SuiMemoryObjectStorage._instances[validatorId];
         }

package/lib/SuiObject.js

@@ -2,6 +2,9 @@ import SuiCommonMethods from './SuiCommonMethods.js';
 import SuiPaginatedResponse from './SuiPaginatedResponse.js';
 import { normalizeSuiAddress } from './SuiUtils.js';
 
+/**
+ * @import { SuiClientTypes } from "@mysten/sui/client"
+ */
 /**
  * @typedef {import("./SuiMaster.js").default} SuiMaster
  */
@@ -12,23 +15,27 @@ export default class SuiObject extends SuiCommonMethods {
      *
      * @param {Object} params - parameters
      * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * @param {SuiClientTypes.Object} [params.raw] - raw data from api
      * @param {?string} [params.id] - ID or address on the sui blockchain
+     * @param {string|number} [params.version] - object version
+     * @param {?string} [params.type] - fully-qualified Move type string
+     * @param {boolean} [params.debug]
      */
-    constructor(params = {}) {
+    constructor(params) {
         super(params);
 
         /** @type {SuiMaster} */
         this._suiMaster = params.suiMaster;
         if (!this._suiMaster) {
-            throw new Error('suiMaster is requried for suiPackage');
+            throw new Error('suiMaster is required for SuiObject');
         }
 
-        /** @type {string} */
+        /** @type {?string} */
         this._id = params.id || null;
-        this._version = params.version || null;
-
+        /** @type {?number} */
+        this._version = params.version != null ? Number(params.version) : null;
 
-        /** @type {string} */
+        /** @type {?string} */
         this._type = params.type || null;
 
         this._fields = {};          //  on-chain fields on the object
@@ -41,42 +48,84 @@ export default class SuiObject extends SuiCommonMethods {
 
         this._localProperties = {}; // object to store some local data for you to help with your local calculations, no interaction with blockchain
 
-        // this._ownerAddress = null;
-
         this._isDeleted = false;
 
-        if (params.objectChange) {
-            this.tryToFillDataFromObjectChange(params.objectChange);
+        if (params.raw) {
+            this.fillDataFromApi(params.raw);
         }
 
         this._constructedAt = new Date(); // just a helpful data so we can sort later when trying to find most recent item in different modules
     }
 
+    /**
+     * Fill local properties from raw SuiClientTypes.Object api response
+     * @param {SuiClientTypes.Object} raw
+     */
+    fillDataFromApi(raw) {
+        if (!raw) {
+            return;
+        }
+
+        if (raw.objectId && !this._id) {
+            this._id = raw.objectId;
+        }
+        if (raw.version !== undefined && raw.version !== null) {
+            this._version = Number(raw.version);
+        }
+        if (raw.type) {
+            this._type = raw.type;
+        }
+        if (raw.owner) {
+            this._owner = raw.owner;
+        }
+
+        if (raw.json && typeof raw.json === 'object') {
+            this._fields = raw.json;
+        }
+
+        if (raw.display && raw.display.output) {
+            this._display = raw.display.output;
+        }
+    }
+
+    /** @returns {Date} timestamp when this JS object was instantiated (useful for sorting by recency) */
     get constructedAt() {
         return this._constructedAt;
     }
 
+    /**
+     * Compare two Sui object IDs after normalisation.
+     * @param {string} id1
+     * @param {string} id2
+     * @returns {boolean}
+     */
     static idsEqual(id1, id2) {
         return (normalizeSuiAddress(id1) === normalizeSuiAddress(id2));
     }
 
+    /** @returns {boolean} true if this object has been marked deleted */
     get isDeleted() {
         return this._isDeleted;
     }
 
+    /** @returns {boolean} true if the object is shared (owned by the network) */
     get isShared() {
-        return (this._owner && this._owner.Shared);
+        return !!(this._owner && (this._owner.Shared || this._owner.$kind === 'Shared'));
     }
 
+    /** @returns {boolean} true if the object is immutable (frozen) */
     get isImmutable() {
-        return (this._owner && this._owner == 'Immutable');
+        return !!(this._owner && (this._owner === 'Immutable' || this._owner.$kind === 'Immutable'));
     }
 
+    /**
+     * Check whether this object is address-owned by the given address or SuiObject.
+     * @param {string | SuiObject} addressOrSuiObject
+     * @returns {boolean}
+     */
     isOwnedBy(addressOrSuiObject) {
-        let toId = addressOrSuiObject;
-        if (toId.id) {
-            toId = toId.id;
-        }
+        const a = /** @type {any} */ (addressOrSuiObject);
+        const toId = a.id ?? a;
 
         if (this._owner && this._owner.AddressOwner && this._owner.AddressOwner == toId) {
             return true;
@@ -85,30 +134,39 @@ export default class SuiObject extends SuiCommonMethods {
         return false;
     }
 
+    /** Mark this object as deleted on-chain and set `isDeleted` to true. */
     markAsDeleted() {
         this._isDeleted = true;
     }
 
+    /** @returns {?string} raw object id as stored (not normalised) */
     get id() {
         return this._id;
     }
 
+    /** @returns {?string} fully-qualified Move type string, e.g. `'0x2::coin::Coin<0x2::sui::SUI>'` */
     get type() {
         return this._type;
     }
 
     /**
-     * In module type name, without package and module prefix and without <T..> suffix
+     * Short type name — last `::` segment without `<T…>` suffix.
+     * @returns {?string} e.g. `'ChatTopMessage'`
      */
     get typeName() {
         return this._type ? (''+this._type).split('<')[0].split('::').pop() : null;
     }
 
+    /**
+     * Check whether this object's normalised address equals `toId`.
+     * @param {string} toId
+     * @returns {boolean}
+     */
     idEquals(toId) {
         if (!toId) {
             return false;
         }
-        
+
         const thisAddress = this.address;
         if (thisAddress && thisAddress === normalizeSuiAddress(toId)) {
             return true;
@@ -116,6 +174,10 @@ export default class SuiObject extends SuiCommonMethods {
         return false;
     }
 
+    /**
+     * Normalised 0x-padded Sui address, or null if the id is invalid.
+     * @returns {?string}
+     */
     get address() {
         try {
             return normalizeSuiAddress(this._id);
@@ -124,99 +186,49 @@ export default class SuiObject extends SuiCommonMethods {
         }
     }
 
+    /** @returns {Object} on-chain Move struct fields (populated by `fillDataFromApi` or `fetchFields`) */
     get fields() {
         return this._fields;
     }
 
+    /** @returns {Object} Display template rendered output (populated by `fillDataFromApi` or `fetchFields`) */
     get display() {
         return this._display;
     }
 
+    /** @returns {Object} local-only property bag — never sent to chain, for caller convenience */
     get localProperties() {
         return this._localProperties;
     }
 
+    /** @returns {?number} object version (lamport timestamp), or null before `fetchFields` */
     get version() {
         return this._version;
     }
 
     /**
-     * Try to get past version of an object from blockchain.
-     * Non-cacheable
-     * Note from SUI docs, there's no garantee past version is available on nodes, so may return null even if you expect v to be there
-     * @param {Number} v 
-     * @returns SuiObject
+     * Fetch transactions that interacted with this object, via GraphQL.
+     *
+     * @param {Object} [params]
+     * @param {number} [params.limit=10]
+     * @param {string} [params.order]
+     * @returns {Promise<SuiPaginatedResponse>}
      */
-    async getPastObject(v = null) {
-        if (!v) {
-            v = this._version - BigInt(1);
-        }
-        v = Number(v);
-
-        const result = await this._suiMaster._client.tryGetPastObject({
-            version: (v),
-            id: this.address,
-            options: {
-              showType: true,
-              showContent: true,
-              showOwner: true,
-              showDisplay: true,
-              "showPreviousTransaction": true,
-              "showBcs": false,
-              "showStorageRebate": true
-            },
-        });
-
-        if (result && result.details && result.details.objectId) {
-            const pastObject = new SuiObject({
-                suiMaster: this._suiMaster,
-                debug: this._debug,
-                objectChange: result.details,
-            });
-
-            return pastObject;
-        }
-
-        return null;
-    }
-
-    async queryTransactionBlocks(params = {}) {
-        // @todo: InputObject / ChangedObject ? make separate function or a param here?
-        const queryParams = {
-            filter: {
-                InputObject: this.address,
-            },
+    async fetchTransactions(params = {}) {
+        return await this._suiMaster.fetchTransactions({
+            affectedObject: this.address,
             limit: params.limit || 10,
-            options: {
-                /* Whether to show transaction input data. Default to be false. */
-                showInput: true,
-                /* Whether to show transaction effects. Default to be false. */
-                showEffects: true,
-                /* Whether to show transaction events. Default to be false. */
-                showEvents: true,
-                /* Whether to show object changes. Default to be false. */
-                showObjectChanges: true,
-                /* Whether to show coin balance changes. Default to be false. */
-                showBalanceChanges: true,    
-                showContent: true,
-                showOwner: true,
-                showDisplay: true,       
-            },
-        };
-
-        const paginatedResponse = new SuiPaginatedResponse({
-            debug: this._debug,
-            suiMaster: this._suiMaster,
-            params: queryParams,
-            method: 'queryTransactionBlocks',
             order: params.order,
         });
-
-        await paginatedResponse.fetch();
-
-        return paginatedResponse;
     }
 
+    /**
+     * Fetch dynamic fields owned by this object, paginated.
+     * @param {Object} [params]
+     * @param {number} [params.limit=50]
+     * @param {string} [params.order]
+     * @returns {Promise<SuiPaginatedResponse>}
+     */
     async getDynamicFields(params = {}) {
         const queryParams = {
             parentId: this.address,
@@ -227,7 +239,7 @@ export default class SuiObject extends SuiCommonMethods {
             debug: this._debug,
             suiMaster: this._suiMaster,
             params: queryParams,
-            method: 'getDynamicFields',
+            method: 'listDynamicFields',
             order: params.order,
         });
 
@@ -236,22 +248,17 @@ export default class SuiObject extends SuiCommonMethods {
         return paginatedResponse;
     }
 
+    /**
+     * Fetch full field data for this object from chain and merge via `replaceWithSuiObjectIfNeeded`.
+     * Populates `fields`, `display`, `type`, and `version` if not already filled.
+     * @returns {Promise<this>}
+     */
     async fetchFields() {
-        const result = await this._suiMaster._client.getObject({
-            id: this.address, // normalized id
-            options: {
-              showType: true,
-              showContent: true,
-              showOwner: true,
-              showDisplay: true,
-              "showPreviousTransaction": true,
-              "showBcs": false,
-              "showStorageRebate": true
-            },
-        });
-        if (result && result.data) {
-            this.tryToFillDataFromObjectChange(result.data);
+        const fetched = await this._suiMaster.getObject(this.address);
+        if (fetched) {
+            this.replaceWithSuiObjectIfNeeded(fetched);
         }
+        return this;
     }
 
     /**
@@ -283,61 +290,29 @@ export default class SuiObject extends SuiCommonMethods {
             return true;
         }
 
-        return false;
-    }
-
-    /**
-     * Try to fill local object properties with values from ( showObjectChanges = true ) rpc response   
-     * @param {Object} objectChange 
-     */
-    tryToFillDataFromObjectChange(objectChange) {
-        if (!objectChange.objectId && objectChange.data && objectChange.data.objectId) {
-            objectChange = objectChange.data;
-        }
-
-        if (objectChange.type && objectChange.type == 'deleted') {
-            this.markAsDeleted();
-        }
-
-        // basic fields. Available both in getObject and in results of .moveCall
-        if (objectChange.objectId) {
-            if (!this._id) {
-                this._id = objectChange.objectId;
-            } else if (!this.idEquals(objectChange.objectId)) {
-                throw new Error('Trying to fill from different object');
-            }
-            if (objectChange.type && !this._type) {
-                this._type = objectChange.type;
-            }
-        }
-        if (objectChange.version) {
-            this._version = BigInt(objectChange.version);
+        // same or older version — still fill any locally-empty slots
+        let filled = false;
+        if (!this._type && suiObject.type) {
+            this._type = suiObject.type;
+            filled = true;
         }
-        if (objectChange.objectType) {
-            this._type = `${objectChange.objectType}`;
+        if (!this._owner && suiObject._owner) {
+            this._owner = suiObject._owner;
+            filled = true;
         }
-
-        // extra fields. Possible to get them from separate call to getObject or multiGetObjects
-        // .content
-        if (objectChange?.content?.fields) {
-            for (const key in objectChange?.content?.fields) {
-                if (key !== 'id') {
-                    this._fields[key] = objectChange.content.fields[key];
-                }
-            }
+        if ((!this._fields || Object.keys(this._fields).length === 0) && suiObject._fields) {
+            this._fields = suiObject._fields;
+            filled = true;
         }
-
-        // .display
-        if (objectChange?.display?.data) {
-            for (const key in objectChange?.display?.data) {
-                this._display[key] = objectChange.display.data[key];
-            }
+        if ((!this._display || Object.keys(this._display).length === 0) && suiObject._display) {
+            this._display = suiObject._display;
+            filled = true;
         }
-
-        // .owner
-        if (objectChange.owner) {
-            this._owner = objectChange.owner;
+        if (!this._version && suiObject.version) {
+            this._version = suiObject.version;
+            filled = true;
         }
 
+        return filled;
     }
 };