@goast/typescript 0.4.3 → 0.5.0

package/src/src/ast/nodes/union-type.ts

@@ -0,0 +1,62 @@
+import { type AstNodeOptions, notNullish, type Nullable, type Prettify, type SourceBuilder } from '@goast/core';
+
+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>,
+  {
+    types: Nullable<TsType<TBuilder>>[];
+  }
+>;
+
+export class TsUnionType<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<
+  TBuilder,
+  TInjects | Injects
+> {
+  public types: TsType<TBuilder>[];
+
+  constructor(options: Options<TBuilder, TInjects>) {
+    super(options);
+    this.types = options.types.filter(notNullish);
+  }
+
+  protected override onWrite(builder: TBuilder): void {
+    const types = this.types.length === 0 ? ['never'] : resolveNestedUnionTypes(this);
+    if (types.length === 1) {
+      writeTsNode(builder, types[0]);
+    } else {
+      const multiline = types.length > 3;
+      if (multiline) {
+        builder.appendLine().append('| ');
+      }
+      builder.forEach(types, (b, t) => b.parenthesize('()', (b) => writeTsNode(b, t)), {
+        separator: multiline ? '\n| ' : ' | ',
+      });
+    }
+  }
+}
+
+const createUnionType = <TBuilder extends SourceBuilder>(
+  types: Options<TBuilder>['types'],
+  options?: Prettify<Omit<Options<TBuilder>, 'types'>>,
+): TsUnionType<TBuilder> => new TsUnionType<TBuilder>({ ...options, types });
+
+export const tsUnionType: typeof createUnionType & { write: typeof writeTsNodes } = Object.assign(createUnionType, {
+  write: writeTsNodes,
+});
+
+function resolveNestedUnionTypes<TBuilder extends SourceBuilder>(node: TsUnionType<TBuilder>): TsType<TBuilder>[] {
+  const types: TsType<TBuilder>[] = [];
+  for (const type of node.types) {
+    if (type instanceof TsUnionType) {
+      types.push(...resolveNestedUnionTypes(type));
+    } else {
+      types.push(type);
+    }
+  }
+  return types;
+}

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

@@ -0,0 +1,49 @@
+import "../../../_dnt.test_polyfills.js";
+import { EOL } from 'node:os';
+
+import { expect } from '../../../deps/jsr.io/@std/expect/1.0.13/expect.js';
+import { beforeEach, it } from '../../../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+
+import { TypeScriptFileBuilder } from '../../file-builder.js';
+import { tsVariable } from './variable.js';
+
+let builder: TypeScriptFileBuilder;
+
+beforeEach(() => {
+  builder = new TypeScriptFileBuilder();
+});
+
+it('should write the name of the variable', () => {
+  builder.append(tsVariable('x'));
+  expect(builder.toString(false)).toBe('let x;' + EOL);
+});
+
+it('should write the type if it exists', () => {
+  builder.append(tsVariable('x', { type: 'number' }));
+  expect(builder.toString(false)).toBe('let x: number;' + EOL);
+});
+
+it('should write the value if it exists', () => {
+  builder.append(tsVariable('x', { value: 42 }));
+  expect(builder.toString(false)).toBe('let x = 42;' + EOL);
+});
+
+it('should write the const keyword if configured', () => {
+  builder.append(tsVariable('x', { readonly: true }));
+  expect(builder.toString(false)).toBe('const x;' + EOL);
+});
+
+it('should write the export keyword if configured', () => {
+  builder.append(tsVariable('x', { export: true }));
+  expect(builder.toString(false)).toBe('export let x;' + EOL);
+});
+
+it('should write all the parts of the variable', () => {
+  builder.append(tsVariable('x', { type: 'number', value: 42, readonly: true, export: true }));
+  expect(builder.toString(false)).toBe('export const x: number = 42;' + EOL);
+});
+
+it('should render injections', () => {
+  builder.append(tsVariable('x', { inject: { before: ['before'], after: ['after'] } }));
+  expect(builder.toString(false)).toBe(`beforelet x;${EOL}after`);
+});

package/src/src/ast/nodes/variable.ts

@@ -0,0 +1,73 @@
+import type { AstNodeOptions, Nullable, Prettify, 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 { TsType, TsValue } from './types.js';
+
+type Injects = never;
+
+type Options<TBuilder extends SourceBuilder, TInjects extends string = never> = AstNodeOptions<
+  typeof TsNode<TBuilder, TInjects | Injects>,
+  {
+    name: string;
+    doc?: Nullable<TsDoc<TBuilder>>;
+    type?: Nullable<TsType<TBuilder>>;
+    value?: Nullable<TsValue<TBuilder>>;
+    export?: Nullable<boolean>;
+    readonly?: Nullable<boolean>;
+  }
+>;
+
+export class TsVariable<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<
+  TBuilder,
+  TInjects | Injects
+> {
+  public name: string;
+  public doc: TsDoc<TBuilder> | null;
+  public type: TsType<TBuilder> | null;
+  public value: TsValue<TBuilder> | null;
+  public export: boolean;
+  public readonly: boolean;
+
+  constructor(options: Options<TBuilder, TInjects>) {
+    super(options);
+    this.name = options.name;
+    this.doc = options.doc ?? null;
+    this.type = options.type ?? null;
+    this.value = options.value ?? null;
+    this.export = options.export ?? false;
+    this.readonly = options.readonly ?? false;
+  }
+
+  protected override onWrite(builder: TBuilder): void {
+    if (this.doc) writeTsNode(builder, this.doc);
+    if (this.export) builder.append('export ');
+
+    builder.append(this.readonly ? 'const ' : 'let ');
+    builder.append(this.name);
+
+    if (this.type) {
+      builder.append(': ');
+      writeTsNode(builder, this.type);
+    }
+
+    if (this.value) {
+      builder.append(' = ');
+      writeTsNode(builder, this.value);
+    }
+
+    builder.append(';');
+
+    builder.appendLine();
+  }
+}
+
+const createVariable = <TBuilder extends SourceBuilder>(
+  name: Options<TBuilder>['name'],
+  options?: Prettify<Omit<Options<TBuilder>, 'name'>>,
+): TsVariable<TBuilder> => new TsVariable<TBuilder>({ ...options, name });
+
+export const tsVariable: typeof createVariable & { write: typeof writeTsNodes } = Object.assign(createVariable, {
+  write: writeTsNodes,
+});

package/src/src/ast/references/angular.ts

@@ -0,0 +1,24 @@
+import {
+  type TsGenericModuleReferenceFactory,
+  type TsModuleReferenceFactory,
+  tsReference,
+} from '../nodes/reference.js';
+
+// @angular/core
+export const inject: TsModuleReferenceFactory = tsReference.factory('inject', '@angular/core');
+export const injectable: TsModuleReferenceFactory = tsReference.factory('Injectable', '@angular/core');
+export const provider: TsModuleReferenceFactory = tsReference.factory('Provider', '@angular/core', {
+  importType: 'type-import',
+});
+
+// @angular/common/http
+export const httpClient: TsModuleReferenceFactory = tsReference.factory('HttpClient', '@angular/common/http');
+export const httpContext: TsModuleReferenceFactory = tsReference.factory('HttpContext', '@angular/common/http');
+export const httpResponse: TsGenericModuleReferenceFactory<1> = tsReference.genericFactory<1>(
+  'HttpResponse',
+  '@angular/common/http',
+);
+export const httpErrorResponse: TsModuleReferenceFactory = tsReference.factory(
+  'HttpErrorResponse',
+  '@angular/common/http',
+);

package/src/src/ast/references/easy-network-stub.ts

@@ -0,0 +1,21 @@
+import {
+  type TsGenericModuleReferenceFactory,
+  type TsModuleReferenceFactory,
+  tsReference,
+} from '../nodes/reference.js';
+
+export const easyNetworkStub: TsModuleReferenceFactory = tsReference.factory('EasyNetworkStub', 'easy-network-stub');
+export const httpMethod: TsModuleReferenceFactory = tsReference.factory('HttpMethod', 'easy-network-stub', {
+  importType: 'type-import',
+});
+export const routeResponseCallback: TsGenericModuleReferenceFactory<2> = tsReference.genericFactory<2>(
+  'RouteResponseCallback',
+  'easy-network-stub',
+  {
+    importType: 'type-import',
+  },
+);
+export const errorResponse: TsGenericModuleReferenceFactory<1> = tsReference.genericFactory<1>(
+  'ErrorResponse',
+  'easy-network-stub',
+);

package/src/src/ast/references/index.ts

@@ -0,0 +1,5 @@
+export * as angular from './angular.js';
+export * as easyNetworkStub from './easy-network-stub.js';
+export * as k6 from './k6.js';
+export * as rxjs from './rxjs.js';
+export * from './typescript.js';

package/src/src/ast/references/k6.ts

@@ -0,0 +1,8 @@
+import { type TsModuleReferenceFactory, tsReference } from '../nodes/reference.js';
+
+// k6
+export const jsonValue: TsModuleReferenceFactory = tsReference.factory('JSONValue', 'k6');
+
+// h6/http
+export const response: TsModuleReferenceFactory = tsReference.factory('Response', 'k6/http');
+export const params: TsModuleReferenceFactory = tsReference.factory('Params', 'k6/http');

package/src/src/ast/references/rxjs.ts

@@ -0,0 +1,7 @@
+import { type TsModuleReferenceFactory, tsReference } from '../nodes/reference.js';
+
+export const observable: TsModuleReferenceFactory = tsReference.factory('Observable', 'rxjs');
+export const firstValueFrom: TsModuleReferenceFactory = tsReference.factory('firstValueFrom', 'rxjs');
+export const filter: TsModuleReferenceFactory = tsReference.factory('filter', 'rxjs');
+export const map: TsModuleReferenceFactory = tsReference.factory('map', 'rxjs');
+export const take: TsModuleReferenceFactory = tsReference.factory('take', 'rxjs');

package/src/src/ast/references/typescript.ts

@@ -0,0 +1,35 @@
+import { type TsGenericReferenceFactory, tsReference, type TsReferenceFactory } from '../nodes/reference.js';
+
+export const any: TsReferenceFactory = tsReference.factory('any');
+export const unknown: TsReferenceFactory = tsReference.factory('unknown');
+export const void_: TsReferenceFactory = tsReference.factory('void');
+export const never: TsReferenceFactory = tsReference.factory('never');
+export const number: TsReferenceFactory = tsReference.factory('number');
+export const string: TsReferenceFactory = tsReference.factory('string');
+export const boolean: TsReferenceFactory = tsReference.factory('boolean');
+export const bigint: TsReferenceFactory = tsReference.factory('bigint');
+export const symbol: TsReferenceFactory = tsReference.factory('symbol');
+export const object: TsReferenceFactory = tsReference.factory('object');
+export const undefined_: TsReferenceFactory = tsReference.factory('undefined');
+export const null_: TsReferenceFactory = tsReference.factory('null');
+
+export const array: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Array');
+export const record: TsGenericReferenceFactory<2> = tsReference.genericFactory<2>('Record');
+export const map: TsGenericReferenceFactory<2> = tsReference.genericFactory<2>('Map');
+export const set: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Set');
+export const promise: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Promise');
+
+export const readonlyArray: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('ReadonlyArray');
+export const readonly: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Readonly');
+export const partial: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Partial');
+export const required: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Required');
+export const pick: TsGenericReferenceFactory<2> = tsReference.genericFactory<2>('Pick');
+export const omit: TsGenericReferenceFactory<2> = tsReference.genericFactory<2>('Omit');
+export const exclude: TsGenericReferenceFactory<2> = tsReference.genericFactory<2>('Exclude');
+export const extract: TsGenericReferenceFactory<2> = tsReference.genericFactory<2>('Extract');
+export const nonNullable: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('NonNullable');
+export const parameters: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('Parameters');
+export const returnType: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('ReturnType');
+export const instanceType: TsGenericReferenceFactory<1> = tsReference.genericFactory<1>('InstanceType');
+
+export const blob: TsReferenceFactory = tsReference.factory('Blob');

package/src/src/ast/utils/get-type-script-builder-options.ts

@@ -0,0 +1,19 @@
+import { defaultOpenApiGeneratorConfig, type SourceBuilder, type StringBuilder } from '@goast/core';
+
+import { defaultTypeScriptGeneratorConfig, type TypeScriptGeneratorConfig } from '../../config.js';
+import { TypeScriptFileBuilder } from '../../file-builder.js';
+
+const tsConfigSymbol = Symbol();
+type _BuilderWithConfig = SourceBuilder & { [tsConfigSymbol]?: TypeScriptGeneratorConfig };
+
+export function getTypeScriptBuilderOptions(builder: StringBuilder): TypeScriptGeneratorConfig {
+  if (builder instanceof TypeScriptFileBuilder) {
+    return builder.options;
+  }
+  if (tsConfigSymbol in builder.options) {
+    return builder.options[tsConfigSymbol] as TypeScriptGeneratorConfig;
+  }
+  const options = { ...defaultOpenApiGeneratorConfig, ...defaultTypeScriptGeneratorConfig, ...builder.options };
+  (builder as _BuilderWithConfig)[tsConfigSymbol] = options;
+  return options;
+}

package/src/src/ast/utils/to-ts-node.ts

@@ -0,0 +1,27 @@
+import type { BasicAppendValue, SourceBuilder } from '@goast/core';
+
+import { type TsObject, tsObject } from '../nodes/object.js';
+import { tsProperty } from '../nodes/property.js';
+import { type TsString, tsString } from '../nodes/string.js';
+import { type TsTuple, tsTuple } from '../nodes/tuple.js';
+
+export function toTsNode<TBuilder extends SourceBuilder>(object: Record<string, unknown>): TsObject<TBuilder>;
+export function toTsNode<TBuilder extends SourceBuilder>(tuple: unknown[]): TsTuple<TBuilder>;
+export function toTsNode<TBuilder extends SourceBuilder>(string: string): TsString<TBuilder>;
+export function toTsNode<TBuilder extends SourceBuilder>(value: unknown): BasicAppendValue<TBuilder>;
+export function toTsNode<TBuilder extends SourceBuilder>(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return tsTuple(value.map((x) => toTsNode<TBuilder>(x)));
+  }
+  if (typeof value === 'object' && value !== null) {
+    const result = tsObject<TBuilder>();
+    for (const [k, v] of Object.entries(value)) {
+      result.members.push(tsProperty(k, { value: toTsNode(v) }));
+    }
+    return result;
+  }
+  if (value === null || value === undefined || typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+  return tsString(String(value));
+}

package/src/src/ast/utils/write-ts-generic-parameters.ts

@@ -0,0 +1,25 @@
+import {
+  type AppendValue,
+  notNullish,
+  type Nullable,
+  type SingleOrMultiple,
+  type SourceBuilder,
+  toArray,
+} from '@goast/core';
+
+import type { TsNode } from '../node.js';
+import { writeTsNodes } from './write-ts-nodes.js';
+
+export function writeTsGenericParameters<TBuilder extends SourceBuilder>(
+  builder: TBuilder,
+  nodes: SingleOrMultiple<Nullable<TsNode<TBuilder> | AppendValue<TBuilder>>>,
+): void {
+  const filteredNodes = toArray(nodes).filter(notNullish);
+  const multiline = filteredNodes.length > 2;
+  builder.parenthesizeIf(
+    filteredNodes.length > 0,
+    '<>',
+    (b) => writeTsNodes(b, filteredNodes, { separator: multiline ? ',\n' : ', ' }),
+    { multiline },
+  );
+}

package/src/src/ast/utils/write-ts-members.ts

@@ -0,0 +1,28 @@
+import { type AppendValue, isAppendValue, notNullish, type Nullable, type SourceBuilder } from '@goast/core';
+
+import type { TsNode } from '../node.js';
+import { tsDoc } from '../nodes/doc.js';
+import { TsMethod } from '../nodes/method.js';
+import { TsProperty } from '../nodes/property.js';
+import { writeTsNode } from './write-ts-nodes.js';
+
+export function writeTsMembers<TBuilder extends SourceBuilder>(
+  builder: TBuilder,
+  members: Nullable<AppendValue<TBuilder> | TsNode<TBuilder>>[],
+  options?: { alreadyHasMembers?: boolean },
+): void {
+  const filteredMembers = members.filter(notNullish);
+  builder.forEach(filteredMembers, (b, m, i) =>
+    b.if(
+      () =>
+        !(m instanceof TsProperty && tsDoc.isEmpty(m.doc) && m.decorators.length === 0) &&
+        !(m instanceof TsMethod && !m.body && tsDoc.isEmpty(m.doc) && m.decorators.length === 0) &&
+        !isAppendValue(m),
+      (b) =>
+        b
+          .if(i > 0 || !!options?.alreadyHasMembers, (b) => b.ensurePreviousLineEmpty())
+          .append((b) => writeTsNode(b, m))
+          .if(i < filteredMembers.length - 1, (b) => b.ensurePreviousLineEmpty()),
+      (b) => b.append((b) => writeTsNode(b, m)).ensureCurrentLineEmpty(),
+    ));
+}

package/src/src/ast/utils/write-ts-nodes.ts

@@ -0,0 +1,35 @@
+import {
+  type AppendValue,
+  notNullish,
+  type Nullable,
+  type Separator,
+  type SingleOrMultiple,
+  type SourceBuilder,
+  toArray,
+} from '@goast/core';
+
+import { TsNode } from '../node.js';
+
+export function writeTsNode<TBuilder extends SourceBuilder>(
+  builder: TBuilder,
+  node: Nullable<AppendValue<TBuilder> | TsNode<TBuilder>>,
+): void {
+  if (node instanceof TsNode) {
+    node.write(builder);
+  } else {
+    builder.append(node);
+  }
+}
+
+export function writeTsNodes<TBuilder extends SourceBuilder>(
+  builder: TBuilder,
+  nodes: SingleOrMultiple<Nullable<AppendValue<TBuilder> | TsNode<TBuilder>>>,
+  options?: { separator?: Separator<TBuilder, AppendValue<TBuilder> | TsNode<TBuilder>> },
+): void {
+  const filteredNodes = toArray(nodes).filter(notNullish);
+  if (filteredNodes.length === 1) {
+    writeTsNode(builder, filteredNodes[0]);
+  } else if (filteredNodes.length > 1) {
+    builder.forEach(filteredNodes, writeTsNode, { separator: options?.separator });
+  }
+}

package/src/src/ast/utils/write-ts-parameters.ts

@@ -0,0 +1,25 @@
+import {
+  type AppendValue,
+  notNullish,
+  type Nullable,
+  type SingleOrMultiple,
+  type SourceBuilder,
+  toArray,
+} from '@goast/core';
+
+import type { TsNode } from '../node.js';
+import { writeTsNodes } from './write-ts-nodes.js';
+
+export function writeTsParameters<TBuilder extends SourceBuilder>(
+  builder: TBuilder,
+  nodes: SingleOrMultiple<Nullable<TsNode<TBuilder> | AppendValue<TBuilder>>>,
+) {
+  const filteredNodes = toArray(nodes).filter(notNullish);
+  const multiline = filteredNodes.length > 2 ||
+    filteredNodes.some((p) =>
+      typeof p === 'object' && 'decorators' in p && Array.isArray(p.decorators) && p.decorators.length > 0
+    );
+  builder.parenthesize('()', (b) => writeTsNodes(b, filteredNodes, { separator: multiline ? ',\n' : ', ' }), {
+    multiline,
+  });
+}

package/src/src/common-results.ts

@@ -0,0 +1,26 @@
+import type { TypeScriptExportOptions } from './import-collection.js';
+
+export type TypeScriptComponentOutputKind = 'interface' | 'type' | 'enum' | 'class' | 'function' | 'variable';
+export type TypeScriptComponentOutput = {
+  component: string;
+  filePath?: string;
+  imports: TypeScriptImport[];
+  additionalExports?: string[] | ({ name: string } & TypeScriptExportOptions)[];
+  kind?: TypeScriptComponentOutputKind;
+};
+
+export type TypeScriptExportOutput = {
+  component: string;
+  filePath: string;
+} & TypeScriptExportOptions;
+
+export type TypeScriptImportKind = 'module' | 'file';
+export type TypeScriptImportType = 'import' | 'type-import' | 'js-doc';
+export type TypeScriptExportType = 'export' | 'type-export';
+
+export type TypeScriptImport = {
+  kind: TypeScriptImportKind;
+  type: TypeScriptImportType;
+  modulePath: string;
+  name: string;
+};

package/src/src/config.ts

@@ -0,0 +1,89 @@
+import type { DefaultGenerationProviderConfig, ExtendedStringCasing, OpenApiGeneratorConfig } from '@goast/core';
+
+import type { ImportModuleTransformer } from './utils.js';
+
+export type TypeScriptGeneratorConfig = OpenApiGeneratorConfig & {
+  /**
+   * The transformer to use for transforming import module paths.
+   * @default 'omit-extension'
+   */
+  importModuleTransformer: ImportModuleTransformer;
+
+  /**
+   * The casing to use for file names.
+   * @default 'kebab'
+   */
+  fileNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for type names.
+   * @default 'pascal'
+   */
+  typeNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for function names.
+   * @default 'camel'
+   */
+  functionNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for property names.
+   * @default 'camel'
+   */
+  propertyNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for enum value names.
+   * @default 'pascal'
+   */
+  enumValueNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for constant names.
+   * @default { casing: 'snake', wordCasing: 'all-upper' }
+   */
+  constantNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for generic parameter names.
+   * @default { casing: 'pascal', prefix: 'T' }
+   */
+  genericParamNameCasing: ExtendedStringCasing;
+
+  /**
+   * The casing to use for parameter names.
+   * @default 'camel'
+   */
+  paramNameCasing: ExtendedStringCasing;
+
+  /**
+   * Whether to prefer `unknown` over `any`.
+   * @default true
+   */
+  preferUnknown: boolean;
+
+  /**
+   * Whether to use single quotes for strings.
+   * @default true
+   */
+  useSingleQuotes: boolean;
+};
+
+export const defaultTypeScriptGeneratorConfig: DefaultGenerationProviderConfig<TypeScriptGeneratorConfig> = {
+  indent: { type: 'spaces', count: 2 },
+
+  importModuleTransformer: 'omit-extension',
+
+  fileNameCasing: 'kebab',
+  typeNameCasing: 'pascal',
+  functionNameCasing: 'camel',
+  propertyNameCasing: 'camel',
+  enumValueNameCasing: 'pascal',
+  constantNameCasing: { casing: 'snake', wordCasing: 'all-upper' },
+  genericParamNameCasing: { casing: 'pascal', prefix: 'T' },
+  paramNameCasing: 'camel',
+
+  preferUnknown: true,
+  useSingleQuotes: true,
+};