Glutinum.CLI

This is a compiler from .d.ts to F# bindings for Fable.

Getting Started

Glutinum is delivered both as a CLI tool and web interface.

Web Interface

The web interface is available here.

It is a simple and easy-to-use tool, allowing you to convert .d.ts files to F# bindings directly from your browser without installing anything.

This is also the tool that you should use to report issues if possible.

💡 The web interface is more often updated than the NPM package

CLI via NPM

The CLI can be invoked using npx:

npx @glutinum/cli --help

or installed locally:

npm i -D @glutinum/cli

Usage

# Without installing the package
npx @glutinum/cli ./node_modules/my-lib/index.d.ts --out-file ./Glutinum.MyLib.fs
# Or with the installed package
npx glue ./node_modules/my-lib/index.d.ts --out-file ./Glutinum.MyLib.fs

or if you prefer you can pipe the output to a file:

# Without installing the package
npx @glutinum/cli ./node_modules/my-lib/index.d.ts > ./Glutinum.MyLib.fs
# Or with the installed package
npx glue ./node_modules/my-lib/index.d.ts > ./Glutinum.MyLib.fs

Contributing

Glutinum.CLI use ./build.sh or ./build.bat as a build script.

You can see the available options by running:

./build.sh --help

When using the test command, you can focus on a specific by forwarding arguments to vitest:

# Focus on all tests containing related to specs/references/class/
./build.sh test specs -- -t class/
# Do the same, but in watch mode
./build.sh test specs --watch -- -t class/

If you need to run a local version of @glutinum/cli, you can use ./build.sh cli [--watch] and then run node cli.js <args>.

Debugging

If you use VSCode, you can run the build script/commands from the JavaScript Debug Terminal. This allows you to have access to the debugger, breakpoints, etc. (it works from the F# files too).

Architecture

Glutinum.Converter.CLI

CLI tool which uses Glutinum.Converter to handle the conversion.

Glutinum.Converter

This is the heart of the project. It contains the logic to convert .d.ts to F# bindings.

From a macro view, it does the following:

1. Read the TypeScript AST and transform it into GlueAST
2. Transform the GlueAST to FsharpAST
3. Print the F# code from FsharpAST

GlueAST

GlueAST philosophy is to follow the TypeScript AST naming convention as much as possible. Its goal is to provide an easier to use AST than the TypeScript one thanks to F# type system (mainly thanks to discriminated unions).

FsharpAST

FsharpAST provides a more idiomatic F# AST but also contains Fable specific information.

For example, FSharpAttribute doesn't just map to string but also Fable/Glutinum specific syntax.

[<RequireQualifiedAccess>]
type FSharpAttribute =
    | Text of string
    /// <summary>
    /// Generates <c>[&lt;Emit("$0($1...)")&gt;]</c> attribute.
    /// </summary>
    | EmitSelfInvoke
    | Import of string * string
    | ImportAll of string
    | Erase
    | AllowNullLiteral
    | StringEnum of Fable.Core.CaseRules
    | CompiledName of string
    | RequireQualifiedAccess
    | EmitConstructor
    | EmitMacroConstructor of className: string
    | EmitIndexer

You can find more information about the internals of Glutinum and the developer workflow by watching the following Amplifying F# session.

Tests

Vitest

This project use Vitest for running tests.

Vitest was chosen because it seems to have a lot of attention and is actively maintained. Plus, it seems well integrated with VSCode and Rider, allowing us to use the test explorer and even debug the tests using source maps.

If you prefer, it is possible to run the tests via the CLI.

VSCode

Install Vitest plugin, then you will be able to run the tests from the test explorer.

Rider

You need to add a new configuration of type Vitest.

1. Run > Edit Configurations...
2. Add a new configuration of type Vitest
3. Then you can run the tests by selecting the configuration in the top right corner of the IDE.

Specs

Tip

Run ./build.sh --help to see the available options (look for test specs command).

Specs tests are used to test isolated TypeScript syntax and their conversion to F#.

They are generated based on the tests/specs/references folder.

Each .d.ts correspond to a test and have a matching .fsx file.

When running ./build.sh test specs, it will generate a similar hierarchy in the tests/specs/generated folder.

Example:

tests/specs/references
├── interfaces
│   ├── callSignature.d.ts
│   ├── callSignature.fsx
│   └── indexSignature
│       ├── numberParameter.d.ts
│       └── numberParameter.fsx
└── typeQuery
    ├── class.d.ts
    ├── class.fsx
    ├── defaultToObj.d.ts
    └── defaultToObj.fsx

generates:

tests/specs/generated
├── interfaces
│   ├── index.test.js
│   └── indexSignature
│       └── index.test.js
└── typeQuery
    └── index.test.js

index.test.js contains all the tests for the .d.ts of the same folder.

Note

If you are using VSCode, the fsx file will be nested under the d.ts file in your explorer.

The .fsx correspond to the expected result suffixed with the following:

(***)
#r "nuget: Fable.Core"
(***)

This allows us to have IDE support in the .fsx file instead of having a lot of syntax errors.

tests/specs/index.js

Sometimes debugging tests through Vitest runner / extensions, is not easy. This is why, we provide a ./tests/index.js scripts which allows you to manually check a specs transformation.

node --enable-source-maps tests/specs tests/specs/references/exports/variable.d.ts

This avoid situation where Vitest extension needs a restart of VSCode to work again, etc.

Tools

One handy tool when working on the TypeScript AST is TypeScript AST Viewer.

It allows you to have a visual representation of the AST.

Make sure to use the same version of TypeScript as the one used by Glutinum.CLI (found in the package.json file). Otherwise, you might have some differences especially in the values of the kind property.