Value

Source: detlef.mjs:33

A handle to a DETLEF value or evaluation result.

Instances are returned by execution and access operations; they must not be constructed manually. Host-owned instances must be disposed. Callback-local instances are disposed automatically; retain() creates a separately owned copy.

Alias: Value

Instance Methods

read(): Primitive

Read a primitive value. Arrays and records are not copied into JavaScript objects.

Returns

• Primitive — BigInt for integer, Number for float, null for none, or undefined for no result.

Throws

• Error — An object/descriptor cannot be read as a primitive, or the handle is disposed.

format(): string

Format the value as text. Arrays and records use JSON representation; primitive strings yield their contents.

Returns

• string — Text representation.

Throws

• Error — The value is disposed, belongs to an unavailable runtime, or cannot be formatted.

get(key: number | string): Value

Read an array element or a named record field.

The returned wrapper must be disposed outside a registered callback. Inside a Function/Control callback it is temporary and disposed automatically.

Parameters

• key (number | string) — Zero-based array index or record field name.

Returns

• Value — A new wrapper to the selected value.

Throws

• Error — Invalid index/field, wrong object type, or a disposed handle.

set(key: number | string, value: HostValue): undefined

Replace an array element or record field after checking its declared type. The supplied Value is borrowed and is not consumed.

Parameters

• key (number | string) — Zero-based array index or record field name.
• value (HostValue) — Replacement value.

Returns

• undefined — No value.

Throws

• Error — Invalid index/field, type mismatch, or unavailable handles.

retain(): Value

Create a separately owned wrapper to the same value. Objects remain shared.

The returned wrapper must be disposed explicitly, including when created inside a registered callback.

Returns

• Value — Retained wrapper.

Throws

• Error — The source handle or runtime is unavailable.

dispose(): undefined

Release this wrapper once. Repeated disposal has no effect. Must be called before runtime disposal; a released wrapper must not be used again.

Returns

• undefined — No value.

Throws

• Error — The runtime is already disposed or the handle cannot be released.

Instance Fields

length: number

Read the number of elements in an array.

Throws

• Error — The value is not an array or its handle is disposed.