@devbie/apits 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @devbie/apits
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Based on the OpenAPI specification, generate request and response type declarations and request method bodies for APIs
+
+## Installation
+
+`npm install @devbie/apits`
+
+## Quick start (no config file needed)
+
+Pass an OpenAPI document URL or a local JSON / YAML file:
+
+```bash
+apits gen http://localhost:3041/api-json
+apits gen ./openapi.yaml -o src/api
+```
+
+The `gen` word is optional:
+
+```bash
+apits ./openapi.json
+```
+
+Each run generates two files in the output directory:
+
+- `<name>.ts` — type declarations and request functions for every API
+- `request.ts` — the default axios client (skipped with `--no-client`)
+
+The file name is derived from the input when `-n/--name` is omitted:
+`http://localhost:3041/api-json` → `localhost.ts`, `./user.openapi.yaml` →
+`userOpenapi.ts`.
+
+### CLI options
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `input` (positional) | OpenAPI document URL or local `.json` / `.json5` / `.yaml` / `.yml` file | — |
+| `-o, --output <path>` | Output directory | `src/api` |
+| `-n, --name <name>` | Base name of the generated `<name>.ts`; when using a config file, filters sources by name | derived from the input host / file name |
+| `--base-url <url>` | Runtime `baseURL` (supports the `[code]:` prefix) | — |
+| `--no-client` | Do not scaffold the default `request.ts` axios client | client is generated |
+| `-w, --watch` | Watch a local document and regenerate on change | off |
+
+## Optional configuration file
+
+Create a config only when you need multiple sources, JSON/JSON5 config, or
+function-based customization:
+
+```bash
+apits init
+```
+
+`apits init ./openapi.json` prefills the document address.
+
+The config file is auto-discovered from any of:
+`apits.config.local.ts`, `apits.config.ts`, `apits.config.local.json`,
+`apits.config.json`, or the `apits` field in `package.json`.
+
+```ts
+// apits.config.ts
+import { defineConfig } from '@devbie/apits'
+
+export default defineConfig([
+  {
+    input: 'http://localhost:3041/api-json',
+    output: 'src/api/user',
+    name: 'user', // optional, derived from `input` when omitted
+    baseURL: '[code]:process.env.BASE_API_URL',
+    clientImportTemplate: () => "import request from './request'",
+    client: true
+  }
+])
+```
+
+CLI flags take precedence over config-file values. With a config file,
+`-n/--name` selects which source(s) to run.
+
+## Generate from a config file
+
+Once a config file exists, generate all sources with:
+
+```bash
+apits gen
+```
+
+Or generate a single source by name:
+
+```bash
+apits gen -n user
+```

package/bin/apits

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const CLI = require("../dist/cjs/core/cli").default;
+new CLI().run(process.argv.slice(2));

package/dist/cjs/core/cli.d.ts

@@ -0,0 +1,29 @@
+import yargs from "yargs";
+/** Flags accepted by the `gen` command. */
+interface GenFlags {
+    /** OpenAPI document URL or local file path. */
+    input?: string;
+    /** Output directory. */
+    output?: string;
+    /** File base name (CLI mode) or name filter (config-file mode). */
+    name?: string;
+    /** Runtime baseURL (string; `[code]:` prefix supported). */
+    baseUrl?: string;
+    /** Whether to scaffold the default request.ts client. */
+    client?: boolean;
+    /** Watch local input files and regenerate on change. */
+    watch?: boolean;
+}
+/** Scaffold an optional apits.config.ts template. */
+export declare function genConfig(prefill?: {
+    input?: string;
+}): Promise<void>;
+export declare function start(flags?: GenFlags): Promise<void>;
+export default class CLI {
+    run(args: string[]): {
+        [x: string]: any;
+    };
+    private genBuilder;
+    init(): yargs.Argv<any>;
+}
+export {};

package/dist/cjs/core/cli.js

@@ -0,0 +1,396 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  default: () => CLI,
+  genConfig: () => genConfig,
+  start: () => start
+});
+module.exports = __toCommonJS(cli_exports);
+var import_api = require("tsx/cjs/api");
+var import_fs_extra = __toESM(require("fs-extra"));
+var import_path = __toESM(require("path"));
+var import_prompts = __toESM(require("prompts"));
+var import_yargs = __toESM(require("yargs"));
+var import_vtilsLite = require("../utils/vtilsLite.js");
+var import_generator = require("./generator.js");
+var import_chalk = __toESM(require("chalk"));
+var conso = __toESM(require("../utils/console.js"));
+var import_utils = require("../utils/utils.js");
+var import_spinner = require("../utils/spinner.js");
+var import_helpers = require("../utils/helpers.js");
+(0, import_api.register)();
+var CONFIG_FILE_CANDIDATES = [
+  "apits.config.local.ts",
+  "apits.config.ts",
+  "apits.config.local.json",
+  "apits.config.json"
+];
+var NoInputError = class extends Error {
+};
+function isHttpInput(input) {
+  return /^https?:\/\//i.test(input);
+}
+function normalizeConfig(raw) {
+  return (0, import_helpers.defineConfig)(Array.isArray(raw) ? raw : [raw]);
+}
+async function discoverConfigFile(cwd = process.cwd()) {
+  for (const fileName of CONFIG_FILE_CANDIDATES) {
+    const filePath = import_path.default.join(cwd, fileName);
+    if (await import_fs_extra.default.pathExists(filePath)) {
+      return { filePath, kind: fileName.endsWith(".json") ? "json" : "ts" };
+    }
+  }
+  const packageJsonPath = import_path.default.join(cwd, "package.json");
+  if (await import_fs_extra.default.pathExists(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(await import_fs_extra.default.readFile(packageJsonPath, "utf-8"));
+      if (pkg.apits) {
+        return { filePath: packageJsonPath, kind: "package" };
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+function loadConfigFile(discovered) {
+  const { filePath, kind } = discovered;
+  if (kind === "ts") {
+    const mod = require(filePath);
+    return normalizeConfig(mod.default ?? mod);
+  }
+  if (kind === "json") {
+    return normalizeConfig(JSON.parse(import_fs_extra.default.readFileSync(filePath, "utf-8")));
+  }
+  const pkg = JSON.parse(import_fs_extra.default.readFileSync(filePath, "utf-8"));
+  return normalizeConfig(pkg.apits);
+}
+function buildCliConfig(flags) {
+  const config = {
+    input: flags.input,
+    output: flags.output || "src/api"
+  };
+  if (flags.name) {
+    config.name = flags.name;
+  }
+  if (flags.baseUrl !== void 0) {
+    config.baseURL = flags.baseUrl;
+  }
+  config.client = flags.client ?? true;
+  return (0, import_helpers.defineConfig)(config)[0];
+}
+function assignUniqueNames(configs) {
+  const counts = /* @__PURE__ */ new Map();
+  configs.forEach((item) => {
+    const base = item.name || import_generator.Generator.deriveName(item.input);
+    const seen = counts.get(base) ?? 0;
+    counts.set(base, seen + 1);
+    if (!item.name) {
+      item.name = seen === 0 ? base : `${base}_${seen + 1}`;
+    }
+  });
+}
+async function resolveConfigs(flags) {
+  if (flags.input) {
+    const configs = [buildCliConfig(flags)];
+    assignUniqueNames(configs);
+    return { configs, source: "cli" };
+  }
+  const discovered = await discoverConfigFile();
+  if (discovered) {
+    let configs = loadConfigFile(discovered);
+    if (flags.name) {
+      configs = configs.filter((item) => item.name === flags.name);
+      if (configs.length === 0) {
+        throw new Error(`No config found with name: ${flags.name}`);
+      }
+    }
+    configs = configs.map((item) => ({
+      ...item,
+      ...flags.output ? { output: flags.output } : {},
+      ...flags.baseUrl !== void 0 ? { baseURL: flags.baseUrl } : {},
+      ...flags.client !== void 0 ? { client: flags.client } : {}
+    }));
+    assignUniqueNames(configs);
+    return { configs, source: "file", configFile: discovered.filePath };
+  }
+  throw new NoInputError();
+}
+function printNoInputHint() {
+  conso.error(
+    [
+      "No OpenAPI input found. Use one of:",
+      "",
+      "  1. Pass document URL or path directly (no config file needed):",
+      "     apits gen http://localhost:3041/api-json -o src/api",
+      "     apits gen ./openapi.yaml",
+      "",
+      "  2. Generate a config file (multi-source / function-based customization):",
+      "     apits init"
+    ].join("\n")
+  );
+}
+async function genConfig(prefill) {
+  const cwd = process.cwd();
+  const configTSFile = import_path.default.join(cwd, "apits.config.ts");
+  if (await import_fs_extra.default.pathExists(configTSFile)) {
+    conso.tips(`Config file already exists: ${configTSFile}`);
+    const answers = await (0, import_prompts.default)({
+      message: "Overwrite existing config file?",
+      name: "override",
+      type: "confirm"
+    });
+    if (!answers.override)
+      return;
+  }
+  const configAnswers = await (0, import_prompts.default)([
+    {
+      message: "API document URL or local JSON/YAML file path",
+      name: "input",
+      type: "text",
+      initial: (prefill == null ? void 0 : prefill.input) || ""
+    },
+    {
+      message: "Generated file name (optional, derived from input if blank)",
+      name: "name",
+      type: "text",
+      initial: ""
+    }
+  ]);
+  if (!configAnswers || !configAnswers.input) {
+    return conso.tips("Cancelled, config file not written");
+  }
+  const nameLine = (configAnswers == null ? void 0 : configAnswers.name) ? `  name: '${configAnswers.name}',
+` : "";
+  await import_fs_extra.default.outputFile(
+    configTSFile,
+    await (0, import_utils.formatContent)(import_vtilsLite.dedent`
+      import { defineConfig } from '@devbie/apits'
+
+      export default defineConfig([{
+        input: '${(configAnswers == null ? void 0 : configAnswers.input) || ""}',
+        output: 'src/api',
+      ${nameLine}  baseURL: '[code]:process.env.BASE_API_URL',
+        clientImportTemplate: () => "${`import request from './request'`}",
+        // Keep the scaffolded request.ts because the import above points at it.
+        client: true,
+      }])
+    `)
+  );
+  conso.success("Config file written");
+}
+async function startGenerate(config, index = 0) {
+  const { output: outputDir } = config;
+  const label = import_chalk.default.green(`${config.input} elapsed`);
+  console.time(label);
+  import_spinner.spinnerInstance.start();
+  const generator = new import_generator.Generator(config);
+  const output = await generator.generate();
+  await generator.write(output);
+  import_spinner.spinnerInstance.clear();
+  conso.log(import_chalk.default.yellowBright(`
+${index + 1}.-------------------------`));
+  conso.success(`Code generated, output: ${outputDir}`);
+  console.timeEnd(label);
+  conso.log(import_chalk.default.yellowBright("---------------------------\n"));
+  return true;
+}
+async function runAll(configs) {
+  await (0, import_helpers.asyncFnArrayOrderRun)(
+    configs.map((configItem, index) => {
+      return async () => {
+        await startGenerate(configItem, index);
+      };
+    })
+  );
+}
+function watchConfigs(configs) {
+  const localConfigs = configs.filter((item) => !isHttpInput(item.input));
+  if (localConfigs.length === 0) {
+    conso.tips("--watch only supports local files; remote URLs are ignored");
+    return;
+  }
+  const timers = /* @__PURE__ */ new Map();
+  localConfigs.forEach((configItem) => {
+    const filePath = import_path.default.resolve(configItem.input);
+    import_fs_extra.default.watch(filePath, async (eventType) => {
+      if (eventType === "rename") {
+        try {
+          import_fs_extra.default.watch(filePath, async (ev) => {
+            scheduleRebuild(filePath, ev);
+          });
+        } catch {
+        }
+      }
+      scheduleRebuild(filePath, eventType);
+    });
+  });
+  function scheduleRebuild(filePath, eventType) {
+    if (eventType !== "change" && eventType !== "rename")
+      return;
+    const oldTimer = timers.get(filePath);
+    if (oldTimer)
+      clearTimeout(oldTimer);
+    timers.set(
+      filePath,
+      setTimeout(async () => {
+        const configItem = localConfigs.find((c) => import_path.default.resolve(c.input) === filePath);
+        if (!configItem)
+          return;
+        const idx = localConfigs.indexOf(configItem);
+        conso.tips(`Detected change, regenerating: ${filePath}`);
+        try {
+          await startGenerate(configItem, idx);
+        } catch (err) {
+          conso.error(`Regeneration failed: ${err.message || err}`);
+        }
+      }, 200)
+    );
+  }
+  conso.tips(`Watching ${localConfigs.length} local document(s), Ctrl+C to exit`);
+}
+async function start(flags = {}) {
+  const timeLabel = import_chalk.default.green("Total elapsed");
+  console.time(timeLabel);
+  let resolved;
+  try {
+    resolved = await resolveConfigs(flags);
+  } catch (err) {
+    if (err instanceof NoInputError) {
+      printNoInputHint();
+      return;
+    }
+    import_spinner.spinnerInstance.stop();
+    conso.error(`Config resolution failed: ${err.message || err}`);
+    return;
+  }
+  conso.tips(
+    resolved.source === "cli" ? `Using CLI input: ${flags.input}` : `Found config file: ${resolved.configFile}`
+  );
+  try {
+    import_spinner.spinnerInstance.start("Generating code...\n");
+    await runAll(resolved.configs);
+    import_spinner.spinnerInstance.stop();
+  } catch (err) {
+    import_spinner.spinnerInstance.stop();
+    conso.error("Execution failed:");
+    conso.error(`Error: ${err.message || err}`);
+    if (err.stack) {
+      conso.error(`Stack: ${err.stack}`);
+    }
+    if (err.cause) {
+      conso.error(`Cause: ${err.cause}`);
+    }
+    return conso.error("Code generation failed, see error details above");
+  }
+  console.timeEnd(timeLabel);
+  if (flags.watch) {
+    watchConfigs(resolved.configs);
+  }
+  return null;
+}
+function toFlags(argv) {
+  return {
+    input: typeof argv.input === "string" && argv.input ? argv.input : void 0,
+    output: typeof argv.output === "string" ? argv.output : void 0,
+    name: typeof argv.name === "string" ? argv.name : void 0,
+    baseUrl: typeof argv.baseUrl === "string" ? argv.baseUrl : void 0,
+    client: typeof argv.client === "boolean" ? argv.client : void 0,
+    watch: Boolean(argv.watch)
+  };
+}
+var CLI = class {
+  run(args) {
+    const cli = this.init();
+    if (args.length === 0) {
+      cli.showHelp();
+    }
+    return cli.parse(args);
+  }
+  genBuilder(y) {
+    return y.positional("input", {
+      type: "string",
+      describe: "OpenAPI document URL or local JSON/YAML file path"
+    }).option("output", {
+      alias: "o",
+      type: "string",
+      describe: "Output directory (default: src/api)"
+    }).option("name", {
+      alias: "n",
+      type: "string",
+      describe: "Generated file name; filters by name in config-file mode"
+    }).option("base-url", {
+      type: "string",
+      describe: "Runtime baseURL (supports [code]: prefix for code emission)"
+    }).option("client", {
+      type: "boolean",
+      describe: "Generate default request.ts (use --no-client to disable, --client to force-enable)"
+    }).option("watch", {
+      alias: "w",
+      type: "boolean",
+      default: false,
+      describe: "Watch local document for changes and auto-regenerate"
+    });
+  }
+  init() {
+    return import_yargs.default.scriptName("apits").usage("Usage: $0 [gen] [input] [options]").command(
+      "init [input]",
+      "Scaffold an optional apits.config.ts file",
+      (y) => {
+        y.positional("input", {
+          type: "string",
+          describe: "Prefilled document URL or local file path"
+        });
+      },
+      async (argv) => {
+        await genConfig({ input: typeof argv.input === "string" ? argv.input : void 0 });
+      }
+    ).command(
+      "gen [input]",
+      "Generate TypeScript types and request functions from an OpenAPI document",
+      (y) => this.genBuilder(y),
+      (argv) => {
+        start(toFlags(argv));
+      }
+    ).command(
+      "$0 [input]",
+      false,
+      (y) => this.genBuilder(y),
+      (argv) => {
+        start(toFlags(argv));
+      }
+    ).help();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  genConfig,
+  start
+});