@arcgis/api-extractor 5.0.0-next.136 → 5.0.0-next.137

package/dist/utils/internalTypeScriptApis.d.ts

@@ -0,0 +1,92 @@
+/** @experimental */
+import type ts from "typescript";
+
+/** Simplified type. Does not include all fields. */
+export interface SourceMap {
+  mappings: "";
+}
+
+/**
+ * Using undocumented TypeScript APIs can break at any time. Moreover, with the
+ * transition to tsgo, the code using these APIs will definitely need to be
+ * refactored.
+ *
+ * However, we are still using them for now because:
+ * - until tsgo provides better API, this is the best way we have
+ * - the migration to tsgo may require significant refactoring anyway, as
+ *   IPC overhead requires TypeScript to rethink the public API.
+ *
+ * Use cases for undocumented TypeScript APIs:
+ * - workaround for there being no public API for printing a file with source
+ *   maps. See: https://github.com/microsoft/TypeScript/issues/51329#issuecomment-2197859814
+ *   - TS has alternative API (program.emit), but it is very slow and does
+ *     type-checking. If tsgo has an API we need, we could use it. Otherwise
+ *     would have to use an alternative AST+transformer+printer in Lumina.
+ * - print TypeNode object literals across multiple lines rather than single
+ *   line
+ *   - alternative: use regex hacks
+ * - keep track of the location of each TypeReferenceNode as it is printed to
+ *   populate the ApiTypeReference.start and .end fields. Alternatives:
+ *   - alternative 1: write custom printer for type nodes, with fallback to
+ *     TypeScript's printer for unknown nodes and `typeof <expression>` syntax.
+ *     Much more control, much better performance, and less exposure to tsgo.
+ *     But is much more complexity.
+ *   - alternative 2: before printing or as part of printing, replace all
+ *     TypeReferenceNodes with markers (`__ref_1__`), then post-process the
+ *     print result.
+ *   - alternative 3: collect list of type references before printing. after
+ *     printing, do a regex search on print string and try matching each type
+ *     reference to places where it is printed.
+ */
+export const unsafeUndocumentedTs: Required<UndocumentedTypeScript>;
+
+export interface UndocumentedTypeScript {
+  /**
+   * @param host
+   * @param basename
+   * @param sourceRoot
+   * @param dirname
+   * @param compilerOptions
+   */
+  createSourceMapGenerator?(host: Pick<ts.CompilerHost, "getCanonicalFileName" | "getCurrentDirectory">, basename: string, sourceRoot: string, dirname: string, compilerOptions: Record<never, never> | ts.CompilerOptions): SourceMapGenerator;
+  /** @param newLine */
+  createTextWriter?(newLine: string): EmitTextWriter;
+  /**
+   * @param options - Printer has undocumented options for printing source maps:
+   * https://github.com/microsoft/TypeScript/blob/7319968e90600102892a79142fb804bcbe384160/src/compiler/types.ts#L9689C18-L9707
+   * @param handlers
+   */
+  createPrinter(options: ts.CompilerOptions & ts.PrinterOptions, handlers?: ts.PrintHandlers): ReturnType<typeof ts.createPrinter> & UndocumentedPrinter;
+}
+
+export interface SourceMapGenerator {
+  toJSON(): SourceMap;
+}
+
+export interface UndocumentedPrinter {
+  /**
+   * @param writeFile
+   * @param writer
+   * @param sourceMapGenerator
+   */
+  writeFile?(writeFile: ts.SourceFile, writer: EmitTextWriter, sourceMapGenerator: SourceMapGenerator | undefined): void;
+  /**
+   * @param hint
+   * @param node
+   * @param sourceFile
+   * @param output
+   */
+  writeNode?(hint: ts.EmitHint, node: ts.Node, sourceFile: ts.SourceFile | undefined, output: EmitTextWriter): void;
+}
+
+export interface EmitTextWriter {
+  getText(): string;
+  getTextPos(): number;
+  clear(): void;
+}
+
+/**
+ * @param compilerOptions
+ * @param handlers
+ */
+export function unsafeGetUndocumentedPrinter(compilerOptions: ts.CompilerOptions, handlers?: ts.PrintHandlers): ReturnType<typeof ts.createPrinter> & UndocumentedPrinter;

package/dist/utils/internalTypeScriptApis.js

@@ -0,0 +1,58 @@
+import p from "typescript";
+const n = p, u = n, o = 5, i = 1, s = 3, a = 4;
+d(n.createSourceMapGenerator);
+c(n.createTextWriter);
+function d(e) {
+  if (typeof e != "function")
+    throw Error(
+      "Failed to find ts.createSourceMapGenerator() function. Lumina needs to be updated to support the new TypeScript version"
+    );
+  if (e.length !== o)
+    throw Error(
+      `ts.createSourceMapGenerator() signature changed. Expected ${o} arguments. Lumina needs to be updated to support the new TypeScript version`
+    );
+}
+function c(e) {
+  if (typeof e != "function")
+    throw Error(
+      "Failed to find ts.createTextWriter() function. Lumina needs to be updated to support the new TypeScript version"
+    );
+  if (e.length !== i)
+    throw Error(
+      `ts.createTextWriter() signature changed. Expected ${i} arguments. Lumina needs to be updated to support the new TypeScript version`
+    );
+}
+function f(e) {
+  if (typeof e != "function")
+    throw Error(
+      "Failed to find ts.Printer.writeFile() function. Lumina needs to be updated to support the new TypeScript version"
+    );
+  if (e.length !== s)
+    throw Error(
+      `ts.Printer.writeFile() signature changed. Expected ${s} arguments. Lumina needs to be updated to support the new TypeScript version`
+    );
+}
+function h(e) {
+  if (typeof e != "function")
+    throw Error(
+      "Failed to find ts.Printer.writeNode() function. Lumina needs to be updated to support the new TypeScript version"
+    );
+  if (e.length !== a)
+    throw Error(
+      `ts.Printer.writeNode() signature changed. Expected ${a} arguments. Lumina needs to be updated to support the new TypeScript version`
+    );
+}
+function m(e, t) {
+  const r = u.createPrinter(e, t);
+  return f(r.writeFile), h(r.writeNode), r;
+}
+function w(e, t) {
+  return e.getWidenedLiteralType(
+    t
+  );
+}
+export {
+  w as getWidenedLiteralType,
+  m as unsafeGetUndocumentedPrinter,
+  u as unsafeUndocumentedTs
+};

package/dist/utils/partPrinter.d.ts

@@ -1,23 +1,29 @@
-import { ApiFunctionLike, ApiParameter, ApiTypeParameter } from '../apiJson.ts';
-export declare function printClass(isAbstract: boolean, 
+import type { ApiFunctionLike } from "../apiJson.js";
+
 /**
- * For consistency and to simplify the docs messaging, everything that appears
- * in our .d.ts files is exported - non-public things don't appear in the .d.ts
- * files.
+ * Double quote property name if it is not a valid identifier and not a symbol.
+ *
+ * @param name
  */
-isDefaultExported: boolean, name: string, typeParameters: ApiTypeParameter[] | undefined, extendsClause: string | undefined, membersText: string): string;
-export declare function printTypeParameters(typeParameters: ApiTypeParameter[] | undefined): string;
-export declare function printInterface(
+export function maybeEscapePropertyName(name: string): string;
+
 /**
- * For consistency and to simplify the docs messaging, everything that appears
- * in our .d.ts files is exported - non-public things don't appear in the .d.ts
- * files.
+ * Determine if property name needs to be quoted and have quotes and backslashes
+ * escaped.
+ *
+ * Permits the name to start with [ for computed property names. At present, only
+ * [Symbol.iterator]
+ *
+ * @param name
  */
-isDefaultExported: boolean, name: string, typeParameters: ApiTypeParameter[] | undefined, extendsClause: string[] | undefined, membersText: string): string;
-export declare function printMethod(isProtected: boolean, isAbstract: boolean, isStatic: boolean, isOptional: boolean, name: string, typeParameters: ApiTypeParameter[] | undefined, parameters: ApiParameter[] | undefined, returnType: string | undefined): string;
-export declare function printFunction(isDefaultExported: boolean, name: string, typeParameters: ApiTypeParameter[] | undefined, parameters: ApiParameter[] | undefined, returnType: string): string;
-export declare function printSignature(functionLike: Pick<ApiFunctionLike, "parameters" | "return" | "typeParameters">): string;
-export declare function printProperty(isProtected: boolean, isAbstract: boolean, isStatic: boolean, isReadOnly: boolean, isAccessor: boolean, isOptional: boolean, name: string, type: string): string;
-export declare function printGetterSetter(isProtected: boolean, isAbstract: boolean, isStatic: boolean, name: string, getterType: string, setterType: string | undefined): string;
-export declare function printVariable(isDefaultExported: boolean, name: string, type: string): string;
-export declare function printTypeAlias(name: string, typeParameters: ApiTypeParameter[] | undefined, superTypes: string[] | undefined, type: string | undefined): string;
+export function isPropertyEscapeNeeded(name: string): boolean;
+
+/**
+ * Print a function or method signature.
+ *
+ * Consider refactoring out usages of this function in favor of rendering a
+ * table of parameters (with their description), and a return type section.
+ *
+ * @param functionLike
+ */
+export function printSignature(functionLike: Pick<ApiFunctionLike, "parameters" | "return" | "typeParameters">): string;

package/dist/utils/partPrinter.js

@@ -0,0 +1,82 @@
+function p(t, r, i, e, n, o) {
+  return `${`${r ? "export default " : "export "}${t ? "abstract " : ""}`}class ${i}${f(e)}${n === void 0 ? "" : ` extends ${n}`} {${o}}`;
+}
+function f(t) {
+  if (t === void 0)
+    return "";
+  let r = "<";
+  for (let i = 0; i < t.length; ++i) {
+    const e = t[i];
+    e.const === !0 ? r += "const " : e.in === !0 ? r += "in " : e.out === !0 && (r += "out "), r += e.name, e.constraint !== void 0 && (r += ` extends ${e.constraint.text}`), e.default !== void 0 && (r += ` = ${e.default.text}`), i < t.length - 1 && (r += ", ");
+  }
+  return r += ">", r;
+}
+function x(t, r, i, e, n) {
+  const o = t ? "export default " : "export ";
+  let $ = "";
+  if (e !== void 0) {
+    $ = " extends ";
+    for (let c = 0; c < e.length; ++c)
+      $ += e[c], c < e.length - 1 && ($ += ", ");
+  }
+  return `${o}interface ${r}${f(i)}${$} {${n}}`;
+}
+function v(t, r, i, e, n, o, $, c) {
+  const s = `${t ? "protected " : ""}${r ? "abstract " : ""}${i ? "static " : ""}`, l = c === void 0 ? "" : `: ${c}`;
+  return `${s}${n === "" ? "" : d(n)}${e ? "?" : ""}${f(o)}(${u($)})${l};`;
+}
+function d(t) {
+  return a.test(t) || t.startsWith("[") ? t : `"${t.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+const g = (t) => !a.test(t) && !t.startsWith("["), a = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+function h(t, r, i, e, n) {
+  return `${t ? "export default " : "export "}function ${r}${f(i)}(${u(e)}): ${n};`;
+}
+function m(t) {
+  return `${f(t.typeParameters)}(${u(t.parameters)}): ${t.return.type.text}`;
+}
+function u(t) {
+  if (t === void 0)
+    return "";
+  let r = "";
+  for (let i = 0; i < t.length; ++i) {
+    const e = t[i];
+    e.rest === !0 && (r += "..."), r += e.name, (e.optional === !0 || e.default !== void 0) && (r += "?"), r += `: ${e.type.text}`, i < t.length - 1 && (r += ", ");
+  }
+  return r;
+}
+function b(t, r, i, e, n, o, $, c) {
+  return `${`${t ? "protected " : ""}${r ? "abstract " : i ? "static " : ""}${e ? "readonly " : n ? "accessor " : ""}`}${d($)}${o ? "?" : ""}: ${c};`;
+}
+function A(t, r, i, e, n, o) {
+  const $ = `${t ? "protected " : ""}${r ? "abstract " : ""}${i ? "static " : ""}`, c = d(e), s = o === void 0 ? "" : `
+${$}set ${c}(value: ${o});`;
+  return `${$}get ${c}(): ${n};${s}`;
+}
+function P(t, r, i) {
+  const n = `${t ? "declare " : "export "}const ${r}: ${i};`;
+  return t ? `${n}
+export default ${r};` : n;
+}
+function N(t, r, i, e) {
+  let n = `export type ${t}${f(r)} = `;
+  if (i !== void 0)
+    for (let o = 0; o < i.length; ++o)
+      n += i[o], (o < i.length - 1 || e !== void 0) && (n += `
+  & `);
+  return e !== void 0 && (n += e), n += ";", n;
+}
+export {
+  g as isPropertyEscapeNeeded,
+  d as maybeEscapePropertyName,
+  p as printClass,
+  h as printFunction,
+  A as printGetterSetter,
+  x as printInterface,
+  v as printMethod,
+  b as printProperty,
+  m as printSignature,
+  N as printTypeAlias,
+  f as printTypeParameters,
+  P as printVariable
+};

package/dist/vite/plugin.d.ts

@@ -0,0 +1,53 @@
+import type { Plugin } from "vite";
+import type { ApiExtractorConfig } from "../extractor/config.js";
+import type { ApiExtractor } from "../extractor/ApiExtractor.js";
+
+/** The non-readonly properties can be modified up till Vite's configResolved hook. */
+export interface ApiExtractorPluginConfig {
+  /**
+   * The name of the API Extractor config file to use.
+   * Pass empty string to disable config loading.
+   *
+   * @default "api-extractor.config.ts"
+   */
+  configFilePath?: string;
+  /**
+   * Override the config file. This option is discouraged - specify the options
+   * in the config file as much as possible. The config file is read by ESLint
+   * rules, Astro docs generator, and other tools. For consistent results, use
+   * the same settings everywhere.
+   *
+   * It is safe to use this for setting .afterCreate() hook as long as you don't
+   * mutate the api.json in it.
+   */
+  unsafeConfigOverride?: ApiExtractorConfig;
+  serve?: ApiExtractorPluginServeConfig;
+  /**
+   * A callback for after ApiExtractor instance is created, but before it is
+   * used for any extraction.
+   *
+   * @param extractor
+   */
+  afterExtractorCreated?(extractor: ApiExtractor): void;
+}
+
+export interface ApiExtractorPluginServeConfig {
+  /**
+   * Whether to run the extractor in the Vite dev server. By default, extractor
+   * only runs during build.
+   *
+   * If running during server, ensure your ApiExtractorConfig settings are
+   * serve-appropriate (like fullTypeCheck, whether dtsEmitPath is set, etc).
+   *
+   * @default false
+   */
+  extract?: boolean;
+}
+
+/**
+ * A vite plugin that runs both type checking and api-extractor.
+ * Supports dev server, build, and build watch modes.
+ *
+ * @param pluginConfig
+ */
+export function useApiExtractor(pluginConfig?: ApiExtractorPluginConfig): Plugin;

package/dist/vite/plugin.js

@@ -0,0 +1,107 @@
+import { l as T, m as J } from "../worker-CULPfolw.js";
+import { A as b, w as S } from "../ApiExtractor-BwOcUvPV.js";
+import { p as k, l as A } from "../typeScript-CzUTFiYO.js";
+import { writeFile as C } from "node:fs/promises";
+import { path as w } from "@arcgis/components-build-utils";
+const M = k.name;
+function V(s = {}) {
+  let t = !1, h = !1, e, i, c, l, E = !0, v = !1, f, m, u, y, p;
+  async function x(d, r) {
+    if (r.dtsFiles !== void 0 && u !== "") {
+      const g = w.join(w.resolve(p, u), "/");
+      await S(g, !1, d.changedDtsFiles ?? r.dtsFiles);
+    }
+    y !== "" && await C(
+      y,
+      d.config.context.environment === "production" ? JSON.stringify(r.apiJson) : JSON.stringify(r.apiJson, null, 2)
+    );
+  }
+  return {
+    name: M,
+    async configResolved(d) {
+      if (e = d, t = e.command === "build", !t && s.serve?.extract !== !0)
+        return;
+      h = (t ? e.build.watch : e.server.watch) !== null, p = e.configFile === void 0 ? e.root : w.dirname(e.configFile);
+      const r = {
+        context: {
+          // Handled by Vite
+          emptyDtsEmitPath: !1,
+          environment: e.mode === "production" ? "production" : "development",
+          cwd: p
+        },
+        types: {
+          // It is desirable to type-check as part of build. Thus, we can do
+          // typed extraction essentially for free.
+          typeCheckedExtraction: !0,
+          fullTypeCheck: t,
+          afterDiagnostic(o) {
+            if (o.length > 0 && !h) {
+              const W = new Error("TypeScript errors reported. See error messages above");
+              throw W.stack = "", W;
+            }
+          }
+        },
+        watch: {
+          // Don't clear by default if running inside Vite. Reasons:
+          // Vanilla `vite build --watch` doesn't clear screen on rebuild.
+          // If we clear the screen, we may interfere with another plugin that
+          // does its own logging or clearing. Let user explicitly enable this
+          // if desired.
+          clearScreen: !1,
+          skipWritingUnchanged: d.build.emptyOutDir === !1,
+          onUpdate(o) {
+            f = o.then((n) => (c = n ?? c, f = void 0, clearTimeout(m), t && !v && n !== void 0 && (n.changedModules.length > 0 || n.removedModules.length > 0) && (m = setTimeout(() => {
+              x(i, n);
+            }, 250)), n));
+          }
+        }
+      }, g = s.configFilePath === "" ? void 0 : await T(p, s.configFilePath), P = s.unsafeConfigOverride ?? {}, F = g === void 0 ? r : J(r, g), a = P === void 0 ? F : J(F, P);
+      u = t ? a.context?.dtsEmitPath ?? e.build.outDir : "", y = t ? a.context?.apiJsonEmitPath ?? "" : "";
+      const D = a.context?.logger ?? e.logger ?? console, B = {
+        ...a,
+        context: {
+          ...a.context,
+          dtsEmitPath: "",
+          apiJsonEmitPath: "",
+          logger: {
+            info(o) {
+              !t || o.startsWith(`${A}Wrote `) || D.info(o);
+            },
+            error(o) {
+              D.error(o);
+            }
+          }
+        },
+        types: {
+          ...a.types,
+          forceProduceDts: a.types?.forceProduceDts === !0 || u !== ""
+        }
+      };
+      i = new b(B), s.afterExtractorCreated?.(i);
+    },
+    /**
+     * TypeScript reads files directly from the file system - Vite's
+     * transform hooks have no impact. So we might as well start extraction
+     * early to give other plugins access to api.json sooner.
+     * This is TypeScript's default behavior, and it ensures our build errors
+     * match what "npx tsc" would report.
+     */
+    async buildStart() {
+      v = !0, clearTimeout(m), !(i === void 0 || !E) && (E = !1, h ? l = await i.watch() : c = await i.run());
+    },
+    async writeBundle() {
+      clearTimeout(m), f !== void 0 && await f, i !== void 0 && c !== void 0 && await x(i, c), v = !1;
+    },
+    // Fires if dev server is closed programmatically. Ctrl+C is handled by Node
+    async closeBundle() {
+      !t && l !== void 0 && await l.close();
+    },
+    // Fires if build watch is closed programmatically. Ctrl+C is handled by Node
+    async closeWatcher() {
+      l !== void 0 && await l.close();
+    }
+  };
+}
+export {
+  V as useApiExtractor
+};

package/dist/vite/typeScript.d.ts

@@ -0,0 +1,16 @@
+import type ts from "typescript";
+
+export interface TypeScriptConfigResult {
+  /** Absolute path to the resolved tsconfig.json file. */
+  configPath: string;
+  config: ts.ParsedCommandLine;
+}
+
+/**
+ * @param cwd - Defaults to process.cwd()
+ * @param configPath - Optional absolute or relative path to a tsconfig.json file.
+ * @param resolveIncludedFiles - If true, will resolve tsconfig's include, exclude,
+ * and files globs. Resolved files can be accessed via
+ * TypeScriptConfigResult.config.fileNames.
+ */
+export function loadTypeScriptConfig(cwd: string | undefined, configPath: string | undefined, resolveIncludedFiles: boolean): TypeScriptConfigResult;

package/dist/vite/typeScript.js

@@ -0,0 +1,6 @@
+import "@arcgis/components-build-utils";
+import "typescript";
+import { b as t } from "../typeScript-CzUTFiYO.js";
+export {
+  t as loadTypeScriptConfig
+};