Skip to main content

TypeScript Types

Full reference of exported types from @sajjadbzn/jcell.

Core Types​

DBConfig​

interface DBConfig {
  adapter: StorageAdapter
}

Document​

type Document = Record<string, unknown>

DocWithId​

type DocWithId = Document & { id: string }

Schema Types​

Field<T>​

The field builder type. Every t.*() method returns a Field<T>.

interface Field<T> {
  _def: FieldDef          // internal
  _infer: T               // phantom type

  optional(): Field<T | undefined>
  default(value: T | (() => T)): Field<T>
  index(options?: { unique?: boolean }): Field<T>
}

SchemaInstance<T>​

interface SchemaInstance<T extends DocWithId> {
  readonly infer: T
  readonly _fields: Record<string, FieldDef>
  readonly _indexes: { field: string; unique?: boolean }[]
}

InferSchema<T>​

Utility type to extract the document shape from a schema:

type InferSchema<T> = {
  [K in keyof T]: T[K] extends Field<infer U> ? U : never
}

FieldDef​

Internal field descriptor:

interface FieldDef {
  type: 'string' | 'number' | 'boolean' | 'id' | 'date' | 'array' | 'object' | 'enum' | 'ref'
  optional: boolean
  hasDefault: boolean
  defaultValue?: unknown
  defaultFn?: () => unknown
  itemField?: FieldDef       // for array fields
  fields?: Record<string, FieldDef>  // for object fields
  enumValues?: readonly unknown[]
  refCollection?: string     // for ref fields
  indexed?: boolean
  indexUnique?: boolean
}

Query Types​

FilterOp​

type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'contains' | 'startsWith'

FilterClause​

interface FilterClause {
  field: string
  op: FilterOp
  value: unknown
}

QueryParams​

interface QueryParams {
  filter?: FilterClause[]
  orFilter?: FilterClause[]
  limit?: number
  offset?: number
  orderBy?: OrderByClause[]
  select?: string[]
}

OrderByClause​

interface OrderByClause {
  field: string
  direction: SortDirection
}

type SortDirection = 'asc' | 'desc'

AggregateStage​

type AggregateStage =
  | { $match: Record<string, unknown> }
  | { $group: Record<string, unknown> }
  | { $sort: Record<string, 1 | -1> }
  | { $limit: number }
  | { $skip: number }
  | { $count: string }
  | { $or: AggregateStage[] }
  | { $and: AggregateStage[] }

Adapter Types​

StorageAdapter​

Core interface for storage backends:

interface StorageAdapter {
  // Basic (required)
  read(collection: string): Promise<string | null>
  write(collection: string, data: string): Promise<void>
  exists(collection: string): Promise<boolean>
  delete?(collection: string): Promise<void>

  // Pro (optional)
  query?(collection: string, params: QueryParams): Promise<Record<string, unknown>[]>
  insertOne?(collection: string, doc: Record<string, unknown>): Promise<Record<string, unknown>>
  updateMany?(collection: string, filter: FilterClause[], changes: Record<string, unknown>): Promise<number>
  deleteMany?(collection: string, filter: FilterClause[]): Promise<number>
  count?(collection: string, filter?: FilterClause[]): Promise<number>
  aggregate?(collection: string, pipeline: AggregateStage[]): Promise<unknown>

  // Schema & indexes
  ensureCollection?(name: string, fields: Record<string, FieldDef>): Promise<void>
  createIndex?(collection: string, field: string, options?: IndexOptions): Promise<void>
  dropIndex?(collection: string, field: string): Promise<void>

  // Transaction support
  transaction?<T>(fn: (adapter: StorageAdapter) => Promise<T>): Promise<T>

  // Lifecycle
  connect?(): Promise<void>
  disconnect?(): Promise<void>
}

FileAdapterConfig​

interface FileAdapterConfig {
  path?: string   // Default: './data'
}

SqliteAdapterConfig​

interface SqliteAdapterConfig {
  path?: string          // Default: './data.db'
  tablePrefix?: string   // Default: ''
}

D1AdapterConfig​

interface D1AdapterConfig {
  binding: D1Database
  tablePrefix?: string
}

IndexOptions​

interface IndexOptions {
  unique?: boolean
  name?: string
}

Hook Types​

HookEvent​

type HookEvent =
  | 'before:insert'
  | 'after:insert'
  | 'before:update'
  | 'after:update'
  | 'before:delete'
  | 'after:delete'

Hook Handlers​

type BeforeInsertHook<T> = (doc: T) => Promise<void> | void
type AfterInsertHook<T> = (doc: T) => Promise<void> | void
type BeforeUpdateHook<T> = (filter: Partial<T>, changes: Partial<T>) => Promise<void> | void
type AfterUpdateHook<T> = (filter: Partial<T>, changes: Partial<T>, count: number) => Promise<void> | void
type BeforeDeleteHook<T> = (filter: Partial<T>) => Promise<void> | void
type AfterDeleteHook<T> = (filter: Partial<T>, count: number) => Promise<void> | void

interface HookMap<T> {
  'before:insert'?: BeforeInsertHook<T>[]
  'after:insert'?: AfterInsertHook<T>[]
  'before:update'?: BeforeUpdateHook<T>[]
  'after:update'?: AfterUpdateHook<T>[]
  'before:delete'?: BeforeDeleteHook<T>[]
  'after:delete'?: AfterDeleteHook<T>[]
}

Migration Types​

Migration​

interface Migration {
  up(db: DB): Promise<void>
  down?(db: DB): Promise<void>
}

MigrationRecord​

interface MigrationRecord {
  id: string
  name: string
  appliedAt: string
}