api-farmer 0.1.3 → 0.1.5

package/README.md

@@ -83,6 +83,7 @@ export default defineConfig({
     verb() {},
     url() {},
     entity() {},
+    name() {},
     fn() {},
     comment() {},
     type() {},
@@ -97,6 +98,25 @@ export default defineConfig({
 })
 ```
 
+#### `name` Transformer
+
+The `name` transformer is a convenience option that derives both `fn` and `type` from a single function. When set, `fn` is the return value, and `type` is automatically capitalized from `fn`. This avoids writing duplicate logic for `fn` and `type`.
+
+```ts
+export default defineConfig({
+  transformer: {
+    name({ verb, entity }) {
+      return `api${verb}${entity}`
+      // fn   -> apiGetUsers
+      // type -> ApiGetUsers
+    },
+  },
+})
+```
+
+> [!NOTE]
+> If `name` is set, `fn` and `type` transformers will be ignored.
+
 ### Configuration Options
 
 ```ts
@@ -155,7 +175,7 @@ export interface Config {
   uncountableNouns?: string[]
   /**
    * Whether to clean the output directory before generating.
-   * @default false
+   * @default true
    */
   clean?: boolean
   /**
@@ -163,6 +183,11 @@ export interface Config {
    *  @see https://openapi-ts.dev/node
    */
   openapiTsOptions?: OpenAPITSOptions
+  /**
+   * Whether to exclude deprecated API endpoints.
+   * @default false
+   */
+  excludeDeprecated?: boolean
 }
 ```
 

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { r as getCliVersion } from "./utils-DachPo4u.mjs";
+import { Command } from "commander";
+//#region src/cli.ts
+const program = new Command();
+program.version(getCliVersion());
+program.action(async () => {
+	const { generate } = await import("./generate-SAL57AwU.mjs").then((n) => n.i);
+	return generate();
+});
+program.parse();
+//#endregion
+export {};

package/dist/generate-SAL57AwU.mjs

@@ -0,0 +1,336 @@
+import { a as getResponseMetadataItems, c as isRequiredRequestBody, d as readTemplateFile, f as CWD, i as getRequestBodyContentType, l as readSchema, p as SUPPORTED_HTTP_METHODS } from "./utils-DachPo4u.mjs";
+import pluralize from "pluralize";
+import { camelize, groupBy, isArray, merge, pascalCase, upperFirst } from "rattail";
+import { resolve } from "path";
+import ejs from "ejs";
+import fse from "fs-extra";
+import openapiTS, { astToString } from "openapi-typescript";
+import prettier from "prettier";
+import { logger } from "rslog";
+import ts from "typescript";
+import { loadConfig } from "unconfig";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/transformer.ts
+function transformModuleName({ name }) {
+	return camelize(name);
+}
+function transformUrl({ path }) {
+	return path.replace(/{/g, ":").replace(/}/g, "");
+}
+function transformComment({ summary, description, path, method }) {
+	return `
+  /**${summary ? `\n* ${summary}` : ""}${description && summary !== description ? `\n* @description ${description}\n*` : ""}
+   * @url ${path}
+   * @method ${method.toLocaleUpperCase()}
+   */
+  `.trim();
+}
+function transformVerb({ method }) {
+	switch (method) {
+		case "post": return "Create";
+		case "put": return "Update";
+		default: return pascalCase(method);
+	}
+}
+function transformEntity({ path, method, uncountableNouns }) {
+	const words = path.split("/").filter(Boolean);
+	return words.reduce((entity, word, index) => {
+		if (word.includes("{")) return entity;
+		word = word.replace(/\.([a-z])/g, (_, p) => p.toUpperCase());
+		const isUncountableNoun = uncountableNouns.includes(word);
+		word = pascalCase(word);
+		word = isUncountableNoun ? word : pluralize.singular(word);
+		if (method === "get" && index === words.length - 1) word = isUncountableNoun ? `${word}List` : pluralize.plural(word);
+		return `${entity}${word}`;
+	}, "");
+}
+function transformFn({ verb, entity }) {
+	return `api${verb}${entity}`;
+}
+function transformType({ verb, entity }) {
+	return `Api${verb}${entity}`;
+}
+function transformTypeValue({ fullPath, method }) {
+	return `paths['${fullPath}']['${method}']`;
+}
+function transformTypeQuery({ type }) {
+	return `${type}Query`;
+}
+function transformTypeQueryValue({ type }) {
+	return `${type}['parameters']['query']`;
+}
+function transformTypeRequestBody({ type }) {
+	return `${type}RequestBody`;
+}
+function transformTypeRequestBodyValue({ type, required, requestContentType }) {
+	return required ? `${type}['requestBody']['content']['${requestContentType}']` : `NonNullable<${type}['requestBody']>['content']['${requestContentType}'] | undefined`;
+}
+function transformTypeResponseBody({ type }) {
+	return `${type}ResponseBody`;
+}
+function transformTypeResponseBodyValue({ type, responseMetadataItems }) {
+	return responseMetadataItems.map(({ status, responseContentType }) => `${type}['responses']['${status}']['content']['${responseContentType}']`).join(" | ");
+}
+function createTransformer() {
+	return {
+		moduleName: transformModuleName,
+		verb: transformVerb,
+		url: transformUrl,
+		comment: transformComment,
+		entity: transformEntity,
+		fn: transformFn,
+		type: transformType,
+		typeValue: transformTypeValue,
+		typeQuery: transformTypeQuery,
+		typeQueryValue: transformTypeQueryValue,
+		typeRequestBody: transformTypeRequestBody,
+		typeRequestBodyValue: transformTypeRequestBodyValue,
+		typeResponseBody: transformTypeResponseBody,
+		typeResponseBodyValue: transformTypeResponseBodyValue
+	};
+}
+//#endregion
+//#region src/config.ts
+function defineConfig(config) {
+	return config;
+}
+async function getConfig() {
+	const { config } = await loadConfig({ sources: [{ files: "api-farmer.config" }] });
+	return config ?? {};
+}
+//#endregion
+//#region src/generate.ts
+var generate_exports = /* @__PURE__ */ __exportAll({
+	detectCollisions: () => detectCollisions,
+	generate: () => generate,
+	generateTypes: () => generateTypes,
+	partitionApiModules: () => partitionApiModules,
+	renderApiModules: () => renderApiModules,
+	transformPayloads: () => transformPayloads
+});
+function transformPayloads(pathItems, options) {
+	const { transformer, path, fullPath, base, uncountableNouns, validateStatus, excludeDeprecated } = options;
+	return Object.entries(pathItems).filter(([key]) => SUPPORTED_HTTP_METHODS.includes(key)).filter(([, operation]) => !(excludeDeprecated && operation.deprecated)).reduce((payloads, [method, operation]) => {
+		const url = transformer.url({
+			path,
+			base,
+			fullPath
+		});
+		const args = {
+			path,
+			base,
+			fullPath,
+			url,
+			method,
+			uncountableNouns,
+			operation
+		};
+		const entity = transformer.entity(args);
+		const verb = transformer.verb(args);
+		const comment = transformer.comment({
+			...args,
+			...operation
+		});
+		const requestContentType = operation.requestBody ? getRequestBodyContentType(operation.requestBody) : void 0;
+		const responseMetadataItems = getResponseMetadataItems(operation, validateStatus);
+		const nameArgs = {
+			...args,
+			verb,
+			entity
+		};
+		const fn = transformer.name ? transformer.name(nameArgs) : transformer.fn(nameArgs);
+		const type = transformer.name ? upperFirst(fn) : transformer.type(nameArgs);
+		const typeValue = transformer.typeValue({
+			...args,
+			verb,
+			entity
+		});
+		const typeQuery = transformer.typeQuery({
+			...args,
+			type,
+			verb,
+			entity
+		});
+		const typeQueryValue = transformer.typeQueryValue({
+			...args,
+			type,
+			verb,
+			entity
+		});
+		const typeRequestBody = transformer.typeRequestBody({
+			...args,
+			type,
+			verb,
+			entity
+		});
+		const typeRequestBodyValue = operation.requestBody && requestContentType ? transformer.typeRequestBodyValue({
+			...args,
+			type,
+			verb,
+			entity,
+			required: isRequiredRequestBody(operation.requestBody),
+			requestContentType
+		}) : "undefined";
+		const typeResponseBody = transformer.typeResponseBody({
+			...args,
+			type,
+			verb,
+			entity
+		});
+		const typeResponseBodyValue = responseMetadataItems.length > 0 ? transformer.typeResponseBodyValue({
+			...args,
+			type,
+			verb,
+			entity,
+			responseMetadataItems
+		}) : "undefined";
+		payloads.push({
+			comment,
+			fn,
+			url,
+			method,
+			verb,
+			entity,
+			requestContentType,
+			type,
+			typeValue,
+			typeQuery,
+			typeQueryValue,
+			typeRequestBody,
+			typeRequestBodyValue,
+			typeResponseBody,
+			typeResponseBodyValue
+		});
+		return payloads;
+	}, []);
+}
+function partitionApiModules(schema, options) {
+	const { base, transformer, uncountableNouns, validateStatus, excludeDeprecated } = options;
+	const schemaPaths = schema.paths ?? {};
+	const keyToPaths = groupBy(base ? Object.keys(schemaPaths).map((key) => key.replace(base, "")) : Object.keys(schemaPaths), (key) => key.split("/")[1]);
+	return Object.entries(keyToPaths).reduce((apiModules, [name, paths]) => {
+		const payloads = paths.reduce((payloads, path) => {
+			const fullPath = base ? base + path : path;
+			const pathItems = schemaPaths[fullPath];
+			payloads.push(...transformPayloads(pathItems, {
+				...options,
+				path,
+				fullPath,
+				transformer,
+				uncountableNouns,
+				validateStatus,
+				excludeDeprecated
+			}));
+			return payloads;
+		}, []);
+		apiModules.push({
+			name: transformer.moduleName({ name }),
+			payloads
+		});
+		return apiModules;
+	}, []);
+}
+function renderApiModules(apiModules, options) {
+	const { output, ts, typesOnly, overrides, preset } = options;
+	const templateFile = readTemplateFile(preset);
+	const typesFilename = options.typesFilename.replace(".ts", "");
+	return Promise.all(apiModules.map((apiModule) => new Promise((promiseResolve) => {
+		const data = {
+			apiModule,
+			typesFilename,
+			ts,
+			typesOnly
+		};
+		prettier.format(ejs.render(templateFile, data), {
+			parser: "typescript",
+			semi: false,
+			singleQuote: true,
+			printWidth: 120
+		}).then((content) => {
+			const path = resolve(output, `${apiModule.name}.${ts ? "ts" : "js"}`);
+			if ((!overrides || isArray(overrides) && !overrides.includes(apiModule.name)) && fse.existsSync(path)) {
+				logger.warn(`File already exists, skip: ${path}`);
+				promiseResolve(content);
+				return;
+			}
+			fse.outputFileSync(path, content);
+			logger.success(`Generated ${path}`);
+			promiseResolve(content);
+		});
+	})));
+}
+async function generateTypes(schema, output, typesFilename, openapiTsOptions) {
+	const BLOB = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("Blob"));
+	const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull());
+	const contents = astToString(await openapiTS(schema, {
+		defaultNonNullable: false,
+		transform(schemaObject) {
+			if (schemaObject.format === "binary") return schemaObject.nullable ? ts.factory.createUnionTypeNode([BLOB, NULL]) : BLOB;
+		},
+		...openapiTsOptions
+	}));
+	const typesFilepath = resolve(CWD, output, typesFilename);
+	fse.outputFileSync(typesFilepath, contents);
+	logger.success(`Generated ${typesFilepath}`);
+}
+function detectCollisions(apiModules) {
+	const fnMap = /* @__PURE__ */ new Map();
+	for (const apiModule of apiModules) for (const payload of apiModule.payloads) {
+		const entries = fnMap.get(payload.fn) ?? [];
+		entries.push({
+			module: apiModule.name,
+			url: payload.url,
+			method: payload.method
+		});
+		fnMap.set(payload.fn, entries);
+	}
+	for (const [fn, entries] of fnMap) if (entries.length > 1) {
+		const endpoints = entries.map((e) => `[${e.method.toUpperCase()}] ${e.url}`).join(", ");
+		logger.warn(`API name collision: "${fn}" is generated by multiple endpoints: ${endpoints}. Consider using the "transformer" option to customize API naming.`);
+	}
+}
+async function generate(userOptions = {}) {
+	const { base, ts = true, typesOnly = false, overrides = true, preset = "axle", input = "./schema.json", output = "./src/apis/generated", typesFilename = "_types.ts", clean = true, validateStatus = (status) => status >= 200 && status < 300, transformer = {}, uncountableNouns = [], openapiTsOptions = {}, excludeDeprecated = false } = merge(await getConfig(), userOptions);
+	const mergedTransformer = {
+		...createTransformer(),
+		...transformer
+	};
+	const schema = await readSchema(input);
+	if (clean) {
+		fse.removeSync(resolve(CWD, output));
+		logger.info(`Cleaned output directory: ${resolve(CWD, output)}`);
+	}
+	logger.info("Generating API modules...");
+	if (openapiTsOptions.excludeDeprecated === void 0) openapiTsOptions.excludeDeprecated = excludeDeprecated;
+	if (ts) await generateTypes(schema, output, typesFilename, openapiTsOptions);
+	const apiModules = partitionApiModules(schema, {
+		base,
+		uncountableNouns,
+		transformer: mergedTransformer,
+		validateStatus,
+		excludeDeprecated
+	});
+	detectCollisions(apiModules);
+	await renderApiModules(apiModules, {
+		output,
+		typesFilename,
+		ts,
+		typesOnly,
+		overrides,
+		preset
+	});
+	logger.success("Done");
+}
+//#endregion
+export { transformUrl as C, transformTypeValue as S, transformTypeQueryValue as _, partitionApiModules as a, transformTypeResponseBody as b, defineConfig as c, transformComment as d, transformEntity as f, transformTypeQuery as g, transformType as h, generate_exports as i, getConfig as l, transformModuleName as m, generate as n, renderApiModules as o, transformFn as p, generateTypes as r, transformPayloads as s, detectCollisions as t, createTransformer as u, transformTypeRequestBody as v, transformVerb as w, transformTypeResponseBodyValue as x, transformTypeRequestBodyValue as y };