WhyNotJS

You're staring at a bug. Some property is wrong. You have no idea who changed it, when, or from where.

console.log everywhere. Breakpoints. git blame on a file that touches the object in 6 places. Thirty minutes later you find it.

There's a better way.

import { track, why } from "whynotjs";

const user = track({ name: "Hritik", age: 25 });

// …mutations happen across your entire codebase…

why(user, "name");
// Changed 2 times
//
// 1. Old → Hritik  New → John
//    Source: ProfileForm.tsx:24  (handleSubmit)
//    Time:   10:22 PM
//
// 2. Old → John    New → Jane
//    Source: UserSettings.tsx:87  (onSave)
//    Time:   10:45 PM

One line to opt in. No store. No actions. No boilerplate. Works on any plain JavaScript object.

Install

npm install whynotjs

How it works

WhyNotJS wraps your object in a native Proxy. Every mutation fires the set trap, which captures an Error stack trace at that exact moment, parses out the call-site, and stores a ChangeRecord in a WeakMap keyed to your object.

track(obj)
  └─ new Proxy(obj, { set, deleteProperty })
       └─ mutation fires → new Error().stack
            └─ parse call-site  (file · line · col · fn)
                 └─ push ChangeRecord into WeakMap<target, Map<prop, history>>
                      └─ why(obj, prop)  reads it back

Four deliberate design decisions:

• WeakMap as the store — your object can be garbage-collected normally. No leaks, no cleanup required (unless you want it with untrack).
• Error.stack for call-sites — no bundler plugin, no source-map server, no build step. It's just a standard V8/SpiderMonkey stack trace, parsed at runtime.
• Reflect alongside Proxy — every trap delegates through Reflect so prototype chains, getters, and class instances all behave correctly.
• No-op on identical values — obj.x = obj.x records nothing. The guard is oldValue !== newValue before any write.

This is the same primitive Vue 3's reactive(), MobX, and Immer are built on. WhyNotJS just exposes the audit trail instead of hiding it.

API

track(obj, options?)

Wrap an object. Returns a Proxy — use it everywhere you'd use the original.

const user   = track({ name: "Hritik", age: 25 });
const config = track({ theme: "dark" }, { verbose: true });

| Option | Type | Default | Description | |---|---|---|---| | maxHistory | number | 50 | Sliding-window cap per property. Oldest records are evicted. | | onchange | (record: ChangeRecord) => void | noop | Fires on every mutation. | | verbose | boolean | false | Logs every change to the console automatically. | | ignore | Array<string \| RegExp> | [] | Properties to skip. | | watch | Array<string \| symbol> | [] | When set, only these properties are tracked. |

why(obj, property)

Full change history for one property.

const report = why(user, "name");

report.count                       // 2
report.changes[0].oldValue         // "Hritik"
report.changes[0].newValue         // "John"
report.changes[0].source           // { file: "ProfileForm.tsx", line: 24, col: 14, fn: "handleSubmit" }
report.changes[0].time             // "10:22 PM"
report.changes[0].timestamp        // "2024-01-15T22:22:00.000Z"

whyAll(obj)

History for every property at once.

const all = whyAll(user);
// { name: WhyReport, age: WhyReport }

print(obj, property)

Pretty-prints to the console using console.group.

print(user, "name");
// [WhyNotJS] .name changed 2 times
//   1. 10:22 PM
//      Old → Hritik  /  New → John
//      ProfileForm.tsx:24 (handleSubmit)
//   2. 10:45 PM
//      Old → John  /  New → Jane
//      UserSettings.tsx:87 (onSave)

reset(obj, property?)

Clear history for one property, or all of them.

reset(user, "name");   // clears .name only
reset(user);           // clears everything

untrack(obj)

Stop tracking entirely and free the WeakMap entry.

untrack(user);

Recipes

React — debug a form without touching state

import { useRef } from "react";
import { track, print } from "whynotjs";

function ProfileForm() {
  const user = useRef(track({ name: "", email: "" })).current;

  return (
    <input
      onChange={e => {
        user.name = e.target.value;       // tracked
        print(user, "name");              // log it any time
      }}
    />
  );
}

Reactive callback — build a mini event system

const store = track(
  { status: "idle", retries: 0 },
  {
    onchange({ property, oldValue, newValue, source, time }) {
      logger.info(`[${time}] ${String(property)}: ${oldValue} → ${newValue}`, source);
    },
  }
);

Audit trail — know exactly what your async code touched

const order = track({ status: "pending", total: 0 });

await processPayment(order);   // black box

print(order, "status");
// Changed 3 times:  pending → validating → charging → complete
// Each with source file + line

Bounded history — keep only the last N changes

const sensor = track({ temp: 0 }, { maxHistory: 10 });

// Stream in 1000 readings — only the last 10 are kept
readings.forEach(r => (sensor.temp = r));

why(sensor, "temp").changes.length   // 10

Ignore internals with a regex

const model = track(obj, { ignore: [/^_/, /^__/] });
// _id, __proto__, _rev — all ignored
// Only public properties are tracked

TypeScript

Written in TypeScript. Full types included, no @types/ package needed.

import type { ChangeRecord, WhyReport, WhyNotOptions, SourceInfo } from "whynotjs";

Compatibility

Requires native Proxy (ES2015+). Cannot be polyfilled.

| Runtime | Minimum version | |---|---| | Node.js | 14 | | Chrome / Edge | 49 | | Firefox | 18 | | Safari | 10 |

License

MIT