Skip to content

definitely_typed.dart generates Dart package:js declarations from TypeScript .d.ts declarations

License

Notifications You must be signed in to change notification settings

jiridanek/definitely_typed

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

definitely_typed.dart

Motivation

Lets use TypeScript definitions (e.g. from DefinitelyTyped) to generate package:js declarations in Dart.

Example

Given a example/dom.generated.d.ts containing

declare var name: string;

and a dart file example/dom.dart,

@DefinitelyTyped('example/dom.d.ts')
library dts2dart.example.example;

import 'package:definitely_typed/definitely_typed.dart';

part 'dom.g.dart';

the script bin/build.dart

$ dart bin/build.dart --full

generates example/dom.g.dart.

@JS()
external String get name;

Test it with

$ pub run test example --platform dartium,chrome

See the example folder in the repository.

Similar efforts

in other languages

in the Dart-o-sphere

There is probably going to be a significant functionality overlap with https://github.com/angular/ts2dart (written in TypeScript, not Dart; can it transpile itself?).

Bugs that definitely_typed.dart solves

It might be a good idea to preserve documentation comments when lexing and parsing

Overview

TypeScript side

Declaration source files have a suffix .d.ts and contain only type definitions (see section 3 in TypeScript 1.6 specification) and ambient declarations (section 1.1 of the specification). See http://www.typescriptlang.org/Handbook#writing-dts-files to get a feel for it.

Dart side (still WIP)

package:js provides a Js() annotation and there is an external keyword in dart 1.13-dev. Analyzer can typecheck calls to declared objects and dart2js generates efficient code that accesses them. See https://pub.dartlang.org/packages/js for the details.

This repository (wIP; not much Work done yet)

Goals

Write everything in Dart. Create a vertical slice of the following functionality

  • given a JavaScript file and a corresponding .t.ds file
  • parse the .d.ts
  • turn it into @JS external Dart code
  • write it out
  • use it to call something in the JavaScript file from Dart

then add features; then possibly break it into components: .t.ds parser, a source_gen generator class; add some more features; ... ???

Non-goals

  • good error messages for .d.ts: use tested .d.ts files; write .d.ts files in an IDE that hints at errors as you make them; test with the TypeScript compiler.
  • complete TypeScript parser: .d.ts files use only a subset of the full TypeScript syntax

Supported features

For now see the example and tests. What is being tested works and vice versa.

Designs

Naming

  • dts2dart, after ts2dart
  • DefinitelyTyped or DefinitelyTyped.dart, after DefinitelyTyped
  • annotate with @DefinitelyTyped("") or @TS("") or @DTS("")

I come to dislike dts2dart. It does not type well. Annotating with @DefinitelyTyped('filepath.d.ts') reads almost like a link, (at).

Parsing .d.ts

  • Option 1: Do it in Dart. a) Use relevant parts of ts2dart, either as it is or try transpiling it to Dart. b) write something yourself
  • Option 2: Use something in some other language, make it dump the AST in say JSON, load the AST

I am going with 1a) using code at https://github.com/robpike/ivy and https://github.com/unclebob/CC_SMC for inspiration.

User experience

  • Option 1: https://github.com/dart-lang/source_gen and annotation that specifies what .d.ts I want to use; How to get the .d.ts?
  • Option 2: generate Dart code for popular DefinitelyTyped .d.ts files and upload everything to Dart Pub

Option 1 is more concrete regarding what needs doing. I will be pursuing that. Option 2 has the advantage that it is me who discovers breakages caused by incompletely implemented parser, not the poor people trying to use the package.

When it is done

About

definitely_typed.dart generates Dart package:js declarations from TypeScript .d.ts declarations

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages