@goast/typescript 0.4.3 → 0.4.4

package/src/src/ast/nodes/doc-tag.test.ts

@@ -0,0 +1,40 @@
+import "../../../_dnt.test_polyfills.js";
+import { EOL } from 'node:os';
+
+import { expect } from '../../../deps/jsr.io/@std/expect/1.0.12/expect.js';
+import { beforeEach, it } from '../../../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+
+import { TypeScriptFileBuilder } from '../../file-builder.js';
+import { tsDocTag } from './doc-tag.js';
+
+let builder: TypeScriptFileBuilder;
+
+beforeEach(() => {
+  builder = new TypeScriptFileBuilder();
+});
+
+it('should write a custom tag', () => {
+  builder
+    .appendLine(tsDocTag('custom'))
+    .appendLine(tsDocTag('custom', { type: 'number' }))
+    .appendLine(tsDocTag('custom', { text: 'description' }))
+    .append(tsDocTag('custom', { type: 'number', text: 'description' }));
+  expect(builder.toString(false)).toBe(
+    `@custom${EOL}@custom {number}${EOL}@custom description${EOL}@custom {number} description`,
+  );
+});
+
+it('should render injections', () => {
+  builder.append(tsDocTag('custom', { inject: { before: ['before'], after: ['after'] } }));
+  expect(builder.toString(false)).toBe(`before@customafter`);
+});
+
+it('should write author tag', () => {
+  builder.appendLine(tsDocTag('author', 'John Doe')).append(tsDocTag('author', 'John Doe', 'john.doe@gmail.com'));
+  expect(builder.toString(false)).toBe(`@author John Doe${EOL}@author John Doe <john.doe@gmail.com>`);
+});
+
+it('should write access tag', () => {
+  builder.append(tsDocTag('access', 'public'));
+  expect(builder.toString(false)).toBe('@access public');
+});

package/src/src/ast/nodes/doc-tag.ts

@@ -0,0 +1,291 @@
+import {
+  type AstNodeOptions,
+  type BasicAppendValue,
+  basicAppendValueGroup,
+  notNullish,
+  type Nullable,
+  type ParametersWithOverloads,
+  type Prettify,
+  type SourceBuilder,
+  type StringSuggestions,
+} from '@goast/core';
+
+import { isTypeScriptAppendValue } from '../../file-builder.js';
+import { TsNode } from '../node.js';
+import { writeTsNode, writeTsNodes } from '../utils/write-ts-nodes.js';
+import type { TsType } from './types.js';
+
+type Injects = never;
+
+type Options<TBuilder extends SourceBuilder, TInjects extends string = never> = AstNodeOptions<
+  typeof TsNode<TBuilder, TInjects | Injects>,
+  {
+    tag: string;
+    type?: Nullable<TsType<TBuilder>>;
+    text?: Nullable<BasicAppendValue<TBuilder>>;
+  }
+>;
+
+export class TsDocTag<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<
+  TBuilder,
+  TInjects | Injects
+> {
+  public tag: string;
+  public type: TsType<TBuilder> | null;
+  public text: BasicAppendValue<TBuilder> | null;
+
+  constructor(options: Options<TBuilder, TInjects>) {
+    super(options);
+    this.tag = options.tag;
+    this.type = options.type ?? null;
+    this.text = options.text ?? null;
+  }
+
+  protected override onWrite(builder: TBuilder): void {
+    builder.append('@', this.tag);
+
+    if (this.type) {
+      builder.append(' ');
+      builder.parenthesize('{}', (b) => writeTsNode(b, this.type));
+    }
+
+    if (this.text) {
+      builder.append(' ', this.text);
+    }
+  }
+}
+
+type _TsDocTagOpt<TBuilder extends SourceBuilder> = Prettify<Omit<Options<TBuilder>, 'tag'>>;
+
+type _TsDocTagArgsMap<TBuilder extends SourceBuilder> =
+  & {
+    access(
+      access: StringSuggestions<'package' | 'private' | 'protected' | 'public'>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    author(authorName: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    author(
+      authorName: BasicAppendValue<TBuilder>,
+      emailAddress: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    borrows(
+      thatNamepath: BasicAppendValue<TBuilder>,
+      thisNamepath: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    params(
+      paramName: BasicAppendValue<TBuilder>,
+      paramDescription: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    example(
+      caption: BasicAppendValue<TBuilder>,
+      code: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    example(code: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    exports(
+      moduleName: BasicAppendValue<TBuilder>,
+      exportName: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    kind(
+      kindName: StringSuggestions<
+        | 'class'
+        | 'constant'
+        | 'event'
+        | 'external'
+        | 'file'
+        | 'function'
+        | 'member'
+        | 'mixin'
+        | 'module'
+        | 'namespace'
+        | 'typedef'
+      >,
+      options?: _TsDocTagOpt<TBuilder>,
+    ): never;
+    license(identifier: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    listens(eventName: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    mixes(otherObjectPath: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    mixin(mixinName: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    requires(moduleName: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    variation(variationNumber: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+  }
+  & {
+    [K in 'virtual' | 'abstract']: (options?: _TsDocTagOpt<TBuilder>) => never;
+  }
+  & {
+    [K in 'alias' | 'augments' | 'callback' | 'extends' | 'lends' | 'name' | 'see' | 'this']: (
+      namePath: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ) => never;
+  }
+  & {
+    [
+      K in
+        | 'async'
+        | 'generator'
+        | 'global'
+        | 'hideconstructor'
+        | 'ignore'
+        | 'inheritdoc'
+        | 'inner'
+        | 'instance'
+        | 'override'
+        | 'static'
+        | 'enum'
+        | 'package'
+        | 'private'
+        | 'protected'
+        | 'implements'
+        | 'type'
+    ]: (options?: _TsDocTagOpt<TBuilder>) => never;
+  }
+  & {
+    [
+      K in
+        | 'class'
+        | 'constructor'
+        | 'const'
+        | 'function'
+        | 'func'
+        | 'method'
+        | 'constant'
+        | 'member'
+        | 'constructs'
+        | 'interface'
+        | 'var'
+        | 'yield'
+        | 'yields'
+        | 'module'
+        | 'namespace'
+        | 'typedef'
+    ]: {
+      (name: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+      (options?: _TsDocTagOpt<TBuilder>): never;
+    };
+  }
+  & {
+    [
+      K in
+        | 'return'
+        | 'returns'
+        | 'throws'
+        | 'exception'
+        | 'classdesc'
+        | 'copyright'
+        | 'deprecated'
+        | 'desc'
+        | 'description'
+        | 'file'
+        | 'fileoverview'
+        | 'overview'
+        | 'public'
+        | 'readonly'
+        | 'since'
+        | 'summary'
+        | 'todo'
+        | 'tutorial'
+        | 'version'
+    ]: {
+      (description: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+      (options?: _TsDocTagOpt<TBuilder>): never;
+    };
+  }
+  & {
+    [K in 'default' | 'defaultvalue']: {
+      (value: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+      (options?: _TsDocTagOpt<TBuilder>): never;
+    };
+  }
+  & {
+    [K in 'event' | 'fires']: (
+      className: BasicAppendValue<TBuilder>,
+      eventName: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ) => never;
+  }
+  & {
+    [K in 'external' | 'host']: (nameOfExternal: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>) => never;
+  }
+  & {
+    [K in 'memberof' | 'memberof!']: (
+      parentNamepath: BasicAppendValue<TBuilder>,
+      options?: _TsDocTagOpt<TBuilder>,
+    ) => never;
+  }
+  & {
+    [K in 'param' | 'arg' | 'argument' | 'prop' | 'property' | 'template']: {
+      (
+        name: BasicAppendValue<TBuilder>,
+        description: BasicAppendValue<TBuilder>,
+        options?: _TsDocTagOpt<TBuilder>,
+      ): never;
+      (name: BasicAppendValue<TBuilder>, options?: _TsDocTagOpt<TBuilder>): never;
+    };
+  };
+
+type _TsDocTagArgs<
+  TTagName extends StringSuggestions<keyof _TsDocTagArgsMap<TBuilder>>,
+  TBuilder extends SourceBuilder,
+> = TTagName extends keyof _TsDocTagArgsMap<TBuilder>
+  // deno-lint-ignore no-explicit-any
+  ? _TsDocTagArgsMap<TBuilder>[TTagName] extends (...args: any[]) => any
+    ? ParametersWithOverloads<_TsDocTagArgsMap<TBuilder>[TTagName]>
+  : never
+  : [options?: _TsDocTagOpt<TBuilder>];
+
+function createDocTag<
+  TTagName extends StringSuggestions<keyof _TsDocTagArgsMap<TBuilder>>,
+  TBuilder extends SourceBuilder,
+>(
+  tag: TTagName,
+  ...args: _TsDocTagArgs<TTagName, TBuilder>
+): TsDocTag<TBuilder>;
+// deno-lint-ignore no-explicit-any
+function createDocTag<TBuilder extends SourceBuilder>(tag: string, ...args: any[]): TsDocTag<TBuilder> {
+  let opt: _TsDocTagOpt<TBuilder> = {};
+  if (args.length > 0) {
+    const lastArg = args[args.length - 1];
+    if (!isTypeScriptAppendValue(lastArg) && !!lastArg) {
+      opt = args.pop() as _TsDocTagOpt<TBuilder>;
+    }
+  }
+
+  let params = args as BasicAppendValue<TBuilder>[];
+
+  if (tag === 'author' && params.length === 2) {
+    params[1] = `<${params[1]}>`;
+  }
+
+  if (tag === 'borrows') {
+    params.splice(1, 0, 'as');
+  }
+
+  if (tag === 'example') {
+    if (typeof params[0] === 'string') {
+      params[0] = `<caption>${params[0]}</caption>`;
+    }
+    if (params[1] && isTypeScriptAppendValue(params[1])) {
+      params.splice(1, 0, '\n');
+    }
+  }
+
+  if ((tag === 'event' || tag === 'fires') && typeof params[0] === 'string' && typeof params[1] === 'string') {
+    params.splice(0, 2, `${params[0]}#${params[1]}`);
+  }
+
+  params = [...params, opt.text].filter(notNullish);
+  return new TsDocTag({
+    tag,
+    type: opt.type,
+    text: params.length > 0 ? basicAppendValueGroup<TBuilder>(params, ' ') : null,
+    inject: opt.inject,
+  });
+}
+
+export const tsDocTag: typeof createDocTag & { write: typeof writeTsNodes } = Object.assign(createDocTag, {
+  write: writeTsNodes,
+});

package/src/src/ast/nodes/doc.test.ts

@@ -0,0 +1,40 @@
+import "../../../_dnt.test_polyfills.js";
+import { EOL } from 'node:os';
+
+import { expect } from '../../../deps/jsr.io/@std/expect/1.0.12/expect.js';
+import { beforeEach, it } from '../../../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+
+import { TypeScriptFileBuilder } from '../../file-builder.js';
+import { tsDocTag } from './doc-tag.js';
+import { tsDoc } from './doc.js';
+
+let builder: TypeScriptFileBuilder;
+
+beforeEach(() => {
+  builder = new TypeScriptFileBuilder();
+});
+
+it('should not write anything if the node is empty', () => {
+  builder.append(tsDoc());
+  expect(builder.toString(false)).toBe('');
+});
+
+it('should write description', () => {
+  builder.append(tsDoc({ description: 'description' }));
+  expect(builder.toString(false)).toBe(`/**${EOL} * description${EOL} */${EOL}`);
+});
+
+it('should write tags', () => {
+  builder.append(tsDoc({ tags: [tsDocTag('tag1'), tsDocTag('tag2')] }));
+  expect(builder.toString(false)).toBe(`/**${EOL} * @tag1${EOL} * @tag2${EOL} */${EOL}`);
+});
+
+it('should write all the parts of the node', () => {
+  builder.append(tsDoc({ description: 'description', tags: [tsDocTag('tag1'), tsDocTag('tag2')] }));
+  expect(builder.toString(false)).toBe(`/**${EOL} * description${EOL} *${EOL} * @tag1${EOL} * @tag2${EOL} */${EOL}`);
+});
+
+it('should render injections', () => {
+  builder.append(tsDoc({ description: 'hello', inject: { before: ['before'], after: ['after'] } }));
+  expect(builder.toString(false)).toBe(`before${EOL}/**${EOL} * hello${EOL} */${EOL}after`);
+});

package/src/src/ast/nodes/doc.ts

@@ -0,0 +1,102 @@
+import {
+  type AstNodeOptions,
+  type BasicAppendValue,
+  createOverwriteProxy,
+  getIsInstanceOf,
+  notNullish,
+  type Nullable,
+  type SourceBuilder,
+} from '@goast/core';
+
+import { TsNode } from '../node.js';
+import { writeTsNodes } from '../utils/write-ts-nodes.js';
+import { type TsDocTag, tsDocTag } from './doc-tag.js';
+import { TsGenericParameter } from './generic-parameter.js';
+import { TsParameter } from './parameter.js';
+
+type Injects = never;
+
+type Options<TBuilder extends SourceBuilder, TInjects extends string = never> = AstNodeOptions<
+  typeof TsNode<TBuilder, TInjects | Injects>,
+  {
+    description?: Nullable<BasicAppendValue<TBuilder>>;
+    tags?: Nullable<Nullable<TsDocTag<TBuilder>>[]>;
+  }
+>;
+
+export class TsDoc<TBuilder extends SourceBuilder, TInjects extends string = never>
+  extends TsNode<TBuilder, TInjects | Injects> {
+  public description: BasicAppendValue<TBuilder> | null;
+  public tags: TsDocTag<TBuilder>[];
+
+  constructor(options: Options<TBuilder, TInjects>) {
+    super(options);
+    this.description = options.description ?? null;
+    this.tags = options.tags?.filter(notNullish) ?? [];
+  }
+
+  protected override onWrite(builder: TBuilder): void {
+    if (!this.description && this.tags.length === 0) {
+      return;
+    }
+
+    builder
+      .ensureCurrentLineEmpty()
+      .parenthesize(
+        ['/**', ' */'],
+        (b) =>
+          b.appendWithLinePrefix(' * ', (b) => {
+            if (this.description) {
+              b.append(this.description);
+            }
+
+            if (this.tags.length > 0) {
+              b.ensurePreviousLineEmpty();
+              tsDocTag.write(b, this.tags, { separator: '\n' });
+            }
+          }),
+        { multiline: true, indent: false },
+      )
+      .appendLine();
+  }
+}
+
+const createDoc = <TBuilder extends SourceBuilder>(options?: Options<TBuilder>): TsDoc<TBuilder> =>
+  new TsDoc<TBuilder>(options ?? {});
+
+function getDoc<TBuilder extends SourceBuilder>(
+  baseDoc: TsDoc<TBuilder> | null,
+  options: {
+    parameters?: Nullable<Nullable<TsParameter<TBuilder> | BasicAppendValue<TBuilder>>[]>;
+    generics?: Nullable<Nullable<TsGenericParameter<TBuilder> | BasicAppendValue<TBuilder>>[]>;
+  },
+): TsDoc<TBuilder> | null {
+  const paramsWithDesc = options.parameters
+    ?.filter(getIsInstanceOf(TsParameter<TBuilder>))
+    .filter((x): x is TsParameter<TBuilder> & { description: NonNullable<unknown> } => !!x.description) ?? [];
+  const genericsWithDesc = options.generics
+    ?.filter(getIsInstanceOf(TsGenericParameter<TBuilder>))
+    .filter((x): x is TsGenericParameter<TBuilder> & { description: NonNullable<unknown> } => !!x.description) ?? [];
+  if (paramsWithDesc.length === 0 && genericsWithDesc.length === 0) {
+    return baseDoc;
+  }
+  const doc = baseDoc ? createOverwriteProxy(baseDoc) : createDoc<TBuilder>();
+  const paramTags = paramsWithDesc.map<TsDocTag<TBuilder>>((p) => tsDocTag('param', p.name, p.description));
+  const genericTags = genericsWithDesc.map<TsDocTag<TBuilder>>((p) => tsDocTag('template', p.name, p.description));
+  doc.tags.splice(0, 0, ...genericTags, ...paramTags);
+  return doc;
+}
+
+function isDocEmpty(doc: Nullable<TsDoc<SourceBuilder>>): boolean {
+  return !doc || (!doc.description && doc.tags.length === 0);
+}
+
+export const tsDoc: typeof createDoc & {
+  write: typeof writeTsNodes;
+  get: typeof getDoc;
+  isEmpty: typeof isDocEmpty;
+} = Object.assign(createDoc, {
+  write: writeTsNodes,
+  get: getDoc,
+  isEmpty: isDocEmpty,
+});

package/src/src/ast/nodes/enum-value.test.ts

@@ -0,0 +1,66 @@
+import "../../../_dnt.test_polyfills.js";
+import { EOL } from 'node:os';
+
+import { expect } from '../../../deps/jsr.io/@std/expect/1.0.12/expect.js';
+import { beforeEach, describe, it } from '../../../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+
+import { TypeScriptFileBuilder } from '../../file-builder.js';
+import { tsDoc } from './doc.js';
+import { tsEnumValue } from './enum-value.js';
+
+let builder: TypeScriptFileBuilder;
+
+beforeEach(() => {
+  builder = new TypeScriptFileBuilder();
+});
+
+describe('tsEnumValue', () => {
+  it('should write the name of the enum value', () => {
+    builder.append(tsEnumValue('x'));
+    expect(builder.toString(false)).toBe('x');
+  });
+
+  it('should write the value if it exists', () => {
+    builder.append(tsEnumValue('x', { value: '42' }));
+    expect(builder.toString(false)).toBe('x = 42');
+  });
+
+  it('should write documentation if it exists', () => {
+    builder.append(tsEnumValue('x', { doc: tsDoc({ description: 'description' }) }));
+    expect(builder.toString(false)).toBe(`/**${EOL} * description${EOL} */${EOL}x`);
+  });
+
+  it('should write all the parts of the enum value', () => {
+    builder.append(tsEnumValue('x', { value: '42', doc: tsDoc({ description: 'description' }) }));
+    expect(builder.toString(false)).toBe(`/**${EOL} * description${EOL} */${EOL}x = 42`);
+  });
+
+  it('should write injections', () => {
+    builder.append(
+      tsEnumValue('x', {
+        value: '42',
+        doc: tsDoc({ description: 'description' }),
+        inject: {
+          before: '║b║',
+          after: '║a║',
+          beforeDoc: '║bd║',
+          afterDoc: '║ad║',
+          beforeName: '║bn║',
+          afterName: '║an║',
+          beforeValue: '║bv║',
+          afterValue: '║av║',
+        },
+      }),
+    );
+    expect(builder.toString(false)).toBe(
+      `║b║║bd║${EOL}/**${EOL} * description${EOL} */${EOL}║ad║║bn║x║an║ = ║bv║42║av║║a║`,
+    );
+  });
+
+  describe('write', () => {
+    it('should write multiple enum values', () => {
+      tsEnumValue.write(builder, [tsEnumValue('x', { value: '42' }), tsEnumValue('y', { value: '43' })]);
+      expect(builder.toString(false)).toBe(`x = 42,${EOL}y = 43`);
+    });
+  });
+});

package/src/src/ast/nodes/enum-value.ts

@@ -0,0 +1,72 @@
+import type {
+  AppendValue,
+  AstNodeOptions,
+  BasicAppendValue,
+  Nullable,
+  Prettify,
+  SingleOrMultiple,
+  SourceBuilder,
+} from '@goast/core';
+
+import { TsNode } from '../node.js';
+import { writeTsNode, writeTsNodes } from '../utils/write-ts-nodes.js';
+import type { TsDoc } from './doc.js';
+import type { TsString } from './string.js';
+
+type Injects = 'doc' | 'name' | 'value';
+
+type Options<TBuilder extends SourceBuilder, TInjects extends string = never> = AstNodeOptions<
+  typeof TsNode<TBuilder, TInjects | Injects>,
+  {
+    doc?: Nullable<TsDoc<TBuilder>>;
+    name: string;
+    value?: Nullable<TsString<TBuilder> | BasicAppendValue<TBuilder>>;
+  }
+>;
+
+export class TsEnumValue<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<
+  TBuilder,
+  TInjects | Injects
+> {
+  public doc: TsDoc<TBuilder> | null;
+  public name: string;
+  public value: TsString<TBuilder> | BasicAppendValue<TBuilder> | null;
+
+  constructor(options: Options<TBuilder, TInjects>) {
+    super(options);
+    this.name = options.name;
+    this.doc = options.doc ?? null;
+    this.value = options.value ?? null;
+  }
+
+  protected override onWrite(builder: TBuilder): void {
+    builder.append(this.inject.beforeDoc);
+    this.doc?.write(builder);
+    builder.append(this.inject.afterDoc);
+
+    builder.append(this.inject.beforeName, this.name, this.inject.afterName);
+
+    if (this.value) {
+      builder.append(' = ');
+      builder.append(this.inject.beforeValue);
+      writeTsNode(builder, this.value);
+      builder.append(this.inject.afterValue);
+    }
+  }
+}
+
+const createEnumValue = <TBuilder extends SourceBuilder>(
+  name: Options<TBuilder>['name'],
+  options?: Prettify<Omit<Options<TBuilder>, 'name'>>,
+): TsEnumValue<TBuilder> => new TsEnumValue<TBuilder>({ ...options, name });
+
+const writeEnumValues = <TBuilder extends SourceBuilder>(
+  builder: TBuilder,
+  nodes: SingleOrMultiple<Nullable<TsEnumValue<TBuilder> | AppendValue<TBuilder>>>,
+): void => {
+  writeTsNodes(builder, nodes, { separator: ',\n' });
+};
+
+export const tsEnumValue: typeof createEnumValue & { write: typeof writeEnumValues } = Object.assign(createEnumValue, {
+  write: writeEnumValues,
+});