@ttsc/factory 0.15.6 → 0.15.8

package/src/factory/types/createIndexSignature.ts

@@ -1,23 +1,33 @@
-import type {
-  IndexSignatureDeclaration,
-  ModifierLike,
-  ParameterDeclaration,
-  TypeNode,
-} from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link IndexSignatureDeclaration}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param modifiers The leading modifiers and decorators, if any.
- * @param parameters The parameters.
- * @param type The type.
- * @returns The created {@link IndexSignatureDeclaration}.
- */
-export const createIndexSignature = (
-  modifiers: readonly ModifierLike[] | undefined,
-  parameters: readonly ParameterDeclaration[],
-  type: TypeNode,
-): IndexSignatureDeclaration =>
-  make("IndexSignature", { modifiers, parameters, type });
+import type {
+  IndexSignatureDeclaration,
+  ModifierLike,
+  ParameterDeclaration,
+  TypeNode,
+} from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link IndexSignatureDeclaration}: a `[key: K]: V` index signature.
+ *
+ * Any modifiers print first (for example `readonly`), then the single key
+ * parameter inside `[...]`, then `: ` followed by the value type.
+ *
+ * Given no modifiers, a `key: string` parameter, and a `number` value type, the
+ * printer renders:
+ *
+ * ```ts
+ * [key: string]: number
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param modifiers The leading modifiers and decorators, if any.
+ * @param parameters The index parameter list.
+ * @param type The value type.
+ * @returns The created {@link IndexSignatureDeclaration}.
+ */
+export const createIndexSignature = (
+  modifiers: readonly ModifierLike[] | undefined,
+  parameters: readonly ParameterDeclaration[],
+  type: TypeNode,
+): IndexSignatureDeclaration =>
+  make("IndexSignature", { modifiers, parameters, type });

package/src/factory/types/createIndexedAccessTypeNode.ts

@@ -1,16 +1,27 @@
-import type { IndexedAccessTypeNode, TypeNode } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link IndexedAccessTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param objectType The object type.
- * @param indexType The index type.
- * @returns The created {@link IndexedAccessTypeNode}.
- */
-export const createIndexedAccessTypeNode = (
-  objectType: TypeNode,
-  indexType: TypeNode,
-): IndexedAccessTypeNode =>
-  make("IndexedAccessTypeNode", { objectType, indexType });
+import type { IndexedAccessTypeNode, TypeNode } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link IndexedAccessTypeNode}: a `T[K]` indexed access type.
+ *
+ * The object type is emitted in postfix-operand position, so a lower-precedence
+ * form (union, intersection, function, constructor, conditional, infer, or
+ * type-operator) gets wrapped in parentheses before the `[...]`. The index type
+ * prints bare inside the brackets.
+ *
+ * Given a `T` object type and a `"key"` index, the printer renders:
+ *
+ * ```ts
+ * T["key"];
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param objectType The object type being indexed.
+ * @param indexType The index type.
+ * @returns The created {@link IndexedAccessTypeNode}.
+ */
+export const createIndexedAccessTypeNode = (
+  objectType: TypeNode,
+  indexType: TypeNode,
+): IndexedAccessTypeNode =>
+  make("IndexedAccessTypeNode", { objectType, indexType });

package/src/factory/types/createInferTypeNode.ts

@@ -1,13 +1,24 @@
-import type { InferTypeNode, TypeParameterDeclaration } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link InferTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param typeParameter The typeParameter.
- * @returns The created node.
- */
-export const createInferTypeNode = (
-  typeParameter: TypeParameterDeclaration,
-): InferTypeNode => make("InferTypeNode", { typeParameter });
+import type { InferTypeNode, TypeParameterDeclaration } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link InferTypeNode}: an `infer R` type used inside the extends
+ * clause of a conditional type.
+ *
+ * The `infer ` keyword prints in front of the type parameter's name. In postfix
+ * and array positions the surrounding printer wraps the infer type in
+ * parentheses so `infer R[]` does not read as an array.
+ *
+ * Given a type parameter named `R`, the printer renders:
+ *
+ * ```ts
+ * infer R
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param typeParameter The type parameter to infer.
+ * @returns The created {@link InferTypeNode}.
+ */
+export const createInferTypeNode = (
+  typeParameter: TypeParameterDeclaration,
+): InferTypeNode => make("InferTypeNode", { typeParameter });

package/src/factory/types/createIntersectionTypeNode.ts

@@ -1,13 +1,24 @@
-import type { IntersectionTypeNode, TypeNode } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link IntersectionTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param types The constituent types.
- * @returns The created {@link IntersectionTypeNode}.
- */
-export const createIntersectionTypeNode = (
-  types: readonly TypeNode[],
-): IntersectionTypeNode => make("IntersectionTypeNode", { types });
+import type { IntersectionTypeNode, TypeNode } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link IntersectionTypeNode}: an `A & B` type.
+ *
+ * The constituents are joined with `&`. The printer is width-aware: when the
+ * whole intersection 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 `A` and `B`, the printer renders:
+ *
+ * ```ts
+ * A & B;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param types The constituent types.
+ * @returns The created {@link IntersectionTypeNode}.
+ */
+export const createIntersectionTypeNode = (
+  types: readonly TypeNode[],
+): IntersectionTypeNode => make("IntersectionTypeNode", { types });

package/src/factory/types/createKeywordTypeNode.ts

@@ -1,13 +1,25 @@
-import type { KeywordTypeNode } from "../../ast";
-import { SyntaxKind } from "../../syntax";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link KeywordTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param kind The token kind.
- * @returns The created {@link KeywordTypeNode}.
- */
-export const createKeywordTypeNode = (kind: SyntaxKind): KeywordTypeNode =>
-  make("KeywordTypeNode", { keyword: kind });
+import type { KeywordTypeNode } from "../../ast";
+import { SyntaxKind } from "../../syntax";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link KeywordTypeNode}: a built-in keyword type such as `string` or
+ * `number`.
+ *
+ * The kind is a keyword {@link SyntaxKind} like `StringKeyword`,
+ * `NumberKeyword`, `BooleanKeyword`, `VoidKeyword`, `AnyKeyword`, or
+ * `UnknownKeyword`. The printer emits the keyword's own source text directly,
+ * so the node renders as that single word with no surrounding tokens.
+ *
+ * Given the `StringKeyword` kind, the printer renders:
+ *
+ * ```ts
+ * string;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param kind The token kind.
+ * @returns The created {@link KeywordTypeNode}.
+ */
+export const createKeywordTypeNode = (kind: SyntaxKind): KeywordTypeNode =>
+  make("KeywordTypeNode", { keyword: kind });

package/src/factory/types/createLiteralTypeNode.ts

@@ -1,19 +1,38 @@
-import type {
-  BigIntLiteral,
-  LiteralTypeNode,
-  NumericLiteral,
-  StringLiteral,
-  Token,
-} from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link LiteralTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param literal The literal.
- * @returns The created {@link LiteralTypeNode}.
- */
-export const createLiteralTypeNode = (
-  literal: StringLiteral | NumericLiteral | BigIntLiteral | Token,
-): LiteralTypeNode => make("LiteralTypeNode", { literal });
+import type {
+  BigIntLiteral,
+  LiteralTypeNode,
+  NumericLiteral,
+  PrefixUnaryExpression,
+  StringLiteral,
+  Token,
+} from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link LiteralTypeNode}: a literal used in type position such as
+ * `"foo"`, `42`, `true`, or `null`.
+ *
+ * The printer emits the wrapped literal directly, so the rendered text is
+ * exactly that literal's own source. A {@link PrefixUnaryExpression} covers
+ * negative numeric literals such as `-1`, and a {@link Token} covers keyword
+ * literals such as `true`, `false`, and `null`.
+ *
+ * Given a `"foo"` string literal, the printer renders:
+ *
+ * ```ts
+ * "foo";
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param literal The literal; a {@link PrefixUnaryExpression} covers negative
+ *   numeric literals such as `-1`.
+ * @returns The created {@link LiteralTypeNode}.
+ */
+export const createLiteralTypeNode = (
+  literal:
+    | StringLiteral
+    | NumericLiteral
+    | BigIntLiteral
+    | PrefixUnaryExpression
+    | Token,
+): LiteralTypeNode => make("LiteralTypeNode", { literal });

package/src/factory/types/createMappedTypeNode.ts

@@ -1,37 +1,56 @@
-import type {
-  MappedTypeNode,
-  Token,
-  TypeElement,
-  TypeNode,
-  TypeParameterDeclaration,
-} from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link MappedTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param readonlyToken The readonlyToken.
- * @param typeParameter The typeParameter.
- * @param nameType The nameType.
- * @param questionToken The questionToken.
- * @param type The type.
- * @param members The members.
- * @returns The created node.
- */
-export const createMappedTypeNode = (
-  readonlyToken: Token | undefined,
-  typeParameter: TypeParameterDeclaration,
-  nameType: TypeNode | undefined,
-  questionToken: Token | undefined,
-  type: TypeNode | undefined,
-  members: readonly TypeElement[] | undefined,
-): MappedTypeNode =>
-  make("MappedTypeNode", {
-    readonlyToken,
-    typeParameter,
-    nameType,
-    questionToken,
-    type,
-    members,
-  });
+import type {
+  MappedTypeNode,
+  Token,
+  TypeElement,
+  TypeNode,
+  TypeParameterDeclaration,
+} from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link MappedTypeNode}: a `{ [K in keyof T]: T[K] }` mapped type.
+ *
+ * The type parameter supplies the key variable and its `in` constraint. When
+ * `nameType` is present it adds an `as` key remap, and when `type` is present
+ * it adds the `: ValueType` value. The whole thing renders inside `{ ... }` on
+ * one line.
+ *
+ * The `readonlyToken` and `questionToken` carry optional modifier polarity. A
+ * plain `readonly` or `?` token prints as `readonly ` and `?`; a `+` or `-`
+ * token prefixes the modifier, so it prints as `+readonly`/`-readonly` and
+ * `+?`/`-?`.
+ *
+ * Given a `K in keyof T` parameter and a `T[K]` value with no modifiers, the
+ * printer renders:
+ *
+ * ```ts
+ * { [K in keyof T]: T[K] }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param readonlyToken The `readonly` modifier with optional `+`/`-` polarity,
+ *   if any.
+ * @param typeParameter The key type parameter holding the `in` constraint.
+ * @param nameType The `as` key remap type, if any.
+ * @param questionToken The optional-marker `?` with optional `+`/`-` polarity,
+ *   if any.
+ * @param type The mapped value type, if any.
+ * @param members The members, if any.
+ * @returns The created {@link MappedTypeNode}.
+ */
+export const createMappedTypeNode = (
+  readonlyToken: Token | undefined,
+  typeParameter: TypeParameterDeclaration,
+  nameType: TypeNode | undefined,
+  questionToken: Token | undefined,
+  type: TypeNode | undefined,
+  members: readonly TypeElement[] | undefined,
+): MappedTypeNode =>
+  make("MappedTypeNode", {
+    readonlyToken,
+    typeParameter,
+    nameType,
+    questionToken,
+    type,
+    members,
+  });

package/src/factory/types/createMethodSignature.ts

@@ -1,40 +1,53 @@
-import type {
-  MethodSignature,
-  ModifierLike,
-  ParameterDeclaration,
-  PropertyName,
-  Token,
-  TypeNode,
-  TypeParameterDeclaration,
-} from "../../ast";
-import { asPropertyName } from "../internal/asPropertyName";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link MethodSignature}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param modifiers The leading modifiers and decorators, if any.
- * @param name The name.
- * @param questionToken The optional marker (`?`), if any.
- * @param typeParameters The generic type parameters, if any.
- * @param parameters The parameters.
- * @param type The type.
- * @returns The created {@link MethodSignature}.
- */
-export const createMethodSignature = (
-  modifiers: readonly ModifierLike[] | undefined,
-  name: string | PropertyName,
-  questionToken: Token | undefined,
-  typeParameters: readonly TypeParameterDeclaration[] | undefined,
-  parameters: readonly ParameterDeclaration[],
-  type: TypeNode | undefined,
-): MethodSignature =>
-  make("MethodSignature", {
-    modifiers,
-    name: asPropertyName(name),
-    questionToken,
-    typeParameters,
-    parameters,
-    type,
-  });
+import type {
+  MethodSignature,
+  ModifierLike,
+  ParameterDeclaration,
+  PropertyName,
+  Token,
+  TypeNode,
+  TypeParameterDeclaration,
+} from "../../ast";
+import { asPropertyName } from "../internal/asPropertyName";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link MethodSignature}: a `name(params): T` method signature for an
+ * interface or type literal.
+ *
+ * Any modifiers print first, then the name, then a `?` when the question token
+ * is present, then optional type parameters as `<...>`, the parameter list, and
+ * the return type as `: Type` when present. A string name is normalized to a
+ * property name node.
+ *
+ * Given the name `greet`, one `name: string` parameter, and a `void` return
+ * type, the printer renders:
+ *
+ * ```ts
+ * greet(name: string): void
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param modifiers The leading modifiers and decorators, if any.
+ * @param name The method name.
+ * @param questionToken The optional marker (`?`), if any.
+ * @param typeParameters The generic type parameters, if any.
+ * @param parameters The parameters.
+ * @param type The return type, if any.
+ * @returns The created {@link MethodSignature}.
+ */
+export const createMethodSignature = (
+  modifiers: readonly ModifierLike[] | undefined,
+  name: string | PropertyName,
+  questionToken: Token | undefined,
+  typeParameters: readonly TypeParameterDeclaration[] | undefined,
+  parameters: readonly ParameterDeclaration[],
+  type: TypeNode | undefined,
+): MethodSignature =>
+  make("MethodSignature", {
+    modifiers,
+    name: asPropertyName(name),
+    questionToken,
+    typeParameters,
+    parameters,
+    type,
+  });

package/src/factory/types/createNamedTupleMember.ts

@@ -1,26 +1,37 @@
-import type { Identifier, NamedTupleMember, Token, TypeNode } from "../../ast";
-import { asName } from "../internal/asName";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link NamedTupleMember}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param dotDotDotToken The dotDotDotToken.
- * @param name The name.
- * @param questionToken The questionToken.
- * @param type The type.
- * @returns The created node.
- */
-export const createNamedTupleMember = (
-  dotDotDotToken: Token | undefined,
-  name: string | Identifier,
-  questionToken: Token | undefined,
-  type: TypeNode,
-): NamedTupleMember =>
-  make("NamedTupleMember", {
-    dotDotDotToken,
-    name: asName(name),
-    questionToken,
-    type,
-  });
+import type { Identifier, NamedTupleMember, Token, TypeNode } from "../../ast";
+import { asName } from "../internal/asName";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link NamedTupleMember}: a labeled tuple element such as `name:
+ * string`.
+ *
+ * A leading `...` prints when the rest token is present, then the label, then a
+ * `?` when the question token is present, then `: ` followed by the type. A
+ * string name is normalized to an identifier.
+ *
+ * Given the label `name` and a `string` type, the printer renders:
+ *
+ * ```ts
+ * name: string;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param dotDotDotToken The rest marker (`...`), if any.
+ * @param name The element label.
+ * @param questionToken The optional marker (`?`), if any.
+ * @param type The element type.
+ * @returns The created {@link NamedTupleMember}.
+ */
+export const createNamedTupleMember = (
+  dotDotDotToken: Token | undefined,
+  name: string | Identifier,
+  questionToken: Token | undefined,
+  type: TypeNode,
+): NamedTupleMember =>
+  make("NamedTupleMember", {
+    dotDotDotToken,
+    name: asName(name),
+    questionToken,
+    type,
+  });

package/src/factory/types/createNotEmittedTypeElement.ts

@@ -0,0 +1,16 @@
+import type { NotEmittedTypeElement } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link NotEmittedTypeElement}: a placeholder type-element that
+ * carries no syntax of its own.
+ *
+ * It exists to hold position and attached comments inside a member list without
+ * contributing any text. The printer emits the empty string for it, so the
+ * rendered output is empty:
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @returns The created {@link NotEmittedTypeElement}.
+ */
+export const createNotEmittedTypeElement = (): NotEmittedTypeElement =>
+  make("NotEmittedTypeElement", {});

package/src/factory/types/createOptionalTypeNode.ts

@@ -1,12 +1,22 @@
-import type { OptionalTypeNode, TypeNode } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link OptionalTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param type The type.
- * @returns The created node.
- */
-export const createOptionalTypeNode = (type: TypeNode): OptionalTypeNode =>
-  make("OptionalTypeNode", { type });
+import type { OptionalTypeNode, TypeNode } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create an {@link OptionalTypeNode}: a `T?` optional element inside a tuple
+ * type.
+ *
+ * The element type prints first, immediately followed by a `?`. This form is
+ * only valid in tuple element position, for example `[string, number?]`.
+ *
+ * Given a `string` element type, the printer renders:
+ *
+ * ```ts
+ * string?
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param type The element type.
+ * @returns The created {@link OptionalTypeNode}.
+ */
+export const createOptionalTypeNode = (type: TypeNode): OptionalTypeNode =>
+  make("OptionalTypeNode", { type });

package/src/factory/types/createParenthesizedType.ts

@@ -1,13 +1,23 @@
-import type { ParenthesizedTypeNode, TypeNode } from "../../ast";
-import { make } from "../internal/make";
-
-/**
- * Create a {@link ParenthesizedTypeNode}.
- *
- * @author Jeongho Nam - https://github.com/samchon
- * @param type The type.
- * @returns The created {@link ParenthesizedTypeNode}.
- */
-export const createParenthesizedType = (
-  type: TypeNode,
-): ParenthesizedTypeNode => make("ParenthesizedTypeNode", { type });
+import type { ParenthesizedTypeNode, TypeNode } from "../../ast";
+import { make } from "../internal/make";
+
+/**
+ * Create a {@link ParenthesizedTypeNode}: a `(T)` explicitly parenthesized type.
+ *
+ * The printer always wraps the inner type in literal parentheses, so this is
+ * the way to force grouping the surrounding printer would not add on its own,
+ * for example to disambiguate a union inside a larger type.
+ *
+ * Given an `A | B` inner type, the printer renders:
+ *
+ * ```ts
+ * A | B;
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param type The inner type to parenthesize.
+ * @returns The created {@link ParenthesizedTypeNode}.
+ */
+export const createParenthesizedType = (
+  type: TypeNode,
+): ParenthesizedTypeNode => make("ParenthesizedTypeNode", { type });