@divmain/jdm-asm 0.2.0

package/src/runtime/arrays.ts

@@ -0,0 +1,579 @@
+// assembly/runtime/arrays.ts (AssemblyScript)
+// Array handling for WASM linear memory
+
+import { heapAlloc } from './memory';
+import { writeString, readString } from './strings';
+import {
+  Value,
+  TYPE_NULL,
+  TYPE_BOOL,
+  TYPE_INT,
+  TYPE_FLOAT,
+  TYPE_STRING,
+  TYPE_ARRAY,
+  TYPE_OBJECT,
+} from './values';
+
+// ============================================================================
+// Array Constants
+// ============================================================================
+
+/**
+ * Size of the length field header in bytes for arrays.
+ */
+export const ARRAY_LENGTH_SIZE: usize = 4;
+
+/**
+ * Size of each F64 element in bytes.
+ */
+export const F64_ELEMENT_SIZE: usize = 8;
+
+/**
+ * Size of each element pointer (usize) in bytes for generic arrays.
+ */
+export const ELEMENT_PTR_SIZE: usize = 4;
+
+/**
+ * Size of the type tag field in bytes for serialized Values.
+ */
+export const VALUE_TYPE_SIZE: usize = 4;
+
+/**
+ * Size of the bool field in bytes for serialized Values.
+ */
+export const VALUE_BOOL_SIZE: usize = 1;
+
+/**
+ * Size of the int field in bytes for serialized Values.
+ */
+export const VALUE_INT_SIZE: usize = 8;
+
+/**
+ * Size of the float field in bytes for serialized Values.
+ */
+export const VALUE_FLOAT_SIZE: usize = 8;
+
+/**
+ * Size of the pointer field in bytes for serialized Values (string, array, object).
+ */
+export const VALUE_PTR_SIZE: usize = 4;
+
+// ============================================================================
+// F64 Array Handling
+// ============================================================================
+
+/**
+ * Write a numeric array (Array<f64>) to memory.
+ *
+ * The array is stored in the format: [length: u32][f64 elements...]
+ *
+ * Memory is allocated from the runtime heap using heapAlloc().
+ * The memory is aligned to 8 bytes for efficient access.
+ *
+ * @param arr - The array to write to memory
+ * @returns Pointer to the allocated array data, or 0 if allocation failed
+ */
+export function writeF64Array(arr: Array<f64>): usize {
+  const len = <u32>arr.length;
+
+  // Calculate total size: length field (4 bytes) + f64 elements (8 bytes each)
+  const totalSize = ARRAY_LENGTH_SIZE + <usize>len * F64_ELEMENT_SIZE;
+
+  // Allocate memory from heap
+  const ptr = heapAlloc(totalSize);
+
+  // Return 0 if allocation failed
+  if (ptr == 0) {
+    return 0;
+  }
+
+  // Write length
+  store<u32>(ptr, len);
+
+  // Write each f64 element
+  for (let i: u32 = 0; i < len; i++) {
+    store<f64>(ptr + ARRAY_LENGTH_SIZE + <usize>i * F64_ELEMENT_SIZE, arr[i]);
+  }
+
+  return ptr;
+}
+
+/**
+ * Read a numeric array (Array<f64>) from memory.
+ *
+ * The array must be stored in the format: [length: u32][f64 elements...]
+ *
+ * @param ptr - Pointer to the array data in memory
+ * @returns The read array, or empty array if pointer is null
+ */
+export function readF64Array(ptr: usize): Array<f64> {
+  // Return empty array for null pointer
+  if (ptr == 0) {
+    return new Array<f64>();
+  }
+
+  // Read length
+  const len = load<u32>(ptr);
+
+  // Create array and populate it
+  const result = new Array<f64>(len);
+  for (let i: u32 = 0; i < len; i++) {
+    result[i] = load<f64>(ptr + ARRAY_LENGTH_SIZE + <usize>i * F64_ELEMENT_SIZE);
+  }
+
+  return result;
+}
+
+/**
+ * Calculate the size in bytes needed to store an F64 array in memory.
+ *
+ * @param len - The length of the array
+ * @returns The total size in bytes including the length header
+ */
+export function getF64ArraySize(len: usize): usize {
+  return ARRAY_LENGTH_SIZE + len * F64_ELEMENT_SIZE;
+}
+
+// ============================================================================
+// Value Serialization
+// ============================================================================
+
+/**
+ * Write a Value to memory and return its pointer.
+ *
+ * For complex types (string/array/object), storing the actual data inline would make
+ * Value structs variable-sized and unpredictable. Storing pointers provides fixed-size
+ * Values (predictable offsets) while allowing arbitrary complex data on the heap.
+ *
+ * The Value is stored in the format: [type: u32][value_data...]
+ *
+ * For primitive types (bool, int, float), value_data is the actual value.
+ * For complex types (string, array, object), value_data is a pointer to the data.
+ *
+ * Memory is allocated from the runtime heap using heapAlloc().
+ *
+ * @param v - The Value to write to memory
+ * @returns Pointer to the allocated Value data, or 0 if allocation failed
+ */
+export function writeValue(v: Value): usize {
+  const type = v.type;
+
+  if (type == TYPE_NULL) {
+    // For null, just write the type tag
+    const ptr = heapAlloc(VALUE_TYPE_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    return ptr;
+  } else if (type == TYPE_BOOL) {
+    // Format: [type: u32][bool: u8]
+    const ptr = heapAlloc(VALUE_TYPE_SIZE + VALUE_BOOL_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    store<u8>(ptr + VALUE_TYPE_SIZE, v.boolVal ? 1 : 0);
+    return ptr;
+  } else if (type == TYPE_INT) {
+    // Format: [type: u32][int: i64]
+    const ptr = heapAlloc(VALUE_TYPE_SIZE + VALUE_INT_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    store<i64>(ptr + VALUE_TYPE_SIZE, v.intVal);
+    return ptr;
+  } else if (type == TYPE_FLOAT) {
+    // Format: [type: u32][float: f64]
+    const ptr = heapAlloc(VALUE_TYPE_SIZE + VALUE_FLOAT_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    store<f64>(ptr + VALUE_TYPE_SIZE, v.floatVal);
+    return ptr;
+  } else if (type == TYPE_STRING) {
+    // Format: [type: u32][stringPtr: u32]
+    const ptr = heapAlloc(VALUE_TYPE_SIZE + VALUE_PTR_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    const stringVal = v.stringVal != null ? v.stringVal! : '';
+    const stringPtr = writeString(stringVal);
+    store<u32>(ptr + VALUE_TYPE_SIZE, stringPtr);
+    return ptr;
+  } else if (type == TYPE_ARRAY) {
+    // Format: [type: u32][arrayPtr: u32]
+    const ptr = heapAlloc(VALUE_TYPE_SIZE + VALUE_PTR_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    const arrayVal = v.arrayVal != null ? v.arrayVal! : new Array<Value>();
+    const arrayPtr = writeValueArray(arrayVal);
+    store<u32>(ptr + VALUE_TYPE_SIZE, arrayPtr);
+    return ptr;
+  } else if (type == TYPE_OBJECT) {
+    // Format: [type: u32][objectPtr: u32]
+    const ptr = heapAlloc(VALUE_TYPE_SIZE + VALUE_PTR_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, type);
+    const objectVal = v.objectVal != null ? v.objectVal! : new Map<string, Value>();
+    const objectPtr = writeValueMap(objectVal);
+    store<u32>(ptr + VALUE_TYPE_SIZE, objectPtr);
+    return ptr;
+  }
+
+  return 0; // Unknown type
+}
+
+/**
+ * Read a Value from memory.
+ *
+ * The Value must be stored in the format: [type: u32][value_data...]
+ *
+ * @param ptr - Pointer to the Value data in memory
+ * @returns The read Value, or null if pointer is invalid
+ */
+export function readValue(ptr: usize): Value {
+  // Return null for null pointer
+  if (ptr == 0) {
+    return Value.Null();
+  }
+
+  // Read type
+  const type = load<u32>(ptr);
+
+  if (type == TYPE_NULL) {
+    return Value.Null();
+  } else if (type == TYPE_BOOL) {
+    const boolVal = load<u8>(ptr + VALUE_TYPE_SIZE) != 0;
+    return Value.Bool(boolVal);
+  } else if (type == TYPE_INT) {
+    const intVal = load<i64>(ptr + VALUE_TYPE_SIZE);
+    return Value.Int(intVal);
+  } else if (type == TYPE_FLOAT) {
+    const floatVal = load<f64>(ptr + VALUE_TYPE_SIZE);
+    return Value.Float(floatVal);
+  } else if (type == TYPE_STRING) {
+    const stringPtr = load<u32>(ptr + VALUE_TYPE_SIZE);
+    const stringVal = readString(stringPtr);
+    return Value.String(stringVal);
+  } else if (type == TYPE_ARRAY) {
+    const arrayPtr = load<u32>(ptr + VALUE_TYPE_SIZE);
+    const arrayVal = readValueArray(arrayPtr);
+    return Value.Array(arrayVal);
+  } else if (type == TYPE_OBJECT) {
+    const objectPtr = load<u32>(ptr + VALUE_TYPE_SIZE);
+    const objectVal = readValueMap(objectPtr);
+    return Value.Object(objectVal);
+  }
+
+  return Value.Null(); // Unknown type
+}
+
+// ============================================================================
+// Value Array Handling
+// ============================================================================
+
+// Format marker for flat numeric arrays (high bit set in length field)
+const FLAT_ARRAY_MARKER: u32 = 0x80000000;
+
+/**
+ * Detect if an array contains only floats/ints (homogeneous numeric array).
+ *
+ * @param arr - The array to check
+ * @returns true if all elements are TYPE_FLOAT or TYPE_INT, false otherwise
+ */
+function isHomogeneousNumericArray(arr: Array<Value>): bool {
+  const len = arr.length;
+  if (len == 0) return false;
+
+  for (let i = 0; i < len; i++) {
+    const type = arr[i].type;
+    if (type != TYPE_FLOAT && type != TYPE_INT) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Write a homogeneous numeric array in flat format.
+ *
+ * Format: [length | FLAT_ARRAY_MARKER: u32][f64 elements...]
+ *
+ * The high bit of the length field is set to indicate flat format.
+ * This specialized format avoids individual Value allocations and type tags,
+ * reducing memory overhead and fragmentation significantly.
+ *
+ * @param arr - The array to write (must be homogeneous numeric)
+ * @returns Pointer to the allocated array data, or 0 if allocation failed
+ */
+function writeHomogeneousNumericArray(arr: Array<Value>): usize {
+  const len = <u32>arr.length;
+
+  // Calculate total size: length with marker (4) + f64 elements (8 each)
+  const totalSize = ARRAY_LENGTH_SIZE + <usize>len * F64_ELEMENT_SIZE;
+
+  // Single allocation for entire array
+  const ptr = heapAlloc(totalSize);
+  if (ptr == 0) return 0;
+
+  // Write length with high bit set to indicate flat format
+  store<u32>(ptr, len | FLAT_ARRAY_MARKER);
+
+  // Write all numeric values as f64 directly (no Value wrapping)
+  for (let i: u32 = 0; i < len; i++) {
+    const val = arr[i];
+    const numVal = val.type == TYPE_FLOAT ? val.floatVal : <f64>val.intVal;
+    store<f64>(ptr + ARRAY_LENGTH_SIZE + <usize>i * F64_ELEMENT_SIZE, numVal);
+  }
+
+  return ptr;
+}
+
+/**
+ * Read a homogeneous numeric array from flat format.
+ *
+ * Format: [length | FLAT_ARRAY_MARKER: u32][f64 elements...]
+ *
+ * @param ptr - Pointer to the array data in memory
+ * @param len - The actual length (without the marker bit)
+ * @returns The read array of Value objects
+ */
+function readHomogeneousNumericArray(ptr: usize, len: u32): Array<Value> {
+  const result = new Array<Value>(len);
+
+  // Read all f64 values and wrap them as Value.Float
+  for (let i: u32 = 0; i < len; i++) {
+    const numVal = load<f64>(ptr + ARRAY_LENGTH_SIZE + <usize>i * F64_ELEMENT_SIZE);
+    result[i] = Value.Float(numVal);
+  }
+
+  return result;
+}
+
+/**
+ * Write a Value array to memory.
+ *
+ * The array is stored in one of two formats:
+ *
+ * 1. Flat numeric format (for homogeneous numeric arrays):
+ *    [length | FLAT_ARRAY_MARKER: u32][f64 elements...]
+ *
+ * 2. Generic format (for mixed-type arrays):
+ *    [length: u32][Value pointers...]
+ *
+ * Homogeneous numeric arrays are detected and serialized using a flat format
+ * that eliminates per-element allocations and type tags, significantly reducing
+ * memory overhead (from ~16+ bytes per element to 8 bytes) and fragmentation.
+ * The flat format is indicated by setting the high bit of the length field.
+ *
+ * Memory is allocated from the runtime heap using heapAlloc().
+ *
+ * @param arr - The array to write to memory
+ * @returns Pointer to the allocated array data, or 0 if allocation failed
+ */
+export function writeValueArray(arr: Array<Value>): usize {
+  const len = <u32>arr.length;
+
+  // Empty array (generic format)
+  if (len == 0) {
+    const ptr = heapAlloc(ARRAY_LENGTH_SIZE);
+    if (ptr == 0) return 0;
+    store<u32>(ptr, 0);
+    return ptr;
+  }
+
+  // Optimization: detect homogeneous numeric arrays and use flat format
+  if (isHomogeneousNumericArray(arr)) {
+    return writeHomogeneousNumericArray(arr);
+  }
+
+  // Generic path: mixed-type array
+  // Format: [length: u32][Value pointers...]
+  const totalSize = ARRAY_LENGTH_SIZE + <usize>len * ELEMENT_PTR_SIZE;
+
+  const ptr = heapAlloc(totalSize);
+  if (ptr == 0) return 0;
+
+  store<u32>(ptr, len);
+
+  // Write each Value pointer
+  for (let i: u32 = 0; i < len; i++) {
+    const valuePtr = writeValue(arr[i]);
+    store<u32>(ptr + ARRAY_LENGTH_SIZE + <usize>i * ELEMENT_PTR_SIZE, valuePtr);
+  }
+
+  return ptr;
+}
+
+/**
+ * Read a Value array from memory.
+ *
+ * Handles both flat numeric format and generic format:
+ *
+ * 1. Flat numeric format: [length | FLAT_ARRAY_MARKER: u32][f64 elements...]
+ * 2. Generic format: [length: u32][Value pointers...]
+ *
+ * The format is detected by checking if the high bit of the length is set.
+ *
+ * @param ptr - Pointer to the array data in memory
+ * @returns The read array, or empty array if pointer is null
+ */
+export function readValueArray(ptr: usize): Array<Value> {
+  // Return empty array for null pointer
+  if (ptr == 0) {
+    return new Array<Value>();
+  }
+
+  // Read length (with potential marker bit)
+  const lengthField = load<u32>(ptr);
+
+  // Check if this is a flat numeric array (high bit set)
+  if ((lengthField & FLAT_ARRAY_MARKER) != 0) {
+    // Flat numeric format - extract actual length
+    const len = lengthField & ~FLAT_ARRAY_MARKER;
+    return readHomogeneousNumericArray(ptr, len);
+  }
+
+  // Generic format - length is used as-is
+  const len = lengthField;
+
+  // Empty array
+  if (len == 0) {
+    return new Array<Value>();
+  }
+
+  // Read array of Value pointers
+  const result = new Array<Value>(len);
+  for (let i: u32 = 0; i < len; i++) {
+    const valuePtr = load<u32>(ptr + ARRAY_LENGTH_SIZE + <usize>i * ELEMENT_PTR_SIZE);
+    result[i] = readValue(valuePtr);
+  }
+
+  return result;
+}
+
+/**
+ * Calculate the size in bytes needed to store a Value array in memory.
+ *
+ * Note: This calculates the size for the generic format.
+ * For flat numeric arrays, the actual size may be different.
+ *
+ * @param len - The length of the array
+ * @returns The total size in bytes including the length header (but not the individual Values)
+ */
+export function getValueArraySize(len: usize): usize {
+  return ARRAY_LENGTH_SIZE + len * ELEMENT_PTR_SIZE;
+}
+
+// ============================================================================
+// Value Map (Object) Handling
+// ============================================================================
+
+/**
+ * Write a Value map to memory.
+ *
+ * The map is stored in the format: [length: u32][keyPtr1: u32][valuePtr1: u32][keyPtr2: u32][valuePtr2: u32]...
+ *
+ * Keys are always strings and written to memory separately using writeString().
+ * Values are serialized using writeValue() separately.
+ *
+ * Memory is allocated from the runtime heap using heapAlloc().
+ *
+ * JavaScript object property order is insertion-ordered (ES2015+), so we must preserve
+ * order when serializing to match JS semantics and ensure deterministic output.
+ *
+ * @param map - The map to write to memory
+ * @returns Pointer to the allocated map data, or 0 if allocation failed
+ */
+export function writeValueMap(map: Map<string, Value>): usize {
+  const len = <u32>map.size;
+
+  // Calculate total size: length field (4 bytes) + key/value pairs (8 bytes each)
+  const totalSize = ARRAY_LENGTH_SIZE + <usize>len * 2 * ELEMENT_PTR_SIZE;
+
+  // Allocate memory from heap
+  const ptr = heapAlloc(totalSize);
+
+  // Return 0 if allocation failed
+  if (ptr == 0) {
+    return 0;
+  }
+
+  // Write length
+  store<u32>(ptr, len);
+
+  // Get keys and write each key/value pair
+  const keys = map.keys();
+  for (let i: u32 = 0; i < <u32>keys.length; i++) {
+    const key = keys[i];
+    const offset = ptr + ARRAY_LENGTH_SIZE + <usize>i * 2 * ELEMENT_PTR_SIZE;
+
+    // Write key pointer
+    const keyPtr = writeString(key);
+    store<u32>(offset, keyPtr);
+
+    // Write value pointer
+    const valuePtr = writeValue(map.get(key));
+    store<u32>(offset + ELEMENT_PTR_SIZE, valuePtr);
+  }
+
+  return ptr;
+}
+
+/**
+ * Read a Value map from memory.
+ *
+ * The map must be stored in the format: [length: u32][keyPtr1: u32][valuePtr1: u32][keyPtr2: u32][valuePtr2: u32]...
+ *
+ * @param ptr - Pointer to the map data in memory
+ * @returns The read map, or empty map if pointer is null
+ */
+export function readValueMap(ptr: usize): Map<string, Value> {
+  // Return empty map for null pointer
+  if (ptr == 0) {
+    return new Map<string, Value>();
+  }
+
+  // Read length
+  const len = load<u32>(ptr);
+
+  // Create map and populate it
+  const result = new Map<string, Value>();
+  for (let i: u32 = 0; i < len; i++) {
+    const keyPtr = load<u32>(ptr + ARRAY_LENGTH_SIZE + <usize>i * 2 * ELEMENT_PTR_SIZE);
+    const valuePtr = load<u32>(
+      ptr + ARRAY_LENGTH_SIZE + <usize>i * 2 * ELEMENT_PTR_SIZE + ELEMENT_PTR_SIZE,
+    );
+
+    const key = readString(keyPtr);
+    const value = readValue(valuePtr);
+
+    result.set(key, value);
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Array Utility Functions
+// ============================================================================
+
+/**
+ * Calculate the length of an array from its pointer in memory.
+ *
+ * @param ptr - Pointer to the array data in memory
+ * @returns The length of the array, or 0 if null
+ */
+export function getArrayLength(ptr: usize): usize {
+  if (ptr == 0) {
+    return 0;
+  }
+  return load<u32>(ptr);
+}
+
+/**
+ * Check if an array pointer points to an empty array.
+ *
+ * @param ptr - Pointer to the array data in memory
+ * @returns true if the array is empty or pointer is null, false otherwise
+ */
+export function isArrayEmpty(ptr: usize): bool {
+  if (ptr == 0) {
+    return true;
+  }
+  return load<u32>(ptr) == 0;
+}