Database contract

What a database adapter implements, as @genoacms/contracts/database declares it. How an adapter is shaped and registered is under adapters ; how a config declares collections is under services .

A collection's schema and primaryKey.schema are JsonSchema: a JSON Schema object, typed structurally. The contract carries schemas and never validates them; GenoaCMS validates documents against them itself.

Types

/**
 * A JSON Schema object. The contract carries schemas and never validates them, so it names the
 * keywords code reads and admits every other.
 */
interface JsonSchema {
  type?: string | string[]
  properties?: Record<string, JsonSchema>
  [keyword: string]: unknown
}

interface CollectionReference {
  name: string
  primaryKey: {
    key: string,
    schema: JsonSchema
  },
  schema: JsonSchema
  uiSchema?: CollectionUiSchema
}
/** How the CMS shows each field, keyed by field name. Adapters ignore it. */
type CollectionUiSchema = Record<string, { showPreview?: boolean }>
interface DocumentReference<C extends CollectionReference> {
  collection: C
  id: string
}
type Comparable = string | number | boolean | null
interface Condition {
  field: string
  operator: '==' | '!=' | '<' | '<=' | '>' | '>='
  value: Comparable
}
interface QueryParams {
  where?: Condition[]
  limit?: number
  pageToken?: string
}
type Document<C extends CollectionReference = CollectionReference> = Record<keyof C['schema'], C['schema'][keyof C['schema']]>
interface DocumentSnapshot<C extends CollectionReference> {
  reference: DocumentReference<C>
  data: Document<C>
}
interface UpdateSnapshot<C extends CollectionReference> extends Omit<DocumentSnapshot<C>, 'data'> {
  data: Partial<Document<C>>
}
interface CollectionPage<C extends CollectionReference> {
  documents: Array<DocumentSnapshot<C>>
  next?: string
}

export type {
  JsonSchema,
  CollectionReference,
  CollectionUiSchema,
  DocumentReference,
  Comparable,
  Condition,
  QueryParams,
  Document,
  DocumentSnapshot,
  UpdateSnapshot,
  CollectionPage
}
ts
Expand code

Adapter

import type { CollectionReference, DocumentReference, DocumentSnapshot, CollectionPage, QueryParams, Document, UpdateSnapshot } from './types.d.ts'

type createDocument = <C extends CollectionReference>(reference: C, document: Document<C>) => Promise<DocumentSnapshot<C>>

type getCollection = <C extends CollectionReference>(reference: C, queryParams?: QueryParams) => Promise<CollectionPage<C>>
type getDocument = <C extends CollectionReference, D extends DocumentReference<C>>(reference: D) => Promise<DocumentSnapshot<C> | undefined>

type updateDocument = <C extends CollectionReference, D extends DocumentReference<C>>(reference: D, document: Document<C>) => Promise<UpdateSnapshot<C>>

type deleteDocument = <C extends CollectionReference, D extends DocumentReference<C>>(reference: D) => Promise<void>

interface Adapter {
  createDocument: createDocument

  getCollection: getCollection
  getDocument: getDocument

  updateDocument: updateDocument

  deleteDocument: deleteDocument
}

export default Adapter
ts

create receives the databases bound to the provider as ctx.resources.

Custom schemas

@genoacms/contracts/schemas exports fields that point outside a document:

/** JSON Schema fragments for collection fields. Plain objects: they serialize into the manifest. */
declare const storageResource: Record<string, unknown>
declare const nullableStorageResource: Record<string, unknown>
declare function globalReference (options: { type?: string, format?: string }): Record<string, unknown>
declare function reference (options: { type?: string, format?: string, collection: string }): Record<string, unknown>

export { storageResource, nullableStorageResource, globalReference, reference }
ts