Proposal: String enums

[jbondc]

A string enum is inferred by looking at the constant value of the initializer of its first member:

enum stringsInferred {
   a = "a",
   b, // "b"
   c  // "c"
}

Or it is declared using a string index:

enum stringsDeclared {
   [prop: string] : string;
   a, // "a"
   B, // "B"
   c  // "c"
}

The auto initialized value on an enum is its property name.

Inferred enum special case

enum stringsLowerCase {
   Shoes = "shoes", // If the first member has lowercase chars, then lowercase all other member values
   Boots, // "boots"
   Feet  // "feet"
}

[mariusschulz]

👍

We should definitely be able to use enums with string values. Even a const enum with compile-time string literals (that are always safe to inline) would be helpful already, mainly for …

• restricting variables to a set of known string values, and
• avoiding misspellings.

I'm not sure the automagical upper- and lowercasing described underneath Inferred enum special cases is such a good idea, though. I'd rather spell all cases exactly like they should be stringified:

enum stringsUpperCase {
   Shoes = "SHOES",  // "SHOES"
   BOOTS,            // "BOOTS"
   Feet              // "Feet"
}

[dead-claudia]

Can this be generalized to other types (with the constraint that all types must be initialized - no value can be inferred)?

[dead-claudia]

@jbondc

I agree, and this could be the other special case (where value inference already exists for numbers). Also, FWIW, I made a post on that bug with a few more specific suggestions IIRC. It just wasn't on the top of my mind at the time.

[dead-claudia]

@jbondc

And I feel this syntax is a little repetitive in the [prop: string]: string part. Couldn't the syntax be modified to have the type after the enum name, instead of in the body? Maybe this syntax, to borrow your example?

enum strings : string {
   Shoes,           // "Shoes"
   BOOTS,            // "BOOTS"
   Feet              // "Feet"
}

[dead-claudia]

@jbondc Any advantages to that over my recent proposal? I don't think that regex-based solution is really that helpful in practice. All that regex does there is enforce type names, something better left to a linter as opposed to the main compiler. And it looks a little out of place compared to the enum entries. And as you said in the other thread, it will complicate the parser and compiler a little, likely more than it should.

And as for extending enums, that's not very good practice, anyways. And it's generally not possible among other TypeScript users. Mine allows for such extensions, but you can only truly extend them in the same module or private namespace declaration, unless you're writing a definition file. That's because of the module wrapper emitted around every namespace declaration. So, for most purposes, you can't really extend them in the first place. Also, the spec currently requires that same-named declarations within the same root to add properties to the same enum.

[lazdmx]

👍 for string (const) enums

[rotemdan]

My current workaround looks something like this (this is a real-world, copy-and-paste code example):

class Task {
  ..
  static State = { 
    Unstarted: "Unstarted", 
    Started: "Started", 
    Completed: "Completed", 
    Faulted: "Faulted", 
    Canceled: "Canceled"
  }
}

let task = new Task();
..
if (task.state === Task.State.Completed) // The declared type of task.state is "string" here.
  console.log("Done!");

This also gives a nice encapsulation into the class type that I find appealing (through the static modifier).

Replicating this through enum would require several different enhancements. I will consider posting a separate proposal for class encapsulated enums if that hasn't been proposed before.

I think having string enums would be very useful (maybe "necessary" should be the right word here). Automatic inferring of things like letters would be problematic because of locale and language issues (every language would have its own letters and ordering). Automatic lowercasing/uppercasing would also be impacted from similar issues (every language has different lower/uppercasing rules), and seems to me like a minor detail/enhancement at this point.

[mariusschulz]

Maybe the string keyword would lend itself to be included in the declaration:

string enum PromiseState {
    Pending,
    Fulfilled,
    Rejected
}

In the above example, the string values of the cases would equal their names. They could be overwritten like this:

string enum PromiseState {
    Pending = "pending",
    Fulfilled = "fulfilled",
    Rejected = "rejected"
}

[rotemdan]

This may turn out a bit long for a const enum that is also exported:

export const string enum PromiseState {
    Pending,
    Fulfilled,
    Rejected
}

So maybe an alternative using some sort of a psuedo-generic type parameter?

export const enum PromiseState<string> {
    Pending,
    Fulfilled,
    Rejected
}

Due to issues with different languages, alphabets, and locales it would be difficult to apply a correct conversion to lowercase/uppercase in many languages other than English. So just preserving the original casing and allowing custom ones through = seems like a reasonable compromise.

[Gambero81]

Hi, what is the actual state of this proposal? can we have a roadmap to know when will be implemented in the language? Thanks

[dead-claudia]

@Gambero81 See #1206 for a more up-to-date version of this.

[dead-claudia]

Can this be closed in favor of #1206? It's more general, which is better IMHO.

[dead-claudia]

Union and intersection types would already exist with my proposal. You
could achieve the same thing.

On Sun, Sep 20, 2015, 09:17 Jon notifications@github.com wrote:

@IMPinball https://github.com/impinball No, added this here strictly
for discussing a string enum & use cases.
e.g. can you interest two string enums?

enum a {
hello = "hello"
}
enum b {
world = "world"
}
let c = a & b;
let d = typeof a & typeof b;

—
Reply to this email directly or view it on GitHub
#3192 (comment)
.

[vitrilo]

Using of String are really neat feature. In our 20k loc project we still use workarounds.
Apart, using objects as enum values (like in #1206 or http://stackoverflow.com/a/15491832/1224258) are risky - comparison fails after any Enums serialization/de-serialization or deepcopy (angular.copy).

[basarat]

Probably better if #1003 is done instead

[dead-claudia]

@basarat I think both have their uses. A primitive enum (excluding symbols) could be seen as the union of their values in that sense. And also, I believe that should be expanded to also include numbers.

[dead-claudia]

I made a relevant response over there on #1003.

[dead-claudia]

@jbondc I tried to include those, but I didn't get a very positive response from it.

[vitrilo]

@basarat Thanks, I've just discovered related #1003, #1295. Great proposals/ideas!
My understanding #1003 (string literal union type) vs #3192 (string enums) is following:

• String enums are simple, straightforward approach
• Singleton types under the form of string literal types #1003 - are more wider idea, which are may be both: multi-purpose (like for type guards) solution and space for funky/unwanted/corner cases
• Syntax are RADICALLY different (which not obvious on first site):

    var var1 = MyEnum.Kind1; //string enum.
    var var2 = "kind1"; //string literal union type - NO compiler type-checking! 
    var var3:MyUnionEnum = "kind1"; //string literal union type with compiler type-checking 

• Readability: IMHO, String enums have better readability. Moreover, in many languages enum types make uppercased to highlight limited possibilities and static nature.
• IDE support. Tools are all for us! Possible, implementing auto-complete for Singleton types under the form of string literal types #1003 (string literal union type) may be significantly harder inside IDEs comparing to Proposal: String enums #3192 (string enums). Not because of complexity of union-type concept, also because IDE should introduce in-natural auto-complete inside string literals: "kind1" (should suggest kind2,kind3.. if this is union type).

Apart, from all above, Javascript ecosystem generally encourage wide usage of string literals. As result, like in #1003, #1295 IDEs/Tools will be forced to support special meaning of string literals, like as enum constants/properties names etc, not just meaningless text to output.

[jtheoof]

👍 This feature would be great.

Right now, the enums are a bit counter intuitive from a JavaScript usage perspective. They work well for internal TypeScript code but not so much when code is used in third party apps.

It would be especially useful for bridging the gap between both worlds:

Example:

sdk.ts
--------

export enum Environments {
  SANDBOX,
  PRODUCTION
}

interface ClientOptions {
  id: string;
  secret: string;
  env?: Environments;
}

export class Client {
  constructor(public options: ClientOptions) {}

  hostname(): string {
    let part = 'sandbox';

    if (this.env === Environments.PRODUCTION) {
      part = 'api';
    }

    return `rest.${part}.example.com`;
  }
}

caller.js
----------

var client = new Client({
  id: 'id',
  secret: 'secret',
  env: 'production'
});

Right now, client.hostname() will fail because Environments.PRODUCTION === 1.

[mrcrowl]

👍

[olmobrutall]

My two cents while this gets approved:

Not that you can pretend this feature like this.

    export enum OrderType {
        Ascending = "Ascending" as any,
        Descending = "Descending" as any,
    }

The benefit is that then your API is better documented, asking for an OrderType instead of a dirty string.

The problem is that you need to repeat the identifier for the common case when declaring.

Also, when using it, you have to cast from string -> any -> OrdeType:

var orderType: OrderType = "Ascending"; //Error
var orderType: OrderType = "Ascending" as any; //OK

[OliverJAsh]

@weswigham Given your example, how come the final line here fails?

function mkenum<T extends {[index: string]: U}, U extends string>(x: T) { return x; }
const Cardinal = mkenum({
  North: 'N',
  South: 'S',
  East: 'E',
  West: 'W'
});
type Cardinal = (typeof Cardinal)[keyof typeof Cardinal];
const p = Cardinal.East
const x = { y: Cardinal.East }
interface z { foo: Cardinal.East } // 'Cardinal' only refers to a type, but is being used as a value here.

[OliverJAsh]

Here's my workaround for string enums with type and value position support, until 2.1 lands with keyof:

// Boilerplate for string enums until 2.1 (keyof)
// String enums can be used in type and value positions.
// https://github.com/Microsoft/TypeScript/issues/3192#issuecomment-261720275
export class ActionTypes {
	public static Foo: 'Foo' = 'Foo'
}

interface FooAction extends ReduxAction {
	type: typeof ActionTypes.Foo
}

[Jessidhia]

@OliverJAsh The error in #3192 (comment) is correct. You are using an "enum value" (Cardinal.East) as if it was a type. The type Cardinal is the union type of all valid const Cardinal values' types (in this example, 'N' | 'S' | 'E' | 'W').

If you want to define a type that has a key that can only ever have the value Cardinal.East, you're going to have to use typeof Cardinal.East; but that's probably not what you mean to do. interface z { foo: Cardinal } should work and allow any of the Cardinal values.

[nahuel]

@weswigham just a note about the mkenum example from #3192 (comment) : the inferred type here will be string, that's a different behaviour from using an standard numeric enum:

enum NumericEnum {
    A = 1
}

let a = NumericEnum.A              // a inferred type will be NumericEnum, good
let b = Cardinal.North             // b inferred type will be string, bad, is too generic, so ...
let c : Cardinal = Cardinal.North  // to have an useful type we must explicitely type c

[nahuel]

Here is a mkenum version were you don't need to specify the strings twice (merged with the previous mkenum example):

// original version:
function mkenum<T extends {[index: string]: U}, U extends string>(x: T) { return x; }
// new:
function mkenum2<X extends {[i:string] : any}, K extends string>(x : X ) 
  : {[K in (keyof X) ] : K}  {
    let o : any = {}
    for(let k in x) 
        o[k] = k;
    return o
}

// to define the type in a more succint way, for both versions:
export type enumType<T> = T[keyof T]

// define enums using the original and the new version:

const Colors  = mkenum({"Red"   : "Red", 
                        "Green" : "Green"});
type  Colors  = enumType<typeof Colors>

const Colors2 = mkenum2({"Red"   : 1, 
                         "Green" : 1});  // strings specified once, not twice
type  Colors2 = enumType<typeof Colors2>

let a  = Colors.Red       // string 
let a2 = Colors2.Red      // "Red"

let b  : Colors  = Colors.Red       // "Red" | "Green"
let b2 : Colors2 = Colors2.Red      // "Red" | "Green"

There is a little difference, the Colors constant is { Red : "Red", Green : "Green"} but the Colors2 constant is generated as { "Red" : "Red", "Green" : "Green"}.

Questions:

1. What's generally better, the type inferred for a (string) or the one inferred for a2 (the "Red" literal)?
2. If the one inferred for a is better, how do you change mkenum2 to generate a constant exactly like Colors to make a2 be inferred with the same type as a?
3. Is possible a mkenum version that takes as parameter an array like ["Red", "Green"] ?

[Gambero81]

Now with typescript 2.1 and keyof, there is a better implementation of string enum? and what about inline version for const string enum?

[igrayson]

@nahuel

Per your third question:

function mkenum3<X extends string>(...x:X[]):{[K in X]:K } {
  const o:any = {};
  for (const k in x)
    o[k] = k;
  return o;
}

type enumType<T> = T[keyof T];

const Colors3  = mkenum3('Red', 'Green');
type  Colors3  = enumType<typeof Colors3>;

[normalser]

@igrayson Is there any way to modify your version so it behave the same as @nahuel mkenum2 ?

let a2 = Colors2.Red // "Red"
let a3 = Colors3.Red // string -> would love to have "Red"

[dphilipson]

@igrayson Awesome solution! But I think your loop is incorrect. It should be

function mkenum3<X extends string>(...x:X[]):{[K in X]:K } {
  const o:any = {};
  for (const k in x)
    o[x[k]] = x[k];
  return o;
}

that is, iterate over the values of the array not the keys.

When I ran your version, the types were correct, but the runtime value of Colors3 was {"0": 0, "1", 1}.

[dphilipson]

I use the techniques here in several of my projects, so I turned them into an NPM module for easy access. See https://github.com/dphilipson/typescript-string-enums.

I don't mean to claim credit for this solution, and I did my best to credit the users who came up with it in the readme. Hopefully others will find this useful.

[pelotom]

The runtypes library allows defining a runtime type for a union of literals and then extracting both the static type as well as its enumerated values. Example usage:

// Define the runtype
const Day = Union(
  Literal('Sunday'),
  Literal('Monday'),
  Literal('Tuesday'),
  Literal('Wednesday'),
  Literal('Thursday'),
  Literal('Friday'),
  Literal('Saturday'),
)

// Extract the static type
type Day = Static<typeof Day> // = 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday'

// Extract enumerated literal values
const days: Day[] = Day.alternatives.map(lit => lit.value)

for (const day of days) {
  console.log(`Good morning, it's ${day}!`)
}

[kimamula]

With custom transformers introduced by #13940, you can create string enum from string literal types.

import { enumerate } from 'ts-transformer-enumerate';

type Colors = 'green' | 'yellow' | 'red';
const Colors = enumerate<Colors>(); // type of Colors is { [K in Colors]: K }

console.log(Colors.green); // 'green'
console.log(Colors.yellow); // 'yellow'
console.log(Colors.red); // 'red'

The above code is compiled to the following JavaScript.

var ts_transformer_enumerate_1 = require("ts-transformer-enumerate");
var Colors = { green: "green", yellow: "yellow", red: "red" }; // type of Colors is { [K in Colors]: K }
console.log(Colors.green); // 'green'
console.log(Colors.yellow); // 'yellow'
console.log(Colors.red); // 'red'

See https://github.com/kimamula/ts-transformer-enumerate.

[ahejlsberg]

Implementation now available in #15486.

[RyanCavanaugh]

Let's track this at #1206