Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: String enums #3192

Closed
jbondc opened this issue May 17, 2015 · 70 comments
Closed

Proposal: String enums #3192

jbondc opened this issue May 17, 2015 · 70 comments
Assignees
Labels
Duplicate An existing issue was already created

Comments

@jbondc
Copy link
Contributor

jbondc commented May 17, 2015

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"
}
@mhegazy mhegazy added the Suggestion An idea for TypeScript label May 28, 2015
@mariusschulz
Copy link
Contributor

👍

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
Copy link

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

@dead-claudia
Copy link

@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
Copy link

@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
Copy link

@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
Copy link

lazdmx commented Jul 16, 2015

👍 for string (const) enums

@danquirk danquirk added the Needs Proposal This issue needs a plan that clarifies the finer details of how it could be implemented. label Jul 20, 2015
@rotemdan
Copy link

rotemdan commented Sep 4, 2015

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
Copy link
Contributor

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
Copy link

rotemdan commented Sep 4, 2015

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
Copy link

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
Copy link

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

@dead-claudia
Copy link

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

@dead-claudia
Copy link

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
Copy link

vitrilo commented Sep 29, 2015

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
Copy link
Contributor

basarat commented Sep 30, 2015

Probably better if #1003 is done instead

@dead-claudia
Copy link

@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
Copy link

I made a relevant response over there on #1003.

@dead-claudia
Copy link

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

@vitrilo
Copy link

vitrilo commented Sep 30, 2015

@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
Copy link

jtheoof commented Nov 20, 2015

👍 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
Copy link

mrcrowl commented Nov 26, 2015

👍

@olmobrutall
Copy link

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
Copy link
Contributor

@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
Copy link
Contributor

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
Copy link

Jessidhia commented Nov 22, 2016

@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
Copy link

nahuel commented Dec 7, 2016

@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
Copy link

nahuel commented Dec 7, 2016

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
Copy link

Gambero81 commented Dec 7, 2016

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
Copy link

igrayson commented Jan 4, 2017

@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
Copy link

@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
Copy link

dphilipson commented Jan 18, 2017

@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
Copy link

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
Copy link

pelotom commented Feb 27, 2017

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
Copy link
Contributor

kimamula commented Apr 25, 2017

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
Copy link
Member

ahejlsberg commented May 1, 2017

Implementation now available in #15486.

@RyanCavanaugh
Copy link
Member

Let's track this at #1206

@RyanCavanaugh RyanCavanaugh added Duplicate An existing issue was already created and removed Needs Proposal This issue needs a plan that clarifies the finer details of how it could be implemented. Suggestion An idea for TypeScript labels May 1, 2017
@microsoft microsoft locked and limited conversation to collaborators Jun 19, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Duplicate An existing issue was already created
Projects
None yet
Development

No branches or pull requests