TypeScript AST Template Generator

Common errors

• Error: Cannot find module 'typescript'

  cause The `typescript` package is a peer dependency and must be installed separately.
  fix npm install typescript

• TypeError: Cannot read properties of undefined (reading 'factory')

  cause This usually indicates `ts` was not correctly imported from the `typescript` package, or an attempt was made to use a `ts.factory` method without `ts` being available.
  fix Ensure `import ts from 'typescript';` is at the top of your file and `typescript` is installed.

• Error: Talt: Unknown identifier SOME_PLACEHOLDER_KEY

  cause A placeholder identifier used in the template string was not provided in the replacement object when calling the compiled template function.
  fix Ensure that every identifier placeholder (e.g., `SOME_PLACEHOLDER_KEY`) in your template string has a corresponding key in the object passed to the template function, mapping to a `ts.Node` or a string.

Warnings

• gotcha Talt is a peer dependency on `typescript`. Ensure `typescript` is installed in your project at a compatible version range (`^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0`) to avoid runtime errors.
  Fix: Run `npm install typescript` or `yarn add typescript` in your project.
• gotcha When using identifier placeholders in templates, ensure the placeholder keys match the property names in the object passed to the compiled template function. Mismatched keys will result in `undefined` nodes or parsing errors.
  Fix: Double-check placeholder names in template strings and the replacement object. For example, `SOME_KEY` in the template requires `{ SOME_KEY: ... }`.
• gotcha While Talt simplifies AST generation, understanding fundamental TypeScript AST concepts and the `typescript` module's `factory` methods is still beneficial for debugging complex templates or handling cases not covered by direct templating.
  Fix: Refer to the TypeScript compiler API documentation and examples when encountering unexpected AST structures.
• breaking In Talt v2.4.0, a new feature was introduced allowing functions `() => ts.Node` as placeholders. While not strictly 'breaking', older code relying solely on identifier placeholders might need adjustment if adopting this more flexible function-based approach for node replacement.
  Fix: No fix needed for existing code. If adopting the new function-based placeholder, update your templates accordingly: `template.expression` `60 * ${() => myNode}` instead of `60 * SOME_PLACEHOLDER_KEY`.

Install

• npm install talt npm
• yarn add talt yarn
• pnpm add talt pnpm

Imports

• template
  wrong:

  import template from 'talt';

  correct:

  import { template } from 'talt';

  The primary utility `template` is a named export. It is an object containing various tag functions.
• template.typeNode

  import { template } from 'talt';
  const node = template.typeNode`{ readonly prop: string }`();

  Specific template functions like `typeNode`, `expression`, `statement`, `sourceFile`, and `jsxAttribute` are properties of the `template` object.
• ts
  wrong:

  import * as ts from 'typescript';

  correct:

  import ts from 'typescript';

  While not directly from 'talt', the `typescript` module (imported as `ts`) is fundamental for working with Talt, as Talt generates `ts.Node` objects. The default import style for TypeScript's own module is generally preferred.

Quickstart

This example demonstrates how to use `talt` to generate complex TypeScript AST nodes, including type declarations and expressions with placeholders, and then print them.

import ts from 'typescript';
import { template } from 'talt';

// Create a type node using a template string
const interfaceTypeNode = template.typeNode`
  interface MyInterface {
    id: string;
    createdAt: Date;
  }
`();

// Create an expression node with a placeholder
const mathExpressionTemplate = template.expression`
  (BASE_VALUE * 2) + ${() => ts.factory.createNumericLiteral('10')}
`;

const generatedExpression = mathExpressionTemplate({
  BASE_VALUE: ts.factory.createNumericLiteral('50')
});

// You can then print the generated AST node to verify
const printer = ts.createPrinter({
  newLine: ts.NewLineKind.LineFeed
});
const resultFile = ts.createSourceFile('temp.ts', '', ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
const printedNode = printer.printNode(ts.EmitHint.Unspecified, generatedExpression, resultFile);

console.log('Generated Interface Type Node:\n', printer.printNode(ts.EmitHint.Unspecified, interfaceTypeNode, resultFile));
console.log('Generated Expression Node:\n', printedNode);