@brinzl/observer 0.1.0

package/AGENTS.md

@@ -0,0 +1,172 @@
+# Observer.js
+
+A lightweight, zero-dependency reactive object observation library built for learning purposes.
+
+## Project Overview
+
+This library provides a way to observe changes to JavaScript objects and arrays using ES6 Proxies. When properties are modified, subscribers are notified with detailed change records.
+
+## API Design
+
+```javascript
+// Create an observable from a plain object
+const observable = Observer.create({ name: 'Alice', age: 30 });
+
+// Subscribe to all changes
+const unsubscribe = Observer.observe(observable, (changes) => {
+  changes.forEach(change => {
+    console.log(change.type);     // 'set' | 'delete' | 'insert' | 'batch'
+    console.log(change.path);     // ['user', 'name'] - path to the changed prop
+    console.log(change.oldValue);
+    console.log(change.newValue);
+  });
+});
+
+// Mutations trigger the callback automatically
+observable.name = 'Bob';              // fires the subscriber
+observable.address = { city: 'NY' };  // nested objects also become observable
+
+// Unsubscribe when done
+unsubscribe();
+
+// Or destroy entirely
+Observer.destroy(observable);
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Observer (Public API)                   │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+│  │   create()  │  │  observe()  │  │       destroy()         │  │
+│  └──────┬──────┘  └──────┬──────┘  └────────────┬────────────┘  │
+└─────────┼────────────────┼──────────────────────┼───────────────┘
+          │                │                      │
+          ▼                ▼                      ▼
+┌─────────────────┐  ┌───────────────────┐  ┌──────────────────┐
+│ObservableFactory│  │ SubscriberRegistry│  │   ProxyRegistry  │
+│                 │  │                   │  │ (WeakMap-based)  │
+│ - createProxy() │  │ - subscribe()     │  │                  │
+│ - wrapValue()   │  │ - unsubscribe()   │  │ - stores metadata│
+│                 │  │ - notify()        │  │ - revoke fns     │
+└────────┬────────┘  └─────────┬─────────┘  └──────────────────┘
+         │                     │
+         ▼                     │
+┌─────────────────────────┐    │
+│     ProxyHandler        │    │
+│                         │    │
+│ - get trap (lazy wrap)  │    │
+│ - set trap ─────────────┼────┼──────┐
+│ - deleteProperty trap ──┼────┼──────┤
+│ - array method patches  │    │      │
+└─────────────────────────┘    │      ▼
+                               │  ┌───────────────┐
+                               │  │  ChangeQueue  │
+                               │  │               │
+                               │  │ - enqueue()   │
+                               │  │ - flush()  ───┼──► notify subscribers
+                               │  └───────────────┘
+```
+
+## File Structure
+
+```
+observer.js/
+├── src/
+│   ├── index.js          # Public API (Observer.create/observe/destroy)
+│   ├── symbols.js        # Shared symbols
+│   ├── registry.js       # ProxyRegistry (WeakMap wrapper)
+│   ├── factory.js        # ObservableFactory (createProxy logic)
+│   ├── queue.js          # ChangeQueue (microtask batching)
+│   ├── subscribers.js    # SubscriberRegistry
+│   └── array-methods.js  # Array mutator wrappers
+├── test.js               # Manual testing script
+├── package.json
+└── AGENTS.md
+```
+
+## Design Decisions
+
+### Core Principles
+
+1. **WeakMap for metadata** - Storing observer state (subscribers, original target, revoke functions) in a WeakMap keyed by the proxy means observables are garbage collected naturally when nothing else holds a reference.
+
+2. **Lazy recursive proxying** - Don't walk the entire object tree up front. When a nested object is accessed via a get trap, wrap it in a proxy at that point. This keeps `create()` fast regardless of object size.
+
+3. **Double-wrap prevention** - Use a sentinel symbol (`IS_OBSERVABLE`) so that if someone passes an already-proxied object into `create()`, it returns as-is rather than double-wrapping.
+
+4. **Revocable proxies** - Use `Proxy.revocable()` instead of `new Proxy()` so that `destroy()` can fully invalidate the proxy and prevent further mutations.
+
+5. **Microtask batching** - Changes are batched per microtask (using `queueMicrotask`) rather than firing synchronously on every mutation. This avoids flooding subscribers when multiple properties change at once.
+
+6. **Path tracking** - Each change record includes the path (e.g. `['address', 'city']`) from the root observable to the changed property.
+
+### Scope Decisions
+
+- **Objects & Arrays only** - No Map/Set support (can be added later)
+- **Path-filtered subscriptions** - Planned as a later enhancement
+- **Circular references** - Not currently handled (documented as unsupported)
+
+## Implementation Phases
+
+### Phase 1: Core Proxy Wrapper (No Reactivity)
+- Create proxies that wrap objects/arrays
+- Track them in a WeakMap registry
+- Implement lazy nested proxy creation
+- Expose internal symbols for debugging
+
+### Phase 2: Change Detection (Set/Delete Traps)
+- Detect mutations via `set` and `deleteProperty` traps
+- Create change records with type, path, oldValue, newValue
+- Wrap newly assigned objects in proxies
+
+### Phase 3: Change Queue & Microtask Batching
+- Accumulate changes within current microtask
+- Flush batched changes to subscribers
+- Group changes by root observable
+
+### Phase 4: Subscriber Registry
+- Implement `Observer.observe()` and unsubscribe
+- Notify subscribers with batched changes
+- Handle subscriber errors gracefully
+
+### Phase 5: Array Method Interception
+- Intercept mutating methods: push, pop, shift, unshift, splice, sort, reverse
+- Emit meaningful `insert`/`delete` change types
+- Wrap inserted objects in proxies
+
+### Phase 6: Destroy & Cleanup
+- Implement `Observer.destroy()`
+- Revoke proxies to prevent further use
+- Clear subscribers and registry entries
+
+## Internal Symbols
+
+```javascript
+SYMBOLS = {
+  IS_OBSERVABLE: Symbol('observer.isObservable'),  // Detect wrapped proxies
+  RAW: Symbol('observer.raw'),                      // Access original target
+  ROOT: Symbol('observer.root'),                    // Get root observable
+  PATH: Symbol('observer.path')                     // Get path from root
+}
+```
+
+## Change Record Format
+
+```javascript
+{
+  type: 'set' | 'delete' | 'insert',
+  path: string[],      // e.g. ['user', 'profile', 'name']
+  oldValue: any,
+  newValue: any
+}
+```
+
+## Testing
+
+Manual testing via `node test.js`. Run tests after each phase to verify implementation.
+
+## Module System
+
+ES Modules (import/export) with `"type": "module"` in package.json.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brinsil Elias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# observer.js
+
+A tiny, zero-dependency reactive object observation library using ES6 Proxies.
+Observe changes to JavaScript objects and arrays with automatic nested tracking and microtask batching.
+
+## Why?
+
+While exploring how Vue.js handle reactivity, and I came across observer pattern that powers their reactive systems. This library was built as a project to understand the fundamentals of reactive programming from first principles. 
+
+Inspired by libraries like [object-observer](https://github.com/gullerya/object-observer), [icaro](https://github.com/GianlucaGuarini/icaro), and [micro-observer](https://github.com/nicedoc/micro-observer).
+
+## Features
+
+- Observe deeply nested objects and arrays
+- Automatic change batching via microtasks
+- Path tracking for precise change locations
+- Clean teardown with proxy revocation
+- Zero dependencies, ~2KB minified
+
+## Usage
+
+```
+npm install @brinzl/observer
+```
+
+### Basic
+
+```javascript
+import { Observer } from '@brinzl/observer';
+
+// Create an observable object.
+const obs = Observer.create({ name: 'Alice', age: 30 });
+
+// Subscribe to changes.
+const unsubscribe = Observer.observe(obs, (changes) => {
+  changes.forEach(change => {
+    console.log(change.type);      // 'set' | 'delete'
+    console.log(change.path);      // ['name']
+    console.log(change.oldValue);  // 'Alice'
+    console.log(change.newValue);  // 'Bob'
+  });
+});
+
+// Mutations trigger the callback.
+obs.name = 'Bob';
+obs.age = 31;
+
+// Unsubscribe when done.
+unsubscribe();
+```
+
+### Nested Objects
+
+```javascript
+const obs = Observer.create({
+  user: {
+    profile: { name: 'Alice' }
+  }
+});
+
+Observer.observe(obs, (changes) => {
+  console.log(changes);
+});
+
+// Nested objects are automatically observed.
+obs.user.profile.name = 'Bob';
+// Change: { type: 'set', path: ['user', 'profile', 'name'], oldValue: 'Alice', newValue: 'Bob' }
+```
+
+### Arrays
+
+```javascript
+const obs = Observer.create({ items: [1, 2, 3] });
+
+Observer.observe(obs, (changes) => {
+  console.log(changes);
+});
+
+obs.items.push(4);
+obs.items[0] = 10;
+```
+
+### Cleanup
+
+```javascript
+const obs = Observer.create({ data: 'test' });
+
+// Completely destroy the observable.
+Observer.destroy(obs);
+
+// Further access throws an error.
+obs.data; // TypeError: Cannot perform 'get' on a proxy that has been revoked
+```
+
+### Accessing Internals
+
+```javascript
+const { IS_OBSERVABLE, RAW, ROOT, PATH } = Observer.symbols;
+
+const obs = Observer.create({ nested: { value: 1 } });
+
+obs[IS_OBSERVABLE];           // true
+obs[RAW];                     // { nested: { value: 1 } } (original object)
+obs.nested[PATH];             // ['nested']
+obs.nested[ROOT] === obs;     // true
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `Observer.create(target)` | Creates an observable from a plain object or array |
+| `Observer.observe(observable, callback)` | Subscribes to changes, returns an unsubscribe function |
+| `Observer.destroy(observable)` | Revokes the proxy and clears all subscribers |
+| `Observer.symbols` | Internal symbols for accessing raw target, path, and root |
+
+## Change Record
+
+```javascript
+{
+  type: 'set' | 'delete',
+  path: string[],      // e.g. ['user', 'profile', 'name']
+  oldValue: any,
+  newValue: any
+}
+```
+
+## License
+
+MIT

package/index.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Observer.js Tests</title>
+</head>
+<body>
+  <script type="module" src="./index.js"></script>
+</body>
+</html>

package/index.js

@@ -0,0 +1,2 @@
+import { Observer } from "./observer";
+Window.Observer = Observer

package/observer.js

@@ -0,0 +1,187 @@
+const symbols = {
+  IS_OBSERVABLE: Symbol('observer.isObservable'),
+  RAW: Symbol('observer.raw'),
+  ROOT: Symbol('observer.root'),
+  PATH: Symbol('observer.path'),
+}
+
+let queue = []
+let scheduled = false
+
+const registry = new WeakMap()
+const targetToProxy = new WeakMap()
+
+const subscribers = new Map()
+
+const register = (proxy, metadata) => {
+  targetToProxy.set(metadata.target, proxy)
+  return registry.set(proxy, metadata)
+}
+const getMetadata = (proxy) => {
+  return registry.get(proxy)
+}
+const unregister = (proxy) => {
+  const metadata = registry.get(proxy)
+  if (metadata) {
+    targetToProxy.delete(metadata.target)
+  }
+  return registry.delete(proxy)
+}
+
+const notifySubscribers = (root, changes) => {
+  const callbacks = subscribers.get(root)
+  if (!callbacks || callbacks.size === 0) return
+
+  for (const callback of callbacks) {
+    try {
+      callback(changes)
+    } catch (error) {
+      console.error('Subscriber error:', error)
+    }
+  }
+}
+
+const flush = () => {
+  const batch = queue
+  const changesByRoot = new Map()
+
+  queue = []
+  scheduled = false
+
+  for (let change of batch) {
+    if (!changesByRoot.has(change.root)) {
+      changesByRoot.set(change.root, [])
+    }
+    changesByRoot.get(change.root).push({
+      type: change.type,
+      path: change.path,
+      oldValue: change.oldValue,
+      newValue: change.newValue
+    })
+  }
+  for (let [root, changes] of changesByRoot) {
+    notifySubscribers(root, changes)
+  }
+}
+
+const enqueue = (change, root) => {
+  queue.push({ ...change, root })
+  if (!scheduled) {
+    scheduled = true
+    queueMicrotask(flush)
+  }
+}
+
+const handler = {
+  get: (target, property, receiver) => {
+    if (property === symbols.IS_OBSERVABLE) return true
+    if (property === symbols.RAW) return target
+    if (property === symbols.ROOT) return getMetadata(receiver).root
+    if (property === symbols.PATH) return getMetadata(receiver).path
+
+    const value = Reflect.get(target, property, receiver)
+    if (value === null || typeof value !== 'object') {
+      return value
+    }
+
+    const metadata = getMetadata(receiver)
+    const wrappedValue = createProxy(value, metadata.root, [...metadata.path, property])
+    return wrappedValue
+  },
+  set: (target, property, value, receiver) => {
+    const oldValue = target[property]
+    const metadata = getMetadata(receiver)
+
+    if (value !== null && typeof value === 'object') {
+      value = createProxy(value, metadata.root, [...metadata.path, property])
+    }
+
+    const success = Reflect.set(target, property, value, receiver)
+    if (success && oldValue !== value) {
+      enqueue({
+        type: 'set',
+        path: [...metadata.path, property],
+        oldValue,
+        newValue: value
+      }, metadata.root)
+    }
+    return success
+  },
+  deleteProperty: (target, property) => {
+    if (!(property in target)) return true
+    const oldValue = target[property]
+    const proxy = targetToProxy.get(target)
+    const metadata = getMetadata(proxy)
+
+    const success = Reflect.deleteProperty(target, property)
+    if (success) {
+      enqueue({
+        type: 'delete',
+        path: [...metadata.path, property],
+        oldValue,
+        newValue: undefined
+      }, metadata.root)
+    }
+    return success
+  }
+}
+
+const createProxy = (target, root = null, path = []) => {
+  if (target === null || typeof target !== 'object') return target
+  if (target[symbols.IS_OBSERVABLE] === true) return target
+
+  const { proxy, revoke } = Proxy.revocable(target, handler)
+  const metadata = {
+    target,
+    revoke,
+    root: root ?? proxy,
+    path
+  }
+
+  register(proxy, metadata)
+  return proxy
+}
+
+const subscribe = (root, callback) => {
+  if (!subscribers.has(root)) subscribers.set(root, new Set())
+  subscribers.get(root).add(callback)
+
+  return () => {
+    const set = subscribers.get(root)
+    if (set) {
+      set.delete(callback)
+      if (set.size === 0) subscribers.delete(root)
+    }
+  }
+}
+
+export const Observer = {
+  create: (target) => {
+    if (target === null || typeof target !== 'object') {
+      throw new TypeError('Observer.create requires an Object or an Array')
+    }
+
+    return createProxy(target)
+  },
+  observe: (observable, callback) => {
+    if (!observable[symbols.IS_OBSERVABLE]) {
+      throw new TypeError('Observer.observe must have an observable')
+    }
+
+    if (typeof callback !== 'function') {
+      throw new TypeError('Observer.observe must have a callback function')
+    }
+
+    return subscribe(observable, callback)
+  },
+  destroy: (observable) => {
+    const metadata = getMetadata(observable)
+    if (!metadata) return
+    subscribers.delete(observable)
+    unregister(observable)
+    metadata.revoke()
+  },
+  symbols
+}
+
+

package/observer.min.js

@@ -0,0 +1 @@
+var a={IS_OBSERVABLE:Symbol("observer.isObservable"),RAW:Symbol("observer.raw"),ROOT:Symbol("observer.root"),PATH:Symbol("observer.path")},f=[],i=!1,l=new WeakMap,d=new WeakMap,c=new Map,y=(e,t)=>{return d.set(t.target,e),l.set(e,t)},u=(e)=>{return l.get(e)},S=(e)=>{let t=l.get(e);if(t)d.delete(t.target);return l.delete(e)},O=(e,t)=>{let o=c.get(e);if(!o||o.size===0)return;for(let r of o)try{r(t)}catch(s){console.error("Subscriber error:",s)}},V=()=>{let e=f,t=new Map;f=[],i=!1;for(let o of e){if(!t.has(o.root))t.set(o.root,[]);t.get(o.root).push({type:o.type,path:o.path,oldValue:o.oldValue,newValue:o.newValue})}for(let[o,r]of t)O(o,r)},w=(e,t)=>{if(f.push({...e,root:t}),!i)i=!0,queueMicrotask(V)},m={get:(e,t,o)=>{if(t===a.IS_OBSERVABLE)return!0;if(t===a.RAW)return e;if(t===a.ROOT)return u(o).root;if(t===a.PATH)return u(o).path;let r=Reflect.get(e,t,o);if(r===null||typeof r!=="object")return r;let s=u(o);return b(r,s.root,[...s.path,t])},set:(e,t,o,r)=>{let s=e[t],n=u(r);if(o!==null&&typeof o==="object")o=b(o,n.root,[...n.path,t]);let h=Reflect.set(e,t,o,r);if(h&&s!==o)w({type:"set",path:[...n.path,t],oldValue:s,newValue:o},n.root);return h},deleteProperty:(e,t)=>{if(!(t in e))return!0;let o=e[t],r=d.get(e),s=u(r),n=Reflect.deleteProperty(e,t);if(n)w({type:"delete",path:[...s.path,t],oldValue:o,newValue:void 0},s.root);return n}},b=(e,t=null,o=[])=>{if(e===null||typeof e!=="object")return e;if(e[a.IS_OBSERVABLE]===!0)return e;let{proxy:r,revoke:s}=Proxy.revocable(e,m);return y(r,{target:e,revoke:s,root:t??r,path:o}),r},p=(e,t)=>{if(!c.has(e))c.set(e,new Set);return c.get(e).add(t),()=>{let o=c.get(e);if(o){if(o.delete(t),o.size===0)c.delete(e)}}},R={create:(e)=>{if(e===null||typeof e!=="object")throw TypeError("Observer.create requires an Object or an Array");return b(e)},observe:(e,t)=>{if(!e[a.IS_OBSERVABLE])throw TypeError("Observer.observe must have an observable");if(typeof t!=="function")throw TypeError("Observer.observe must have a callback function");return p(e,t)},destroy:(e)=>{let t=u(e);if(!t)return;c.delete(e),S(e),t.revoke()},symbols:a};export{R as Observer};

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@brinzl/observer",
+  "version": "0.1.0",
+  "description": "A lightweight, zero-dependency reactive object observation library.",
+  "main": "observer.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Brinsil Elias",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/brinzl/observer.js/issues"
+  },
+  "homepage": "https://github.com/brinzl/observer.js#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}