@webqit/observer 2.1.2 → 2.1.3

package/README.md

@@ -6,62 +6,34 @@
 
 <!-- /BADGES -->
 
-A web-native object observability API!
+**[Motivation](#motivation) • [Overview](#an-overview) • [Polyfill](#the-polyfill) • [Design Discussion](#design-discussion) • [Getting Involved](#getting-involved) • [License](#license)**
 
-Observe and intercept operations on any type of JavaScript objects and arrays, using a notably lightweight and predictable utility-first reactivity API!
+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 extends it with the best of JavaScript's other [reflection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect) and interception APIs - *Proxies*, *accessors* - to support any kind of reactive programming model!
 
-## Motivation
-
-Tracking mutations on JavaScript objects has historically relied on "object wrapping" with [ES6 Proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) and "property mangling" with [getters and setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty). Besides the *object identity trade-off* problem of the first and the *property compromisal* problem of the second, there is also the "scalability" issue inherent to the techniques and much "inflexibility" in the programming model they enable:
-
-+ **Scalability**: objects have to be created a certain way, or purpose-built for the specific technique, to participate in the reactive system; objects *you don't own* have to be altered in some way - where that's even possible - to be onboarded into the reactivity system. Scalability is hamstrung as we must fulfill the **implementation criteria** for as many objects as will be needed in the design - clamped to the finite number of objects that can be made to work this way!
-
-+ **Programming model**: proxy traps and object accessors by design only interface with one listenining logic in the entire program. Objects are effectively open to multiple interactions on the outside but closed-off to one observer on the inside, enabling just a "many to one" model. This does not correctly reflect the most common usecases where the idea is to have any number of listeners per event; i.e. a "many to many" model! It takes yet a non-trivial effort to go from the default model to the one desired.
-
-Surprisingly, we at one time had an *object observability* primitive that checked all the boxes and touched the very pain points we have today: the [`Object.observe()`](https://web.dev/es7-observe/) API. How about an equivalent API that brings all of the good thinking from `Object.observe()` together with the idea of *Proxies* and *accessors* in one design, delivered as one utility for all things *reactivity*? This is the idea with the new **Observer API**!
-
-## Table of Contents
-
-+ [Motivation](#motivation)
-+ [Download Options](#download-options)
-+ [An Overview](#an-overview)
-  + [Method: `Observer.observe()`](#method-observerobserve)
-    + [Concept](#concept)
-    + [Concept: *Mutations*](#concept-mutations)
-    + [Concept: *Batch Mutations*](#concept-batch-mutations)
-    + [Concept: *Custom Details*](#concept-custom-details)
-    + [Concept: *Diffing*](#concept-diffing)
-  + [Method: `Observer.intercept()`](#method-observerintercept)
-    + [Concept](#concept)
-+ [Design Discussion](#design-discussion)
-+ [Issues](#issues)
-+ [License](#license)
+Observer API is an upcoming proposal!
 
-## Download Options
+## Motivation
 
-**_Use as an npm package:_**
+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 trade-off* problem of the first and the *property compromisal* problem of the second, there is also the "scalability" issue inherent to the techniques and much "inflexibility" in the programming model they enable:
 
-```bash
-npm i @webqit/observer
-```
++ **Scalability**: objects have to be created a certain way, or be purpose-built for the specific technique, to participate in the reactivity system; objects *you don't own* have to be altered in some way - where that's even possible - to be onboarded into the reactivity system. Scalability is inhibited as we must fulfill the **implementation criteria** for as many objects as will be needed in the design - clamped to the finite number of objects that can be made to work this way! 
 
-```js
-// Import
-import Observer from '@webqit/observer';;
-```
++ **Programming model**: proxy traps and object accessors only lend themselves to being wired to *one* underlying listenining logic in the entire program. Objects are effectively open to multiple interactions on the outside but "locked" to one observer on the inside, enabling just a "many to one" communication model. This does not correctly reflect the most common usecases where the idea is to have any number of listeners per event, to enable a "many to many" model! It takes yet a non-trivial amount of effort to go from the default model to the one desired.
 
-**_Use as a script:_**
+Interestingly, we at one time had an *object observability* primitive that checked all the boxes and touched the very pain points we have today: the [`Object.observe()`](https://web.dev/es7-observe/) API. So, how about an equivalent API that brings all of the good thinking from `Object.observe()` together with the idea of *Proxies*, *accessors*, and JavaScript's other [*reflection* API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect) in one design, delivered as one utility for all things *reactivity*? This is the idea with the new **Observer API**!
 
-```html
-<script src="https://unpkg.com/@webqit/observer/dist/main.js"></script>
-```
+## An Overview
 
-```js
-// Obtain the APIs
-const Observer = window.webqit.Observer;
-```
+The Observer API comes as a set of utility functions.
 
-## An Overview
++ [Method: `Observer.observe()`](#method-observerobserve)
+  + [Concept](#concept)
+  + [Concept: *Mutation APIs*](#concept-mutation-apis)
+  + [Concept: *Batch Mutations*](#concept-batch-mutations)
+  + [Concept: *Custom Details*](#concept-custom-details)
+  + [Concept: *Diffing*](#concept-diffing)
++ [Method: `Observer.intercept()`](#method-observerintercept)
+  + [Concept](#concept-1)
 
 > **Note**
 > <br>This is documentation for `Observer@2.x`. (Looking for [`Observer@1.x`](https://github.com/webqit/observer/tree/v1.7.6)?)
@@ -131,7 +103,7 @@ Observer.observe( obj, mutations => {
 abortController.abort();
 ```
 
-#### Concept: *Mutations*
+#### Concept: *Mutation APIs*
 
 Programmatically mutate properties of an object using the *[Reflect](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect#static_methods)-like* set of operators; each operation will be reported by observers:
 
@@ -416,13 +388,44 @@ Observer.intercept( obj, {
 } );
 ```
 
+## The Polyfill
+
+**_Use as an npm package:_**
+
+```bash
+npm i @webqit/observer
+```
+
+```js
+// Import
+import Observer from '@webqit/observer';;
+```
+
+**_Use as a script:_**
+
+```html
+<script src="https://unpkg.com/@webqit/observer/dist/main.js"></script>
+```
+
+> 4.54 KB min+compressed | 12.85 KB min
+
+```js
+// Obtain the APIs
+const Observer = window.webqit.Observer;
+```
+
 ## Design Discussion
 
 *[TODO]*
 
-## Issues
+## Getting Involved
+
+All forms of contributions are welcome at this time. For example, implementation details are all up for discussion. And here are specific links:
 
-To report bugs or request features, please submit an [issue](https://github.com/webqit/observer/issues).
++ [Project](https://github.com/webqit/observer)
++ [Documentation](https://github.com/webqit/observer/wiki)
++ [Discusions](https://github.com/webqit/observer/discussions)
++ [Issues](https://github.com/webqit/observer/issues)
 
 ## License
 

package/package.json

@@ -12,7 +12,7 @@
     "events"
   ],
   "homepage": "https://webqit.io/tooling/observer",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",