npm package: @kibcode/types-generator
Description: This repository contains utilities which help developers to generate TypeScript types based on TON-specific files.
Latest version: 1.1.0-alpha.2

# TON TypeScript Generator

This repository contains utilities which help developers to generate TypeScript
types based on TON-specific files.

## Features

- Types constructors and functions parameters types generation based on
  `.tlo` file.
- Node client generation based on `.tlo` file.

## Installation

### yarn

```bash
yarn add --dev @kibcode/types-generator
```

### npm

```bash
npm i -D @kibcode/types-generator
```

## BinaryReader

`BinaryReader` is class which derives TypeLanguage file configuration from
`.tlo` binary file. You can find an example of such file
[here](https://github.com/newton-blockchain/ton/blob/master/tl/generate/scheme/ton_api.tlo)
.

Creating binary reader from different types of sources will append specific to
this source meta information to config.

### Usage

#### Create from file path

```typescript
import {BinaryReader} from '@kibcode/types-generator';

const config = BinaryReader.fromFilePath('...').readConfig();

console.log(config);
```

#### Create from file URL

```typescript
import {BinaryReader} from '@kibcode/types-generator';

(async () => {
  // To test fetch functionality, you could try this URL:
  // https://github.com/newton-blockchain/ton/blob/master/tl/generate/scheme/ton_api.tlo?raw=true
  const reader = await BinaryReader.fromFileURL('...');

  console.log(reader.readConfig());
})();
```

## Types generator

To make communication with tonlib easier, this library generates types which are
based on passed `.tlo` file.

As a result, it creates `.ts` file with namespace, which contains another two.
The first one is responsible for carrying type names, the second one contains
combinators which are presented as interfaces.

### Usage

#### Common usage

```typescript
import {writeTypes, BinaryReader} from '@kibcode/types-generator';

// Here we should define path to .tlo file.
const tloFilePath = '...';

// Read config from .tlo file.
const config = BinaryReader.fromFile(tloFilePath).readConfig();

// Write types to file.
writeTypes('types.ts', config);
```

#### Changing generated namespace names

```typescript
// This will generate root namespace with name "MyRoot" and namespaces 
// "MyTypes" and "MyCombinators" for types and combinators respectively.
writeTypes('types.ts', config, {
  namespaces: {
    types: 'MyTypes',
    root: 'MyRoot',
    combinators: 'MyCombinators',
  }
});
```

<a id='types-generator-formatting-options'></a>
#### Formatting options

To format TypeScript code, ESLint used. You can set your own linter
configuration by passing `linterConfig` option:

```typescript
writeTypes('types.ts', config, {
  linterConfig: {
    rules: {
      'max-len': ['error', 80],
    }
  }
});
```

While formatting TypeScript code, don't forget to pass required components
which are mentioned [here](https://typescript-eslint.io/docs/linting/#configuration).

Types generator uses configuration mentioned above by default. So, you could
reuse it too: 

```typescript
import {defaultLinterConfig} from '@kibcode/types-generator';

writeTypes('types.ts', config, {
  linterConfig: {
    ...defaultLinterConfig,
    rules: {
      ...defaultLinterConfig.rules,
      'max-len': ['error', 80]
    },
  }
});
```

## Client generator

Generated client represents abstract class which required such methods
as `_request` and `_send` to be implemented. Usually, client generation is
connected with types generation. So, it is important to see
[Generating types](#Generating types) section first.

Probably, to implement these methods, you could use Node tonlib
[implementation](https://www.npmjs.com/package/@kibcode/tonlib-node).

### Usage

#### Common usage

```typescript
import {writeClient, BinaryReader} from '@kibcode/types-generator';

// Here we should define path to .tlo file.
const tloFilePath = '...';

// Read config from .tlo file.
const config = BinaryReader.fromFile(tloFilePath).readConfig();

writeClient('client.ts', config, {
  // Set import source from which generator should get tonlib root namespace
  // declaration.
  // As a result, generated class file will contain such import:
  // import {Tonlib} from './types';
  typesSource: './types',
});
```

#### Changing source namespace and client names

```typescript
import {writeTypes, writeClient, BinaryReader} from '@kibcode/types-generator';

// Here we should define path to .tlo file.
const tloFilePath = '...';

// Read config from .tlo file.
const config = BinaryReader.fromFile(tloFilePath).readConfig();

const namespaces = {
  root: 'MyRoot',
  types: 'MyTypes',
  combinators: 'MyCombinators',
};

// Write types to file.
writeTypes('types.ts', config, {namespaces});

// This will generate class "MyClass" with functions that will refer to
// types which are placed in MyRoot.MyTypes and MyRoot.MyCombinators 
// namespaces.
//
// Additionally, import declaration will have this form:
// import {MyRoot} from './types';
writeClient('client.ts', config, {
  typesSource: './types',
  names: {
    namespaces,
    class: 'MyClass',
  }
});
```

#### Formatting options

Client generator uses the same formatting flow as Types generator does. So, to
learn more, follow [this](#types-generator-formatting-options) section.

## Example output

You can find examples of generated output in
[output](https://github.com/wolframdeus/ton-ts-gen/tree/master/output) folder.