@unyt/datex 0.0.10 → 0.0.12

package/esm/dif/dif-handler.js

@@ -9,16 +9,19 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _DIFHandler_runtime, _DIFHandler_handle, _DIFHandler_transceiver_id, _DIFHandler_cache, _DIFHandler_observers;
+var _DIFHandler_runtime, _DIFHandler_handle, _DIFHandler_transceiver_id, _DIFHandler_cache, _DIFHandler_proxyMapping, _DIFHandler_referenceMetadata, _DIFHandler_observers, _DIFHandler_type_registry;
 import { Ref } from "../refs/ref.js";
-import { Endpoint } from "../runtime/special-core-types.js";
-import { DIFReferenceMutability, DIFUpdateKind, } from "./definitions.js";
+import { Endpoint } from "../lib/special-core-types/endpoint.js";
+import { DIFReferenceMutability, DIFTypeDefinitionKind, DIFUpdateKind, } from "./definitions.js";
 import { CoreTypeAddress, CoreTypeAddressRanges } from "./core.js";
-import { difValueContainerToDisplayString } from "./display.js";
+import { TypeRegistry } from "./type-registry.js";
+import { panic } from "../utils/exceptions.js";
+import { JsLibTypeAddress } from "./js-lib.js";
+export const IS_PROXY_ACCESS = Symbol("IS_PROXY_ACCESS");
 /**
  * The DIFHandler class provides methods to interact with the DATEX Core DIF runtime,
- * including executing Datex scripts, creating and managing pointers, and observing changes.
- * It includes a local pointer cache to optimize performance and reduce cross-language calls.
+ * including executing Datex scripts, creating and managing references, and observing changes.
+ * It includes a local reference cache to optimize performance and reduce cross-language calls.
  */
 export class DIFHandler {
     /**
@@ -42,6 +45,9 @@ export class DIFHandler {
     get _transceiver_id() {
         return __classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f");
     }
+    get type_registry() {
+        return __classPrivateFieldGet(this, _DIFHandler_type_registry, "f");
+    }
     /**
      * Creates a new DIFHandler instance.
      * @param runtime - The JSRuntime instance for executing Datex scripts.
@@ -53,11 +59,22 @@ export class DIFHandler {
         _DIFHandler_handle.set(this, void 0);
         // always 0 for now - potentially used for multi DIF transceivers using the same underlying runtime
         _DIFHandler_transceiver_id.set(this, 0);
-        /** The pointer cache for storing and reusing object instances on the JS side
-         * The observerId is only set if the pointer is being observed (if not final).
+        /**
+         * The reference cache for storing and reusing object instances on the JS side
+         * The observerId is only set if the reference is being observed (if not final).
          */
         _DIFHandler_cache.set(this, new Map());
+        /**
+         * Maps the original value to a proxy value
+         * (if the values is bound to a custom proxy wrapper)
+         */
+        _DIFHandler_proxyMapping.set(this, new WeakMap());
+        /**
+         * The reference metadata map, storing metadata for each cached reference.
+         */
+        _DIFHandler_referenceMetadata.set(this, new WeakMap());
         _DIFHandler_observers.set(this, new Map());
+        _DIFHandler_type_registry.set(this, new TypeRegistry(this));
         __classPrivateFieldSet(this, _DIFHandler_runtime, runtime, "f");
         __classPrivateFieldSet(this, _DIFHandler_handle, runtime.dif(), "f");
     }
@@ -82,31 +99,21 @@ export class DIFHandler {
         return __classPrivateFieldGet(this, _DIFHandler_runtime, "f").execute_sync(datexScript, this.convertToDIFValues(values));
     }
     /**
-     * Creates a new pointer for the specified value.
-     * @param difValue - The DIFValue value to create a pointer for.
+     * Creates a new pointer for the specified DIF value.
+     * @param difValueContainer - The DIFValueContainer value to create a pointer for.
      * @param allowedType - The allowed type for the pointer.
      * @param mutability - The mutability of the pointer.
      * @returns The created pointer address.
      */
-    createPointer(difValue, allowedType = null, mutability) {
-        return __classPrivateFieldGet(this, _DIFHandler_handle, "f").create_pointer(difValue, allowedType, mutability);
-    }
-    /**
-     * Creates a new pointer that points to an existing address.
-     * @param address - The address to create a reference pointer for.
-     * @param allowedType - The allowed type for the pointer.
-     * @param mutability - The mutability of the pointer.
-     * @returns A Promise that resolves to the created pointer address.
-     */
-    createRefPointer(address, allowedType = null, mutability) {
-        return __classPrivateFieldGet(this, _DIFHandler_handle, "f").create_pointer(address, allowedType, mutability);
+    createReferenceFromDIFValue(difValueContainer, allowedType = null, mutability) {
+        return __classPrivateFieldGet(this, _DIFHandler_handle, "f").create_pointer(difValueContainer, allowedType, mutability);
     }
     /**
      * Updates the DIF value at the specified address.
      * @param address - The address of the DIF value to update.
      * @param dif - The DIFUpdate object containing the update information.
      */
-    updatePointer(address, dif) {
+    updateReference(address, dif) {
         __classPrivateFieldGet(this, _DIFHandler_handle, "f").update(__classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f"), address, dif);
     }
     /**
@@ -159,7 +166,7 @@ export class DIFHandler {
      * @param address - The address of the DIF value being observed.
      * @param observerId - The observer ID returned by the observePointer method.
      */
-    unobservePointerBindDirect(address, observerId) {
+    unobserveReferenceBindDirect(address, observerId) {
         __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif().unobserve_pointer(address, observerId);
     }
     /**
@@ -228,22 +235,27 @@ export class DIFHandler {
      * @param value
      */
     resolveDIFValue(value) {
-        console.log("RESOLVE", value);
         let type = value.type;
+        let convertMapToJSObject = false;
+        // no type specified since it is inferable from the value
         if (type === undefined) {
             if (Array.isArray(value.value)) {
+                // [[x,y,]] -> map
                 if (Array.isArray(value.value[0])) {
                     type = CoreTypeAddress.map;
-                }
+                } // [x,y] or [] -> list
                 else {
                     type = CoreTypeAddress.list;
                 }
             }
+            else if (typeof value.value === "object" && value.value !== null) {
+                type = CoreTypeAddress.map;
+                convertMapToJSObject = true;
+            } // primitive JS value, no type specified
             else {
                 return value.value;
             }
         }
-        console.log(type, value);
         // null, boolean and text types values are just returned as is
         if (type === CoreTypeAddress.boolean ||
             type == CoreTypeAddress.text ||
@@ -255,8 +267,7 @@ export class DIFHandler {
             this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.small_unsigned_integers))) {
             return Number(value.value);
         } // big integers are interpreted as JS BigInt
-        else if (typeof type === "string" && (this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.big_signed_integers) ||
-            this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.big_unsigned_integers))) {
+        else if (typeof type === "string" && (this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.big_signed_integers))) {
             return BigInt(value.value);
         } // decimal types are interpreted as JS numbers
         else if (typeof type === "string" &&
@@ -273,25 +284,39 @@ export class DIFHandler {
             if (Array.isArray(value.value)) {
                 const resolvedMap = new Map();
                 for (const [key, val] of value.value) {
-                    // TODO: currently always converting to an object here, but this should be a Map per default
                     resolvedMap.set(this.resolveDIFValueContainer(key), this.resolveDIFValueContainer(val));
                 }
                 // TODO: map promises
                 return resolvedMap;
             }
             else {
-                const resolvedObj = {};
-                for (const [key, val] of Object.entries(value.value)) {
-                    // TODO: currently always converting to an object here, but this should be a Map per default
-                    resolvedObj[key] = this.resolveDIFValueContainer(val);
+                if (convertMapToJSObject) {
+                    const resolvedObj = {};
+                    for (const [key, val] of Object.entries(value.value)) {
+                        resolvedObj[key] = this.resolveDIFValueContainer(val);
+                    }
+                    return resolvedObj;
+                }
+                else {
+                    const resolvedMap = new Map();
+                    for (const [key, val] of Object.entries(value.value)) {
+                        resolvedMap.set(key, this.resolveDIFValueContainer(val));
+                    }
+                    return resolvedMap;
                 }
-                return this.promiseFromObjectOrSync(resolvedObj);
+            }
+        } // impl types
+        else if (typeof type == "object" &&
+            type.kind === DIFTypeDefinitionKind.ImplType) {
+            // undefined (null + js.undefined)
+            if (type.def[0] === CoreTypeAddress.null &&
+                type.def[1].length === 1 &&
+                type.def[1][0] == JsLibTypeAddress.undefined) {
+                return undefined;
             }
         }
-        else {
-            // custom types not implemented yet
-            throw new Error("Custom type resolution not implemented yet");
-        }
+        // custom types not implemented yet
+        throw new Error("Custom type resolution not implemented yet");
     }
     /**
      * Converts an array of Promises or resolved values to either a Promise of an array of resolved values,
@@ -366,6 +391,20 @@ export class DIFHandler {
         }
         return result;
     }
+    /**
+     * Resolves a DIFProperty to its corresponding JS value.
+     */
+    resolveDIFPropertySync(property) {
+        if (property.kind === "text") {
+            return property.value;
+        }
+        else if (property.kind === "index") {
+            return property.value;
+        }
+        else {
+            return this.resolveDIFValueContainerSync(property.value);
+        }
+    }
     /**
      * Resolves a pointer address to its corresponding JS value.
      * If the pointer address is not yet loaded in memory, it returns a Promise that resolves to the value.
@@ -375,7 +414,7 @@ export class DIFHandler {
      */
     resolvePointerAddress(address) {
         // check cache first
-        const cached = this.getCachedPointer(address);
+        const cached = this.getCachedReference(address);
         if (cached) {
             return cached;
         }
@@ -385,7 +424,7 @@ export class DIFHandler {
             const value = this.resolveDIFValueContainer(reference.value);
             return this.mapPromise(value, (v) => {
                 // init pointer
-                this.initPointer(address, v, reference.mut, reference.allowed_type);
+                this.initReference(address, v, reference.mut, reference.allowed_type);
                 return v;
             });
         });
@@ -400,7 +439,7 @@ export class DIFHandler {
      */
     resolvePointerAddressSync(address) {
         // check cache first
-        const cached = this.getCachedPointer(address);
+        const cached = this.getCachedReference(address);
         if (cached) {
             return cached;
         }
@@ -408,16 +447,46 @@ export class DIFHandler {
         const entry = __classPrivateFieldGet(this, _DIFHandler_handle, "f")
             .resolve_pointer_address_sync(address);
         const value = this.resolveDIFValueContainerSync(entry.value);
-        this.initPointer(address, value, entry.mut, entry.allowed_type);
+        this.initReference(address, value, entry.mut, entry.allowed_type);
         return value;
     }
+    /**
+     * Retrieves the original value from a proxy value if available
+     * @param proxy
+     * @returns
+     */
+    getOriginalValueFromProxy(proxy) {
+        const address = this.getPointerAddressForValue(proxy);
+        if (address) {
+            const cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address);
+            if (cached && cached.originalValue) {
+                return cached.originalValue;
+            }
+        }
+        return null;
+    }
+    /**
+     * Retrieves the proxy value for a given original value if available
+     * @param original
+     * @returns
+     */
+    getProxyValueFromOriginal(original) {
+        const ref = __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").get(original);
+        if (ref) {
+            const proxied = ref.deref();
+            if (proxied) {
+                return proxied;
+            }
+        }
+        return null;
+    }
     /**
      * Converts an array of JS values to an array of DIFValues.
      * If the input is null, it returns null.
      * @param values
      */
     convertToDIFValues(values) {
-        return values?.map((value) => this.convertJSValueToDIFValue(value)) ||
+        return values?.map((value) => this.convertJSValueToDIFValueContainer(value)) ||
             null;
     }
     /**
@@ -427,21 +496,41 @@ export class DIFHandler {
         return range.has(address);
     }
     /**
-     * Initializes a pointer with the given value and mutability, by
+     * Initializes a reference with the given value and mutability, by
      * adding a proxy wrapper if necessary, and setting up observation and caching on the JS side.
      */
-    initPointer(ptrAddress, value, mutability, allowedType = null) {
-        const refValue = this.wrapJSValueInProxy(value, ptrAddress, allowedType);
+    initReference(pointerAddress, value, mutability, allowedType = null) {
+        let wrappedValue = this.wrapJSValue(value, pointerAddress, allowedType);
+        let typeBinding = null;
+        let metadata = undefined;
+        // bind js value (if mutable, nominal type)
+        const bindJSValue = mutability !== DIFReferenceMutability.Immutable &&
+            typeof allowedType == "string";
+        if (bindJSValue && !(wrappedValue instanceof Ref)) {
+            typeBinding = this.type_registry.getTypeBinding(allowedType);
+            if (typeBinding) {
+                const { value, metadata: newMetadata } = typeBinding
+                    .bindValue(wrappedValue, pointerAddress);
+                metadata = newMetadata;
+                wrappedValue = value;
+            }
+        }
         // if not immutable, observe to keep the pointer 'live' and receive updates
         let observerId = null;
         if (mutability !== DIFReferenceMutability.Immutable) {
-            observerId = this.observePointerBindDirect(ptrAddress, (update) => {
+            observerId = this.observePointerBindDirect(pointerAddress, (update) => {
                 // if source_id is not own transceiver id, handle pointer update
                 if (update.source_id !== __classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f")) {
-                    this.handlePointerUpdate(ptrAddress, update.data);
+                    try {
+                        this.handlePointerUpdate(pointerAddress, wrappedValue, update.data, typeBinding);
+                    }
+                    catch (e) {
+                        console.error("Error handling pointer update", e);
+                        throw e;
+                    }
                 }
                 // call all local observers
-                const observers = __classPrivateFieldGet(this, _DIFHandler_observers, "f").get(ptrAddress);
+                const observers = __classPrivateFieldGet(this, _DIFHandler_observers, "f").get(pointerAddress);
                 if (observers) {
                     for (const cb of observers.values()) {
                         try {
@@ -455,55 +544,69 @@ export class DIFHandler {
                 console.debug("Pointer update received", update);
             });
         }
-        this.cacheWrappedPointerValue(ptrAddress, refValue, observerId);
-        return refValue;
+        this.cacheWrappedReferenceValue(pointerAddress, value, wrappedValue, observerId, metadata);
+        // set up observers
+        return wrappedValue;
     }
-    /**
-     * Handles a pointer update received from the DATEX core runtime.
-     * If the pointer is cached and has a dereferenceable value, it updates the value.
-     * @param address - The address of the pointer being updated.
-     * @param update - The DIFUpdateData containing the update information.
-     * @returns True if the pointer was found and updated, false otherwise.
-     */
-    handlePointerUpdate(address, update) {
-        const cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address);
+    handlePointerUpdate(pointerAddress, value, update, typeBinding) {
+        const cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(pointerAddress);
         if (!cached)
             return false;
-        const deref = cached.val.deref();
+        const deref = cached.value.deref();
         if (!deref)
             return false;
         if (deref instanceof Ref && update.kind === DIFUpdateKind.Replace) {
             deref.updateValueSilently(this.resolveDIFValueContainerSync(update.value));
         }
-        // TODO: handle generic updates for values (depending on type interface definition)
+        // handle generic updates for values (depending on type interface definition)
+        if (typeBinding) {
+            typeBinding.handleDifUpdate(value, pointerAddress, update);
+        }
         return true;
     }
     /**
-     * Caches the given pointer value with the given address in the JS side cache.
-     * The pointer must already be wrapped if necessary.
+     * Caches the given reference value with the given address in the JS side cache.
+     * The reference must already be wrapped if necessary.
      */
-    cacheWrappedPointerValue(address, value, observerId) {
+    cacheWrappedReferenceValue(address, originalValue, proxiedValue, observerId, metadata = {}) {
+        const isProxifiedValue = this.isWeakKey(originalValue) &&
+            originalValue !== proxiedValue;
         __classPrivateFieldGet(this, _DIFHandler_cache, "f").set(address, {
-            val: new WeakRef(value),
+            value: new WeakRef(proxiedValue),
+            originalValue: isProxifiedValue ? originalValue : null,
             observerId,
         });
-        // register finalizer to clean up the cache and free the pointer in the runtime
+        __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").set(proxiedValue, {
+            address,
+            customMetadata: metadata,
+        });
+        // store in proxy mapping if original value is not identical to proxied value
+        // and original value is a weak key
+        if (isProxifiedValue) {
+            __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").set(originalValue, new WeakRef(proxiedValue));
+        }
+        // register finalizer to clean up the cache and free the reference in the runtime
         // when the object is garbage collected
         const finalizationRegistry = new FinalizationRegistry((address) => {
+            const originalValue = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address)?.originalValue;
+            // remove from proxy mapping if applicable
+            if (originalValue) {
+                __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").delete(originalValue);
+            }
             __classPrivateFieldGet(this, _DIFHandler_cache, "f").delete(address);
             // remove local observers
             __classPrivateFieldGet(this, _DIFHandler_observers, "f").delete(address);
             // if observer is active, unregister it
             if (observerId !== null) {
-                this.unobservePointerBindDirect(address, observerId);
+                this.unobserveReferenceBindDirect(address, observerId);
             }
         });
-        finalizationRegistry.register(value, address);
+        finalizationRegistry.register(proxiedValue, address);
     }
-    getCachedPointer(address) {
+    getCachedReference(address) {
         const cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address);
         if (cached) {
-            const deref = cached.val.deref();
+            const deref = cached.value.deref();
             if (deref) {
                 return deref;
             }
@@ -511,92 +614,51 @@ export class DIFHandler {
         return undefined;
     }
     /**
-     * Creates a new pointer containg the given JS value.
+     * Creates a new reference containg the given JS value.
      * The returned value is a proxy object that behaves like the original object,
      * but also propagates changes between JS and the DATEX runtime.
+     * If a reference for the given value already exists, an error is thrown.
      */
-    createPointerFromJSValue(value, allowedType = null, mutability = DIFReferenceMutability.Mutable) {
-        const difValue = this.convertJSValueToDIFValue(value);
-        console.log("DIF", difValueContainerToDisplayString(difValue));
-        const ptrAddress = this.createPointer(difValue, allowedType, mutability);
+    createTransparentReference(value, allowedType = null, mutability = DIFReferenceMutability.Mutable) {
+        // if already bound to a reference, return the existing reference proxy (or the value itself)
+        const pointerAddress = this.getPointerAddressForValue(value);
+        if (pointerAddress) {
+            throw new Error(`Value is already bound to a reference ($${pointerAddress}). Cannot create a new reference for the same value.`);
+        }
+        const difValue = this.convertJSValueToDIFValueContainer(value);
+        const ptrAddress = this.createReferenceFromDIFValue(difValue, allowedType, mutability);
         // get inferred allowed type from pointer if not explicitly set
         if (!allowedType) {
             allowedType = __classPrivateFieldGet(this, _DIFHandler_handle, "f").resolve_pointer_address_sync(ptrAddress).allowed_type;
         }
-        return this.initPointer(ptrAddress, value, mutability, allowedType); // TODO: map to correct pointer wrapper type
+        return this.initReference(ptrAddress, value, mutability, allowedType);
     }
-    wrapJSValueInProxy(value, pointerAddress, _type = null) {
-        // primitive values are always wrapped in a Ref proxy
-        if (value === null || value === undefined ||
+    isPrimitiveValue(value) {
+        return value === null || value === undefined ||
             typeof value === "boolean" ||
             typeof value === "number" || typeof value === "bigint" ||
-            typeof value === "string") {
-            return new Ref(value, pointerAddress, this);
-        }
-        else if (value instanceof Map) {
-            return this.proxifyJSMap(value, pointerAddress);
-        }
-        else if (typeof value === "object") {
-            return this.wrapJSObjectInProxy(value);
+            typeof value === "string" || typeof value === "symbol";
+    }
+    isWeakKey(value) {
+        // non-registered symbols are valid WeakKeys
+        return (typeof value === "symbol" && !Symbol.keyFor(value)) ||
+            !this.isPrimitiveValue(value);
+    }
+    /**
+     * Wraps a given JS value in a Ref proxy if necessary.
+     */
+    wrapJSValue(value, pointerAddress, _type = null) {
+        // primitive values are always wrapped in a Ref proxy
+        if (this.isWeakKey(value)) {
+            return value;
         }
         else {
-            return value;
+            return new Ref(value, pointerAddress, this);
         }
     }
     isRef(value) {
         return value instanceof Ref;
     }
-    proxifyJSMap(map, pointerAddress) {
-        const originalSet = map.set;
-        const originalDelete = map.delete;
-        const originalClear = map.clear;
-        // deno-lint-ignore no-this-alias
-        const self = this;
-        Object.defineProperties(map, {
-            set: {
-                value: function (key, value) {
-                    self.updatePointer(pointerAddress, {
-                        kind: DIFUpdateKind.Set,
-                        key: {
-                            kind: "value",
-                            value: self.convertJSValueToDIFValue(key),
-                        },
-                        value: self.convertJSValueToDIFValue(value),
-                    });
-                    return originalSet.call(this, key, value);
-                },
-                configurable: true,
-                writable: true,
-            },
-            delete: {
-                value: function (key) {
-                    self.updatePointer(pointerAddress, {
-                        kind: DIFUpdateKind.Remove,
-                        key: {
-                            kind: "value",
-                            value: self.convertJSValueToDIFValue(key),
-                        },
-                    });
-                    const result = originalDelete.call(this, key);
-                    return result;
-                },
-                configurable: true,
-                writable: true,
-            },
-            clear: {
-                value: function () {
-                    self.updatePointer(pointerAddress, {
-                        kind: DIFUpdateKind.Clear,
-                    });
-                    const result = originalClear.call(this);
-                    return result;
-                },
-                configurable: true,
-                writable: true,
-            },
-        });
-        return map;
-    }
     wrapJSObjectInProxy(value) {
         // deno-lint-ignore no-this-alias
         const self = this;
@@ -624,22 +686,68 @@ export class DIFHandler {
             },
         });
     }
-    /// Returns the pointer address for the given value if it is already cached, or null otherwise.
-    /// TODO: optimize by using a reverse map or direct Symbols on the objects
-    /// But this is probably not important for normal use cases
+    /**
+     * Returns the pointer address for the given value if it is already cached, or null otherwise.
+     */
     getPointerAddressForValue(value) {
-        for (const [address, entry] of __classPrivateFieldGet(this, _DIFHandler_cache, "f")) {
-            const deref = entry.val.deref();
-            if (deref === value) {
-                return address;
+        return __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").get(value)?.address || null;
+    }
+    /**
+     * Returns the reference metadata for the given value if it is registered.
+     * The caller must ensure that the correct type M is used and the reference is already registered.
+     * If the reference is not found, an error is thrown.
+     */
+    getReferenceMetadataUnsafe(value) {
+        const metadata = this.tryGetReferenceMetadata(value);
+        if (!metadata) {
+            panic("Reference metadata not found for the given value");
+        }
+        return metadata;
+    }
+    /**
+     * Returns the reference metadata for the given value if it is registered, or null otherwise.
+     */
+    tryGetReferenceMetadata(value) {
+        return (__classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").get(value) ??
+            __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").get(__classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").get(value)?.deref()) ??
+            null);
+    }
+    isReference(value) {
+        return __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").has(value) ||
+            __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").has(value);
+    }
+    getReferenceProxy(value) {
+        const reference = __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").get(value);
+        if (reference) {
+            return value;
+        }
+        const proxyRef = __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").get(value);
+        if (proxyRef) {
+            const deref = proxyRef.deref();
+            if (deref) {
+                return deref;
+            }
+            else {
+                panic("Reference proxy has been garbage collected");
             }
         }
-        return null;
+        else {
+            return null;
+        }
     }
     /**
-     * Converts a given JS value to its DIFValue representation.
+     * Converts a given JS value to its DIFValueContainer representation.
+     * This method can be called statically or with an instance to use the instance's DIFHandler context.
+     * NOTE: When called statically, there is no cache for already registered references, meaning that new references will be created
+     * for the same object each time this method is called.
      */
-    convertJSValueToDIFValue(value) {
+    static convertJSValueToDIFValueContainer(value, difHandlerInstance) {
+        // if the value is a registered reference, return its address
+        const existingReference = difHandlerInstance &&
+            difHandlerInstance.tryGetReferenceMetadata(value);
+        if (existingReference) {
+            return existingReference.address;
+        }
         // assuming core values
         // TODO: handle custom types
         if (value === null) {
@@ -647,6 +755,18 @@ export class DIFHandler {
                 value: null,
             };
         }
+        else if (value === undefined) {
+            return {
+                type: {
+                    kind: DIFTypeDefinitionKind.ImplType,
+                    def: [
+                        CoreTypeAddress.null,
+                        [JsLibTypeAddress.undefined],
+                    ],
+                },
+                value: null,
+            };
+        }
         else if (typeof value === "boolean") {
             return {
                 value,
@@ -659,7 +779,7 @@ export class DIFHandler {
         }
         else if (typeof value === "bigint") {
             return {
-                type: CoreTypeAddress.integer_big,
+                type: CoreTypeAddress.integer_ibig,
                 value: value.toString(), // convert bigint to string for DIFValue
             };
         }
@@ -676,13 +796,14 @@ export class DIFHandler {
         }
         else if (Array.isArray(value)) {
             return {
-                value: value.map((v) => this.convertJSValueToDIFValue(v)),
+                value: value.map((v) => this.convertJSValueToDIFValueContainer(v)),
             };
         }
         else if (value instanceof Map) {
-            const map = value.entries().map(([k, v]) => [
-                this.convertJSValueToDIFValue(k),
-                this.convertJSValueToDIFValue(v),
+            const map = value
+                .entries().map(([k, v]) => [
+                this.convertJSValueToDIFValueContainer(k),
+                this.convertJSValueToDIFValueContainer(v),
             ]).toArray();
             return {
                 type: CoreTypeAddress.map,
@@ -692,14 +813,112 @@ export class DIFHandler {
         else if (typeof value === "object") {
             const map = {};
             for (const [key, val] of Object.entries(value)) {
-                map[key] = this.convertJSValueToDIFValue(val);
+                map[key] = this.convertJSValueToDIFValueContainer(val);
             }
             return {
-                type: CoreTypeAddress.map,
                 value: map,
             };
         }
         throw new Error("Unsupported type for conversion to DIFValue");
     }
+    /**
+     * Instance method wrapper for static convertJSValueToDIFValueContainer
+     * Converts a given JS value to its DIFValueContainer representation.
+     * @param value
+     */
+    convertJSValueToDIFValueContainer(value) {
+        return DIFHandler.convertJSValueToDIFValueContainer(value, this);
+    }
+    /** DIF update handler utilities */
+    /**
+     * Triggers a 'set' update for the given pointer address, key and value.
+     */
+    triggerSet(pointerAddress, key, value) {
+        const difKey = this.convertJSValueToDIFValueContainer(key);
+        const difValue = this.convertJSValueToDIFValueContainer(value);
+        const update = {
+            kind: DIFUpdateKind.Set,
+            key: { kind: "value", value: difKey },
+            value: difValue,
+        };
+        console.log("Triggering set update", update);
+        this.updateReference(pointerAddress, update);
+    }
+    /**
+     * Triggers a 'set' update for the given pointer address, index and value.
+     */
+    triggerIndexSet(pointerAddress, index, value) {
+        if (typeof index !== "bigint" && !Number.isInteger(index)) {
+            throw new Error("Index must be a non-negative integer");
+        }
+        const difValue = this.convertJSValueToDIFValueContainer(value);
+        const update = {
+            kind: DIFUpdateKind.Set,
+            key: { kind: "index", value: Number(index) },
+            value: difValue,
+        };
+        console.log("Triggering index set update", update);
+        this.updateReference(pointerAddress, update);
+    }
+    /**
+     * Triggers an 'append' update for the given pointer address and value.
+     */
+    triggerAppend(pointerAddress, value) {
+        const difValue = this.convertJSValueToDIFValueContainer(value);
+        const update = {
+            kind: DIFUpdateKind.Append,
+            value: difValue,
+        };
+        console.log("Triggering append update", update);
+        this.updateReference(pointerAddress, update);
+    }
+    /**
+     * Triggers a 'replace' update for the given pointer address and key.
+     */
+    triggerReplace(pointerAddress, value) {
+        const difValue = this.convertJSValueToDIFValueContainer(value);
+        const update = {
+            kind: DIFUpdateKind.Replace,
+            value: difValue,
+        };
+        console.log("Triggering replace update", update);
+        this.updateReference(pointerAddress, update);
+    }
+    /**
+     * Triggers a 'delete' update for the given pointer address and key.
+     */
+    triggerDelete(pointerAddress, key) {
+        const difKey = this.convertJSValueToDIFValueContainer(key);
+        const update = {
+            kind: DIFUpdateKind.Delete,
+            key: { kind: "value", value: difKey },
+        };
+        console.log("Triggering delete update", update);
+        this.updateReference(pointerAddress, update);
+    }
+    /**
+     * Triggers a 'clear' update for the given pointer address.
+     */
+    triggerClear(pointerAddress) {
+        const update = {
+            kind: DIFUpdateKind.Clear,
+        };
+        console.log("Triggering clear update", update);
+        this.updateReference(pointerAddress, update);
+    }
+    /**
+     * Triggers a 'list splice' update for the given pointer address.
+     */
+    triggerListSplice(pointerAddress, start, deleteCount, items) {
+        const difItems = items.map((item) => this.convertJSValueToDIFValueContainer(item));
+        const update = {
+            kind: DIFUpdateKind.ListSplice,
+            start,
+            delete_count: deleteCount,
+            items: difItems,
+        };
+        console.log("Triggering list splice update", update);
+        this.updateReference(pointerAddress, update);
+    }
 }
-_DIFHandler_runtime = new WeakMap(), _DIFHandler_handle = new WeakMap(), _DIFHandler_transceiver_id = new WeakMap(), _DIFHandler_cache = new WeakMap(), _DIFHandler_observers = new WeakMap();
+_DIFHandler_runtime = new WeakMap(), _DIFHandler_handle = new WeakMap(), _DIFHandler_transceiver_id = new WeakMap(), _DIFHandler_cache = new WeakMap(), _DIFHandler_proxyMapping = new WeakMap(), _DIFHandler_referenceMetadata = new WeakMap(), _DIFHandler_observers = new WeakMap(), _DIFHandler_type_registry = new WeakMap();