Merge pull request #36 from mojotech/em/constant-inference

Improve constant decoder type inference

Author: mulias

src/decoder.ts

@@ -203,75 +203,37 @@ export class Decoder<A> {
   /**
    * Decoder primitive that only matches on exact values.
    *
-   * Note that `constant('string to match')` returns a `Decoder<string>` which
-   * fails if the input is not equal to `'string to match'`. In many cases this
-   * is sufficient, but in some situations typescript requires that the decoder
-   * type be a type-literal. In such a case you must provide the type parameter,
-   * which looks like `constant<'string to match'>('string to match')`.
-   *
-   * Providing the type parameter is only necessary for type-literal strings
-   * and numbers, as detailed by this table:
-   *
-   * ```
-   *  | Decoder                      | Type                 |
-   *  | ---------------------------- | ---------------------|
-   *  | constant(true)               | Decoder<true>        |
-   *  | constant(false)              | Decoder<false>       |
-   *  | constant(null)               | Decoder<null>        |
-   *  | constant('alaska')           | Decoder<string>      |
-   *  | constant<'alaska'>('alaska') | Decoder<'alaska'>    |
-   *  | constant(50)                 | Decoder<number>      |
-   *  | constant<50>(50)             | Decoder<50>          |
-   *  | constant([1,2,3])            | Decoder<number[]>    |
-   *  | constant<[1,2,3]>([1,2,3])   | Decoder<[1,2,3]>     |
-   *  | constant({x: 't'})           | Decoder<{x: string}> |
-   *  | constant<{x: 't'}>({x: 't'}) | Decoder<{x: 't'}>    |
-   * ```
-   *
-   *
-   * One place where this happens is when a type-literal is in an interface:
-   * ```
-   * interface Bear {
-   *   kind: 'bear';
-   *   isBig: boolean;
-   * }
-   *
-   * const bearDecoder1: Decoder<Bear> = object({
-   *   kind: constant('bear'),
-   *   isBig: boolean()
-   * });
-   * // Type 'Decoder<{ kind: string; isBig: boolean; }>' is not assignable to
-   * // type 'Decoder<Bear>'. Type 'string' is not assignable to type '"bear"'.
-   *
-   * const bearDecoder2: Decoder<Bear> = object({
-   *   kind: constant<'bear'>('bear'),
-   *   isBig: boolean()
-   * });
-   * // no compiler errors
-   * ```
-   *
-   * Another is in type-literal unions:
-   * ```
-   * type animal = 'bird' | 'bear';
-   *
-   * const animalDecoder1: Decoder<animal> = union(
-   *   constant('bird'),
-   *   constant('bear')
-   * );
-   * // Type 'Decoder<string>' is not assignable to type 'Decoder<animal>'.
-   * // Type 'string' is not assignable to type 'animal'.
-   *
-   * const animalDecoder2: Decoder<animal> = union(
-   *   constant<'bird'>('bird'),
-   *   constant<'bear'>('bear')
-   * );
-   * // no compiler errors
+   * For primitive values and shallow structures of primitive values `constant`
+   * will infer an exact literal type:
+   * ```
+   *  | Decoder                      | Type                          |
+   *  | ---------------------------- | ------------------------------|
+   *  | constant(true)               | Decoder<true>                 |
+   *  | constant(false)              | Decoder<false>                |
+   *  | constant(null)               | Decoder<null>                 |
+   *  | constant(undefined)          | Decoder<undefined>            |
+   *  | constant('alaska')           | Decoder<'alaska'>             |
+   *  | constant(50)                 | Decoder<50>                   |
+   *  | constant([1,2,3])            | Decoder<[1,2,3]>              |
+   *  | constant({x: 't'})           | Decoder<{x: 't'}>             |
+   * ```
+   *
+   * Inference breaks on nested structures, which require an annotation to get
+   * the literal type:
+   * ```
+   *  | Decoder                      | Type                          |
+   *  | -----------------------------|-------------------------------|
+   *  | constant([1,[2]])            | Decoder<(number|number[])[]>  |
+   *  | constant<[1,[2]]>([1,[2]])   | Decoder<[1,[2]]>              |
+   *  | constant({x: [1]})           | Decoder<{x: number[]}>        |
+   *  | constant<{x: [1]}>({x: [1]}) | Decoder<{x: [1]}>             |
    * ```
    */
-  static constant(value: true): Decoder<true>;
-  static constant(value: false): Decoder<false>;
-  static constant<A>(value: A): Decoder<A>;
-  static constant(value: any): Decoder<any> {
+  static constant<T extends string | number | boolean | []>(value: T): Decoder<T>;
+  static constant<T extends string | number | boolean, U extends [T, ...T[]]>(value: U): Decoder<U>;
+  static constant<T extends string | number | boolean, U extends Record<string, T>>(value: U): Decoder<U>;
+  static constant<T>(value: T): Decoder<T>;
+  static constant(value: any) {
     return new Decoder(
       (json: unknown) =>
         isEqual(json, value)

test/json-decode.test.ts

@@ -138,13 +138,13 @@ describe('unknownJson', () => {
 
 describe('constant', () => {
   it('works for string-literals', () => {
-    const decoder = constant<'zero'>('zero');
+    const decoder: Decoder<'zero'> = constant('zero');
 
     expect(decoder.run('zero')).toEqual({ok: true, result: 'zero'});
   });
 
   it('fails when given two different values', () => {
-    const decoder = constant<42>(42);
+    const decoder: Decoder<42> = constant(42);
 
     expect(decoder.run(true)).toMatchObject({
       ok: false,
@@ -180,8 +180,7 @@ describe('constant', () => {
   });
 
   it('can decode a constant array', () => {
-    type A = [1, 2, 3];
-    const decoder: Decoder<A> = constant<A>([1, 2, 3]);
+    const decoder: Decoder<[1, 2, 3]> = constant([1, 2, 3]);
 
     expect(decoder.run([1, 2, 3])).toEqual({ok: true, result: [1, 2, 3]});
     expect(decoder.run([1, 2, 3, 4])).toMatchObject({
@@ -191,8 +190,7 @@ describe('constant', () => {
   });
 
   it('can decode a constant object', () => {
-    type O = {a: true; b: 12};
-    const decoder: Decoder<O> = constant<O>({a: true, b: 12});
+    const decoder: Decoder<{a: true; b: 12}> = constant({a: true, b: 12});
 
     expect(decoder.run({a: true, b: 12})).toEqual({ok: true, result: {a: true, b: 12}});
     expect(decoder.run({a: true, b: 7})).toMatchObject({
@@ -579,8 +577,8 @@ describe('union', () => {
   type C = A | B;
 
   const decoder: Decoder<C> = union(
-    object({kind: constant<'a'>('a'), value: number()}),
-    object({kind: constant<'b'>('b'), value: boolean()})
+    object({kind: constant('a'), value: number()}),
+    object({kind: constant('b'), value: boolean()})
   );
 
   it('can decode a value that matches one of the union types', () => {