The SDK

The StudioCMS SDK is a powerful tool that allows you to interact with StudioCMS programmatically. It provides a set of functions and utilities that allow you to manage and serve your content using Astro DB. It also provides the backbone for the StudioCMS Dashboard, and is built with Effect^.

Basic Usage

The StudioCMS SDK is available as a virtual module in your Astro project. You can import and utilize it using the following syntax:

import { 
const SDKCore: Effect.Effect<SDKCore, never, never>
The new Effect-TS based SDK implementation that replaces the deprecated SDK.
This unified SDK merges the normal and cached SDK functionalities.
@example 
import { Effect } from 'studiocms/effect';
import { SDKCore } from 'studiocms:sdk';

const db = Effect.gen(function* () {
  const sdk = yield* SDKCore;

  return sdk.db;
}).pipe(Effect.provide(SDKCore.Default));
SDKCore, 
const SDKCoreJs: {
    db: Database;
    dbService: AstroDB;
    getFullPath: (tree: FolderNode[], path: string[]) => Effect.Effect<string[], SDKCoreError, never>;
    findNodeByPath: (tree: FolderNode[], path: string[]) => Effect.Effect<FolderNode | null, SDKCoreError, never>;
    ... 32 more ...;
    CONFIG: SDKCore_CONFIG;
}
VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions
@example 
import { SDKCoreJs, runSDK } from 'studiocms:sdk';

const pages = await runSDK(SDKCoreJs.GET.pages());
SDKCoreJs, 
const runSDK: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
Utility function for running components of the SDKCoreJs
@example 
import { SDKCoreJs, runSDK } from 'studiocms:sdk';

const pages = await runSDK(SDKCoreJs.GET.pages());
runSDK } from 'studiocms:sdk';
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'studiocms/effect';


// Create the Usable Effect
const 
const pagesEffect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>
pagesEffect = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Effect.Effect<SDKCore, never, never>> | YieldWrap<Effect.Effect<PageDataCacheObject[], SDKCoreError, never>>, PageDataCacheObject[]>(f: (resume: Effect.Adapter) => Generator<YieldWrap<Effect.Effect<SDKCore, never, never>> | YieldWrap<Effect.Effect<PageDataCacheObject[], SDKCoreError, never>>, PageDataCacheObject[], never>) => Effect.Effect<...> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function* () {
  const 
const sdk: SDKCore
sdk = yield* 
const SDKCore: Effect.Effect<SDKCore, never, never>
The new Effect-TS based SDK implementation that replaces the deprecated SDK.
This unified SDK merges the normal and cached SDK functionalities.
@example 
import { Effect } from 'studiocms/effect';
import { SDKCore } from 'studiocms:sdk';

const db = Effect.gen(function* () {
  const sdk = yield* SDKCore;

  return sdk.db;
}).pipe(Effect.provide(SDKCore.Default));
SDKCore;

 // then do something with the SDK
 return yield* 
const sdk: SDKCore
sdk.
type GET: SDKCore_GET
GET.
pages: (includeDrafts?: boolean, hideDefaultIndex?: boolean, metaOnly?: false, paginate?: PaginateInput) => Effect.Effect<PageDataCacheObject[], SDKCoreError, never> (+1 overload)
pages()
});

// Convert the Effect into a JS/TS "program"
const 
const pagesResult1: PageDataCacheObject[]
pagesResult1 = await 
runSDK<PageDataCacheObject[], SDKCoreError>(effect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>): Promise<PageDataCacheObject[]>
Alias for runEffect, used to run SDK effects and convert them to plain JavaScript objects.
@param ― effect - The Effect to be converted.
@returns ― A promise that resolves to the plain JavaScript object representation of the effect's result.
runSDK(
const pagesEffect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>
pagesEffect);


// Just run the SDKCoreJS with the runSDK wrapper!
const 
const pagesResult2: PageDataCacheObject[]
pagesResult2 = await 
runSDK<PageDataCacheObject[], SDKCoreError>(effect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>): Promise<PageDataCacheObject[]>
Alias for runEffect, used to run SDK effects and convert them to plain JavaScript objects.
@param ― effect - The Effect to be converted.
@returns ― A promise that resolves to the plain JavaScript object representation of the effect's result.
runSDK(
const SDKCoreJs: {
    db: Database;
    dbService: AstroDB;
    getFullPath: (tree: FolderNode[], path: string[]) => Effect.Effect<string[], SDKCoreError, never>;
    findNodeByPath: (tree: FolderNode[], path: string[]) => Effect.Effect<FolderNode | null, SDKCoreError, never>;
    ... 32 more ...;
    CONFIG: SDKCore_CONFIG;
}
VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions
@example 
import { SDKCoreJs, runSDK } from 'studiocms:sdk';

const pages = await runSDK(SDKCoreJs.GET.pages());
SDKCoreJs.
type GET: SDKCore_GET
GET.
pages: (includeDrafts?: boolean, hideDefaultIndex?: boolean, metaOnly?: false, paginate?: PaginateInput) => Effect.Effect<PageDataCacheObject[], SDKCoreError, never> (+1 overload)
pages());

Available utils

The following is a list of the Primary utils provided by the StudioCMS SDK for interacting with the database.

import { 
const SDKCoreJs: {
    db: Database;
    dbService: AstroDB;
    getFullPath: (tree: FolderNode[], path: string[]) => Effect<string[], SDKCoreError, never>;
    findNodeByPath: (tree: FolderNode[], path: string[]) => Effect<FolderNode | null, SDKCoreError, never>;
    ... 32 more ...;
    CONFIG: SDKCore_CONFIG;
}
VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions
@example 
import { SDKCoreJs, runSDK } from 'studiocms:sdk';

const pages = await runSDK(SDKCoreJs.GET.pages());
SDKCoreJs } from 'studiocms:sdk';

const {
   
const db: Database
db,
   
const dbService: AstroDB
dbService,
   
const CLEAR: SDKCore_CLEAR
CLEAR,
   
const DELETE: SDKCore_DELETE
DELETE,
   
const INIT: SDKCore_INIT
INIT,
   
const AUTH: SDKCore_AUTH
AUTH,
   
const REST_API: SDKCore_REST_API
REST_API,
   
const GET: SDKCore_GET
GET,
   
const POST: SDKCore_POST
POST,
   
const UPDATE: SDKCore_UPDATE
UPDATE,
   
const PLUGINS: SDKCore_PLUGINS
PLUGINS,
   
const MIDDLEWARES: SDKCore_MIDDLEWARES
MIDDLEWARES,
} = 
const SDKCoreJs: {
    db: Database;
    dbService: AstroDB;
    getFullPath: (tree: FolderNode[], path: string[]) => Effect<string[], SDKCoreError, never>;
    findNodeByPath: (tree: FolderNode[], path: string[]) => Effect<FolderNode | null, SDKCoreError, never>;
    ... 32 more ...;
    CONFIG: SDKCore_CONFIG;
}
VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions
@example 
import { SDKCoreJs, runSDK } from 'studiocms:sdk';

const pages = await runSDK(SDKCoreJs.GET.pages());
SDKCoreJs;