index signatures

Author: Basarat Ali Syed

code/types/freshness/index-signatures.ts

@@ -1,29 +1,29 @@
 module a {
- let foo:any = {};
+ let foo: any = {};
  foo['Hello'] = 'World';
  console.log(foo['Hello']); // World
 }
 module b {
  class Foo {
- constructor(public message: string){};
- log(){
+ constructor(public message: string) { };
+ log() {
  console.log(this.message)
  }
  }
 
- let foo:any = {};
+ let foo: any = {};
  foo['Hello'] = new Foo('World');
  foo['Hello'].log(); // World
 }
 module c {
  let obj = {
- toString(){
+ toString() {
  console.log('toString called')
  return 'Hello'
  }
  }
 
- let foo:any = {};
+ let foo: any = {};
  foo[obj] = 'World'; // toString called
  console.log(foo[obj]); // toString called, World
  console.log(foo['Hello']); // World
@@ -36,12 +36,12 @@ module d {
 
 module e {
  let obj = {
- toString(){
+ toString() {
  return 'Hello'
  }
  }
 
- let foo:any = {};
+ let foo: any = {};
 
  // ERROR: the index signature must be string, number ...
  foo[obj] = 'World';
@@ -51,8 +51,8 @@ module e {
 }
 
 module f {
- let obj = {message:'Hello'}
- let foo:any = {};
+ let obj = { message: 'Hello' }
+ let foo: any = {};
 
  // ERROR: the index signature must be string, number ...
  foo[obj] = 'World';
@@ -67,7 +67,7 @@ module f {
 }
 
 module g {
- let foo:{ [index:string] : {message: string} } = {};
+ let foo: { [index: string]: { message: string } } = {};
 
  /**
  * Must store stuff that conforms the structure
@@ -90,24 +90,24 @@ module mustConform {
 
  /** Okay */
  interface Foo {
- [key:string]: number
+ [key: string]: number
  x: number;
  y: number;
  }
  /** Error */
  interface Bar {
- [key:string]: number
+ [key: string]: number
  x: number;
  y: string; // Property `y` must of of type number
  }
 }
 
 module mustConform2 {
  interface Foo {
- [key:string]: number
+ [key: string]: number
  x: number;
  }
- let foo: Foo = {x:1,y:2};
+ let foo: Foo = { x: 1, y: 2 };
  foo['x']; // number
  let x = 'x'
  foo[x]; // number
@@ -123,3 +123,43 @@ module dual {
  length: number;
  }
 }
+
+module jsland {
+ interface NestedCSS {
+ color?: string;
+ [selector: string]: string | NestedCSS;
+ }
+
+ const example: NestedCSS = {
+ color: 'red',
+ '.subclass': {
+ color: 'blue'
+ }
+ }
+
+ const failsSilently: NestedCSS = {
+ colour: 'red', // No error is `colour` is a valid string selector
+ }
+}
+
+module better {
+ interface NestedCSS {
+ color?: string;
+ nest?: {
+ [selector: string]: NestedCSS;
+ }
+ }
+
+ const example: NestedCSS = {
+ color: 'red',
+ nest: {
+ '.subclass': {
+ color: 'blue'
+ }
+ }
+ }
+
+ const failsSilently: NestedCSS = {
+ colour: 'red', // TS Error: unknown property `colour`
+ }
+}

docs/types/index-signatures.md

@@ -166,9 +166,9 @@ foo['x']; // number
 let x = 'x'
 foo[x]; // number
 ```
-### Extending `string`
+### Using a limited set of string literals
 
-An index signature can require that index strings be members of a "vocabulary" union of literal strings, because such a union extends `string`:
+An index signature can require that index strings be members of a union of literal strings e.g.:
 
 ```ts
 type Index = 'a' | 'b' | 'c'
@@ -178,7 +178,7 @@ const good: FromIndex = {b:1, c:2}
 
 // Type '{ b: number; c: number; d: number; }' is not assignable to type 'FromIndex'.
 // Object literal may only specify known properties, and 'd' does not exist in type 'FromIndex'.
-const bad: FromIndex = {b:1, c:2, d:3} // 
+const bad: FromIndex = {b:1, c:2, d:3} //
 ```
 This is often used together with `keyof typeof` to capture vocabulary types, described on the next page.
 
@@ -204,3 +204,52 @@ interface ArrStr {
  length: number;
 }
 ```
+
+### TIP: API consideration when adding index signatures
+
+Quite commonly in the JS community you will see APIs that abuse string indexers. e.g. a common pattern among CSS in JS libraries:
+
+```js
+interface NestedCSS {
+ color?: string;
+ [selector: string]: string | NestedCSS;
+}
+
+const example: NestedCSS = {
+ color: 'red',
+ '.subclass': {
+ color: 'blue'
+ }
+}
+```
+Try not to mix string indexers with *valid* values this way. E.g. a typo in the padding will remain uncaught:
+
+```js
+const failsSilently: NestedCSS = {
+ colour: 'red', // No error is `colour` is a valid string selector
+}
+```
+
+Instead seperate out the nesting into its own property e.g. in a name like `nest` (or `children` or `subnodes` etc.):
+
+```js
+interface NestedCSS {
+ color?: string;
+ nest?: {
+ [selector: string]: NestedCSS;
+ }
+}
+
+const example: NestedCSS = {
+ color: 'red',
+ nest: {
+ '.subclass': {
+ color: 'blue'
+ }
+ }
+}
+
+const failsSilently: NestedCSS = {
+ colour: 'red', // TS Error: unknown property `colour`
+}
+```