@webqit/observer - npm Package Compare versions

Comparing version 2.1.11 to 2.1.12

package.json

		@@ -15,3 +15,3 @@ {
		"homepage": "https://webqit.io/tooling/observer",
		"version": "2.1.11",
		"version": "2.1.12",
		"license": "MIT",
		@@ -18,0 +18,0 @@ "repository": {

README.md

		@@ -17,3 +17,3 @@ # The Observer API

		Tracking mutations on JavaScript objects has historically relied on "object wrapping" techniques with [ES6 Proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy), and on "property mangling" techniques with [getters and setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty). Besides how the first poses an object identity problem and the second, an interoperability problem, there is also much inflexibility in the programming model they enable!
		Tracking mutations on JavaScript objects has historically relied on "object wrapping" techniques with [ES6 Proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy), and on "property mangling" techniques with [getters and setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty). Besides how the first poses an object identity problem and the second, an interoperability problem, there is also much inflexibility in the programming model that the two techniques enable!

		@@ -26,31 +26,15 @@ This is discussed extensively in [the introductory blog post](https://dev.to/oxharris/reinvestigating-reactivity-22e0-temp-slug-5973064?preview=8afd0f8b156bf0b0b1c08058837fe4986054e52a7450f0a28adbaf07dcb7f5659b724166f553fb98ceab3d080748e86b244684f515d579bcd0f48cbb#introducing-the-observer-api)<sup>draft</sup>

		The Observer API is a set of utility functions.
		The Observer API is a set of utility functions for all things object observability - notably, the `Observer.observe()` and `Observer.intercept()` methods.

		> Note
		> <br>This is documentation for `Observer@2.x`. (Looking for [`Observer@1.x`](https://github.com/webqit/observer/tree/v1.7.6)?)
		<details><summary>This is documentation for Observer@2.x</summary>

		Looking for [`Observer@1.x`](https://github.com/webqit/observer/tree/v1.7.6)?

		</details>

		### Method: `Observer.observe()`

		Observe mutations on any object or array!
		Observe mutations on arbitrary objects or arrays!

		```js
		// Signature 1
		Observer.observe( obj, callback[, options = {} ]);
		```

		```js
		// Signature 2
		Observer.observe( obj, [ prop, prop, ... ], callback[, options = {} ]);
		```

		```js
		// Signature 3
		Observer.observe( obj, prop, callback[, options = {} ]);
		```

		#### Usage

		Observe arbitrary objects and arrays:

		```js
		// An object
		@@ -109,2 +93,3 @@ const obj = {};

		// Child
		Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
		@@ -115,6 +100,2 @@

		> Note
		> <br>This is documentation for `Observer@2.x`. (Looking for [`Observer@1.x`](https://github.com/webqit/observer/tree/v1.7.6)?)


		└ "Child" observers get automatically aborted at parent's "next turn", and at parent's own abortion!
		@@ -139,6 +120,5 @@

		<details>
		<summary>Polyfill limitations</summary>
		<details><summary>Polyfill limitations</summary>

		Beware non-reactive operations:
		In the polyfill, object observability doesn't work with literal operations. Beware non-reactive operations:

		@@ -189,6 +169,5 @@ ```js

		<details>
		<summary>Polyfill limitations</summary>
		<details><summary>Polyfill limitations</summary>

		Beware non-reactive operations:
		In the polyfill, object observability doesn't work with literal operations. Beware non-reactive operations:

		@@ -287,4 +266,3 @@ ```js

		<details>
		<summary>Console</summary>
		<details><summary>Console</summary>

		@@ -404,41 +382,6 @@ \| type \| path \| value \| isUpdate \|

		#### Concept: Custom Details

		Pass some custom detail - an arbitrary value - to observers via a `params.detail` property.

		```js
		// A set operation with detail
		Observer.set( obj, {
		prop2: 'value2',
		prop3: 'value3',
		}, { detail: 'Certain detail' } );
		```

		└ Observers recieve this value on their `mutation.detail` property.

		```js
		// An observer with detail
		Observer.observe( obj, 'prop1', mutation => {
		console.log( 'A mutation has been made with detail:' + mutation.detail );
		} );
		```

		### Method: `Observer.intercept()`

		Intercept operations on any object or array before they happen!
		Intercept operations on any object or array before they happen! This helps you extend standard operations on an object - `Observer.set()`, `Observer.deleteProperty()`, etc - using Proxy-like traps.

		```js
		// Signature 1
		Observer.intercept( obj, type, handler[, options = {} ]);
		```

		```js
		// Signature 2
		Observer.intercept( obj, traps[, options = {} ]);
		```

		#### Usage

		Extend standard operations on an object - `Observer.set()`, `Observer.deleteProperty()`, etc - with custom traps using the [`Observer.intercept()`](https://webqit.io/tooling/observer/docs/api/reactions/intercept) method!

		└ Below, we intercept all "set" operations for an HTTP URL then transform it to an HTTPS URL.
		@@ -445,0 +388,0 @@

@webqit/observer - npm Package Compare versions

Worsened metrics