You are building a reactive state layer on top of JavaScript Proxy. How do you decide between wrapping the object graph deeply and wrapping only the top level, and what does the deep option force you to build?

## The decision, stated properly The question is not 'deep or shallow' in the abstract; it is *what mutation style do the callers use, and what identity guarantees do they need*. Deep wrapping buys ergonomics — write to any nesting level and it is observed. Shallow wrapping buys predictability — exactly one object is special, and everything reachable from it is ordinary data. If the surrounding codebase already replaces subtrees immutably (a store that assigns a fresh object at the top), deep wrapping is machinery bought for nothing. If callers mutate in place at arbitrary depth, shallow wrapping means every such write silently fails to notify, which is the worst possible failure mode: correct-looking code that does not update. ## What deep wrapping forces you to build **Lazy wrapping, never eager.** Walking the graph at creation is O(nodes) up front and wraps subtrees nobody ever reads. Instead the `get` trap wraps nested objects on first access: ```js const proxyCache = new WeakMap(); // target -> proxy const rawCache = new WeakMap(); // proxy -> target function reactive(target) { if (!isPlainish(target)) return target; // skip list, see below if (rawCache.has(target)) return target; // already a proxy const existing = proxyCache.get(target); if (existing) return existing; const proxy = new Proxy(target, { get(t, key, receiver) { track(t, key); return reactive(Reflect.get(t, key, receiver)); }, set(t, key, value, receiver) { const ok = Reflect.set(t, key, toRaw(value), receiver); trigger(t, key); return ok; } }); proxyCache.set(target, proxy); rawCache.set(proxy, target); return proxy; } function toRaw(v) { return rawCache.get(v) ?? v; } ``` **A target-to-proxy cache.** Without it, two reads of `state.user` return two different proxies, so `state.user === state.user` is `false`. That breaks memoisation, dependency comparison, keyed list diffing and every `Set`-based dedup downstream. `WeakMap` is the right structure because it does not keep dead targets alive. **A raw hatch and a normalization rule.** You need `toRaw` for serialization, `structuredClone`, worker transfer and object-keyed caches, all of which reject or mis-key a proxy. You also need a rule about what happens when a proxy is *written into* the graph: storing the raw value (as above) keeps one canonical object per node and avoids proxies of proxies. Whatever you choose, document it, because the alternative is raw and wrapped references to the same node circulating together and comparing unequal. **A skip list.** Objects a Proxy cannot transparently wrap must be handed through raw: class instances with `#private` fields, `Map`/`Set`/`WeakMap`/`Date`/typed arrays/`ArrayBuffer`, promises, and DOM nodes — all of them throw on method calls made with the proxy as receiver. Frozen objects are a separate hazard: proxy invariants forbid reporting a value different from a non-configurable, non-writable own property, so a wrapper that transforms values will throw on frozen data. If you want reactive `Map` and `Set`, you cannot rely on forwarding at all; you must return instrumented replacements for their methods, bound to the raw collection, and track on the collection rather than on a key. **Array handling.** Index writes and `length` writes both surface as `set` traps, so a single `push` fires more than one notification unless you batch. Deciding whether observers see one change or several is a design decision, not an implementation detail. ## The costs you are signing up for Every nesting level in an access path is another trap call, so hot paths pay proportionally. Debugging gets harder: a stack trace shows the mutation site, not the observer that reacted, and a devtools inspection of a proxied object shows the proxy's traps rather than plain data. And you have introduced a rule the whole team must internalise — where the boundary between reactive and raw sits, and which one crosses a serialization or worker boundary. ## How I would decide Default to shallow. Go deep only when three things hold: callers genuinely mutate in place at depth, the data is coordination-shaped rather than bulk numeric, and you are prepared to own the cache, the unwrap hatch and the skip list as first-class API. When only part of the state needs depth, split the store — a deeply reactive object for the small mutable region, raw references for bulk data — rather than making the whole graph pay. And whichever you choose, make the boundary visible in the type or naming so that the next reader does not guess.