Pular para o conteúdo principal

@starlightcms/js-sdk

Index

API Entities

Client

Data Fields

Data Groups

Errors

StarlightError

Media Utilities

Instances

Request Parameters

Selectors

Type Aliases

Instances

Internal Types

Selectors

DynamicModelSelector

Utility Types

Visual Data Blocks

Client

DynamicStarlightClient

DynamicStarlightClient<T>: StarlightClient<T> & { [ K in keyof T ]: DynamicModelInstance<T[K]> }

This type adds support for the dynamic syntax to the StarlightClient interface, which allows users to create DynamicModelInstances dynamically. See StarlightClient to learn which methods it provides. Also see Dynamic Instances documentation to learn more about the dynamic syntax.

This allows TypeScript to correctly type all models defined by the user in the DefaultModelDefinition type, aside from letting the user using any “unknown” model slug, which is provided by the WorkspaceModelDefinition type.

This type is only aware of the DefaultModelDefinition type because the StarlightClient uses it by default when no model definition type is passed.

Type parameters

T: WorkspaceModelDefinition

StarlightConfig

StarlightConfig: { baseUrl?: BaseUrl; debug?: boolean; workspace?: string }

The available options to configure a StarlightClient.

workspace is required when creating new clients or configuring the default client.

Type declaration

optionalbaseUrl?: BaseUrl
The Starlight Query API URL, including the version, and without a trailing slash. Defaults to the production Query API URL.

You only need to set this if you’re not using Starlight’s production APIs.
optionaldebug?: boolean
When true, logs all API requests in the console. Defaults to false.
optionalworkspace?: string
The ID of the workspace that the client should use to request data.

Note: the current APIs only support using workspace IDs as identifiers, and not slugs. Slug support will be added in the future. You can find the workspace ID in the left-side menu on the Starlight interface or below the workspace name in the workspace list.

constdefault

default: DynamicStarlightClient<DefaultModelDefinition & WorkspaceModelDefinition> = ...

This is the default object exported by the SDK module, which is a pre-created StarlightClient. In the docs, this is called the “global SDK client”. If your application only requests data from a single Starlight workspace, using this client is easier than creating a new one using makeStarlightClient.

Using the default client is as easy as importing the SDK:

// "Starlight" below is the default client.
import Starlight from '@starlightcms/js-sdk'

const response = await Starlight.posts.entries.list()

You need to configure the default workspace before using it. See StarlightClient.configure to learn more.

Data Fields

BooleanField

BooleanField: boolean | undefined

Represents a Boolean Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

DecimalField

DecimalField: number | undefined

Represents a Decimal Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

FloatField

FloatField: number | undefined

Represents a Float Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

HtmlField

HtmlField: string | undefined

Represents an HTML Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

IntegerField

IntegerField: number | undefined

Represents an Integer Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

MediaField

MediaField: MediaObject | undefined

Represents a Media Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

RelationField

RelationField<T>: Relation<T> | undefined

Represents a Relation Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Type parameters

T

SelectField

SelectField<Options>: (Options[multiple] extends false ? string : string | string[]) | undefined

Represents a Select Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Type parameters

Options: SelectFieldOptions = { multiple: false }

StringField

StringField: string | undefined

Represents a String Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

TextField

TextField: string | undefined

Represents a Text Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

VisualField

VisualField: VisualData | undefined

Represents a Visual Field returned by the API.

Field types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Data Groups

Group

Group<Fields>: { [ Property in keyof Fields ]: Fields[Property] } | undefined

Represents a Group returned by the API.

Group types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Type parameters

Fields: Record<string, unknown>

RepeaterGroup

RepeaterGroup<Fields>: { [ Property in keyof Fields ]: Fields[Property] }[] | null | undefined

Represents a Repeater Group returned by the API.

Note that the API return empty repeaters as null.

To retrieve the type of a RepeaterGroup item, use the RepeaterItem utility type.

Group types are used to type Entry and Singleton objects when requesting them using some SDK methods. See DefaultModelDefinition for more info.

Type parameters

Fields: Record<string, unknown>

Other

BaseUrl

BaseUrl: https://query.starlightcms.io/v2 | string

This is a utility type that allows any string to be used as a URL, but provides a default one which can be used by IDEs to provide auto-completion. The default URL points to version 2 of the Query API.

SelectFieldOptions

SelectFieldOptions: { multiple?: boolean }

Type declaration

optionalmultiple?: boolean
Indicates if the Select Field accepts multiple selected choices.

Instances

DynamicCollectionSelector

DynamicCollectionSelector: CollectionSelector & {}

A Selector that provide all CollectionSelector methods and adds support for creating CollectionInstances using the dynamic syntax.

See CollectionSelector to view all available methods.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a CollectionInstance using the dynamic syntax.

import Starlight from '@starlightcms/js-sdk'

// "sliders" below will be a CollectionInstance.
const response = await Starlight.collections.sliders.list()

DynamicModelCategorySelector

DynamicModelCategorySelector<D>: ModelCategorySelector & {}

A Selector that provide all ModelCategorySelector methods and adds support for creating ModelCategoryInstances using the dynamic syntax.

See ModelCategorySelector to view all available methods. You can use a DynamicModelCategorySelector by accessing ModelInstance.categories.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a ModelCategorySelector using the dynamic syntax on a model of slug “posts”

import Starlight from '@starlightcms/js-sdk'

// "articles" below will be a ModelCategorySelector.
const response = await Starlight.posts.categories.articles.list()

Type parameters

D: SerializedData

DynamicModelInstance

DynamicModelInstance<D>: ModelInstance<D> & {}

An Instance that provide all ModelInstance methods and adds support for creating ModelCategoryInstances using the dynamic syntax.

See ModelInstance to view all available methods.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a ModelCategoryInstance using the dynamic syntax.

import Starlight from '@starlightcms/js-sdk'

// "articles" below will be a ModelCategoryInstance.
const response = await Starlight.posts.articles.list()

Type parameters

D: SerializedData

Internal Types

QueryableFields

QueryableFields<D>: { [ K in keyof D as `field:${string & K}` ]?: string | boolean }

Utility type that creates a string map of all fields of the given SerializedData type with the field: prefix. This syntax allows to filter specific fields when listing Entries:

Text fields can be filtered by a string query. This works just like passing a query parameter, but it only applies to one field.
Boolean fields can be filtered by “true” or “false”.

If a request uses this type, it means that this syntax can be used in their parameters:

import Starlight from '@starlightcms/js-sdk'

const response = await Starlight.posts.entries.list({
  // EntrySelector.list() supports the "field:foo" syntax:
  'field:content': 'hello world',
  'field:is_featured': true,

  // EntrySelector.list() also support other parameters,
  // which are passed in this object too:
  page: 42,
  limit: 20,
})

@remark

The information below is only useful for SDK maintainers.

This type receives a SerializedData-like structure, like an object. For instance, for an Entry with fields “content” and “summary”, the generated type would look like this:

type GeneratedType = {
  'field:content'?: string
  'field:summary'?: string
}

However, note that QueryableFields receive a SerializedData, not an Entry:

import { VisualField, StringField } from '@starlightcms/js-sdk'

type EntryFields = {
  content: VisualField
  summary: StringField
}

type MyEntry = Entry<EntryFields>

// Error TS2344: Type does not satisfy the constraint 'SerializedData'
type GeneratedType = QueryableFields<MyEntry>

// Works!
type GeneratedType = QueryableFields<EntryFields>

This type is only useful to request methods that support field querying using the “field:foo” syntax.

Type parameters

D: SerializedData

SerializedData

SerializedData: Record<string, unknown> | undefined

Represents content data returned by either an Entry or Singleton entity from the API.

This is a utility type used internally by the SDK and you don’t need to use it. Its purpose is to constraint Entry and Singleton data to the shape of a JS object.

WithQueryableFieldsOnModelables

WithQueryableFieldsOnModelables<T>: T extends Entry<never> | Singleton<never> ? QueryableFields<T[data]> : never

Utility type that return QueryableFields if the given type T is an Entry or a Singleton, but generates an empty object otherwise.

Fun fact: internally, Entries and Singletons have parent Models, which is why they are called “modelables” here.

Type parameters

T

Selectors

DynamicModelSelector

DynamicModelSelector<T>: ModelSelector & { [ K in keyof T ]: DynamicModelInstance<T[K]> }

A Selector that provide all ModelSelector methods and adds support for creating DynamicModelInstances using the dynamic syntax.

See ModelSelector to view all available methods.

See Dynamic Instances documentation to learn more about the dynamic syntax.

@example

Accessing a DynamicModelInstance using the dynamic syntax.

import Starlight from '@starlightcms/js-sdk'

// "posts" below will be a DynamicModelInstance.
const response = await Starlight.models.posts.entries.list()

Type parameters

T: WorkspaceModelDefinition

Utility Types

GetFromStructure

GetFromStructure<Structure, Path>: Get<Structure, Path>

Returns the type of the group or field in the given structure at the specified path. Use dot notation . to access items inside groups and bracket notation [] to access items inside repeaters.

Syntax example:

foo
foo.bar
foo.bar[0].baz
foo.bar[0].baz.quo

This utility is useful to get the type of a deeply nested group or field inside a Model, Singleton or Form structure.

@example

Retrieving the type of a deeply nested group or field.

import { Group, StringField, GetFromStructure } from '@starlightcms/js-sdk'

type ComplexModel = {
  info: Group<{
    title: StringField
    meta: Group<{
      keywords: StringField
      tags: RepeaterGroup<{
        name: StringField
      }>
    }>
  }>
}

type MetaGroupType = GetFromStructure<ComplexModel, 'info.meta'>
// Resulting type -> Group<{ keywords: StringField, tags: RepeaterGroup<{ name: StringField }> }>

type KeywordsFieldType = GetFromStructure<ComplexModel, 'info.meta.keywords'>
// Resulting type -> StringField

type TagNameFieldType = GetFromStructure<ComplexModel, 'info.meta.tags[0].name'>
// Resulting type -> StringField

Type parameters

Structure
Path: Paths<Structure, { bracketNotation: true; maxRecursionDepth: 4 }>

GetRepeaterItem

GetRepeaterItem<Repeater>: Repeater extends readonly infer ItemType[] ? ItemType : never

Returns the item type of the given Repeater Group.

This utility is useful to get the type of the content held in items of a specific Repeater Group.

@example

Retrieving the type of a repeater item.

import {
 RepeaterGroup,
 MediaField,
 StringField,
 GetRepeaterItem,
 GetFromStructure
} from '@starlightcms/js-sdk'

type SlideshowModel = {
  slides: RepeaterGroup<{
    image: MediaField
    description: StringField
  }>
}

type Slide = GetRepeaterItem<SlideshowModel['slides']>
// Resulting type -> { image: MediaField, description: StringField }

// Also works with the GetFromStructure utility
type Slide = GetRepeaterItem<GetFromStructure<SlideshowModel, 'slides'>>
// Resulting type -> { image: MediaField, description: StringField }

Type parameters

Repeater: RepeaterGroup<Record<string, unknown>>

Visual Data Blocks

HTMLBlock

HTMLBlock: StretchableBlock<BaseHTMLBlock>

Represents an HTML block, which is used to render custom HTML code. Mainly used to place embeds or heavily customized content structures.

HeaderBlock

HeaderBlock: StretchableBlock<AlignableBlock<BaseHeaderBlock>>

Represents a Header block, which is used to render h1 through h6 HTML elements.

ImageBlock

ImageBlock: StretchableBlock<AlignableBlock<BaseImageBlock>>

Represents an Image block, which is used to render img or picture HTML elements.

ListBlock

ListBlock: StretchableBlock<BaseListBlock>

Represents a List block, which is used to render ol or ul HTML elements.

ParagraphBlock

ParagraphBlock: StretchableBlock<AlignableBlock<BaseParagraphBlock>>

Represents a Paragraph block, which is the default block type used for text content in the Visual Editor.

VideoBlock

VideoBlock: StretchableBlock<AlignableBlock<BaseVideoBlock>>

Represents a Video block, which is used to render embed video elements.