@webqit/observer 3.8.3 → 3.8.5

package/README.md

@@ -1,10 +1,14 @@
-# Observer
+<div align="center">
+
+# The Observer API
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![bundle][bundle-src]][bundle-href]
 [![License][license-src]][license-href]
 
+</div>
+
 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 unifies that with related APIs like Reflect and Proxy "traps"!
 
 The Observer API comes as one little API for all things _object observability_. (Only `~5.8KiB min|zip`)
@@ -172,16 +176,16 @@ Observer.set(user, 'email', 'JOHN@EXAMPLE.COM'); // Becomes 'john@example.com'
 ## Key Features
 
 ### **Core Reactivity**
-- **🔄 Real-time Observation**: Watch object and array changes as they happen
-- **⚡ Synchronous Updates**: Changes are delivered immediately, not batched
-- **🎯 Granular Control**: Watch specific properties, paths, or entire objects
-- **🌳 Deep Path Watching**: Observe nested properties with wildcards and subtrees
+- **🔄 Real-time Observability**: Watch object and array changes as they happen
+- **⚡ Synchronous Updates**: Changes are delivered synchronously, not batched
+- **🎯 Granular Control**: Watch specific properties, paths; even wildcards
+- **🌳 Deep Path Watching**: Observe nested properties or entire object tree
 
 ### **Advanced Capabilities**
 - **🛡️ Operation Interception**: Transform, validate, or block operations before execution
-- **📦 Atomic Batching**: Group multiple changes into single events
-- **🔄 Object Mirroring**: Create reactive synchronization between objects
 - **🔗 Traps Pipeline**: Compose multiple interceptors for complex behavior
+- **📦 Atomic Batching**: Batch multiple changes into single atomic operation
+- **🔄 Object Mirroring**: Create reactive synchronization between objects
 
 ### **Developer Experience**
 - **🔧 Utility-First API**: Clean, functional design with consistent patterns
@@ -191,19 +195,19 @@ Observer.set(user, 'email', 'JOHN@EXAMPLE.COM'); // Becomes 'john@example.com'
 
 ## Ecosystem Integrations
 
-The Observer API is enabling a shared protocol of mutation-based reactivity across the ecosystem:
+The Observer API is enabling a shared protocol for *mutation-based* reactivity across the ecosystem:
 
 ### **🚀 [Quantum Runtime](https://github.com/webqit/quantum-js)**
 Uses Observer API under the hood to operate as a **full-fledged reactive runtime**. Quantum enables Imperative Reactive Programming by leveraging Observer's reactivity foundation to make ordinary JavaScript code reactive.
 
 ### **🌐 [OOHTML](https://github.com/webqit/oohtml)**
-Uses Observer API to underpin **reactive HTML templating**. OOHTML leverages Observer's reactivity layer to create dynamic, data-driven templates with seamless integration between data and presentation.
+Uses Observer API to underpin **dynamic, reactive UIs**. OOHTML enables live data binding between UI and app state, automatically updating the DOM when your data changes.
 
 ### **⚡ [Webflo](https://github.com/webqit/webflo)**
-Uses Observer API to underpin **Live Objects** as a first-class concept. Webflo leverages Observer's reactivity foundation to enable real-time data synchronization across client and server.
+Uses Observer API to underpin **Live Objects** as a first-class concept. Live Objects in Webflo lets you send dynamic state from your server to the UI with reactivity over the wire.
 
 ### **🔗 [LinkedQL](https://github.com/linked-db/linked-ql)**
-Uses Observer API to underpin **Live Objects** as a first-class concept. LinkedQL leverages Observer's reactivity foundation to provide reactive database operations with real-time data synchronization.
+Uses Observer API to underpin **Live Objects** as a first-class concept. Live Objects in LinkedQL lets you have query results as self-updating result sets.
 
 ## API Reference
     

package/package.json

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

package/README copy.md

@@ -1,500 +0,0 @@
-# The Observer API
-
-<!-- BADGES/ -->
-
-<span class="badge-npmversion"><a href="https://npmjs.org/package/@webqit/observer" title="View this project on NPM"><img src="https://img.shields.io/npm/v/@webqit/observer.svg" alt="NPM version" /></a></span> <span class="badge-npmdownloads"><a href="https://npmjs.org/package/@webqit/observer" title="View this project on NPM"><img src="https://img.shields.io/npm/dm/@webqit/observer.svg" alt="NPM downloads" /></a></span>
-
-<!-- /BADGES -->
-
-**[Motivation](#motivation) • [Overview](#an-overview) • [Documentation](#documentation) • [Polyfill](#the-polyfill) • [Getting Involved](#getting-involved) • [License](#license)**
-
-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)!
-
-Observer API is an upcoming proposal!
-
-## Motivation
-
-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 each enables!
-
-This is discussed extensively in [the introductory blog post](https://dev.to/oxharris/re-exploring-reactivity-and-introducing-the-observer-api-and-reflex-functions-4h70)
-
-We find a design precedent to object observability in the [`Object.observe()`](https://web.dev/es7-observe/) API, which at one time checked all the boxes and touched the very pain points we have today! The idea with the new **Observer API** is to re-explore that unique design with a more wholistic approach that considers the broader subject of Reactive Programming in JavaScript!
-
-## Status
-
-+ Working implementation via a polyfill
-+ Integral to the [Quantum JS project](https://github.com/webqit/quantum-js)
-+ Actively developed
-+ Open to contributions
-
-## An Overview
-
-The Observer API is a set of utility functions - notably, the `Observer.observe()` and `Observer.intercept()` methods - for all things object observability.
-
-<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 arbitrary objects or arrays!
-
-```js
-// An object
-const obj = {};
-// Mtation observer on an object
-const abortController = Observer.observe( obj, inspect );
-```
-
-```js
-// An array
-const arr = [];
-// Mtation observer on an array
-const abortController = Observer.observe( arr, inspect );
-```
-
-└ *Changes are delivered [**synchronously**](https://github.com/webqit/observer/wiki/#timing-and-batching) - as they happen.*
-
-```js
-// The change handler
-function inspect( mutations ) {
-    mutations.forEach( mutation => {
-        console.log( mutation.type, mutation.key, mutation.value, mutation.oldValue );
-    } );
-}
-```
-
-**-->** Stop observing at any time by calling `abort()` on the returned *abortController*:
-
-```js
-// Remove listener
-abortController.abort();
-```
-
-└ And you can provide your own [Abort Signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance:
-
-```js
-// Providing an AbortSignal
-const abortController = new AbortController;
-Observer.observe( obj, inspect, { signal: abortController.signal } );
-```
-
-```js
-// Abort at any time
-abortController.abort();
-```
-
-**-->** Where listeners initiate nested observers (child observers), leverage "AbortSignal-cascading" to tie child observers to parent observer's lifecycle:
-
-```js
-// Parent - 
-const abortController = Observer.observe( obj, ( mutations, flags ) => {
-
-    // Child
-    Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
-
-    // Child
-    Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
-
-} );
-```
-
-└ *"Child" observers get automatically aborted at parent's "next turn", and at parent's own abortion!*
-
-**-->** Use the `options.diff` parameter to ignore mutation events whose current value is same as previous value:
-
-```js
-// Parent - 
-const abortController = Observer.observe( obj, mutations => {
-  console.log( m.type, m.value, m.oldValue );
-}, { diff: true } );
-```
-
-```js
-obj.property = 'Same value';
-```
-
-```js
-obj.property = 'Same value';
-```
-
-└ *Observer is called only on the first update!*
-
-#### Concept: *Mutation APIs*
-
-In addition to making literal operations, you can also 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:
-
-```js
-// A single "set" operation on an object
-Observer.set( obj, 'prop0', 'value0' );
-Observer.defineProperty( obj, 'prop1', { get: () => 'value1' } );
-Observer.deleteProperty( obj, 'prop2' );
-```
-
-```js
-// A single "set" operation on an array
-Observer.set( arr, 0, 'item0' ); // Array [ 'item0' ]
-Observer.deleteProperty( arr, 0 ); // Array [ <1 empty slot> ]
-```
-
-<details><summary>Polyfill limitations</summary>
-
-In the polyfill, object observability doesn't work with literal operations. **Beware non-reactive operations**:
-
-```js
-// Literal object operators
-delete obj.prop0;
-obj.prop3 = 'value3';
-```
-
-```js
-// Array methods
-arr.push( 'item3' );
-arr.pop();
-```
-
-</details>
-
-**-->** Enable reactivity on *specific* properties with literal *object accessors* - using the `Observer.accessorize()` method:
-
-```js
-// Accessorize all current enumerable properties
-Observer.accessorize( obj );
-// Accessorize specific properties (existing or new)
-Observer.accessorize( obj, [ 'prop0', 'prop1', 'prop2' ] );
-
-// Make reactive UPDATES
-obj.prop0 = 'value0';
-obj.prop1 = 'value1';
-obj.prop2 = 'value2';
-```
-
-```js
-// Accessorize all current indexes
-Observer.accessorize( arr );
-// Accessorize specific indexes (existing or new)
-Observer.accessorize( arr, [ 0, 1, 2 ] );
-
-// Make reactive UPDATES
-arr[ 0 ] = 'item0';
-arr[ 1 ] = 'item1';
-arr[ 2 ] = 'item2';
-
-// Bonus reactivity with array methods that re-index existing items
-arr.unshift( 'new-item0' );
-arr.shift();
-```
-
-<details><summary>Polyfill limitations</summary>
-
-In the polyfill, object observability doesn't work with literal operations. **Beware non-reactive operations**:
-
-```js
-// The delete operator and object properties that haven't been accessorized
-delete obj.prop0;
-obj.prop3 = 'value3';
-```
-
-```js
-// Array methods that do not re-index existing items
-arr.push( 'item0' );
-arr.pop();
-```
-
-</details>
-
-**-->** Enable reactivity on *arbitray* properties with *Proxies* - using the `Observer.proxy()` method:
-
-```js
-// Obtain a reactive Proxy for an object
-const $obj = Observer.proxy( obj );
-
-// Make reactive operations
-$obj.prop1 = 'value1';
-$obj.prop4 = 'value4';
-$obj.prop8 = 'value8';
-
-// With the delete operator
-delete $obj.prop0;
-```
-
-```js
-// Obtain a reactive Proxy for an array
-const $arr = Observer.proxy( arr );
-
-// Make reactive operations
-$arr[ 0 ] = 'item0';
-$arr[ 1 ] = 'item1';
-$arr[ 2 ] = 'item2';
-
-// With an instance method
-$arr.push( 'item3' );
-```
-
-└ *And no problem if you end up nesting the approaches.*
-
-```js
-// 'value1'-->obj
-Observer.accessorize( obj, [ 'prop0', 'prop1', 'prop2', ] );
-obj.prop1 = 'value1';
-
-// 'value1'-->$obj-->obj
-let $obj = Observer.proxy( obj );
-$obj.prop1 = 'value1';
-
-// 'value1'-->set()-->$obj-->obj
-Observer.set( $obj, 'prop1', 'value1' );
-```
-
-**-->** "Restore" accessorized properties to their normal state by calling the `unaccessorize()` method:
-
-```js
-Observer.unaccessorize( obj, [ 'prop1', 'prop6', 'prop10' ] );
-```
-
-**-->** "Reproduce" original objects from Proxies obtained via `Observer.proxy()` by calling the `unproxy()` method:
-
-```js
-obj = Observer.unproxy( $obj );
-```
-
-#### Concept: *Paths*
-
-Observe "a property" at a path in an object tree:
-
-```js
-const obj = {
-  level1: {
-    level2: 'level2-value',
-  },
-};
-```
-
-```js
-const path = Observer.path( 'level1', 'level2' );
-Observer.observe( obj, path, m => {
-  console.log( m.type, m.path, m.value, m.isUpdate );
-} );
-```
-
-```js
-Observer.set( obj.level1, 'level2', 'level2-new-value' );
-```
-
-<details><summary>Console</summary>
-
-| type | path | value | isUpdate |
-| ---- | ---- | ----- | -------- |
-| `set` | [ `level1`, `level2`, ] | `level2-new-value` | `true` |
-
-</details>
-
-└ *And the initial tree structure can be whatever*:
-
-```js
-// A tree structure that is yet to be built
-const obj = {};
-```
-
-```js
-const path = Observer.path( 'level1', 'level2', 'level3', 'level4' );
-Observer.observe( obj, path, m => {
-  console.log( m.type, m.path, m.value, m.isUpdate );
-} );
-```
-
-└ *Now, any operation that changes what "the value" at the path resolves to - either by tree extension or tree truncation - will fire our listener*:
-
-```js
-Observer.set( obj, 'level1', { level2: {}, } );
-```
-
-<details>
-<summary>Console</summary>
-
-| type | path | value | isUpdate |
-| ---- | ---- | ----- | -------- |
-| `set` | [ `level1`, `level2`, `level3`, `level4`, ] | `undefined` | `false` |
-
-</details>
-
-└ *Meanwhile, this next one completes the tree, and the listener reports a value at its observed path*:
-
-```js
-Observer.set( obj.level1, 'level2', { level3: { level4: 'level4-value', }, } );
-```
-
-<details>
-<summary>Console</summary>
-
-| type | path | value | isUpdate |
-| ---- | ---- | ----- | -------- |
-| `set` | [ `level1`, `level2`, `level3`, `level4`, ] | `level4-value` | `false` |
-
-</details>
-
-**-->** Use the event's `context` property to inspect the parent event if you were to find the exact point at which mutation happened in the path in an audit trail:
-
-```js
-let context = m.context;
-console.log(context);
-```
-
-└ *And up again one level until the root event*:
-
-```js
-let parentContext = context.context;
-console.log(parentContext);
-```
-
-**-->** Observe trees that are built *asynchronously*! Where a promise is encountered along the path, further access is paused until promise resolves:
-
-```js
-Observer.set( obj.level1, 'level2', Promise.resolve( { level3: { level4: 'level4-value', }, } ) );
-```
-
-#### Concept: *Batch Mutations*
-
-Make multiple mutations at a go, and they'll be correctly delivered as a batch to observers!
-
-```js
-// Batch operations on an object
-Observer.set( obj, {
-    prop0: 'value0',
-    prop1: 'value1',
-    prop2: 'value2',
-} );
-Observer.defineProperties( obj, {
-    prop0: { value: 'value0' },
-    prop1: { value: 'value1' },
-    prop2: { get: () => 'value2' },
-} );
-Observer.deleteProperties( obj, [ 'prop0', 'prop1', 'prop2' ] );
-```
-
-```js
-// Batch operations on an array
-Observer.set( arr, {
-    '0': 'item0',
-    '1': 'item1',
-    '2': 'item2',
-} );
-Object.proxy( arr ).push( 'item3', 'item4', 'item5', );
-Object.proxy( arr ).unshift( 'new-item0' );
-Object.proxy( arr ).splice( 0 );
-```
-
-**-->** Use the `Observer.batch()` to batch multiple arbitrary mutations - whether related or not:
-
-```js
-Observer.batch( arr, async () => {
-    Observer.set( arr, 0, 'item0' ); // Array [ 'item0' ]
-    await somePromise();
-    Observer.set( arr, 2, 'item2' ); // Array [ 'item0', <1 empty slot>, 'item2' ]
-} );
-```
-
-> Method calls on a proxied instance - e.g. `Object.proxy( arr ).splice( 0 )` - also follow this strategy.
-
-### Method: `Observer.intercept()`
-
-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.
-
-└ *Below, we intercept all "set" operations for an HTTP URL then transform it to an HTTPS URL.*
-
-```js
-const setTrap = ( operation, previous, next ) => {
-    if ( operation.key === 'url' && operation.value.startsWith( 'http:' ) ) {
-        operation.value = operation.value.replace( 'http:', 'https:' );
-    }
-    return next();
-};
-Observer.intercept( obj, 'set', setTrap );
-```
-
-└ *Now, only the first of the following will fly as-is.*
-
-```js
-// Not transformed
-Observer.set( obj, 'url', 'https://webqit.io' );
-
-// Transformed
-Observer.set( obj, 'url', 'http://webqit.io' );
-```
-
-└ *And below, we intercept all "get" operations for a certain value to trigger a network fetch behind the scenes.*
-
-```js
-const getTrap = ( operation, previous, next ) => {
-    if ( operation.key === 'token' ) {
-        return next( fetch( tokenUrl ) );
-    }
-    return next();
-};
-Observer.intercept( obj, 'get', getTrap );
-```
-
-└ *And all of that can go into one "traps" object:*
-
-```js
-Observer.intercept( obj, {
-    get: getTrap,
-    set: setTrap,
-    deleteProperty: deletePropertyTrap,
-    defineProperty: definePropertyTrap,
-    ownKeys: ownKeysTrap,
-    has: hasTrap,
-    // etc
-} );
-```
-
-## Documentation
-
-Visit the [docs](https://github.com/webqit/observer/wiki) for full details - including [Reflect API Supersets](https://github.com/webqit/observer/wiki#featuring-reflect-api-supersets), [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.
-
-## The Polyfill
-
-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).
-
-<details><summary>Load from a CDN</summary>
-
-```html
-<script src="https://unpkg.com/@webqit/observer/dist/main.js"></script>
-```
-
-> `4.4` kB min + gz | `13.9` KB min [↗](https://bundlephobia.com/package/@webqit/observer)
-
-```js
-// Obtain the APIs
-const Observer = window.webqit.Observer;
-```
-
-</details>
-
-<details><summary>Install from NPM</summary>
-
-```bash
-npm i @webqit/observer
-```
-
-```js
-// Import
-import Observer from '@webqit/observer';;
-```
-
-</details>
-
-## 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:
-
-+ [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
-
-MIT.