flugrekorder 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -194,6 +194,71 @@ type Rekording = {
 
 ---
 
+## Resolving paths inside a callback
+
+`getProxyById` and `getPath` are most useful when called *inside* the callback while the trap is still in context — not as a post-processing step on the raw recordings.
+
+When an `apply` trap fires, `origin.source` is the ID of the function proxy that was called. Resolving it immediately gives you a human-readable path:
+
+```ts
+let p!: typeof myService;
+
+p = create(myService, {
+  only: ['get', 'apply'],
+  callback(r) {
+    if (r.trap !== 'apply' || !r.origin || !('source' in r.origin)) return;
+    const fn = getProxyById(r.origin.source, p);
+    if (fn) console.log('called:', getPath(fn)); // e.g. "users.find"
+  },
+});
+```
+
+The same pattern works for `set` traps — `origin.parent` is the ID of the proxy being written to:
+
+```ts
+let p!: typeof config;
+
+p = create(config, {
+  callback(r) {
+    if (r.trap !== 'set' || !r.origin || !('parent' in r.origin)) return;
+    const parent = getProxyById(r.origin.parent, p);
+    const prefix = parent ? getPath(parent) : '';
+    console.log(`${prefix ? `${prefix}.` : ''}${r.origin.key} =`, r.args[2]);
+    // e.g. "db.port = 5433"
+  },
+});
+```
+
+Note the `let p!: typeof …` pattern: the callback closes over `p` before it is assigned, but `p` is fully set by the time any trap fires, so the reference is always valid.
+
+---
+
+## How it works
+
+### One graph per session
+
+Every `create()` call produces an isolated `Graph` — a session-scoped registry that maps proxies, targets, and IDs to each other. Once all references to a proxied tree are dropped, the graph is eligible for garbage collection. There are no module-level leaks between independent recordings.
+
+### Structured origin
+
+Each proxy carries an `Origin` that describes exactly how it was created: which trap fired, on which parent proxy, and under which key (for property traps) or from which function proxy (for call traps). This makes the recording self-describing — you can reconstruct a full call graph from the records alone, without keeping any external state.
+
+Earlier designs tracked paths as arrays of keys. That approach broke down when the same object was accessed via different routes, or when proxies were collected before the path could be read. Storing a parent ID and a key instead of a full path makes the origin both stable and compact.
+
+### `{ $proxy: id }` serialization
+
+Proxiable values (objects and functions) in args and results are replaced with `{ $proxy: '<id>' }` tags rather than inlined. This keeps records JSON-safe, avoids circular reference problems, and lets you resolve references back to live proxies via `getProxyById` when needed.
+
+### Promises
+
+Promises cannot be proxied directly — native `.then()` checks for the `[[PromiseState]]` internal slot and throws if `this` is a Proxy. Instead, flugrekorder returns a new Promise that resolves to a proxy of the settled value, maintaining the stability guarantee across async boundaries.
+
+### `wrap` vs `wrapKnown`
+
+Trap specs use two wrapping modes. `wrap` creates a new proxy for any proxiable value not already in the graph — used for results, where a newly returned object should be recorded. `wrapKnown` only wraps values that are already in the graph — used for call arguments, where passing a plain object to a proxied function should not silently create a new proxy out of it.
+
+---
+
 ## Examples
 
 ### Stream interactions to a file (NDJSON)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flugrekorder",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "publishConfig": {
     "access": "public"
   },