kastor API reference

#kastor(config)

kastor({ adapter, schema, relations?, log? }): KastorClient

Creates the client. schema is an object of tables, relations a function that receives the tables and returns the relations of each one, log prints every statement when set to true or calls your function with it.

import pg from 'pg'
import { kastor, one, many } from 'kastor-orm'
import { postgres } from 'kastor-orm/postgres'
import { users, posts } from './schema'

export const db = kastor({
  adapter: postgres(new pg.Pool({ connectionString: process.env.DATABASE_URL })),
  schema: { users, posts },
  relations: ({ users, posts }) => ({
    users: { posts: many(posts) },
    posts: { author: one(users, { fields: ['authorId'], references: ['id'] }) },
  }),
})

#Adapters

Each adapter lives in its own entry point so your bundle only carries the dialect you use. On MongoDB, t.id() keys are ObjectIds exposed as strings (and so are the columns that reference them); pass mongodb(db, { ids: 'int' }) for numeric keys like on SQL, or ids: 'uuid' for UUID strings.

#Client members

$transaction, $sql, $execute, $schema (the schema as plain JSON), $dialect and $disconnect() which closes the pool you passed in.

#table(name, columns, options?)

table('users', { ... }, { indexes?, primaryKey?, softDelete? })

Declares a table. indexes: (cols) => [index(cols.a), uniqueIndex(cols.a, cols.b)] adds indexes, primaryKey: (cols) => [cols.a, cols.b] sets a composite key and softDelete: 'deletedAt' turns deletes into updates of that column. Columns are available as properties, users.email.

import { table, t, index, uniqueIndex } from 'kastor-orm'

export const memberships = table('memberships', {
  userId: t.int().references(() => users.id, { onDelete: 'cascade' }),
  teamId: t.int().references(() => teams.id, { onDelete: 'cascade' }),
  role: t.enum(['member', 'owner']).default('member'),
  joinedAt: t.datetime().defaultNow(),
}, {
  primaryKey: (m) => [m.userId, m.teamId],
  indexes: (m) => [index(m.teamId)],
})

#t

Column builders and the TypeScript type each one infers.

#Column modifiers

.nullable() adds | null, .default(value), .defaultNow(), .defaultRandom(), .defaultSql('...'), .unique(), .primaryKey(), .references(() => other.col, { onDelete, onUpdate }), .map('db_column') for a different column name in the database and .nativeType('varchar(64)') to pick the exact native type.

#one() and many()

one(target, { fields, references }?) many(target, { through }?)

Relations are declared next to the client, not in the tables, so tables never import each other in a cycle. Leave the config out of the side without the foreign key. For many to many, pass the join table with through.

relations: ({ users, posts, tags, postTags }) => ({
  users: { posts: many(posts) },
  posts: {
    author: one(users, { fields: ['authorId'], references: ['id'] }),
    tags: many(tags, { through: postTags }),
  },
})

#InferSelect and InferInsert

Row types for your own functions: type User = InferSelect<typeof users> is what queries return, InferInsert what create accepts (defaults and nullable columns are optional).

#findMany

findMany({ where?, select?, include?, orderBy?, take?, skip?, cursor?, distinct? })

All matching rows, as an array.

await db.posts.findMany({ where: { published: true }, orderBy: { id: 'desc' }, take: 20, skip: 40 })

#findFirst and findFirstOrThrow

The first matching row or null. The OrThrow version throws a KastorError with code NOT_FOUND.

#findUnique and findUniqueOrThrow

One row by a primary key or unique column.

await db.users.findUnique({ where: { email: 'ada@example.com' } })

#findPage

findPage({ first, after?, before?, where?, orderBy?, select?, include? })

Cursor pagination with opaque cursors. Returns { items, pageInfo }, where pageInfo holds startCursor, endCursor and hasNextPage. Pass after: pageInfo.endCursor for the next page, before for the previous one. first is the page size, 1 to 1000.

const page = await db.posts.findPage({ first: 20, orderBy: { id: 'desc' } })
const next = await db.posts.findPage({ first: 20, orderBy: { id: 'desc' }, after: page.pageInfo.endCursor })

#include

Loads relations, nested as deep as you like, each level with its own where, orderBy, take, skip, select and include. _count counts related rows. One query per root call: JSON aggregation on SQL databases, $lookup stages on MongoDB.

await db.users.findMany({
  include: {
    posts: { where: { published: true }, take: 3, include: { tags: true } },
    _count: { select: { posts: true } },
  },
})

#select

Picks columns and relations. The result type keeps only what you selected.

await db.users.findMany({ select: { id: true, email: true, posts: { select: { title: true } } } })

#count, aggregate and groupBy

count returns a number. aggregate computes _count, _sum, _avg, _min and _max. groupBy groups by columns with the same aggregates, having and ordering by aggregates.

#Operators

Every operator works on every database.

#create, createMany and createManyAndReturn

Insert one row (returned, with select or include if you like), many rows (returns { count }) or many rows and get them back. Nested create and connect write related rows in the same transaction.

await db.users.create({
  data: { email: 'kas@example.com', posts: { create: [{ title: 'First log' }] } },
})

#update, updateMany and upsert

Numbers accept { increment }, { decrement }, { multiply } and { divide }. upsert uses the native syntax of each database.

await db.posts.update({ where: { id: 1 }, data: { views: { increment: 1 } } })
await db.users.upsert({ where: { email }, create: { email }, update: { name } })

#delete and deleteMany

On soft delete tables they set the column instead; restore, hardDelete and hardDeleteMany are there too.

#$transaction

A callback that receives a transaction client, or an array of queries that run together. A nested call reuses the open transaction.

await db.$transaction(async (tx) => {
  const user = await tx.users.create({ data: { email } })
  await tx.posts.create({ data: { title: 'Welcome', authorId: user.id } })
})

#$sql, $execute and sql

Tagged templates: values become parameters. $sql returns rows typed by the generic you pass, $execute the affected row count. The sql tag builds fragments for where with sql.raw, sql.join and sql.ident.

const rows = await db.$sql<{ id: number; total: number }>`
  select author_id as id, count(*) as total from posts where views > ${min} group by author_id
`

#KastorError and isKastorError

Every failure is a KastorError with a stable code, a plain English message, a hint with the fix, meta and the driver error as cause.

#defineConfig

kastor.config.ts tells the CLI where the schema is, how to connect, where migrations live and which seed to run.

import pg from 'pg'
import { defineConfig } from 'kastor-orm'
import { postgres } from 'kastor-orm/postgres'

export default defineConfig({
  schema: './src/db/schema.ts',
  adapter: () => postgres(new pg.Pool({ connectionString: process.env.DATABASE_URL })),
  migrations: './kastor/migrations',
  seed: './src/db/seed.ts',
})

#defineSeed and factory

defineSeed<Db>(fn) factory(db.model, ({ seq }) => data)

defineSeed types the default export of your seed file, which npx kastor db seed calls with the client. factory takes a model of the client and a defaults function that receives a sequence number, and returns build, buildMany, create, createMany and reset.

import { factory } from 'kastor-orm'
import { db } from '../src/db'

export const users = factory(db.users, ({ seq }) => ({ email: `user${seq}@example.com` }))

const ada = await users.create({ name: 'Ada' })
const ten = await users.createMany(10)

#npx kastor

The command line. Every command takes --config and --help. The npm package is kastor-orm and the command is kastor: run npx kastor-orm init before the package is installed, and npx kastor migrate dev and the other commands once it is.