@webqit/observer - npm Package Compare versions

Comparing version 2.1.10 to 2.1.11

package.json

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

README.md

@@ -9,3 +9,3 @@ # The Observer API
 
-**[Motivation](#motivation) • [Overview](#an-overview) • [Polyfill](#the-polyfill) • [Design Discussion](#design-discussion) • [Getting Involved](#getting-involved) • [License](#license)**
+**[Motivation](#motivation) • [Overview](#an-overview) • [Documentation](#documentation) • [Polyfill](#the-polyfill) • [Getting Involved](#getting-involved) • [License](#license)**
 
@@ -18,3 +18,3 @@ Observe and intercept operations on arbitrary JavaScript objects and arrays using a utility-first, general-purpose reactivity API! This API re-explores the unique design of the [`Object.observe()`](https://web.dev/es7-observe/) API and takes a stab at what could be **a unifying API** over *related but disparate* things like `Object.observe()`, [Reflect](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect) APIs, and the "traps" API (proxy traps)!
 
-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 the *object identity* problem of the first and the *object compromissory* nature of the second, there is also the "scalability" issue inherent to the techniques and 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 they enable!
 
@@ -29,18 +29,2 @@ 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>
 
-<details>
-<summary><b>Show Outline</b></summary>
-
-+ [Method: `Observer.observe()`](#method-observerobserve)
-  + [Usage](#usage)
-  + [Concept: *Mutation APIs*](#concept-mutation-apis)
-  + [Concept: *Paths*](#concept-paths)
-  + [Concept: *Batch Mutations*](#concept-batch-mutations)
-  + [Concept: *Custom Details*](#concept-custom-details)
-  + [Concept: *Diffing*](#concept-diffing)
-+ [Method: `Observer.intercept()`](#method-observerintercept)
-  + [Usage](#usage-1)
-+ [API Reference](#api-reference)
-
-</details>
-
 > **Note**
@@ -76,3 +60,3 @@ > <br>This is documentation for `Observer@2.x`. (Looking for [`Observer@1.x`](https://github.com/webqit/observer/tree/v1.7.6)?)
 // Mtation observer on an object
-const abortController = Observer.observe( obj, handleChanges );
+const abortController = Observer.observe( obj, inspect );
 ```
@@ -84,10 +68,10 @@
 // Mtation observer on an array
-const abortController = Observer.observe( arr, handleChanges );
+const abortController = Observer.observe( arr, inspect );
 ```
 
-└ *Changes are delivered [**synchronously**](https://dev.to/oxharris/reinvestigating-reactivity-22e0-temp-slug-5973064?preview=8afd0f8b156bf0b0b1c08058837fe4986054e52a7450f0a28adbaf07dcb7f5659b724166f553fb98ceab3d080748e86b244684f515d579bcd0f48cbb#timing-and-batching) - as they happen.*
+└ *Changes are delivered [**synchronously**](https://github.com/webqit/observer/wiki/#timing-and-batching) - as they happen.*
 
 ```js
 // The change handler
-function handleChanges( mutations ) {
+function inspect( mutations ) {
     mutations.forEach( mutation => {
@@ -111,3 +95,3 @@ console.log( mutation.type, mutation.key, mutation.value, mutation.oldValue );
 const abortController = new AbortController;
-Observer.observe( obj, handleChanges, { signal: abortController.signal } );
+Observer.observe( obj, inspect, { signal: abortController.signal } );
 ```
@@ -127,9 +111,15 @@
     // Child
-    Observer.observe( obj, handleChanges, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
+    Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
 
+    Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
+
 } );
 ```
 
-└ *"Child" gets automatically aborted at parent's "next turn", and at parent's own abortion!*
+> **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!*
+
 #### Concept: *Mutation APIs*
@@ -277,3 +267,3 @@
 
-Observe "the value" at a path in a given tree:
+Observe "a property" at a path in a given tree:
 
@@ -436,27 +426,2 @@ ```js
 
-#### Concept: *Diffing*
-
-Receive notifications only for mutations that actually change property state, and ignore those that don't.
-
-```js
-// Responding to state changes only
-Observer.observe( obj, handleChanges, { diff: true } );
-```
-
-```js
-// Recieved
-Observer.set( obj, 'prop0', 'value' );
-```
-
-```js
-// Ignored
-Observer.set( obj, 'prop0', 'value' );
-```
-
-<!--
-### Concept: *Live*
-descripted
-namespace
--->
-
 ### Method: `Observer.intercept()`
@@ -528,16 +493,11 @@
 
-## The Polyfill
+## Documentation
 
-**_Use as an npm package:_**
+Visit the [docs](https://github.com/webqit/observer/wiki) for all what's possible - including [Reflect APIs](https://github.com/webqit/observer/wiki#featuring-reflect-apis-extended), [Timing and Batching](https://github.com/webqit/observer/wiki#timing-and-batching), [API Reference](https://github.com/webqit/observer/wiki#putting-it-all-together), etc.
 
-```bash
-npm i @webqit/observer
-```
+## The Polyfill
 
-```js
-// Import
-import Observer from '@webqit/observer';;
-```
+The Observer API is being developed as something to be used today - via a polyfill. The polyfill features all of what's documented - with limitations in the area of making mutations: you can only make mutations using the [Mutation APIs](#concept-mutation-apis).
 
-**_Use as a script:_**
+<details><summary>Load from a CDN</summary>
 
@@ -548,3 +508,3 @@ ```html
 
-> 4.4 kB min + gz | 13.9 KB min [↗](https://bundlephobia.com/package/@webqit/observer@2.1.4)
+> `4.4` kB min + gz | `13.9` KB min [↗](https://bundlephobia.com/package/@webqit/observer)
 
@@ -556,62 +516,17 @@ ```js
 
-## API Reference
+</details>
 
-<!--
+<details><summary>Install from NPM</summary>
 
-| Observer API | Reflect API | Description | Trap |
-| -------------- | ------------ | ----------- | --------------- |
-| `apply()`   | ✓    | Invokes a  function [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/apply) | `apply() {}` |
-| `batch()`   | `×`   | Creates a batching context [↗](https://github.com/webqit/observer#:~:text=use%20the%20observer.batch()%20to%20batch%20multiple%20arbitrary%20mutations%20-%20whether%20related%20or%20not) | `-` |
-| `construct()`   | ✓    | Initializes a constructor [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/construct) | `construct() {}` |
-| `defineProperties()` [↗]()   | `×`    | `defineProperty() {}` |
-| `defineProperty()`   | ✓    | Defines a property [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/defineProperty) | `defineProperty() {}` |
-| `deleteProperties()` [↗]()   | `×`    | `deleteProperty() {}` |
-| `deleteProperty()`   | ✓    | Deletes a property [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/deleteProperty) | `deleteProperty() {}` |
-| `get()`   | ✓    | Reads a property [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/get) | `get() {}` |
-| `getOwnPropertyDescriptor()`        | ✓    | Obtains property descriptor [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getOwnPropertyDescriptor) | `getOwnPropertyDescriptor() {}`     |
-| `getPrototypeOf()`  | ✓    | Obtains object prototype [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getPrototypeOf) | `getPrototypeOf() {}` |
-| `has()`   | ✓    | Checks property existence [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/has) | `has() {}` |
-| `intercept()`   | `×`   | Binds a "traps" object [↗](https://github.com/webqit/observer#method-observerintercept) | `-` |
-| `isExtensible()`   | ✓    | Checks object extensibility [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/isExtensible) | `isExtensible() {}` |
-| `observe()`   | `×`  | Binds a mutation observer [↗](https://github.com/webqit/observer#method-observerobserve) | `-` |
-| `ownKeys()`   | ✓    | Obtains object keys [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/ownKeys) | `ownKeys() {}` |
-| `path()`   | `×`   | Evaluates a path [↗](#) | `-` |
-| `preventExtensions()`   | ✓    | Prevents object extensibility [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/preventExtensions) | `preventExtensions() {}` |
-| `set()`   | ✓    | Sets a property [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/set) | `set() {}` |
-| `setPrototypeOf()`   | ✓    | Sets object prototype [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/setPrototypeOf) | `setPrototypeOf() {}` |
-| . | . | . | . |
-| `accessorize()`   | `×`  | Applies pre-intercepted getters/setters to properties [↗](https://github.com/webqit/observer#:~:text=enable%20reactivity%20on%20specific%20properties%20with%20literal%20object%20accessors%20-%20using%20the%20observer.accessorize()%20method) | `-` |
-| `proxy()`   | `×`  | Creates a pre-intercepted proxy object [↗](https://github.com/webqit/observer#:~:text=enable%20reactivity%20on%20arbitray%20properties%20with%20proxies%20-%20using%20the%20observer.proxy()%20method) | `-` |
+```bash
+npm i @webqit/observer
+```
 
--->
+```js
+// Import
+import Observer from '@webqit/observer';;
+```
 
-| Observer API | Reflect API | Trap |
-| -------------- | ------------ | ----------- |
-| `apply()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/apply)   | ✓    | `apply() {}` |
-| `batch()` [↗](https://github.com/webqit/observer#concept-batch-mutations)   | `×`   | `-` |
-| `construct()`  [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/construct)  | ✓    | `construct() {}` |
-| `defineProperties()` [↗]()   | `×`    | `defineProperty() {}` |
-| `defineProperty()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/defineProperty)   | ✓    | `defineProperty() {}` |
-| `deleteProperties()` [↗]()   | `×`    | `deleteProperty() {}` |
-| `deleteProperty()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/deleteProperty)   | ✓    | `deleteProperty() {}` |
-| `get()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/get)   | ✓    | `get() {}` |
-| `getOwnPropertyDescriptor()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getOwnPropertyDescriptor)        | ✓    | `getOwnPropertyDescriptor() {}`     |
-| `getPrototypeOf()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getPrototypeOf)  | ✓    | `getPrototypeOf() {}` |
-| `has()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/has)   | ✓    | `has() {}` |
-| `intercept()`[↗](https://github.com/webqit/observer#method-observerintercept)   | `×`   | `-` |
-| `isExtensible()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/isExtensible)   | ✓    | `isExtensible() {}` |
-| `observe()` [↗](https://github.com/webqit/observer#method-observerobserve)   | `×`  | `-` |
-| `ownKeys()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/ownKeys)   | ✓    | `ownKeys() {}` |
-| `path()` [↗](https://github.com/webqit/observer#concept-paths)   | `×`   | `-` |
-| `preventExtensions()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/preventExtensions)   | ✓    | `preventExtensions() {}` |
-| `set()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/set)   | ✓    | `set() {}` |
-| `setPrototypeOf()` [↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/setPrototypeOf)   | ✓    | `setPrototypeOf() {}` |
-| . | . | . | . |
-| `accessorize()` [↗](https://github.com/webqit/observer#:~:text=enable%20reactivity%20on%20specific%20properties%20with%20literal%20object%20accessors%20-%20using%20the%20observer.accessorize()%20method)   | `×`  | `-` |
-| `proxy()` [↗](https://github.com/webqit/observer#:~:text=enable%20reactivity%20on%20arbitray%20properties%20with%20proxies%20-%20using%20the%20observer.proxy()%20method)   | `×`  | `-` |
+</details>
 
-## Design Discussion
-
-[See more in the introductory blog post](https://dev.to/oxharris/reinvestigating-reactivity-22e0-temp-slug-5973064?preview=8afd0f8b156bf0b0b1c08058837fe4986054e52a7450f0a28adbaf07dcb7f5659b724166f553fb98ceab3d080748e86b244684f515d579bcd0f48cbb#introducing-the-observer-api)<sup>draft</sup>
-
 ## Getting Involved
@@ -618,0 +533,0 @@

No alert changes

Worsened metrics

Total package byte prevSize

159418

decreased by-4.44%

Number of lines in readme file

532

decreased by-13.78%

No dependency changes