typescript annotations

Author: basarat

SUMMARY.md

@@ -11,3 +11,7 @@
  * [for...of](docs/for...of.md)
  * [Template Strings](docs/template-strings.md)
  * [Spread Operator](docs/spread-operator.md)
+* [TypeScript's Type System](docs/types/type-system.md)
+ * [Ambient Declarations](docs/types/ambient-declarations.md)
+ * [Functions](docs/types/type-compatability.md)
+ * [Type Compatability](docs/types/type-compatability.md)

code/types/types.js

@@ -88,6 +88,12 @@ var null_undefined;
  foo: Null;
  bar: Undefined;
 })(null_undefined || (null_undefined = {}));
+var void_;
+(function (void_) {
+ function log(message) {
+ console.log(message);
+ }
+})(void_ || (void_ = {}));
 var generics;
 (function (generics) {
  function reverse(items) {
@@ -133,3 +139,73 @@ var generics;
  '2'
  ];
 })(generics || (generics = {}));
+var union;
+(function (union) {
+ function formatCommandline(command) {
+ var line = '';
+ if (typeof command === 'string') {
+ line = command.trim();
+ }
+ else {
+ line = command.join(' ').trim();
+ }
+ }
+})(union || (union = {}));
+var tuple;
+(function (tuple) {
+ var nameNumber;
+ nameNumber = [
+ 'Jenny',
+ 8675309
+ ];
+ nameNumber = [
+ 'Jenny',
+ '867-5309'
+ ];
+ var name = nameNumber[0], num = nameNumber[1];
+})(tuple || (tuple = {}));
+var getset;
+(function (getset) {
+ var _value;
+ function getOrSet(value) {
+ if (value === undefined) {
+ return _value;
+ }
+ else {
+ _value = value;
+ }
+ }
+ getOrSet(1);
+ console.log(getOrSet());
+})(getset || (getset = {}));
+var getset_;
+(function (getset_) {
+ var _value;
+ function getOrSet(value) {
+ if (value === undefined) {
+ return _value;
+ }
+ else {
+ _value = value;
+ }
+ }
+ getOrSet(1);
+ console.log(getOrSet());
+})(getset_ || (getset_ = {}));
+var overload;
+(function (overload) {
+ function callMe(v1, v2) {
+ }
+ callMe();
+ callMe(1);
+ callMe('jenny', 5309);
+ callMe('jenny');
+ callMe('jenny', '5309');
+})(overload || (overload = {}));
+var alias;
+(function (alias) {
+ var sample;
+ sample = 123;
+ sample = '123';
+ sample = true;
+})(alias || (alias = {}));

code/types/types.ts

@@ -13,7 +13,7 @@ export module m1 {
  num = 123;
  num = 123.456;
  num = '123'; // Error
- 
+
  str = '123';
  str = 123; // Error
 
@@ -27,7 +27,7 @@ export module m2 {
 
  boolArray = [true, false];
  console.log(boolArray[0]); // true
- console.log(boolArray.length); // 2 
+ console.log(boolArray.length); // 2
  boolArray[1] = true;
  boolArray = [false, false];
 
@@ -78,7 +78,7 @@ export module m4 {
 
 module any {
  var power: any;
- 
+
  // Takes any and all types
  power = '123';
  power = 123;
@@ -92,16 +92,22 @@ module any {
 module null_undefined {
  var num: number;
  var str: string;
- 
+
  // These literals can be assigned to anything
  num = null;
- str = undefined; 
- 
+ str = undefined;
+
  // However they don't have a dedicated annotation
  foo: Null; // Error
  bar: Undefined; // Error
 }
 
+module void_ {
+ function log(message): void {
+ console.log(message);
+ }
+}
+
 module generics {
  function reverse<T>(items: T[]): T[] {
  var toreturn = [];
@@ -114,25 +120,112 @@ module generics {
  var sample = [1, 2, 3];
  var reversed = reverse(sample);
  console.log(reversed); // 3,2,1
- 
+
  // Safety!
- reversed[0] = '1'; // Error! 
+ reversed[0] = '1'; // Error!
  reversed = ['1', '2']; // Error!
- 
+
  reversed[0] = 1; // Okay
  reversed = [1, 2]; // Okay
- 
+
  //////////////////////
- 
+
  var strArr = ['1', '2'];
  var reversedStrs = reverse(strArr);
 
  reversedStr = [1, 2]; // Error!
- 
- /// 
+
+ ///
  var numArr = [1, 2];
  var reversedNums = numArr.reverse();
- 
+
  reversedNums = ['1', '2']; // Error!
 }
 
+module union {
+ function formatCommandline(command: string[]|string) {
+ var line = '';
+ if (typeof command === 'string') {
+ line = command.trim();
+ } else {
+ line = command.join(' ').trim();
+ }
+
+ // Do stuff with line:string
+ }
+}
+
+module tuple {
+ var nameNumber: [string, number];
+
+ // Okay
+ nameNumber = ['Jenny', 8675309];
+
+ // Error!
+ nameNumber = ['Jenny', '867-5309'];
+
+ var [name, num] = nameNumber;
+}
+
+module getset {
+
+ var _value;
+ function getOrSet(value) {
+ if (value === undefined) {
+ return _value;
+ } else {
+ _value = value;
+ }
+ }
+
+ getOrSet(1); // set : 1
+ console.log(getOrSet()); // get : 1
+}
+
+module getset_ {
+
+ var _value;
+ function getOrSet(): number;
+ function getOrSet(value: number);
+ function getOrSet(value?: number) {
+ if (value === undefined) {
+ return _value;
+ } else {
+ _value = value;
+ }
+ }
+
+ getOrSet(1); // set : 1
+ console.log(getOrSet()); // get : 1
+}
+
+
+module overload {
+
+ function callMe(): number;
+ function callMe(v1: number);
+ function callMe(v1: string, v2: number);
+ function callMe(v1?: any, v2?: any): any {
+ // Implementation body goes here
+ }
+
+ // Allowed calls
+ callMe();
+ callMe(1);
+ callMe('jenny', 5309);
+
+ // ERROR: invalid calls:
+ callMe('jenny');
+ callMe('jenny', '5309');
+}
+
+module alias {
+ type StrOrNum = string|number;
+
+ var sample: StrOrNum;
+ sample = 123;
+ sample = '123';
+
+ // Safety
+ sample = true; // Error!
+}

docs/types/advanced.md

@@ -0,0 +1,122 @@
+
+
+
+
+# Functions
+
+## Optional
+The `?` annotation can be used before a function argument or member of an interface to denote that a member is optional. That is to say that you can provide it if you want (and it will be type checked), but if it is ommited its *okay*. This is shown in the following example:
+
+## Specialized Parameters
+
+## Function Overloads
+The JavaScript runtime does not have runtime support for function overloading. There can be only a single function body for any given name in scope. However people do support function overloading by utilizing the highly dynamic nature of JavaScript e.g. a getter and a setter:
+
+```ts
+var _value;
+function getOrSet(value) {
+ if (value === undefined) {
+ return _value;
+ } else {
+ _value = value;
+ }
+}
+
+getOrSet(1); // set : 1
+console.log(getOrSet()); // get : 1
+```
+
+Such implementation can be captured by the TypeScript's type system by providing function signatures before the function implementation:
+
+```ts
+var _value;
+function getOrSet(): number;
+function getOrSet(value: number);
+function getOrSet(value?: number) {
+ if (value === undefined) {
+ return _value;
+ } else {
+ _value = value;
+ }
+}
+
+getOrSet(1); // set : 1
+console.log(getOrSet()); // get : 1
+```
+
+Note that when you define function overloads this way, *the last signature is actually not callable*. You have to provide it however to help the implementer of the function be aware of the consequences of his overload signatures. For example in the following example the function with the signature `function callMe(v1?: any, v2?: any): any` is not open to public use:
+
+```ts
+function callMe(): number;
+function callMe(v1: number);
+function callMe(v1: string, v2: number);
+function callMe(v1?: any, v2?: any): any {
+ // Implementation body goes here
+}
+
+// Allowed calls
+callMe();
+callMe(1);
+callMe('jenny', 5309);
+
+// COMPILER ERROR: invalid calls
+callMe('jenny');
+callMe('jenny', '5309');
+```
+
+TIP: Note that there is a slight overlap between union types and function overloading. If two function signatures only differ by a single parameter having different types just use a union type for that parameter instead of creating an overload signature.
+
+
+# Interfaces
+
+Interfaces have a lot of power in TypeScript. This is because they are designed to capture all the complexity of
+
+
+
+
+# Ambient Declarations
+
+We previously had a brief look at ambient declarations in the section *why typescript?*. One of the core design goals of TypeScript is to allow easy consumption of existing JavaScript libraries. You can declare the type information for existing JavaScript using *ambient declarations*. You declare ambient stuff using the `declare` keyword. In fact this is how a bunch of stuff available by default in a browser environment (e.g `window`, `document` etc) is declared in a file called `lib.d.ts`
+
+
+Note: You can find type definitions for nearly 90% of the most popular JavaScript libraries at [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped) with contributions from [lots of developers](https://github.com/borisyankov/DefinitelyTyped/graphs/contributors).
+
+
+
+### lib.d.ts
+
+# Interfaces
+
+
+
+### Interfaces for primitive types
+
+### Interface for array
+
+## Type Alias
+
+## Union Types
+needed for configuration objects
+
+## Type Inference
+It tries to *infer* as much as it can *so that you don't need to explicitly type* your code.
+
+## Function Signatures
+
+Specialized
+
+## Type Assertion
+
+If A is a subtype of B or B is a subtype of A.
+
+
+
+
+
+
+
+
+[more on interfaces]
+Structural so more information is okay, but less information is an error. Duck typing is baked deep into the language design.
+Open Ended
+Type Compatibility