@cparra/apexdocs 3.17.0-beta.1 → 3.17.0-beta.3

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-DBJhh0_O.js');
+var logger$1 = require('../logger-DK9lGHPu.js');
 var cosmiconfig = require('cosmiconfig');
 var yargs = require('yargs');
 var E = require('fp-ts/Either');
@@ -15,6 +15,10 @@ require('fp-ts/lib/Array');
 require('@cparra/apex-reflection');
 require('fp-ts/Option');
 require('fast-xml-parser');
+require('node:worker_threads');
+require('node:path');
+require('node:os');
+require('node:fs');
 require('handlebars');
 require('fp-ts/boolean');
 require('fp-ts/Array');
@@ -152,10 +156,15 @@ const markdownOptions = {
     describe: "Enable experimental support for documenting Lightning Web Components (LWC).",
     default: logger$1.markdownDefaults.experimentalLwcSupport
   },
-  useParallelProcessing: {
+  parallelReflection: {
     type: "boolean",
-    describe: "Enable parallel processing using worker threads for improved performance on large codebases.",
-    default: logger$1.markdownDefaults.useParallelProcessing
+    describe: "Parallelize CPU-heavy reflection via worker threads.",
+    default: logger$1.markdownDefaults.parallelReflection
+  },
+  parallelReflectionMaxWorkers: {
+    type: "number",
+    describe: "Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value based on CPU count.",
+    default: logger$1.markdownDefaults.parallelReflectionMaxWorkers
   }
 };
 

package/dist/core/reflection/apex/apex-reflection.worker.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_worker_threads_1 = require("node:worker_threads");
+const apex_reflection_1 = require("@cparra/apex-reflection");
+function isRequestMessage(msg) {
+    if (!msg || typeof msg !== 'object')
+        return false;
+    const m = msg;
+    if (typeof m.id !== 'number')
+        return false;
+    if (!m.payload || typeof m.payload !== 'object')
+        return false;
+    const p = m.payload;
+    return typeof p.content === 'string';
+}
+function post(msg) {
+    // `parentPort` should always exist in a worker, but guard anyway.
+    if (!node_worker_threads_1.parentPort) {
+        return;
+    }
+    node_worker_threads_1.parentPort.postMessage(msg);
+}
+function reflectOrThrow(rawSource) {
+    const result = (0, apex_reflection_1.reflect)(rawSource);
+    if (result.typeMirror) {
+        return result.typeMirror;
+    }
+    if (result.error) {
+        throw result.error;
+    }
+    throw new Error('Unknown reflection failure: no typeMirror or error returned.');
+}
+if (!node_worker_threads_1.parentPort) {
+    throw new Error('apex-reflection.worker started without a parentPort');
+}
+node_worker_threads_1.parentPort.on('message', (msg) => {
+    if (!isRequestMessage(msg)) {
+        // Can't correlate without a valid id; ignore.
+        return;
+    }
+    const { id, payload } = msg;
+    try {
+        const typeMirror = reflectOrThrow(payload.content);
+        post({ id, ok: true, result: typeMirror });
+    }
+    catch (e) {
+        const message = (e === null || e === void 0 ? void 0 : e.message) &&
+            typeof e.message === 'string'
+            ? e.message
+            : 'Unknown error';
+        post({
+            id,
+            ok: false,
+            error: { message },
+        });
+    }
+});

package/dist/index.d.ts

@@ -400,7 +400,18 @@ type CliConfigurableMarkdownConfig = {
   includeFieldSecurityMetadata: boolean;
   includeInlineHelpTextMetadata: boolean;
   experimentalLwcSupport: boolean;
-  useParallelProcessing: boolean;
+
+  /**
+   * Whether to parallelize CPU-heavy reflection steps via worker threads.
+   * Defaults to true.
+   */
+  parallelReflection: boolean;
+
+  /**
+   * Max number of worker threads to use for parallel reflection.
+   * Defaults to a reasonable value based on CPU count.
+   */
+  parallelReflectionMaxWorkers?: number;
 };
 
 type UserDefinedMarkdownConfig = {

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger = require('./logger-DBJhh0_O.js');
+var logger = require('./logger-DK9lGHPu.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');
@@ -12,6 +12,10 @@ require('fp-ts/lib/Array');
 require('@cparra/apex-reflection');
 require('fp-ts/Option');
 require('fast-xml-parser');
+require('node:worker_threads');
+require('node:path');
+require('node:os');
+require('node:fs');
 require('handlebars');
 require('fp-ts/boolean');
 require('fp-ts/Array');

package/dist/{logger-DBJhh0_O.js → logger-DK9lGHPu.js}

@@ -10,10 +10,14 @@ var A = require('fp-ts/lib/Array');
 var apexReflection = require('@cparra/apex-reflection');
 var O = require('fp-ts/Option');
 var fastXmlParser = require('fast-xml-parser');
+var node_worker_threads = require('node:worker_threads');
+var path$1 = require('node:path');
+var os = require('node:os');
+var fs = require('node:fs');
 var Handlebars = require('handlebars');
 var boolean = require('fp-ts/boolean');
 var A$1 = require('fp-ts/Array');
-var fs = require('fs');
+var fs$1 = require('fs');
 var TE$1 = require('fp-ts/lib/TaskEither');
 var minimatch = require('minimatch');
 var sourceDeployRetrieve = require('@salesforce/source-deploy-retrieve');
@@ -44,7 +48,7 @@ var T__namespace = /*#__PURE__*/_interopNamespaceDefault(T);
 var A__namespace = /*#__PURE__*/_interopNamespaceDefault(A);
 var O__namespace = /*#__PURE__*/_interopNamespaceDefault(O);
 var A__namespace$1 = /*#__PURE__*/_interopNamespaceDefault(A$1);
-var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs$1);
 var TE__namespace$1 = /*#__PURE__*/_interopNamespaceDefault(TE$1);
 
 function apply(fn, ...front) {
@@ -179,19 +183,19 @@ const defaultTranslations = {
   }
 };
 
-var __defProp$s = Object.defineProperty;
-var __getOwnPropSymbols$s = Object.getOwnPropertySymbols;
-var __hasOwnProp$s = Object.prototype.hasOwnProperty;
-var __propIsEnum$s = Object.prototype.propertyIsEnumerable;
-var __defNormalProp$s = (obj, key, value) => key in obj ? __defProp$s(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues$s = (a, b) => {
+var __defProp$r = Object.defineProperty;
+var __getOwnPropSymbols$r = Object.getOwnPropertySymbols;
+var __hasOwnProp$r = Object.prototype.hasOwnProperty;
+var __propIsEnum$r = Object.prototype.propertyIsEnumerable;
+var __defNormalProp$r = (obj, key, value) => key in obj ? __defProp$r(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues$r = (a, b) => {
   for (var prop in b || (b = {}))
-    if (__hasOwnProp$s.call(b, prop))
-      __defNormalProp$s(a, prop, b[prop]);
-  if (__getOwnPropSymbols$s)
-    for (var prop of __getOwnPropSymbols$s(b)) {
-      if (__propIsEnum$s.call(b, prop))
-        __defNormalProp$s(a, prop, b[prop]);
+    if (__hasOwnProp$r.call(b, prop))
+      __defNormalProp$r(a, prop, b[prop]);
+  if (__getOwnPropSymbols$r)
+    for (var prop of __getOwnPropSymbols$r(b)) {
+      if (__propIsEnum$r.call(b, prop))
+        __defNormalProp$r(a, prop, b[prop]);
     }
   return a;
 };
@@ -207,7 +211,7 @@ function isObjectWithStringKeys(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function deepMerge(target, source) {
-  const result = __spreadValues$s({}, target);
+  const result = __spreadValues$r({}, target);
   for (const key in source) {
     if (Object.prototype.hasOwnProperty.call(source, key)) {
       const sourceValue = source[key];
@@ -321,25 +325,25 @@ function isInlineCode(content) {
   return Object.keys(content).includes("__type") && content.__type === "inline-code";
 }
 
-var __defProp$r = Object.defineProperty;
-var __defProps$q = Object.defineProperties;
-var __getOwnPropDescs$q = Object.getOwnPropertyDescriptors;
-var __getOwnPropSymbols$r = Object.getOwnPropertySymbols;
-var __hasOwnProp$r = Object.prototype.hasOwnProperty;
-var __propIsEnum$r = Object.prototype.propertyIsEnumerable;
-var __defNormalProp$r = (obj, key, value) => key in obj ? __defProp$r(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues$r = (a, b) => {
+var __defProp$q = Object.defineProperty;
+var __defProps$p = Object.defineProperties;
+var __getOwnPropDescs$p = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols$q = Object.getOwnPropertySymbols;
+var __hasOwnProp$q = Object.prototype.hasOwnProperty;
+var __propIsEnum$q = Object.prototype.propertyIsEnumerable;
+var __defNormalProp$q = (obj, key, value) => key in obj ? __defProp$q(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues$q = (a, b) => {
   for (var prop in b || (b = {}))
-    if (__hasOwnProp$r.call(b, prop))
-      __defNormalProp$r(a, prop, b[prop]);
-  if (__getOwnPropSymbols$r)
-    for (var prop of __getOwnPropSymbols$r(b)) {
-      if (__propIsEnum$r.call(b, prop))
-        __defNormalProp$r(a, prop, b[prop]);
+    if (__hasOwnProp$q.call(b, prop))
+      __defNormalProp$q(a, prop, b[prop]);
+  if (__getOwnPropSymbols$q)
+    for (var prop of __getOwnPropSymbols$q(b)) {
+      if (__propIsEnum$q.call(b, prop))
+        __defNormalProp$q(a, prop, b[prop]);
     }
   return a;
 };
-var __spreadProps$q = (a, b) => __defProps$q(a, __getOwnPropDescs$q(b));
+var __spreadProps$p = (a, b) => __defProps$p(a, __getOwnPropDescs$p(b));
 function adaptDescribable(describable, linkGenerator) {
   return {
     description: describableToRenderableContent(describable, linkGenerator)
@@ -391,7 +395,7 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
   function extractCustomTags(type) {
     var _a2, _b2;
     const baseTags = ["description", "group", "author", "date", "see", "example", "throws", "exception"];
-    return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase())).map((currentAnnotation) => __spreadProps$q(__spreadValues$r({}, adaptDescribable(currentAnnotation.bodyLines, linkGenerator)), {
+    return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase())).map((currentAnnotation) => __spreadProps$p(__spreadValues$q({}, adaptDescribable(currentAnnotation.bodyLines, linkGenerator)), {
       name: currentAnnotation.name
     }))) != null ? _b2 : [];
   }
@@ -405,7 +409,7 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
     var _a2, _b2;
     return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === "see").map((currentAnnotation) => currentAnnotation.body)) != null ? _b2 : [];
   }
-  return __spreadProps$q(__spreadValues$r({}, adaptDescribable((_a = documentable.docComment) == null ? void 0 : _a.descriptionLines, linkGenerator)), {
+  return __spreadProps$p(__spreadValues$q({}, adaptDescribable((_a = documentable.docComment) == null ? void 0 : _a.descriptionLines, linkGenerator)), {
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
     customTags: extractCustomTags(documentable),
     example: {
@@ -420,25 +424,25 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
   });
 }
 
-var __defProp$q = Object.defineProperty;
-var __defProps$p = Object.defineProperties;
-var __getOwnPropDescs$p = Object.getOwnPropertyDescriptors;
-var __getOwnPropSymbols$q = Object.getOwnPropertySymbols;
-var __hasOwnProp$q = Object.prototype.hasOwnProperty;
-var __propIsEnum$q = Object.prototype.propertyIsEnumerable;
-var __defNormalProp$q = (obj, key, value) => key in obj ? __defProp$q(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues$q = (a, b) => {
+var __defProp$p = Object.defineProperty;
+var __defProps$o = Object.defineProperties;
+var __getOwnPropDescs$o = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols$p = Object.getOwnPropertySymbols;
+var __hasOwnProp$p = Object.prototype.hasOwnProperty;
+var __propIsEnum$p = Object.prototype.propertyIsEnumerable;
+var __defNormalProp$p = (obj, key, value) => key in obj ? __defProp$p(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues$p = (a, b) => {
   for (var prop in b || (b = {}))
-    if (__hasOwnProp$q.call(b, prop))
-      __defNormalProp$q(a, prop, b[prop]);
-  if (__getOwnPropSymbols$q)
-    for (var prop of __getOwnPropSymbols$q(b)) {
-      if (__propIsEnum$q.call(b, prop))
-        __defNormalProp$q(a, prop, b[prop]);
+    if (__hasOwnProp$p.call(b, prop))
+      __defNormalProp$p(a, prop, b[prop]);
+  if (__getOwnPropSymbols$p)
+    for (var prop of __getOwnPropSymbols$p(b)) {
+      if (__propIsEnum$p.call(b, prop))
+        __defNormalProp$p(a, prop, b[prop]);
     }
   return a;
 };
-var __spreadProps$p = (a, b) => __defProps$p(a, __getOwnPropDescs$p(b));
+var __spreadProps$o = (a, b) => __defProps$o(a, __getOwnPropDescs$o(b));
 function adaptMethod(method, linkGenerator, baseHeadingLevel, translations) {
   var _a, _b, _c;
   function buildTitle(method2) {
@@ -468,7 +472,7 @@ function adaptMethod(method, linkGenerator, baseHeadingLevel, translations) {
     returnType: {
       headingLevel: baseHeadingLevel + 1,
       heading: translations.markdown.details.returnType,
-      value: __spreadProps$p(__spreadValues$q({}, adaptDescribable((_b = (_a = method.docComment) == null ? void 0 : _a.returnAnnotation) == null ? void 0 : _b.bodyLines, linkGenerator)), {
+      value: __spreadProps$o(__spreadValues$p({}, adaptDescribable((_b = (_a = method.docComment) == null ? void 0 : _a.returnAnnotation) == null ? void 0 : _b.bodyLines, linkGenerator)), {
         type: linkGenerator(method.typeReference.rawDeclaration)
       })
     },
@@ -527,13 +531,13 @@ function mapParameters(documentable, param, linkGenerator) {
   const paramAnnotation = (_a = documentable.docComment) == null ? void 0 : _a.paramAnnotations.find(
     (pa) => pa.paramName.toLowerCase() === param.name.toLowerCase()
   );
-  return __spreadProps$p(__spreadValues$q({}, adaptDescribable(paramAnnotation == null ? void 0 : paramAnnotation.bodyLines, linkGenerator)), {
+  return __spreadProps$o(__spreadValues$p({}, adaptDescribable(paramAnnotation == null ? void 0 : paramAnnotation.bodyLines, linkGenerator)), {
     name: param.name,
     type: linkGenerator(param.typeReference.rawDeclaration)
   });
 }
 function mapThrows(thrown, linkGenerator) {
-  return __spreadProps$p(__spreadValues$q({}, adaptDescribable(thrown.bodyLines, linkGenerator)), {
+  return __spreadProps$o(__spreadValues$p({}, adaptDescribable(thrown.bodyLines, linkGenerator)), {
     type: linkGenerator(thrown.exceptionName)
   });
 }
@@ -626,25 +630,25 @@ ${yamlString}---
 `;
 }
 
-var __defProp$p = Object.defineProperty;
-var __defProps$o = Object.defineProperties;
-var __getOwnPropDescs$o = Object.getOwnPropertyDescriptors;
-var __getOwnPropSymbols$p = Object.getOwnPropertySymbols;
-var __hasOwnProp$p = Object.prototype.hasOwnProperty;
-var __propIsEnum$p = Object.prototype.propertyIsEnumerable;
-var __defNormalProp$p = (obj, key, value) => key in obj ? __defProp$p(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues$p = (a, b) => {
+var __defProp$o = Object.defineProperty;
+var __defProps$n = Object.defineProperties;
+var __getOwnPropDescs$n = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols$o = Object.getOwnPropertySymbols;
+var __hasOwnProp$o = Object.prototype.hasOwnProperty;
+var __propIsEnum$o = Object.prototype.propertyIsEnumerable;
+var __defNormalProp$o = (obj, key, value) => key in obj ? __defProp$o(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues$o = (a, b) => {
   for (var prop in b || (b = {}))
-    if (__hasOwnProp$p.call(b, prop))
-      __defNormalProp$p(a, prop, b[prop]);
-  if (__getOwnPropSymbols$p)
-    for (var prop of __getOwnPropSymbols$p(b)) {
-      if (__propIsEnum$p.call(b, prop))
-        __defNormalProp$p(a, prop, b[prop]);
+    if (__hasOwnProp$o.call(b, prop))
+      __defNormalProp$o(a, prop, b[prop]);
+  if (__getOwnPropSymbols$o)
+    for (var prop of __getOwnPropSymbols$o(b)) {
+      if (__propIsEnum$o.call(b, prop))
+        __defNormalProp$o(a, prop, b[prop]);
     }
   return a;
 };
-var __spreadProps$o = (a, b) => __defProps$o(a, __getOwnPropDescs$o(b));
+var __spreadProps$n = (a, b) => __defProps$n(a, __getOwnPropDescs$n(b));
 function typeToRenderable$1(parsedFile, linkGenerator, config, translations) {
   function getRenderable() {
     const { type } = parsedFile;
@@ -663,7 +667,7 @@ function typeToRenderable$1(parsedFile, linkGenerator, config, translations) {
         return lwcMetadataToRenderable(type, config, translations);
     }
   }
-  return __spreadProps$o(__spreadValues$p({}, getRenderable()), {
+  return __spreadProps$n(__spreadValues$o({}, getRenderable()), {
     filePath: isInSource(parsedFile.source) ? parsedFile.source.filePath : void 0,
     namespace: config.namespace
   });
@@ -688,7 +692,7 @@ function baseTypeAdapter(type, linkGenerator, baseHeadingLevel, translations) {
   };
 }
 function enumTypeToEnumSource(enumType, linkGenerator, baseHeadingLevel = 1, translations) {
-  return __spreadProps$o(__spreadValues$p({
+  return __spreadProps$n(__spreadValues$o({
     type: "enum"
   }, baseTypeAdapter(enumType, linkGenerator, baseHeadingLevel, translations)), {
     values: {
@@ -696,7 +700,7 @@ function enumTypeToEnumSource(enumType, linkGenerator, baseHeadingLevel = 1, tra
       heading: translations.markdown.sections.values,
       value: enumType.values.map((value) => {
         var _a;
-        return __spreadProps$o(__spreadValues$p({}, adaptDescribable((_a = value.docComment) == null ? void 0 : _a.descriptionLines, linkGenerator)), {
+        return __spreadProps$n(__spreadValues$o({}, adaptDescribable((_a = value.docComment) == null ? void 0 : _a.descriptionLines, linkGenerator)), {
           value: value.name
         });
       })
@@ -704,7 +708,7 @@ function enumTypeToEnumSource(enumType, linkGenerator, baseHeadingLevel = 1, tra
   });
 }
 function interfaceTypeToInterfaceSource(interfaceType, linkGenerator, baseHeadingLevel = 1, translations) {
-  return __spreadProps$o(__spreadValues$p({
+  return __spreadProps$n(__spreadValues$o({
     type: "interface"
   }, baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel, translations)), {
     extends: interfaceType.extended_interfaces.map(linkGenerator),
@@ -718,7 +722,7 @@ function interfaceTypeToInterfaceSource(interfaceType, linkGenerator, baseHeadin
   });
 }
 function classTypeToClassSource(classType, linkGenerator, baseHeadingLevel = 1, translations) {
-  return __spreadProps$o(__spreadValues$p({
+  return __spreadProps$n(__spreadValues$o({
     type: "class"
   }, baseTypeAdapter(classType, linkGenerator, baseHeadingLevel, translations)), {
     classModifier: classType.classModifier,
@@ -762,7 +766,7 @@ function classTypeToClassSource(classType, linkGenerator, baseHeadingLevel = 1,
       heading: translations.markdown.sections.classes,
       value: classType.classes.map(
         (innerClass) => classTypeToClassSource(
-          __spreadProps$o(__spreadValues$p({}, innerClass), { inheritanceChain: [] }),
+          __spreadProps$n(__spreadValues$o({}, innerClass), { inheritanceChain: [] }),
           linkGenerator,
           baseHeadingLevel + 2,
           translations
@@ -1133,25 +1137,6 @@ function toMap(metadata) {
   return map;
 }
 
-var __defProp$o = Object.defineProperty;
-var __defProps$n = Object.defineProperties;
-var __getOwnPropDescs$n = Object.getOwnPropertyDescriptors;
-var __getOwnPropSymbols$o = Object.getOwnPropertySymbols;
-var __hasOwnProp$o = Object.prototype.hasOwnProperty;
-var __propIsEnum$o = Object.prototype.propertyIsEnumerable;
-var __defNormalProp$o = (obj, key, value) => key in obj ? __defProp$o(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues$o = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp$o.call(b, prop))
-      __defNormalProp$o(a, prop, b[prop]);
-  if (__getOwnPropSymbols$o)
-    for (var prop of __getOwnPropSymbols$o(b)) {
-      if (__propIsEnum$o.call(b, prop))
-        __defNormalProp$o(a, prop, b[prop]);
-    }
-  return a;
-};
-var __spreadProps$n = (a, b) => __defProps$n(a, __getOwnPropDescs$n(b));
 var __async$6 = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -1172,89 +1157,248 @@ var __async$6 = (__this, __arguments, generator) => {
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
-function reflectAsync$2(rawSource) {
-  return __async$6(this, null, function* () {
+class WorkerPool {
+  constructor(createWorker, options = {}) {
+    this.nextTaskId = 1;
+    this.terminating = false;
+    this.idleWorkers = [];
+    this.busyWorkers = /* @__PURE__ */ new Set();
+    this.allWorkers = /* @__PURE__ */ new Set();
+    this.queue = [];
+    this.inFlightByWorker = /* @__PURE__ */ new Map();
+    this.createdWorkers = 0;
+    this.completedTasks = 0;
+    this.failedTasks = 0;
+    var _a, _b, _c, _d, _e, _f;
+    this.createWorker = createWorker;
+    const cpuCount = Math.max(1, (_b = (_a = os.cpus()) == null ? void 0 : _a.length) != null ? _b : 1);
+    this.maxWorkers = Math.max(1, (_c = options.maxWorkers) != null ? _c : cpuCount);
+    this.maxQueueSize = (_d = options.maxQueueSize) != null ? _d : Number.POSITIVE_INFINITY;
+    this.drainOnTerminate = (_e = options.drainOnTerminate) != null ? _e : false;
+    this.unrefWorkers = (_f = options.unrefWorkers) != null ? _f : false;
+  }
+  /**
+   * Enqueue a task and resolve with the worker's response `result`.
+   */
+  run(payload) {
+    if (this.terminating) {
+      return Promise.reject(new Error("WorkerPool is terminating; cannot accept new tasks."));
+    }
+    if (this.queue.length >= this.maxQueueSize) {
+      return Promise.reject(
+        new Error(`WorkerPool queue limit exceeded (maxQueueSize=${this.maxQueueSize}).`)
+      );
+    }
+    const id = this.nextTaskId++;
     return new Promise((resolve, reject) => {
-      const result = apexReflection.reflect(rawSource);
-      if (result.typeMirror) {
-        return resolve(result.typeMirror);
-      } else if (result.error) {
-        return reject(result.error);
-      } else {
-        return reject(new Error("Unknown error"));
-      }
+      this.queue.push({
+        id,
+        payload,
+        resolve,
+        reject
+      });
+      this.pump();
     });
-  });
-}
-function reflectApexSource(apexBundles) {
-  const semiGroupReflectionError = {
-    concat: (x, y) => new ReflectionErrors([...x.errors, ...y.errors])
-  };
-  const Ap = TE__namespace.getApplicativeTaskValidation(T__namespace.ApplyPar, semiGroupReflectionError);
-  return _function.pipe(apexBundles, A__namespace.traverse(Ap)(reflectBundle$2));
-}
-function reflectBundle$2(apexBundle) {
-  const convertToParsedFile = apply(toParsedFile$6, apexBundle.filePath);
-  const withMetadata = apply(addMetadata, apexBundle.metadataContent);
-  return _function.pipe(apexBundle, reflectAsTask$1, TE__namespace.map(convertToParsedFile), TE__namespace.flatMap(withMetadata));
-}
-function reflectAsTask$1(apexBundle) {
-  return TE__namespace.tryCatch(
-    () => reflectAsync$2(apexBundle.content),
-    (error) => new ReflectionErrors([new ReflectionError(apexBundle.filePath, error.message)])
-  );
-}
-function toParsedFile$6(filePath, typeMirror) {
-  return {
-    source: {
-      filePath,
-      name: typeMirror.name,
-      type: typeMirror.type_name
-    },
-    type: typeMirror
-  };
-}
-function addMetadata(rawMetadataContent, parsedFile) {
-  return TE__namespace.fromEither(
-    _function.pipe(
-      parsedFile.type,
-      (type) => addFileMetadataToTypeAnnotation$1(type, rawMetadataContent),
-      E__namespace.map((type) => __spreadProps$n(__spreadValues$o({}, parsedFile), { type })),
-      E__namespace.mapLeft(
-        (error) => errorToReflectionErrors$1(error, isInSource(parsedFile.source) ? parsedFile.source.filePath : "")
-      )
-    )
-  );
-}
-function errorToReflectionErrors$1(error, filePath) {
-  return new ReflectionErrors([new ReflectionError(filePath, error.message)]);
-}
-function addFileMetadataToTypeAnnotation$1(type, metadata) {
-  const concatAnnotationToType = apply(concatAnnotations$1, type);
-  return _function.pipe(
-    O__namespace.fromNullable(metadata),
-    O__namespace.map(concatAnnotationToType),
-    O__namespace.getOrElse(() => E__namespace.right(type))
-  );
-}
-function concatAnnotations$1(type, metadataInput) {
-  return _function.pipe(
-    metadataInput,
-    parseApexMetadata,
-    E__namespace.map((metadataMap) => __spreadProps$n(__spreadValues$o({}, type), {
-      annotations: [...type.annotations, ...mapToAnnotations$1(metadataMap)]
-    }))
-  );
-}
-function mapToAnnotations$1(metadata) {
-  return Array.from(metadata.entries()).map(([key, value]) => {
-    const declaration = `${key}: ${value}`;
+  }
+  /**
+   * Returns current pool stats.
+   */
+  stats() {
     return {
-      name: declaration,
-      type: declaration,
-      rawDeclaration: declaration
+      maxWorkers: this.maxWorkers,
+      activeWorkers: this.allWorkers.size,
+      idleWorkers: this.idleWorkers.length,
+      queuedTasks: this.queue.length,
+      inFlightTasks: this.inFlightByWorker.size,
+      createdWorkers: this.createdWorkers,
+      completedTasks: this.completedTasks,
+      failedTasks: this.failedTasks
     };
-  });
+  }
+  /**
+   * Terminates all workers and rejects queued tasks (unless drainOnTerminate=true).
+   *
+   * - If `drainOnTerminate` is false (default), queued tasks are rejected immediately,
+   *   and in-flight tasks are rejected when each worker is terminated.
+   * - If `drainOnTerminate` is true, the pool stops accepting new tasks and will attempt
+   *   to finish queued + in-flight tasks before terminating workers.
+   */
+  terminate() {
+    return __async$6(this, null, function* () {
+      if (this.terminating) {
+        return;
+      }
+      this.terminating = true;
+      if (!this.drainOnTerminate) {
+        while (this.queue.length) {
+          const task = this.queue.shift();
+          task.reject(new Error("WorkerPool terminated before task could start."));
+          this.failedTasks++;
+        }
+      }
+      if (this.drainOnTerminate) {
+        yield this.waitForDrain();
+      }
+      const terminations = Array.from(this.allWorkers).map((w) => __async$6(this, null, function* () {
+        this.rejectInFlight(w, new Error("WorkerPool terminated with task still in flight."));
+        try {
+          yield w.terminate();
+        } catch (e) {
+        }
+      }));
+      yield Promise.all(terminations);
+      this.idleWorkers.length = 0;
+      this.busyWorkers.clear();
+      this.allWorkers.clear();
+      this.inFlightByWorker.clear();
+    });
+  }
+  /**
+   * Wait until all queued tasks have been processed and no tasks are in flight.
+   * This does NOT terminate workers.
+   */
+  drain() {
+    return __async$6(this, null, function* () {
+      yield this.waitForDrain();
+    });
+  }
+  pump() {
+    if (this.terminating && !this.drainOnTerminate) {
+      return;
+    }
+    while (this.queue.length > 0) {
+      const worker = this.getIdleOrCreateWorker();
+      if (!worker) {
+        return;
+      }
+      const task = this.queue.shift();
+      this.assign(worker, task);
+    }
+  }
+  getIdleOrCreateWorker() {
+    const idle = this.idleWorkers.pop();
+    if (idle) return idle;
+    if (this.allWorkers.size < this.maxWorkers) {
+      const w = this.spawnWorker();
+      return w;
+    }
+    return null;
+  }
+  spawnWorker() {
+    const worker = this.createWorker();
+    this.createdWorkers++;
+    this.allWorkers.add(worker);
+    if (this.unrefWorkers) {
+      worker.unref();
+    }
+    worker.on("message", (msg) => this.onWorkerMessage(worker, msg));
+    worker.on("error", (err) => this.onWorkerError(worker, err));
+    worker.on("exit", (code) => this.onWorkerExit(worker, code));
+    this.idleWorkers.push(worker);
+    return worker;
+  }
+  assign(worker, task) {
+    this.idleWorkersRemove(worker);
+    this.busyWorkers.add(worker);
+    this.inFlightByWorker.set(worker, {
+      id: task.id,
+      resolve: task.resolve,
+      reject: task.reject
+    });
+    try {
+      worker.postMessage({ id: task.id, payload: task.payload });
+    } catch (e) {
+      this.inFlightByWorker.delete(worker);
+      this.busyWorkers.delete(worker);
+      this.idleWorkers.push(worker);
+      task.reject(e);
+      this.failedTasks++;
+      this.pump();
+    }
+  }
+  onWorkerMessage(worker, msg) {
+    var _a;
+    const inFlight = this.inFlightByWorker.get(worker);
+    if (!inFlight) {
+      return;
+    }
+    const m = msg;
+    const sameId = typeof (m == null ? void 0 : m.id) === "number" && m.id === inFlight.id;
+    const okFlag = typeof (m == null ? void 0 : m.ok) === "boolean";
+    if (!sameId || !okFlag) {
+      this.finishTask(worker);
+      inFlight.reject(
+        new Error("WorkerPool received an invalid response message for the in-flight task.")
+      );
+      this.failedTasks++;
+      this.pump();
+      return;
+    }
+    this.finishTask(worker);
+    if (m.ok) {
+      this.completedTasks++;
+      inFlight.resolve(m.result);
+    } else {
+      this.failedTasks++;
+      inFlight.reject((_a = m.error) != null ? _a : new Error("Worker indicated failure without an error payload."));
+    }
+    this.pump();
+  }
+  onWorkerError(worker, err) {
+    this.rejectInFlight(worker, err);
+    this.removeWorker(worker);
+    this.pump();
+  }
+  onWorkerExit(worker, code) {
+    this.rejectInFlight(worker, new Error(`Worker exited unexpectedly (code=${code}).`));
+    this.removeWorker(worker);
+    this.pump();
+  }
+  finishTask(worker) {
+    this.inFlightByWorker.delete(worker);
+    this.busyWorkers.delete(worker);
+    if (!this.terminating || this.drainOnTerminate) {
+      this.idleWorkers.push(worker);
+    }
+  }
+  rejectInFlight(worker, reason) {
+    const inFlight = this.inFlightByWorker.get(worker);
+    if (!inFlight) return;
+    this.inFlightByWorker.delete(worker);
+    this.busyWorkers.delete(worker);
+    inFlight.reject(reason);
+    this.failedTasks++;
+  }
+  removeWorker(worker) {
+    this.inFlightByWorker.delete(worker);
+    this.busyWorkers.delete(worker);
+    this.idleWorkersRemove(worker);
+    this.allWorkers.delete(worker);
+  }
+  idleWorkersRemove(worker) {
+    const idx = this.idleWorkers.indexOf(worker);
+    if (idx !== -1) {
+      this.idleWorkers.splice(idx, 1);
+    }
+  }
+  waitForDrain() {
+    return __async$6(this, null, function* () {
+      if (this.queue.length === 0 && this.inFlightByWorker.size === 0) {
+        return;
+      }
+      yield new Promise((resolve) => {
+        const tick = () => {
+          this.pump();
+          if (this.queue.length === 0 && this.inFlightByWorker.size === 0) {
+            resolve();
+            return;
+          }
+          setTimeout(tick, 10);
+        };
+        tick();
+      });
+    });
+  }
 }
 
 var __defProp$n = Object.defineProperty;
@@ -1310,51 +1454,109 @@ function reflectAsync$1(rawSource) {
     });
   });
 }
-function reflectApexSourceParallel(apexBundles) {
+function supportsWorkerThreads() {
+  try {
+    return typeof node_worker_threads.Worker === "function";
+  } catch (e) {
+    return false;
+  }
+}
+function isWorkerReflectionEnabled(config) {
+  var _a, _b;
+  const env = ((_a = process.env.APEXDOCS_WORKER_REFLECTION) != null ? _a : "").toLowerCase();
+  if (env === "true" || env === "1") return true;
+  if (env === "false" || env === "0") return false;
+  return (_b = config == null ? void 0 : config.parallelReflection) != null ? _b : true;
+}
+function getWorkerEntrypointPath() {
+  const candidate1 = path$1.resolve(__dirname, "./apex-reflection.worker.js");
+  if (fs.existsSync(candidate1)) {
+    return candidate1;
+  }
+  const candidate1b = path$1.resolve(__dirname, "../apex-reflection.worker.js");
+  if (fs.existsSync(candidate1b)) {
+    return candidate1b;
+  }
+  let dir = __dirname;
+  for (let i = 0; i < 10; i++) {
+    const maybeDist1 = path$1.resolve(dir, "../../..");
+    const candidate2a = path$1.resolve(maybeDist1, "core", "reflection", "apex", "apex-reflection.worker.js");
+    if (fs.existsSync(candidate2a)) {
+      return candidate2a;
+    }
+    const maybeDist2 = path$1.resolve(dir, "../../../..");
+    const candidate2b = path$1.resolve(maybeDist2, "core", "reflection", "apex", "apex-reflection.worker.js");
+    if (fs.existsSync(candidate2b)) {
+      return candidate2b;
+    }
+    const parent = path$1.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return candidate1;
+}
+function reflectAsTaskParallel(apexBundles, config) {
   return TE__namespace.tryCatch(
     () => __async$5(null, null, function* () {
-      if (apexBundles.length === 0) {
-        return [];
-      }
-      const results = yield Promise.all(apexBundles.map((bundle) => reflectBundleAsync(bundle)));
-      const errors = [];
-      const parsedFiles = [];
-      for (const result of results) {
-        if (E__namespace.isRight(result)) {
-          parsedFiles.push(result.right);
-        } else {
-          errors.push(...result.left.errors);
-        }
-      }
-      if (errors.length > 0) {
-        throw new ReflectionErrors(errors);
+      var _a, _b, _c;
+      const cpu = (_b = (_a = os.cpus()) == null ? void 0 : _a.length) != null ? _b : 1;
+      const defaultMax = Math.max(1, Math.min(cpu, 8));
+      const maxWorkers = Math.max(1, (_c = config == null ? void 0 : config.parallelReflectionMaxWorkers) != null ? _c : defaultMax);
+      const pool = new WorkerPool(() => new node_worker_threads.Worker(getWorkerEntrypointPath()), {
+        maxWorkers
+        // Keep default queue size (Infinity) unless we later decide to bound it via config.
+      });
+      try {
+        const results = yield Promise.all(
+          apexBundles.map((bundle) => __async$5(null, null, function* () {
+            const typeMirror = yield pool.run({ content: bundle.content });
+            return typeMirror;
+          }))
+        );
+        return results;
+      } finally {
+        yield pool.terminate();
       }
-      return parsedFiles;
     }),
     (error) => {
-      if (error instanceof ReflectionErrors) {
-        return error;
-      }
-      return new ReflectionErrors([new ReflectionError("", error.message)]);
+      const message = error == null ? void 0 : error.message;
+      return new ReflectionErrors([new ReflectionError("", typeof message === "string" ? message : "Worker failure")]);
     }
   );
 }
-function reflectBundleAsync(apexBundle) {
-  return __async$5(this, null, function* () {
-    try {
-      const type = yield reflectAsync$1(apexBundle.content);
-      const parsedFile = toParsedFile$5(apexBundle.filePath, type);
-      if (apexBundle.metadataContent) {
-        const withMetadataResult = yield addMetadataSync(apexBundle.metadataContent, parsedFile);
-        return withMetadataResult;
-      }
-      return E__namespace.right(parsedFile);
-    } catch (error) {
-      return E__namespace.left(
-        new ReflectionErrors([new ReflectionError(apexBundle.filePath, error.message)])
-      );
-    }
-  });
+function reflectApexSource(apexBundles, config) {
+  const semiGroupReflectionError = {
+    concat: (x, y) => new ReflectionErrors([...x.errors, ...y.errors])
+  };
+  const Ap = TE__namespace.getApplicativeTaskValidation(T__namespace.ApplyPar, semiGroupReflectionError);
+  if (!isWorkerReflectionEnabled(config) || !supportsWorkerThreads()) {
+    return _function.pipe(apexBundles, A__namespace.traverse(Ap)(reflectBundle$2));
+  }
+  return _function.pipe(
+    reflectAsTaskParallel(apexBundles, config),
+    TE__namespace.map((typeMirrors) => typeMirrors.map((t, idx) => ({ t, idx }))),
+    TE__namespace.mapLeft((errs) => errs),
+    TE__namespace.flatMap((pairs) => {
+      const parsedTasks = pairs.map(({ t, idx }) => {
+        const bundle = apexBundles[idx];
+        const convertToParsedFile = apply(toParsedFile$5, bundle.filePath);
+        const withMetadata = apply(addMetadata, bundle.metadataContent);
+        return _function.pipe(TE__namespace.right(t), TE__namespace.map(convertToParsedFile), TE__namespace.flatMap(withMetadata));
+      });
+      return _function.pipe(parsedTasks, A__namespace.sequence(Ap));
+    })
+  );
+}
+function reflectBundle$2(apexBundle) {
+  const convertToParsedFile = apply(toParsedFile$5, apexBundle.filePath);
+  const withMetadata = apply(addMetadata, apexBundle.metadataContent);
+  return _function.pipe(apexBundle, reflectAsTask$1, TE__namespace.map(convertToParsedFile), TE__namespace.flatMap(withMetadata));
+}
+function reflectAsTask$1(apexBundle) {
+  return TE__namespace.tryCatch(
+    () => reflectAsync$1(apexBundle.content),
+    (error) => new ReflectionErrors([new ReflectionError(apexBundle.filePath, error.message)])
+  );
 }
 function toParsedFile$5(filePath, typeMirror) {
   return {
@@ -1366,17 +1568,17 @@ function toParsedFile$5(filePath, typeMirror) {
     type: typeMirror
   };
 }
-function addMetadataSync(rawMetadataContent, parsedFile) {
-  return __async$5(this, null, function* () {
-    return _function.pipe(
+function addMetadata(rawMetadataContent, parsedFile) {
+  return TE__namespace.fromEither(
+    _function.pipe(
       parsedFile.type,
       (type) => addFileMetadataToTypeAnnotation(type, rawMetadataContent),
       E__namespace.map((type) => __spreadProps$m(__spreadValues$n({}, parsedFile), { type })),
       E__namespace.mapLeft(
         (error) => errorToReflectionErrors(error, isInSource(parsedFile.source) ? parsedFile.source.filePath : "")
       )
-    );
-  });
+    )
+  );
 }
 function errorToReflectionErrors(error, filePath) {
   return new ReflectionErrors([new ReflectionError(filePath, error.message)]);
@@ -2006,7 +2208,10 @@ const markdownDefaults = __spreadProps$j(__spreadValues$k({}, markdownAndChangel
   includeFieldSecurityMetadata: false,
   includeInlineHelpTextMetadata: false,
   experimentalLwcSupport: false,
-  useParallelProcessing: true
+  // Performance: parallel reflection via worker threads (enabled by default).
+  parallelReflection: true,
+  // Default is computed at runtime if not provided.
+  parallelReflectionMaxWorkers: void 0
 });
 const openApiDefaults = __spreadProps$j(__spreadValues$k({}, commonDefaults), {
   fileName: "openapi",
@@ -3426,10 +3631,12 @@ function replaceMacros(unparsedBundles, macros) {
 function generateForApex(apexBundles, config) {
   const filterOutOfScope = apply(filterScope, config.scope);
   const removeExcluded = apply(removeExcludedTags, config.excludeTags);
-  const reflectFn = config.useParallelProcessing ? reflectApexSourceParallel : reflectApexSource;
   return _function.pipe(
     apexBundles,
-    reflectFn,
+    (bundles) => reflectApexSource(bundles, {
+      parallelReflection: config.parallelReflection,
+      parallelReflectionMaxWorkers: config.parallelReflectionMaxWorkers
+    }),
     TE__namespace.map(filterOutOfScope),
     TE__namespace.map(addInheritedMembersToTypes),
     TE__namespace.map(addInheritanceChainToTypes),
@@ -5251,6 +5458,9 @@ var __async$1 = (__this, __arguments, generator) => {
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
+const changelogReflectionConfig = {
+  parallelReflection: false
+};
 function generateChangeLog(oldBundles, newBundles, config) {
   const convertToPageData = apply(toPageData, config.fileName);
   function handleConversion({ changelog, newManifest }) {
@@ -5281,7 +5491,7 @@ function generateChangeLog(oldBundles, newBundles, config) {
 function reflect(bundles, config) {
   const filterOutOfScopeApex = apply(filterScope, config.scope);
   function reflectApexFiles(sourceFiles) {
-    return _function.pipe(reflectApexSource(sourceFiles), TE__namespace.map(filterOutOfScopeApex));
+    return _function.pipe(reflectApexSource(sourceFiles, changelogReflectionConfig), TE__namespace.map(filterOutOfScopeApex));
   }
   return _function.pipe(
     // Filter out LWC. These will be implemented at a later date

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.17.0-beta.1",
+  "version": "3.17.0-beta.3",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -36,7 +36,7 @@
       "output": []
     },
     "build": {
-      "command": "tsc --noEmit --pretty && pkgroll",
+      "command": "tsc --noEmit --pretty && pkgroll --target node18 && node -e \"const fs=require('fs'); const path=require('path'); const src=path.join(__dirname,'src','core','reflection','apex','apex-reflection.worker.ts'); const distRoot=path.join(__dirname,'dist'); const candidates=[]; (function walk(dir){ for (const ent of fs.readdirSync(dir,{withFileTypes:true})) { const p=path.join(dir,ent.name); if (ent.isDirectory()) walk(p); else if (ent.isFile() && ent.name==='generate.js') candidates.push(p); } })(distRoot); if (!candidates.length) throw new Error('Could not locate dist bundle to determine worker output location'); const distEntry=candidates[0]; const destDir=path.join(path.dirname(distEntry),'..','core','reflection','apex'); fs.mkdirSync(destDir,{recursive:true}); const out=path.join(destDir,'apex-reflection.worker.js'); const ts=require('typescript'); const input=fs.readFileSync(src,'utf8'); const res=ts.transpileModule(input,{compilerOptions:{module:ts.ModuleKind.CommonJS,target:ts.ScriptTarget.ES2018,esModuleInterop:true}}); fs.writeFileSync(out,res.outputText,'utf8'); if (!fs.existsSync(out)) throw new Error('Failed to write worker entrypoint');\"",
       "dependencies": [
         "lint"
       ],
@@ -92,7 +92,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.22.0-beta.1",
+    "@cparra/apex-reflection": "2.21.1",
     "@salesforce/source-deploy-retrieve": "^12.20.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",