@zerotal/core 1.0.0

package/src/http/Http.ts

@@ -0,0 +1,298 @@
+/**
+ * The `Http` facade — a fluent, static entry point for making outgoing HTTP
+ * requests, plus the test helpers (`fake`, `assertSent`, …) for intercepting
+ * and asserting on them.
+ */
+import {
+  PendingRequest,
+  _installFakes,
+  _clearFakes,
+  _getRecorded,
+  type FakeStub,
+} from "./HttpClient.ts";
+
+/**
+ * Fluent facade for outgoing (server-to-server) HTTP requests. Static verb
+ * methods ({@link Http.get}, {@link Http.post}, …) return a {@link PendingRequest}
+ * that can be awaited directly or chained (`.json()`, `.text()`). Prefix a request
+ * with configuration ({@link Http.withHeaders}, {@link Http.withToken},
+ * {@link Http.timeout}, {@link Http.retry}) to apply it before the verb.
+ *
+ * The `fake`/`assert*` helpers intercept requests in tests so no real network
+ * traffic occurs.
+ *
+ * @example
+ * ```ts
+ * // GET with a custom header, retry, and timeout
+ * const users = await Http
+ *   .withHeaders({ "X-Trace": "abc" })
+ *   .retry(3, 200)      // up to 3 attempts, 200ms apart
+ *   .timeout(5000)      // abort after 5s
+ *   .get("https://api.example.com/users")
+ *   .json();
+ *
+ * // POST a JSON body with a bearer token
+ * const created = await Http
+ *   .withToken("secret")
+ *   .post("https://api.example.com/users", { name: "Alice" })
+ *   .json();
+ *
+ * // Testing — intercept requests
+ * Http.fake([{ url: "https://api.example.com/*", body: { ok: true } }]);
+ * await Http.get("https://api.example.com/users");
+ * Http.assertSent((req) => req.url.includes("/users"));
+ * Http.resetFakes();
+ * ```
+ */
+export class Http {
+  // ── Instance builder (for chaining global options before the method) ─────
+
+  /**
+   * Start a request with the given headers applied.
+   * Returns a builder whose `get`/`post`/etc. methods issue the actual request.
+   * @category Configuration
+   */
+  static withHeaders(headers: Record<string, string>): _Builder {
+    return new _Builder().withHeaders(headers);
+  }
+
+  /**
+   * Set a Bearer token on the next request.
+   * @category Configuration
+   */
+  static withToken(token: string): _Builder {
+    return new _Builder().withToken(token);
+  }
+
+  /**
+   * Set HTTP Basic Auth credentials.
+   * @category Configuration
+   */
+  static withBasicAuth(username: string, password: string): _Builder {
+    return new _Builder().withBasicAuth(username, password);
+  }
+
+  /**
+   * Set the request timeout in milliseconds.
+   * @category Retries & resilience
+   */
+  static timeout(milliseconds: number): _Builder {
+    return new _Builder().timeout(milliseconds);
+  }
+
+  /**
+   * Retry up to `times` times with optional delay.
+   * @category Retries & resilience
+   */
+  static retry(times: number, delay?: number): _Builder {
+    return new _Builder().retry(times, delay);
+  }
+
+  // ── Verb shortcuts ────────────────────────────────────────────────────────
+
+  /**
+   * Begin a GET request to `url`.
+   * @category Requests
+   */
+  static get(url: string): PendingRequest {
+    return new PendingRequest("GET", url);
+  }
+
+  /**
+   * Begin a POST request to `url`, attaching `data` as a JSON body when given.
+   * @category Requests
+   */
+  static post(url: string, data?: unknown): PendingRequest {
+    const request = new PendingRequest("POST", url);
+    if (data !== undefined) request.withJson(data);
+    return request;
+  }
+
+  /**
+   * Begin a PUT request to `url`, attaching `data` as a JSON body when given.
+   * @category Requests
+   */
+  static put(url: string, data?: unknown): PendingRequest {
+    const request = new PendingRequest("PUT", url);
+    if (data !== undefined) request.withJson(data);
+    return request;
+  }
+
+  /**
+   * Begin a PATCH request to `url`, attaching `data` as a JSON body when given.
+   * @category Requests
+   */
+  static patch(url: string, data?: unknown): PendingRequest {
+    const request = new PendingRequest("PATCH", url);
+    if (data !== undefined) request.withJson(data);
+    return request;
+  }
+
+  /**
+   * Begin a DELETE request to `url`.
+   * @category Requests
+   */
+  static delete(url: string): PendingRequest {
+    return new PendingRequest("DELETE", url);
+  }
+
+  /**
+   * Begin a HEAD request to `url`.
+   * @category Requests
+   */
+  static head(url: string): PendingRequest {
+    return new PendingRequest("HEAD", url);
+  }
+
+  // ── Fake / testing ────────────────────────────────────────────────────────
+
+  /**
+   * Intercept all outgoing HTTP requests with the given stubs.
+   * No real HTTP requests will be made while fakes are active.
+   *
+   * @param stubs Array of URL-response pairs. Use `'*'` to match any URL.
+   * @category Testing
+   * @example
+   * Http.fake([
+   *   { url: 'https://api.example.com/users', body: [{ id: 1 }] },
+   *   { url: '*', status: 503 },
+   * ]);
+   */
+  static fake(stubs: FakeStub[] = [{ url: "*" }]): void {
+    _installFakes(stubs);
+  }
+
+  /**
+   * Remove all fake stubs and restore real HTTP behaviour.
+   * @category Testing
+   */
+  static resetFakes(): void {
+    _clearFakes();
+  }
+
+  /**
+   * Return all requests recorded since `Http.fake()` was called.
+   * @category Testing
+   */
+  static recorded(): Array<{ method: string; url: string; options: RequestInit }> {
+    return _getRecorded();
+  }
+
+  /**
+   * Assert that at least one recorded request matches the predicate.
+   * @category Testing
+   * @throws {Error} when no recorded request matches.
+   */
+  static assertSent(predicate: (req: { method: string; url: string }) => boolean): void {
+    const recorded = _getRecorded();
+    const match = recorded.some(predicate);
+    if (!match) {
+      throw new Error(
+        `Http.assertSent: no recorded request matched the predicate.\n` +
+          `Recorded: ${JSON.stringify(
+            recorded.map((entry) => `${entry.method} ${entry.url}`),
+            null,
+            2,
+          )}`,
+      );
+    }
+  }
+
+  /**
+   * Assert that no recorded request matches the predicate.
+   * @category Testing
+   * @throws {Error} when a recorded request matches.
+   */
+  static assertNotSent(predicate: (req: { method: string; url: string }) => boolean): void {
+    const recorded = _getRecorded();
+    const match = recorded.some(predicate);
+    if (match) {
+      const found = recorded.filter(predicate).map((entry) => `${entry.method} ${entry.url}`);
+      throw new Error(`Http.assertNotSent: unexpected request(s) matched: ${found.join(", ")}`);
+    }
+  }
+
+  /**
+   * Assert that exactly `count` requests were recorded.
+   * @category Testing
+   * @throws {Error} when the recorded count differs from `count`.
+   */
+  static assertSentCount(count: number): void {
+    const actual = _getRecorded().length;
+    if (actual !== count) {
+      throw new Error(`Http.assertSentCount: expected ${count}, got ${actual}.`);
+    }
+  }
+
+  /**
+   * Assert that no requests were recorded.
+   * @category Testing
+   * @throws {Error} when any request was recorded.
+   */
+  static assertNothingSent(): void {
+    Http.assertSentCount(0);
+  }
+}
+
+// ── Internal pre-configured builder ──────────────────────────────────────────
+// Http.withToken(...).get(url) pattern
+
+class _Builder {
+  private _headers: Record<string, string> = {};
+  private _timeoutMs: number | undefined = undefined;
+  private _retries: number = 0;
+  private _retryDelay: number = 100;
+
+  withHeaders(headers: Record<string, string>): this {
+    Object.assign(this._headers, headers);
+    return this;
+  }
+  withToken(token: string): this {
+    this._headers["Authorization"] = `Bearer ${token}`;
+    return this;
+  }
+  withBasicAuth(username: string, password: string): this {
+    this._headers["Authorization"] = `Basic ${btoa(`${username}:${password}`)}`;
+    return this;
+  }
+  timeout(milliseconds: number): this {
+    this._timeoutMs = milliseconds;
+    return this;
+  }
+  retry(times: number, delay = 100): this {
+    this._retries = times;
+    this._retryDelay = delay;
+    return this;
+  }
+
+  private _build(
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD",
+    url: string,
+    data?: unknown,
+  ): PendingRequest {
+    const request = new PendingRequest(method, url).withHeaders(this._headers);
+    if (this._timeoutMs !== undefined) request.timeout(this._timeoutMs);
+    if (this._retries > 0) request.retry(this._retries, this._retryDelay);
+    if (data !== undefined) request.withJson(data);
+    return request;
+  }
+
+  get(url: string): PendingRequest {
+    return this._build("GET", url);
+  }
+  post(url: string, data?: unknown): PendingRequest {
+    return this._build("POST", url, data);
+  }
+  put(url: string, data?: unknown): PendingRequest {
+    return this._build("PUT", url, data);
+  }
+  patch(url: string, data?: unknown): PendingRequest {
+    return this._build("PATCH", url, data);
+  }
+  delete(url: string): PendingRequest {
+    return this._build("DELETE", url);
+  }
+  head(url: string): PendingRequest {
+    return this._build("HEAD", url);
+  }
+}

package/src/http/HttpClient.ts

@@ -0,0 +1,289 @@
+/**
+ * The HTTP client internals behind the `Http` facade: the fluent
+ * `PendingRequest` builder, the `HttpClientResponse` wrapper, and the
+ * request-interception machinery that powers `Http.fake()` in tests.
+ */
+import { ZerotalError } from "../errors/ZerotalError.ts";
+import { FrameworkEvents, OutgoingRequestCompleted } from "../events/FrameworkEvents.ts";
+
+/** An HTTP request method. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+/** A fake response definition matched by URL while `Http.fake()` is active. */
+export interface FakeStub {
+  /** URL to match — exact string or glob-style `*` wildcard. */
+  url: string;
+  status?: number;
+  /** Response body. If object/array, serialized as JSON and Content-Type set automatically. */
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+let _fakeStubs: FakeStub[] | null = null;
+const _recorded: Array<{ method: HttpMethod; url: string; options: RequestInit }> = [];
+
+/** @internal Install fake stubs; while active, no real HTTP requests are made. */
+export function _installFakes(stubs: FakeStub[]): void {
+  _fakeStubs = stubs;
+  _recorded.length = 0;
+}
+
+/** @internal Remove all fakes, restoring real HTTP behaviour. */
+export function _clearFakes(): void {
+  _fakeStubs = null;
+  _recorded.length = 0;
+}
+
+/** @internal Return a copy of every request made while fakes are active. */
+export function _getRecorded(): typeof _recorded {
+  return [..._recorded];
+}
+
+function _matchUrl(pattern: string, url: string): boolean {
+  if (pattern === "*") return true;
+  if (!pattern.includes("*")) return pattern === url;
+  const regex = new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$",
+  );
+  return regex.test(url);
+}
+
+function _buildFakeResponse(stub: FakeStub): Response {
+  const status = stub.status ?? 200;
+  const headers = new Headers(stub.headers ?? {});
+
+  if (stub.body === undefined) {
+    return new Response(null, { status, headers });
+  }
+  if (typeof stub.body === "string") {
+    if (!headers.has("Content-Type")) headers.set("Content-Type", "text/plain");
+    return new Response(stub.body, { status, headers });
+  }
+  if (!headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+  return new Response(JSON.stringify(stub.body), { status, headers });
+}
+
+// ── HttpClientResponse ────────────────────────────────────────────────────────
+
+/** Wraps a fetch Response with convenient accessors. */
+export class HttpClientResponse {
+  constructor(private readonly _res: Response) {}
+
+  get status(): number {
+    return this._res.status;
+  }
+  get ok(): boolean {
+    return this._res.ok;
+  }
+  get headers(): Headers {
+    return this._res.headers;
+  }
+
+  json<T = unknown>(): Promise<T> {
+    return this._res.json() as Promise<T>;
+  }
+  text(): Promise<string> {
+    return this._res.text();
+  }
+  blob(): Promise<Blob> {
+    return this._res.blob();
+  }
+
+  /**
+   * Return this response, or throw when the status is >= 400.
+   * @throws {HttpClientError} when the underlying response is not `ok`.
+   */
+  throw(): this {
+    if (!this._res.ok) {
+      throw new HttpClientError(`HTTP ${this._res.status}`, this._res.status, this);
+    }
+    return this;
+  }
+}
+
+/** Thrown by `HttpClientResponse.throw()` when a response has a 4xx/5xx status. */
+export class HttpClientError extends ZerotalError {
+  constructor(
+    message: string,
+    status: number,
+    readonly response: HttpClientResponse,
+  ) {
+    super(message, "E_HTTP_CLIENT", status);
+  }
+}
+
+// ── PendingRequest ────────────────────────────────────────────────────────────
+
+/**
+ * Fluent HTTP request builder.
+ *
+ * Can be awaited directly (`await Http.get(url)`) or chained for shorthand
+ * (`await Http.post(url, data).json()`).
+ */
+export class PendingRequest implements PromiseLike<HttpClientResponse> {
+  private _headers: Record<string, string> = {};
+  private _timeout: number | undefined = undefined;
+  private _retries: number = 0;
+  private _retryDelay: number = 100;
+  private _body: BodyInit | undefined = undefined;
+  private _bodyType: "json" | "form" | "raw" = "json";
+
+  constructor(
+    private readonly _method: HttpMethod,
+    private readonly _url: string,
+  ) {}
+
+  /**
+   * Merge additional headers into the request.
+   * @category Configuration
+   */
+  withHeaders(headers: Record<string, string>): this {
+    Object.assign(this._headers, headers);
+    return this;
+  }
+
+  /**
+   * Set a Bearer token in the Authorization header.
+   * @category Configuration
+   */
+  withToken(token: string): this {
+    this._headers["Authorization"] = `Bearer ${token}`;
+    return this;
+  }
+
+  /**
+   * Set HTTP Basic Auth credentials.
+   * @category Configuration
+   */
+  withBasicAuth(username: string, password: string): this {
+    const encoded = btoa(`${username}:${password}`);
+    this._headers["Authorization"] = `Basic ${encoded}`;
+    return this;
+  }
+
+  /**
+   * Set an Accept: application/json header.
+   * @category Configuration
+   */
+  acceptJson(): this {
+    this._headers["Accept"] = "application/json";
+    return this;
+  }
+
+  /**
+   * Abort the request after the given number of milliseconds.
+   * @category Retries & resilience
+   */
+  timeout(ms: number): this {
+    this._timeout = ms;
+    return this;
+  }
+
+  /**
+   * Retry failed requests up to `times` times, with optional delay in ms.
+   * @category Retries & resilience
+   */
+  retry(times: number, delay = 100): this {
+    this._retries = times;
+    this._retryDelay = delay;
+    return this;
+  }
+
+  /**
+   * Attach a JSON body. Used internally — prefer passing data to Http.post().
+   * @category Configuration
+   */
+  withJson(data: unknown): this {
+    this._body = JSON.stringify(data);
+    this._bodyType = "json";
+    this._headers["Content-Type"] = "application/json";
+    return this;
+  }
+
+  /**
+   * Attach a FormData body.
+   * @category Configuration
+   */
+  withFormData(data: FormData): this {
+    this._body = data;
+    this._bodyType = "form";
+    return this;
+  }
+
+  /**
+   * Execute the request and return an HttpClientResponse.
+   * @category Responses
+   * @throws the last error encountered after all retry attempts are exhausted
+   * (e.g. a network failure or `AbortSignal.timeout` abort).
+   * @throws {Error} when `Http.fake()` is active but no stub matches the URL.
+   */
+  async send(): Promise<HttpClientResponse> {
+    const options: RequestInit = {
+      method: this._method,
+      headers: this._headers,
+    };
+    if (this._body !== undefined) options.body = this._body;
+
+    if (_fakeStubs !== null) {
+      _recorded.push({ method: this._method, url: this._url, options });
+      const stub = _fakeStubs.find((candidate) => _matchUrl(candidate.url, this._url));
+      if (stub) return new HttpClientResponse(_buildFakeResponse(stub));
+      throw new Error(`[Http.fake] No stub matched: ${this._method} ${this._url}`);
+    }
+
+    const startedAt = performance.now();
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= this._retries; attempt++) {
+      try {
+        const signal = this._timeout ? AbortSignal.timeout(this._timeout) : undefined;
+        const response = await fetch(this._url, signal ? { ...options, signal } : options);
+        this._emitCompleted(response.status, response.ok, performance.now() - startedAt);
+        return new HttpClientResponse(response);
+      } catch (error) {
+        lastError = error;
+        if (attempt < this._retries) {
+          await new Promise((resolve) => setTimeout(resolve, this._retryDelay));
+        }
+      }
+    }
+    this._emitCompleted(0, false, performance.now() - startedAt);
+    throw lastError;
+  }
+
+  /** Announce a finished outgoing request on the framework event bus (best-effort). */
+  private _emitCompleted(status: number, ok: boolean, ms: number): void {
+    let host = this._url;
+    try {
+      host = new URL(this._url).host;
+    } catch {
+      /* non-absolute URL — keep the raw value */
+    }
+    FrameworkEvents.emit(
+      new OutgoingRequestCompleted(host, this._method, this._url, status, Math.round(ms), ok),
+    );
+  }
+
+  /**
+   * Shorthand: send and deserialize JSON response body.
+   * @category Responses
+   */
+  json<T = unknown>(): Promise<T> {
+    return this.send().then((response) => response.json<T>());
+  }
+
+  /**
+   * Shorthand: send and return the text body.
+   * @category Responses
+   */
+  text(): Promise<string> {
+    return this.send().then((response) => response.text());
+  }
+
+  // Allow `await Http.get(url)` without calling .send() explicitly.
+  then<TResult1 = HttpClientResponse, TResult2 = never>(
+    onfulfilled?: ((value: HttpClientResponse) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return this.send().then(onfulfilled, onrejected);
+  }
+}