lacspace-http 0.1.0

package/dist/lib.d.cts

@@ -0,0 +1,290 @@
+/**
+ * A tiny, hand-written JSON-path evaluator used for response capture and
+ * assertions. It understands a deliberately small, predictable dialect — no
+ * `eval`, no regex-of-doom, no wildcards:
+ *
+ *   $                    the root value
+ *   $.data.items         object keys via dots
+ *   data.items           a leading `$` is optional
+ *   $.items[0].id        array indices via brackets
+ *   $.items[-1]          negative indices count from the end
+ *   $['odd key'].x       bracketed / quoted keys (dots, spaces, etc.)
+ *
+ * Missing paths resolve to `undefined` rather than throwing, so an assertion
+ * like `body.$.error exists` can be tested cleanly.
+ */
+/** One resolved step of a JSON path. */
+type JsonPathSegment = {
+    type: "key";
+    key: string;
+} | {
+    type: "index";
+    index: number;
+};
+/** Parse a path string into an ordered list of segments. Throws on syntax errors. */
+declare function parseJsonPath(path: string): JsonPathSegment[];
+/**
+ * Resolve `path` against `root`. Returns the value at the path, or `undefined`
+ * if any step does not exist. `$` alone returns `root` itself.
+ */
+declare function evalPath(root: unknown, path: string): unknown;
+
+/** A flat name→value map used to resolve `{{var}}` references. */
+type VarScope = Map<string, string>;
+/** Build a scope from any number of plain objects (later objects win). */
+declare function makeScope(...sources: Array<Record<string, string> | undefined>): VarScope;
+/** Result of {@link resolveVars}: the substituted text plus any unresolved names. */
+interface ResolveResult {
+    text: string;
+    missing: string[];
+}
+/**
+ * Replace every `{{name}}` in `text` with its value from `scope` (or a built-in
+ * system variable). Unknown references are left verbatim and reported in
+ * `missing`, so callers can decide whether that's fatal.
+ */
+declare function resolveVars(text: string, scope: VarScope): ResolveResult;
+/**
+ * Parse a REST-client `http-client.env.json` document and return the merged
+ * variables for `envName`. A top-level `$shared` block (if present) is merged
+ * first, then the named environment overrides it.
+ */
+declare function parseEnvJson(json: string, envName: string): Record<string, string>;
+/** Parse a `.env`-style document (KEY=VALUE lines, `#` comments, optional quotes). */
+declare function parseDotenv(text: string): Record<string, string>;
+/** Parse `k=v` CLI pairs (repeatable `--var`) into a plain object. */
+declare function parseKvPairs(pairs: string[]): Record<string, string>;
+
+/**
+ * A hand-written parser for the well-known `.http` / `.rest` file format (the
+ * one VS Code's REST Client and JetBrains HTTP Client use). Requests are
+ * separated by `###`, may carry a `# @name` tag, and can declare `# @capture`
+ * and `# @assert` directives that turn a file into a runnable API test suite.
+ *
+ * The parser is intentionally forgiving and does no network work — it only
+ * turns text into structured {@link HttpFileRequest} objects.
+ */
+/** A `# @capture <name> = <source>` directive. `source` is an assertion LHS. */
+interface CaptureDirective {
+    name: string;
+    source: string;
+}
+/** A `# @assert <expr>` directive. `expr` is parsed later by the assert engine. */
+interface AssertDirective {
+    expr: string;
+}
+/** One request block parsed out of a `.http` file. */
+interface HttpFileRequest {
+    /** `# @name <id>` if present. */
+    name?: string;
+    method: string;
+    url: string;
+    /** Header pairs in source order (values may still contain `{{vars}}`). */
+    headers: Array<[string, string]>;
+    /** Raw request body (may contain `{{vars}}`), or undefined if none. */
+    body?: string;
+    captures: CaptureDirective[];
+    assertions: AssertDirective[];
+    /** 1-based line number of the request line, for diagnostics. */
+    line: number;
+}
+/**
+ * Parse a whole `.http` document into an ordered list of requests. Directive
+ * comments (`# @name`, `# @capture`, `# @assert`) are extracted; plain comments
+ * are ignored.
+ */
+declare function parseHttpFile(source: string): HttpFileRequest[];
+
+/**
+ * The request engine: assemble a {@link RequestSpec} from friendly options,
+ * send it with the global `fetch` (with manual redirect handling, a timeout, a
+ * response-size cap and precise timing), and render the equivalent `curl`
+ * command. The `fetch` implementation is injectable so tests never touch the
+ * network.
+ */
+/** A concrete, ready-to-send HTTP request. */
+interface RequestSpec {
+    method: string;
+    url: string;
+    /** Header pairs in order. */
+    headers: Array<[string, string]>;
+    body?: string;
+}
+/** Friendly inputs used to build a {@link RequestSpec}. */
+interface AssembleOptions {
+    method?: string;
+    /** Raw `"Key: Value"` header strings (repeatable `-H`). */
+    headers?: string[];
+    /** `"k=v"` query params (repeatable `-q`). */
+    query?: string[];
+    /** Raw request body (`-d`). */
+    data?: string;
+    /** A raw JSON object/array string (`--json '{...}'`). */
+    json?: string;
+    /** `"k=v"` (string) or `"k:=v"` (raw JSON) JSON-body shorthands (`-j`). */
+    jsonKv?: string[];
+    /** `"k=v"` urlencoded form fields (`--form`). */
+    form?: string[];
+    /** Bearer token → `Authorization: Bearer <token>` (`-b`). */
+    bearer?: string;
+    /** `"user:pass"` → HTTP Basic `Authorization` header (`-u`). */
+    user?: string;
+}
+/** Assemble a concrete request from friendly options. Pure — no I/O. */
+declare function assembleRequest(url: string, o?: AssembleOptions): RequestSpec;
+/** Options controlling how a request is sent. */
+interface SendOptions {
+    /** Abort after this many ms (default 30000). */
+    timeoutMs?: number;
+    /** Cap the response body read at this many bytes (default 10MB). */
+    maxSize?: number;
+    /** Follow up to this many redirects (default 5). */
+    maxRedirects?: number;
+    /** Whether to follow redirects at all (default true). */
+    followRedirects?: boolean;
+    /** Inject a `fetch` implementation (defaults to the global). */
+    fetchImpl?: typeof fetch;
+}
+/** A structured, serialisable record of an HTTP response. */
+interface ResponseRecord {
+    status: number;
+    statusText: string;
+    /** Lower-cased header name → value. */
+    headers: Record<string, string>;
+    /** Total wall-clock time for the request (ms), including redirects. */
+    timeMs: number;
+    /** Bytes of body actually read (after any cap). */
+    size: number;
+    /** Response body as text (possibly truncated to `maxSize`). */
+    body: string;
+    /** Parsed JSON body, if the response looked like JSON. */
+    json?: unknown;
+    /** Final URL after any redirects. */
+    url: string;
+    /** Whether any redirect was followed. */
+    redirected: boolean;
+    /** The chain of URLs visited before the final one. */
+    redirectChain: string[];
+    ok: boolean;
+    /** True if the body was cut off at `maxSize`. */
+    truncated: boolean;
+    /** True if a followed redirect crossed to a different host. */
+    crossHostRedirect: boolean;
+}
+/**
+ * Send a {@link RequestSpec}. Redirects are followed manually so the hop count
+ * is enforced (`maxRedirects`) and cross-host hops are recorded rather than
+ * followed silently. Times out after `timeoutMs`; the body is read up to
+ * `maxSize` bytes.
+ */
+declare function sendRequest(spec: RequestSpec, opts?: SendOptions): Promise<ResponseRecord>;
+/** Options for {@link toCurl}. */
+interface CurlOptions {
+    /** Show real credential values instead of masking them (default false). */
+    showSecrets?: boolean;
+    maxRedirects?: number;
+    followRedirects?: boolean;
+}
+/**
+ * Render the equivalent `curl` command for a request. Credentials in an
+ * `Authorization` header are masked (`Bearer ***` / `Basic ***`) unless
+ * `showSecrets` is set.
+ */
+declare function toCurl(spec: RequestSpec, opts?: CurlOptions): string;
+
+/** The comparison operators an assertion may use. */
+type AssertOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "contains" | "matches" | "exists" | "empty";
+/** A parsed assertion: an LHS, an operator, and (for binary ops) an RHS. */
+interface Assertion {
+    lhs: string;
+    op: AssertOp;
+    rhs?: string;
+    raw: string;
+}
+/** Parse an assertion expression like `body.$.ok == true`. Throws on malformed input. */
+declare function parseAssertion(expr: string): Assertion;
+/** Resolve an LHS expression to a concrete value from the response. */
+declare function resolveLhs(lhs: string, rec: ResponseRecord): unknown;
+/** The outcome of evaluating one assertion. */
+interface AssertResult {
+    ok: boolean;
+    assertion: Assertion;
+    actual: unknown;
+    expected?: unknown;
+    message: string;
+}
+/** Evaluate a parsed assertion against a response. */
+declare function evalAssertion(assertion: Assertion, rec: ResponseRecord): AssertResult;
+/** Parse + evaluate in one step. */
+declare function runAssertion(expr: string, rec: ResponseRecord): AssertResult;
+/** Resolve a capture source (same grammar as an LHS) to a string value. */
+declare function captureValue(source: string, rec: ResponseRecord): string | undefined;
+
+/** Options for {@link runHttpFile}. */
+interface RunOptions extends SendOptions {
+    /** Variables from an env block (`http-client.env.json` / `.env`). */
+    env?: Record<string, string>;
+    /** CLI `--var k=v` overrides (highest precedence at start). */
+    vars?: Record<string, string>;
+    /** Run only the request whose `# @name` matches this. */
+    name?: string;
+    /** Called after each request completes (for streaming CLI output). */
+    onResult?: (result: RequestRunResult) => void;
+}
+/** The result of running one request from the file. */
+interface RequestRunResult {
+    name?: string;
+    method: string;
+    url: string;
+    line: number;
+    /** Unresolved `{{vars}}` encountered while building the request. */
+    missingVars: string[];
+    /** Set when the request could not be sent at all. */
+    error?: string;
+    response?: ResponseRecord;
+    assertions: AssertResult[];
+    /** Values captured from this response (name → value). */
+    captured: Record<string, string>;
+    /** True if it was sent, all assertions passed and no error occurred. */
+    ok: boolean;
+}
+/** The overall result of a run. */
+interface RunResult {
+    results: RequestRunResult[];
+    passed: number;
+    failed: number;
+    ok: boolean;
+}
+/** Parse and run a `.http` document. */
+declare function runHttpFile(source: string, opts?: RunOptions): Promise<RunResult>;
+
+/**
+ * Presentation helpers: a byte-size formatter, a status-code colour picker, and
+ * a JSON pretty-printer with optional ANSI syntax highlighting. With `color`
+ * off, {@link prettyJson} is byte-for-byte `JSON.stringify(value, null, 2)`, so
+ * it stays trivially testable and pipe-safe.
+ */
+declare const ANSI: {
+    reset: string;
+    dim: string;
+    green: string;
+    red: string;
+    yellow: string;
+    cyan: string;
+    magenta: string;
+    blue: string;
+};
+/** Human-readable byte size: `950 B`, `1.2 KB`, `3.4 MB`. */
+declare function humanSize(bytes: number): string;
+/** The ANSI colour name appropriate for a status code (green/cyan/yellow/red). */
+declare function statusColor(status: number): keyof typeof ANSI;
+/**
+ * Pretty-print a JSON value. When `color` is false the output equals
+ * `JSON.stringify(value, null, 2)`; when true, keys/strings/numbers/booleans are
+ * syntax-highlighted with ANSI colours.
+ */
+declare function prettyJson(value: unknown, color?: boolean): string;
+/** True if the given content-type looks like JSON. */
+declare function isJsonContentType(ct: string | undefined): boolean;
+
+export { type AssembleOptions, type AssertDirective, type AssertOp, type AssertResult, type Assertion, type CaptureDirective, type CurlOptions, type HttpFileRequest, type JsonPathSegment, type RequestRunResult, type RequestSpec, type ResolveResult, type ResponseRecord, type RunOptions, type RunResult, type SendOptions, type VarScope, assembleRequest, captureValue, evalAssertion, evalPath, humanSize, isJsonContentType, makeScope, parseAssertion, parseDotenv, parseEnvJson, parseHttpFile, parseJsonPath, parseKvPairs, prettyJson, resolveLhs, resolveVars, runAssertion, runHttpFile, sendRequest, statusColor, toCurl };

package/dist/lib.d.ts

@@ -0,0 +1,290 @@
+/**
+ * A tiny, hand-written JSON-path evaluator used for response capture and
+ * assertions. It understands a deliberately small, predictable dialect — no
+ * `eval`, no regex-of-doom, no wildcards:
+ *
+ *   $                    the root value
+ *   $.data.items         object keys via dots
+ *   data.items           a leading `$` is optional
+ *   $.items[0].id        array indices via brackets
+ *   $.items[-1]          negative indices count from the end
+ *   $['odd key'].x       bracketed / quoted keys (dots, spaces, etc.)
+ *
+ * Missing paths resolve to `undefined` rather than throwing, so an assertion
+ * like `body.$.error exists` can be tested cleanly.
+ */
+/** One resolved step of a JSON path. */
+type JsonPathSegment = {
+    type: "key";
+    key: string;
+} | {
+    type: "index";
+    index: number;
+};
+/** Parse a path string into an ordered list of segments. Throws on syntax errors. */
+declare function parseJsonPath(path: string): JsonPathSegment[];
+/**
+ * Resolve `path` against `root`. Returns the value at the path, or `undefined`
+ * if any step does not exist. `$` alone returns `root` itself.
+ */
+declare function evalPath(root: unknown, path: string): unknown;
+
+/** A flat name→value map used to resolve `{{var}}` references. */
+type VarScope = Map<string, string>;
+/** Build a scope from any number of plain objects (later objects win). */
+declare function makeScope(...sources: Array<Record<string, string> | undefined>): VarScope;
+/** Result of {@link resolveVars}: the substituted text plus any unresolved names. */
+interface ResolveResult {
+    text: string;
+    missing: string[];
+}
+/**
+ * Replace every `{{name}}` in `text` with its value from `scope` (or a built-in
+ * system variable). Unknown references are left verbatim and reported in
+ * `missing`, so callers can decide whether that's fatal.
+ */
+declare function resolveVars(text: string, scope: VarScope): ResolveResult;
+/**
+ * Parse a REST-client `http-client.env.json` document and return the merged
+ * variables for `envName`. A top-level `$shared` block (if present) is merged
+ * first, then the named environment overrides it.
+ */
+declare function parseEnvJson(json: string, envName: string): Record<string, string>;
+/** Parse a `.env`-style document (KEY=VALUE lines, `#` comments, optional quotes). */
+declare function parseDotenv(text: string): Record<string, string>;
+/** Parse `k=v` CLI pairs (repeatable `--var`) into a plain object. */
+declare function parseKvPairs(pairs: string[]): Record<string, string>;
+
+/**
+ * A hand-written parser for the well-known `.http` / `.rest` file format (the
+ * one VS Code's REST Client and JetBrains HTTP Client use). Requests are
+ * separated by `###`, may carry a `# @name` tag, and can declare `# @capture`
+ * and `# @assert` directives that turn a file into a runnable API test suite.
+ *
+ * The parser is intentionally forgiving and does no network work — it only
+ * turns text into structured {@link HttpFileRequest} objects.
+ */
+/** A `# @capture <name> = <source>` directive. `source` is an assertion LHS. */
+interface CaptureDirective {
+    name: string;
+    source: string;
+}
+/** A `# @assert <expr>` directive. `expr` is parsed later by the assert engine. */
+interface AssertDirective {
+    expr: string;
+}
+/** One request block parsed out of a `.http` file. */
+interface HttpFileRequest {
+    /** `# @name <id>` if present. */
+    name?: string;
+    method: string;
+    url: string;
+    /** Header pairs in source order (values may still contain `{{vars}}`). */
+    headers: Array<[string, string]>;
+    /** Raw request body (may contain `{{vars}}`), or undefined if none. */
+    body?: string;
+    captures: CaptureDirective[];
+    assertions: AssertDirective[];
+    /** 1-based line number of the request line, for diagnostics. */
+    line: number;
+}
+/**
+ * Parse a whole `.http` document into an ordered list of requests. Directive
+ * comments (`# @name`, `# @capture`, `# @assert`) are extracted; plain comments
+ * are ignored.
+ */
+declare function parseHttpFile(source: string): HttpFileRequest[];
+
+/**
+ * The request engine: assemble a {@link RequestSpec} from friendly options,
+ * send it with the global `fetch` (with manual redirect handling, a timeout, a
+ * response-size cap and precise timing), and render the equivalent `curl`
+ * command. The `fetch` implementation is injectable so tests never touch the
+ * network.
+ */
+/** A concrete, ready-to-send HTTP request. */
+interface RequestSpec {
+    method: string;
+    url: string;
+    /** Header pairs in order. */
+    headers: Array<[string, string]>;
+    body?: string;
+}
+/** Friendly inputs used to build a {@link RequestSpec}. */
+interface AssembleOptions {
+    method?: string;
+    /** Raw `"Key: Value"` header strings (repeatable `-H`). */
+    headers?: string[];
+    /** `"k=v"` query params (repeatable `-q`). */
+    query?: string[];
+    /** Raw request body (`-d`). */
+    data?: string;
+    /** A raw JSON object/array string (`--json '{...}'`). */
+    json?: string;
+    /** `"k=v"` (string) or `"k:=v"` (raw JSON) JSON-body shorthands (`-j`). */
+    jsonKv?: string[];
+    /** `"k=v"` urlencoded form fields (`--form`). */
+    form?: string[];
+    /** Bearer token → `Authorization: Bearer <token>` (`-b`). */
+    bearer?: string;
+    /** `"user:pass"` → HTTP Basic `Authorization` header (`-u`). */
+    user?: string;
+}
+/** Assemble a concrete request from friendly options. Pure — no I/O. */
+declare function assembleRequest(url: string, o?: AssembleOptions): RequestSpec;
+/** Options controlling how a request is sent. */
+interface SendOptions {
+    /** Abort after this many ms (default 30000). */
+    timeoutMs?: number;
+    /** Cap the response body read at this many bytes (default 10MB). */
+    maxSize?: number;
+    /** Follow up to this many redirects (default 5). */
+    maxRedirects?: number;
+    /** Whether to follow redirects at all (default true). */
+    followRedirects?: boolean;
+    /** Inject a `fetch` implementation (defaults to the global). */
+    fetchImpl?: typeof fetch;
+}
+/** A structured, serialisable record of an HTTP response. */
+interface ResponseRecord {
+    status: number;
+    statusText: string;
+    /** Lower-cased header name → value. */
+    headers: Record<string, string>;
+    /** Total wall-clock time for the request (ms), including redirects. */
+    timeMs: number;
+    /** Bytes of body actually read (after any cap). */
+    size: number;
+    /** Response body as text (possibly truncated to `maxSize`). */
+    body: string;
+    /** Parsed JSON body, if the response looked like JSON. */
+    json?: unknown;
+    /** Final URL after any redirects. */
+    url: string;
+    /** Whether any redirect was followed. */
+    redirected: boolean;
+    /** The chain of URLs visited before the final one. */
+    redirectChain: string[];
+    ok: boolean;
+    /** True if the body was cut off at `maxSize`. */
+    truncated: boolean;
+    /** True if a followed redirect crossed to a different host. */
+    crossHostRedirect: boolean;
+}
+/**
+ * Send a {@link RequestSpec}. Redirects are followed manually so the hop count
+ * is enforced (`maxRedirects`) and cross-host hops are recorded rather than
+ * followed silently. Times out after `timeoutMs`; the body is read up to
+ * `maxSize` bytes.
+ */
+declare function sendRequest(spec: RequestSpec, opts?: SendOptions): Promise<ResponseRecord>;
+/** Options for {@link toCurl}. */
+interface CurlOptions {
+    /** Show real credential values instead of masking them (default false). */
+    showSecrets?: boolean;
+    maxRedirects?: number;
+    followRedirects?: boolean;
+}
+/**
+ * Render the equivalent `curl` command for a request. Credentials in an
+ * `Authorization` header are masked (`Bearer ***` / `Basic ***`) unless
+ * `showSecrets` is set.
+ */
+declare function toCurl(spec: RequestSpec, opts?: CurlOptions): string;
+
+/** The comparison operators an assertion may use. */
+type AssertOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "contains" | "matches" | "exists" | "empty";
+/** A parsed assertion: an LHS, an operator, and (for binary ops) an RHS. */
+interface Assertion {
+    lhs: string;
+    op: AssertOp;
+    rhs?: string;
+    raw: string;
+}
+/** Parse an assertion expression like `body.$.ok == true`. Throws on malformed input. */
+declare function parseAssertion(expr: string): Assertion;
+/** Resolve an LHS expression to a concrete value from the response. */
+declare function resolveLhs(lhs: string, rec: ResponseRecord): unknown;
+/** The outcome of evaluating one assertion. */
+interface AssertResult {
+    ok: boolean;
+    assertion: Assertion;
+    actual: unknown;
+    expected?: unknown;
+    message: string;
+}
+/** Evaluate a parsed assertion against a response. */
+declare function evalAssertion(assertion: Assertion, rec: ResponseRecord): AssertResult;
+/** Parse + evaluate in one step. */
+declare function runAssertion(expr: string, rec: ResponseRecord): AssertResult;
+/** Resolve a capture source (same grammar as an LHS) to a string value. */
+declare function captureValue(source: string, rec: ResponseRecord): string | undefined;
+
+/** Options for {@link runHttpFile}. */
+interface RunOptions extends SendOptions {
+    /** Variables from an env block (`http-client.env.json` / `.env`). */
+    env?: Record<string, string>;
+    /** CLI `--var k=v` overrides (highest precedence at start). */
+    vars?: Record<string, string>;
+    /** Run only the request whose `# @name` matches this. */
+    name?: string;
+    /** Called after each request completes (for streaming CLI output). */
+    onResult?: (result: RequestRunResult) => void;
+}
+/** The result of running one request from the file. */
+interface RequestRunResult {
+    name?: string;
+    method: string;
+    url: string;
+    line: number;
+    /** Unresolved `{{vars}}` encountered while building the request. */
+    missingVars: string[];
+    /** Set when the request could not be sent at all. */
+    error?: string;
+    response?: ResponseRecord;
+    assertions: AssertResult[];
+    /** Values captured from this response (name → value). */
+    captured: Record<string, string>;
+    /** True if it was sent, all assertions passed and no error occurred. */
+    ok: boolean;
+}
+/** The overall result of a run. */
+interface RunResult {
+    results: RequestRunResult[];
+    passed: number;
+    failed: number;
+    ok: boolean;
+}
+/** Parse and run a `.http` document. */
+declare function runHttpFile(source: string, opts?: RunOptions): Promise<RunResult>;
+
+/**
+ * Presentation helpers: a byte-size formatter, a status-code colour picker, and
+ * a JSON pretty-printer with optional ANSI syntax highlighting. With `color`
+ * off, {@link prettyJson} is byte-for-byte `JSON.stringify(value, null, 2)`, so
+ * it stays trivially testable and pipe-safe.
+ */
+declare const ANSI: {
+    reset: string;
+    dim: string;
+    green: string;
+    red: string;
+    yellow: string;
+    cyan: string;
+    magenta: string;
+    blue: string;
+};
+/** Human-readable byte size: `950 B`, `1.2 KB`, `3.4 MB`. */
+declare function humanSize(bytes: number): string;
+/** The ANSI colour name appropriate for a status code (green/cyan/yellow/red). */
+declare function statusColor(status: number): keyof typeof ANSI;
+/**
+ * Pretty-print a JSON value. When `color` is false the output equals
+ * `JSON.stringify(value, null, 2)`; when true, keys/strings/numbers/booleans are
+ * syntax-highlighted with ANSI colours.
+ */
+declare function prettyJson(value: unknown, color?: boolean): string;
+/** True if the given content-type looks like JSON. */
+declare function isJsonContentType(ct: string | undefined): boolean;
+
+export { type AssembleOptions, type AssertDirective, type AssertOp, type AssertResult, type Assertion, type CaptureDirective, type CurlOptions, type HttpFileRequest, type JsonPathSegment, type RequestRunResult, type RequestSpec, type ResolveResult, type ResponseRecord, type RunOptions, type RunResult, type SendOptions, type VarScope, assembleRequest, captureValue, evalAssertion, evalPath, humanSize, isJsonContentType, makeScope, parseAssertion, parseDotenv, parseEnvJson, parseHttpFile, parseJsonPath, parseKvPairs, prettyJson, resolveLhs, resolveVars, runAssertion, runHttpFile, sendRequest, statusColor, toCurl };