Registry / crm-productivity / proxy-target

proxy-target

library3.0.2jsnpmunverified

proxy-target is a JavaScript utility library designed to simplify the use of native Proxies, particularly when dealing with primitive values, `null`, `undefined`, and functions. It addresses common `Proxy` limitations, such as the inability to directly proxy primitives or the 'Array.isArray shenanigans' by wrapping values in an object structure that can be consistently proxied and then unwrapped. The current stable version is 3.0.2. It appears to follow a release cadence driven by feature enhancements and bug fixes, rather than strict time-based intervals. Key differentiators include its ability to uniformly proxy almost any JavaScript value (primitives, objects, functions, etc.) by converting them into a structured `{ type, value }` pair, and its explicit mechanisms (`wrap`, `unwrap`, `bound`, `unbound`) for managing `this` context and value retrieval within a proxy chain. This makes it particularly useful for advanced metaprogramming scenarios where uniform proxy behavior across diverse value types is crucial.

crm-productivity

npm install proxy-target

package ↗

INSTALL

IMPORT

SIG · PROXY-TARGET

proxy-target

crm-productivityjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

wrap

✓ import { wrap } from 'proxy-target';

✗ const wrap = require('proxy-target').wrap;

ESM is the primary export since version 3. For CommonJS, destructuring the require result is necessary.

unwrap

✓ import { unwrap } from 'proxy-target';

✗ import unwrap from 'proxy-target/unwrap';

All core utilities are named exports from the main package entry point.

target

✓ import { target } from 'proxy-target';

✗ const target = require('proxy-target');

`target` is a named export; direct CommonJS `require` would return the module object, not the function.

bound

✓ import { bound } from 'proxy-target';

✗ import { bound } from 'proxy-target/bound';

`bound` is a utility for handling function context within proxied operations and is a named export.

Demonstrates wrapping and unwrapping various JavaScript values (objects, primitives, functions) and using `bound`/`unbound` to manage function context within a proxy.

import { wrap, unwrap, bound, target, unbound } from 'proxy-target'; // Example 1: Wrapping and unwrapping an object let proxiedObject = wrap({ a: 1, b: 'hello' }); console.log('Wrapped object:', proxiedObject); let unwrappedObject = unwrap(proxiedObject); console.log('Unwrapped object:', unwrappedObject); // Verify identity if not a primitive (proxy-target specific) console.log('Original vs Unwrapped (object):', unwrappedObject.a === 1, unwrappedObject.b === 'hello'); // Example 2: Wrapping a primitive (number) let proxiedNumber = wrap(123); console.log('Wrapped number:', proxiedNumber); // The wrapper exposes a { type, value } structure for primitives console.log('Type of wrapped number:', proxiedNumber.type); console.log('Value of wrapped number:', proxiedNumber.value); let unwrappedNumber = unwrap(proxiedNumber); console.log('Unwrapped number:', unwrappedNumber); console.log('Original vs Unwrapped (number):', unwrappedNumber === 123); // Example 3: Handling functions with `bound` and `unbound` const originalFunction = (val) => `Processed: ${val}`; const callbacks = [ (a) => a + 1, (b) => b + 2 ]; let proxiedFunction = wrap( callbacks[1], (type, value) => bound( target(type, callbacks.indexOf(value)) ) ); // To get the original function back, first unwrap `bound` then use the callback const retrievedIndex = unbound(proxiedFunction); const finalUnwrappedFunction = unwrap(retrievedIndex, (type, value) => { return type === "function" ? callbacks[value] : value; }); console.log('Retrieved function result:', finalUnwrappedFunction(10));

Debug

Known issues

gotchaWhen wrapping primitive values (number, string, boolean, symbol, bigint, null, undefined), `proxy-target` returns an object of the form `{ type: string, value: any }` rather than the primitive itself, to allow consistent proxying. Direct `typeof` or comparison without `unwrap` will yield unexpected results.

fix

Always use `unwrap(proxiedValue)` before performing type checks, comparisons, or operations that expect the original primitive value.

affects: >=1.0.0

breakingVersions prior to 3.0.0 might have different import paths or CommonJS behavior. Version 3.0.0 and above primarily use ESM named exports. Using `require()` directly on named exports for older versions might not work as expected or produce the entire module object.

fix

For new projects or when upgrading, use `import { SymbolName } from 'proxy-target';`. For CommonJS in modern Node.js, consider dynamic `import()` or stick to `const { SymbolName } = require('proxy-target');` if available.

affects: >=3.0.0

gotchaThe `wrap` function can optionally take a callback to customize how the target is created. Incorrectly implementing this callback can lead to `Proxy` traps failing or the unwrapped value not matching expectations, especially when not returning a structure compatible with `proxy-target`'s internal handling.

fix

Refer to the documentation for custom `wrap` callbacks. Ensure the callback returns a structure (`target(type, value)`) that `proxy-target` can properly interpret, or the original value if you intend it to bypass the wrapping logic.

affects: >=1.0.0

gotchaThe default `wrap` behavior for arrays and functions is to return them directly, unless `proxy-target/array` is used (for arrays) or `bound` is explicitly used for functions. This can lead to inconsistencies if you expect all values to be wrapped into a `{ type, value }` object by default.

fix

Be aware of the specific wrapping behavior for arrays and functions. If you need arrays to be explicitly wrapped into a `{type: 'array', value: [...]}` structure, you may need to import `proxy-target/array` and use its specific `wrap` function, or provide a custom `wrap` callback.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: 'get' on proxy: property 'type' is a read-only and non-configurable data property on the proxy target but the proxy's handler has a get trap that returns a different value

Attempting to modify the `type` or `value` property of a wrapped primitive (e.g., `proxiedNumber.type = 'newType'`). The internal `{ type, value }` object created by `proxy-target` for primitives is not meant to be modified directly.

fix

Do not attempt to mutate the internal `type` or `value` properties of wrapped primitives. If you need a different representation, unwrap the value, modify it, and re-wrap if necessary.

TypeError: Cannot create proxy with a non-object as target or handler

This error typically indicates that you are trying to create a native `Proxy` with a non-object as its target directly, which `proxy-target` aims to solve. If you encounter this when using `proxy-target`, it's likely an issue where `wrap` was not used correctly, or a custom `wrap` callback returned a primitive directly without the necessary `{ type, value }` structure.

fix

Ensure that any value passed to `wrap` (or returned by a custom `wrap` callback that is then passed to `Proxy`) is either an object/function, or is correctly transformed into the `{ type, value }` object structure by `proxy-target`'s internal logic or your custom callback.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

43 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/proxy-target ↗