# als-object-observer

> Triger callback on js object change

Latest version **0.1.0** (published 2023-04-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install als-object-observer
pnpm add als-object-observer
yarn add als-object-observer
bun add als-object-observer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2023-04-07 |
| First published | 2023-04-07 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 17.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Alex Sorkin |
| Maintainers | alexsorkin |

## Links

- npm: https://www.npmjs.com/package/als-object-observer
- npm.io page: https://npm.io/package/als-object-observer

## Recent versions

- 0.1.0 (latest) — 2023-04-07

## README

# ObjectObserver

- [ObjectObserver](#objectobserver)
  - [Basics](#basics)
  - [$vars](#vars)
  - [callback params](#callback-params)
  - [objMap](#objmap)
  - [mapKeys](#mapkeys)


The ObjectObserver class is a built-in class in JavaScript that can be used to add a proxy to an object and its subtree. When changes are made to the object or any of its properties, the proxy will trigger a callback function that can be used to handle the change. This can be useful in situations where you need to monitor changes to an object and take action based on those changes.

## Basics
To use ObjectObserver, you must first create an instance of the class and pass in an object to observe, a callback function to run when changes occur, and an optional params object. The params object is an object that can be used to store additional parameters that are needed by the callback function.

```javascript
function callback({map,action,args=[],result,error=null},params={}) {
   // ...your code for callback
}

let obj = {a: 1, b: {c: 2, d: 3}};
let dobj = new ObjectObserver(obj, callback, params={});
```

## $vars
The ``dobj.$vars`` property is a proxy with a subtree of proxies for every object in the obj object. Changes made using $vars trigger the callback function.

```javascript
dobj.$vars.a = 2; // Triggers callback
```

Here are example for ``$vars`` usage:
```javascript
const obj = {
    foo: 'bar',
    baz: null,
    some: null,
    qux: {
       a: 1,
       b: [2, 3, { c: 4 },'df'],
       c: {
          d: 'e'
       }
    }
};

let dobj = new ObjectObserver(obj,function(arguments) {
   let {map,action,args,result,error} = arguments
   console.log(arguments)
})
let {$vars,objMap} = dobj

$vars.test = ['hello',{some:'test'},5] 
// {"map":["test"],"action":"set","args":[],"result":["hello",{"some":"test"},5],"error":null}
$vars.qux.b.splice(0,1)
// {"map":["qux","b"],"action":"splice","args":[0,1],"result":[2],"error":null}
delete dobj.$vars.qux
// {"map":["qux"],"action":"delete","args":[],"result":true,"error":null}
delete dobj.$vars.quxd
// {"map":["quxe"],"action":"delete","args":[],"result":false,"error":"Can't delete \"quxe\" because it's not exists"}
$vars.qux.b.some = 'test'
// {"map":["qux","b","some"],"action":"set","args":[],"result":"test","error":null}
```

## callback params
* map - map in subtree for value that changed. 
  * For example ``obj.some[2].test`` is ``['some',2,'test']``
* action - set,delete, or array method (like push, reverse,...)
* args - arguments for array method
* result - result for new value
  * array methods - splice will reture spliced ellement, push - new element
  * delete will return true (if deleted) or false (if not deleted)
* error - null or string in case for deleting value which not exists
* params - is an object which
  * for example calback is method of some class, you can pass self (this for method)


## objMap
The ``dobj.objMap`` property is a Map object that maps objects in the obj object to their corresponding proxies. The dobj.mapKeys property is an object that maps the keys of objects in the obj object to their corresponding parent, key, and parentProxy.

In other words, ``objMap`` is a Map object which has objects and arrays from ``obj`` subtree as a key and ``{key,value,map,parent,proxy,revoke}`` as value. 

```javascript
dobj.objMap.get(obj.b); // Returns the proxy for obj.b
dobj.mapKeys["b.c"]; // Returns { parent: { c: 2, d: 3 }, key: "c", parentProxy: Proxy }
```


For example (example from code above) :
```javascript
objMap.get(obj)
/*{
   key: undefined,
   map: [],
   parent: undefined,
   proxy: Proxy(Object) {foo: 'bar', baz: null, some: null, qux: {…}},
   revoke: ƒ ()
}*/
objMap.get(obj.qux.b)
/*{
   key: "b",
   map: (2) ['qux', 'b'],
   parent: {a: 1, b: Array(4), c: {…}},
   proxy: Proxy(Array) {0: 2, 1: 3, 2: {…}, 3: 'df'},
   revoke: ƒ (),
}*/
```


## mapKeys
``mapKeys`` is an object which has joined map for each item in obj as a key and {key,parent,parentProxy} as a value. 

Here is the example for obj above:
```javascript
'baz': {parent: {…}, key: 'baz', parentProxy: Proxy(Object)}
'foo': {parent: {…}, key: 'foo', parentProxy: Proxy(Object)}
'some': {parent: {…}, key: 'some', parentProxy: Proxy(Object)}
'test': {parent: {…}, key: 'test', parentProxy: Proxy(Object)}
'test.0': {parent: Array(3), key: '0', parentProxy: Proxy(Array)}
'test.1': {parent: Array(3), key: '1', parentProxy: Proxy(Array)}
'test.1.some': {parent: {…}, key: 'some', parentProxy: Proxy(Object)}
'test.2': {parent: Array(3), key: '2', parentProxy: Proxy(Array)}
```

---
_Source: https://npm.io/package/als-object-observer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._