@haddowg/json-api-codegen 1.9.0 → 1.10.0

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { r as CodegenConfig } from "./index-k_oATv7Q.mjs";
+import { r as CodegenConfig } from "./index-DqeWPRAD.mjs";
 
 //#region src/cli.d.ts
 declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]";

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as generateFiles, t as check } from "./src-py1RBWZr.mjs";
+import { i as generateFiles, t as check } from "./src-C3noZURK.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-k_oATv7Q.d.mts → index-DqeWPRAD.d.mts}

@@ -56,6 +56,12 @@ interface OperationObject {
   parameters?: readonly ParameterObject[];
   requestBody?: RequestBodyObject;
   responses?: Record<string, ResponseObject>;
+  /** What a custom action declares about its effects (generator contract 15). */
+  'x-safety'?: {
+    readOnly?: unknown;
+    destructive?: unknown;
+    idempotent?: unknown;
+  };
 }
 type HttpMethod = 'get' | 'post' | 'patch' | 'put' | 'delete';
 type PathItemObject = Partial<Record<HttpMethod, OperationObject>>;
@@ -152,9 +158,12 @@ declare class DescriptorBuilder {
    * `{collection}/{id}/-actions/{name}` paths. The action name is the last segment; scope
    * is `resource` when the path carries `/{id}/`, else `collection`. `input` is `document`
    * (a JSON:API requestBody), `none` (no requestBody) or `raw` (a non-JSON:API body);
-   * `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`).
+   * `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`). An action
+   * answering to several methods gives one entry per method (see {@link pickOperations}).
    */
   private actions;
+  /** The descriptor for one operation of a custom action. */
+  private action;
   /**
    * The non-JSON:API media types an action answers with under its 2xx responses, each once, in
    * the document's order, with how the client reads its body.
@@ -295,7 +304,7 @@ declare function buildExamples(doc: OpenApiDocument, descriptor: ApiDescriptor):
 /** Below this the document predates the structures this codegen reads. */
 declare const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-declare const MAXIMUM_CONTRACT = 14;
+declare const MAXIMUM_CONTRACT = 15;
 /**
  * Check the document's `info.x-generator.contract` against the range this codegen reads. A
  * document older than the range throws; a newer one returns a warning, because its new
@@ -683,4 +692,4 @@ declare function generateFiles(config: CodegenConfig): Promise<string[]>;
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
 export { operationExamples as A, PathItemObject as B, VerbCollision as C, MINIMUM_CONTRACT as D, MAXIMUM_CONTRACT as E, InfoObject as F, ResponseObject as H, MediaTypeObject as I, OpenApiDocument as L, buildAtomic as M, buildDescriptor as N, checkContract as O, HttpMethod as P, OperationObject as R, Emitter as S, emit as T, SchemaObject as U, RequestBodyObject as V, SchemaOrBool as W, emitExamples as _, examplesOutputPath as a, emitErrorCodes as b, schemasOutputPath as c, hashJson as d, provenanceLines as f, readSchemas as g, readDocument as h, check as i, DescriptorBuilder as j, buildExamples as k, Provenance as l, SchemaBundle as m, CheckResult as n, generate as o, emitSchemas as p, CodegenConfig as r, generateFiles as s, ArtifactDrift as t, deriveProvenance as u, DocumentedErrorCode as v, detectVerbCollisions as w, readErrorCatalogue as x, ErrorCatalogue as y, ParameterObject as z };
-//# sourceMappingURL=index-k_oATv7Q.d.mts.map
+//# sourceMappingURL=index-DqeWPRAD.d.mts.map

package/dist/index-DqeWPRAD.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DqeWPRAD.d.mts","names":[],"sources":["../src/openapi.ts","../src/build-descriptor.ts","../src/build-examples.ts","../src/contract.ts","../src/emit.ts","../src/error-codes.ts","../src/emit-examples.ts","../src/reader.ts","../src/emit-schemas.ts","../src/provenance.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, H as ResponseObject, I as MediaTypeObject, L as OpenApiDocument, M as buildAtomic, N as buildDescriptor, O as checkContract, P as HttpMethod, R as OperationObject, S as Emitter, T as emit, U as SchemaObject, V as RequestBodyObject, W as SchemaOrBool, _ as emitExamples, a as examplesOutputPath, b as emitErrorCodes, c as schemasOutputPath, d as hashJson, f as provenanceLines, g as readSchemas, h as readDocument, i as check, j as DescriptorBuilder, k as buildExamples, l as Provenance, m as SchemaBundle, n as CheckResult, o as generate, p as emitSchemas, r as CodegenConfig, s as generateFiles, t as ArtifactDrift, u as deriveProvenance, v as DocumentedErrorCode, w as detectVerbCollisions, x as readErrorCatalogue, y as ErrorCatalogue, z as ParameterObject } from "./index-k_oATv7Q.mjs";
+import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, H as ResponseObject, I as MediaTypeObject, L as OpenApiDocument, M as buildAtomic, N as buildDescriptor, O as checkContract, P as HttpMethod, R as OperationObject, S as Emitter, T as emit, U as SchemaObject, V as RequestBodyObject, W as SchemaOrBool, _ as emitExamples, a as examplesOutputPath, b as emitErrorCodes, c as schemasOutputPath, d as hashJson, f as provenanceLines, g as readSchemas, h as readDocument, i as check, j as DescriptorBuilder, k as buildExamples, l as Provenance, m as SchemaBundle, n as CheckResult, o as generate, p as emitSchemas, r as CodegenConfig, s as generateFiles, t as ArtifactDrift, u as deriveProvenance, v as DocumentedErrorCode, w as detectVerbCollisions, x as readErrorCatalogue, y as ErrorCatalogue, z as ParameterObject } from "./index-DqeWPRAD.mjs";
 export { ArtifactDrift, CheckResult, CodegenConfig, DescriptorBuilder, type DocumentedErrorCode, Emitter, type ErrorCatalogue, type HttpMethod, type InfoObject, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, type MediaTypeObject, type OpenApiDocument, type OperationObject, type ParameterObject, type PathItemObject, type Provenance, type RequestBodyObject, type ResponseObject, type SchemaBundle, type SchemaObject, type SchemaOrBool, type VerbCollision, buildAtomic, buildDescriptor, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { C as DescriptorBuilder, S as operationExamples, T as buildDescriptor, _ as readErrorCatalogue, a as schemasOutputPath, b as checkContract, c as emitSchemas, d as detectVerbCollisions, f as emit, g as emitErrorCodes, h as provenanceLines, i as generateFiles, l as emitExamples, m as hashJson, n as examplesOutputPath, o as readDocument, p as deriveProvenance, r as generate, s as readSchemas, t as check, u as Emitter, v as MAXIMUM_CONTRACT, w as buildAtomic, x as buildExamples, y as MINIMUM_CONTRACT } from "./src-py1RBWZr.mjs";
+import { C as DescriptorBuilder, S as operationExamples, T as buildDescriptor, _ as readErrorCatalogue, a as schemasOutputPath, b as checkContract, c as emitSchemas, d as detectVerbCollisions, f as emit, g as emitErrorCodes, h as provenanceLines, i as generateFiles, l as emitExamples, m as hashJson, n as examplesOutputPath, o as readDocument, p as deriveProvenance, r as generate, s as readSchemas, t as check, u as Emitter, v as MAXIMUM_CONTRACT, w as buildAtomic, x as buildExamples, y as MINIMUM_CONTRACT } from "./src-C3noZURK.mjs";
 export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/{src-py1RBWZr.mjs → src-C3noZURK.mjs}

@@ -327,7 +327,8 @@ var DescriptorBuilder = class {
 	* `{collection}/{id}/-actions/{name}` paths. The action name is the last segment; scope
 	* is `resource` when the path carries `/{id}/`, else `collection`. `input` is `document`
 	* (a JSON:API requestBody), `none` (no requestBody) or `raw` (a non-JSON:API body);
-	* `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`).
+	* `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`). An action
+	* answering to several methods gives one entry per method (see {@link pickOperations}).
 	*/
 	actions(collection) {
 		const out = {};
@@ -344,47 +345,66 @@ var DescriptorBuilder = class {
 				name = path.slice(collectionPrefix.length);
 			} else continue;
 			if (name.length === 0 || name.includes("/")) continue;
-			const picked = pickOperation(item);
-			if (picked === void 0) {
+			const picked = pickOperations(item);
+			if (picked.length === 0) {
 				console.warn(`json-api codegen: custom action path "${path}" advertises no usable operation; skipping.`);
 				continue;
 			}
-			const { method, op } = picked;
-			const input = actionInput(op);
-			const output = actionOutput(op);
-			const action = {
-				scope,
-				path,
-				input,
-				output
-			};
-			if (method !== "post") action.method = method.toUpperCase();
-			if (input === "document") {
-				const inputType = this.documentPrimary(actionRequestRef(op))?.type;
-				if (inputType !== void 0) action.inputType = inputType;
-			}
-			if (output === "document") {
-				const primary = this.documentPrimary(this.firstOkJsonApiRef(op));
-				if (primary !== void 0) {
-					action.outputType = primary.type;
-					action.outputCardinality = primary.cardinality;
+			for (const [index, { method, op }] of picked.entries()) {
+				const key = index === 0 ? name : methodActionName(name, method);
+				if (key in out) {
+					console.warn(`json-api codegen: the ${method.toUpperCase()} operation of custom action path "${path}" would be named "${key}", which another action already uses; skipping.`);
+					continue;
 				}
+				out[key] = this.action(scope, path, method, op);
 			}
-			if (input === "raw") {
-				const contentType = rawContentType(op);
-				if (contentType !== void 0) action.contentType = contentType;
-			}
-			const rawOutput = this.rawOutput(op);
-			if (rawOutput.length > 0) action.rawOutput = rawOutput;
-			const requestContent = Object.entries(op.requestBody?.content ?? {});
-			if (requestContent.length > 1) action.inputMedia = requestContent.map(([mediaType, media]) => ({
-				mediaType,
-				kind: this.inputMediaKind(mediaType, media.schema)
-			}));
-			out[name] = action;
 		}
 		return sortRecord(out);
 	}
+	/** The descriptor for one operation of a custom action. */
+	action(scope, path, method, op) {
+		const input = actionInput(op);
+		const output = actionOutput(op);
+		const action = {
+			scope,
+			path,
+			input,
+			output
+		};
+		if (method !== "post") action.method = method.toUpperCase();
+		if (input === "document") {
+			const inputType = this.documentPrimary(actionRequestRef(op))?.type;
+			if (inputType !== void 0) action.inputType = inputType;
+		}
+		if (output === "document") {
+			const primary = this.documentPrimary(this.firstOkJsonApiRef(op));
+			if (primary !== void 0) {
+				action.outputType = primary.type;
+				action.outputCardinality = primary.cardinality;
+			}
+		}
+		if (input === "raw") {
+			const contentType = rawContentType(op);
+			if (contentType !== void 0) action.contentType = contentType;
+		}
+		const rawOutput = this.rawOutput(op);
+		if (rawOutput.length > 0) action.rawOutput = rawOutput;
+		const requestContent = Object.entries(op.requestBody?.content ?? {});
+		if (requestContent.length > 1) action.inputMedia = requestContent.map(([mediaType, media]) => ({
+			mediaType,
+			kind: this.inputMediaKind(mediaType, media.schema)
+		}));
+		const safety = op["x-safety"];
+		for (const flag of [
+			"readOnly",
+			"destructive",
+			"idempotent"
+		]) {
+			const value = safety?.[flag];
+			if (typeof value === "boolean") action[flag] = value;
+		}
+		return action;
+	}
 	/**
 	* The non-JSON:API media types an action answers with under its 2xx responses, each once, in
 	* the document's order, with how the client reads its body.
@@ -837,18 +857,39 @@ const ACTION_METHODS = [
 	"delete"
 ];
 /**
-* The single operation an action is invoked over: POST when advertised (the common default), else
-* the first advertised method. `undefined` when the path item carries no operation at all.
+* The operations an action is invoked over, the preferred one first: POST when advertised (the
+* common default), else the first advertised method. The other methods follow only when their
+* `operationId` differs from the preferred one's, as contract 15 makes it for an action answering
+* to several methods. An older document gave every method one id, and its client exposed only the
+* preferred one. Empty when the path item carries no operation at all.
 */
-function pickOperation(item) {
+function pickOperations(item) {
 	const available = ACTION_METHODS.filter((method) => item[method] !== void 0);
-	const method = available.includes("post") ? "post" : available[0];
-	if (method === void 0) return;
-	const op = item[method];
-	return op === void 0 ? void 0 : {
-		method,
-		op
-	};
+	const preferred = available.includes("post") ? "post" : available[0];
+	if (preferred === void 0) return [];
+	const first = item[preferred];
+	const out = [{
+		method: preferred,
+		op: first
+	}];
+	for (const method of available) {
+		const op = item[method];
+		if (method !== preferred && op.operationId !== first.operationId) out.push({
+			method,
+			op
+		});
+	}
+	return out;
+}
+/**
+* The name a multi-method action's other methods go under: the action's name and the method,
+* joined the way the name joins its words. So `export` gives `exportGet` and `bulk-import` gives
+* `bulk-import-get`. Core refuses action ids that differ only in case or punctuation, so the
+* name can't clash with another action's.
+*/
+function methodActionName(name, method) {
+	const separator = /[-_.]/.exec(name)?.[0];
+	return separator === void 0 ? `${name}${method[0].toUpperCase()}${method.slice(1)}` : `${name}${separator}${method}`;
 }
 /** The body shape a custom action accepts: a JSON:API document, none, or a raw payload. */
 function actionInput(op) {
@@ -1044,7 +1085,7 @@ function buildExamples(doc, descriptor) {
 /** Below this the document predates the structures this codegen reads. */
 const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-const MAXIMUM_CONTRACT = 14;
+const MAXIMUM_CONTRACT = 15;
 /**
 * Check the document's `info.x-generator.contract` against the range this codegen reads. A
 * document older than the range throws; a newer one returns a warning, because its new
@@ -1054,8 +1095,8 @@ const MAXIMUM_CONTRACT = 14;
 function checkContract(doc) {
 	const contract = doc.info?.["x-generator"]?.contract;
 	if (typeof contract !== "number") return;
-	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 14). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 14) return `the document declares contract ${contract} and this codegen reads up to 14. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 15). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 15) return `the document declares contract ${contract} and this codegen reads up to 15. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/declared-links.ts
@@ -1521,6 +1562,19 @@ function actionDoc(name, op) {
 	if (description && !generated.test(description)) parts.push(description);
 	return parts.length === 0 ? void 0 : parts.join("\n\n");
 }
+/**
+* What an action declares about its effects (generator contract 15), as one sentence, or
+* `undefined` when it declares nothing.
+*/
+function safetyDoc(action) {
+	const words = [
+		[action.readOnly, "read-only"],
+		[action.destructive, "destructive"],
+		[action.idempotent, "idempotent"]
+	].filter(([value]) => value !== void 0).map(([value, word]) => value === true ? word : `not ${word}`);
+	if (words.length === 0) return;
+	return `The server declares this action ${words.length === 1 ? words[0] : `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`}.`;
+}
 /** Whether a media type carries JSON: JSON:API, `application/json` or a `+json` suffix. */
 function isJsonMedia(mediaType) {
 	const essence = mediaType.split(";")[0].trim().toLowerCase();
@@ -1630,7 +1684,11 @@ var Emitter = class {
 				const single = action.contentType;
 				if (single !== void 0 && (single.startsWith("multipart/") || single === "application/x-www-form-urlencoded")) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(single)}Input`);
 				const op = actionOperation(this.doc, action);
-				const parts = [actionDoc(name, op), exampleDoc(op)].filter((part) => part !== void 0);
+				const parts = [
+					actionDoc(action.path.slice(action.path.lastIndexOf("/") + 1), op),
+					safetyDoc(action),
+					exampleDoc(op)
+				].filter((part) => part !== void 0);
 				const doc = parts.length === 0 ? void 0 : parts.join("\n\n");
 				if (doc !== void 0) this.literalDocs.set(`${type}/actions/${name}`, doc);
 			}
@@ -2460,4 +2518,4 @@ async function check(config) {
 //#endregion
 export { DescriptorBuilder as C, operationExamples as S, buildDescriptor as T, readErrorCatalogue as _, schemasOutputPath as a, checkContract as b, emitSchemas as c, detectVerbCollisions as d, emit as f, emitErrorCodes as g, provenanceLines as h, generateFiles as i, emitExamples as l, hashJson as m, examplesOutputPath as n, readDocument as o, deriveProvenance as p, generate as r, readSchemas as s, check as t, Emitter as u, MAXIMUM_CONTRACT as v, buildAtomic as w, buildExamples as x, MINIMUM_CONTRACT as y };
 
-//# sourceMappingURL=src-py1RBWZr.mjs.map
+//# sourceMappingURL=src-C3noZURK.mjs.map