Memory Management

/**
 * Copies a string's value from the module's memory to a JavaScript string
 * @param ptr - Pointer to the string in WebAssembly memory (must not be zero)
 * @returns The JavaScript string value
 */
__getString(ptr: number): string;

/**
 * Allocates a new string in the module's memory and returns a pointer to it
 * @param str - The JavaScript string to allocate
 * @returns Pointer to the allocated string in WebAssembly memory
 * @requires --exportRuntime for access to __new
 */
__newString(str: string): number;

// Create a string in WebAssembly memory
const strPtr = exports.__newString("Hello, AssemblyScript!");

// Read the string back
const result = exports.__getString(strPtr);
console.log(result); // "Hello, AssemblyScript!"

// Handle special characters and Unicode
const unicodePtr = exports.__newString("Hello 🌍! ∀ ∁ ∂ ∃");
const unicode = exports.__getString(unicodePtr);

/**
 * Copies an ArrayBuffer's value from the module's memory to a JavaScript buffer
 * @param ptr - Pointer to the ArrayBuffer in WebAssembly memory (must not be zero)
 * @returns The JavaScript ArrayBuffer copy
 */
__getArrayBuffer(ptr: number): ArrayBuffer;

/**
 * Allocates a new ArrayBuffer in the module's memory and returns a pointer to it
 * @param buf - The JavaScript ArrayBuffer to allocate
 * @returns Pointer to the allocated ArrayBuffer in WebAssembly memory
 * @requires --exportRuntime for access to __new
 */
__newArrayBuffer(buf: ArrayBuffer): number;

// Create an ArrayBuffer in WebAssembly memory
const input = new Uint8Array([1, 2, 3, 4]);
const bufPtr = exports.__newArrayBuffer(input.buffer);

// Read the ArrayBuffer back
const output = new Uint8Array(exports.__getArrayBuffer(bufPtr));
console.log(output); // Uint8Array [1, 2, 3, 4]

/**
 * Copies an array's values from the module's memory to a JavaScript array
 * Infers the array type from RTTI
 * @param ptr - Pointer to the array in WebAssembly memory (must not be zero)
 * @returns JavaScript array with copied values
 */
__getArray(ptr: number): number[];

/**
 * Allocates a new array in the module's memory and returns a pointer to it
 * @param id - The unique runtime id of the respective array class (e.g., Int32Array_ID)
 * @param valuesOrCapacity - Array values to copy, or capacity for pre-allocation
 * @returns Pointer to the allocated array in WebAssembly memory
 * @requires --exportRuntime for access to __new
 */
__newArray(id: number, valuesOrCapacity?: Array<number> | ArrayBufferView | number): number;

/**
 * Gets a live view on an array's values in the module's memory
 * Infers the array type from RTTI
 * @param ptr - Pointer to the array in WebAssembly memory (must not be zero)
 * @returns Live TypedArray view (changes affect WebAssembly memory)
 * @warning View may become invalid if array grows or is garbage collected
 */
__getArrayView(ptr: number): ArrayBufferView;

// Create array with values
const arr = [1, 2, 3, 4, 5, 0x80000000 | 0];
const ref = exports.__newArray(exports.INT32ARRAY_ID, arr);

// Copy values to JavaScript array
const values = exports.__getArray(ref);
console.log(values); // [1, 2, 3, 4, 5, -2147483648]

// Get live view for direct memory access
const view = exports.__getArrayView(ref);
console.log(view); // Int32Array view

// Create empty array with capacity
const emptyRef = exports.__newArray(exports.ARRAYI32_ID, 32);
const emptyValues = exports.__getArray(emptyRef);
console.log(emptyValues.length); // 32

/**
 * Copies an Int8Array's values from the module's memory
 */
__getInt8Array(ptr: number): Int8Array;

/**
 * Copies a Uint8Array's values from the module's memory  
 */
__getUint8Array(ptr: number): Uint8Array;

/**
 * Copies a Uint8ClampedArray's values from the module's memory
 */
__getUint8ClampedArray(ptr: number): Uint8ClampedArray;

/**
 * Copies an Int16Array's values from the module's memory
 */
__getInt16Array(ptr: number): Int16Array;

/**
 * Copies a Uint16Array's values from the module's memory
 */
__getUint16Array(ptr: number): Uint16Array;

/**
 * Copies an Int32Array's values from the module's memory
 */
__getInt32Array(ptr: number): Int32Array;

/**
 * Copies a Uint32Array's values from the module's memory
 */
__getUint32Array(ptr: number): Uint32Array;

/**
 * Copies a Float32Array's values from the module's memory
 */
__getFloat32Array(ptr: number): Float32Array;

/**
 * Copies a Float64Array's values from the module's memory
 */
__getFloat64Array(ptr: number): Float64Array;

/**
 * Copies an Int64Array's values from the module's memory (BigInt support required)
 */
__getInt64Array?(ptr: number): BigInt64Array;

/**
 * Copies a Uint64Array's values from the module's memory (BigInt support required)  
 */
__getUint64Array?(ptr: number): BigUint64Array;

/**
 * Gets a live view on an Int8Array's values in the module's memory
 */
__getInt8ArrayView(ptr: number): Int8Array;

/**
 * Gets a live view on a Uint8Array's values in the module's memory
 */
__getUint8ArrayView(ptr: number): Uint8Array;

/**
 * Gets a live view on a Uint8ClampedArray's values in the module's memory
 */
__getUint8ClampedArrayView(ptr: number): Uint8ClampedArray;

/**
 * Gets a live view on an Int16Array's values in the module's memory
 */
__getInt16ArrayView(ptr: number): Int16Array;

/**
 * Gets a live view on a Uint16Array's values in the module's memory
 */
__getUint16ArrayView(ptr: number): Uint16Array;

/**
 * Gets a live view on an Int32Array's values in the module's memory
 */
__getInt32ArrayView(ptr: number): Int32Array;

/**
 * Gets a live view on a Uint32Array's values in the module's memory
 */
__getUint32ArrayView(ptr: number): Uint32Array;

/**
 * Gets a live view on a Float32Array's values in the module's memory
 */
__getFloat32ArrayView(ptr: number): Float32Array;

/**
 * Gets a live view on a Float64Array's values in the module's memory
 */
__getFloat64ArrayView(ptr: number): Float64Array;

/**
 * Gets a live view on an Int64Array's values in the module's memory (BigInt support required)
 */
__getInt64ArrayView?(ptr: number): BigInt64Array;

/**
 * Gets a live view on a Uint64Array's values in the module's memory (BigInt support required)
 */
__getUint64ArrayView?(ptr: number): BigUint64Array;

// Work with specific typed arrays
const values = [0, 255, 127];
const arr = new Uint8Array(values);
const ref = exports.__newArray(exports.UINT8ARRAY_ID, arr);

// Get typed array copy
const uint8Copy = exports.__getUint8Array(ref);
console.log(uint8Copy); // Uint8Array [0, 255, 127]

// Get live view
const uint8View = exports.__getUint8ArrayView(ref);
console.log(uint8View); // Live Uint8Array view

// Distinguish between signed and unsigned
const signedValues = [0, 0xFFFF, -0x00FF];
const signedRef = exports.__newArray(exports.INT16ARRAY_ID, new Int16Array(signedValues));
const signedArray = exports.__getInt16Array(signedRef);
console.log(signedArray); // Int16Array [0, -1, -255]

/**
 * Gets a callable function object from the module's memory containing its table index
 * @param ptr - Pointer containing table index (must not be zero)
 * @returns Callable function or null if invalid
 * @requires --exportTable for access to function table
 */
__getFunction(ptr: number): ((...args: unknown[]) => unknown) | null;

// Get function from pointer
const funcPtr = exports.getVaraddFunc(); // Returns function pointer
const addFunc = exports.__getFunction(funcPtr);

if (addFunc) {
  const result = addFunc(1, 2);
  console.log(result); // 3
}

// Handle invalid pointers
const invalidFunc = exports.__getFunction(0);
console.log(invalidFunc); // null

/**
 * Allocates an instance of the class represented by the specified id
 * @param size - Size in bytes to allocate
 * @param id - Runtime type id of the class
 * @returns Pointer to allocated memory
 * @requires --exportRuntime
 */
__new(size: number, id: number): number;

/**
 * Pins a managed object externally, preventing it from becoming garbage collected
 * @param ptr - Pointer to the object to pin
 * @returns The same pointer value
 * @requires --exportRuntime
 */
__pin(ptr: number): number;

/**
 * Unpins a managed object externally, allowing it to become garbage collected
 * @param ptr - Pointer to the object to unpin
 * @requires --exportRuntime
 */
__unpin(ptr: number): void;

/**
 * Performs a full garbage collection cycle
 * @param incremental - Whether to perform incremental collection (optional)
 * @requires --exportRuntime
 */
__collect(incremental?: boolean): void;

// Pin an object to prevent garbage collection
const strPtr = exports.__newString("test");
exports.__pin(strPtr);

// Use the object...
const result = exports.someFunction(strPtr);

// Unpin when done
exports.__unpin(strPtr);

// Force garbage collection
exports.__collect();

// Working with custom classes
const fooPtr = exports.__pin(exports.getFoo()); // Pin returned object
const foo = exports.Foo.wrap(fooPtr);          // Wrap in JavaScript class
const result = foo.getString();                // Call method
exports.__unpin(fooPtr);                       // Unpin when done

// Safer: Copy array values
const values = exports.__getArray(arrayPtr);

// Riskier: Direct memory view (faster but potentially unsafe)
const view = exports.__getArrayView(arrayPtr);
// Use immediately and don't store long-term references

// Pin before storing references
const objPtr = exports.__pin(exports.createObject());
// Store objPtr somewhere...

// Later, when done with the object
exports.__unpin(objPtr);