feat: add State generic to field types

[angeloashmore]

Types of changes

• Chore (a non-breaking change which is related to package maintenance)
• Bug fix (a non-breaking change which fixes an issue)
• New feature (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR adds a State generic to field types that can be empty. For example, a Select field can be empty which returns null rather than a string.

In the following example, State is the second generic.

import * as prismicT from "@prismicio/types"

type MyField = prismicT.SelectField<"Option 1" | "Option 2", "empty">
// MyField === null

To explicitly set the field as "filled":

import * as prismicT from "@prismicio/types"

type MyField = prismicT.SelectField<"Option 1" | "Option 2", "filled">
// MyField === "Option 1" | "Option 2"

By default, the state is ambiguous (i.e. "empty" | "filled"):

import * as prismicT from "@prismicio/types"

type MyField = prismicT.SelectField<"Option 1" | "Option 2">
// MyField === "Option 1" | "Option 2" | null

Related @prismicio/mock PR: prismicio/prismic-mock#4

Checklist:

• My change requires an update to the official documentation.
• All TSDoc comments are up-to-date and new ones have been added where necessary.
• All new and existing tests are passing.

🦮

[codecov-commenter]

Codecov Report

Merging #13 (460f466) into master (b075b39) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##            master       #13   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines           59        59           
=========================================
  Hits            59        59           

Impacted Files	Coverage Δ
src/fields.ts	100.00% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b075b39...460f466. Read the comment docs.

[lihbr]

LGTM, that's quite a weird way of doing a "union if" but seems like the only way ^^'

Maybe you can add a short TSDoc for the isEmpty type params to explain it (others can be postponed for now)

If boolean is still too obscure have you considered using a string type? Something like this (not as nice maybe but I actually quite like it, and gives the "filled" state as a bonus ☺️):

// Union let a hint of what's expected(?)
export type ImageFieldImage<State extends "empty" | "filled" = "empty" | "filled"> =
	State extends "empty"
		? EmptyImageFieldImage
		: FilledImageFieldImage;

Schrodinger's types 🤔

[angeloashmore]

Great idea! IsEmpty has been replaced by FieldState:

import * as prismicT from '@prismicio/types'

type MyField = prismicT.SelectField<"Option 1" | "Option 2", "empty">
// MyField === null

I'll add TSDocs for the new generic before considering this ready to merge.