@ttsc/factory 0.15.6 → 0.15.7

package/src/factory/names/createToken.ts

@@ -1,14 +1,25 @@
-import type { Token } from "../../ast";
-import { SyntaxKind } from "../../syntax";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link Token}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param token The token.
- * @returns The created {@link Token}.
- */
-export const createToken = <TKind extends SyntaxKind>(
-  token: TKind,
-): Token<TKind> => make("Token", { token }) as Token<TKind>;
+import type { Token } from "../../ast";
+import { SyntaxKind } from "../../syntax";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link Token}: a node that wraps a single {@link SyntaxKind}.
+ *
+ * The `token` is the syntax kind to wrap, such as a punctuation or keyword
+ * kind. The printer emits the source spelling tied to that kind, so a question
+ * mark token prints as `?` and a keyword token prints as its keyword. The
+ * generic `TKind` flows through to the result type for type-safe consumers.
+ *
+ * With `token` of the question-mark kind, this prints:
+ *
+ * ```ts
+ * ?
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param token The token.
+ * @returns The created {@link Token}.
+ */
+export const createToken = <TKind extends SyntaxKind>(
+  token: TKind,
+): Token<TKind> => make("Token", { token }) as Token<TKind>;

package/src/factory/names/createTrue.ts

@@ -1,11 +1,20 @@
-import type { Token } from "../../ast";
-import { SyntaxKind } from "../../syntax";
-import { createToken } from "./createToken";
-
-/**
- * Create a {@link Token}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @returns The created {@link Token}.
- */
-export const createTrue = (): Token => createToken(SyntaxKind.TrueKeyword);
+import type { Token } from "../../ast";
+import { SyntaxKind } from "../../syntax";
+import { createToken } from "./createToken";
+
+/**
+ * Create the `true` keyword as a {@link Token}.
+ *
+ * This takes no arguments and wraps the `TrueKeyword` syntax kind. The printer
+ * emits the keyword as the boolean literal `true`.
+ *
+ * This prints:
+ *
+ * ```ts
+ * true;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @returns The created {@link Token}.
+ */
+export const createTrue = (): Token => createToken(SyntaxKind.TrueKeyword);

package/src/factory/names/createUniqueName.ts

@@ -0,0 +1,35 @@
+import type { Identifier } from "../../ast";
+import { createIdentifier } from "./createIdentifier";
+
+/**
+ * Create a unique identifier name as a plain {@link Identifier}.
+ *
+ * The legacy compiler uses a stateful name generator that guarantees the
+ * returned identifier is unique within its scope. This package is stateless, so
+ * this is a simplified placeholder: it does not guarantee uniqueness, it just
+ * returns the given `text` with the optional `prefix` and `suffix` wrapped
+ * around it.
+ *
+ * The `flags` parameter belongs to the stateful generator and is accepted for
+ * signature parity but ignored. Two calls with the same arguments produce the
+ * same name, so the caller is responsible for avoiding collisions.
+ *
+ * With `text` of `base` and no prefix or suffix, this prints:
+ *
+ * ```ts
+ * base;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param text The base name text.
+ * @param _flags Ignored; kept for signature parity.
+ * @param prefix An optional name prefix.
+ * @param suffix An optional name suffix.
+ * @returns The created {@link Identifier}.
+ */
+export const createUniqueName = (
+  text: string,
+  _flags?: number,
+  prefix?: string,
+  suffix?: string,
+): Identifier => createIdentifier(`${prefix ?? ""}${text}${suffix ?? ""}`);

package/src/factory/names/createUniquePrivateName.ts

@@ -0,0 +1,34 @@
+import type { PrivateIdentifier } from "../../ast";
+import { createPrivateIdentifier } from "./createPrivateIdentifier";
+
+/**
+ * Create a unique private identifier name as a plain {@link PrivateIdentifier}.
+ *
+ * The legacy compiler uses a stateful name generator that guarantees the
+ * returned private identifier is unique within its scope. This package is
+ * stateless, so this is a simplified placeholder: it does not guarantee
+ * uniqueness, it assembles a name from the optional `prefix`, the `text` (or
+ * the fallback `_unique` when omitted), and the optional `suffix`, then
+ * delegates to {@link createPrivateIdentifier}. Any leading `#` on `text` is
+ * stripped first so the delegate adds exactly one.
+ *
+ * With no arguments, the fallback applies and this prints:
+ *
+ * ```ts
+ * #_unique;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param text The base name text, if any.
+ * @param prefix An optional name prefix.
+ * @param suffix An optional name suffix.
+ * @returns The created {@link PrivateIdentifier}.
+ */
+export const createUniquePrivateName = (
+  text?: string,
+  prefix?: string,
+  suffix?: string,
+): PrivateIdentifier =>
+  createPrivateIdentifier(
+    `#${prefix ?? ""}${text ? text.replace(/^#/, "") : "_unique"}${suffix ?? ""}`,
+  );

package/src/factory/statements/createBlock.ts

@@ -1,15 +1,30 @@
-import type { Block, Statement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link Block}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param statements The statements.
- * @param multiLine When `true`, print one entry per line.
- * @returns The created {@link Block}.
- */
-export const createBlock = (
-  statements: readonly Statement[],
-  multiLine?: boolean,
-): Block => make("Block", { statements, multiLine: multiLine ?? true });
+import type { Block, Statement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link Block}: a `{ ... }` statement block.
+ *
+ * The `statements` become the body, in order. The `multiLine` flag controls how
+ * the printer lays the block out: when `true` (the default here), each
+ * statement sits on its own indented line between braces; when `false`, the
+ * printer keeps the body compact on a single line.
+ *
+ * With `statements` printing `a()` and `b()` and `multiLine` left at its
+ * default, the result is:
+ *
+ * ```ts
+ * {
+ *   a();
+ *   b();
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param statements The statements.
+ * @param multiLine When `true`, print one entry per line.
+ * @returns The created {@link Block}.
+ */
+export const createBlock = (
+  statements: readonly Statement[],
+  multiLine?: boolean,
+): Block => make("Block", { statements, multiLine: multiLine ?? true });

package/src/factory/statements/createBreakStatement.ts

@@ -1,17 +1,32 @@
-import type { BreakStatement, Identifier } from "../../ast";
-import { asName } from "../internal/asName";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link BreakStatement}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param label The label.
- * @returns The created {@link BreakStatement}.
- */
-export const createBreakStatement = (
-  label?: string | Identifier,
-): BreakStatement =>
-  make("BreakStatement", {
-    label: label === undefined ? undefined : asName(label),
-  });
+import type { BreakStatement, Identifier } from "../../ast";
+import { asName } from "../internal/asName";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link BreakStatement}: a `break;` statement.
+ *
+ * The optional `label` names an enclosing labeled statement to break out of. A
+ * string is wrapped into an identifier; pass nothing for a plain `break`.
+ *
+ * With no label the result is:
+ *
+ * ```ts
+ * break;
+ * ```
+ *
+ * With `label` of `outer` the result is:
+ *
+ * ```ts
+ * break outer;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param label The label.
+ * @returns The created {@link BreakStatement}.
+ */
+export const createBreakStatement = (
+  label?: string | Identifier,
+): BreakStatement =>
+  make("BreakStatement", {
+    label: label === undefined ? undefined : asName(label),
+  });

package/src/factory/statements/createCaseBlock.ts

@@ -1,13 +1,30 @@
-import type { CaseBlock, CaseOrDefaultClause } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link CaseBlock}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param clauses The clauses.
- * @returns The created {@link CaseBlock}.
- */
-export const createCaseBlock = (
-  clauses: readonly CaseOrDefaultClause[],
-): CaseBlock => make("CaseBlock", { clauses });
+import type { CaseBlock, CaseOrDefaultClause } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link CaseBlock}: the braced body of a switch statement.
+ *
+ * The `clauses` are the `case` and `default` arms, printed in the given order
+ * between braces. This is the body you hand to {@link createSwitchStatement}; on
+ * its own it carries no switch subject.
+ *
+ * With `clauses` of a `case 1:` arm (calling `a()` then `break`) and a
+ * `default:` arm (calling `b()`), the result is:
+ *
+ * ```ts
+ * {
+ *   case 1:
+ *     a();
+ *     break;
+ *   default:
+ *     b();
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param clauses The clauses.
+ * @returns The created {@link CaseBlock}.
+ */
+export const createCaseBlock = (
+  clauses: readonly CaseOrDefaultClause[],
+): CaseBlock => make("CaseBlock", { clauses });

package/src/factory/statements/createCaseClause.ts

@@ -1,15 +1,29 @@
-import type { CaseClause, Expression, Statement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link CaseClause}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param expression The expression.
- * @param statements The statements.
- * @returns The created {@link CaseClause}.
- */
-export const createCaseClause = (
-  expression: Expression,
-  statements: readonly Statement[],
-): CaseClause => make("CaseClause", { expression, statements });
+import type { CaseClause, Expression, Statement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link CaseClause}: one `case ...:` arm of a switch.
+ *
+ * The `expression` is the value matched against the switch subject, and
+ * `statements` is the body that runs on a match. Fall-through is the default,
+ * so include an explicit `break` in `statements` when you want the arm to
+ * stop.
+ *
+ * With `expression` of `1` and `statements` of `a()` followed by a `break`, the
+ * result is:
+ *
+ * ```ts
+ * case 1:
+ *   a();
+ *   break;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param expression The expression.
+ * @param statements The statements.
+ * @returns The created {@link CaseClause}.
+ */
+export const createCaseClause = (
+  expression: Expression,
+  statements: readonly Statement[],
+): CaseClause => make("CaseClause", { expression, statements });

package/src/factory/statements/createCatchClause.ts

@@ -1,28 +1,43 @@
-import type { Block, CatchClause, VariableDeclaration } from "../../ast";
-import { make } from "../internal/make";
-import { createVariableDeclaration } from "./createVariableDeclaration";
-
-/**
- * Create a {@link CatchClause}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param variableDeclaration The variableDeclaration.
- * @param block The block.
- * @returns The created {@link CatchClause}.
- */
-export const createCatchClause = (
-  variableDeclaration: string | VariableDeclaration | undefined,
-  block: Block,
-): CatchClause =>
-  make("CatchClause", {
-    variableDeclaration:
-      typeof variableDeclaration === "string"
-        ? createVariableDeclaration(
-            variableDeclaration,
-            undefined,
-            undefined,
-            undefined,
-          )
-        : variableDeclaration,
-    block,
-  });
+import type { Block, CatchClause, VariableDeclaration } from "../../ast";
+import { make } from "../internal/make";
+import { createVariableDeclaration } from "./createVariableDeclaration";
+
+/**
+ * Create a {@link CatchClause}: the `catch (...) { ... }` arm of a try.
+ *
+ * The `variableDeclaration` binds the caught value. Pass a string for the
+ * common `catch (e)` case and it is turned into a bare binding; pass a full
+ * {@link VariableDeclaration} when you need a type or destructuring pattern;
+ * pass `undefined` for the binding-less `catch { ... }` form. The `block` is
+ * the handler body.
+ *
+ * With `variableDeclaration` of `e` and a `block` calling `handle(e)`, the
+ * result is:
+ *
+ * ```ts
+ * catch (e) {
+ *   handle(e);
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param variableDeclaration The variableDeclaration.
+ * @param block The block.
+ * @returns The created {@link CatchClause}.
+ */
+export const createCatchClause = (
+  variableDeclaration: string | VariableDeclaration | undefined,
+  block: Block,
+): CatchClause =>
+  make("CatchClause", {
+    variableDeclaration:
+      typeof variableDeclaration === "string"
+        ? createVariableDeclaration(
+            variableDeclaration,
+            undefined,
+            undefined,
+            undefined,
+          )
+        : variableDeclaration,
+    block,
+  });

package/src/factory/statements/createContinueStatement.ts

@@ -1,17 +1,32 @@
-import type { ContinueStatement, Identifier } from "../../ast";
-import { asName } from "../internal/asName";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link ContinueStatement}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param label The label.
- * @returns The created {@link ContinueStatement}.
- */
-export const createContinueStatement = (
-  label?: string | Identifier,
-): ContinueStatement =>
-  make("ContinueStatement", {
-    label: label === undefined ? undefined : asName(label),
-  });
+import type { ContinueStatement, Identifier } from "../../ast";
+import { asName } from "../internal/asName";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link ContinueStatement}: a `continue;` statement.
+ *
+ * The optional `label` names an enclosing labeled loop to continue. A string is
+ * wrapped into an identifier; pass nothing for a plain `continue`.
+ *
+ * With no label the result is:
+ *
+ * ```ts
+ * continue;
+ * ```
+ *
+ * With `label` of `outer` the result is:
+ *
+ * ```ts
+ * continue outer;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param label The label.
+ * @returns The created {@link ContinueStatement}.
+ */
+export const createContinueStatement = (
+  label?: string | Identifier,
+): ContinueStatement =>
+  make("ContinueStatement", {
+    label: label === undefined ? undefined : asName(label),
+  });

package/src/factory/statements/createDebuggerStatement.ts

@@ -1,11 +1,20 @@
-import type { DebuggerStatement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link DebuggerStatement}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @returns The created {@link DebuggerStatement}.
- */
-export const createDebuggerStatement = (): DebuggerStatement =>
-  make("DebuggerStatement", {});
+import type { DebuggerStatement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link DebuggerStatement}: a `debugger;` statement.
+ *
+ * The statement takes no inputs and triggers a breakpoint when a debugger is
+ * attached.
+ *
+ * The result is always:
+ *
+ * ```ts
+ * debugger;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @returns The created {@link DebuggerStatement}.
+ */
+export const createDebuggerStatement = (): DebuggerStatement =>
+  make("DebuggerStatement", {});

package/src/factory/statements/createDefaultClause.ts

@@ -1,13 +1,24 @@
-import type { DefaultClause, Statement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link DefaultClause}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param statements The statements.
- * @returns The created {@link DefaultClause}.
- */
-export const createDefaultClause = (
-  statements: readonly Statement[],
-): DefaultClause => make("DefaultClause", { statements });
+import type { DefaultClause, Statement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link DefaultClause}: the `default:` arm of a switch.
+ *
+ * The `statements` form the body that runs when no `case` matches. As with
+ * `case` arms, fall-through is the default, so add an explicit `break` when the
+ * arm should stop.
+ *
+ * With `statements` of a single `b()` call, the result is:
+ *
+ * ```ts
+ * default:
+ *   b();
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param statements The statements.
+ * @returns The created {@link DefaultClause}.
+ */
+export const createDefaultClause = (
+  statements: readonly Statement[],
+): DefaultClause => make("DefaultClause", { statements });

package/src/factory/statements/createDoStatement.ts

@@ -1,15 +1,28 @@
-import type { DoStatement, Expression, Statement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link DoStatement}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param statement The statement.
- * @param expression The expression.
- * @returns The created {@link DoStatement}.
- */
-export const createDoStatement = (
-  statement: Statement,
-  expression: Expression,
-): DoStatement => make("DoStatement", { statement, expression });
+import type { DoStatement, Expression, Statement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link DoStatement}: a `do ... while (...)` loop.
+ *
+ * The `statement` is the loop body and `expression` is the condition tested
+ * after each pass, so the body always runs at least once. Note the argument
+ * order: the body comes before the condition, matching the source layout.
+ *
+ * With a `statement` block calling `a()` and an `expression` of `cond`, the
+ * result is:
+ *
+ * ```ts
+ * do {
+ *   a();
+ * } while (cond);
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param statement The statement.
+ * @param expression The expression.
+ * @returns The created {@link DoStatement}.
+ */
+export const createDoStatement = (
+  statement: Statement,
+  expression: Expression,
+): DoStatement => make("DoStatement", { statement, expression });

package/src/factory/statements/createEmptyStatement.ts

@@ -1,11 +1,20 @@
-import type { EmptyStatement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link EmptyStatement}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @returns The created {@link EmptyStatement}.
- */
-export const createEmptyStatement = (): EmptyStatement =>
-  make("EmptyStatement", {});
+import type { EmptyStatement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link EmptyStatement}: a lone `;` statement.
+ *
+ * The statement takes no inputs and does nothing. It is the empty body you
+ * reach for when a loop or branch needs a statement but no work, such as `for
+ * (; cond; );`.
+ *
+ * The result is a single semicolon:
+ *
+ * ```ts
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @returns The created {@link EmptyStatement}.
+ */
+export const createEmptyStatement = (): EmptyStatement =>
+  make("EmptyStatement", {});

package/src/factory/statements/createExpressionStatement.ts

@@ -1,13 +1,23 @@
-import type { Expression, ExpressionStatement } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link ExpressionStatement}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param expression The expression.
- * @returns The created {@link ExpressionStatement}.
- */
-export const createExpressionStatement = (
-  expression: Expression,
-): ExpressionStatement => make("ExpressionStatement", { expression });
+import type { Expression, ExpressionStatement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link ExpressionStatement}: an expression used as a statement.
+ *
+ * The `expression` is evaluated for its effect and the printer terminates it
+ * with a semicolon. This is how a call, assignment, or similar expression
+ * becomes a standalone statement.
+ *
+ * With `expression` of a `doThing(a)` call, the result is:
+ *
+ * ```ts
+ * doThing(a);
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param expression The expression.
+ * @returns The created {@link ExpressionStatement}.
+ */
+export const createExpressionStatement = (
+  expression: Expression,
+): ExpressionStatement => make("ExpressionStatement", { expression });