@ttsc/factory 0.15.6 → 0.15.7

package/src/factory/types/createUnionTypeNode.ts

@@ -1,13 +1,24 @@
-import type { TypeNode, UnionTypeNode } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link UnionTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param types The constituent types.
- * @returns The created {@link UnionTypeNode}.
- */
-export const createUnionTypeNode = (
-  types: readonly TypeNode[],
-): UnionTypeNode => make("UnionTypeNode", { types });
+import type { TypeNode, UnionTypeNode } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link UnionTypeNode}: an `A | B` type.
+ *
+ * The constituents are joined with `|`. The printer is width-aware: when the
+ * whole union fits on one line it stays inline as `A | B`, and when it has to
+ * break it indents and puts each constituent on its own line with a leading
+ * `|`, including a leading `|` before the first member.
+ *
+ * Given the constituents `string` and `number`, the printer renders:
+ *
+ * ```ts
+ * string | number;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param types The constituent types.
+ * @returns The created {@link UnionTypeNode}.
+ */
+export const createUnionTypeNode = (
+  types: readonly TypeNode[],
+): UnionTypeNode => make("UnionTypeNode", { types });

package/src/index.ts

@@ -1,30 +1,40 @@
-/**
- * Hand-written, dependency-free re-implementation of the legacy TypeScript AST
- * factory (`ts.factory`) and printer (`ts.Printer`).
- *
- * ```typescript
- * import factory, { SyntaxKind, TsPrinter } from "@ttsc/factory";
- * ```
- *
- * - `factory` — the node factory namespace (also the default export).
- * - {@link TsPrinter} — renders factory nodes to TypeScript source text.
- * - {@link SyntaxKind} / {@link NodeFlags} — token & flag enums.
- * - Outline AST types (`Expression`, `Statement`, `TypeNode`, ...).
- *
- * No `typescript` module is imported anywhere; the logic is implemented
- * directly, so this keeps working in the TypeScript-Go (tsgo) era.
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export * as factory from "./factory/index";
-export { SyntaxKind, NodeFlags, tokenToString } from "./syntax";
-export { TsPrinter } from "./TsPrinter";
-export type { TsPrinterOptions } from "./TsPrinter";
-export type * from "./ast";
-
-import * as factory from "./factory/index";
-
-/** Outline of the legacy `ts.NodeFactory`. */
-export type NodeFactory = typeof factory;
-
-export default factory;
+import * as factory from "./factory/index";
+
+/**
+ * Hand-written, dependency-free re-implementation of the legacy TypeScript AST
+ * factory (`ts.factory`) and printer (`ts.Printer`).
+ *
+ * ```typescript
+ * import factory, { SyntaxKind, TsPrinter } from "@ttsc/factory";
+ * ```
+ *
+ * - `factory` — the node factory namespace (also the default export).
+ * - {@link TsPrinter} — renders factory nodes to TypeScript source text.
+ * - {@link SyntaxKind} / {@link NodeFlags} — token & flag enums.
+ * - {@link addSyntheticLeadingComment} — attach `//` / `/* *\/` comments.
+ * - Outline AST types (`Expression`, `Statement`, `TypeNode`, ...).
+ *
+ * No `typescript` module is imported anywhere; the logic is implemented
+ * directly, so this keeps working in the TypeScript-Go (tsgo) era.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export * as factory from "./factory/index";
+export { SyntaxKind, NodeFlags } from "./syntax";
+export { TsPrinter } from "./TsPrinter";
+export type { TsPrinterOptions } from "./TsPrinter";
+export {
+  addSyntheticLeadingComment,
+  addSyntheticTrailingComment,
+  getSyntheticLeadingComments,
+  getSyntheticTrailingComments,
+  setSyntheticLeadingComments,
+  setSyntheticTrailingComments,
+} from "./comments";
+export type { SynthesizedComment } from "./comments";
+export type * from "./ast";
+
+/** Outline of the legacy `ts.NodeFactory`. */
+export type NodeFactory = typeof factory;
+
+export default factory;

package/src/internal/doc.ts

@@ -1,195 +1,195 @@
-/**
- * Internal Wadler/Prettier-style pretty-printing engine.
- *
- * {@link TsPrinter} builds a {@link Doc} (an intermediate representation) per
- * node instead of concatenating strings, then {@link printDocToString} lays it
- * out against a print width: each {@link group} prints flat when it fits on the
- * current line and breaks otherwise — the same algorithm Prettier uses.
- *
- * This module is internal; it is not part of the public `@ttsc/factory` API.
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export type Doc =
-  | string
-  | { type: "concat"; parts: Doc[] }
-  | { type: "line" }
-  | { type: "softline" }
-  | { type: "hardline" }
-  | { type: "indent"; doc: Doc }
-  | { type: "group"; doc: Doc; break: boolean }
-  | { type: "ifBreak"; broken: Doc; flat: Doc };
-
-/** Concatenate documents. */
-export const concat = (parts: Doc[]): Doc => ({ type: "concat", parts });
-/** A group: printed flat when it fits, broken otherwise. */
-export const group = (doc: Doc, shouldBreak: boolean = false): Doc => ({
-  type: "group",
-  doc,
-  break: shouldBreak,
-});
-/** Increase indentation of the inner document by one level. */
-export const indent = (doc: Doc): Doc => ({ type: "indent", doc });
-/** A space when flat, a newline when broken. */
-export const line: Doc = { type: "line" };
-/** Nothing when flat, a newline when broken. */
-export const softline: Doc = { type: "softline" };
-/** Always a newline; forces every enclosing group to break. */
-export const hardline: Doc = { type: "hardline" };
-/** Print `broken` when the enclosing group breaks, `flat` otherwise. */
-export const ifBreak = (broken: Doc, flat: Doc = ""): Doc => ({
-  type: "ifBreak",
-  broken,
-  flat,
-});
-/** Interleave `items` with `separator`. */
-export const join = (separator: Doc, items: Doc[]): Doc => {
-  const parts: Doc[] = [];
-  items.forEach((item, i) => {
-    if (i !== 0) parts.push(separator);
-    parts.push(item);
-  });
-  return concat(parts);
-};
-
-const MODE_BREAK = 1;
-const MODE_FLAT = 2;
-type Cmd = [number, number, Doc];
-
-/** Mark every group that (transitively) contains a hardline as broken. */
-const propagateBreaks = (doc: Doc): boolean => {
-  if (typeof doc === "string") return false;
-  switch (doc.type) {
-    case "concat": {
-      let broke = false;
-      for (const part of doc.parts) broke = propagateBreaks(part) || broke;
-      return broke;
-    }
-    case "indent":
-      return propagateBreaks(doc.doc);
-    case "group": {
-      const broke = propagateBreaks(doc.doc);
-      doc.break = doc.break || broke;
-      return doc.break;
-    }
-    case "ifBreak":
-      propagateBreaks(doc.broken);
-      propagateBreaks(doc.flat);
-      return false;
-    case "hardline":
-      return true;
-    default:
-      return false;
-  }
-};
-
-/** Does `next` (followed by `rest`) fit flat within `remaining` columns? */
-const fits = (next: Cmd, rest: readonly Cmd[], remaining: number): boolean => {
-  let width = remaining;
-  const cmds: Cmd[] = [next];
-  let restIndex = rest.length;
-  while (width >= 0) {
-    if (cmds.length === 0) {
-      if (restIndex === 0) return true;
-      cmds.push(rest[--restIndex]!);
-      continue;
-    }
-    const [ind, mode, doc] = cmds.pop()!;
-    if (typeof doc === "string") {
-      width -= doc.length;
-      continue;
-    }
-    switch (doc.type) {
-      case "concat":
-        for (let i = doc.parts.length - 1; i >= 0; i--)
-          cmds.push([ind, mode, doc.parts[i]!]);
-        break;
-      case "indent":
-        cmds.push([ind + 1, mode, doc.doc]);
-        break;
-      case "group":
-        cmds.push([ind, doc.break ? MODE_BREAK : mode, doc.doc]);
-        break;
-      case "ifBreak":
-        cmds.push([ind, mode, mode === MODE_BREAK ? doc.broken : doc.flat]);
-        break;
-      case "line":
-        if (mode === MODE_FLAT) width -= 1;
-        else return true;
-        break;
-      case "softline":
-        if (mode !== MODE_FLAT) return true;
-        break;
-      case "hardline":
-        return true;
-    }
-  }
-  return false;
-};
-
-/** Options for {@link printDocToString}. */
-export interface PrintDocOptions {
-  printWidth: number;
-  newLine: string;
-  indent: string;
-}
-
-/** Lay a {@link Doc} out into source text. */
-export const printDocToString = (
-  doc: Doc,
-  options: PrintDocOptions,
-): string => {
-  propagateBreaks(doc);
-  const { printWidth, newLine, indent: tab } = options;
-  const out: string[] = [];
-  let pos = 0;
-  const cmds: Cmd[] = [[0, MODE_BREAK, doc]];
-  const newlineTo = (ind: number): void => {
-    if (out.length)
-      out[out.length - 1] = out[out.length - 1]!.replace(/[ \t]+$/, "");
-    out.push(newLine + tab.repeat(ind));
-    pos = tab.length * ind;
-  };
-  while (cmds.length) {
-    const [ind, mode, d] = cmds.pop()!;
-    if (typeof d === "string") {
-      out.push(d);
-      pos += d.length;
-      continue;
-    }
-    switch (d.type) {
-      case "concat":
-        for (let i = d.parts.length - 1; i >= 0; i--)
-          cmds.push([ind, mode, d.parts[i]!]);
-        break;
-      case "indent":
-        cmds.push([ind + 1, mode, d.doc]);
-        break;
-      case "group":
-        if (mode === MODE_FLAT && !d.break) cmds.push([ind, MODE_FLAT, d.doc]);
-        else if (
-          !d.break &&
-          fits([ind, MODE_FLAT, d.doc], cmds, printWidth - pos)
-        )
-          cmds.push([ind, MODE_FLAT, d.doc]);
-        else cmds.push([ind, MODE_BREAK, d.doc]);
-        break;
-      case "ifBreak":
-        cmds.push([ind, mode, mode === MODE_BREAK ? d.broken : d.flat]);
-        break;
-      case "line":
-        if (mode === MODE_FLAT) {
-          out.push(" ");
-          pos += 1;
-        } else newlineTo(ind);
-        break;
-      case "softline":
-        if (mode !== MODE_FLAT) newlineTo(ind);
-        break;
-      case "hardline":
-        newlineTo(ind);
-        break;
-    }
-  }
-  return out.join("");
-};
+/**
+ * Internal Wadler/Prettier-style pretty-printing engine.
+ *
+ * {@link TsPrinter} builds a {@link Doc} (an intermediate representation) per
+ * node instead of concatenating strings, then {@link printDocToString} lays it
+ * out against a print width: each {@link group} prints flat when it fits on the
+ * current line and breaks otherwise — the same algorithm Prettier uses.
+ *
+ * This module is internal; it is not part of the public `@ttsc/factory` API.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type Doc =
+  | string
+  | { type: "concat"; parts: Doc[] }
+  | { type: "line" }
+  | { type: "softline" }
+  | { type: "hardline" }
+  | { type: "indent"; doc: Doc }
+  | { type: "group"; doc: Doc; break: boolean }
+  | { type: "ifBreak"; broken: Doc; flat: Doc };
+
+/** Concatenate documents. */
+export const concat = (parts: Doc[]): Doc => ({ type: "concat", parts });
+/** A group: printed flat when it fits, broken otherwise. */
+export const group = (doc: Doc, shouldBreak: boolean = false): Doc => ({
+  type: "group",
+  doc,
+  break: shouldBreak,
+});
+/** Increase indentation of the inner document by one level. */
+export const indent = (doc: Doc): Doc => ({ type: "indent", doc });
+/** A space when flat, a newline when broken. */
+export const line: Doc = { type: "line" };
+/** Nothing when flat, a newline when broken. */
+export const softline: Doc = { type: "softline" };
+/** Always a newline; forces every enclosing group to break. */
+export const hardline: Doc = { type: "hardline" };
+/** Print `broken` when the enclosing group breaks, `flat` otherwise. */
+export const ifBreak = (broken: Doc, flat: Doc = ""): Doc => ({
+  type: "ifBreak",
+  broken,
+  flat,
+});
+/** Interleave `items` with `separator`. */
+export const join = (separator: Doc, items: Doc[]): Doc => {
+  const parts: Doc[] = [];
+  items.forEach((item, i) => {
+    if (i !== 0) parts.push(separator);
+    parts.push(item);
+  });
+  return concat(parts);
+};
+
+const MODE_BREAK = 1;
+const MODE_FLAT = 2;
+type Cmd = [number, number, Doc];
+
+/** Mark every group that (transitively) contains a hardline as broken. */
+const propagateBreaks = (doc: Doc): boolean => {
+  if (typeof doc === "string") return false;
+  switch (doc.type) {
+    case "concat": {
+      let broke = false;
+      for (const part of doc.parts) broke = propagateBreaks(part) || broke;
+      return broke;
+    }
+    case "indent":
+      return propagateBreaks(doc.doc);
+    case "group": {
+      const broke = propagateBreaks(doc.doc);
+      doc.break = doc.break || broke;
+      return doc.break;
+    }
+    case "ifBreak":
+      propagateBreaks(doc.broken);
+      propagateBreaks(doc.flat);
+      return false;
+    case "hardline":
+      return true;
+    default:
+      return false;
+  }
+};
+
+/** Does `next` (followed by `rest`) fit flat within `remaining` columns? */
+const fits = (next: Cmd, rest: readonly Cmd[], remaining: number): boolean => {
+  let width = remaining;
+  const cmds: Cmd[] = [next];
+  let restIndex = rest.length;
+  while (width >= 0) {
+    if (cmds.length === 0) {
+      if (restIndex === 0) return true;
+      cmds.push(rest[--restIndex]!);
+      continue;
+    }
+    const [ind, mode, doc] = cmds.pop()!;
+    if (typeof doc === "string") {
+      width -= doc.length;
+      continue;
+    }
+    switch (doc.type) {
+      case "concat":
+        for (let i = doc.parts.length - 1; i >= 0; i--)
+          cmds.push([ind, mode, doc.parts[i]!]);
+        break;
+      case "indent":
+        cmds.push([ind + 1, mode, doc.doc]);
+        break;
+      case "group":
+        cmds.push([ind, doc.break ? MODE_BREAK : mode, doc.doc]);
+        break;
+      case "ifBreak":
+        cmds.push([ind, mode, mode === MODE_BREAK ? doc.broken : doc.flat]);
+        break;
+      case "line":
+        if (mode === MODE_FLAT) width -= 1;
+        else return true;
+        break;
+      case "softline":
+        if (mode !== MODE_FLAT) return true;
+        break;
+      case "hardline":
+        return true;
+    }
+  }
+  return false;
+};
+
+/** Options for {@link printDocToString}. */
+export interface PrintDocOptions {
+  printWidth: number;
+  newLine: string;
+  indent: string;
+}
+
+/** Lay a {@link Doc} out into source text. */
+export const printDocToString = (
+  doc: Doc,
+  options: PrintDocOptions,
+): string => {
+  propagateBreaks(doc);
+  const { printWidth, newLine, indent: tab } = options;
+  const out: string[] = [];
+  let pos = 0;
+  const cmds: Cmd[] = [[0, MODE_BREAK, doc]];
+  const newlineTo = (ind: number): void => {
+    if (out.length)
+      out[out.length - 1] = out[out.length - 1]!.replace(/[ \t]+$/, "");
+    out.push(newLine + tab.repeat(ind));
+    pos = tab.length * ind;
+  };
+  while (cmds.length) {
+    const [ind, mode, d] = cmds.pop()!;
+    if (typeof d === "string") {
+      out.push(d);
+      pos += d.length;
+      continue;
+    }
+    switch (d.type) {
+      case "concat":
+        for (let i = d.parts.length - 1; i >= 0; i--)
+          cmds.push([ind, mode, d.parts[i]!]);
+        break;
+      case "indent":
+        cmds.push([ind + 1, mode, d.doc]);
+        break;
+      case "group":
+        if (mode === MODE_FLAT && !d.break) cmds.push([ind, MODE_FLAT, d.doc]);
+        else if (
+          !d.break &&
+          fits([ind, MODE_FLAT, d.doc], cmds, printWidth - pos)
+        )
+          cmds.push([ind, MODE_FLAT, d.doc]);
+        else cmds.push([ind, MODE_BREAK, d.doc]);
+        break;
+      case "ifBreak":
+        cmds.push([ind, mode, mode === MODE_BREAK ? d.broken : d.flat]);
+        break;
+      case "line":
+        if (mode === MODE_FLAT) {
+          out.push(" ");
+          pos += 1;
+        } else newlineTo(ind);
+        break;
+      case "softline":
+        if (mode !== MODE_FLAT) newlineTo(ind);
+        break;
+      case "hardline":
+        newlineTo(ind);
+        break;
+    }
+  }
+  return out.join("");
+};

package/src/syntax/NodeFlags.ts

@@ -1,12 +1,19 @@
-/**
- * Flags for {@link factory.createVariableDeclarationList}.
- *
- * Outline of the relevant subset of the legacy `ts.NodeFlags`.
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export enum NodeFlags {
-  None = 0,
-  Let = 1,
-  Const = 2,
-}
+/**
+ * Flags for {@link factory.createVariableDeclarationList} and
+ * {@link factory.createModuleDeclaration}.
+ *
+ * An outline of the relevant subset of the legacy `ts.NodeFlags`. Each member's
+ * value is the keyword it implies (`Let = "let"`, `Const = "const"`), so the
+ * printer reads it directly. `Namespace` is accepted for API parity — the
+ * printer renders the `module` / `namespace` keyword from the module name kind,
+ * not from this flag. A string-valued `const enum`, so references inline with
+ * no runtime object.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export const enum NodeFlags {
+  None = "",
+  Let = "let",
+  Const = "const",
+  Namespace = "namespace",
+}