docs: add missing types, prefer pnpm, fix various typos, discourage using payload from import (#9847)

- Adds missing types, especially the `Where` type. Will be helpful for
people to see that they can type their queries like that
- Mention pnpm first and prefer pnpm > npm > yarn throughout docs
- Add `payload` to function arguments in examples to discourage people
from doing `import payload from 'payload'`
- PNPM => pnpm, NPM => npm
- Fix some typos
This commit is contained in:
Alessio Gravili
2024-12-09 19:05:09 -07:00
committed by GitHub
parent 36c2714251
commit 254d888b73
18 changed files with 78 additions and 57 deletions

View File

@@ -43,7 +43,9 @@ But with a `depth` of `1`, the response might look like this:
To specify depth in the [Local API](../local-api/overview), you can use the `depth` option in your query:
```ts
const getPosts = async () => {
import type { Payload } from 'payload'
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
depth: 2, // highlight-line

View File

@@ -19,7 +19,9 @@ Each of these APIs share the same underlying querying language, and fully suppor
To query your Documents, you can send any number of [Operators](#operators) through your request:
```ts
const query = {
import type { Where } from 'payload'
const query: Where = {
color: {
equals: 'blue',
},
@@ -67,7 +69,9 @@ In addition to defining simple queries, you can join multiple queries together u
To join queries, use the `and` or `or` keys in your query object:
```ts
const query = {
import type { Where } from 'payload'
const query: Where = {
or: [ // highlight-line
{
color: {
@@ -99,7 +103,9 @@ Written in plain English, if the above query were passed to a `find` operation,
When working with nested properties, which can happen when using relational fields, it is possible to use the dot notation to access the nested property. For example, when working with a `Song` collection that has a `artists` field which is related to an `Artists` collection using the `name: 'artists'`. You can access a property within the collection `Artists` like so:
```js
const query = {
import type { Where } from 'payload'
const query: Where = {
'artists.featured': {
// nested property name to filter on
exists: true, // operator to use and boolean value that needs to be true
@@ -116,7 +122,9 @@ Writing queries in Payload is simple and consistent across all APIs, with only m
The [Local API](../local-api/overview) supports the `find` operation that accepts a raw query object:
```ts
const getPosts = async () => {
import type { Payload } from 'payload'
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
where: {
@@ -157,19 +165,20 @@ For this reason, we recommend to use the extremely helpful and ubiquitous [`qs-e
```ts
import { stringify } from 'qs-esm'
import type { Where } from 'payload'
const query = {
const query: Where = {
color: {
equals: 'mint',
},
// This query could be much more complex
// and QS would handle it beautifully
// and qs-esm would handle it beautifully
}
const getPosts = async () => {
const stringifiedQuery = stringify(
{
where: query, // ensure that `qs` adds the `where` property, too!
where: query, // ensure that `qs-esm` adds the `where` property, too!
},
{ addQueryPrefix: true },
)

View File

@@ -15,8 +15,10 @@ This is where Payload's `select` feature comes in. Here, you can define exactly
To specify `select` in the [Local API](../local-api/overview), you can use the `select` option in your query:
```ts
import type { Payload } from 'payload'
// Include mode
const getPosts = async () => {
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
select: {
@@ -34,7 +36,7 @@ const getPosts = async () => {
}
// Exclude mode
const getPosts = async () => {
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
// Select everything except for array and group.number
@@ -73,8 +75,9 @@ For this reason, we recommend to use the extremely helpful and ubiquitous [`qs-e
```ts
import { stringify } from 'qs-esm'
import type { Where } from 'payload'
const select = {
const select: Where = {
text: true,
group: {
number: true
@@ -116,9 +119,6 @@ Loading all of the page content, its related links, and everything else is going
```ts
import type { CollectionConfig } from 'payload'
import { lexicalEditor, LinkFeature } from '@payloadcms/richtext-lexical'
import { slateEditor } from '@payloadcms/richtext-slate'
// The TSlug generic can be passed to have type safety for `defaultPopulate`.
// If avoided, the `defaultPopulate` type resolves to `SelectType`.
export const Pages: CollectionConfig<'pages'> = {
@@ -144,7 +144,9 @@ Setting `defaultPopulate` will enforce that each time Payload performs a "popula
**Local API:**
```ts
const getPosts = async () => {
import type { Payload } from 'payload'
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
populate: {

View File

@@ -20,7 +20,9 @@ Because sorting is handled by the database, the field cannot be a [Virtual Field
To sort Documents in the [Local API](../local-api/overview), you can use the `sort` option in your query:
```ts
const getPosts = async () => {
import type { Payload } from 'payload'
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
sort: '-createdAt', // highlight-line
@@ -33,7 +35,9 @@ const getPosts = async () => {
To sort by multiple fields, you can use the `sort` option with fields in an array:
```ts
const getPosts = async () => {
import type { Payload } from 'payload'
const getPosts = async (payload: Payload) => {
const posts = await payload.find({
collection: 'posts',
sort: ['priority', '-createdAt'], // highlight-line