@webqit/observer 3.8.2 → 3.8.4

package/README.md

@@ -1,500 +1,1134 @@
-# The Observer API
+# Observer
 
-<!-- BADGES/ -->
+[![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]
 
-<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>
+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"!
 
-<!-- /BADGES -->
+The Observer API comes as one little API for all things _object observability_. (Only `~5.8KiB min|zip`)
 
-**[Motivation](#motivation) • [Overview](#an-overview) • [Documentation](#documentation) • [Polyfill](#the-polyfill) • [Getting Involved](#getting-involved) • [License](#license)**
+```js
+const state = {};
+
+// Make mutations observable
+Observer.observe(state, (mutations) => {
+  mutations.forEach(mutation => {
+    console.log(`${mutation.type}: ${mutation.key} = ${mutation.value}`);
+    // React to any mutation: set, delete, defineProperty, etc.
+  });
+});
+
+// Now these mutations are observable and reactive
+Observer.set(state, 'count', 5);
+Observer.deleteProperty(state, 'oldProp');
+```
 
-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)!
+> [!TIP]
+> While reactivity is anchored on the programmtic APIs — `.set()`, `.deleteProperty()`, etc. — reactivity is also possible over literal JavaScript operations like `obj.prop = value`, `delete obj.prop` — by means of the `accessorize()` and `proxy()` methods covered just ahead.
+>
+> For full-fledged Imperative Reactive Programming, you may to see the [Quantum JS](https://github.com/webqit/quantum-js) project.
 
-Observer API is an upcoming proposal!
+<details><summary>Looking for Observer@1.x?</summary>
 
-## Motivation
+This documentation is for Observer@2.x. For the previous version, see [Observer@1.x](https://github.com/webqit/observer/tree/v1.7.6).
 
-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!
+</details>
 
-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)
+- [Why Observer](#why-observer)
+- [Quick Start](#quick-start)
+- [Key Features](#key-features)
+- [Ecosystem Integrations](#ecosystem-integrations)
+- [API Reference](#api-reference)
+- [Extended Documentation](#extended-documentation)
+- [Contributing](#contributing)
 
-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!
+## Why Observer?
 
-## Status
+JavaScript is *inherently* a mutable language but lacks a built-in way to observe said mutations. When you do `obj.prop = value` or `delete obj.prop`, there's no mechanism to detect those changes.
 
-+ Working implementation via a polyfill
-+ Integral to the [Quantum JS project](https://github.com/webqit/quantum-js)
-+ Actively developed
-+ Open to contributions
+**The Problem:**
 
-## An Overview
+```js
+const state = { count: 0, items: [] };
 
-The Observer API is a set of utility functions - notably, the `Observer.observe()` and `Observer.intercept()` methods - for all things object observability.
+// No way to observe/intercept these mutations in JavaScript
+state.count = 5;
+state.items.push('new item');
+delete state.oldProp;
 
-<details><summary>This is documentation for Observer@2.x</summary>
+// No way to detect these changes
+```
 
-Looking for [`Observer@1.x`](https://github.com/webqit/observer/tree/v1.7.6)?
+This limitation in the language has long created a **blindspot** — and a **weakness** — for reactive systems. Consequently:
 
-</details>
-    
-### Method: `Observer.observe()`
-
-Observe mutations on arbitrary objects or arrays!
++ reactive frameworks (like React, Vue) learned to forbid mutability
++ *immutability* became the default workaround. You don't mutate, you create a new object each time:
+  
+  ```js
+  state = { ...state, count: 6 };
+  state = { ...state, count: 7 };
+  state = { ...state, count: 8 };
+  ```
 
 ```js
-// An object
-const obj = {};
-// Mtation observer on an object
-const abortController = Observer.observe( obj, inspect );
+  state = { ...state, items: [...state.items, 'new item 1'] };
+  state = { ...state, items: [...state.items, 'new item 2'] };
+  state = { ...state, items: [...state.items, 'new item 3'] };
+  ```
+
+  > Because this is generally hard to follow, frameworks typically enforce immutability via strong design constraints. Outside of a framework, you get standalone *immutability* libraries (like Immer, or Immutable.js back in the day) that as well try to simulate an immutable world, where data is never changed, only replaced.
+
++ mutation gets a bad rap
+
+**Using the Observer API:**
+
+By enabling observability at the object/array level, the Observer API effectively solves reactivity for a mutable world. Consequently:
+
++ you are able to weild *the sheer power of mutability* in programming unappologetically
++ you are able to make sense of a mutable world — and integrate with it — rather than see it as somethng to fight.
+
+The Observer API collapses layers of complexity that reactive frameworks have built around immutability, bringing you back to the simplicity and power of direct mutation—but now with full observability.
+
+**The Result:** Mutation-based reactivity as a first-class concept in JavaScript. Observer enables frameworks to embrace mutability instead of avoiding it — with [Quantum JS](https://github.com/webqit/quantum-js) taking this foundation to create imperative reactive programming.
+
+## Quick Start
+
+Observer provides a simple API for watching object and array changes.
+
+### Installation
+
+```bash
+npm install @webqit/observer
 ```
 
 ```js
-// An array
-const arr = [];
-// Mtation observer on an array
-const abortController = Observer.observe( arr, inspect );
+import Observer from '@webqit/observer';
 ```
 
-└ *Changes are delivered [**synchronously**](https://github.com/webqit/observer/wiki/#timing-and-batching) - as they happen.*
+### CDN
 
-```js
-// The change handler
-function inspect( mutations ) {
-    mutations.forEach( mutation => {
-        console.log( mutation.type, mutation.key, mutation.value, mutation.oldValue );
-    } );
-}
+```html
+<script src="https://unpkg.com/@webqit/observer/dist/main.js"></script>
+<script>
+  const Observer = window.webqit.Observer;
+</script>
 ```
 
-**-->** Stop observing at any time by calling `abort()` on the returned *abortController*:
+### Basic Usage
 
 ```js
-// Remove listener
-abortController.abort();
+import Observer from '@webqit/observer';
+
+const user = { name: 'John', items: [] };
+
+// Watch for changes
+const controller = Observer.observe(user, (mutations) => {
+  mutations.forEach(mutation => {
+    console.log(`Changed ${mutation.key}: ${mutation.oldValue} → ${mutation.value}`);
+  });
+});
+
+// Make changes using programmatic APIs
+Observer.set(user, 'name', 'Jane');
+Observer.set(user, 'age', 26);
+
+// Stop watching
+controller.abort();
 ```
 
-└ And you can provide your own [Abort Signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance:
+### Working with Arrays
 
 ```js
-// Providing an AbortSignal
-const abortController = new AbortController;
-Observer.observe( obj, inspect, { signal: abortController.signal } );
+const items = ['apple', 'banana'];
+
+Observer.observe(items, (mutations) => {
+  console.log('Array changed:', mutations);
+});
+
+// Use programmatic APIs for mutations
+Observer.set(items, 0, 'grape');
+Observer.set(items, 2, 'orange');
+
+// Reactive method calls
+Observer.apply(items.push, items, ['new item']); // Observer.proxy(state.items).push('new item')
 ```
 
+### Intercepting Operations
+
 ```js
-// Abort at any time
-abortController.abort();
+// Transform values before they're set
+Observer.intercept(user, 'set', (operation, previous, next) => {
+  if (operation.key === 'email') {
+    operation.value = operation.value.toLowerCase();
+  }
+  return next();
+});
+
+Observer.set(user, 'email', 'JOHN@EXAMPLE.COM'); // Becomes 'john@example.com'
 ```
 
-**-->** Where listeners initiate nested observers (child observers), leverage "AbortSignal-cascading" to tie child observers to parent observer's lifecycle:
+## 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
 
+### **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
+
+### **Developer Experience**
+- **🔧 Utility-First API**: Clean, functional design with consistent patterns
+- **📱 Universal Support**: Works in browsers, Node.js, and all JavaScript environments
+- **🔌 Standard Integration**: Built on AbortSignal, Reflect API, and Proxy standards
+- **📊 Lightweight**: Only ~5.8KB min+gz with zero dependencies
+
+## Ecosystem Integrations
+
+The Observer API is enabling a shared protocol of 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.
+
+### **⚡ [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.
+
+### **🔗 [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.
+
+## API Reference
+    
+- [Observer.observe()](#observerobservertarget-callback-options)
+- [Observer.intercept()](#observerintercepttarget-operation-handler-options)
+- [Observer.set()](#observersettarget-key-value-options)
+- [Observer.get()](#observergettarget-key-options)
+- [Observer.has()](#observerhastarget-key-options)
+- [Observer.ownKeys()](#observerownkeystarget-options)
+- [Observer.deleteProperty()](#observerdeletepropertytarget-key-options)
+- [Observer.deleteProperties()](#observerdeletepropertiestarget-keys-options)
+- [Observer.defineProperty()](#observerdefinepropertytarget-key-descriptor-options)
+- [Observer.defineProperties()](#observerdefinepropertiestarget-descriptors-options)
+- [Observer.accessorize()](#observeraccessorizetarget-properties-options)
+- [Observer.unaccessorize()](#observerunaccessorizetarget-properties-options)
+- [Observer.proxy()](#observerproxytarget-options)
+- [Observer.unproxy()](#observerunproxytarget-options)
+- [Observer.path()](#observerpathsegments)
+- [Observer.batch()](#observerbatchtarget-callback-options)
+- [Observer.map()](#observermapsource-target-options)
+- [Observer.any()](#observerany)
+- [Observer.subtree()](#observersubtree)
+- [Other Methods](#other-methods)
+
+### `Observer.observe(target, callback, options?)`
+
+Watch for changes on an object or array.
+Returns an AbortController for lifecycle management.
+
+**Basic Usage:**
 ```js
-// Parent - 
-const abortController = Observer.observe( obj, ( mutations, flags ) => {
+const obj = {};
+const controller = Observer.observe(obj, (mutations) => {
+  mutations.forEach(mutation => {
+    console.log(`${mutation.type}: ${mutation.key} = ${mutation.value}`);
+  });
+});
+
+// Changes are delivered synchronously
+Observer.set(obj, 'name', 'Bob');
+Observer.set(obj, 'age', 30);
+
+// Stop observing
+controller.abort();
+```
 
-    // Child
-    Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
+**Alternative Method Shapes:**
+```js
+// Watch specific properties
+Observer.observe(obj, ['name', 'email'], callback);
 
-    // Child
-    Observer.observe( obj, inspect, { signal: flags.signal } ); // <<<---- AbortSignal-cascading
+// Watch a single property
+Observer.observe(obj, 'name', callback);
 
-} );
+// Watch all properties (default)
+Observer.observe(obj, callback);
 ```
 
-└ *"Child" observers get automatically aborted at parent's "next turn", and at parent's own abortion!*
+**Options:**
+- `signal`: A custom AbortSignal instance that control lifecycle
+- `diff`: Only fire for values that actually changed
+- `recursions`: Controls recursion handling (`'inject'`, `'force-sync'`, `'force-async'`)
+- `withPropertyDescriptors`: Include property descriptor information
 
-**-->** Use the `options.diff` parameter to ignore mutation events whose current value is same as previous value:
+#### Abort Signals
+
+Observer returns a standard [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance for managing observer lifecycle.
 
 ```js
-// Parent - 
-const abortController = Observer.observe( obj, mutations => {
-  console.log( m.type, m.value, m.oldValue );
-}, { diff: true } );
+// Returns AbortController for lifecycle management
+const controller = Observer.observe(obj, callback);
+controller.abort(); // Stop observing
+
+// Provide your own AbortSignal
+const abortController = new AbortController();
+Observer.observe(obj, callback, { signal: abortController.signal });
+abortController.abort(); // Stop observing
 ```
 
+Or, you can provide your own:
+
 ```js
-obj.property = 'Same value';
+// Providing an AbortSignal
+const abortController = new AbortController;
+Observer.observe(obj, inspect, { signal: abortController.signal });
 ```
 
 ```js
-obj.property = 'Same value';
+// Abort at any time
+abortController.abort();
 ```
 
-└ *Observer is called only on the first update!*
-
-#### Concept: *Mutation APIs*
+#### Lifecycle Signals
 
-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:
+Each lifecycle event fired carries its own Abort Signal that automatically aborts at the end of its turn — just when the next event fires. They're useful for tying other parts of the system to just the given event's lifecycle. For example, lifecycle signals enable parent-child observer relationships where child observers automatically abort when their parent aborts.
+Leverage this to simplify hierarchical observer patterns.
 
 ```js
-// A single "set" operation on an object
-Observer.set( obj, 'prop0', 'value0' );
-Observer.defineProperty( obj, 'prop1', { get: () => 'value1' } );
-Observer.deleteProperty( obj, 'prop2' );
+// Parent observer with lifecycle management
+const parentController = Observer.observe(obj, (mutations, flags) => {
+  // Child observers automatically abort when parent aborts
+  Observer.observe(obj, childCallback, { signal: flags.signal });
+  
+  // Multiple child observers tied to parent lifecycle
+  Observer.observe(obj, anotherCallback, { signal: flags.signal });
+});
+
+// All child observers abort when parent aborts
+parentController.abort();
 ```
 
+#### Parity Table
+
+| | Observer API | Object.observe() (Deprecated) |
+|-------------|--------------|-------------------------------|
+| **Signature** | `.observe(target, callback, options?)` | `.observe(target, callback, acceptList?)` |
+| **Return Value** | `AbortController` (lifecycle management) | `undefined` (no lifecycle management) |
+| **Additional Features** | AbortSignal integration, path watching, batch/atomic operations, synchronous event model, etc. | Basic object observation, asynchronous event model (deprecated) |
+
+### `Observer.intercept(target, operation, handler, options?)`
+
+Intercept operations before they happen.
+Can intercept individual operations or multiple operations at once.
+
+**Single Operation Interception:**
+
+Intercept individual operations to transform, validate, or block them before they execute.
+
 ```js
-// A single "set" operation on an array
-Observer.set( arr, 0, 'item0' ); // Array [ 'item0' ]
-Observer.deleteProperty( arr, 0 ); // Array [ <1 empty slot> ]
+// Transform values before they're set
+Observer.intercept(obj, 'set', (operation, previous, next) => {
+  if (operation.key === 'email') {
+    operation.value = operation.value.toLowerCase();
+  }
+  return next();
+});
+
+Observer.set(obj, 'email', 'JOHN@EXAMPLE.COM'); // Becomes 'john@example.com'
 ```
 
-<details><summary>Polyfill limitations</summary>
+**Multiple Operations Interception:**
 
-In the polyfill, object observability doesn't work with literal operations. **Beware non-reactive operations**:
+Intercept multiple operations simultaneously to create comprehensive behavior modifications.
 
 ```js
-// Literal object operators
-delete obj.prop0;
-obj.prop3 = 'value3';
+const options = {};
+Observer.intercept(obj, {
+  set: (operation, previous, next) => {
+    if (operation.key === 'email') {
+      operation.value = operation.value.toLowerCase();
+    }
+    return next();
+  },
+  get: (operation, previous, next) => {
+    if (operation.key === 'token') {
+      return next(fetchToken());
+    }
+    return next();
+  },
+  deleteProperty: (operation, previous, next) => {
+    if (operation.key === 'password') {
+      console.log('Password deletion blocked');
+      return false; // Block the operation
+    }
+    return next();
+  }
+}, options);
 ```
 
+**Traps Pipeline:**
+
+Multiple interceptors can intercept same operation, and these will operate like a middleware pipeline where each interceptor uses `next()` to advance the operation to subsequent interceptors in the pipeline.
+
 ```js
-// Array methods
-arr.push( 'item3' );
-arr.pop();
+// First interceptor: Transform email to lowercase
+Observer.intercept(obj, 'get', (operation, previous, next) => {
+  if (operation.key === 'email') {
+    const result = next();
+    return result ? result.toLowerCase() : result;
+  }
+  return next();
+});
+
+// Second interceptor: Add validation
+Observer.intercept(obj, 'get', (operation, previous, next) => {
+  if (operation.key === 'email') {
+    const result = next();
+    if (result && !result.includes('@')) {
+      throw new Error('Invalid email format');
+    }
+    return result;
+  }
+  return next();
+});
+
+// Now when accessing email, both interceptors run in sequence:
+// 1. First: transforms to lowercase
+// 2. Second: validates format
+// Result: 'JOHN@EXAMPLE.COM' → 'john@example.com' → validation passes
 ```
 
-</details>
+#### Interceptable Operations
 
-**-->** Enable reactivity on *specific* properties with literal *object accessors* - using the `Observer.accessorize()` method:
+- `set` - Property assignment
+- `get` - Property access
+- `has` - Property existence check
+- `ownKeys` - Object key enumeration
+- `deleteProperty` - Property deletion
+- `defineProperty` - Property definition
+- `getOwnPropertyDescriptor` - Property descriptor access
+
+#### Parity Table
+
+| | Observer API | Proxy Traps |
+|-------------|--------------|-------------|
+| **Signature** | `.intercept(target, operation, handler, options?)`<br>`.intercept(target, { [operation]: handler[, ...]}, options?)` | `new Proxy(target, { [operation]: handler[, ...] })` |
+| **Return Value** | `undefined` (registration) | `Proxy` (wrapped object) |
+| **Additional Features** | Traps pipeline, composable interceptors | Single trap per operation, no composability |
+
+---
+
+### `Observer.set(target, key, value, options?)`
+
+Set properties _reactively_ using a programmatic mutation API.
+Triggers observers and can be intercepted via `Observer.intercept()`.
+
+**Basic Usage:**
 
 ```js
-// Accessorize all current enumerable properties
-Observer.accessorize( obj );
-// Accessorize specific properties (existing or new)
-Observer.accessorize( obj, [ 'prop0', 'prop1', 'prop2' ] );
+Observer.set(obj, 'name', 'Alice');
+Observer.set(arr, 0, 'first item');
+```
+
+**Alternative Method Shapes:**
 
-// Make reactive UPDATES
-obj.prop0 = 'value0';
-obj.prop1 = 'value1';
-obj.prop2 = 'value2';
+```js
+// Set multiple properties at once
+Observer.set(obj, {
+  name: 'Alice',
+  age: 25,
+  email: 'alice@example.com'
+});
+
+// Set with receiver context
+Observer.set(obj, 'name', 'Alice', receiver);
 ```
 
+#### Usage Patterns
+
 ```js
-// Accessorize all current indexes
-Observer.accessorize( arr );
-// Accessorize specific indexes (existing or new)
-Observer.accessorize( arr, [ 0, 1, 2 ] );
+// Reactive state updates
+Observer.set(state, 'loading', true);
+Observer.set(state, 'data', responseData);
 
-// Make reactive UPDATES
-arr[ 0 ] = 'item0';
-arr[ 1 ] = 'item1';
-arr[ 2 ] = 'item2';
+// Array operations
+Observer.set(items, 0, 'new item');
+Observer.set(items, items.length, 'append item');
 
-// Bonus reactivity with array methods that re-index existing items
-arr.unshift( 'new-item0' );
-arr.shift();
+// Nested property updates
+Observer.set(obj, Observer.path('user', 'profile', 'name'), 'Alice');
 ```
 
-<details><summary>Polyfill limitations</summary>
+#### Parity Table
+
+| | Observer API | Reflect API |
+|-------------|--------------|-------------|
+| **Signature** | `.set(target, key, value, options?)` | `.set(target, key, value)` |
+| **Return Value** | `boolean` (success) | `boolean` (success) |
+| **Additional Features** | Triggers observers, interceptable | Standard property setting |
+
+### `Observer.get(target, key, options?)`
 
-In the polyfill, object observability doesn't work with literal operations. **Beware non-reactive operations**:
+Get properties using a programmatic API.
+Can be intercepted via `Observer.intercept()` to provide computed values or transformations.
+
+**Basic Usage:**
 
 ```js
-// The delete operator and object properties that haven't been accessorized
-delete obj.prop0;
-obj.prop3 = 'value3';
+const value = Observer.get(obj, 'name');
+const nested = Observer.get(obj, 'user.profile.name');
 ```
 
+**_Scenario_: Computed Properties:**
+
 ```js
-// Array methods that do not re-index existing items
-arr.push( 'item0' );
-arr.pop();
+// Intercept to provide computed values
+Observer.intercept(obj, 'get', (operation, previous, next) => {
+  if (operation.key === 'fullName') {
+    return `${obj.firstName} ${obj.lastName}`;
+  }
+  return next();
+});
+
+Observer.get(obj, 'fullName'); // "John Doe" (computed on-the-fly)
 ```
 
-</details>
+#### Parity Table
 
-**-->** Enable reactivity on *arbitray* properties with *Proxies* - using the `Observer.proxy()` method:
+| | Observer API | Reflect API |
+|-------------|--------------|-------------|
+| **Signature** | `.get(target, key, options?)` | `.get(target, key)` |
+| **Return Value** | `any` (property value) | `any` (property value) |
+| **Additional Features** | Interceptable for computed values | Standard property access |
 
-```js
-// Obtain a reactive Proxy for an object
-const $obj = Observer.proxy( obj );
+### `Observer.has(target, key, options?)`
 
-// Make reactive operations
-$obj.prop1 = 'value1';
-$obj.prop4 = 'value4';
-$obj.prop8 = 'value8';
+Check if a property exists on an object.
+Can be intercepted via `Observer.intercept()` to hide or reveal properties dynamically.
 
-// With the delete operator
-delete $obj.prop0;
-```
+**Basic Usage:**
 
 ```js
-// Obtain a reactive Proxy for an array
-const $arr = Observer.proxy( arr );
+Observer.has(obj, 'name'); // true/false
+Observer.has(obj, 'user.profile.name'); // nested property check
+```
 
-// Make reactive operations
-$arr[ 0 ] = 'item0';
-$arr[ 1 ] = 'item1';
-$arr[ 2 ] = 'item2';
+**_Scenario_: Property Hiding:**
 
-// With an instance method
-$arr.push( 'item3' );
+```js
+// Intercept to hide sensitive properties
+Observer.intercept(obj, 'has', (operation, previous, next) => {
+  if (operation.key === 'password') {
+    return false; // Hide password from property checks
+  }
+  return next();
+});
+
+Observer.has(obj, 'password'); // false (hidden from checks)
 ```
 
-└ *And no problem if you end up nesting the approaches.*
+#### Parity Table
 
-```js
-// 'value1'-->obj
-Observer.accessorize( obj, [ 'prop0', 'prop1', 'prop2', ] );
-obj.prop1 = 'value1';
+| | Observer API | Reflect API |
+|-------------|--------------|-------------|
+| **Signature** | `.has(target, key, options?)` | `.has(target, key)` |
+| **Return Value** | `boolean` (exists) | `boolean` (exists) |
+| **Additional Features** | Interceptable for property hiding | Standard property existence check |
+
+### `Observer.ownKeys(target, options?)`
 
-// 'value1'-->$obj-->obj
-let $obj = Observer.proxy( obj );
-$obj.prop1 = 'value1';
+Get all own property keys of an object.
+Can be intercepted via `Observer.intercept()` to filter or transform the key list.
 
-// 'value1'-->set()-->$obj-->obj
-Observer.set( $obj, 'prop1', 'value1' );
+**Basic Usage:**
+
+```js
+Observer.ownKeys(obj); // ['name', 'email', 'age']
 ```
 
-**-->** "Restore" accessorized properties to their normal state by calling the `unaccessorize()` method:
+**_Scenario_: Key Filtering:**
 
 ```js
-Observer.unaccessorize( obj, [ 'prop1', 'prop6', 'prop10' ] );
+// Intercept to filter out sensitive keys
+Observer.intercept(obj, 'ownKeys', (operation, previous, next) => {
+  const keys = next();
+  return keys.filter(key => key !== 'password');
+});
+
+Observer.ownKeys(obj); // ['name', 'email'] (password filtered out)
 ```
 
-**-->** "Reproduce" original objects from Proxies obtained via `Observer.proxy()` by calling the `unproxy()` method:
+#### Parity Table
 
+| | Observer API | Reflect API | Object API |
+|-------------|--------------|-------------|-------------|
+| **Signature** | `.ownKeys(target, options?)` | `.ownKeys(target)` | `.keys(obj)` |
+| **Return Value** | `string[]` (keys) | `string[]` (keys) | `string[]` (keys) |
+| **Additional Features** | Interceptable for key filtering | Standard key enumeration | Standard key enumeration |
+
+### `Observer.deleteProperty(target, key, options?)`
+
+Delete properties _reactively_ using a programmatic mutation API.
+
+**Basic Usage:**
 ```js
-obj = Observer.unproxy( $obj );
+Observer.deleteProperty(obj, 'oldProp');
+Observer.deleteProperty(arr, 0);
 ```
 
-#### Concept: *Paths*
+#### Parity Table
+
+| | Observer API | Reflect API |
+|-------------|--------------|-------------|
+| **Signature** | `.deleteProperty(target, key, options?)` | `.deleteProperty(target, key)` |
+| **Return Value** | `boolean` (success) | `boolean` (success) |
+| **Additional Features** | Triggers observers, interceptable | Standard property deletion |
 
-Observe "a property" at a path in an object tree:
+### `Observer.deleteProperties(target, keys, options?)`
+
+Delete multiple properties at once.
 
 ```js
-const obj = {
-  level1: {
-    level2: 'level2-value',
-  },
-};
+Observer.deleteProperties(obj, ['oldProp1', 'oldProp2', 'tempProp']);
 ```
 
+#### Parity Table
+
+| | Observer API | No Direct Equivalent |
+|-------------|--------------|---------------------|
+| **Signature** | `.deleteProperties(target, keys, options?)` | No batch delete in standard APIs |
+| **Return Value** | `boolean[]` (success array) | N/A |
+| **Additional Features** | Triggers observers, interceptable | N/A |
+
+### `Observer.defineProperty(target, key, descriptor, options?)`
+
+Define properties _reactively_ using the programmatic mutation API.
+
+**Basic Usage:**
+
 ```js
-const path = Observer.path( 'level1', 'level2' );
-Observer.observe( obj, path, m => {
-  console.log( m.type, m.path, m.value, m.isUpdate );
-} );
+Observer.defineProperty(obj, 'computed', { 
+  get: () => obj.value * 2 
+});
 ```
 
+#### Parity Table
+
+| | Observer API | Reflect API | Object API |
+|-------------|--------------|-------------|-------------|
+| **Signature** | `.defineProperty(target, key, descriptor, options?)` | `.defineProperty(target, key, descriptor)` | `.defineProperty(obj, key, descriptor)` |
+| **Return Value** | `boolean` (success) | `boolean` (success) | `object` (modified object) |
+| **Additional Features** | Triggers observers, interceptable | Standard property definition | Standard property definition |
+
+### `Observer.defineProperties(target, descriptors, options?)`
+
+Define multiple properties at once.
+
 ```js
-Observer.set( obj.level1, 'level2', 'level2-new-value' );
+Observer.defineProperties(obj, {
+  name: { value: 'Alice', writable: true },
+  email: { value: 'alice@example.com', writable: true },
+  age: { value: 25, writable: true }
+});
 ```
 
-<details><summary>Console</summary>
+#### Parity Table
 
-| type | path | value | isUpdate |
-| ---- | ---- | ----- | -------- |
-| `set` | [ `level1`, `level2`, ] | `level2-new-value` | `true` |
+| | Observer API | Object API |
+|-------------|--------------|-------------|
+| **Signature** | `.defineProperties(target, descriptors, options?)` | `.defineProperties(obj, descriptors)` |
+| **Return Value** | `boolean` (success) | `object` (modified object) |
+| **Additional Features** | Triggers observers, interceptable | Standard property definition |
 
-</details>
+---
 
-└ *And the initial tree structure can be whatever*:
+### `Observer.accessorize(target, properties?, options?)`
+
+Make properties reactive for direct assignment.
 
 ```js
-// A tree structure that is yet to be built
-const obj = {};
+const obj = { age: null };
+
+// Make all CURRENT properties reactive
+Observer.accessorize(obj);
+
+// Make specific properties reactive
+Observer.accessorize(obj, ['name', 'email']);
+
+// Now direct assignment works
+obj.name = 'Alice';
+obj.email = 'alice@example.com';
 ```
 
+#### Parity Table
+
+| | Observer API | No Direct Equivalent |
+|-------------|--------------|---------------------|
+| **Signature** | `.accessorize(target, properties?, options?)` | No direct equivalent in standard APIs |
+| **Return Value** | `undefined` (modification) | N/A |
+| **Additional Features** | Makes properties reactive for direct assignment | N/A |
+
+### `Observer.unaccessorize(target, properties?)`
+
+Restore accessorized properties to their normal state.
+
 ```js
-const path = Observer.path( 'level1', 'level2', 'level3', 'level4' );
-Observer.observe( obj, path, m => {
-  console.log( m.type, m.path, m.value, m.isUpdate );
-} );
+// Restore specific properties
+Observer.unaccessorize(obj, ['name', 'email'], options?);
+
+// Restore all accessorized properties
+Observer.unaccessorize(obj);
 ```
 
-└ *Now, any operation that changes what "the value" at the path resolves to - either by tree extension or tree truncation - will fire our listener*:
+#### Parity Table
+
+| | Observer API | No Direct Equivalent |
+|-------------|--------------|---------------------|
+| **Signature** | `.unaccessorize(target, properties?, options?)` | No direct equivalent in standard APIs |
+| **Return Value** | `undefined` (modification) | N/A |
+| **Additional Features** | Restores accessorized properties to normal state | N/A |
+
+---
+
+### `Observer.proxy(target, options?)`
+
+Create a reactive proxy of any object to get automatic reactivity and interceptibility over on-the-fly operations.
+
+**Basic Usage:**
 
 ```js
-Observer.set( obj, 'level1', { level2: {}, } );
+const $obj = Observer.proxy(obj);
+
+// All operations are reactive
+$obj.name = 'Alice';             // Triggers observers
+$obj.newProp = 'value';          // Triggers observers
+delete $obj.oldProp;             // Triggers observers
+
+// Array methods are reactive
+$arr.push('item1', 'item2');     // Triggers observers
+$arr[0] = 'newValue';            // Triggers observers
 ```
 
-<details>
-<summary>Console</summary>
+#### Nested Operations (Requires `chainable: true`)
 
-| type | path | value | isUpdate |
-| ---- | ---- | ----- | -------- |
-| `set` | [ `level1`, `level2`, `level3`, `level4`, ] | `undefined` | `false` |
+Use `chainable: true` to interact with deeply nested objects as proxy instances too. By default, `.proxy()` doesn't perform deep wrapping - nested objects are returned as plain objects. Chainable mode enables automatic proxying of nested objects at the point they're accessed, allowing nested operations to trigger observers.
 
-</details>
+```js
+const $obj = Observer.proxy(obj, { chainable: true });
 
-└ *Meanwhile, this next one completes the tree, and the listener reports a value at its observed path*:
+// Nested objects are automatically proxied when accessed
+const $user = $obj.user;           // Returns a proxied object
+$user.name = 'Alice';              // Triggers observers
+$user.profile.theme = 'dark';      // Triggers observers
+
+// Array methods return proxied arrays
+const $filtered = $obj.items.filter(x => x.active); // Returns proxied array
+$filtered.push('newItem');         // Triggers observers
+
+// Direct nested access also works
+$obj.users[0].name = 'Bob';        // Triggers observers
+$obj.data.splice(0, 1);            // Triggers observers
+```
+
+#### Membrane Mode
+
+Membranes ensure that the same proxy instance is returned across multiple `.proxy()` calls for the same object. When combined with `chainable: true`, membranes also ensure consistent proxy identity for nested objects.
 
 ```js
-Observer.set( obj.level1, 'level2', { level3: { level4: 'level4-value', }, } );
+// Create membrane for consistent proxy identity
+const $obj1 = Observer.proxy(obj, { membrane: 'userData' });
+const $obj2 = Observer.proxy(obj, { membrane: 'userData' });
+
+// Same proxy instance returned
+console.log($obj1 === $obj2); // true
+
+// Root operations are reactive
+$obj1.name = 'Alice';                  // Triggers observers
+$obj2.email = 'alice@example.com';    // Triggers observers (same proxy)
+
+// When combined with chainable: true
+const $obj3 = Observer.proxy(obj, { membrane: 'userData', chainable: true });
+const $user1 = $obj3.user;
+const $user2 = $obj3.user;
+
+// Same nested proxy instance returned
+console.log($user1 === $user2); // true
+$user1.name = 'Alice';          // Triggers observers
 ```
 
-<details>
-<summary>Console</summary>
+#### How Membranes Work
 
-| type | path | value | isUpdate |
-| ---- | ---- | ----- | -------- |
-| `set` | [ `level1`, `level2`, `level3`, `level4`, ] | `level4-value` | `false` |
+- **Root Object Identity** - Same root object always returns the same proxy instance across multiple `.proxy()` calls
+- **Membrane References** - Uses a reference system to ensure consistent proxy identity
+- **Nested Object Identity** - When combined with `chainable: true`, ensures same nested objects return same proxy instances
+- **Performance** - Only creates one proxy per object (root or nested)
+- **Consistency** - Maintains referential equality for both root and nested objects
 
-</details>
+#### Membrane vs Chainable Object Identity
+
+```js
+const obj = { user: { name: 'Alice' }, items: ['item1'] };
+
+// MEMBRANE: Same root object = same proxy instance
+const $obj1 = Observer.proxy(obj, { membrane: 'test' });
+const $obj2 = Observer.proxy(obj, { membrane: 'test' });
+console.log($obj1 === $obj2); // true - same root proxy
+
+// Nested objects are NOT automatically proxied (without chainable)
+const user1 = $obj1.user; // Plain object, not proxied
+const user2 = $obj2.user; // Plain object, not proxied
+console.log(user1 === user2); // true - same plain object
+
+// CHAINABLE: Auto-proxies nested objects when accessed
+const $obj = Observer.proxy(obj, { chainable: true });
+const $user1 = $obj.user; // Proxied object
+const $user2 = $obj.user; // Different proxy instance
+console.log($user1 !== $user2); // true - different proxy instances
+
+// MEMBRANE + CHAINABLE: Consistent nested proxy identity
+const $obj3 = Observer.proxy(obj, { membrane: 'test', chainable: true });
+const $user3 = $obj3.user; // Proxied object
+const $user4 = $obj3.user; // Same proxy instance
+console.log($user3 === $user4); // true - same nested proxy
+```
+
+#### Real-World Usage Patterns
 
-**-->** 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:
+**_Scenario_: Form Handling:**
 
 ```js
-let context = m.context;
-console.log(context);
+const $form = Observer.proxy(formData, { membrane: 'form' });
+$form.name = 'John';             // Auto-save, validation
+$form.email = 'john@example.com'; // Auto-save, validation
+$form.tags.push('urgent');       // Auto-save, validation
 ```
 
-└ *And up again one level until the root event*:
+**_Scenario_: State Management:**
 
 ```js
-let parentContext = context.context;
-console.log(parentContext);
+const $state = Observer.proxy(appState, { chainable: true });
+$state.user.isLoggedIn = true;   // UI updates
+$state.cart.items.push(product); // UI updates
+$state.getUser().profile.theme = 'dark'; // UI updates (chainable)
 ```
 
-**-->** Observe trees that are built *asynchronously*! Where a promise is encountered along the path, further access is paused until promise resolves:
+#### Formal Arguments
 
 ```js
-Observer.set( obj.level1, 'level2', Promise.resolve( { level3: { level4: 'level4-value', }, } ) );
+// Basic proxy
+const $obj = Observer.proxy(obj);
+
+// Proxy with options
+const $obj = Observer.proxy(obj, {
+  membrane: 'userData',        // Auto-proxy nested objects
+  chainable: true              // Auto-wrap returned objects
+});
+
+// Proxy with custom extension
+const $obj = Observer.proxy(obj, {}, (traps) => {
+  // Extend proxy traps
+  traps.get = (target, key, receiver) => {
+    if (key === 'computed') {
+      return target.firstName + ' ' + target.lastName;
+    }
+    return traps.get(target, key, receiver);
+  };
+  return traps;
+});
 ```
 
-#### Concept: *Batch Mutations*
+#### Proxy Features (Summary)
 
-Make multiple mutations at a go, and they'll be correctly delivered as a batch to observers!
+- **Literal syntax** - Use normal JavaScript operations
+- **Array methods** - All array methods are reactive
+- **Property access** - All property operations are reactive
+- **Nested operations** - Works with deeply nested objects
+- **Dynamic properties** - Supports computed property names
+- **Method chaining** - Array methods can be chained
+- **Membrane support** - Auto-proxy nested objects
+- **Chainable operations** - Auto-wrap returned values
+- **Custom traps** - Extend proxy behavior
+- **Namespace isolation** - Separate observer namespaces
+
+#### Parity Table
+
+| | Observer API | Proxy API |
+|-------------|--------------|-----------|
+| **Signature** | `.proxy(target, options?)` | `new Proxy(target, handlers)` |
+| **Return Value** | `Proxy` (reactive proxy) | `Proxy` (standard proxy) |
+| **Additional Features** | Built-in reactivity, membrane, chainable | Manual trap implementation required |
+
+### `Observer.unproxy(target, options?)`
+
+Get the original object from a proxy.
 
 ```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' ] );
+const $obj = Observer.proxy(obj);
+const original = Observer.unproxy($obj); // Returns original obj
 ```
 
+#### Parity Table
+
+| | Observer API | No Direct Equivalent |
+|-------------|--------------|---------------------|
+| **Signature** | `.unproxy(target)` | No direct equivalent in standard APIs |
+| **Return Value** | `object` (original object) | N/A |
+| **Additional Features** | Extracts original object from Observer proxy | N/A |
+
+---
+
+### `Observer.path(...segments)`
+
+Create path arrays for deep property observation. Path watching enables observing changes at specific nested paths within object trees, including non-existent paths that are created dynamically.
+
+**Basic Usage:**
+
 ```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 );
+// Watch deep paths
+const path = Observer.path('user', 'profile', 'settings');
+Observer.observe(obj, path, (mutation) => {
+  console.log(`Deep change: ${mutation.path} = ${mutation.value}`);
+});
 ```
 
-**-->** Use the `Observer.batch()` to batch multiple arbitrary mutations - whether related or not:
+#### Usage Patterns
 
 ```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' ]
-} );
+// Form validation
+const path = Observer.path('form', 'user', 'email');
+Observer.observe(form, path, (mutation) => {
+  validateEmail(mutation.value);
+});
+
+// State management
+const path = Observer.path('app', 'user', 'preferences', 'theme');
+Observer.observe(state, path, (mutation) => {
+  updateTheme(mutation.value);
+});
+
+// Configuration watching
+const path = Observer.path('config', 'api', 'endpoint');
+Observer.observe(config, path, (mutation) => {
+  updateApiEndpoint(mutation.value);
+});
 ```
 
-> Method calls on a proxied instance - e.g. `Object.proxy( arr ).splice( 0 )` - also follow this strategy.
+#### Path Features (Summary)
 
-### Method: `Observer.intercept()`
+- Watches paths that are created dynamically
+- Uses an array syntax to avoid conflicting with property names with dots
+- Returns mutation context for audit trails
 
-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.
+### `Observer.any()`
 
-└ *Below, we intercept all "set" operations for an HTTP URL then transform it to an HTTPS URL.*
+Create a wildcard directive for matching any property or array index in path patterns. Wildcards enable flexible observation of dynamic data structures where you need to watch changes at any index or property name.
+
+**Basic Usage:**
 
 ```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 );
+// Watch any user at any index
+const path = Observer.path('users', Observer.any(), 'name');
+Observer.observe(obj, path, (mutation) => {
+  console.log(`User name changed: ${mutation.path} = ${mutation.value}`);
+});
 ```
 
-└ *Now, only the first of the following will fly as-is.*
+**Advanced Compositions:**
+
+Combine multiple wildcards to create powerful observation patterns for complex data structures. This enables watching changes across dynamic arrays, nested objects, and varying property names.
 
 ```js
-// Not transformed
-Observer.set( obj, 'url', 'https://webqit.io' );
+// Multiple wildcards in sequence
+const path = Observer.path('sections', Observer.any(), 'items', Observer.any(), 'name');
+// Matches: sections[0].items[1].name, sections[2].items[0].name, etc.
+
+// Wildcard at different levels
+const path = Observer.path('app', 'users', Observer.any(), 'profile', 'settings', Observer.any());
+// Matches: app.users[0].profile.settings[theme], app.users[1].profile.settings[language], etc.
 
-// Transformed
-Observer.set( obj, 'url', 'http://webqit.io' );
+// Wildcard with specific properties
+const path = Observer.path('data', Observer.any(), 'metadata', 'version');
+// Matches: data[item1].metadata.version, data[item2].metadata.version, etc.
 ```
 
-└ *And below, we intercept all "get" operations for a certain value to trigger a network fetch behind the scenes.*
+### `Observer.subtree()`
+
+Create a subtree directive for watching all changes from a specific level down infinitely. Subtree watching enables comprehensive observation of complex nested data structures without needing to specify every possible path.
+
+**Basic Usage:**
 
 ```js
-const getTrap = ( operation, previous, next ) => {
-    if ( operation.key === 'token' ) {
-        return next( fetch( tokenUrl ) );
-    }
-    return next();
-};
-Observer.intercept( obj, 'get', getTrap );
+// Watch all changes from this level down
+Observer.observe(obj, Observer.subtree(), (mutation) => {
+  console.log(`Any change: ${mutation.path} = ${mutation.value}`);
+});
 ```
 
-└ *And all of that can go into one "traps" object:*
+**Advanced Compositions:**
 
 ```js
-Observer.intercept( obj, {
-    get: getTrap,
-    set: setTrap,
-    deleteProperty: deletePropertyTrap,
-    defineProperty: definePropertyTrap,
-    ownKeys: ownKeysTrap,
-    has: hasTrap,
-    // etc
-} );
+// Subtree after specific path
+const path = Observer.path('app', 'users', Observer.subtree());
+// Watches: app.users.name, app.users.profile.theme, app.users.settings.notifications, etc.
+
+// Subtree with wildcards
+const path = Observer.path('sections', Observer.any(), Observer.subtree());
+// Watches: sections[0].title, sections[0].items[1].name, sections[1].config.theme, etc.
+
+// Multiple subtrees
+const path = Observer.path('app', 'users', Observer.any(), 'profile', Observer.subtree());
+// Watches: app.users[0].profile.name, app.users[0].profile.settings.theme, etc.
+
+// Subtree at root level
+Observer.observe(obj, Observer.subtree(), (mutation) => {
+  // Watches EVERY change in the entire object tree
+});
 ```
 
-## Documentation
+#### Real-World Usage Patterns
 
-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.
+```js
+// E-commerce: Watch any product in any category
+const path = Observer.path('store', 'categories', Observer.any(), 'products', Observer.any(), Observer.subtree());
+// Triggers for: store.categories[electronics].products[laptop].price
+//              store.categories[books].products[novel].title
+//              store.categories[clothing].products[shirt].sizes[large]
+```
 
-## The Polyfill
+```js
+// Multi-tenant: Watch any user's data in any organization
+const path = Observer.path('orgs', Observer.any(), 'users', Observer.any(), Observer.subtree());
+// Triggers for: orgs[company1].users[alice].profile.name
+//              orgs[company2].users[bob].settings.theme
+```
 
-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).
+```js
+// Content Management: Watch any page in any section
+const path = Observer.path('cms', 'sections', Observer.any(), 'pages', Observer.any(), Observer.subtree());
+// Triggers for: cms.sections[blog].pages[post1].content
+//              cms.sections[news].pages[article].metadata.tags
+```
 
-<details><summary>Load from a CDN</summary>
+---
 
-```html
-<script src="https://unpkg.com/@webqit/observer/dist/main.js"></script>
-```
+### `Observer.batch(target, callback, options?)`
 
-> `4.4` kB min + gz | `13.9` KB min [↗](https://bundlephobia.com/package/@webqit/observer)
+Batch multiple operations together. Batched operations ensure atomicity - all changes are delivered as a single event to observers, preventing partial updates and ensuring data consistency.
+
+**Basic Usage:**
 
 ```js
-// Obtain the APIs
-const Observer = window.webqit.Observer;
+// Batch multiple changes
+Observer.batch(obj, () => {
+  Observer.set(obj, 'name', 'Alice');
+  Observer.set(obj, 'email', 'alice@example.com');
+  Observer.deleteProperty(obj, 'age');
+});
+
+// All changes are delivered as a single batch to observers
 ```
 
-</details>
+---
 
-<details><summary>Install from NPM</summary>
+### `Observer.map(source, target, options?)`
 
-```bash
-npm i @webqit/observer
+Create reactive mirrors between objects — changes in source automatically sync to target. Object mirroring enables automatic data flow between different parts of your application, keeping them synchronized without manual intervention.
+
+**Basic Usage:**
+
+```js
+const source = { name: 'Alice', age: 25 };
+const target = {};
+
+// Create reactive mirror
+const controller = Observer.map(source, target);
+
+// Changes in source automatically sync to target
+Observer.set(source, 'name', 'Bob');
+console.log(target.name); // 'Bob'
+
+// Stop mirroring
+controller.abort();
 ```
 
+**Alternative Method Shapes:**
+
 ```js
-// Import
-import Observer from '@webqit/observer';;
+// Mirror with options
+Observer.map(source, target, {
+  only: ['name', 'email'], // Only mirror specific properties
+  except: ['password'], // Exclude specific properties
+  spread: true, // Spread array elements
+  onlyEnumerable: false // Include non-enumerable properties
+});
+
+// Mirror with namespace
+Observer.map(source, target, { namespace: 'user' });
 ```
 
-</details>
+#### Usage Patterns
+
+```js
+// State synchronization
+const appState = { user: { name: 'Alice' } };
+const uiState = {};
+Observer.map(appState, uiState);
+
+// Form data mirroring
+const formData = { name: '', email: '' };
+const validationState = {};
+Observer.map(formData, validationState);
+
+// Array synchronization
+const sourceArray = [1, 2, 3];
+const targetArray = [];
+Observer.map(sourceArray, targetArray, { spread: true });
+```
+
+---
 
-## Getting Involved
+### Other Methods
 
-All forms of contributions are welcome at this time. For example, implementation details are all up for discussion. And here are specific links:
+Mentioned here for completeness, Observer also provides these utility methods:
 
-+ [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)
+- **`Observer.apply(target, thisArg, args)`** - Apply functions reactively
+- **`Observer.construct(target, args)`** - Construct objects reactively  
+- **`Observer.getOwnPropertyDescriptor(target, key)`** - Get property descriptors reactively
+- **`Observer.getPrototypeOf(target)`** - Get prototype reactively
+- **`Observer.setPrototypeOf(target, prototype)`** - Set prototype reactively
+- **`Observer.isExtensible(target)`** - Check extensibility reactively
+- **`Observer.preventExtensions(target)`** - Prevent extensions reactively
+
+## Extended Documentation
+
+- [Timing and Batching](https://github.com/webqit/observer/wiki#timing-and-batching)
+- [Reflect API Supersets](https://github.com/webqit/observer/wiki#featuring-reflect-api-supersets)
+
+## Contributing
+
+We welcome contributions! Here's how to get involved:
+
+- 🐛 [Report Issues](https://github.com/webqit/observer/issues)
+- 💬 [Join Discussions](https://github.com/webqit/observer/discussions)
+- 📖 [Read Documentation](https://github.com/webqit/observer/wiki)
+- 🔧 [View Source](https://github.com/webqit/observer)
 
 ## License
 
-MIT.
+MIT
+
+[npm-version-src]: https://img.shields.io/npm/v/@webqit/observer?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-version-href]: https://npmjs.com/package/@webqit/observer
+[npm-downloads-src]: https://img.shields.io/npm/dm/@webqit/observer?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-downloads-href]: https://npmjs.com/package/@webqit/observer
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/@webqit/observer?style=flat&colorA=18181B&colorB=F0DB4F
+[bundle-href]: https://bundlephobia.com/result?p=@webqit/observer
+[license-src]: https://img.shields.io/github/license/webqit/observer.svg?style=flat&colorA=18181B&colorB=F0DB4F
+[license-href]: https://github.com/webqit/observer/LICENSE