Add support for decoding non-const enums. (#25)

* Add support for decoding non-const enums.

* Add documentation, set target back to es5, bump version, and minor cleanups.

README.md

@@ -101,6 +101,37 @@ JsonDecoder.boolean.decode(true); // Ok<boolean>({value: true})
 JsonDecoder.boolean.decode(null); // Err({error: 'null is not a valid boolean'})
 ```
 
+### JsonDecoder.enumeration
+
+> `enumeration<e>(enumObj: object, decoderName: string): Decoder<e>`
+
+Creates a decoder for a (non-const) enum.
+
+#### @param `enumObj: object`
+
+The enum object to use for decoding. This doesn't exist for const enums.
+
+#### @param `decoderName: string`
+
+Type of the object we are decoding. i.e. `User`. It is used to generate meaningful decoding error messages.
+
+#### Basic example
+
+```ts
+enum ExampleEnum {
+ X = 1,
+ Y, /* 2 */
+ Z = 'foo',
+}
+
+const exampleEnumDecoder = JsonDecoder.enumeration<ExampleEnum>(
+ ExampleEnum, 'ExampleEnum');
+
+exampleEnumDecoder.decode(1); // Ok<ExampleEnum>({value: 1})
+exampleEnumDecoder.decode(ExampleEnum.Y); // Ok<ExampleEnum>({value: 2})
+exampleEnumDecoder.decode(3); // Err({error: '<ExampleEnum> decoder failed at value "3" which is not in the enum'})
+```
+
 ### JsonDecoder.object
 
 > `object<a>(decoders: DecoderObject<a>, decoderName: string, keyMap?: DecoderObjectKeyMap<a>): Decoder<a>`

package.json

@@ -1,6 +1,6 @@
 {
  "name": "ts.data.json",
- "version": "1.2.0",
+ "version": "1.3.0",
  "description": "A JSON decoding library for Typescript",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",

src/json-decoder.spec.ts

@@ -88,6 +88,54 @@ describe('json-decoder', () => {
  });
  });
 
+ // enumeration
+ describe('enumeration', () => {
+ enum IntEnum {
+ A,
+ B,
+ C,
+ }
+ enum OddlyOrderedIntEnum {
+ A = 2,
+ B = 8,
+ C = -3,
+ }
+ enum HeterogeneousEnum {
+ X = 1,
+ Y, /* 2 */
+ Z = 'foo',
+ }
+ it('should decode when the value is in the enum', () => {
+ expectOkWithValue(JsonDecoder.enumeration<IntEnum>(IntEnum, 'IntEnum').decode(1),
+ IntEnum.B /* 1 */);
+ expectOkWithValue(JsonDecoder.enumeration<OddlyOrderedIntEnum>(
+ OddlyOrderedIntEnum, 'OddlyOrderedIntEnum').decode(-3),
+ OddlyOrderedIntEnum.C /* -3 */);
+ expectOkWithValue(JsonDecoder.enumeration<HeterogeneousEnum>(
+ HeterogeneousEnum, 'HeterogeneousEnum').decode(2),
+ HeterogeneousEnum.Y /* 2 */);
+ expectOkWithValue(JsonDecoder.enumeration<HeterogeneousEnum>(
+ HeterogeneousEnum, 'HeterogeneousEnum').decode('foo'),
+ HeterogeneousEnum.Z /* 'foo' */);
+ });
+ it('should fail when the value is not in the enum', () => {
+ expectErrWithMsg(
+ JsonDecoder.enumeration<IntEnum>(IntEnum, 'IntEnum').decode(3),
+ $JsonDecoderErrors.enumValueError('IntEnum', 3)
+ );
+ expectErrWithMsg(
+ JsonDecoder.enumeration<IntEnum>(
+ OddlyOrderedIntEnum, 'OddlyOrderedIntEnum').decode(3),
+ $JsonDecoderErrors.enumValueError('OddlyOrderedIntEnum', 3)
+ );
+ expectErrWithMsg(
+ JsonDecoder.enumeration<HeterogeneousEnum>(
+ HeterogeneousEnum, 'HeterogeneousEnum').decode(0),
+ $JsonDecoderErrors.enumValueError('HeterogeneousEnum', 0)
+ );
+ });
+ });
+
  // failover
  describe('failover (on failure provide a default value)', () => {
  it('should decode a value when value is provided', () => {

src/json-decoder.ts

@@ -119,6 +119,25 @@ export namespace JsonDecoder {
  }
  });
 
+ /**
+ * Decode for `enumeration`.
+ *
+ * @param enumObj The enum object to use for decoding. Must not be a const enum.
+ * @param decoderName How to display the name of the object being decoded in errors.
+ */
+ export function enumeration<e>(
+ enumObj: object,
+ decoderName: string
+ ): Decoder<e> {
+ return new Decoder<e>((json: any) => {
+ const enumValue = Object.values(enumObj).find((x: any) => x === json);
+ if (enumValue) {
+ return ok<e>(enumValue);
+ }
+ return err<e>($JsonDecoderErrors.enumValueError(decoderName, json));
+ });
+ }
+
  export type DecoderObject<a> = { [p in keyof Required<a>]: Decoder<a[p]> };
  export type DecoderObjectKeyMap<a> = { [p in keyof a]?: string };
 
@@ -584,6 +603,12 @@ export namespace $JsonDecoderErrors {
  json
  )} can't be decoded with any of the provided oneOf decoders`;
 
+ export const enumValueError = (
+ decoderName: string,
+ invalidValue: any,
+ ): string =>
+ `<${decoderName}> decoder failed at value "${invalidValue}" which is not in the enum`;
+
  export const objectError = (
  decoderName: string,
  key: string,

tsconfig.json

@@ -7,7 +7,7 @@
  "outDir": "./dist",
  "strict": true,
  "lib": [
- "es2016",
+ "ES2017",
  "dom"
  ]
  },