feat: declare document TypeScript types in createClient()

[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 the ability to declare document types queryable by the client.

Client methods that accept an explicit document type, such as getByType() and getSingle(), can automatically return the appropriate document type. Furthermore, these methods are typed to only accept document type IDs that have been provided to the client.

import * as prismic from "@prismicio/client";
import * as prismicT from "@prismicio/types";

type PageDocument = prismicT.PrismicDocument<
  { foo: prismicT.KeyTextField },
  "page"
>;

type SettingsDocument = prismicT.PrismicDocument<
  { bar: prismicT.BooleanField },
  "settings"
>;

type AllDocumentTypes = PageDocument | SettingsDocument;

const client = prismic.createClient<AllDocumentTypes>("qwerty");
//    ^ Contains references to document types

const home = await client.getByUID("page", "home");
//    ^ Typed as PageDocument

home.data.foo;
//        ^ Typed as KeyTextField

const settings = await client.getSingle("settings");
//    ^ Typed as SettingsDocument

const foo = await client.getByType("foo");
// Type error - argument of type "foo" is not assignable to parameter of type "page" | "settings"

Methods that do not explicitly accept a document type return a union of all possible document types. Documents can be type narrowed at runtime by checking their type property.

const client = prismic.createClient<AllDocumentTypes>("qwerty");

const doc = await client.getFirst();
//    ^ Typed as PageDocument | SettingsDocument

Maintaining backwards compatibility

Query methods still accept a DocumentType type parameter to explicitly declare the returned document type. This is useful if types were not provided to createClient() or the document type passed to a query method is not a constant (i.e. typed as string).

Backwards compatibility is maintained compared to the previous TypeScript API.

const client = prismic.createClient("qwerty");

const homeWithoutType = await client.getByUID("page", "home");
//    ^ Typed as prismicT.PrismicDocument (i.e. a generic document)

const homeWithType = await client.getByUID<PageDocument>("page", "home");
//    ^ Typed as PageDocument

If types are provided to createClient(), explitly provided document types to a query method must be assignable to the client-level types.

type FooDocument = prismicT.PrismicDocument<
  { baz: prismicT.BooleanField },
  "foo"
>;

const client = prismic.createClient<PageDocument | SettingsDocument>("qwerty");

const foo = await client.getSingle<FooDocument>("settings");
// Type error - FooDocument is not assignable to PageDocument | SettingsDocument

Client type augmentation

This PR also adds the ability for createClient() type augmentation through a new CreateClient interface. This lets third-party packages, such as those generating types, to automatically link a literal repository name to a set of document types.

// prismic-client.d.ts
import * as prismic from "@prismicio/client";
import * as prismicT from "@prismicio/types";

type PageDocument = prismicT.PrismicDocument<
  { foo: prismicT.KeyTextField },
  "page"
>;

type SettingsDocument = prismicT.PrismicDocument<
  { bar: prismicT.Boolean },
  "settings"
>;

type AllDocumentTypes = PageDocument | SettingsDocument;

declare module "@prismicio/client" {
  interface CreateClient {
    (
      repositoryNameOrEndpoint: "qwerty",
      options?: prismic.ClientConfig | undefined
    ): prismic.Client<AllDocumentTypes>;
  }
}

With this module augmentation in place, createClient("qwerty") will automatically use AllDocumentTypes.

import * as prismic from "@prismicio/client";

const client = prismic.createClient("qwerty");
//    ^ Contains references to document types

const home = await client.getByUID("page", "home");
//    ^ Typed as PageDocument

home.data.foo;
//        ^ typed as KeyTextField

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 #238 (0759f1e) into master (f93af08) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master      #238   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           23        23           
  Lines          363       363           
  Branches        67        67           
=========================================
  Hits           363       363           

Impacted Files	Coverage Δ
src/index.ts	100.00% <ø> (ø)
src/client.ts	100.00% <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 f93af08...0759f1e. Read the comment docs.

[github-actions]

size-limit report 📦

Path	Size
dist/index.js	4.09 KB (-0.1% 🔽)
dist/index.cjs	6.98 KB (-0.02% 🔽)

[lihbr]

Nice job, looks good to me!

Maybe it's worth adding an example for the CreateClient extends? Up to you!

[lihbr]

Is there any value to allow extension of the whole createClient() function type?
As-in, can we make it so that you only need to extend the document type map?

[angeloashmore]

This is needed to pair a repository name literal to its document types. This allows this new system to support apps with multiple repositories, each with their own set of document types.

For example:

declare module "@prismicio/client" {
  interface CreateClient {
    (
      repositoryNameOrEndpoint: "foo",
      options?: prismic.ClientConfig | undefined
    ): prismic.Client<FooDocumentTypes>;
    (
      repositoryNameOrEndpoint: "bar",
      options?: prismic.ClientConfig | undefined
    ): prismic.Client<BarDocumentTypes>;
  }
}

While this is a rare situation, it ensure we are not locked into only supporting a single global config.

Since this code would typically be generated rather than hand-written, the extra boilerplate is okay, I think.

[lihbr]

OK, I was thinking it'll be something like that, great!

[lihbr]

From @chamois-d-or (Alexandre): Any consideration about graph queries?

[angeloashmore]

Thanks for the review! 🙂 (And the nice refactor to use Exclude over a map!)

Maybe it's worth adding an example for the CreateClient extends? Up to you!

Augmenting CreateClient is more of an internal API for now. I think we can omit a CreateClient example until we want or see a need for external tools to extend it.

I'll update the "With TypeScript" example to use this new API. Manual usage (i.e. without touching CreateClient) is now a bit simpler than before, and is more type-safe.

Maybe we should add another example for JSDoc.

[lihbr]

Perfect 👌

[angeloashmore]

Oops, I missed this question:

From @chamois-d-or (Alexandre): Any consideration about graph queries?

Automatically typing GraphQuery or FetchLinks is out of scope for this PR. This PR still allows developers to manually extend the return type like this:

import * as prismic from "./index";
import * as prismicT from "@prismicio/types";

type PageDocument = prismicT.PrismicDocument<
	{
		foo: prismicT.KeyTextField;
		parent: prismicT.LinkField;
	},
	"page"
>;

type AllDocumentTypes = PageDocument;

const client = prismic.createClient<AllDocumentTypes>("qwerty");

const graphQuery = `
{
	page {
		parent {
			...on page {
				title
			}
		}
	}
}
`.trim();

// Manually extend PageDocument to include the GraphQuery fields.
const home = (await client.getByUID("page", "home", {
	graphQuery,
})) as PageDocument & {
	data: {
		parent: {
			data: {
				title: prismicT.TitleField;
			};
		};
	};
};

The "page" parameter will still be type checked against PageDocument.

In the future, we could support an automatic GraphQuery/FetchLinks => TypeScript conversion that would simplify the above approach, but this is not planned currently:

const home = (await client.getByUID("page", "home", {
	graphQuery,
})) as PageDocument & PageParentGraphQuery;