@divmain/jdm-asm 0.2.0 → 0.2.3

package/src/runtime/arrays.ts

@@ -1,579 +0,0 @@
-// 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;
-}