StaticJsObject

Base interface for all object-like sandbox values.

Import

import { type StaticJsObject, isStaticJsObject } from "@suntime-js/core";

Overview

StaticJsObject is the base interface for every object-like value in the sandbox. It extends StaticJsPrimitive and adds a full property-manipulation API that mirrors the ECMAScript internal methods ([[Get]], [[Set]], [[DefineOwnProperty]], etc.).

Every method comes in a set of three triplets, documented in the section below.

Implemented by

StaticJsPlainObject: ordinary {} objects
StaticJsArray: array instances
StaticJsFunction: functions and callables
StaticJsSymbol: symbols (for Symbol.prototype access)
StaticJsProxy: proxy objects

Method triplets

Every property operation is exposed as three variants:

Suffix	Signature	When to use
`*Async`	Returns `Promise<T>`	General host code. Drives evaluation via the realm's `runTask`.
`*Sync`	Returns `T`	Host code that must complete synchronously. Drives evaluation via the realm's `runTaskSync`. Requires a sync-safe task runner.
`*Evaluator`	Returns `EvaluationGenerator<T>`	Inside evaluator functions only. Must be consumed with `yield*`.

Both *Async and *Sync accept an optional StaticJsObjectPropertyAccessRunTaskOptions as their final argument, letting you override the task runner and receiver per-call. *Evaluator variants of get/set do not accept a runTask, and instead can accept the receiver directly as a as a positional argument (preferred) or via StaticJsObjectPropertyAccessOptions.

All key parameters throughout this API are of type StaticJsPropertyKey: either a native string or a StaticJsSymbol.

Code invocation

Property access can invoke sandboxed code (getters, setters, Proxy traps). Always use a time-bounded task runner when calling *Sync methods on untrusted objects.

Methods

getPrototypeOf(opts?)

getPrototypeOfAsync(opts?: StaticJsRunTaskOptions): Promise<StaticJsObject | null>
getPrototypeOfSync(opts?: StaticJsRunTaskOptions): StaticJsObject | null

Returns the prototype of this object, or null if it has none.

setPrototypeOf(prototype, opts?)

setPrototypeOfAsync(prototype: StaticJsObject | null, opts?: StaticJsRunTaskOptions): Promise<boolean>
setPrototypeOfSync(prototype: StaticJsObject | null, opts?: StaticJsRunTaskOptions): boolean

Sets the prototype. Returns true on success, false if the object is non-extensible or the operation is otherwise rejected.

isExtensible(opts?)

isExtensibleAsync(opts?: StaticJsRunTaskOptions): Promise<boolean>
isExtensibleSync(opts?: StaticJsRunTaskOptions): boolean

Returns true if new properties can be added to the object.

preventExtensions(opts?)

preventExtensionsAsync(opts?: StaticJsRunTaskOptions): Promise<boolean>
preventExtensionsSync(opts?: StaticJsRunTaskOptions): boolean

Seals the object against new properties. Returns true on success.

ownPropertyKeys(opts?)

ownPropertyKeysAsync(opts?: StaticJsRunTaskOptions): Promise<StaticJsPropertyKey[]>
ownPropertyKeysSync(opts?: StaticJsRunTaskOptions): StaticJsPropertyKey[]

Returns all own property keys; both string and symbol. String keys are native string; symbol keys are StaticJsSymbol instances.

ownEnumerableKeys(opts?)

ownEnumerableKeysAsync(opts?: StaticJsRunTaskOptions): Promise<string[]>
ownEnumerableKeysSync(opts?: StaticJsRunTaskOptions): string[]

Returns only own enumerable string property keys, as native strings. Equivalent to Object.keys(...).

hasProperty(key, opts?)

hasPropertyAsync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): Promise<boolean>
hasPropertySync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): boolean

Returns true if the key exists on this object or its prototype chain. Pass a native string or a StaticJsSymbol as the key.

hasOwnProperty(key, opts?)

hasOwnPropertyAsync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): Promise<boolean>
hasOwnPropertySync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): boolean

Returns true if the key exists directly on this object, not its prototype.

getProperty(key, opts?)

getPropertyAsync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): Promise<StaticJsPropertyDescriptor | undefined>
getPropertySync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): StaticJsPropertyDescriptor | undefined

Returns the property descriptor for key from this object or its prototype chain, or undefined if the key does not exist.

getOwnProperty(key, opts?)

getOwnPropertyAsync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): Promise<StaticJsPropertyDescriptor | undefined>
getOwnPropertySync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): StaticJsPropertyDescriptor | undefined

Same as getProperty but only searches the object's own properties.

StaticJsPropertyDescriptor

Returned by getProperty and getOwnProperty. One of two forms:

Data descriptor:

Property	Type	Description
`value`	`StaticJsValue`	The stored value.
`writable`	`boolean`	Whether the value can be reassigned.
`enumerable`	`boolean`	Appears in `for...in` / `Object.keys`.
`configurable`	`boolean`	Whether the descriptor can be changed or deleted.

Accessor descriptor:

Property	Type	Description
`get`	`StaticJsCallable \| undefined`	Getter function.
`set`	`StaticJsCallable \| undefined`	Setter function.
`enumerable`	`boolean`	As above.
`configurable`	`boolean`	As above.

defineOwnProperty(key, descriptor, opts?)

defineOwnPropertyAsync(
  key: StaticJsPropertyKey,
  descriptor: StaticJsPropertyDescriptorRecord,
  opts?: StaticJsRunTaskOptions,
): Promise<boolean>
defineOwnPropertySync(
  key: StaticJsPropertyKey,
  descriptor: StaticJsPropertyDescriptorRecord,
  opts?: StaticJsRunTaskOptions,
): boolean

Defines or redefines an own property. descriptor is the record form (all fields optional). Returns true on success, false if the operation is rejected (e.g. the property is non-configurable).

See StaticJsPropertyDescriptorRecord for the descriptor shape.

get(key, opts?)

getAsync(key: StaticJsPropertyKey, opts?: StaticJsObjectPropertyAccessRunTaskOptions): Promise<StaticJsValue>
getSync(key: StaticJsPropertyKey, opts?: StaticJsObjectPropertyAccessRunTaskOptions): StaticJsValue

// Preferred: pass receiver directly:
getEvaluator(key: StaticJsPropertyKey, receiver?: StaticJsValue): EvaluationGenerator<StaticJsValue>
// Alternative: pass receiver inside an opts object:
getEvaluator(key: StaticJsPropertyKey, opts?: StaticJsObjectPropertyAccessOptions): EvaluationGenerator<StaticJsValue>

Gets the value of key on this object or its prototype chain. Invokes getter functions if present. Returns StaticJsUndefined if the key does not exist.

receiver is the value bound as this inside getter calls. Defaults to the object itself. For *Async/*Sync pass it as opts.receiver; for *Evaluator pass it as the second argument directly (preferred) or via opts.receiver.

set(key, value, opts?)

setAsync(key: StaticJsPropertyKey, value: StaticJsValue, opts?: StaticJsObjectPropertyAccessRunTaskOptions): Promise<boolean>
setSync(key: StaticJsPropertyKey, value: StaticJsValue, opts?: StaticJsObjectPropertyAccessRunTaskOptions): boolean

// Preferred: pass receiver directly:
setEvaluator(key: StaticJsPropertyKey, value: StaticJsValue, receiver?: StaticJsValue): EvaluationGenerator<boolean>
// Alternative: pass receiver inside an opts object:
setEvaluator(key: StaticJsPropertyKey, value: StaticJsValue, opts?: StaticJsObjectPropertyAccessOptions): EvaluationGenerator<boolean>

Sets key to value. Invokes setter functions if present. Returns true on success, false if the assignment is rejected (e.g. in strict mode with a non-writable property).

receiver is the value bound as this inside setter calls. Defaults to the object itself. For *Async/*Sync pass it as opts.receiver; for *Evaluator pass it as the third argument directly (preferred) or via opts.receiver.

delete(key, opts?)

deleteAsync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): Promise<boolean>
deleteSync(key: StaticJsPropertyKey, opts?: StaticJsRunTaskOptions): boolean

Deletes the property key from this object. Returns true if the property was deleted or did not exist; false if the property is non-configurable.

toNative()

toNative(): object

Returns a host-side proxy that delegates all property accesses back into the sandbox. Reading or writing any property on the returned object may synchronously invoke sandboxed code (getters, setters, Proxy traps).

Synchronous code invocation

Do not call toNative() on sandbox objects unless a time-bounded runTaskSync is configured on the realm. Without a bound, sandboxed getters or Proxy traps that contain loops will deadlock the host process.

Prefer the StaticJsObject API methods (getAsync, setAsync, defineOwnPropertyAsync, etc.) for direct, controlled access to sandbox object properties.

See Type Coercion for the complete coercion rules applied when crossing the sandbox boundary.

Types

StaticJsPropertyKey

import { type StaticJsPropertyKey, isStaticJsPropertyKey } from "@suntime-js/core";

type StaticJsPropertyKey = string | StaticJsSymbol;

The union of valid property key types. All property-access methods on StaticJsObject accept either a native string (for string-keyed properties) or a StaticJsSymbol (for symbol-keyed properties).

isStaticJsPropertyKey(value) narrows an unknown value to StaticJsPropertyKey.

Options types

StaticJsObjectPropertyAccessOptions

interface StaticJsObjectPropertyAccessOptions {
  receiver?: StaticJsValue;
}

Accepted by the opts-object overload of *Evaluator variants of get and set. receiver is the value bound as this inside getter and setter calls. Defaults to the object itself when not provided.

StaticJsObjectPropertyAccessRunTaskOptions

type StaticJsObjectPropertyAccessRunTaskOptions = StaticJsObjectPropertyAccessOptions &
  StaticJsRunTaskOptions;

Combined options for the *Async and *Sync variants. Extends StaticJsObjectPropertyAccessOptions with all fields from StaticJsRunTaskOptions (runTask, etc.).

Type guard

isStaticJsObject(value)

isStaticJsObject(value: unknown): value is StaticJsObject

Returns true for any object-like sandbox value: plain objects, arrays, functions, symbols, and proxies.

Overview​

Implemented by​

Method triplets​

Methods​

getPrototypeOf(opts?)​

setPrototypeOf(prototype, opts?)​

isExtensible(opts?)​

preventExtensions(opts?)​

ownPropertyKeys(opts?)​

ownEnumerableKeys(opts?)​

hasProperty(key, opts?)​

hasOwnProperty(key, opts?)​

getProperty(key, opts?)​

getOwnProperty(key, opts?)​

StaticJsPropertyDescriptor​

defineOwnProperty(key, descriptor, opts?)​

get(key, opts?)​

set(key, value, opts?)​

delete(key, opts?)​

toNative()​

Types​

StaticJsPropertyKey​

Options types​

StaticJsObjectPropertyAccessOptions​

StaticJsObjectPropertyAccessRunTaskOptions​

Type guard​

isStaticJsObject(value)​