@crustjs/openapi 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 Call a CLI's HTTP API and browse its OpenAPI spec from an api command
 
-`apiCommand({ spec, baseUrl, auth })` adds `<cli> api`, a `gh api`-style escape hatch: `--list` and `--spec` read the bundled OpenAPI document offline, and `api <path>` sends an authenticated request. It also provides the `apiClient` Context, so your own commands share the same base URL and auth.
+`apiCommand({ spec, baseUrl, auth, paginate })` adds `<cli> api`, a `gh api`-style escape hatch: `--list` and `--spec` read the bundled OpenAPI document offline, and `api <path>` sends an authenticated request and prints the response body, byte for byte to a pipe or file. With the `json()` Extension, `--json` prints each mode's data as JSON on stdout. It also provides the `apiClient` Context, so your own commands share the same base URL and auth.
 
 ## Install
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CommandDefinition, CommandShape, ContextFactory, ContextInstance, ContextSetup, ExtensionFactory } from "@crustjs/core";
+import { JsonValue } from "@crustjs/utils/json";
 interface ApiClientOptions {
   /** URL request paths resolve against, e.g. `https://api.example.com/v1`. */
   readonly baseUrl: string;
@@ -63,7 +64,10 @@ interface ApiCommandOptions extends ApiClientOptions {
    */
   readonly paginate?: (response: Response) => ApiRequest | undefined | Promise<ApiRequest | undefined>;
 }
-/** A non-2xx response to `api <path>`; its body was already printed to stdout. */
+/**
+ * A non-2xx response to `api <path>`; its body was already printed (to stderr under `--json`).
+ * The `json()` Extension prints its `status` as the error's `details`.
+ */
 export declare class ApiResponseError extends Error {
   override name: string;
   /** The HTTP status code. */
@@ -113,14 +117,16 @@ declare const apiFlags: {
   };
 };
 /** The contributed `api` command, spelled out because the exported factory needs a declared type. */
-type ApiCommandDefinition = CommandDefinition<"api", readonly [], CommandShape<readonly [typeof pathArg], typeof apiFlags, {}, void, {}, undefined>, {
+type ApiCommandDefinition = CommandDefinition<"api", readonly [], CommandShape<readonly [typeof pathArg], typeof apiFlags, {}, JsonValue | undefined, {}, readonly JsonValue[] | undefined>, {
   api: ApiClient;
 }>;
 /**
  * Provides the {@link apiClient} Context and contributes `api`: `api --list` and
  * `api --spec <operationId|path>` read the spec (calling its loader, if any); `api <path>` sends
- * a request through the client, prints the response body to stdout, and fails with
- * {@link ApiResponseError} on a non-2xx status.
+ * a request through the client, prints the response body to stdout (its exact bytes to a pipe or
+ * file; as text to a terminal, failing instead for a binary body), and fails with {@link ApiResponseError} on a non-2xx
+ * status. Under the `json()` Extension's `--json`, `api` returns its data as the command result instead: the operations, the
+ * definition, or the parsed response body; `--paginate` yields each page body as an event.
  */
 export declare const apiCommand: ExtensionFactory<[options: ApiCommandOptions], {
   api: ApiClient;

package/dist/index.js

@@ -1,4 +1,5 @@
 import { CrustError, defineCommand, defineContext, defineExtension, defineExtensionId } from "@crustjs/core";
+import { jsonErrorDetails } from "@crustjs/utils/json";
 // src/client.ts
 /** `path` joined below `baseUrl`, keeping the base's own path; absolute URLs pass through. */
 function resolveUrl(baseUrl, path) {
@@ -137,7 +138,10 @@ const apiClient = /* @__PURE__ */ defineContext("api").setup(async (input, optio
 });
 // src/api-command.ts
 const API = /* @__PURE__ */ defineExtensionId("crust:openapi");
-/** A non-2xx response to `api <path>`; its body was already printed to stdout. */
+/**
+* A non-2xx response to `api <path>`; its body was already printed (to stderr under `--json`).
+* The `json()` Extension prints its `status` as the error's `details`.
+*/
 var ApiResponseError = class extends Error {
 	name = "ApiResponseError";
 	/** The HTTP status code. */
@@ -145,6 +149,7 @@ var ApiResponseError = class extends Error {
 	constructor(status, message) {
 		super(message);
 		this.status = status;
+		Object.defineProperty(this, jsonErrorDetails, { value: { status } });
 	}
 };
 const METHODS = [
@@ -201,7 +206,8 @@ function operations(spec) {
 			return typeof operation === "object" && operation !== null ? [{
 				method,
 				path,
-				operation
+				operation,
+				shared: resolved.parameters
 			}] : [];
 		});
 	});
@@ -225,44 +231,116 @@ async function loadSpec(spec, signal) {
 	}
 	return loaded;
 }
-/** One line per operation: `METHOD path operationId summary`, omitting what the spec lacks. */
+/** Each operation's method, path, and the `operationId` and `summary` the spec has. */
 function listOperations(spec) {
 	return operations(spec).map(({ method, path, operation }) => {
 		const { operationId, summary } = operation;
-		return [
-			method.toUpperCase(),
+		return {
+			method: method.toUpperCase(),
 			path,
-			operationId,
-			summary
-		].filter((part) => typeof part === "string" && part !== "").join(" ");
+			...typeof operationId === "string" && operationId !== "" ? { operationId } : {},
+			...typeof summary === "string" && summary !== "" ? { summary } : {}
+		};
 	});
 }
-/** Follows local `$ref`s (`#/...`), keeping sibling keys; a `$ref` back into its own chain stays as is. */
-function resolveRefs(value, spec, chain) {
-	if (Array.isArray(value)) return value.map((item) => resolveRefs(item, spec, chain));
-	if (typeof value !== "object" || value === null) return value;
-	const { $ref, ...siblings } = value;
-	if (typeof $ref === "string" && $ref.startsWith("#") && !chain.includes($ref)) {
-		const target = refTarget(spec, $ref);
-		if (target !== void 0) {
-			const resolved = resolveRefs(target, spec, [...chain, $ref]);
+function isLocalRef(ref) {
+	return typeof ref === "string" && ref.startsWith("#");
+}
+/** `value` with its local `$ref` chain followed, stopping at a cycle or a dangling `$ref`. */
+function deref(spec, value) {
+	const seen = /* @__PURE__ */ new Set();
+	for (;;) {
+		const ref = typeof value === "object" && value !== null ? value.$ref : void 0;
+		if (!isLocalRef(ref) || seen.has(ref)) return value;
+		seen.add(ref);
+		const target = refTarget(spec, ref);
+		if (target === void 0) return value;
+		value = target;
+	}
+}
+/** The path item's `parameters`, minus those the operation redefines (same `name` and `in`), then the operation's. */
+function mergeParameters(spec, shared, own) {
+	const list = (parameters) => Array.isArray(parameters) ? parameters : [];
+	const key = (parameter) => {
+		const { name, in: location } = deref(spec, parameter) ?? {};
+		return typeof name === "string" && typeof location === "string" ? JSON.stringify([location, name]) : void 0;
+	};
+	const redefined = new Set(list(own).map(key));
+	return [...list(shared).filter((parameter) => {
+		const id = key(parameter);
+		return id === void 0 || !redefined.has(id);
+	}), ...list(own)];
+}
+/**
+* `value` with local `$ref`s (`#/...`) followed, each target written once: a target used once is
+* inlined, keeping sibling keys; one used more often, or recursively, keeps its `$ref`s and is
+* written once under `$refs`, keyed by the `$ref` text. Inlining every use instead grows
+* exponentially with shared schemas, as in large public specs.
+*/
+function resolveRefs(value, spec) {
+	const targets = /* @__PURE__ */ new Map();
+	const target = (ref) => {
+		if (!targets.has(ref)) targets.set(ref, refTarget(spec, ref));
+		return targets.get(ref);
+	};
+	const uses = /* @__PURE__ */ new Map();
+	const count = (node) => {
+		if (typeof node !== "object" || node === null) return;
+		for (const item of Object.values(node)) count(item);
+		const { $ref } = node;
+		if (!isLocalRef($ref) || target($ref) === void 0) return;
+		const seen = uses.get($ref) ?? 0;
+		uses.set($ref, seen + 1);
+		if (seen === 0) count(target($ref));
+	};
+	count(value);
+	const refs = {};
+	const write = (node) => {
+		if (Array.isArray(node)) return node.map(write);
+		if (typeof node !== "object" || node === null) return node;
+		const { $ref, ...siblings } = node;
+		const used = isLocalRef($ref) ? uses.get($ref) ?? 0 : 0;
+		if (used === 1) {
+			const resolved = write(target($ref));
 			return typeof resolved === "object" && resolved !== null && !Array.isArray(resolved) ? {
 				...resolved,
-				...resolveRefs(siblings, spec, chain)
+				...write(siblings)
 			} : resolved;
 		}
-	}
-	return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolveRefs(item, spec, chain)]));
+		if (used > 1 && !Object.hasOwn(refs, $ref)) {
+			refs[$ref] = void 0;
+			refs[$ref] = write(target($ref));
+		}
+		return Object.fromEntries(Object.entries(node).map(([key, item]) => [key, key === "$ref" ? item : write(item)]));
+	};
+	const written = write(value);
+	return Object.keys(refs).length > 0 ? {
+		...written,
+		$refs: refs
+	} : written;
 }
 /**
-* The path item for a spec path, or the operation with that `operationId`, with
-* local `$ref`s resolved.
+* The path item for a spec path, or the operation with that `operationId` with its method, path,
+* and the path item's shared `parameters`; local `$ref`s resolved by {@link resolveRefs}.
 */
 function specFor(spec, target) {
 	const paths = spec.paths ?? {};
-	const found = target.startsWith("/") && Object.hasOwn(paths, target) ? paths[target] : operations(spec).find(({ operation }) => operation.operationId === target)?.operation;
-	if (found === void 0) throw new Error(`No operation or path "${target}" in the OpenAPI spec`);
-	return resolveRefs(found, spec, []);
+	if (target.startsWith("/") && Object.hasOwn(paths, target)) return resolveRefs(paths[target], spec);
+	const matches = operations(spec).filter(({ operation }) => operation.operationId === target);
+	const [match] = matches;
+	if (match === void 0) throw new Error(`No operation or path "${target}" in the OpenAPI spec`);
+	if (matches.length > 1) {
+		const candidates = matches.map(({ method, path }) => `${method.toUpperCase()} ${path}`);
+		throw new Error(`The operationId "${target}" is ambiguous in the OpenAPI spec (${candidates.join(", ")}): pass a path instead`);
+	}
+	const { method, path, operation, shared } = match;
+	const parameters = mergeParameters(spec, shared, operation.parameters);
+	return resolveRefs({
+		method: method.toUpperCase(),
+		path,
+		...operation,
+		...parameters.length > 0 ? { parameters } : {}
+	}, spec);
 }
 const JSON_NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
 /** `key=value`; `true`, `false`, `null`, and JSON numbers become JSON values, like `gh api -F`. */
@@ -281,6 +359,22 @@ function parseField(field) {
 	if (!Number.isFinite(number)) throw new CrustError("PARSE", `Invalid -F value for "${field.slice(0, at)}": the number is out of range.`, { flag: "field" });
 	return [field.slice(0, at), number];
 }
+/** RFC 9110 `token`, the grammar of a method. */
+const METHOD_TOKEN = /^[!#$%&'*+.^_`|~\w-]+$/;
+/** The method to send for `-X`, upper-cased, failing before any request for one fetch() would not send. */
+function parseMethod(method) {
+	if (!METHOD_TOKEN.test(method)) throw new CrustError("PARSE", "Invalid -X value: expected an HTTP method such as GET or PATCH, without spaces.", { flag: "method" });
+	const normalized = method.toUpperCase();
+	let sent;
+	try {
+		sent = new Request("http://localhost/", { method: normalized }).method;
+	} catch {}
+	if (sent !== normalized) {
+		const problem = sent === void 0 ? "cannot send it" : `would send it as ${sent}`;
+		throw new CrustError("PARSE", `-X ${normalized}: this runtime's fetch() ${problem}.`, { flag: "method" });
+	}
+	return normalized;
+}
 function parseHeader(header) {
 	const at = header.indexOf(":");
 	if (at <= 0) throw new CrustError("PARSE", "Invalid -H value: expected \"Name: value\".", { flag: "header" });
@@ -349,16 +443,23 @@ const apiFlags = {
 /**
 * Provides the {@link apiClient} Context and contributes `api`: `api --list` and
 * `api --spec <operationId|path>` read the spec (calling its loader, if any); `api <path>` sends
-* a request through the client, prints the response body to stdout, and fails with
-* {@link ApiResponseError} on a non-2xx status.
+* a request through the client, prints the response body to stdout (its exact bytes to a pipe or
+* file; as text to a terminal, failing instead for a binary body), and fails with {@link ApiResponseError} on a non-2xx
+* status. Under the `json()` Extension's `--json`, `api` returns its data as the command result instead: the operations, the
+* definition, or the parsed response body; `--paginate` yields each page body as an event.
 */
-const apiCommand = /* @__PURE__ */ defineExtension(API).factory((extension, { spec, paginate, ...client }) => extension.provide(apiClient(client)).add(defineCommand("api", { description: "Call the HTTP API, or browse its OpenAPI spec" }, (command) => command.use(apiClient).args(pathArg).flags(apiFlags).action(async ({ args, flags, ctx, signal, stdout }) => {
+const apiCommand = /* @__PURE__ */ defineExtension(API).factory((extension, { spec, paginate, ...client }) => extension.provide(apiClient(client)).add(defineCommand("api", { description: "Call the HTTP API, or browse its OpenAPI spec" }, (command) => command.use(apiClient).args(pathArg).flags(apiFlags).action(async ({ args, flags, ctx, signal, stdout, stderr }) => {
+	const json = flags.json === true;
 	if (flags.list) {
-		for (const line of listOperations(await loadSpec(spec, signal))) stdout(line);
+		const listed = listOperations(await loadSpec(spec, signal));
+		if (json) return listed;
+		for (const entry of listed) stdout(Object.values(entry).join(" "));
 		return;
 	}
 	if (flags.spec !== void 0) {
-		stdout(JSON.stringify(specFor(await loadSpec(spec, signal), flags.spec)));
+		const found = specFor(await loadSpec(spec, signal), flags.spec);
+		if (json) return found;
+		stdout(JSON.stringify(found));
 		return;
 	}
 	if (args.path === void 0) throw new CrustError("VALIDATION", "Missing required argument \"<path>\" (or pass --list or --spec)");
@@ -372,7 +473,7 @@ const apiCommand = /* @__PURE__ */ defineExtension(API).factory((extension, { sp
 	}
 	const fields = (flags.field ?? []).map(parseField);
 	const body = flags.body === void 0 ? void 0 : await readBody(flags.body, signal);
-	const method = (flags.method ?? (fields.length > 0 || body !== void 0 ? "POST" : "GET")).toUpperCase();
+	const method = parseMethod(flags.method ?? (fields.length > 0 || body !== void 0 ? "POST" : "GET"));
 	const headers = new Headers((flags.header ?? []).map(parseHeader));
 	let path = args.path;
 	let requestBody = body;
@@ -385,36 +486,96 @@ const apiCommand = /* @__PURE__ */ defineExtension(API).factory((extension, { sp
 	}
 	if (requestBody !== void 0 && !headers.has("content-type")) headers.set("content-type", "application/json");
 	const api = await ctx.api;
-	let request = {
-		path,
-		init: {
-			method,
-			headers,
-			body: requestBody
-		}
-	};
-	let sentMethod = method;
-	let response = await api.fetch(request.path, request.init);
-	for (let pageNumber = 2;; pageNumber++) {
-		const page = flags.paginate ? response.clone() : void 0;
-		const text = await response.text();
-		if (flags.paginate) stdout(compactJson(text));
-		else if (text !== "") stdout(text.replace(/\r?\n$/, ""));
-		if (!response.ok) throw new ApiResponseError(response.status, `${request.init?.method ?? "GET"} ${request.path}: HTTP ${response.status} ${response.statusText}`.trimEnd());
-		const next = page && paginate ? await paginate(page) : void 0;
-		if (next === void 0) return;
-		const nextInit = next.init ?? request.init;
-		const nextUrl = resolveUrl(client.baseUrl, next.path).href;
-		const nextMethod = nextInit?.method ?? "GET";
-		if (nextInit === request.init && nextMethod === sentMethod && nextUrl === resolveUrl(client.baseUrl, request.path).href) throw new Error(`--paginate: page ${pageNumber} repeats the previous request (${nextMethod} ${nextUrl})`);
-		request = {
-			path: next.path,
-			init: nextInit
+	/** The response and body of each page: just one without --paginate. Fails after a non-2xx page. */
+	async function* pages() {
+		let request = {
+			path,
+			init: {
+				method,
+				headers,
+				body: requestBody
+			}
 		};
-		sentMethod = nextMethod;
-		response = await fetchNextPage(api, request.path, request.init);
+		let shown = args.path;
+		let sentMethod = method;
+		let response = await api.fetch(request.path, request.init);
+		for (let pageNumber = 2;; pageNumber++) {
+			const page = flags.paginate ? response.clone() : void 0;
+			yield {
+				response,
+				bytes: new Uint8Array(await response.arrayBuffer())
+			};
+			if (!response.ok) throw new ApiResponseError(response.status, `${sentMethod} ${withoutQuery(shown)}: HTTP ${response.status} ${response.statusText}`.trimEnd());
+			const next = page && paginate ? await paginate(page) : void 0;
+			if (next === void 0) return;
+			const nextInit = next.init ?? request.init;
+			const nextUrl = resolveUrl(client.baseUrl, next.path).href;
+			const nextMethod = nextInit?.method ?? "GET";
+			if (nextInit === request.init && nextMethod === sentMethod && nextUrl === resolveUrl(client.baseUrl, request.path).href) throw new Error(`--paginate: page ${pageNumber} repeats the previous request (${nextMethod} ${withoutQuery(nextUrl)})`);
+			request = {
+				path: next.path,
+				init: nextInit
+			};
+			shown = next.path;
+			sentMethod = nextMethod;
+			response = await fetchNextPage(api, request.path, request.init);
+		}
+	}
+	/** Prints each page's body; under --json, yields a successful page's body as JSON data instead. */
+	async function* bodies() {
+		const { getAmbientTerminalIO, writeProcessOutput } = await import("@crustjs/utils/terminal");
+		let refusal;
+		if (flags.paginate) refusal = "--paginate prints only text and JSON bodies";
+		else if (json) refusal = "--json prints only text and JSON bodies, so run without it to write the bytes to stdout";
+		else if (getAmbientTerminalIO() !== void 0) refusal = "its bytes go only to the process's stdout, not to captured output";
+		else if (process.getBuiltinModule("node:tty").isatty(1)) refusal = "redirect or pipe stdout to save it instead of printing it to the terminal";
+		for await (const { response, bytes } of pages()) {
+			if (refusal === void 0) {
+				writeProcessOutput(1, bytes);
+				continue;
+			}
+			const text = bodyText(bytes);
+			if (text === void 0) {
+				if (response.ok) {
+					const type = response.headers.get("content-type") ?? "no Content-Type";
+					throw new Error(`api: ${flags.paginate ? "a --paginate page" : "the response"} body is binary (${type}); ${refusal}`);
+				}
+				continue;
+			}
+			if (!json) {
+				if (flags.paginate) stdout(compactJson(text));
+				else if (text !== "") stdout(text.replace(/\r?\n$/, ""));
+			} else if (!response.ok) {
+				if (text !== "") stderr(text.replace(/\r?\n$/, ""));
+			} else if (flags.paginate || text !== "") yield bodyValue(text);
+		}
+		return void 0;
 	}
+	if (flags.paginate && json) return bodies();
+	let result;
+	for await (const value of bodies()) result = value;
+	return result;
 }))));
+/** `path` up to its query or fragment, which may hold a credential such as an `-F` field. */
+function withoutQuery(path) {
+	return path.replace(/[?#][\s\S]*$/, "");
+}
+/** The body as text, or `undefined` when it is not valid UTF-8. */
+function bodyText(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+}
+/** A body as JSON data: parsed when it is JSON (numbers as doubles), the text itself otherwise. */
+function bodyValue(text) {
+	try {
+		return JSON.parse(text, (_key, value) => Object.is(value, -0) ? 0 : value);
+	} catch {
+		return text;
+	}
+}
 /** A page body as one NDJSON line: JSON compacted, any other text (even empty) as a JSON string. */
 function compactJson(text) {
 	try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crustjs/openapi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Call a CLI's HTTP API and browse its OpenAPI spec from an api command",
   "type": "module",
   "sideEffects": false,
@@ -36,17 +36,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@crustjs/utils": "^0.3.0"
+    "@crustjs/utils": "^0.3.1"
   },
   "devDependencies": {
     "@crustjs/config": "0.0.0",
-    "@crustjs/core": "0.6.0",
-    "@crustjs/testing": "0.1.7",
+    "@crustjs/core": "0.6.1",
+    "@crustjs/extensions": "0.6.1",
+    "@crustjs/testing": "0.1.8",
     "vite-plus": "1.4.0"
   },
   "peerDependencies": {
-    "@crustjs/core": "^0.6.0",
-    "typescript": "^7.0.0"
+    "@crustjs/core": "^0.6.1",
+    "typescript": ">=5.9.0"
   },
   "peerDependenciesMeta": {
     "typescript": {