[RFC] Rename context.lists to context.query and `context.db.lists…

…` to `context.db` (#6535)

.changeset/large-pugs-exist.md

@@ -0,0 +1,8 @@
+---
+'@keystone-next/auth': major
+'@keystone-next/keystone': major
+---
+
+The API `context.lists` has been renamed to `context.query`, and `context.db.lists` has been renamed to `context.db`.
+
+When using the experimental option `config.experimental.generateNodeAPI`, the `api` module now exports `query` rather than `lists`.

.changeset/popular-goats-juggle.md

@@ -2,4 +2,4 @@
 '@keystone-next/keystone': patch
 ---
 
-Fixed a bug in `context.db.lists` API when finding items that don't exist.
+Fixed a bug in `context.db` API when finding items that don't exist.

docs/components/docs/Navigation.tsx

@@ -192,8 +192,8 @@ export function DocsNavigation() {
 
         <SubHeading>Context</SubHeading>
         <NavItem href="/docs/apis/context">Context API</NavItem>
-        <NavItem href="/docs/apis/list-items">List Item API</NavItem>
-        <NavItem href="/docs/apis/db-items">DB Item API</NavItem>
+        <NavItem href="/docs/apis/query">Query API</NavItem>
+        <NavItem href="/docs/apis/db-items">DB API</NavItem>
 
         <SubHeading>GraphQL</SubHeading>
         <NavItem href="/docs/apis/graphql">

docs/pages/docs/apis/context.mdx

@@ -67,13 +67,13 @@ context = {
 
 `req`: The [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) object from the HTTP request which called the GraphQL API.
 
-### List item API
+### Query API
 
-`lists`: The [list items API](./list-items), which can be used to perform CRUD operations against your GraphQL API.
+`query`: The [Query API](./query), which can be used to perform CRUD operations against your GraphQL API and return a queried value.
 
-### Database item API
+### Database API
 
-`db.lists`: The [database items API](./db-items), which can be used to retrieve objects suitable for return from mutations in [schema extensions](../guides/schema-extension).
+`db`: The [Database API](./db-items), which can be used to perform CRUD operations against your GraphQL API and return database objects suitable for return from mutations in [schema extensions](../guides/schema-extension).
 
 ### GraphQL helpers
 
@@ -107,7 +107,7 @@ See the [session API](./session#session-context) for more details.
 
 ### New context creators
 
-When using the `context.lists`, `context.graphql.run`, and `context.graphql.raw` APIs, access control and session information is passed through to these calls from the `context` object.
+When using the `context.query`, `context.graphql.run`, and `context.graphql.raw` APIs, access control and session information is passed through to these calls from the `context` object.
 The following functions will create a new `KeystoneContext` object with this behaviour modified.
 
 `sudo()`: A function which returns a new `KeystoneContext` object with all access control disabled and all filters enabled for subsequent API calls.
@@ -165,13 +165,13 @@ They will be removed in future releases.
 
 <RelatedContent>
   <Well
-    heading="List Items API Reference"
-    href="/docs/apis/list-items"
+    heading="Query API Reference"
+    href="/docs/apis/query"
     >
-    A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.lists.&lt;listName&gt;</InlineCode>
+    A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.query.&lt;listName&gt;</InlineCode>
   </Well>
   <Well
-    heading="DB Items API Reference"
+    heading="DB API Reference"
     href="/docs/apis/db-items"
     >
     The API for running CRUD operations against the internal GraphQL resolvers in your system. It returns internal item objects, which can be returned from GraphQL resolvers.

docs/pages/docs/apis/db-items.mdx

@@ -3,9 +3,9 @@ import { Well } from '../../../components/primitives/Well';
 import { RelatedContent } from '../../../components/RelatedContent';
 import { InlineCode } from '../../../components/primitives/Code';
 
-# Database Items API
+# Database API
 
-The database items API provides a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system.
+The database API provides a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system.
 Importantly, this API bypasses the GraphQL Server itself, instead invoking the resolver functions directly.
 The return values of this API are **internal item** objects, which are suitable to be returned from GraphQL resolvers.
 
@@ -14,7 +14,7 @@ Refer to the [internal items guide](../guides/internal-items) for details on how
 This API executes the [`access control`](../guides/access-control) rules and [`hooks`](../guides/hooks) defined in your system.
 To bypass these, you can directly use the Prisma Client at [`context.prisma`](./context#database-access).
 
-For each list in your system the following API is available at `context.db.lists.<listName>`.
+For each list in your system the following API is available at `context.db.<listName>`.
 
 ```
 {
@@ -36,7 +36,7 @@ Unless otherwise specified, the arguments to all functions are required.
 ### findOne
 
 ```typescript
-const user = await context.db.lists.User.findOne({
+const user = await context.db.User.findOne({
   where: { id: '...' },
 });
 ```
@@ -46,7 +46,7 @@ const user = await context.db.lists.User.findOne({
 All arguments are optional.
 
 ```typescript
-const users = await context.db.lists.User.findMany({
+const users = await context.db.User.findMany({
   where: { name: { startsWith: 'A' } },
   take: 10,
   skip: 20,
@@ -59,15 +59,15 @@ const users = await context.db.lists.User.findMany({
 All arguments are optional.
 
 ```typescript
-const count = await context.db.lists.User.count({
+const count = await context.db.User.count({
   where: { name: { startsWith: 'A' } },
 });
 ```
 
 ### createOne
 
 ```typescript
-const user = await context.db.lists.User.createOne({
+const user = await context.db.User.createOne({
   data: {
     name: 'Alice',
     posts: { create: [{ title: 'My first post' }] },
@@ -78,7 +78,7 @@ const user = await context.db.lists.User.createOne({
 ### createMany
 
 ```typescript
-const users = await context.db.lists.User.createMany({
+const users = await context.db.User.createMany({
   data: [
     {
       name: 'Alice',
@@ -95,7 +95,7 @@ const users = await context.db.lists.User.createMany({
 ### updateOne
 
 ```typescript
-const user = await context.db.lists.User.updateOne({
+const user = await context.db.User.updateOne({
   where: { id: '...' },
   data: {
     name: 'Alice',
@@ -107,7 +107,7 @@ const user = await context.db.lists.User.updateOne({
 ### updateMany
 
 ```typescript
-const users = await context.db.lists.User.updateMany({
+const users = await context.db.User.updateMany({
   data: [
     {
       where: { id: '...' },
@@ -130,15 +130,15 @@ const users = await context.db.lists.User.updateMany({
 ### deleteOne
 
 ```typescript
-const user = await context.db.lists.User.deleteOne({
+const user = await context.db.User.deleteOne({
   where: { id: '...' },
 });
 ```
 
 ### deleteMany
 
 ```typescript
-const users = await context.db.lists.User.deleteMany({
+const users = await context.db.User.deleteMany({
   where: [{ id: '...' }, { id: '...' }],
 });
 ```
@@ -147,10 +147,10 @@ const users = await context.db.lists.User.deleteMany({
 
 <RelatedContent>
   <Well
-    heading="List Items API Reference"
-    href="/docs/apis/list-items"
+    heading="Query API Reference"
+    href="/docs/apis/query"
     >
-    A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.lists.&lt;listName&gt;</InlineCode>.
+    A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.query.&lt;listName&gt;</InlineCode>.
   </Well>
   <Well
     heading="Context API Reference"
@@ -160,4 +160,4 @@ const users = await context.db.lists.User.deleteMany({
   </Well>
 </RelatedContent>
 
-export default ({ children }) => <Markdown description="Keystone’s database items API is a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system. It bypasses the GraphQL Server itself, invoking resolver functions directly.">{children}</Markdown>;
+export default ({ children }) => <Markdown description="Keystone’s database API is a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system. It bypasses the GraphQL Server itself, invoking resolver functions directly.">{children}</Markdown>;