js-proxy - npm Package Compare versions

Comparing version 0.1.4 to 0.2.0

package.json

 {
   "name": "js-proxy",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "The one-stop shop solution for JS Proxies and FFI APIs",
@@ -35,2 +35,6 @@ "main": "./cjs/index.js",
     },
+    "./mitm": {
+      "import": "./esm/mitm.js",
+      "default": "./cjs/mitm.js"
+    },
     "./traps": {
@@ -37,0 +41,0 @@ "import": "./esm/traps.js",

README.md

@@ -9,13 +9,16 @@ [![build status](https://github.com/WebReflection/js-proxy/actions/workflows/node.js.yml/badge.svg)](https://github.com/WebReflection/js-proxy/actions) [![Coverage Status](https://coveralls.io/repos/github/WebReflection/js-proxy/badge.svg?branch=main)](https://coveralls.io/github/WebReflection/js-proxy?branch=main)
 
+- - -
+
 ### Table of content
 
-  * [API](#api) that describes the default exported utility
-  * [jsProxy](#jsproxy) that describes the namespace returned by the utility
-  * [Heap](#heap) that describes what `js-proxy/heap` exports as extra utility
+  * **[API](#api)** that describes the default exported utility
+  * **[jsProxy](#jsproxy)** that describes the namespace returned by the utility
+  * **[MITM](#mitm)** that describes what `js-proxy/mitm` exports as extra utility
+  * **[Heap](#heap)** that describes what `js-proxy/heap` exports as extra utility
+  * **[Traps](#traps)** that describes what `js-proxy/traps` exports
+  * **[Types](#types)** that describes what `js-proxy/types` exports
 
 ## API
 
-<details id="define" open>
-  <summary><strong style="font-size:1.5rem"><code>&nbsp;define(namespace):jsProxy&nbsp;</code></strong></summary>
-  <div markdown=1>
+### `define(namespace):jsProxy`
 
@@ -29,3 +32,3 @@ The default export provides an utility to define various handlers for any kind of proxied value and returns a [jsProxy](#jsproxy) object literal.
 
-> ℹ️ **Important**
+> [!Important]
 > 
@@ -38,3 +41,3 @@ > If the namespace contains `object`, `array`, or `function` as own entries the value can be either a reference to those types or actually a number or any other primitive which goal is to reflect proxies across worlds (boundaries, workers, realms, interpreters).
 
-<h4>Example</h4>
+#### Example
 
@@ -88,11 +91,6 @@ ```js
 
-  </div>
-</details>
 
-
 ## jsProxy
 
-<details id="js-proxy-proxy" open>
-  <summary><strong style="font-size:1.5rem"><code>&nbsp;jsProxy.proxy.type(value, ...rest)&nbsp;</code></strong></summary>
-  <div markdown=1>
+### `jsProxy.proxy.type(value, ...rest)`
 
@@ -128,3 +126,3 @@ The `proxy` literal will contain all defined proxy types able to bootstrap related proxies directly.
 
-<h4 id="dealing-with-primitives">Dealing with primitives</h4>
+#### Dealing with primitives
 
@@ -137,3 +135,3 @@ The `proxy` namespace is able to bootstrap even primitives but with the following constraints:
 
-<h4>Example</h4>
+#### Example
 
@@ -168,3 +166,3 @@ ```js
 
-<h4 id="dealing-with-foreing-pl">Dealing with foreign programming languages</h4>
+#### Dealing with foreign programming languages
 
@@ -180,3 +178,3 @@ Usually most primitive types are exchanged as such in the *ForeignPL* to *JS* world, so that numbers are converted, boolean are converted, strings are (likely) converted (but they don't really need to be) but objects, arrays, and functions cannot really be converted retaining their reference in the *ForeignPL* counterpart.
 
-<h4>Example</h4>
+#### Example
 
@@ -208,9 +206,4 @@ ```js
 
-  </div>
-</details>
+### `jsProxy.release(token)`
 
-<details id="js-proxy-release" open>
-  <summary><strong style="font-size:1.5rem"><code>&nbsp;jsProxy.release(token)&nbsp;</code></strong></summary>
-  <div markdown=1>
-
 This utility is particularly handy for *FFI* related use cases or whenever an explicit `destroy()` or `destruct()` method is meant by the code that provides the proxy.
@@ -224,3 +217,3 @@
 
-<h4>Example</h4>
+#### Example
 
@@ -245,9 +238,4 @@ ```js
 
-  </div>
-</details>
+### `jsProxy.typeOf(unknown)`
 
-<details id="js-proxy-type-of" open>
-  <summary><strong style="font-size:1.5rem"><code>&nbsp;jsProxy.typeOf(unknown)&nbsp;</code></strong></summary>
-  <div markdown=1>
-
 Differently from the [typeof operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof), the `typeOf` utility does the following:
@@ -262,7 +250,7 @@
 
-> ℹ️ **Note**
+> [!Note]
 > 
 > This utility is not necessarily that useful with this module but it's especially handy to branch out specific proxies handlers and behavior whenever the type of proxy is known in the namespace.
 
-<h4>Example</h4>
+#### Example
 
@@ -288,8 +276,4 @@ ```js
 
-  </div>
-</details>
 
-<details id="js-proxy-value-of" open>
-  <summary><strong style="font-size:1.5rem"><code>&nbsp;jsProxy.valueOf(unknown)&nbsp;</code></strong></summary>
-  <div markdown=1>
+### `jsProxy.valueOf(unknown)`
 
@@ -302,3 +286,3 @@ If a defined proxy handler has its own `valueOf` trap, this utility will call that trap directly and return whatever that method decided to return.
 
-<h4>Example</h4>
+#### Example
 
@@ -331,6 +315,43 @@ ```js
 
-  </div>
-</details>
 
+## MITM
 
+The [MITM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) utility puts a proxy handler behind the reference and not upfront. Usually, proxies are transparent until they are not:
+
+  * DOM operations are not allowed with proxies
+  * `typeof` or `isArray` or anything else drilling the proxied type might reveal the proxy or fail
+  * references need to be proxied before others can consume these, as opposite of hook any extra feature/utility/observability without requiring 3rd party to change their reference to the real target
+
+Accordingly, the *MITM* export allows anything to have a proxy between its reference and its prototype, which requires extra careful handling, but it can summarized as such:
+
+```js
+import mitm from 'js-proxy/mitm';
+
+// generic DOM handler for text property
+const textHandler = {
+  get(__proto__, name, target) {
+    if (name === 'text')
+      return target.textContent;
+    return Reflect.get(__proto__, name, target);
+  },
+  set(__proto__, name, value, target) {
+    if (name === 'text') {
+      target.textContent = value;
+      return true;
+    }
+    return Reflect.set(__proto__, name, value, target);
+  }
+};
+
+// pollute (once) any DOM node
+mitm(document.body, textHandler);
+
+// see magic
+document.body.text = 'Hello MITM';
+document.body.text; // 'Hello MITM'
+```
+
+The rule of thumb for *MITM* is that last come is the first to intercept but it's possible to add multiple *MITM* although performance will degrade proportionally as more logic will be involved per each property.
+
+
 ## Heap
@@ -342,3 +363,3 @@
 
-<h4>Example</h4>
+#### Example
 
@@ -374,1 +395,45 @@ ```js
 As summary, this export helps relating any reference to a unique identifier and it holds such reference until it's dropped. This is particularly useful to avoid the current realm collecting that reference, as it might be used solely in the outer world, still enabling, via `destruct` ability, to free memory on occasion.
+
+
+## Traps
+
+The `js-proxy/traps` exports the following:
+
+```js
+// Standard Proxy Traps
+export const APPLY                        = 'apply';
+export const CONSTRUCT                    = 'construct';
+export const DEFINE_PROPERTY              = 'defineProperty';
+export const DELETE_PROPERTY              = 'deleteProperty';
+export const GET                          = 'get';
+export const GET_OWN_PROPERTY_DESCRIPTOR  = 'getOwnPropertyDescriptor';
+export const GET_PROTOTYPE_OF             = 'getPrototypeOf';
+export const HAS                          = 'has';
+export const IS_EXTENSIBLE                = 'isExtensible';
+export const OWN_KEYS                     = 'ownKeys';
+export const PREVENT_EXTENSION            = 'preventExtensions';
+export const SET                          = 'set';
+export const SET_PROTOTYPE_OF             = 'setPrototypeOf';
+
+// Custom (JS)Proxy Traps
+export const DESTRUCT                     = 'destruct';
+export const VALUE_OF                     = 'valueOf';
+```
+
+
+## Types
+
+The `js-proxy/types` exports the following:
+
+```js
+export const ARRAY     = 'array';
+export const BIGINT    = 'bigint';
+export const BOOLEAN   = 'boolean';
+export const FUNCTION  = 'function';
+export const NULL      = 'null';
+export const NUMBER    = 'number';
+export const OBJECT    = 'object';
+export const STRING    = 'string';
+export const SYMBOL    = 'symbol';
+export const UNDEFINED = 'undefined';
+```

No alert changes

Improved metrics

Total package byte prevSize

29312

increased by16.02%

Number of package files

15

increased by25%

Lines of code

387

increased by15.52%

Number of lines in readme file

423

increased by18.16%

No dependency changes