generate-ts

The purpose of this repository is to provide a simple, Typescript native way to dynamically generate Typescript code based on a pattern from a markdown file.

Getting started

Typescript version ^4.8.4 needs to be installed globally via:

npm install -g typescript

Then you can simply run this package via an npx command:

npx generate-ts

It will pick up any <NAME>.generator.md files in your project and generate patterns based on a particular format.

How to structure the generator.md files

Create some .md files with the name <NAME>.generator.md and structure them like so:

filePath
`src/example/test.ts`

fileNamePattern
`.screen.ts`

codePatterns

```TypeScript
import { $nameScreen } from './$importName'; // pattern
```

```TypeScript
const test = () => {
  // variable assignment
  const $nameVariable = "$name"; // pattern
  return {
    $nameVariable, // pattern
  };
};
```

Run npx generate-ts, and the resulting test.ts file will look like this:

import { ExampleScreen } from './Example.screen';
import { SecondScreen } from './Second.screen';

const test = () => {
  // variable assignment
  const ExampleVariable = 'Example';
  const SecondVariable = 'Second';
  return {
    ExampleVariable,
    SecondVariable,
  };
};

API

Markdown file structure

Flag	Description
filePath	The path to the file to be generated
fileNamePattern	The pattern used to pick up files by their extensions
codePatterns	Any code blocks after this will be used to generate code

Code patterns

Type	Description	Example
Static	Code that is generated once	const test = "test";
Pattern	Must be appended with a // pattern comment. This is code that is generated for each file that matches the fileNamePattern	import { $nameScreen } from './$importPath'; // pattern

Pattern Variables

Variable	Description
$name	Gets the first section of the file name: "MyScreen"
$fileName	Gets the entire file name: "MyScreen.screen.ts"
$importPath	Gets the file path without the last extension: "src/screens/MyScreen.screen"
$path	Gets the full path: "src/screens/MyScreen.screen.ts"

Using the library programmatically

You can install this package and use it programmatically instead of using npx:

npm install generate-ts

And then use it like so:

import { generatePattern, GeneratePatternOptions } from 'generate-ts';

const options: GeneratePatternOptions = {
  filePath: 'src/Example/test.ts',
  fileNamePattern: '.screen.ts',
  codePatterns: [
    {
      pattern: `// import code block`
      static: true,
    },
    {
      pattern: `import { $nameScreen } from './$importName';`
      static: false,
    }
  ],
};

generatePattern(options);

Options

Property	Type	Description
folder	string (optional)	Limits file search to a provided directory. Defaults to './'

Motivation

Over a year ago I wrote a blog post going over how the vscode-generate-index plugin has helped solve a lot of tedious problems we may face in the Typescript world. However, if I wasn't following my own advice about continuous improvement, I would have never thought to start working on this project.

The vscode-generate-index plugin has been helpful in the short-term. However, in the long-term we identified several issues that this plugin's approach created. Here is a breakdown of the problems we faced, and how this project solves them:

vscode-generate-index	Typescript-Code-Generation
Creating and maintaining the patterns is cumbersome. The patterns exist as single line comments	Patterns are defined with simple, overt syntax. Documentation is also encouraged and can be added anywhere in the markdown file
Onboarding new developers creates learning curve issues. They need to learn the minimatch pattern, and the @index flag syntax, among other things	API is interacted with via native Typescript. In fact, the entire backend is run via the Typescript Compiler API
Makes it too easy/tempting to combine with manual code, adding to confusion	Each code generation result is placed in its own file, overwriting itself on each invocation
When not left in check, creates monolithic generated files	While any file can become monolithic, this project makes it difficult because it is not possible to have different file searches in the same output, only different patterns as a result of a single file search
No type safety or compiler checks until after the code is generated	The resulting code from each pattern is run through the native Typescript compiler API, and any errors and type issues are outputted to the console and blocks generation of the file