@goast/typescript 0.9.0-beta.2 → 0.9.1

package/dist/src/ast/nodes/method.d.ts

@@ -23,24 +23,114 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     returnType?: Nullable<TsType<TBuilder>>;
     body?: Nullable<AppendValue<TBuilder>>;
 }>;
+/**
+ * Represents a method of a class, or a method signature of an object type or an object literal.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`,
+ * `async`), name, optional marker, generics, parameters, return type, and the body. Without a body the method ends
+ * with a semicolon, except inside an object literal (`tsObject`), where every method ends with a comma instead. The
+ * injection points are named after the parts they wrap, such as `beforeParams` and `afterReturnType`.
+ *
+ * @template TBuilder The type of the source builder the method is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsMethod
+ */
 export declare class TsMethod<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The doc comment written above the method, or `null` to omit it. The descriptions of the generic parameters and of
+     * the parameters are added to it as `@template` and `@param` tags.
+     */
     doc: TsDoc<TBuilder> | null;
+    /**
+     * The decorators written above the method, each on its own line.
+     */
     decorators: TsDecorator<TBuilder>[];
+    /**
+     * The access modifier written before the method, such as `public`, or `null` to omit it.
+     */
     accessModifier: TsAccessModifier | null;
+    /**
+     * Whether the method is written with the `static` keyword.
+     * @default false
+     */
     static: boolean;
+    /**
+     * Whether the method is written with the `abstract` keyword.
+     * @default false
+     */
     abstract: boolean;
+    /**
+     * Whether the method is written with the `override` keyword.
+     * @default false
+     */
     override: boolean;
+    /**
+     * Whether the method is written with the `async` keyword, which is placed after `override`.
+     * @default false
+     */
     async: boolean;
+    /**
+     * The method name, written verbatim after the modifiers.
+     */
     name: string;
+    /**
+     * Whether the name is followed by `?`, which marks the method as optional, such as `x?()`.
+     * @default false
+     */
     optional: boolean;
+    /**
+     * The type parameters written in angle brackets after the name, such as `<T, U>`. Described parameters also add a
+     * `@template` tag to the doc comment.
+     */
     generics: (TsGenericParameter<TBuilder> | BasicAppendValue<TBuilder>)[];
+    /**
+     * The parameters written in parentheses, in the given order. Each parameter with a description adds a `@param` tag to
+     * the doc comment.
+     */
     parameters: (TsParameter<TBuilder> | BasicAppendValue<TBuilder>)[];
+    /**
+     * The return type written after the parameters, such as `: number`, or `null` to omit it.
+     */
     returnType: TsType<TBuilder> | null;
+    /**
+     * The code written in braces after the signature, one statement per line. `null` writes the method without a body,
+     * which ends with a semicolon outside of object literals.
+     */
     body: AppendValue<TBuilder> | null;
+    /**
+     * Initializes a new instance of the TsMethod class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
+/**
+ * Creates a method node. This is the function that `tsMethod` wraps, and `tsMethod` also provides `write`.
+ *
+ * @param name The name of the method. See `TsMethod.name`.
+ * @param options The settings of the method. See `TsMethod` for the available properties.
+ * @example
+ * ```ts
+ * createMethod('x', { returnType: 'number' });
+ * // Emits:
+ * // x(): number;
+ * ```
+ */
 export declare const createMethod: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], options?: Prettify<Omit<Options<TBuilder>, 'name'>>) => TsMethod<TBuilder>;
+/**
+ * Factory for creating method nodes. The `write` function writes one or more method nodes to a builder.
+ *
+ * @param name The name of the method. See `TsMethod.name`.
+ * @param options The settings of the method. See `TsMethod` for the available properties.
+ * @example
+ * ```ts
+ * tsMethod('x', { parameters: [tsParameter('y'), tsParameter('z')], returnType: 'number', body: 'return 42;' });
+ * // Emits:
+ * // x(y, z): number {
+ * //   return 42;
+ * // }
+ * ```
+ */
 export declare const tsMethod: typeof createMethod & {
     write: typeof writeTsNodes;
 };

package/dist/src/ast/nodes/method.js

@@ -6,20 +6,84 @@ import { tsDoc } from './doc.js';
 import { tsGenericParameter } from './generic-parameter.js';
 import { TsObject } from './object.js';
 import { tsParameter } from './parameter.js';
+/**
+ * Represents a method of a class, or a method signature of an object type or an object literal.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`,
+ * `async`), name, optional marker, generics, parameters, return type, and the body. Without a body the method ends
+ * with a semicolon, except inside an object literal (`tsObject`), where every method ends with a comma instead. The
+ * injection points are named after the parts they wrap, such as `beforeParams` and `afterReturnType`.
+ *
+ * @template TBuilder The type of the source builder the method is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsMethod
+ */
 export class TsMethod extends TsNode {
+    /**
+     * The doc comment written above the method, or `null` to omit it. The descriptions of the generic parameters and of
+     * the parameters are added to it as `@template` and `@param` tags.
+     */
     doc;
+    /**
+     * The decorators written above the method, each on its own line.
+     */
     decorators;
+    /**
+     * The access modifier written before the method, such as `public`, or `null` to omit it.
+     */
     accessModifier;
+    /**
+     * Whether the method is written with the `static` keyword.
+     * @default false
+     */
     static;
+    /**
+     * Whether the method is written with the `abstract` keyword.
+     * @default false
+     */
     abstract;
+    /**
+     * Whether the method is written with the `override` keyword.
+     * @default false
+     */
     override;
+    /**
+     * Whether the method is written with the `async` keyword, which is placed after `override`.
+     * @default false
+     */
     async;
+    /**
+     * The method name, written verbatim after the modifiers.
+     */
     name;
+    /**
+     * Whether the name is followed by `?`, which marks the method as optional, such as `x?()`.
+     * @default false
+     */
     optional;
+    /**
+     * The type parameters written in angle brackets after the name, such as `<T, U>`. Described parameters also add a
+     * `@template` tag to the doc comment.
+     */
     generics;
+    /**
+     * The parameters written in parentheses, in the given order. Each parameter with a description adds a `@param` tag to
+     * the doc comment.
+     */
     parameters;
+    /**
+     * The return type written after the parameters, such as `: number`, or `null` to omit it.
+     */
     returnType;
+    /**
+     * The code written in braces after the signature, one statement per line. `null` writes the method without a body,
+     * which ends with a semicolon outside of object literals.
+     */
     body;
+    /**
+     * Initializes a new instance of the TsMethod class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.doc = options.doc ?? null;
@@ -86,7 +150,33 @@ export class TsMethod extends TsNode {
         builder.appendLine();
     }
 }
+/**
+ * Creates a method node. This is the function that `tsMethod` wraps, and `tsMethod` also provides `write`.
+ *
+ * @param name The name of the method. See `TsMethod.name`.
+ * @param options The settings of the method. See `TsMethod` for the available properties.
+ * @example
+ * ```ts
+ * createMethod('x', { returnType: 'number' });
+ * // Emits:
+ * // x(): number;
+ * ```
+ */
 export const createMethod = (name, options) => new TsMethod({ ...options, name });
+/**
+ * Factory for creating method nodes. The `write` function writes one or more method nodes to a builder.
+ *
+ * @param name The name of the method. See `TsMethod.name`.
+ * @param options The settings of the method. See `TsMethod` for the available properties.
+ * @example
+ * ```ts
+ * tsMethod('x', { parameters: [tsParameter('y'), tsParameter('z')], returnType: 'number', body: 'return 42;' });
+ * // Emits:
+ * // x(y, z): number {
+ * //   return 42;
+ * // }
+ * ```
+ */
 export const tsMethod = Object.assign(createMethod, {
     write: writeTsNodes,
 });

package/dist/src/ast/nodes/object-type.d.ts

@@ -9,12 +9,46 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     members?: Nullable<Nullable<Member<TBuilder>>[]>;
 }>;
 type Member<TBuilder extends SourceBuilder> = TsProperty<TBuilder> | TsMethod<TBuilder> | TsIndexer<TBuilder> | BasicAppendValue<TBuilder>;
+/**
+ * Represents an object type literal, which describes the shape of a value in a type position.
+ *
+ * The members are written between braces, one per line. An object type without members is written as `{}`.
+ * Properties and bodyless methods end with a semicolon.
+ *
+ * @template TBuilder The type of the source builder the object type is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsObjectType
+ * @see TsObject
+ */
 export declare class TsObjectType<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The members written between the braces, in the given order. Null entries are skipped. Properties and bodyless
+     * methods without a doc comment or decorators are written without blank lines, other members are set off by blank
+     * lines.
+     */
     members: Member<TBuilder>[];
+    /**
+     * Initializes a new instance of the TsObjectType class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createObjectType: <TBuilder extends SourceBuilder>(options?: Options<TBuilder>) => TsObjectType<TBuilder>;
+/**
+ * Factory for creating object type nodes. The `write` function writes one or more object type nodes to a builder.
+ *
+ * @param options The settings of the object type. See `TsObjectType` for the available properties.
+ * @example
+ * ```ts
+ * tsObjectType({ members: [tsProperty('x'), tsProperty('y')] });
+ * // Emits:
+ * // {
+ * //   x;
+ * //   y;
+ * // }
+ * ```
+ */
 export declare const tsObjectType: typeof createObjectType & {
     write: typeof writeTsNodes;
 };

package/dist/src/ast/nodes/object-type.js

@@ -2,8 +2,28 @@ import { notNullish } from '@goast/core';
 import { TsNode } from '../node.js';
 import { writeTsMembers } from '../utils/write-ts-members.js';
 import { writeTsNodes } from '../utils/write-ts-nodes.js';
+/**
+ * Represents an object type literal, which describes the shape of a value in a type position.
+ *
+ * The members are written between braces, one per line. An object type without members is written as `{}`.
+ * Properties and bodyless methods end with a semicolon.
+ *
+ * @template TBuilder The type of the source builder the object type is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsObjectType
+ * @see TsObject
+ */
 export class TsObjectType extends TsNode {
+    /**
+     * The members written between the braces, in the given order. Null entries are skipped. Properties and bodyless
+     * methods without a doc comment or decorators are written without blank lines, other members are set off by blank
+     * lines.
+     */
     members;
+    /**
+     * Initializes a new instance of the TsObjectType class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.members = options.members?.filter(notNullish) ?? [];
@@ -15,6 +35,20 @@ export class TsObjectType extends TsNode {
     }
 }
 const createObjectType = (options) => new TsObjectType(options ?? {});
+/**
+ * Factory for creating object type nodes. The `write` function writes one or more object type nodes to a builder.
+ *
+ * @param options The settings of the object type. See `TsObjectType` for the available properties.
+ * @example
+ * ```ts
+ * tsObjectType({ members: [tsProperty('x'), tsProperty('y')] });
+ * // Emits:
+ * // {
+ * //   x;
+ * //   y;
+ * // }
+ * ```
+ */
 export const tsObjectType = Object.assign(createObjectType, {
     write: writeTsNodes,
 });

package/dist/src/ast/nodes/object.d.ts

@@ -8,11 +8,45 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     members?: Nullable<Nullable<Member<TBuilder>>[]>;
 }>;
 type Member<TBuilder extends SourceBuilder> = TsProperty<TBuilder> | TsMethod<TBuilder> | BasicAppendValue<TBuilder>;
+/**
+ * Represents an object literal, which creates a value in an expression position.
+ *
+ * The members are written between braces, one per line, and each member ends with a comma. Object literals have no
+ * type annotations, so properties are written without one. An object without members is written as `{}`.
+ *
+ * @template TBuilder The type of the source builder the object literal is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsObject
+ * @see TsObjectType
+ */
 export declare class TsObject<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The members written between the braces, in the given order. Null entries are skipped. Properties are written as
+     * `name: value,`, or as `name,` when they have no value. Properties and bodyless methods without a doc comment or
+     * decorators are written without blank lines, other members are set off by blank lines.
+     */
     members: Member<TBuilder>[];
+    /**
+     * Initializes a new instance of the TsObject class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
+/**
+ * Factory for creating object literal nodes. The `write` function writes one or more object literal nodes to a builder.
+ *
+ * @param options The settings of the object literal. See `TsObject` for the available properties.
+ * @example
+ * ```ts
+ * tsObject({ members: [tsProperty('x'), tsProperty('y')] });
+ * // Emits:
+ * // {
+ * //   x,
+ * //   y,
+ * // }
+ * ```
+ */
 declare const createObject: <TBuilder extends SourceBuilder>(options?: Options<TBuilder>) => TsObject<TBuilder>;
 export declare const tsObject: typeof createObject & {
     write: typeof writeTsNodes;

package/dist/src/ast/nodes/object.js

@@ -2,8 +2,28 @@ import { notNullish } from '@goast/core';
 import { TsNode } from '../node.js';
 import { writeTsMembers } from '../utils/write-ts-members.js';
 import { writeTsNodes } from '../utils/write-ts-nodes.js';
+/**
+ * Represents an object literal, which creates a value in an expression position.
+ *
+ * The members are written between braces, one per line, and each member ends with a comma. Object literals have no
+ * type annotations, so properties are written without one. An object without members is written as `{}`.
+ *
+ * @template TBuilder The type of the source builder the object literal is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsObject
+ * @see TsObjectType
+ */
 export class TsObject extends TsNode {
+    /**
+     * The members written between the braces, in the given order. Null entries are skipped. Properties are written as
+     * `name: value,`, or as `name,` when they have no value. Properties and bodyless methods without a doc comment or
+     * decorators are written without blank lines, other members are set off by blank lines.
+     */
     members;
+    /**
+     * Initializes a new instance of the TsObject class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.members = options.members?.filter(notNullish) ?? [];
@@ -14,6 +34,20 @@ export class TsObject extends TsNode {
         }, { multiline: this.members.length > 0 });
     }
 }
+/**
+ * Factory for creating object literal nodes. The `write` function writes one or more object literal nodes to a builder.
+ *
+ * @param options The settings of the object literal. See `TsObject` for the available properties.
+ * @example
+ * ```ts
+ * tsObject({ members: [tsProperty('x'), tsProperty('y')] });
+ * // Emits:
+ * // {
+ * //   x,
+ * //   y,
+ * // }
+ * ```
+ */
 const createObject = (options) => new TsObject(options ?? {});
 export const tsObject = Object.assign(createObject, {
     write: writeTsNodes,

package/dist/src/ast/nodes/parameter.d.ts

@@ -12,17 +12,68 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     optional?: Nullable<boolean>;
     default?: Nullable<TsValue<TBuilder>>;
 }>;
+/**
+ * Represents a parameter of a function or method, such as `x?: number = 42`.
+ *
+ * Written in this order: decorators, name, optional marker, type annotation, and default value. The injection points
+ * `beforeDecorators` and `afterDecorators` wrap the decorators, `beforeName` and `afterName` wrap the name,
+ * `beforeType` and `afterType` wrap the type, and `beforeDefault` and `afterDefault` wrap the default value.
+ *
+ * A parameter does not write its own parentheses. `tsParameter.write` writes a list of parameters in parentheses, one
+ * per line when there are more than two parameters or when one of them has decorators.
+ *
+ * @template TBuilder The type of the source builder the parameter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsParameter
+ */
 export declare class TsParameter<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The name of the parameter, written verbatim.
+     */
     name: string;
+    /**
+     * The text of the `@param` tag that the method or function that owns this parameter writes for it. The parameter
+     * itself does not write the description, so `null` only omits the tag.
+     */
     description: BasicAppendValue<TBuilder> | null;
+    /**
+     * The decorators written before the parameter. They are separated by spaces and written on the same line, such as
+     * `@decorator x`.
+     */
     decorators: TsDecorator<TBuilder>[];
+    /**
+     * The type annotation written after the name, such as `: number`, or `null` to omit it.
+     */
     type: TsType<TBuilder> | null;
+    /**
+     * Whether the name is followed by `?`, which marks the parameter as optional.
+     * @default false
+     */
     optional: boolean;
+    /**
+     * The default value written after ` = `, such as ` = 42`, or `null` to omit it. Falsy values are not written.
+     */
     default: TsValue<TBuilder> | null;
+    /**
+     * Initializes a new instance of the TsParameter class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createParameter: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], options?: Prettify<Omit<Options<TBuilder>, 'name'>>) => TsParameter<TBuilder>;
+/**
+ * Factory for creating parameter nodes. The `write` function writes a parenthesized list of parameters to a builder.
+ *
+ * @param name The name of the parameter. See `TsParameter.name`.
+ * @param options The settings of the parameter. See `TsParameter` for the available properties.
+ * @example
+ * ```ts
+ * tsParameter('x', { decorators: [tsDecorator('decorator')], type: 'number', default: '42', optional: true });
+ * // Emits:
+ * // @decorator x?: number = 42
+ * ```
+ */
 export declare const tsParameter: typeof createParameter & {
     write: typeof writeTsParameters;
 };

package/dist/src/ast/nodes/parameter.js

@@ -3,13 +3,52 @@ import { TsNode } from '../node.js';
 import { writeTsNode } from '../utils/write-ts-nodes.js';
 import { writeTsParameters } from '../utils/write-ts-parameters.js';
 import { tsDecorator } from './decorator.js';
+/**
+ * Represents a parameter of a function or method, such as `x?: number = 42`.
+ *
+ * Written in this order: decorators, name, optional marker, type annotation, and default value. The injection points
+ * `beforeDecorators` and `afterDecorators` wrap the decorators, `beforeName` and `afterName` wrap the name,
+ * `beforeType` and `afterType` wrap the type, and `beforeDefault` and `afterDefault` wrap the default value.
+ *
+ * A parameter does not write its own parentheses. `tsParameter.write` writes a list of parameters in parentheses, one
+ * per line when there are more than two parameters or when one of them has decorators.
+ *
+ * @template TBuilder The type of the source builder the parameter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsParameter
+ */
 export class TsParameter extends TsNode {
+    /**
+     * The name of the parameter, written verbatim.
+     */
     name;
+    /**
+     * The text of the `@param` tag that the method or function that owns this parameter writes for it. The parameter
+     * itself does not write the description, so `null` only omits the tag.
+     */
     description;
+    /**
+     * The decorators written before the parameter. They are separated by spaces and written on the same line, such as
+     * `@decorator x`.
+     */
     decorators;
+    /**
+     * The type annotation written after the name, such as `: number`, or `null` to omit it.
+     */
     type;
+    /**
+     * Whether the name is followed by `?`, which marks the parameter as optional.
+     * @default false
+     */
     optional;
+    /**
+     * The default value written after ` = `, such as ` = 42`, or `null` to omit it. Falsy values are not written.
+     */
     default;
+    /**
+     * Initializes a new instance of the TsParameter class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.name = options.name;
@@ -41,6 +80,18 @@ export class TsParameter extends TsNode {
     }
 }
 const createParameter = (name, options) => new TsParameter({ ...options, name });
+/**
+ * Factory for creating parameter nodes. The `write` function writes a parenthesized list of parameters to a builder.
+ *
+ * @param name The name of the parameter. See `TsParameter.name`.
+ * @param options The settings of the parameter. See `TsParameter` for the available properties.
+ * @example
+ * ```ts
+ * tsParameter('x', { decorators: [tsDecorator('decorator')], type: 'number', default: '42', optional: true });
+ * // Emits:
+ * // @decorator x?: number = 42
+ * ```
+ */
 export const tsParameter = Object.assign(createParameter, {
     write: writeTsParameters,
 });