@specific.dev/spectest 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -26,8 +26,9 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 // `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
 // leaf read off a wrapped op result is raw and untagged, so an `expect(...)` on
 // it renders detached from its source op; `field` tags from the container so the
-// assertion still nests. (Base64-decoded values lose provenance the same way;
-// that case is the `.base64Decoded()` provenance transform on `expect(...)`.)
+// assertion still nests. (A decoded value loses provenance the same way — that
+// case is the `.transform(label, fn)` method every wrapped value carries, which
+// runs the still-tagged value through `fn` and re-wraps the result.)
 // To recover a raw value, call `.unwrap()` on it — spectest op results are
 // always wrapped (in every context), so the method is always there; there is no
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
@@ -1344,52 +1345,7 @@ interface Matchers {
   toHaveLength(n: number): void;
 }
 
-/**
- * Provenance-preserving transforms. Each returns a fresh {@link Expectation}
- * bound to the *decoded* value but still carrying the originating op's tag (its
- * path extended by a marker like `<base64>`), so the eventual assertion nests
- * under the source read in the timeline. This is what lets a value that must be
- * decoded through a plain function — `Buffer.from(x,"base64").toString()`,
- * `decodeURIComponent(x)` — be asserted on with the *full* matcher vocabulary
- * (`toHaveLength`, `toContain`, `toMatch`, …) without dropping to `expectRaw`,
- * which severs the link. Transforms chain (`.base64Decoded().urlDecoded()`),
- * and the matcher you finish with may be negated (`.base64Decoded().not.…`).
- *
- * They supersede the old `toBeBase64Of` matcher, which was equality-only:
- * `expect(secret.data?.X).base64Decoded().toBe("plain")` is the direct
- * replacement, and `.toHaveLength(32)` / `.toContain("redis://")` / `.toMatch(re)`
- * are the cases it couldn't express.
- */
-interface Transforms {
-  /** Interpret the value as a base64 string and decode it (UTF-8), mirroring
-   *  `Buffer.from(x, "base64").toString()`. Throws-as-failed-assertion if the
-   *  value isn't a string. */
-  base64Decoded(): Expectation;
-  /** URL-decode the value, mirroring `decodeURIComponent(x)`. Chains after
-   *  `base64Decoded()` for base64-then-URL-encoded values. */
-  urlDecoded(): Expectation;
-  /** Parse the value as JSON (`JSON.parse(x)`) and assert on the result with the
-   *  full matcher vocabulary — `toEqual` against the decoded object/array,
-   *  `toContain`/`toHaveLength` against a decoded array. Throws-as-failed-assertion
-   *  if the value isn't a string or isn't valid JSON. Chains after other
-   *  transforms (e.g. `base64Decoded().jsonDecoded()` for a base64-wrapped JSON
-   *  payload). The optional type parameter `T` annotates the decoded shape at the
-   *  call site (`jsonDecoded<User>()`) — it casts the parsed value, but, like the
-   *  matchers, is not enforced at runtime. */
-  jsonDecoded<T = unknown>(): Expectation;
-  /**
-   * Generic escape hatch: apply an arbitrary `fn` to the raw value and assert on
-   * the result, keeping provenance. `label` is a plain word (`"json"`,
-   * `"decompressed"`) appended to the op path so the timeline shows what was
-   * derived; the UI brackets it (`<json>`) to mark it as a derived step, so do
-   * **not** include the brackets yourself. Sugar like {@link base64Decoded} is
-   * built on this. If `fn` throws, the next assertion records as a failure
-   * describing the transform error.
-   */
-  transform(label: string, fn: (value: unknown) => unknown): Expectation;
-}
-
-export interface Expectation extends Matchers, Transforms {
+export interface Expectation extends Matchers {
   not: Matchers;
 }
 
@@ -1495,31 +1451,6 @@ function buildCore(
     });
     if (!passed) throw new ExpectationError(msg);
   };
-  // Apply `fn` to the raw value and rebuild against the result, extending the
-  // op path by a derived-step marker so the decoded value still nests under the
-  // source read. `label` is a plain word ("base64", "json"); the `<…>` marker
-  // syntax that distinguishes a transform from a real property read in the
-  // timeline is added here, so it lives in one place and never leaks into the
-  // API surface — the same convention `inspect.ts` uses for array methods
-  // (`<find>`, `<map>`). A throw becomes a `pendingError` on the returned
-  // Expectation rather than escaping — a malformed decode renders as a failed
-  // assertion in the timeline, not an unhandled exception. Propagates an
-  // existing `pendingError` untouched.
-  const applyTransform = (label: string, fn: (value: unknown) => unknown): Expectation => {
-    const marker = `<${label}>`;
-    const nextTag: OpTag | undefined = tag
-      ? { sourceSeq: tag.sourceSeq, path: [...tag.path, marker] }
-      : undefined;
-    if (pendingError !== undefined) {
-      return buildCore(undefined, nextTag, false, message, pendingError);
-    }
-    try {
-      return buildCore(fn(actual), nextTag, false, message);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      return buildCore(undefined, nextTag, false, message, `${marker}: ${detail}`);
-    }
-  };
   return {
     toBe(expected) {
       const exp = readRaw(expected);
@@ -1628,25 +1559,6 @@ function buildCore(
         { actual: len, pathSuffix: "length" },
       );
     },
-    transform(label, fn) {
-      return applyTransform(label, fn);
-    },
-    base64Decoded() {
-      return applyTransform("base64", (v) => {
-        if (typeof v !== "string") {
-          throw new Error(`base64Decoded expects a string, got ${typeof v}`);
-        }
-        return Buffer.from(v, "base64").toString();
-      });
-    },
-    urlDecoded() {
-      return applyTransform("urldecode", (v) => {
-        if (typeof v !== "string") {
-          throw new Error(`urlDecoded expects a string, got ${typeof v}`);
-        }
-        return decodeURIComponent(v);
-      });
-    },
     get not(): Matchers {
       // Re-pass the already-unwrapped value, tag and message so the tag and raw
       // label are preserved for the negated branch's AssertionEvent.

package/src/inspect.ts

@@ -248,6 +248,12 @@ function wrapObject<T extends object>(
           return () => readRaw(target);
         }
       }
+      // `.transform(label, fn)` — same shape/guard as `unwrap`: only intercept
+      // when the underlying object has no own `transform`, so a real data field
+      // named `transform` is never shadowed.
+      if (prop === "transform" && !(prop in (target as object))) {
+        return makeTransform(readRaw(target), sourceSeq, path);
+      }
       // Hide thenable-ness from `await`. We must never accidentally
       // implement `then`, or `await fetch(...)` would resolve to the
       // wrong thing if we ever wrapped a Promise (we don't, but be safe).
@@ -298,6 +304,34 @@ function wrapObject<T extends object>(
   return new Proxy(raw, handler);
 }
 
+// The `.transform(label, fn)` method every wrapper (carrier + object/array
+// proxy) carries — the value-level analogue of `.unwrap()`. It runs the raw
+// value through `fn` and re-`wrap`s the result with `path` extended by a
+// `<label>` derived-step marker, so the decoded value keeps the source op's
+// provenance (`sourceSeq`) and stays navigable: a later `expect(...)` on it, or
+// on a subfield, still nests under the originating op (`secret.data.config.<json>.tier`).
+// `label` is a plain word; the `<…>` brackets are added here so they never leak
+// into the call site (the same convention array methods use, `<find>`/`<map>`).
+// A throw in `fn` (a non-string value, malformed base64/JSON) is rethrown
+// prefixed with `<label>:`, failing the test at the bad value.
+function makeTransform(
+  raw: unknown,
+  sourceSeq: number | undefined,
+  path: readonly string[],
+): (label: string, fn: (raw: never) => unknown) => unknown {
+  return (label, fn) => {
+    const nextPath = [...path, `<${label}>`];
+    let result: unknown;
+    try {
+      result = (fn as (r: unknown) => unknown)(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`<${label}>: ${detail}`);
+    }
+    return wrap(result, sourceSeq, nextPath);
+  };
+}
+
 // Runtime shape of a primitive carrier: the public `Carrier<T>` surface
 // (`unwrap()`) plus the internal provenance symbols. Kept private so the
 // exported `Carrier<T>` stays clean.
@@ -316,6 +350,7 @@ function makeCarrier<T>(
     [OP_TAG]: tag,
     [UNWRAP]: raw,
     unwrap: () => raw,
+    transform: makeTransform(raw, sourceSeq, path) as unknown as Carrier<T>["transform"],
     // Coercion sinks recover the raw primitive instead of inheriting
     // Object.prototype's defaults ("[object Object]" / NaN / {}). A
     // carrier interpolated into a string, fed to arithmetic, `==`, or
@@ -338,10 +373,10 @@ function makeCarrier<T>(
 // passes them through raw. So `expect(row.deleted_at).toBe(null)` reaches
 // `expect()` as a bare `null` with no tag and renders as a disconnected
 // top-level row. `field` recovers the link by tagging from the *container*.
-// (Base64-decoded values lose their tag the same way, via the transform; that
-// case is handled by the `.base64Decoded()` provenance transform in index.ts,
-// which decodes the still-tagged value internally and rebuilds the Expectation
-// against the result.)
+// (A decoded value loses its tag the same way, through the decode; the
+// `.transform(label, fn)` method every wrapper carries (see `makeTransform`)
+// recovers it — it runs the still-tagged value through `fn` and re-`wrap`s the
+// result with the source path extended by a `<label>` marker.)
 // ───────────────────────────────────────────────────────────────────────────
 
 /**
@@ -410,6 +445,22 @@ export function field(value: unknown, ...path: Array<string | number>): unknown
 export interface Carrier<T> {
   /** Recover the raw underlying value. */
   unwrap(): T;
+  /**
+   * Run the raw value through `fn` and get back a provenance-carrying handle to
+   * the result — for asserting on a *decoded* value (base64, JSON, JWT, …) while
+   * keeping its link to the op that produced it. The op path is extended by a
+   * `<label>` marker, so a later `expect(...)` on the result still nests under
+   * the source op. `label` is a plain word (`"base64"`, `"json"`); the UI adds
+   * the `<…>` brackets, so don't include them yourself. `fn` receives the raw
+   * value (typed `T`), so no cast is needed. `R` types the result. A throw in
+   * `fn` is rethrown prefixed with `<label>:`, failing the test at the value.
+   *
+   * ```ts
+   * expect(secret.data.url.transform("base64", (s) => Buffer.from(s, "base64").toString()))
+   *   .toContain("redis://");
+   * ```
+   */
+  transform<R = unknown>(label: string, fn: (raw: T) => R): Wrapped<R>;
   /** Coerces to the raw value (arithmetic, `==`). */
   valueOf(): T;
   /** Renders the raw value (template interpolation). */
@@ -475,6 +526,9 @@ export type WrappedObject<T> = {
 } & {
   /** Recover the fully raw value (nested leaves unwrapped too). */
   unwrap(): T;
+  /** Run the raw object through `fn`, keeping provenance (op path + `<label>`),
+   *  and get back a navigable handle to the result. See {@link Carrier.transform}. */
+  transform<R = unknown>(label: string, fn: (raw: T) => R): Wrapped<R>;
 };
 
 /**
@@ -491,6 +545,9 @@ export interface WrappedArray<U> {
   readonly [index: number]: Wrapped<U>;
   /** Recover the raw array (elements unwrapped). */
   unwrap(): U[];
+  /** Run the raw array through `fn`, keeping provenance (op path + `<label>`),
+   *  and get back a navigable handle to the result. See {@link Carrier.transform}. */
+  transform<R = unknown>(label: string, fn: (raw: U[]) => R): Wrapped<R>;
   at(index: number): Wrapped<U> | undefined;
   find(
     predicate: (value: U, index: number, obj: U[]) => unknown,