Improve changelog and documentation

lydell · lydell · commit db5f2cb697f5 · 2023-10-21T20:56:16.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,28 +2,62 @@ Note: I’m currently working on several breaking changes to tiny-decoders, but
 
 ### Version 11.0.0 (unreleased)
 
-- Changed: `fieldsAuto` works slightly differently. As part of that change, `optional` has been removed and replaced by `undefinedOr` and `field`. These changes make `fields` redundant, so it has been deprecated.
+This release deprecates `fields`, and makes `fieldsAuto` more powerful so that it can do most of what only `fields` could before. Removing `fields` unlocks further changes that will come in future releases. It’s also nice to have just one way of decoding objects (`fieldsAuto`), instead of having two. Finally, the changes to `fieldsAuto` gets rid of a flawed design choice which solves several reported bugs: [#22](https://github.com/lydell/tiny-decoders/issues/22) and [#24](https://github.com/lydell/tiny-decoders/issues/24).
 
-- Added: `recursive`. It’s needed now that `fields` has been deprecated.
+- Changed: `optional` has been removed and replaced by `undefinedOr` and a new function called `field`. The `optional` function did two things: It made a decoder also accept `undefined`, and marked fields as optional. Now there’s one function for each use case.
 
-- Changed: TypeScript 5+, because the above uses [const type parameters](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#const-type-parameters)) (added in 5.0), and leads to [exactOptionalPropertyTypes](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) (added in 4.4) option in `tsconfig.json` being recommended.
+- Added: The new `field` function returns a `Field` type, which is a decoder with some metadata. The metadata tells whether the field is optional, and whether the field has a different name in the JSON object.
+
+- Changed: `fieldsAuto` takes an object like before, where the values are `Decoder`s like before, but now the values can be `Field`s as well (returned from the `field` function). Passing a plain `Decoder` instead of a `Field` is just a convenience shortcut for passing a `Field` with the default metadata (the field is required, and has the same name both in TypeScript and in JSON).
+
+- Changed: `fieldsAuto` no longer computes which fields are optional by checking if the type of the field includes `| undefined`. Instead, it’s based purely on the `Field` metadata.
+
+- Changed: `const myDecoder = fieldsAuto<MyType>({ /* ... */ })` now needs to be written as `const myDecoder: Decoder<MyType> = fieldsAuto({ /* ... */ })`. It is no longer recommended to specify the generic of `fieldsAuto`, and doing so does not mean the same thing anymore. Either annotate the decoder as any other, or don’t and infer the type.
+
+- Added: `recursive`. It’s needed when making a decoder for a recursive data structure using `fieldsAuto`. (Previously, the recommendation was to use `fields` for recursive objects.)
+
+- Changed: TypeScript 5+ is now required, because the above uses [const type parameters](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#const-type-parameters)) (added in 5.0), and leads to the [exactOptionalPropertyTypes](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) (added in 4.4) option in `tsconfig.json` being recommended (see the documentation for the `field` function for why).
 
 The motivation for the changes are:
 
-- Supporting TypeScript’s [exactOptionalPropertyTypes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/#exact-optional-property-types) option.
-- Supporting generic decoders.
-- Stop setting all optional fields to `undefined` when they are missing (rather than leaving them out).
+- Supporting TypeScript’s [exactOptionalPropertyTypes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/#exact-optional-property-types) option. That option decouples optional fields (`field?:`) and union with undefined (`| undefined`). Now tiny-decoders has done that too.
+
+- Supporting generic decoders. Marking the fields as optional was previously done by looking for fields with `| undefined` in their type. However, if the type of a field is generic, TypeScript can’t know if the type is going to have `| undefined` until the generic type is instantiated with a concrete type. As such it couldn’t know if the field should be optional or not yet either. This resulted in it being very difficult and ugly trying to write a type annotation for a generic function returning a decoder – in practice it was unusable without forcing TypeScript to the wanted type annotation. [#24](https://github.com/lydell/tiny-decoders/issues/24)
+
+- Stop setting all optional fields to `undefined` when they are missing (rather than leaving them out). [#22](https://github.com/lydell/tiny-decoders/issues/22)
+
 - Better error messages for missing required fields.
-- Being able to rename fields with `fieldsAuto`. Now you don’t need to refactor from `fieldsAuto` to `fields` anymore if you need to rename a field.
-- Getting rid of `fields` unlocks further changes that will come in future releases. (Note: `fields` is only deprecated in this release, not removed.)
 
-The `optional` function did two things: It made a decoder also accept `undefined`, and marked fields as optional. Marking the fields as optional was done by looking for fields with `| undefined` in their type. However, if the type of a field is generic, TypeScript can’t know if the type is going to have `| undefined` until the generic type is instantiated with a concrete type. As such it couldn’t know if the field should be optional or not yet either. This resulted in it being very difficult and ugly trying to write a type annotation for a generic function returning a decoder. This design also doesn’t let you use `exactOptionalPropertyTypes` as intended. The whole concept was flawed.
+  Before:
 
-`optional` has therefore been renamed to `undefinedOr`, and now it does only one thing: Makes a decoder also accept `undefined`.
+  ```
+  At root["firstName"]:
+  Expected a string
 
-The `field` function has been introduced to mark fields as optional, separating the two jobs that `optional` used to do.
+  Got: undefined
+  ```
 
-For example:
+  After:
+
+  ```
+  At root:
+  Expected an object with a field called: "firstName"
+  Got: {
+    "id": 1,
+    "first_name": "John"
+  }
+  ```
+
+  In other words, `fieldsAuto` now checks if fields exist, rather than trying to access them regardless. Previously, `fieldsAuto` ran `decoderAtKey(object[key])` even when `key` did not exist in `object`, which is equivalent to `decoderAtKey(undefined)`. Whether or not that succeeded was up to if `decoderAtKey` was using `optional` or not. This resulted in the worse (but technically correct) error message. The new version of `fieldsAuto` knows if the field is supposed to be optional or not thanks to the `Field` type and the `field` function mentioned above.
+
+  > **Warning**  
+  > Temporary behavior: If a field is missing and _not_ marked as optional, `fieldsAuto` still _tries_ the decoder at the field (passing `undefined` to it). If the decoder succeeds (because it allows `undefined` or succeeds for any input), that value is used. If it fails, the regular “missing field” error is thrown. This means that `fieldsAuto({ name: undefinedOr(string) })` successfully produces `{ name: undefined }` if given `{}` as input. It is supposed to fail in that case (because a required field is missing), but temporarily it does not fail. This is to support how `fieldsUnion` is used currently. When `fieldsUnion` is updated to a new API in an upcoming version of tiny-decoders, this temporary behavior in `fieldsAuto` will be removed.
+
+- Being able to rename fields with `fieldsAuto`. Now you don’t need to refactor from `fieldsAuto` to `fields` anymore if you need to rename a field. This is done by using the `field` function.
+
+- Getting rid of `fields` unlocks further changes that will come in future releases. (Note: `fields` is only deprecated in this release, not removed.)
+
+Here’s an example illustrating the difference between optional fields and accepting `undefined`:
 
 ```ts
 fieldsAuto({
@@ -41,6 +75,17 @@ fieldsAuto({
 });
 ```
 
+The inferred type of the above is:
+
+```ts
+type Inferred = {
+  a: string;
+  b?: string;
+  c: string | undefined;
+  d?: string | undefined;
+};
+```
+
 In all places where you use `optional(x)` currently, you need to figure out if you should use `undefinedOr(x)` or `field(x, { optional: true })` or `field(undefinedOr(x), { optional: true })`.
 
 The `field` function also lets you rename fields. This means that you can refactor:
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ npm install tiny-decoders
 
 tiny-decoders requires TypeScript 5+ (because it uses [const type parameters](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#const-type-parameters)).
 
-It is recommended to enable the [exactOptionalPropertyTypes](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) option in `tsconfig.json`.
+It is recommended to enable the [exactOptionalPropertyTypes](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) option in `tsconfig.json` – see the note at the [field](#field) function.
 
 Note that it is possible to use tiny-decoders in plain JavaScript without type checking as well.
 
@@ -79,7 +79,7 @@ You can even [infer the type from the decoder](#type-inference) instead of writi
 type User2 = ReturnType<typeof userDecoder2>;
 ```
 
-The above produces the `User` type already shown above.
+`User2` above is equivalent to the `User` type already shown earlier.
 
 ## Decoder&lt;T&gt;
 
@@ -494,6 +494,10 @@ function field<Decoded, const Meta extends FieldMeta>(
   meta: Meta,
 ): Field<Decoded, Meta>;
 
+type Field<Decoded, Meta extends FieldMeta> = Meta & {
+  decoder: Decoder<Decoded>;
+};
+
 type FieldMeta = {
   renameFrom?: string | undefined;
   optional?: boolean | undefined;
@@ -508,6 +512,35 @@ This function takes a decoder and lets you:
 
 Use it with [fieldsAuto](#fieldsAuto).
 
+Here’s an example illustrating the difference between `field(string, { optional: true })` and `undefinedOr(string)`:
+
+```ts
+const exampleDecoder = fieldsAuto({
+  // Required field.
+  a: string,
+
+  // Optional field.
+  b: field(string, { optional: true }),
+
+  // Required field that can be set to `undefined`:
+  c: undefinedOr(string),
+
+  // Optional field that can be set to `undefined`:
+  d: field(undefinedOr(string), { optional: true }),
+});
+```
+
+The inferred type of `exampleDecoder` is:
+
+```ts
+type Example = {
+  a: string;
+  b?: string;
+  c: string | undefined;
+  d?: string | undefined;
+};
+```
+
 > **Warning**  
 > It is recommended to enable the [exactOptionalPropertyTypes](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) option in `tsconfig.json`.
 >
@@ -543,7 +576,7 @@ Use it with [fieldsAuto](#fieldsAuto).
 >
 > That gives the same inferred type, but also supports decoding the `name` field being set to `undefined` explicitly.
 >
-> All in all, you avoid a slight gotcha with optional fields and inferred types if you use `exactOptionalPropertyTypes`.
+> All in all, you avoid a slight gotcha with optional fields and inferred types if you enable `exactOptionalPropertyTypes`.
 
 ### fieldsUnion
 
@@ -945,10 +978,15 @@ Rather than first defining the type and then defining the decoder (which often f
 ```ts
 const personDecoder = fieldsAuto({
   name: string,
-  age: optional(number),
+  age: number,
 });
 
 type Person = ReturnType<typeof personDecoder>;
+// equivalent to:
+type Person = {
+  name: string;
+  age: number;
+};
 ```
 
 See the [type inference example](examples/type-inference.test.ts) for more details.
diff --git a/examples/readme.test.ts b/examples/readme.test.ts
@@ -209,3 +209,44 @@ test("fieldsAuto", () => {
     name: undefined,
   });
 });
+
+test("field", () => {
+  const exampleDecoder = fieldsAuto({
+    // Required field.
+    a: string,
+
+    // Optional field.
+    b: field(string, { optional: true }),
+
+    // Required field that can be set to `undefined`:
+    c: undefinedOr(string),
+
+    // Optional field that can be set to `undefined`:
+    d: field(undefinedOr(string), { optional: true }),
+  });
+
+  type Example = {
+    a: string;
+    b?: string;
+    c: string | undefined;
+    d?: string | undefined;
+  };
+
+  expectType<TypeEqual<ReturnType<typeof exampleDecoder>, Example>>(true);
+
+  expect(exampleDecoder({ a: "", c: undefined })).toStrictEqual({
+    a: "",
+    c: undefined,
+  });
+
+  expect(
+    exampleDecoder({ a: "", b: "", c: undefined, d: undefined }),
+  ).toStrictEqual({ a: "", b: "", c: undefined, d: undefined });
+
+  expect(exampleDecoder({ a: "", b: "", c: "", d: "" })).toStrictEqual({
+    a: "",
+    b: "",
+    c: "",
+    d: "",
+  });
+});
