@goast/typescript 0.9.0 → 0.9.1

package/dist/src/ast/nodes/property-accessor.d.ts

@@ -24,30 +24,124 @@ declare abstract class TsPropertyAccessor<TBuilder extends SourceBuilder, TInjec
     private _static;
     private _abstract;
     private _override;
+    /**
+     * The doc comment written above the accessor, or `null` to omit it. It is written as given, after the doc comment of
+     * the owning property when there is one.
+     */
     doc: TsDoc<TBuilder> | null;
+    /**
+     * The decorators written before the accessor. They are separated by spaces and written on the same line as the
+     * accessor, such as `@decorator get x();`.
+     */
     decorators: TsDecorator<TBuilder>[];
+    /**
+     * The code written in braces after the signature, on separate lines. `null` writes the accessor without a body,
+     * which ends with a semicolon instead.
+     */
     body: AppendValue<TBuilder> | null;
+    /**
+     * The name written after `get` or `set`. When the accessor belongs to an accessor property, the name of that property
+     * is used instead. Defaults to `someProperty` when neither is set.
+     */
     get propertyName(): string;
     set propertyName(value: string | null);
+    /**
+     * The type of the accessor. A getter writes it as its return type, such as `: number`, and a setter writes it as the
+     * type of its `value` parameter. When the accessor belongs to an accessor property, the type of that property is used
+     * if it is set. `null` omits the type.
+     */
     get type(): TsType<TBuilder> | null;
     set type(value: TsType<TBuilder> | null);
+    /**
+     * The access modifier written before the accessor, such as `public`, or `null` to omit it. When the accessor belongs
+     * to an accessor property, the modifier of that property is used if it is set.
+     */
     get accessModifier(): TsAccessModifier | null;
     set accessModifier(value: TsAccessModifier | null);
+    /**
+     * Whether the accessor is written with the `static` keyword. When the accessor belongs to an accessor property, the
+     * value of that property is used if it is set.
+     * @default false
+     */
     get static(): boolean;
     set static(value: boolean);
+    /**
+     * Whether the accessor is written with the `abstract` keyword. When the accessor belongs to an accessor property, the
+     * value of that property is used if it is set.
+     * @default false
+     */
     get abstract(): boolean;
     set abstract(value: boolean);
+    /**
+     * Whether the accessor is written with the `override` keyword. When the accessor belongs to an accessor property, the
+     * value of that property is used if it is set.
+     * @default false
+     */
     get override(): boolean;
     set override(value: boolean);
     protected property?: TsProperty<TBuilder>;
+    /**
+     * Initializes a new instance of the TsPropertyAccessor class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
 }
+/**
+ * Represents the setter of a property, such as `set x(value: number) { ... }`.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`), the
+ * `set` keyword, the name, and a `value` parameter, which is typed when a type is set. Without a body the setter ends
+ * with a semicolon. A body is written in braces over several lines.
+ *
+ * @template TBuilder The type of the source builder the setter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see createPropertySetter
+ */
 export declare class TsPropertySetter<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsPropertyAccessor<TBuilder, TInjects> {
     protected onWrite(builder: TBuilder): void;
 }
+/**
+ * Represents the getter of a property, such as `get x(): number { ... }`.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`), the
+ * `get` keyword, the name, an empty parameter list, and the return type when a type is set. Without a body the getter
+ * ends with a semicolon. A body is written in braces over several lines.
+ *
+ * @template TBuilder The type of the source builder the getter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see createPropertyGetter
+ */
 export declare class TsPropertyGetter<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsPropertyAccessor<TBuilder, TInjects> {
     protected onWrite(builder: TBuilder): void;
 }
+/**
+ * Factory for creating property setter nodes. The returned node is written with its `write` method, or it is passed
+ * to the `set` of an accessor property (see `tsProperty`).
+ *
+ * @param options The settings of the setter. See `TsPropertySetter` for the available properties.
+ * @example
+ * ```ts
+ * createPropertySetter({ propertyName: 'x', type: 'number', body: 'this.x = value;' });
+ * // Emits:
+ * // set x(value: number) {
+ * //   this.x = value;
+ * // }
+ * ```
+ */
 export declare const createPropertySetter: <TBuilder extends SourceBuilder>(options?: Options<TBuilder>) => TsPropertySetter<TBuilder>;
+/**
+ * Factory for creating property getter nodes. The returned node is written with its `write` method, or it is passed
+ * to the `get` of an accessor property (see `tsProperty`).
+ *
+ * @param options The settings of the getter. See `TsPropertyGetter` for the available properties.
+ * @example
+ * ```ts
+ * createPropertyGetter({ propertyName: 'x', type: 'number', body: 'return this.x;' });
+ * // Emits:
+ * // get x(): number {
+ * //   return this.x;
+ * // }
+ * ```
+ */
 export declare const createPropertyGetter: <TBuilder extends SourceBuilder>(options?: Options<TBuilder>) => TsPropertyGetter<TBuilder>;
 export {};

package/dist/src/ast/nodes/property-accessor.js

@@ -10,39 +10,79 @@ class TsPropertyAccessor extends TsNode {
     _static;
     _abstract;
     _override;
+    /**
+     * The doc comment written above the accessor, or `null` to omit it. It is written as given, after the doc comment of
+     * the owning property when there is one.
+     */
     doc;
+    /**
+     * The decorators written before the accessor. They are separated by spaces and written on the same line as the
+     * accessor, such as `@decorator get x();`.
+     */
     decorators;
+    /**
+     * The code written in braces after the signature, on separate lines. `null` writes the accessor without a body,
+     * which ends with a semicolon instead.
+     */
     body;
+    /**
+     * The name written after `get` or `set`. When the accessor belongs to an accessor property, the name of that property
+     * is used instead. Defaults to `someProperty` when neither is set.
+     */
     get propertyName() {
         return this.property?.name ?? this._propertyName ?? 'someProperty';
     }
     set propertyName(value) {
         this._propertyName = value;
     }
+    /**
+     * The type of the accessor. A getter writes it as its return type, such as `: number`, and a setter writes it as the
+     * type of its `value` parameter. When the accessor belongs to an accessor property, the type of that property is used
+     * if it is set. `null` omits the type.
+     */
     get type() {
         return this.property?.type ?? this._type;
     }
     set type(value) {
         this._type = value;
     }
+    /**
+     * The access modifier written before the accessor, such as `public`, or `null` to omit it. When the accessor belongs
+     * to an accessor property, the modifier of that property is used if it is set.
+     */
     get accessModifier() {
         return this.property?.accessModifier ?? this._accessModifier;
     }
     set accessModifier(value) {
         this._accessModifier = value;
     }
+    /**
+     * Whether the accessor is written with the `static` keyword. When the accessor belongs to an accessor property, the
+     * value of that property is used if it is set.
+     * @default false
+     */
     get static() {
         return this.property?.static ?? this._static;
     }
     set static(value) {
         this._static = value;
     }
+    /**
+     * Whether the accessor is written with the `abstract` keyword. When the accessor belongs to an accessor property, the
+     * value of that property is used if it is set.
+     * @default false
+     */
     get abstract() {
         return this.property?.abstract ?? this._abstract;
     }
     set abstract(value) {
         this._abstract = value;
     }
+    /**
+     * Whether the accessor is written with the `override` keyword. When the accessor belongs to an accessor property, the
+     * value of that property is used if it is set.
+     * @default false
+     */
     get override() {
         return this.property?.override ?? this._override;
     }
@@ -50,6 +90,10 @@ class TsPropertyAccessor extends TsNode {
         this._override = value;
     }
     property;
+    /**
+     * Initializes a new instance of the TsPropertyAccessor class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this._propertyName = options.propertyName ?? null;
@@ -63,6 +107,17 @@ class TsPropertyAccessor extends TsNode {
         this._override = options.override ?? false;
     }
 }
+/**
+ * Represents the setter of a property, such as `set x(value: number) { ... }`.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`), the
+ * `set` keyword, the name, and a `value` parameter, which is typed when a type is set. Without a body the setter ends
+ * with a semicolon. A body is written in braces over several lines.
+ *
+ * @template TBuilder The type of the source builder the setter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see createPropertySetter
+ */
 export class TsPropertySetter extends TsPropertyAccessor {
     onWrite(builder) {
         tsDoc.write(builder, this.doc);
@@ -93,6 +148,17 @@ export class TsPropertySetter extends TsPropertyAccessor {
         builder.appendLine();
     }
 }
+/**
+ * Represents the getter of a property, such as `get x(): number { ... }`.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`), the
+ * `get` keyword, the name, an empty parameter list, and the return type when a type is set. Without a body the getter
+ * ends with a semicolon. A body is written in braces over several lines.
+ *
+ * @template TBuilder The type of the source builder the getter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see createPropertyGetter
+ */
 export class TsPropertyGetter extends TsPropertyAccessor {
     onWrite(builder) {
         tsDoc.write(builder, this.doc);
@@ -120,5 +186,33 @@ export class TsPropertyGetter extends TsPropertyAccessor {
         builder.appendLine();
     }
 }
+/**
+ * Factory for creating property setter nodes. The returned node is written with its `write` method, or it is passed
+ * to the `set` of an accessor property (see `tsProperty`).
+ *
+ * @param options The settings of the setter. See `TsPropertySetter` for the available properties.
+ * @example
+ * ```ts
+ * createPropertySetter({ propertyName: 'x', type: 'number', body: 'this.x = value;' });
+ * // Emits:
+ * // set x(value: number) {
+ * //   this.x = value;
+ * // }
+ * ```
+ */
 export const createPropertySetter = (options) => new TsPropertySetter(options ?? {});
+/**
+ * Factory for creating property getter nodes. The returned node is written with its `write` method, or it is passed
+ * to the `get` of an accessor property (see `tsProperty`).
+ *
+ * @param options The settings of the getter. See `TsPropertyGetter` for the available properties.
+ * @example
+ * ```ts
+ * createPropertyGetter({ propertyName: 'x', type: 'number', body: 'return this.x;' });
+ * // Emits:
+ * // get x(): number {
+ * //   return this.x;
+ * // }
+ * ```
+ */
 export const createPropertyGetter = (options) => new TsPropertyGetter(options ?? {});

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

@@ -26,35 +26,148 @@ type AccessorOptions<TBuilder extends SourceBuilder, TInjects extends string = n
     get?: Nullable<TsPropertyGetter<TBuilder>>;
     set?: Nullable<TsPropertySetter<TBuilder>>;
 };
+/**
+ * Base class for the properties of classes and object literals. It holds the parts that all properties share: the name,
+ * the doc comment, the decorators, the type and the modifiers.
+ *
+ * Use `tsProperty` to create a property. It returns a `TsSimpleProperty` for a plain property, and a
+ * `TsAccessorProperty` when getters or setters are passed in its options.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsProperty
+ */
 export declare abstract class TsProperty<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | BaseInjects> {
+    /**
+     * The name of the property. A simple property writes it verbatim, or in quotes when it is not a plain identifier,
+     * such as `'x y'`. An accessor property writes it through its getter and setter instead.
+     */
     name: string;
+    /**
+     * The doc comment written above the property, or `null` to omit it. It is written as given, so no tags are added.
+     */
     doc: TsDoc<TBuilder> | null;
+    /**
+     * The decorators written before the property. They are separated by spaces and written on the same line as the
+     * property, such as `@decorator x;`.
+     */
     decorators: TsDecorator<TBuilder>[];
+    /**
+     * The type annotation written after the name, such as `: number`, or `null` to omit it. A simple property also omits
+     * the annotation inside an object literal, which has none.
+     */
     type: TsType<TBuilder> | null;
+    /**
+     * The access modifier written before the property, such as `public`, or `null` to omit it.
+     */
     accessModifier: TsAccessModifier | null;
+    /**
+     * Whether the property is written with the `static` keyword. `null` and `false` both omit the keyword.
+     * @default null
+     */
     static: boolean | null;
+    /**
+     * Whether the property is written with the `abstract` keyword. `null` and `false` both omit the keyword.
+     * @default null
+     */
     abstract: boolean | null;
+    /**
+     * Whether the property is written with the `override` keyword. `null` and `false` both omit the keyword.
+     * @default null
+     */
     override: boolean | null;
+    /**
+     * Initializes a new instance of the TsProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: BaseOptions<TBuilder, TInjects>);
 }
+/**
+ * Represents a property with a name, an optional type and an optional value, such as `readonly x?: number = 42;`.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`,
+ * `readonly`), name, optional marker, type annotation, value, and a terminator. Inside an object literal (`tsObject`),
+ * the property is written as `x: 42,` instead: the type annotation is omitted, the value follows a colon, and a comma
+ * ends the property.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsProperty
+ */
 export declare class TsSimpleProperty<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsProperty<TBuilder, TInjects> {
+    /**
+     * The initial value of the property, or `null` to omit it. In a class it is written after ` = `, such as `x = 42;`,
+     * and in an object literal after a colon, such as `x: 42,`. Falsy values are not written.
+     */
     value: TsValue<TBuilder> | null;
+    /**
+     * Whether the property is written with the `readonly` keyword, which is placed after the other modifiers.
+     * @default false
+     */
     readonly: boolean;
+    /**
+     * Whether the name is followed by `?`, which marks the property as optional, such as `x?: number`.
+     * @default false
+     */
     optional: boolean;
+    /**
+     * Initializes a new instance of the TsSimpleProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: SimpleOptions<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
+/**
+ * Represents a property that is written as a getter, a setter, or both, such as `get x(): number` and `set x(value)`.
+ *
+ * The property writes its doc comment and decorators first, then its getter, and then its setter. The accessors take
+ * their name, type and modifiers from this property when those are set here.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsProperty
+ * @see TsPropertyGetter
+ * @see TsPropertySetter
+ */
 export declare class TsAccessorProperty<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsProperty<TBuilder, TInjects> {
     private _get;
     private _set;
+    /**
+     * The getter of the property, or `null` to omit it. Assigning a getter links it to this property, so the getter takes
+     * its name, type and modifiers from here. A getter that was assigned before is unlinked.
+     */
     get get(): TsPropertyGetter<TBuilder> | null;
     set get(value: TsPropertyGetter<TBuilder> | null);
+    /**
+     * The setter of the property, or `null` to omit it. Assigning a setter links it to this property, so the setter takes
+     * its name, type and modifiers from here. A setter that was assigned before is unlinked.
+     */
     get set(): TsPropertySetter<TBuilder> | null;
     set set(value: TsPropertySetter<TBuilder> | null);
+    /**
+     * Initializes a new instance of the TsAccessorProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: AccessorOptions<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createProperty: <TBuilder extends SourceBuilder>(name: BaseOptions<TBuilder>['name'], options?: Prettify<Omit<SimpleOptions<TBuilder>, 'name'>> | Prettify<Omit<AccessorOptions<TBuilder>, 'name'>>) => TsProperty<TBuilder>;
+/**
+ * Factory for creating property nodes. The `write` function writes one or more property nodes to a builder. The
+ * `getter` and `setter` functions create the accessors that are passed to an accessor property.
+ *
+ * Passing `get` or `set` in the options creates a `TsAccessorProperty`. Otherwise a `TsSimpleProperty` is created.
+ *
+ * @param name The name of the property. See `TsProperty.name`.
+ * @param options The settings of the property. See `TsSimpleProperty` and `TsAccessorProperty` for the available
+ * properties.
+ * @example
+ * ```ts
+ * tsProperty('x', { type: 'number', value: 42, readonly: true, accessModifier: 'public' });
+ * // Emits:
+ * // public readonly x: number = 42;
+ * ```
+ */
 export declare const tsProperty: typeof createProperty & {
     write: typeof writeTsNodes;
     getter: typeof createPropertyGetter;

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

@@ -6,15 +6,60 @@ import { tsDoc } from './doc.js';
 import { TsObject } from './object.js';
 import { createPropertyGetter, createPropertySetter, } from './property-accessor.js';
 import { tsString } from './string.js';
+/**
+ * Base class for the properties of classes and object literals. It holds the parts that all properties share: the name,
+ * the doc comment, the decorators, the type and the modifiers.
+ *
+ * Use `tsProperty` to create a property. It returns a `TsSimpleProperty` for a plain property, and a
+ * `TsAccessorProperty` when getters or setters are passed in its options.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsProperty
+ */
 export class TsProperty extends TsNode {
+    /**
+     * The name of the property. A simple property writes it verbatim, or in quotes when it is not a plain identifier,
+     * such as `'x y'`. An accessor property writes it through its getter and setter instead.
+     */
     name;
+    /**
+     * The doc comment written above the property, or `null` to omit it. It is written as given, so no tags are added.
+     */
     doc;
+    /**
+     * The decorators written before the property. They are separated by spaces and written on the same line as the
+     * property, such as `@decorator x;`.
+     */
     decorators;
+    /**
+     * The type annotation written after the name, such as `: number`, or `null` to omit it. A simple property also omits
+     * the annotation inside an object literal, which has none.
+     */
     type;
+    /**
+     * The access modifier written before the property, such as `public`, or `null` to omit it.
+     */
     accessModifier;
+    /**
+     * Whether the property is written with the `static` keyword. `null` and `false` both omit the keyword.
+     * @default null
+     */
     static;
+    /**
+     * Whether the property is written with the `abstract` keyword. `null` and `false` both omit the keyword.
+     * @default null
+     */
     abstract;
+    /**
+     * Whether the property is written with the `override` keyword. `null` and `false` both omit the keyword.
+     * @default null
+     */
     override;
+    /**
+     * Initializes a new instance of the TsProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.name = options.name;
@@ -27,10 +72,38 @@ export class TsProperty extends TsNode {
         this.override = options.override ?? null;
     }
 }
+/**
+ * Represents a property with a name, an optional type and an optional value, such as `readonly x?: number = 42;`.
+ *
+ * Written in this order: doc comment, decorators, modifiers (access modifier, `static`, `abstract`, `override`,
+ * `readonly`), name, optional marker, type annotation, value, and a terminator. Inside an object literal (`tsObject`),
+ * the property is written as `x: 42,` instead: the type annotation is omitted, the value follows a colon, and a comma
+ * ends the property.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsProperty
+ */
 export class TsSimpleProperty extends TsProperty {
+    /**
+     * The initial value of the property, or `null` to omit it. In a class it is written after ` = `, such as `x = 42;`,
+     * and in an object literal after a colon, such as `x: 42,`. Falsy values are not written.
+     */
     value;
+    /**
+     * Whether the property is written with the `readonly` keyword, which is placed after the other modifiers.
+     * @default false
+     */
     readonly;
+    /**
+     * Whether the name is followed by `?`, which marks the property as optional, such as `x?: number`.
+     * @default false
+     */
     optional;
+    /**
+     * Initializes a new instance of the TsSimpleProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.value = options.value ?? null;
@@ -66,9 +139,25 @@ export class TsSimpleProperty extends TsProperty {
         builder.appendLine();
     }
 }
+/**
+ * Represents a property that is written as a getter, a setter, or both, such as `get x(): number` and `set x(value)`.
+ *
+ * The property writes its doc comment and decorators first, then its getter, and then its setter. The accessors take
+ * their name, type and modifiers from this property when those are set here.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsProperty
+ * @see TsPropertyGetter
+ * @see TsPropertySetter
+ */
 export class TsAccessorProperty extends TsProperty {
     _get = null;
     _set = null;
+    /**
+     * The getter of the property, or `null` to omit it. Assigning a getter links it to this property, so the getter takes
+     * its name, type and modifiers from here. A getter that was assigned before is unlinked.
+     */
     get get() {
         return this._get;
     }
@@ -81,6 +170,10 @@ export class TsAccessorProperty extends TsProperty {
         }
         this._get = value;
     }
+    /**
+     * The setter of the property, or `null` to omit it. Assigning a setter links it to this property, so the setter takes
+     * its name, type and modifiers from here. A setter that was assigned before is unlinked.
+     */
     get set() {
         return this._set;
     }
@@ -93,6 +186,10 @@ export class TsAccessorProperty extends TsProperty {
         }
         this._set = value;
     }
+    /**
+     * Initializes a new instance of the TsAccessorProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.get = options.get ?? null;
@@ -114,6 +211,22 @@ const createProperty = (name, options) => {
     }
     return new TsSimpleProperty({ ...options, name });
 };
+/**
+ * Factory for creating property nodes. The `write` function writes one or more property nodes to a builder. The
+ * `getter` and `setter` functions create the accessors that are passed to an accessor property.
+ *
+ * Passing `get` or `set` in the options creates a `TsAccessorProperty`. Otherwise a `TsSimpleProperty` is created.
+ *
+ * @param name The name of the property. See `TsProperty.name`.
+ * @param options The settings of the property. See `TsSimpleProperty` and `TsAccessorProperty` for the available
+ * properties.
+ * @example
+ * ```ts
+ * tsProperty('x', { type: 'number', value: 42, readonly: true, accessModifier: 'public' });
+ * // Emits:
+ * // public readonly x: number = 42;
+ * ```
+ */
 export const tsProperty = Object.assign(createProperty, {
     write: writeTsNodes,
     getter: createPropertyGetter,