@cparra/apexdocs 3.17.0-beta.0 → 3.17.0-beta.2

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-Cej7LT-j.js');
+var logger$1 = require('../logger-CBoQUQAm.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');
@@ -151,6 +155,16 @@ const markdownOptions = {
     type: "boolean",
     describe: "Enable experimental support for documenting Lightning Web Components (LWC).",
     default: logger$1.markdownDefaults.experimentalLwcSupport
+  },
+  parallelReflection: {
+    type: "boolean",
+    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,6 +400,18 @@ type CliConfigurableMarkdownConfig = {
   includeFieldSecurityMetadata: boolean;
   includeInlineHelpTextMetadata: boolean;
   experimentalLwcSupport: 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-Cej7LT-j.js');
+var logger = require('./logger-CBoQUQAm.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-Cej7LT-j.js → logger-CBoQUQAm.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) {
@@ -1133,6 +1137,270 @@ function toMap(metadata) {
   return map;
 }
 
+var __async$6 = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+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) => {
+      this.queue.push({
+        id,
+        payload,
+        resolve,
+        reject
+      });
+      this.pump();
+    });
+  }
+  /**
+   * Returns current pool stats.
+   */
+  stats() {
+    return {
+      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;
 var __defProps$m = Object.defineProperties;
 var __getOwnPropDescs$m = Object.getOwnPropertyDescriptors;
@@ -1186,12 +1454,89 @@ function reflectAsync$1(rawSource) {
     });
   });
 }
-function reflectApexSource(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;
+  }
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    const maybeDist = path$1.resolve(dir, "../../..");
+    const candidate2 = path$1.resolve(maybeDist, "core", "reflection", "apex", "apex-reflection.worker.js");
+    if (fs.existsSync(candidate2)) {
+      return candidate2;
+    }
+    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* () {
+      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();
+      }
+    }),
+    (error) => {
+      const message = error == null ? void 0 : error.message;
+      return new ReflectionErrors([new ReflectionError("", typeof message === "string" ? message : "Worker failure")]);
+    }
+  );
+}
+function reflectApexSource(apexBundles, config) {
   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));
+  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);
@@ -1853,7 +2198,11 @@ const markdownDefaults = __spreadProps$j(__spreadValues$k({}, markdownAndChangel
   excludeTags: [],
   includeFieldSecurityMetadata: false,
   includeInlineHelpTextMetadata: false,
-  experimentalLwcSupport: false
+  experimentalLwcSupport: false,
+  // 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",
@@ -3275,7 +3624,10 @@ function generateForApex(apexBundles, config) {
   const removeExcluded = apply(removeExcludedTags, config.excludeTags);
   return _function.pipe(
     apexBundles,
-    reflectApexSource,
+    (bundles) => reflectApexSource(bundles, {
+      parallelReflection: config.parallelReflection,
+      parallelReflectionMaxWorkers: config.parallelReflectionMaxWorkers
+    }),
     TE__namespace.map(filterOutOfScope),
     TE__namespace.map(addInheritedMembersToTypes),
     TE__namespace.map(addInheritanceChainToTypes),
@@ -5097,6 +5449,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 }) {
@@ -5127,7 +5482,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.0",
+  "version": "3.17.0-beta.2",
   "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.0",
+    "@cparra/apex-reflection": "2.21.1",
     "@salesforce/source-deploy-retrieve": "^12.20.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",