Embind: `enums` are not serializable. Couldn't the implementation be simplified ?

[FelixNumworks]

When I'm storing an enum value binded via embind in a js var, I can't use JSON.stringify on it.

Current implementation:

I'm not understanding very well why the enums are binded the way they are today, attaching values to their constructor.

Register enum

emscripten/src/lib/libembind.js

Lines 2277 to 2295 in 1cb178b

	_embind_register_enum: (rawType, name, size, isSigned) => {
	name = readLatin1String(name);
	function ctor() {}
	ctor.values = {};
	registerType(rawType, {
	name,
	constructor: ctor,
	'fromWireType': function(c) {
	return this.constructor.values[c];
	},
	'toWireType': (destructors, c) => c.value,
	argPackAdvance: GenericWireTypeSize,
	'readValueFromPointer': enumReadValueFromPointer(name, size, isSigned),
	destructorFunction: null,
	});
	exposePublicSymbol(name, ctor);
	},

Register enum value

emscripten/src/lib/libembind.js

Lines 2298 to 2310 in 1cb178b

	_embind_register_enum_value: (rawEnumType, name, enumValue) => {
	var enumType = requireRegisteredType(rawEnumType, 'enum');
	name = readLatin1String(name);
	var Enum = enumType.constructor;
	var Value = Object.create(enumType.constructor.prototype, {
	value: {value: enumValue},
	constructor: {value: createNamedFunction(`${enumType.name}_${name}`, function() {})},
	});
	Enum.values[enumValue] = Value;
	Enum[name] = Value;
	},

Suggested implementation

Isn't it possible to replace with something along those lines:

Register enum

  _embind_register_enum: (rawType, name, size, isSigned) => {
    name = readLatin1String(name);
    var values = {};
    registerType(rawType, {
      name,
      values,
      fromWireType: (c) => {
        return Object.values(values).find((v) => v.value === c);
      },
      toWireType: (destructors, c) => c.value,
      argPackAdvance: GenericWireTypeSize,
      'readValueFromPointer': enumReadValueFromPointer(name, size, isSigned),
      destructorFunction: null,
    });
    exposePublicSymbol(name, values);
  },

Register enum value

  _embind_register_enum_value: (rawEnumType, name, enumValue) => {
    var enumType = requireRegisteredType(rawEnumType, 'enum');
    name = readLatin1String(name);
    enumType.values[name] = { value: enumValue };
  },

I'm just creating a values object tied to the enum type. And enum values are just a simple object { value: ... }

It seems to me that it doesn't change how enums are used, but it makes them way more flexible, as they are just simple js object.

Typescript

You could even add the enum name to the the enum values to strongly type them in typescript

  _embind_register_enum_value: (rawEnumType, name, enumValue) => {
    var enumType = requireRegisteredType(rawEnumType, 'enum');
    name = readLatin1String(name);
    enumType.values[name] = { value: enumValue, enumType: enumType.name };
  },

In the .d.ts file:

export interface MyEnumValue<T extends number> {
  value: T;
  enumType: "MyEnum";
}

export type MyEnum = MyEnumValue<0> | MyEnumValue<1> | MyEnumValue<2>;

interface EmbindModule {
  MyEnum: { MyFirstValue: MyEnumValue<0>, MySecondValue: MyEnumValue<1>, MyThirdValue: MyEnumValue<2> }
}

Maybe there is something I'm not grasping here ...

[FelixNumworks]

This simpler implementation would also fix #19387 and #18585

[FelixNumworks]

You could even just expose strings to have something like this:

export type MyType = 'MyFirstValue' | 'MySecondValue' | 'MyThirdValue';

interface EmbindModule {
  MyTypeEnum: { MyFirstValue: 'MyFirstValue', MySecondValue: 'MySecondValue', MyThirdValue: 'MyThirdValue' };
}

The implementation would be like this:

__embind_register_enum: (rawType, name, size, isSigned) => {
    name = readLatin1String(name);
    var valuesDict = {};
    var keysDict = {};
    registerType(rawType, {
      name: name,
      valuesDict,
      keysDict,
      fromWireType: (c) => Object.keys(valuesDict).find((key) => valuesDict[key] === c),
      toWireType: (destructors, c) => valuesDict[c],
      argPackAdvance: GenericWireTypeSize,
      readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
      destructorFunction: null,
    });
    exposePublicSymbol(name + 'Enum', keysDict);
  };

__embind_register_enum_value: (rawEnumType, name, enumValue) => {
    var enumType = requireRegisteredType(rawEnumType, 'enum');
    name = readLatin1String(name);
    enumType.valuesDict[name] = enumValue;
    enumType.keysDict[name] = name;
  };

EDIT: This implementation is very handy for my case. For those who want to have those string enums, you can add this in you pre-js file:

// pre-js.js

/**
 * DIRTY HACK
 * This changes the way the enums are registered in the JS code.
 * The enum values are now registered as strings, so that they can be
 * more easily used in JS code (e.g. for stringification, comparison, etc.)
 * The enum values are stored in a "valuesDict" object for wireType conversion.
 * The values are exposed by a dict named "<enum_name>Enum" for easy access.
 * Example: module.PrimaryColorEnum.Red === 'Red'
 */

function replaceEnumRegistration() {
  /* module.js has the following structure:
   *
   * ```
   * function __embind_register_enum () { ... }
   * function __embind_register_enum_value () { ... }
   * ...
   * var wasmImports = {
   *   ...
   *   unknown_key_1: __embind_register_enum,
   *   unknown_key_2: __embind_register_enum_value,
   *   ...
   * }
   * ```
   *
   * To replace the __embind_register_enum and __embind_register_enum_value
   * functions, we need to find the keys that points to them in the wasmImports
   * object, and then point them to our new functions.
   */
  replaceWasmImport(__embind_register_enum, (rawType, name, size, isSigned) => {
    name = readLatin1String(name);
    var valuesDict = {};
    var keysDict = {};
    registerType(rawType, {
      name: name,
      valuesDict,
      keysDict,
      fromWireType: (c) => Object.keys(valuesDict).find((key) => valuesDict[key] === c),
      toWireType: (destructors, c) => valuesDict[c],
      argPackAdvance: GenericWireTypeSize,
      readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
      destructorFunction: null,
    });
    exposePublicSymbol(name + 'Enum', keysDict);
    // TODO: I'm not sure why this property is added in the first place
    delete Module[name + 'Enum'].argCount;
  });

  replaceWasmImport(__embind_register_enum_value, (rawEnumType, name, enumValue) => {
    var enumType = requireRegisteredType(rawEnumType, 'enum');
    name = readLatin1String(name);
    enumType.valuesDict[name] = enumValue;
    enumType.keysDict[name] = name;
  });
}

function replaceWasmImport(originalImport, newImport) {
  const importKey = Object.keys(wasmImports).find((key) => wasmImports[key] === originalImport);
  if (importKey) {
    wasmImports[importKey] = newImport;
  }
}

// Defer the enum registration function (we need to wait for wasmImports to be defined)
Promise.resolve().then(replaceEnumRegistration);

You need to manually edit your .d.ts though (or use some kind of custom script to modify it)

[brendandahl]

Enums in embind were created before TS was popular. I'm open to changing the way enums work to be more inline with TS. Are you able to do it in a way that doesn't break the previous users? Alternatively, we could add new way to declare TS style enums.

[FelixNumworks]

If the change is implemented, it would totally broke the previous implementation of enums as we'd go from this:

export type MyTypeValue<T extends number> {
  value: T
}

export type MyType = MyTypeValue<0> | MyTypeValue<1> | MyTypeValue<2>;

interface EmbindModule {
  MyType: { MyFirstValue: MyTypeValue<0>, MySecondValue: MyTypeValue<1>, MyThirdValue: MyTypeValue<2> };
}

to this

export type MyType = 'MyFirstValue' | 'MySecondValue' | 'MyThirdValue';

interface EmbindModule {
  MyTypeEnum: { MyFirstValue: 'MyFirstValue', MySecondValue: 'MySecondValue', MyThirdValue: 'MyThirdValue' };
}

Main changes:

• Cannot access .value on the enum values
• Enum values are just plain strings
• (optional) the object bound to the Module is renamed MyTypeEnum vs MyType

[brendandahl]

If we are going to add different enum support, why not use TS's enum?

[FelixNumworks]

If we are going to add different enum support, why not use TS's enum?

It seems to me that using TypeScript enums directly isn't feasible for a few reasons:

• Emscripten generates a .js file for module instantiation, and enums are a TypeScript-only feature. To mirror the same behavior in JS, we’d effectively have to "reimplement" TypeScript enums in plain JavaScript.
• The current "enums" generated by embind are attached to the Module object, whereas TypeScript enums can only be declared at the top level.

The best compromise seems to be defining a TypeScript type for the enum (as I’ve done above), and then adding a dictionary to the module object with the same name and values:

export type MyEnum = 'MyFirstValue' | 'MySecondValue' | 'MyThirdValue';

interface EmbindModule {
  MyEnum: {
    MyFirstValue: 'MyFirstValue',
    MySecondValue: 'MySecondValue',
    MyThirdValue: 'MyThirdValue'
  };
}

This makes the implementation behave very similarly to TypeScript string enums, without relying on the enum keyword. The enum type can be used either by:

• Referring to the string directly (e.g., 'MyFirstValue')
• Accessing the enum-like dictionary (e.g., Module.MyEnum.MyFirstValue)