Skip to content

Rhino host objects

Every Rhino object implements Scriptable. Reflect and the corresponding Object methods accept those objects regardless of whether their storage comes from ScriptableObject.

Use ScriptableObject when the engine should manage properties, attributes and accessors. Implement Scriptable directly when properties live in a host data structure. The original get, put, has, delete, prototype and scope methods remain sufficient for a legacy host. The additional object operations have default implementations, including JVM interface defaults.

Operation Legacy default Override when
ownPropertyKeys() The names returned by getIds() The host has non-enumerable keys, symbols or a different own-key order
getOwnPropertyDescriptor(cx, key) An own data property, writable, enumerable and configurable Properties have accessors or different attributes
defineOwnPropertyOrFalse(cx, key, descriptor) Writes representable data definitions; refuses unsupported attributes and accessors The host can retain other descriptors or report mutation refusal directly
isExtensible true The host can prevent new properties
preventExtensions() false The host can enforce non-extensibility on subsequent writes and definitions
setPrototypeOf(cx, prototype) Checks extensibility and ordinary prototype cycles, then sets the prototype The host has an immutable or otherwise exotic prototype

Keys use the engine's existing string, integer-index and Symbol representation. Implement SymbolScriptable when the value operations support symbols. Own-key operations include non-enumerable properties and preserve the host's order. Descriptors contain Scriptable.NOT_FOUND for omitted fields; an explicit undefined is a supplied value.

The default interface cannot retain accessor functions or altered property flags beside a host's own storage. For example, defining a new property with only {value: 1} requires false flags, so a legacy host refuses it. Defining {value: 1, writable: true, enumerable: true, configurable: true} is representable. A value-only update to an existing mutable data property preserves its attributes. A host that supports richer definitions implements the boolean operation and reports its actual resulting descriptors.

Reflect.defineProperty returns false when the definition is refused. Object.defineProperty throws a TypeError for that refusal. An exception raised by the host operation propagates through either method. The pre-existing ScriptableObject.defineOwnProperty API keeps its exception behavior; embedders can use defineOwnPropertyOrFalse when they need the boolean operation.

The same distinction applies to extensibility. A legacy host that cannot prevent writes answers false from Reflect.preventExtensions and remains extensible. Object.preventExtensions, Object.seal and Object.freeze throw if the host refuses the operation. A descriptor-aware host can support them by enforcing its extensibility and descriptor state consistently.

Delegator forwards metadata and mutations to its delegee. The legacy With wrapper reports the wrapped object's property descriptors and keys. Proxies accept host targets and handlers, forward missing traps through the same object-operation contract, and validate trap answers against the host's actual descriptors and extensibility.

Ordinary property writes through Reflect.set respect the target's descriptor and write to the receiver. Accessor calls receive that receiver. A host with Callable or Constructable capabilities remains an object and can participate in Reflect.apply, Reflect.construct and proxy forwarding. Primitive this boxing in the Rhino call protocol remains tracked in #47 and #78.