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
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