feat: allow non-cli execution

bin/cli.mjs

@@ -1,20 +1,12 @@
 #!/usr/bin/env node
 
-import { resolve } from 'node:path';
 import { argv } from 'node:process';
-
 import { Command, Option } from 'commander';
-
-import { coerce } from 'semver';
 import { DOC_NODE_CHANGELOG_URL, DOC_NODE_VERSION } from '../src/constants.mjs';
-import createGenerator from '../src/generators.mjs';
-import generators from '../src/generators/index.mjs';
-import createLoader from '../src/loader.mjs';
-import createParser from '../src/parser.mjs';
-import createNodeReleases from '../src/releases.mjs';
+import { generateApiDocs } from '../src/index.mjs';
+import generators from './generators/index.mjs';
 
 const availableGenerators = Object.keys(generators);
-
 const program = new Command();
 
 program
@@ -52,41 +44,4 @@ program
   )
   .parse(argv);
 
-/**
- * @typedef {keyof generators} Target A list of the available generator names.
- *
- * @typedef {Object} Options
- * @property {Array<string>|string} input Specifies the glob/path for input files.
- * @property {string} output Specifies the directory where output files will be saved.
- * @property {Target[]} target Specifies the generator target mode.
- * @property {string} version Specifies the target Node.js version.
- * @property {string} changelog Specifies the path to the Node.js CHANGELOG.md file
- *
- * @name ProgramOptions
- * @type {Options}
- * @description The return type for values sent to the program from the CLI.
- */
-const { input, output, target = [], version, changelog } = program.opts();
-
-const { loadFiles } = createLoader();
-const { parseApiDocs } = createParser();
-
-const apiDocFiles = loadFiles(input);
-
-const parsedApiDocs = await parseApiDocs(apiDocFiles);
-
-const { runGenerators } = createGenerator(parsedApiDocs);
-
-// Retrieves Node.js release metadata from a given Node.js version and CHANGELOG.md file
-const { getAllMajors } = createNodeReleases(changelog);
-
-await runGenerators({
-  // A list of target modes for the API docs parser
-  generators: target,
-  // Resolved `output` path to be used
-  output: resolve(output),
-  // Resolved SemVer of current Node.js version
-  version: coerce(version),
-  // A list of all Node.js major versions with LTS status
-  releases: await getAllMajors(),
-});
+generateApiDocs(program.opts());

package.json

@@ -12,6 +12,8 @@
     "run": "node bin/cli.mjs",
     "watch": "node --watch bin/cli.mjs"
   },
+  "main": "./src/index.mjs",
+  "type": "module",
   "bin": {
     "api-docs-tooling": "./bin/cli.mjs"
   },

src/generators/json-simple/index.mjs

@@ -56,6 +56,12 @@ export default {
 
     // Writes all the API docs stringified content into one file
     // Note: The full JSON generator in the future will create one JSON file per top-level API doc file
-    await writeFile(join(options.output, 'api-docs.json'), stringifiedContent);
+    if (options.output) {
+      await writeFile(
+        join(options.output, 'api-docs.json'),
+        stringifiedContent
+      );
+    }
+    return stringifiedContent;
   },
 };

src/generators/legacy-html-all/index.mjs

@@ -96,6 +96,10 @@ export default {
       minifyJS: true,
     });
 
-    await writeFile(join(output, 'all.html'), minified);
+    if (output) {
+      await writeFile(join(output, 'all.html'), minified);
+    }
+
+    return minified;
   },
 };

src/generators/man-page/index.mjs

@@ -72,7 +72,11 @@ export default {
       .replace('__OPTIONS__', output.options)
       .replace('__ENVIRONMENT__', output.env);
 
-    await writeFile(options.output, filledTemplate);
+    if (options.output) {
+      await writeFile(options.output, filledTemplate);
+    }
+
+    return filledTemplate;
   },
 };
 

src/index.mjs

@@ -0,0 +1,57 @@
+import { resolve } from 'node:path';
+import { coerce } from 'semver';
+import { DOC_NODE_CHANGELOG_URL, DOC_NODE_VERSION } from './constants.mjs';
+import createGenerator from './generators.mjs';
+import generators from './generators/index.mjs';
+import createLoader from './loader.mjs';
+import createParser from './parser.mjs';
+import createNodeReleases from './releases.mjs';
+
+const availableGenerators = Object.keys(generators);
+const { loadFiles } = createLoader();
+const { parseApiDocs } = createParser();
+
+/**
+ * Function to generate API documentation programmatically.
+ *
+ * @param {Object} options - The options for generating API documentation.
+ * @param {Array<string>|string} options.input - Input file patterns using glob syntax.
+ * @param {string} options.output - The relative or absolute output directory.
+ * @param {string} [options.version=DOC_NODE_VERSION] - The target version of Node.js, semver compliant.
+ * @param {string} [options.changelog=DOC_NODE_CHANGELOG_URL] - Path to the CHANGELOG.md file.
+ * @param {Array<string>|string} [options.target=[]] - Processing target modes.
+ */
+export async function generateApiDocs({
+  input,
+  output,
+  version = DOC_NODE_VERSION,
+  changelog = DOC_NODE_CHANGELOG_URL,
+  target = [],
+}) {
+  if (!Array.isArray(target)) {
+    target = [target];
+  }
+
+  if (!input) {
+    throw new Error('options.input is required.');
+  }
+
+  // Validate the target generators
+  const validTargets = target.filter(t => availableGenerators.includes(t));
+
+  // Load and parse the API documentation files
+  const apiDocFiles = loadFiles(input);
+  const parsedApiDocs = await parseApiDocs(apiDocFiles);
+
+  const { runGenerators } = createGenerator(parsedApiDocs);
+
+  // Retrieves Node.js release metadata from a given Node.js version and CHANGELOG.md file
+  const { getAllMajors } = createNodeReleases(changelog);
+
+  return await runGenerators({
+    generators: validTargets,
+    output: output && resolve(output),
+    version: coerce(version),
+    releases: await getAllMajors(),
+  });
+}