Index Signatures

    Here is a quick example:

    We store a string "World" under the key "Hello". Remember we said it can store any JavaScript object, so lets store a class instance just to show the concept:

    1. class Foo {
    2.   constructor(public message: string){};
    3.   log(){
    4.     console.log(this.message)
    5.   }
    6. }
    8. let foo:any = {};
    9. foo['Hello'] = new Foo('World');
    10. foo['Hello'].log(); // World

    Also remember that we said that it can be accessed with a string. If you pass some any other object to the index signature the JavaScript runtime actually calls .toString on it before getting the result. This is demonstrated below:

    1. let obj = {
    2.   toString(){
    3.     console.log('toString called')
    4.     return 'Hello'
    5.   }
    6. }
    8. let foo:any = {};
    9. foo[obj] = 'World'; // toString called
    10. console.log(foo[obj]); // toString called, World
    11. console.log(foo['Hello']); // World

    Note that toString will get called whenever the obj is used in an index position.

    Arrays are slightly different. For number indexing JavaScript VMs will try to optimise (depending on things like is it actually an array and do the structures of items stored match etc.). So number should be considered as a valid object accessor in its own right (distinct from string). Here is a simple array example:

    1. let foo = ['World'];
    2. console.log(foo[0]); // World

    So that’s JavaScript. Now let’s look at TypeScript graceful handling of this concept.

    First off, because JavaScript implicitly calls toString on any object index signature, TypeScript will give you an error to prevent beginners from shooting themselves in the foot (I see users shooting themselves in their feet when using JavaScript all the time on stackoverflow):

    1. let obj = {
    2.   toString(){
    3.     return 'Hello'
    4.   }
    5. }
    7. let foo:any = {};
    8. // ERROR: the index signature must be string, number ...
    9. foo[obj] = 'World';
    12. foo[obj.toString()] = 'World';

    The reason for forcing the user to be explicit is because the default toString implementation on an object is pretty awful, e.g. on v8 it always returns [object Object]:

    1. its needed for excellent Array / Tuple support.
    2. even if you use it for an obj its default toString implementation is nice (not [object Object]).

    Point 2 is shown below:

    1. console.log((1).toString()); // 1
    2. console.log((2).toString()); // 2

    So lesson 1:

    Quick note: symbols are also valid and supported by TypeScript. But let’s not go there just yet. Baby steps.

    So we’ve been using any to tell TypeScript to let us do whatever we want. We can actually specify an index signature explicitly. E.g. say you want to make sure than anything that is stored in an object using a string conforms to the structure {message: string}. This can be done with the declaration { [index:string] : {message: string} }. This is demonstrated below:

    1. let foo:{ [index:string] : {message: string} } = {};
    3. /**
    4.  * Must store stuff that conforms the structure
    5.  */
    6. /** Ok */
    7. foo['a'] = { message: 'some message' };
    8. /** Error: must contain a `message` or type string. You have a typo in `message` */
    9. foo['a'] = { messages: 'some message' };
    11. /**
    12.  * Stuff that is read is also type checked
    13.  */
    14. /** Ok */
    15. foo['a'].message;
    16. /** Error: messages does not exist. You have a typo in `message` */
    17. foo['a'].messages;

    Of course number indexes are also supported e.g. { [count: number] : SomeOtherTypeYouWantToStoreEgRebate }

    As soon as you have a string index signature, all explicit members must also conform to that index signature. This is shown below:

    1. /** Okay */
    2. interface Foo {
    3.   [key:string]: number
    4.   x: number;
    5.   y: number;
    6. }
    7. /** Error */
    9.   [key:string]: number
    10.   x: number;
    11. }
    1. interface Foo {
    2.   [key:string]: number
    3.   x: number;
    4. }
    5. let foo: Foo = {x:1,y:2};
    7. // Directly
    8. foo['x']; // number
    10. // Indirectly
    11. let x = 'x'
    12. foo[x]; // number

    An index signature can require that index strings be members of a union of literal strings by using Mapped Types e.g.:

    This is often used together with keyof typeof to capture vocabulary types, described on the next page.

    The specification of the vocabulary can be deferred generically:

    1. type FromSomeIndex<K extends string> = { [key in K]: number }

    This is not a common use case, but TypeScript compiler supports it nonetheless.

    However it has the restriction that the string indexer is more strict than the number indexer. This is intentional e.g. to allow typing stuff like:

    1. interface ArrStr {
    2.   [key: string]: string | number; // Must accomodate all members
    4.   [index: number]: string; // Can be a subset of string indexer
    6.   // Just an example member
    7.   length: number;
    8. }

    Quite commonly in the JS community you will see APIs that abuse string indexers. e.g. a common pattern among CSS in JS libraries:

    1. interface NestedCSS {
    2.   color?: string;
    3.   [selector: string]: string | NestedCSS;
    4. }
    6. const example: NestedCSS = {
    7.   color: 'red',
    8.   '.subclass': {
    9.     color: 'blue'
    10.   }
    11. }

    Try not to mix string indexers with valid values this way. E.g. a typo in the padding will remain uncaught:

    1. const failsSilently: NestedCSS = {
    2.   colour: 'red', // No error as `colour` is a valid string selector
    3. }