Update resolveFields and query behaviour in the Items API

[JedWatson]

Followup to #5451 after further discussion

NOTE: This has been changed again, see comment below. Leaving this previous description for context.

I think this is even clearer, and the API now "does what it says"

You have two options:

(1) Query specific fields by passing the query option, as a string:

const [post] = await lists.Post.findMany({
  where: { slug },
  query: `
    title
    content
    image {
      src
      width
      height
    }`,
});

(2) Return the raw data stored in the database, by passing resolveFields: false

const [post] = await lists.Post.findMany({
  where: { slug },
  resolveFields: false,
});

For backwards compatibility the types and logic still accept a string value to resolveFields, I propose we leave it like that for now and narrow it to only accept false in a future release.

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/keystonejs/keystone-next-docs/6L3eE3JLrw1uV7NTUfa3qskqnqJV
✅ Preview: https://keystone-next-git-update-items-api-resolvefields-key-3269ee.vercel.app

[changeset-bot]

🦋 Changeset detected

Latest commit: b46c2bd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 18 packages

Name	Type
@keystone-next/api-tests-legacy	Patch
@keystone-next/example-ecommerce	Patch
@keystone-next/example-next-lite	Patch
@keystone-next/admin-ui	Patch
@keystone-next/auth	Major
@keystone-next/keystone	Minor
@keystone-next/types	Minor
@keystone-next/website	Patch
@keystone-next/server-side-graphql-client-legacy	Patch
@keystone-next/test-utils-legacy	Patch
@keystone-next/example-auth	Patch
@keystone-next/app-basic	Patch
keystone-next-app	Patch
@keystone-next/example-roles	Patch
@keystone-next/example-sandbox	Patch
@keystone-next/example-todo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[JedWatson]

Note I've updated the changeset from #5451 so the release notes are clearer, rather than adding a new one

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit b46c2bd:

Sandbox	Source
@keystone-next/example-sandbox	Configuration

[rohan-deshpande]

I like this. It makes the API a lot clearer.

[emmatown]

Just want to explicitly block this on further discussion

[JedWatson]

Another change after more discussion:

resolveFields has been deprecated entirely (again) in favour of a new API on context.db.lists.{List}

The updated changelog:

---

With the goal of making the Lists API (i.e context.lists.{List}) more intuitive to use, the resolveFields option has been deprecated in favor of two new methods:

(1) You can specify a string of fields to return with the new query option, when you want to query for resolved field values (including querying relationships and virtual fields). This replaces the resolveFields: false use case.

For example, to query a Post you would now write:

const [post] = await context.lists.Post.findMany({
  where: { slug },
  query: `
    title
    content
    image {
      src
      width
      height
    }`,
});

(2) Alternatively, there is a new set of APIs on context.db.lists.{List} which will return the unresolved item data from the database (but with read hooks applied), which can then be referenced directly or returned from a custom mutation or query in the GraphQL API to be handled by the Field resolvers. This replaces the resolveFields: boolean use case.

For example, to query for the raw data stored in the database, you would write:

const [post] = await context.db.lists.Post.findMany({
  where: { slug }
});

[timleslie]

👍 LGTM