skills/angular__angular
1
0
Fork 0
mirror of https://github.com/angular/angular.git synced 2026-09-14 13:54:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: remove dart source and tooling

Browse Source
This commit is contained in:
Jeremy Elbourn
2016-04-05 09:45:27 -07:00
parent c8f87a427a
commit 69512c2f6a
28 changed files with 12 additions and 1688 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/dart/writing-compatible-typescript.md
-48
View File
@@ -1,48 +0,0 @@
# Writing Dart Compatible TypeScript
When writing TypeScript files in Material 2, it is important to keep in mind that these files will be automatically compiled and verified in Dart. There is valid TypeScript that will work in Angular 2, but will be transpiled to invalid Dart code.
Because of this, there's certain things to keep in mind.
## Requirements
This document refers to the following concepts, but do not explain them:
* The Dart language: https://www.dartlang.org
* The `pub` Dart packages management: https://pub.dartlang.org/
* The `angular-cli` toolchain: https://github.com/angular/angular-cli
## Dart Toolchain
When running `ng build` (or `ng server` which also builds), a Broccoli tree will automatically compile and format your TypeScript code into Dart. These files live along the JavaScript output of the build process, and also are moved into a special directory structure that is compatible with `pub`.
For example, let say you have a `md-awesome` component for Material, which contains the `awesome.ts` implementation. This file is contained in the source code as `src/components/awesome/awesome.ts`. Building this component (assuming no specs or `scss`) will result in the following files:
* `dist/components/awesome/awesome.ts`. The original copy.
* `dist/components/awesome/awesome.js`. The Javascript code.
* `dist/components/awesome/awesome.js.map`. Sourcemap.
* `dist/components/awesome/awesome.dart`. The Dart code, transpiled by `ts2dart` and formatted by `dartfmt`.
* `dist/dart/lib/components/awesome/awesome.dart`. The same file, copied from above into a directory structure compatible with `pub`.
If you have transpilation errors (ie. your TypeScript is invalid in Dart), these will fail the `ng build` step now and will output the errors in the console.
## Gotchas
Here's a list of gotchas to keep in mind when writing TypeScript code that will be compiled to Dart:
* **Unused imports are enforced in Dart.** Importing a file but not using it is an error, not a warning.
* **`void` is not a proper type for templates.** This is important when creating `EventEmitter<>` or other templates. Instead of `void`, use `Object` and pass in `null`.
* **There's no global execution.** Every executed code need to be in a function.
* **Unit tests need to live inside a `main()` function.** Because of the point above, `describe()` is technically executed code and has to live in a function. Additionally, spec files are programs in Dart and as such much have a `void main() {}` function containing the test code.
* **Boolean expressions are required to be boolean.** There's no type coercion or truthiness concept in Dart. Code like this: `if (!aNumber) {}` must be refactored to be `if (aNumber != 0) {}`.
* **Accessing any platform primitive must be done through a Facade.** For example, Promises or DOM manipulation. Facades are going to be provided on a need-to-have basis.
* **Union types are a no-go.** Dart has them on its roadmap, but for now we must avoid them.
* **Dart files cannot have the same name as a reserved keyword.** For example, `for.dart`, `switch.dart` or `class.dart` are all invalid names. Since the TypeScript files have the same name when transpiled to Dart, they also have the same restriction.
* **Default values need to be constants.** This mean that code like `function myFunction(arg1: string = callToSomething()) {}` will not compile.
* **The const keyword must have a const value.** Because of that, we cannot do `const x = a + b;` even if the value of `x`, `a` and `b` will not change.
* **Lambdas need to abide to the type required.** Meaning that if a function requires a function that takes one argument, the lambda cannot be `() => {}`. Use `_` for temporary parameters. This is notable in Promises.
* **Dynamic return values fat arrows can't return non-primitive types without casting.** For example, a fat arrow that return a promise (or Future) generates a warning if using directly, like so: `promiseA.then(() => promiseB)`. In this case simply using a block works as expected; `promiseA.then(() => { return promiseB; })`.
* **Dart does not have [generic methods](http://www.typescriptlang.org/docs/handbook/generics.html)** ([issue](https://github.com/dart-lang/sdk/issues/254)).
* **Dart does not have destructuring** but it does have a [proposal](https://github.com/dart-lang/dart_enhancement_proposals/issues/24) for it.
* **Dart does not support type aliases.** Code like `type Nop = () => void` will not compile.
* **Dart does not support [tagged template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals)**.