getPropNames, QuicJSIterator

Author: justjake

c/interface.c

@@ -591,6 +591,22 @@ void QTS_DefineProp(JSContext *ctx, JSValueConst *this_val, JSValueConst *prop_n
   JS_FreeAtom(ctx, prop_atom);
 }
 
+MaybeAsync(JSValue *) QTS_GetOwnPropertyNames(JSContext *ctx, JSValue **out_ptrs, uint32_t *out_len, JSValueConst *obj, int flags) {
+  JSPropertyEnum *tab = NULL;
+  int status = 0;
+  status = JS_GetOwnPropertyNames(ctx, &tab, out_len, *obj, flags);
+  if (status < 0) {
+    return jsvalue_to_heap(JS_GetException(ctx));
+  }
+  *out_ptrs = malloc(sizeof(JSValue) * *out_len);
+  for (int i = 0; i < *out_len; i++) {
+    (*out_ptrs)[i] = jsvalue_to_heap(JS_AtomToValue(ctx, tab[i].atom));
+    JS_FreeAtom(ctx, tab[i].atom);
+  }
+  js_free(ctx, tab);
+  return NULL;
+}
+
 MaybeAsync(JSValue *) QTS_Call(JSContext *ctx, JSValueConst *func_obj, JSValueConst *this_obj, int argc, JSValueConst **argv_ptrs) {
   // convert array of pointers to array of values
   JSValueConst argv[argc];

packages/quickjs-emscripten-core/src/QuickJSIterator.ts

@@ -0,0 +1,144 @@
+import type { QuickJSContext } from "./context"
+import { Lifetime, UsingDisposable } from "./lifetime"
+import type { QuickJSRuntime } from "./runtime"
+import type { QuickJSHandle } from "./types"
+import type { VmCallResult } from "./vm-interface"
+
+/**
+ * Proxies the iteration protocol from the host to a guest iterator.
+ * The guest iterator is a QuickJS object with a `next` method.
+ * See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).
+ *
+ * If calling the `next` method or any other method of the iteration protocol throws an error,
+ * the iterator is disposed after returning the exception as the final value.
+ *
+ * When the iterator is done, the handle is disposed automatically.
+ * The caller is responsible for disposing each successive value.
+ *
+ * ```typescript
+ * for (const nextResult of context.unwrapResult(context.getIterator(arrayHandle)) {
+ *   const nextHandle = context.unwrapResult(nextResult)
+ *   try {
+ *     // Do something with nextHandle
+ *     console.log(context.dump(nextHandle))
+ *   } finally {
+ *     nextHandle.dispose()
+ *   }
+ * }
+ * ```
+ */
+export class QuickJSIterator
+  extends UsingDisposable
+  implements Disposable, Iterator<VmCallResult<QuickJSHandle>>
+{
+  public owner: QuickJSRuntime
+  private _next: QuickJSHandle | undefined
+  private _isDone = false
+
+  constructor(
+    public handle: QuickJSHandle,
+    public context: QuickJSContext,
+  ) {
+    super()
+    this.owner = context.runtime
+  }
+
+  next(value?: QuickJSHandle): IteratorResult<VmCallResult<QuickJSHandle>, any> {
+    if (!this.alive || this._isDone) {
+      return {
+        done: true,
+        value: undefined,
+      }
+    }
+
+    const nextMethod = (this._next ??= this.context.getProp(this.handle, "next"))
+    return this.callIteratorMethod(nextMethod, value)
+  }
+
+  return(value?: QuickJSHandle): IteratorResult<VmCallResult<QuickJSHandle>, any> {
+    if (!this.alive) {
+      return {
+        done: true,
+        value: undefined,
+      }
+    }
+
+    const returnMethod = this.context.getProp(this.handle, "return")
+    if (returnMethod === this.context.undefined && value === undefined) {
+      // This may be an automatic call by the host Javascript engine,
+      // but the guest iterator doesn't have a `return` method.
+      // Don't call it then.
+      this.dispose()
+      return {
+        done: true,
+        value: undefined,
+      }
+    }
+
+    const result = this.callIteratorMethod(returnMethod, value)
+    returnMethod.dispose()
+    this.dispose()
+    return result
+  }
+
+  throw(e?: any): IteratorResult<VmCallResult<QuickJSHandle>, any> {
+    if (!this.alive) {
+      return {
+        done: true,
+        value: undefined,
+      }
+    }
+
+    const errorHandle = e instanceof Lifetime ? e : this.context.newError(e)
+    const throwMethod = this.context.getProp(this.handle, "throw")
+    const result = this.callIteratorMethod(throwMethod, e)
+    if (errorHandle.alive) {
+      errorHandle.dispose()
+    }
+    throwMethod.dispose()
+    this.dispose()
+    return result
+  }
+
+  get alive() {
+    return this.handle.alive
+  }
+
+  dispose() {
+    this._isDone = true
+    this.handle.dispose()
+    this._next?.dispose()
+  }
+
+  private callIteratorMethod(
+    method: QuickJSHandle,
+    input?: QuickJSHandle,
+  ): IteratorResult<VmCallResult<QuickJSHandle>, any> {
+    const callResult = input
+      ? this.context.callFunction(method, this.handle, input)
+      : this.context.callFunction(method, this.handle)
+    if (callResult.error) {
+      this.dispose()
+      return {
+        value: callResult,
+      }
+    }
+
+    const done = this.context.getProp(callResult.value, "done").consume((v) => this.context.dump(v))
+    if (done) {
+      callResult.value.dispose()
+      this.dispose()
+      return {
+        done,
+        value: undefined,
+      }
+    }
+
+    const value = this.context.getProp(callResult.value, "value")
+    callResult.value.dispose()
+    return {
+      value: { value },
+      done,
+    }
+  }
+}

packages/quickjs-emscripten-core/src/context.ts

@@ -18,8 +18,15 @@ import { QuickJSDeferredPromise } from "./deferred-promise"
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { shouldInterruptAfterDeadline } from "./interrupt-helpers"
 import { QuickJSPromisePending, QuickJSUnwrapError } from "./errors"
-import type { Disposable } from "./lifetime"
-import { Lifetime, Scope, StaticLifetime, UsingDisposable, WeakLifetime } from "./lifetime"
+import type { Disposable, DisposableArray } from "./lifetime"
+import {
+  Lifetime,
+  Scope,
+  StaticLifetime,
+  UsingDisposable,
+  WeakLifetime,
+  createDisposableArray,
+} from "./lifetime"
 import type { HeapTypedArray } from "./memory"
 import { ModuleMemory } from "./memory"
 import type { ContextCallbacks, QuickJSModuleCallbacks } from "./module"
@@ -28,15 +35,23 @@ import type {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   ExecutePendingJobsResult,
 } from "./runtime"
-import type { ContextEvalOptions, JSValue, PromiseExecutor, QuickJSHandle } from "./types"
-import { evalOptionsToFlags } from "./types"
+import {
+  ContextEvalOptions,
+  GetOwnPropertyNamesOptions,
+  JSValue,
+  PromiseExecutor,
+  QuickJSHandle,
+  StaticJSValue,
+} from "./types"
+import { evalOptionsToFlags, getOwnPropertyNamesOptionsToFlags } from "./types"
 import type {
   LowLevelJavascriptVm,
   SuccessOrFail,
   VmCallResult,
   VmFunctionImplementation,
   VmPropertyDescriptor,
 } from "./vm-interface"
+import { QuickJSIterator } from "./QuickJSIterator"
 
 /**
  * Property key for getting or setting a property on a handle with
@@ -109,6 +124,15 @@ class ContextMemory extends ModuleMemory implements Disposable {
   heapValueHandle(ptr: JSValuePointer): JSValue {
     return new Lifetime(ptr, this.copyJSValue, this.freeJSValue, this.owner)
   }
+
+  /** Manage a heap pointer with the lifetime of the context */
+  staticHeapValueHandle(ptr: JSValuePointer | JSValueConstPointer): StaticJSValue {
+    this.manage(this.heapValueHandle(ptr as JSValuePointer))
+    // This isn't technically a static lifetime, but since it has the same
+    // lifetime as the VM, it's okay to fake one since when the VM is
+    // disposed, no other functions will accept the value.
+    return new StaticLifetime(ptr as JSValueConstPointer, this.owner) as StaticJSValue
+  }
 }
 
 /**
@@ -178,6 +202,12 @@ export class QuickJSContext
   protected _BigInt: QuickJSHandle | undefined = undefined
   /** @private  */
   protected uint32Out: HeapTypedArray<Uint32Array, UInt32Pointer>
+  /** @private */
+  protected _Symbol: QuickJSHandle | undefined = undefined
+  /** @private */
+  protected _SymbolIterator: QuickJSHandle | undefined = undefined
+  /** @private */
+  protected _SymbolAsyncIterator: QuickJSHandle | undefined = undefined
 
   /**
    * Use {@link QuickJSRuntime#newContext} or {@link QuickJSWASMModule#newContext}
@@ -297,12 +327,7 @@ export class QuickJSContext
     const ptr = this.ffi.QTS_GetGlobalObject(this.ctx.value)
 
     // Automatically clean up this reference when we dispose
-    this.memory.manage(this.memory.heapValueHandle(ptr))
-
-    // This isn't technically a static lifetime, but since it has the same
-    // lifetime as the VM, it's okay to fake one since when the VM is
-    // disposed, no other functions will accept the value.
-    this._global = new StaticLifetime(ptr, this.runtime)
+    this._global = this.memory.staticHeapValueHandle(ptr)
     return this._global
   }
 
@@ -349,6 +374,14 @@ export class QuickJSContext
     return this.memory.heapValueHandle(ptr)
   }
 
+  /**
+   * Access a well-known symbol that is a property of the global Symbol object, like `Symbol.iterator`.
+   */
+  getWellKnownSymbol(name: string): QuickJSHandle {
+    this._Symbol ??= this.memory.manage(this.getProp(this.global, "Symbol"))
+    return this.getProp(this._Symbol, name)
+  }
+
   /**
    * Create a QuickJS [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) value.
    */
@@ -781,6 +814,73 @@ export class QuickJSContext
     return this.uint32Out.value.typedArray[0]
   }
 
+  /**
+   * `Object.getOwnPropertyNames(handle)`.
+   * Similar to the [standard semantics](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyNames).
+   */
+  getPropNames(
+    handle: QuickJSHandle,
+    options: GetOwnPropertyNamesOptions,
+  ): SuccessOrFail<DisposableArray<JSValue>, QuickJSHandle> {
+    this.runtime.assertOwned(handle)
+    handle.value // assert alive
+    const flags = getOwnPropertyNamesOptionsToFlags(options)
+    return Scope.withScope((scope) => {
+      const outPtr = scope.manage(this.memory.newMutablePointerArray<JSValuePointerPointer>(1))
+      const errorPtr = this.ffi.QTS_GetOwnPropertyNames(
+        this.ctx.value,
+        outPtr.value.ptr,
+        this.uint32Out.value.ptr,
+        handle.value,
+        flags,
+      )
+      if (errorPtr) {
+        return { error: this.memory.heapValueHandle(errorPtr) }
+      }
+      const len = this.uint32Out.value.typedArray[0]
+      const ptr = outPtr.value.typedArray[0]
+      const pointerArray = new Uint32Array(this.module.HEAP8.buffer, ptr, len)
+      const handles = Array.from(pointerArray).map((ptr) =>
+        this.memory.heapValueHandle(ptr as JSValuePointer),
+      )
+      this.module._free(ptr)
+      return { value: createDisposableArray(handles) }
+    })
+  }
+
+  /**
+   * `handle[Symbol.iterator]()`. See {@link QuickJSIterator}.
+   * Returns a host iterator that wraps and proxies calls to a guest iterator handle.
+   * Each step of the iteration returns a result, either an error or a handle to the next value.
+   * Once the iterator is done, the handle is automatically disposed, and the iterator
+   * is considered done if the handle is disposed.
+   *
+   * ```typescript
+   * for (const nextResult of context.unwrapResult(context.getIterator(arrayHandle)) {
+   *   const nextHandle = context.unwrapResult(nextResult)
+   *   try {
+   *     // Do something with nextHandle
+   *     console.log(context.dump(nextHandle))
+   *   } finally {
+   *     nextHandle.dispose()
+   *   }
+   * }
+   * ```
+   */
+  getIterator(handle: QuickJSHandle): SuccessOrFail<QuickJSIterator, QuickJSHandle> {
+    const SymbolIterator = (this._SymbolIterator ??= this.memory.manage(
+      this.getWellKnownSymbol("iterator"),
+    ))
+    return Scope.withScope((scope) => {
+      const methodHandle = scope.manage(this.getProp(handle, SymbolIterator))
+      const iteratorCallResult = this.callFunction(methodHandle, handle)
+      if (iteratorCallResult.error) {
+        return iteratorCallResult
+      }
+      return { value: new QuickJSIterator(iteratorCallResult.value, this) }
+    })
+  }
+
   /**
    * `handle[key] = value`.
    * Set a property on a JSValue.

packages/quickjs-emscripten-core/src/lifetime.ts

@@ -318,3 +318,48 @@ export class Scope extends UsingDisposable implements Disposable {
     this._disposables.dispose()
   }
 }
+
+/**
+ * An `Array` that also implements {@link Disposable}:
+ *
+ * - Considered {@link Disposable#alive} if any of its elements are `alive`.
+ * - When {@link Disposable#dispose}d, it will dispose of all its elements that are `alive`.
+ */
+export type DisposableArray<T> = T[] & Disposable
+
+/**
+ * Create an array that also implements {@link Disposable}.
+ */
+export function createDisposableArray<T extends Disposable>(
+  items?: Iterable<T>,
+): DisposableArray<T> {
+  const array = items ? Array.from(items) : []
+
+  function disposeAlive() {
+    return array.forEach((disposable) => (disposable.alive ? disposable.dispose() : undefined))
+  }
+
+  function someIsAlive() {
+    return array.some((disposable) => disposable.alive)
+  }
+
+  Object.defineProperty(array, SymbolDispose, {
+    configurable: true,
+    enumerable: false,
+    value: disposeAlive,
+  })
+
+  Object.defineProperty(array, "dispose", {
+    configurable: true,
+    enumerable: false,
+    value: disposeAlive,
+  })
+
+  Object.defineProperty(array, "alive", {
+    configurable: true,
+    enumerable: false,
+    get: someIsAlive,
+  })
+
+  return array as T[] & Disposable
+}