-
-
Notifications
You must be signed in to change notification settings - Fork 7.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Contributor Doc] Type System CheatSheet #20168
Merged
Merged
Changes from 33 commits
Commits
Show all changes
34 commits
Select commit
Hold shift + click to select a range
834406f
docs: add comments to the type-system types for clarity
Convly fb008ec
Merge branch 'v5/tsdoc/ts-doc-as-markdown' into v5/tsdoc/init-doc-mai…
Convly 469f319
refactor: update import statements and usage in schema.ts
Convly 35470f7
Merge remote-tracking branch 'origin/v5/tsdoc/init-doc-main-types' in…
Convly 31082b8
docs: add new contributor guide for the type system and its philosophy
Convly 2de49c3
docs: add documentation for type system concepts
Convly 0ae41a4
Merge branch 'v5/main' of github.com:strapi/strapi into v5/tsdoc/conc…
Convly 13297ea
docs: update docs/docs/guides/05-type-system/02-concepts/01-schema.mdx
Convly 40fa359
docs: update docs/docs/guides/05-type-system/02-concepts/01-schema.mdx
Convly 3a8070c
docs: update docs/docs/guides/05-type-system/02-concepts/01-schema.mdx
Convly 8718369
docs: update docs/docs/guides/05-type-system/02-concepts/02-uid.mdx
Convly d08de91
docs: update docs/docs/guides/05-type-system/02-concepts/02-uid.mdx
Convly 08db027
docs: update docs/docs/guides/05-type-system/02-concepts/02-uid.mdx
Convly 4b92680
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly 84dc625
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly 467689c
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly 8e1a4e2
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly 7709fae
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly c7d9de3
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly 748fd44
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly c7a21d3
docs: update docs/docs/guides/05-type-system/02-concepts/02-uid.mdx
Convly 0888a0e
docs: update docs/docs/guides/05-type-system/02-concepts/02-uid.mdx
Convly 17ff41e
docs: update docs/docs/guides/05-type-system/02-concepts/01-schema.mdx
Convly 77b4cdd
docs: update docs/docs/guides/05-type-system/02-concepts/01-schema.mdx
Convly f07976e
docs: update docs/docs/guides/05-type-system/02-concepts/03-public-re…
Convly e9cae72
docs: clarify distinction between database models and raw schema defi…
Convly 0e918fd
Merge branch 'v5/tsdoc/concepts' of github.com:strapi/strapi into v5/…
Convly 5a1a695
Merge branch 'v5/main' of github.com:strapi/strapi into v5/tsdoc/conc…
Convly 36d744c
docs: add TypeScript cheat sheet guide in type system section
Convly 373d957
Merge branch 'v5/main' of github.com:strapi/strapi into v5/tsdoc/chea…
Convly aae4c5e
docs: update docs/docs/guides/05-type-system/03-cheatsheet.mdx
Convly d3e7b8c
docs: update docs/docs/guides/05-type-system/02-concepts/02-uid.mdx
Convly adf419a
Merge branch 'v5/main' into v5/tsdoc/cheatsheet
Convly 520b0a3
chore: fix linting
innerdvations File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,255 @@ | ||
--- | ||
title: CheatSheet | ||
tags: | ||
- typescript | ||
- type system | ||
- type | ||
- cheatsheet | ||
toc_max_heading_level: 3 | ||
--- | ||
|
||
import Tabs from '@theme/Tabs' | ||
import TabItem from '@theme/TabItem' | ||
import Admonition from '@theme/Admonition' | ||
|
||
### Common Use Cases | ||
|
||
--- | ||
|
||
#### Function that Returns Any Entity | ||
|
||
```typescript | ||
import type { Data } from '@strapi/types'; | ||
|
||
function find(): Data.Entity {} | ||
``` | ||
|
||
--- | ||
|
||
#### Using UIDs as Resource Selectors in Function Params | ||
|
||
<Tabs> | ||
|
||
<TabItem value='dynamic' label='Dynamic'> | ||
|
||
:::info | ||
Infer the UID type based on usage and allow passing it to other generic types. | ||
::: | ||
|
||
```typescript | ||
import type { Schema, UID } from '@strapi/types'; | ||
|
||
function getSchema<TSchemaUID extends UID.Schema>( | ||
uid: TSchemaUID | ||
): Schema.Schema<TSchemaUID> {} | ||
``` | ||
|
||
</TabItem> | ||
|
||
<TabItem value='static' label='Static'> | ||
|
||
:::info | ||
Simpler definition than the dynamic one. | ||
Useful when the uid type doesn't need to be re-used by other type. | ||
::: | ||
|
||
```typescript | ||
import type { Schema, UID } from '@strapi/types'; | ||
|
||
function getSchema(uid: UID.Schema): Schema.Schema {} | ||
``` | ||
|
||
</TabItem> | ||
|
||
</Tabs> | ||
|
||
|
||
--- | ||
|
||
#### Loop Over Schema Attributes | ||
|
||
Given a schema such as: | ||
|
||
```typescript | ||
import type { Schema } from '@strapi/types'; | ||
|
||
declare const schema: Schema.Schema; | ||
``` | ||
|
||
Extract its attributes | ||
|
||
```typescript | ||
const { attributes } = schema; | ||
``` | ||
|
||
Then loop over them, using `attribute.type` as a discriminator to infer the correct type for each attribute type. | ||
|
||
```typescript | ||
for (const attributeName in attributes) { | ||
// attribute is Schema.Attribute.AnyAttribute | ||
const attribute = attributes[attributeName]; | ||
|
||
switch (attribute.type) { | ||
case 'string': | ||
// attribute is Schema.Attribute.String | ||
console.log(attribute.minLength, attribute.maxLength); | ||
break; | ||
case 'relation': | ||
// attribute is Schema.Attribute.Relation | ||
console.log(attribute.relation); | ||
break; | ||
} | ||
} | ||
``` | ||
|
||
--- | ||
|
||
#### Type Guard | ||
|
||
```typescript | ||
import type { Schema } from '@strapi/types'; | ||
|
||
function isContentTypeSchema(schema: Schema.Schema): schema is Schema.ContentType { | ||
return schema.modelType === 'contentType'; | ||
} | ||
``` | ||
|
||
--- | ||
|
||
#### Assertion Function | ||
|
||
```typescript | ||
import type { Schema } from '@strapi/types'; | ||
|
||
function assertIsContentTypeSchema(schema: Schema.Schema): asserts schema is Schema.ContentType { | ||
if (schema.modelType !== 'contentType') { | ||
throw new Error('schema is not a content-type') | ||
} | ||
} | ||
``` | ||
|
||
--- | ||
|
||
### Data | ||
|
||
```typescript | ||
import type { Data } from '@strapi/types'; | ||
``` | ||
|
||
<Tabs> | ||
<TabItem value="entity" label="Data.Entity"> | ||
#### Represent any entity | ||
|
||
```typescript | ||
type Entity = Data.Entity; | ||
``` | ||
|
||
#### Represent a specific content-type entity | ||
|
||
```typescript | ||
type Article = Data.Entity<'api::article.article'>; | ||
``` | ||
|
||
#### Represent a specific component entity | ||
|
||
```typescript | ||
type Metadata = Data.Entity<'seo.metadata'>; | ||
``` | ||
|
||
#### Represent any content-type | ||
|
||
```typescript | ||
type Entity = Data.Entity<UID.ContentType>; | ||
``` | ||
|
||
#### Only select a subset of an entity | ||
|
||
```typescript | ||
type PartialArticle = Data.Entity<'api::article.article', 'title' | 'description' | 'author'>; | ||
``` | ||
</TabItem> | ||
<TabItem value="contenttype" label="Data.ContentType"> | ||
#### Represent any content-type entity | ||
|
||
```typescript | ||
type ContentTypeEntity = Data.ContentType; | ||
``` | ||
|
||
#### Represent a specific content-type entity | ||
|
||
```typescript | ||
type Article = Data.ContentType<'api::article.article'>; | ||
``` | ||
|
||
#### Only select a subset of a content-type entity | ||
|
||
```typescript | ||
type PartialArticle = Data.ContentType<'api::article.article', 'title' | 'description' | 'author'>; | ||
``` | ||
|
||
</TabItem> | ||
<TabItem value="component" label="Data.Component"> | ||
#### Represent any component entity | ||
|
||
```typescript | ||
type ComponentEntity = Data.Component; | ||
``` | ||
|
||
#### Represent a specific component entity | ||
|
||
```typescript | ||
type Metadata = Data.Component<'seo.metadata'>; | ||
``` | ||
|
||
#### Only select a subset of a component entity | ||
|
||
```typescript | ||
type PartialMetadata = Data.Component<'seo.metadata', 'description' | 'tags'>; | ||
``` | ||
</TabItem> | ||
</Tabs> | ||
|
||
--- | ||
|
||
### UID | ||
|
||
```typescript | ||
import type { UID } from '@strapi/types'; | ||
``` | ||
|
||
#### Represent any schema UID | ||
|
||
```typescript | ||
type SchemaUID = UID.Schema; | ||
``` | ||
|
||
#### Represent a specific content-type UID | ||
|
||
```typescript | ||
const articleUID = 'api::article.article' satisfies UID.ContentType; | ||
``` | ||
|
||
#### Represent a specific component entity | ||
|
||
```typescript | ||
const metadataUID = 'seo.metadata' satisfies UID.Component; | ||
``` | ||
|
||
#### Represent any content-type | ||
|
||
```typescript | ||
type ContentTypeUID = UID.ContentType; | ||
``` | ||
|
||
```typescript | ||
declare const contentTypeUID: UID.ContentType; | ||
``` | ||
|
||
#### Check if a given UID is a ContentType UID | ||
```typescript | ||
type IsContentType = UID.IsContentType<'api::article.article'>; | ||
``` | ||
|
||
:::note | ||
`IsContentType` will either be `true` or `false`. | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you give a code example with a return to see when this might be used?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure I understand completely what you're referring too? Do you want an actual body definition for the function?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, like a use case showing what you would select in order to want to return a generic Data.Entity. Not important though, just a thought.