flugrekorder 1.1.0 → 1.2.0

package/dist/flugrekorder.d.ts

@@ -1,11 +1,10 @@
 import { Writable } from 'node:stream';
 
-/** Any value that can be wrapped in a Proxy — objects and functions. */
-type Proxiable = object | Function;
+type Proxiable = object;
 /** Reflect traps that operate on a property — carry a parent ID and key in their origin. */
 type PropertyTrap = 'get' | 'set' | 'defineProperty' | 'getOwnPropertyDescriptor';
-/** Reflect traps that invoke a callable — carry a source ID in their origin. */
-type CallTrap = 'apply' | 'construct';
+/** Reflect traps that invoke a callable — carry a source ID in their origin. Includes synthetic variants for native boundary crossings. */
+type CallTrap = 'apply' | 'construct' | 'apply:native' | 'construct:native' | 'apply:structure' | 'apply:private';
 /** Describes how a proxy was created — which trap fired, on which parent, and under which key or source. Null for root proxies. */
 type Origin = {
     trap: PropertyTrap;
@@ -24,12 +23,24 @@ type SerializedOrigin = {
     trap: CallTrap;
     source: string;
 } | null;
-/** A JSON-safe representation of any value. Proxiable values are replaced with `{ $proxy: id }` tags. */
+/** A JSON-safe representation of any value. Proxiable values are replaced with `{ $proxy: id }` tags. Raw targets (proxiable values known to the graph but passed unwrapped) are tagged `{ $unwrap: { $proxy: id } }`. */
 type Serialized = string | number | boolean | bigint | null | undefined | {
     readonly $proxy: string;
+} | {
+    readonly $unwrap: {
+        readonly $proxy: string;
+    };
 } | Array<Serialized> | {
     [key: string]: Serialized;
 };
+/** Returns true for any value that can meaningfully be wrapped in a Proxy. */
+declare function isProxiable(value: unknown): value is Proxiable;
+/**
+ * Determines whether and how a key/value pair should be redacted during serialization.
+ * Return `false` to keep as-is, `true` to replace with `"[redacted]"`,
+ * a string to use as a custom replacement, or `null` to drop the key entirely.
+ */
+type Redactor = (key: string | symbol, value: unknown, target: object) => string | boolean | null;
 /** A single recorded interaction — one Reflect trap firing on one proxy. */
 type Rekording = {
     id: string;
@@ -37,25 +48,14 @@ type Rekording = {
     origin: SerializedOrigin;
     args: Array<Serialized>;
     result: Serialized;
+    timestamp: number;
 };
-type CreateOptions = {
-    id?: number | (() => string);
-    recursive?: boolean;
-    only?: string[];
-} & ({
-    stream: Writable;
-    callback?: never;
-} | {
-    callback: (record: Rekording) => void;
-    stream?: never;
-});
-/**
- * Wraps `target` in a transparent recording proxy.
- * Every Reflect trap that fires emits a `Rekording` to `callback` or `stream`.
- */
-declare function create<T extends Proxiable>(target: T, options: CreateOptions): T;
-/** Returns `true` if `value` is a proxy created by this module. */
-declare function isFlugrekorder(value: unknown): value is Proxiable;
+
+/** Converts a `Rekording` to a human-readable string.
+ * When `proxy` is supplied, `{ $proxy: id }` tags in args and results resolve to dotted paths.
+ * When omitted, raw IDs are shown instead. */
+declare function format(rekording: Rekording, proxy?: Proxiable): string;
+
 /** Returns the original unwrapped target of a proxy, or `null` for non-proxies. */
 declare function getTarget(pxy: Proxiable): Proxiable | null;
 /**
@@ -81,4 +81,29 @@ declare function getAncestors(pxy: Proxiable): Array<{
  */
 declare function getPath(pxy: Proxiable): string;
 
-export { type CallTrap, type Origin, type PropertyTrap, type Proxiable, type Rekording, type Serialized, create, getAncestors, getOrigin, getPath, getProxyById, getTarget, isFlugrekorder };
+type CommonCreateOptions = {
+    id?: number | (() => string);
+    recursive?: boolean;
+    only?: Array<string>;
+    filter?: (rekording: Rekording) => boolean;
+    depth?: number;
+    redact?: Redactor | Array<Redactor>;
+    truncate?: number;
+    bind?: boolean;
+};
+type StreamCreateOptions = CommonCreateOptions & {
+    stream: Writable;
+};
+type CallbackCreateOptions = CommonCreateOptions & {
+    callback: (record: Rekording) => void;
+};
+type CreateOptions = StreamCreateOptions | CallbackCreateOptions;
+/**
+ * Wraps `target` in a transparent recording proxy.
+ * Every Reflect trap that fires emits a `Rekording` to `callback` or `stream`.
+ */
+declare function create<T extends Proxiable>(target: T, options: CreateOptions): T;
+/** Returns `true` if `value` is a proxy created by this module. */
+declare function isFlugrekorder(value: unknown): value is Proxiable;
+
+export { type CallTrap, type Origin, type PropertyTrap, type Proxiable, type Redactor, type Rekording, type Serialized, create, format, getAncestors, getOrigin, getPath, getProxyById, getTarget, isFlugrekorder, isProxiable };