Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jamesnw/objectionable
Track changes to Javascript values with a deep proxy. Figure out where you're breaking immutability expectations.
https://github.com/jamesnw/objectionable
deep-proxy javascript javascript-library npm-package proxy
Last synced: about 1 month ago
JSON representation
Track changes to Javascript values with a deep proxy. Figure out where you're breaking immutability expectations.
- Host: GitHub
- URL: https://github.com/jamesnw/objectionable
- Owner: jamesnw
- License: isc
- Created: 2022-10-20T01:23:11.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2022-10-25T00:25:17.000Z (about 2 years ago)
- Last Synced: 2024-11-17T11:51:33.257Z (about 2 months ago)
- Topics: deep-proxy, javascript, javascript-library, npm-package, proxy
- Language: TypeScript
- Homepage:
- Size: 69.3 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Objectionable
When something is mutating your data, and you don't know what it is, find it `objectionable`.
This will setup a deep proxy that will alert you whenever an object is mutated.
```ts
let objected = objectionable([{ a: [0, { b: [{ c: 1 }] }] }]);
objected[0].a[1].b[0].c = 2;
// Console.log >> "Set: /0/a/1/b/0/c to 2";
```
Check tests to see all covered cases. Some highlights-
- new key added
- editing existing value
- deep nesting, including mixed arrays and objects
- new value added to array
- length changed on array (implicitly and explicitly)
## Get started
1. Install:
```bash
npm install objectionable
pnpm add objectionable
yarn add objectionable
```
2. Import into your project:
```ts
import objectionable from "objectionable";
```
3. Wrap any assignments to the value you want to track with `objectionable`.
```ts
let observed = objectionable(newValue);
```
Any mutations to `observed` will be reported.
4. Fix the issue, and uninstall `objectionable`. This strategy may have unintended consequences, so it's not recommended to use it long term.
## Features:
1. No dependencies
1. Designed for temporary troubleshooting
1. 100% test coverage
1. Handles deeply nested array and objects
1. Helpful for troubleshooting React, Vue and Svelte reactivity issues.
## Options:
`setValue` - Boolean, defaults to true
If true, object setting acts as normal. If false, the value won't change, and an error will be thrown on every set.
`reporter` - callback, defaults to console.log of `Set: ${path} to ${value}`
Callback receives the following arguments-
- `object`- the entire observed object
- `prop`- the specific key being set
- `path`- a `/` separated path to the key
- `value`- the value being set
Example callback, which would throw an error when a specific key is changed-
```ts
const callback: ObjectionableReporterCallback = function (
object,
property,
path,
value
) {
if (path === "deep/path/set") {
throw new Error(`${path} set to ${value}`);
}
};
```
# Other options
- Roll your own recursive proxy.
- Certainly less overhead, but there are fair number of edge cases you may miss. For example, most StackOverflow solutions don't handle arrays.
- https://github.com/samvv/js-proxy-deep or https://github.com/qiwi/deep-proxy
- Allows for more use cases of proxies, but requires more setup to solve this particular use.
# Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.