@specific.dev/spectest 0.88.3 → 0.89.1

package/src/inspect.ts

@@ -240,6 +240,20 @@ export function wrap<T>(
   if (raw === null || raw === undefined) return raw;
   const t = typeof raw;
   if (t === "object") {
+    const native = readRaw(raw);
+    if (native instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && native instanceof SharedArrayBuffer)) {
+      return wrapNative(native, sourceSeq, path, new Set(["byteLength", "maxByteLength", "resizable", "growable", "detached"]),
+        new Set(["slice", "transfer", "transferToFixedLength"])) as T;
+    }
+    if (ArrayBuffer.isView(native)) {
+      return wrapNative(native, sourceSeq, path, new Set(["buffer", "byteLength", "byteOffset"]), BINARY_METHODS, true) as T;
+    }
+    if (native instanceof Blob) {
+      return wrapNative(native, sourceSeq, path, new Set(["size", "type", "name", "lastModified", "webkitRelativePath"]),
+        new Set(["slice", "text", "bytes", "arrayBuffer", "stream"])) as T;
+    }
+    if (native instanceof FormData) return wrapFormData(native, sourceSeq, path) as T;
+    if (native instanceof ReadableStream) return wrapStream(native, sourceSeq, path) as T;
     return wrapObject(raw as object, sourceSeq, path) as unknown as T;
   }
   if (t === "function") return raw;
@@ -578,12 +592,23 @@ export type Wrapped<T> = T extends null | undefined
   ? T
   : T extends readonly (infer U)[]
     ? WrappedArray<U>
-    : // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-      T extends (...args: never[]) => unknown
-      ? T
-      : T extends object
-        ? WrappedObject<T>
-        : Carrier<T>;
+    : T extends ArrayBuffer | SharedArrayBuffer
+      ? WrappedBuffer<T>
+      : T extends ArrayBufferView
+        ? WrappedBinaryView<T>
+        : T extends File
+          ? WrappedFile
+          : T extends Blob
+            ? WrappedBlob
+            : T extends FormData
+              ? WrappedFormData
+              : T extends ReadableStream<infer C>
+                ? WrappedStream<C>
+                : T extends (...args: never[]) => unknown
+                  ? T
+                  : T extends object
+                    ? WrappedObject<T>
+                    : Carrier<T>;
 
 /** A wrapped object: every own property is itself {@link Wrapped}, plus an
  *  `.unwrap()` that recovers the fully-raw value (all nested leaves raw). */
@@ -645,6 +670,188 @@ export interface WrappedArray<U> {
   [Symbol.iterator](): IterableIterator<U>;
 }
 
+/** Native objects need their own views: getters and methods must receive the
+ * real native receiver, and method results must be wrapped after they resolve.
+ * Iteration, callbacks, and control-flow flags on stream readers remain raw.
+ */
+type NativeResult<T> = T extends Promise<infer R> ? Promise<Wrapped<R>> : Wrapped<T>;
+type NativeView<T, K extends keyof T> = Omit<T, K> & {
+  readonly [P in K]: T[P] extends (...args: infer A) => infer R
+    ? (...args: A) => NativeResult<R> : Wrapped<T[P]>;
+} & {
+  unwrap(): T;
+  transform<R>(label: string, fn: (raw: T) => R): Wrapped<R>;
+};
+
+export type WrappedBuffer<T extends ArrayBuffer | SharedArrayBuffer = ArrayBuffer> = NativeView<T,
+  Extract<keyof T, "byteLength" | "maxByteLength" | "resizable" | "growable" | "detached" |
+    "slice" | "transfer" | "transferToFixedLength">>;
+
+const BINARY_METHOD_NAMES = [
+  "at", "slice", "subarray", "includes", "indexOf", "lastIndexOf", "find", "findLast",
+  "findIndex", "findLastIndex", "some", "every", "filter", "map", "join",
+  "fill", "copyWithin", "reverse", "sort", "toReversed", "toSorted", "with", "toHex", "toBase64",
+  "getInt8", "getUint8", "getInt16", "getUint16", "getInt32", "getUint32",
+  "getFloat16", "getFloat32", "getFloat64", "getBigInt64", "getBigUint64",
+] as const;
+const BINARY_METHODS = new Set<string>(BINARY_METHOD_NAMES);
+/** Numeric indexes carry provenance. Like WrappedArray, length and iteration
+ * stay raw; callbacks receive native values. Unwrap for native API inputs. */
+export type WrappedBinaryView<T extends ArrayBufferView> = NativeView<T,
+  Extract<keyof T, number | "buffer" | "byteLength" | "byteOffset" | typeof BINARY_METHOD_NAMES[number]>>;
+export type WrappedBytes = WrappedBinaryView<Uint8Array>;
+export type WrappedBlob = NativeView<Blob,
+  "size" | "type" | "slice" | "text" | "bytes" | "arrayBuffer" | "stream">;
+export type WrappedFile = NativeView<File,
+  "name" | "lastModified" | "webkitRelativePath" | "size" | "type" |
+  "slice" | "text" | "bytes" | "arrayBuffer" | "stream">;
+export type WrappedFormData = NativeView<FormData, "get" | "getAll" | "has">;
+
+export type WrappedReadResult<T> =
+  | { done: false; value: Wrapped<T> }
+  | { done: true; value: Wrapped<T> | undefined };
+export interface WrappedReader<T> extends Omit<ReadableStreamDefaultReader<T>, "read"> {
+  read(): Promise<WrappedReadResult<T>>;
+  unwrap(): ReadableStreamDefaultReader<T>;
+}
+export interface WrappedBYOBReader extends Omit<ReadableStreamBYOBReader, "read"> {
+  read<T extends ArrayBufferView>(view: T, options?: { min?: number }): Promise<WrappedReadResult<T>>;
+  unwrap(): ReadableStreamBYOBReader;
+}
+export interface WrappedStream<T> extends Omit<ReadableStream<T>, "getReader" | "tee" | "pipeThrough"> {
+  getReader(): WrappedReader<T>;
+  getReader(options: { mode: "byob" }): WrappedBYOBReader;
+  getReader(options: ReadableStreamGetReaderOptions): WrappedReader<T> | WrappedBYOBReader;
+  tee(): [WrappedStream<T>, WrappedStream<T>];
+  pipeThrough<R>(transform: ReadableWritablePair<R, any>, options?: StreamPipeOptions): WrappedStream<R>;
+  unwrap(): ReadableStream<T>;
+  transform<R>(label: string, fn: (raw: ReadableStream<T>) => R): Wrapped<R>;
+}
+
+function wrapNative<T extends object>(
+  raw: T, sourceSeq: number | undefined, path: readonly string[],
+  properties: ReadonlySet<string>, methods: ReadonlySet<string>, indexes = false,
+): T {
+  const tag: OpTag = { sourceSeq, path };
+  return new Proxy(raw, {
+    get(target, prop) {
+      if (prop === OP_TAG) return tag;
+      if (prop === UNWRAP) return target;
+      if (prop === "unwrap") return () => target;
+      if (prop === "transform") return makeTransform(target, sourceSeq, path);
+      const value = Reflect.get(target, prop, target);
+      if (typeof prop === "string") {
+        if (properties.has(prop) || (indexes && /^(0|[1-9]\d*)$/.test(prop))) {
+          return wrapChild(value, sourceSeq, [...path, prop]);
+        }
+        if (methods.has(prop) && typeof value === "function") {
+          return (...args: unknown[]) => {
+            const result = value.apply(target, args);
+            const resultPath = [...path, `<${prop}>`];
+            return result instanceof Promise
+              ? result.then((v) => wrapChild(v, sourceSeq, resultPath))
+              : wrapChild(result, sourceSeq, resultPath);
+          };
+        }
+      }
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+    has(target, prop) {
+      return prop === OP_TAG || prop === UNWRAP || Reflect.has(target, prop);
+    },
+  });
+}
+
+function wrapFormData(raw: FormData, sourceSeq: number | undefined, path: readonly string[]): FormData {
+  const base = wrapNative(raw, sourceSeq, path, new Set(), new Set());
+  return new Proxy(base, {
+    get(target, prop) {
+      if (prop === "get" || prop === "getAll" || prop === "has") {
+        return (name: string) => wrapChild(raw[prop](name), sourceSeq,
+          prop === "get" ? [...path, name] : [...path, name, `<${prop}>`]);
+      }
+      return Reflect.get(target, prop);
+    },
+  });
+}
+
+function wrapStream<T>(raw: ReadableStream<T>, sourceSeq: number | undefined, path: readonly string[]): ReadableStream<T> {
+  const base = wrapNative(raw, sourceSeq, path, new Set(), new Set(["pipeThrough"]));
+  return new Proxy(base, {
+    get(target, prop) {
+      if (prop === "tee") return () => raw.tee().map((s, i) => wrapStream(s, sourceSeq, [...path, `<tee>`, String(i)]));
+      if (prop === "getReader") return (options?: ReadableStreamGetReaderOptions) => {
+        const reader = raw.getReader(options!);
+        let index = 0;
+        return new Proxy(reader, {
+          get(r, key) {
+            if (key === "unwrap" || key === UNWRAP) return key === "unwrap" ? () => r : r;
+            if (key === OP_TAG) return { sourceSeq, path };
+            if (key === "read") return async (...args: unknown[]) => {
+              const read = r.read as (...args: unknown[]) => Promise<ReadableStreamReadResult<T>>;
+              const result = await read.apply(r, args);
+              const valuePath = [...path, "<read>", String(index++)];
+              // done stays a real boolean so normal reader loops terminate.
+              return { done: result.done, get value() { return wrapChild(result.value, sourceSeq, valuePath); } };
+            };
+            const value = Reflect.get(r, key, r);
+            return typeof value === "function" ? value.bind(r) : value;
+          },
+          has(r, key) { return key === UNWRAP || key === OP_TAG || Reflect.has(r, key); },
+        });
+      };
+      return Reflect.get(target, prop);
+    },
+  });
+}
+
+/** Response headers whose lookups retain the originating HTTP call's provenance.
+ * Missing headers remain `null`; `expect(headers.get(name)).toBe(null)` still
+ * links to the call. Iterators and other native methods return raw values.
+ */
+export interface WrappedHeaders extends Omit<Headers, "get" | "has" | "getSetCookie" | "getAll" | "toJSON" | "count"> {
+  get(name: string): Carrier<string> | null;
+  /** Unwrap before using the result as a condition. */
+  has(name: string): Carrier<boolean>;
+  getSetCookie(): WrappedArray<string>;
+  getAll(name: "set-cookie" | "Set-Cookie"): WrappedArray<string>;
+  toJSON(): Wrapped<Record<string, string | string[]>>;
+  readonly count: Carrier<number>;
+  unwrap(): Headers;
+  transform<R = unknown>(label: string, fn: (raw: Headers) => R): Wrapped<R>;
+}
+
+function wrapHeaders(headers: Headers, sourceSeq: number | undefined): WrappedHeaders {
+  const path = ["headers"];
+  const tag: OpTag = { sourceSeq, path };
+  return new Proxy(headers, {
+    get(target, prop) {
+      if (prop === OP_TAG) return tag;
+      if (prop === UNWRAP) return target;
+      if (prop === "unwrap") return () => target;
+      if (prop === "transform") return makeTransform(target, sourceSeq, path);
+      if (prop === "get" || prop === "has") {
+        return (name: string) => wrapChild(
+          target[prop](name), sourceSeq,
+          prop === "get" ? [...path, name.toLowerCase()] : [...path, name.toLowerCase(), "<has>"],
+        );
+      }
+      if (prop === "count") return wrap(target.count, sourceSeq, [...path, "count"]);
+      if (prop === "getAll") return (name: "set-cookie" | "Set-Cookie") => wrap(target.getAll(name), sourceSeq, [...path, name.toLowerCase()]);
+      if (prop === "toJSON") return () => wrap(target.toJSON(), sourceSeq, path);
+      if (prop === "getSetCookie") {
+        return () => wrap(target.getSetCookie(), sourceSeq, [...path, "set-cookie"]);
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+    has(target, prop) {
+      if (prop === OP_TAG || prop === UNWRAP) return true;
+      return Reflect.has(target, prop);
+    },
+  }) as unknown as WrappedHeaders;
+}
+
 /**
  * The view `ctx.fetch` resolves to in every context (a spectest op wraps
  * unconditionally): a {@link Response} whose status-line accessors are
@@ -653,8 +860,9 @@ export interface WrappedArray<U> {
  * used to silently always be false. Compare `res.status.unwrap() === 200`
  * or `res.unwrap().status === 200`, or assert with `expect(res.status)`.
  *
- * `json<T>()` / `text()` return {@link Wrapped} body values; `.unwrap()`
- * (or {@link unwrap the whole response}) recovers the plain `Response`.
+ * All body readers return provenance-carrying values, including binary bodies,
+ * blobs and form data. `.unwrap()` recovers the native response or body value.
+ * Stream reader `done` and stream `locked` remain raw control-flow booleans.
  */
 export interface WrappedResponse {
   readonly status: Carrier<number>;
@@ -663,13 +871,15 @@ export interface WrappedResponse {
   readonly url: Carrier<string>;
   readonly redirected: Carrier<boolean>;
   readonly type: Carrier<string>;
-  readonly headers: Headers;
-  readonly bodyUsed: boolean;
+  readonly headers: WrappedHeaders;
+  readonly bodyUsed: Carrier<boolean>;
+  readonly body: WrappedStream<Uint8Array> | null;
   json<T = unknown>(): Promise<Wrapped<T>>;
   text(): Promise<Carrier<string>>;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  blob(): Promise<Blob>;
-  formData(): Promise<FormData>;
+  arrayBuffer(): Promise<WrappedBuffer>;
+  bytes(): Promise<WrappedBytes>;
+  blob(): Promise<WrappedBlob>;
+  formData(): Promise<WrappedFormData>;
   clone(): WrappedResponse;
   /** Recover the underlying raw {@link Response} (a real `number` status,
    *  an unwrapped body, etc.). */
@@ -680,18 +890,27 @@ export interface WrappedResponse {
  *  {@link WrappedResponse} so reads carry provenance into assertions. */
 export type SpectestFetch = (
   input: RequestInfo | URL,
-  init?: RequestInit,
+  init?: SpectestRequestInit,
 ) => Promise<WrappedResponse>;
 
+export interface SpectestRequestInit extends RequestInit {
+  /** Skip the recorder's body capture for open-ended streams. SSE skips it
+   * automatically. The response and assertions remain recorded. */
+  captureBody?: boolean;
+}
+
 /**
  * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
  * `statusText` / `url` / `redirected` / `type` return carriers tagged
- * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
- * resolved value wrapped under `path: ["body"]`. Everything else passes
- * through bound to the real Response.
+ * to `sourceSeq`. Every body-reading method returns its resolved value
+ * wrapped under `path: ["body"]`. Header lookups carry paths
+ * under `headers`, and clones retain the same provenance. Everything else
+ * passes through bound to the real Response.
  */
 export function wrapResponse(res: Response, sourceSeq: number | undefined): WrappedResponse {
   const tag: OpTag = { sourceSeq, path: [] };
+  let headers: WrappedHeaders | undefined;
+  let body: ReadableStream<Uint8Array> | undefined;
   const carrierProps = new Set([
     "status",
     "ok",
@@ -699,8 +918,9 @@ export function wrapResponse(res: Response, sourceSeq: number | undefined): Wrap
     "url",
     "redirected",
     "type",
+    "bodyUsed",
   ]);
-  const bodyMethods = new Set(["json", "text"]);
+  const bodyMethods = new Set(["json", "text", "bytes", "arrayBuffer", "blob", "formData"]);
   const handler: ProxyHandler<Response> = {
     get(target, prop) {
       if (prop === OP_TAG) return tag;
@@ -708,6 +928,12 @@ export function wrapResponse(res: Response, sourceSeq: number | undefined): Wrap
       // Full recursive unwrap (see the note in `wrapObject`).
       if (prop === "unwrap") return () => readRaw(target);
       if (prop === "then") return undefined;
+      if (prop === "headers") return headers ??= wrapHeaders(target.headers, sourceSeq);
+      if (prop === "body") {
+        if (target.body === null) return wrapChild(null, sourceSeq, ["body"]);
+        return body ??= wrapStream(target.body, sourceSeq, ["body"]);
+      }
+      if (prop === "clone") return () => wrapResponse(target.clone(), sourceSeq);
 
       if (typeof prop === "string" && carrierProps.has(prop)) {
         const value = (target as unknown as Record<string, unknown>)[prop];
@@ -720,7 +946,7 @@ export function wrapResponse(res: Response, sourceSeq: number | undefined): Wrap
         if (typeof fn !== "function") return fn;
         return async (...args: unknown[]) => {
           const value = await fn.apply(target, args);
-          return wrap(value, sourceSeq, ["body"]);
+          return wrapChild(value, sourceSeq, ["body"]);
         };
       }
       const value = (target as unknown as Record<string | symbol, unknown>)[