Skip to main content
Version: v1.2.0

Class: Nexo

Defined in: src/Nexo.ts:31

Represents a proxy factory for creating and managing proxy objects.

Remarks​

This class provides utilities for creating proxies, retrieving existing ones by unique IDs, and interacting with them through event-driven mechanisms.

It emits the following events:

  • proxy: Fired whenever a new proxy is created.
  • error: Fired when an error occurs.
  • proxy.handler: Fired when any proxy handler function is invoked.
  • proxy.error: Fired when a proxy operation fails.

Example​

// Example of listening to 'proxy' event every time a new proxy is created.
const nexo = new Nexo();
const listener = (event: NexoEvent) => {};

nexo.on('proxy', listener);

// The listener will be called when a new proxy is created.
const proxy = nexo.create();

Extends​

Constructors​

new Nexo()​

new Nexo(): Nexo

Defined in: src/Nexo.ts:124

Initializes the Nexo proxy system and event hooks.

Returns​

Nexo

Remarks​

Inherits all event management behavior from NexoEmitter. Use on() and emit() to subscribe and react to internal proxy lifecycle events.

Overrides​

NexoEmitter.constructor

Properties​

entries​

readonly entries: NexoMap<Proxy>

Defined in: src/Nexo.ts:38

A map that stores unique proxy IDs associated with their respective WeakRef references to the proxy objects.

Remarks​

This map allows quick access to proxies by their unique ID, ensuring that proxies are properly managed and referenced.

Methods​

create()​

create(target?): Proxy

Defined in: src/Nexo.ts:185

Creates a new proxy object or retrieves an existing one with the specified target.

Parameters​

target?​

object

An optional target object for the proxy

Returns​

Proxy

A new proxy object

Remarks​

Proxies can be created with or without a target. If a target is provided, it will be used as the proxy target. The method will emit a proxy event every time a new proxy is created.

Example​

// Creating a new proxy
const nexo = new Nexo();
const proxy = nexo.create();

use()​

use(id, target?): Proxy

Defined in: src/Nexo.ts:149

Creates or retrieves an existing proxy by its unique ID.

Parameters​

id​

string

A unique identifier for the proxy

target?​

object

An optional target object to associate with the proxy

Returns​

Proxy

A proxy uniquely associated with the provided ID and optional target. Use this method to retrieve or memoize proxies tied to stable identifiers.

Remarks​

If a proxy is already created with the provided ID, this method will return the existing proxy. If a new proxy is requested with a different target, the method will create a new proxy associated with that target. A ProxyError is thrown if an attempt is made to use the same ID for different targets.

Example​

// Creating or retrieving a proxy by its ID
const nexo = new Nexo();
const proxy = nexo.use('foo');
nexo.use('foo') === proxy; // True, retrieves the same proxy by ID

Throws​

ProxyError - If the ID is already used by another proxy with a different target

getOwnPropertyDescriptor()​

static getOwnPropertyDescriptor(proxy, property): void | PropertyDescriptor

Defined in: src/Nexo.ts:72

Retrieves the property descriptor for a proxy, considering its sandbox target if applicable.

Parameters​

proxy​

Proxy

An existing proxy object

property​

ObjectKey

The property name (key) to retrieve the descriptor for

Returns​

void | PropertyDescriptor

The property descriptor if the property exists, or undefined otherwise

Remarks​

Since proxies can have altered behavior, using Reflect.getOwnPropertyDescriptor directly may not return the expected results. This method ensures the correct descriptor is fetched from the sandbox target if the proxy was created without a direct target.

getPrototypeOf()​

static getPrototypeOf(proxy): object

Defined in: src/Nexo.ts:109

Retrieves the prototype of a proxy, considering its sandbox target if applicable.

Parameters​

proxy​

Proxy

An existing proxy object

Returns​

object

The prototype of the proxy, which can be an object or null

Remarks​

This method ensures that the prototype returned is the one from the sandbox target when the proxy was created without a direct target.

keys()​

static keys(proxy): ObjectKey[]

Defined in: src/Nexo.ts:92

Retrieves the own property keys of a proxy, considering its sandbox target if applicable.

Parameters​

proxy​

Proxy

An existing proxy object

Returns​

ObjectKey[]

An array of the proxy object's own property keys, including both strings and symbols

Remarks​

Similar to the property descriptor method, this method ensures that the keys returned are from the sandbox target when the proxy was created without a direct target.

wrap()​

static wrap(proxy): ProxyWrapper

Defined in: src/Nexo.ts:58

Provides a wrapper for an existing proxy.

Parameters​

proxy​

Proxy

An existing proxy object

Returns​

ProxyWrapper

A wrapper for the proxy that allows interaction with proxy events

Remarks​

This method wraps a proxy object and allows interaction with the proxy's events and properties. Proxy-related events follow the format proxy.handler, where the handler corresponds to one of the standard proxy handler functions such as apply, construct, get, etc.

Example​

// Wrapping an existing proxy and listening to 'proxy.get' event
const nexo = new Nexo();
const proxy = nexo.create();
const wrapper = Nexo.wrap(proxy);

wrapper.on('proxy.get', (event: ProxyEvent) => {});