Singletons

[emmatown]

Adds a new singleton list function for configuring lists as singletons.
update: See #7941, we now prefer isSingleton: true, not a function

See below for an example of configuring a singleton:

import { list, singleton } from '@keystone-6/core';
import { allowAll } from '@keystone-6/core/access';
import { relationship, text } from '@keystone-6/core/fields';

 const lists = {
  Settings: singleton({
    access: allowAll,
    fields: {
      websiteName: text(),
      copyrightText: text(),
      highlightedPosts: relationship({ ref: 'Post', many: true }),
    },
  }),
  Post: list({
    access: allowAll,
    fields: {
      title: text({ validation: { isRequired: true } }),
      content: text(),
    },
  }),
  ...
};

Setting this flag does a few things:

In Graphql

Graphql queries for singletons are all the same as those for lists, however with two major differences:

• Graphql will error if you ever make a query that doesn't have the where: { id: '1' }, you will get an error - you can only read, create, update, or delete an item with an ID of 1 in singleton.
• Upside, we are defaulting the where query for singletons, meaning you can simply not provide it, so you don't need to think about the above

So for example, the query for the above singleton would be:

query {
  settings {
    copyrightText
  }
}

NB: This is a query for a single settings

In the admin UI

• Singletons do not display a count or an add button.
• Clicking on a singleton's dashboard card or dashboard nav link will take you to the single singleton item
• If the singleton doesn't exist when you visit its page, you get a create button, and a message {ThisSingleton} doesn't exist or you don't have access to it.

In Keystone

• You cannot have a relationship to a singleton. This is done because, since there is only ever one, there's very little reason to ever have a relationship to a singleton, and allowing it added some edge-cases that were easier just to simply not to support

DX Design Notes

If the plural of a singleton is ambiguous, singleton lists default to the plural Many${ListName}.
This should typically be unambiguous.

We have retained the many query support for singletons to maximize compatibility and keep support for generic functions across lists that may or may not be singletons.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
keystone-next-docs	❌ Failed (Inspect)		Sep 7, 2022 at 5:47AM (UTC)

[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 7050783:

Sandbox	Source
@keystone-6/sandbox	Configuration