API Reference

Complete API documentation for an5 ORM.

An5Adapter Class (@an5/adapters)

Factory / Constructor

import { createAn5Adapter, An5Adapter } from '@an5/adapters';

const db = createAn5Adapter({
  connectionString: process.env.DATABASE_URL!,
});

Methods

Method / Property Returns Description
db[modelName] AdapterTableClient<T> Dynamic model access property (e.g. db.user, db.order)
table(name) AdapterTableClient<T> Explicit dynamic table client instance (adapter.table('User'))
$connect() Promise<void> Establish connection to database
$disconnect() Promise<void> Close database connection pool
$transaction(fn, options?) Promise<T> Execute callback-style transaction

AdapterTableClient API

findFirst

db.model.findFirst(params: FindFirstArgs): Promise<Model | null>

Params:

{
  where?: WhereInput,
  orderBy?: OrderByInput,
  include?: IncludeInput,
  select?: SelectInput,
  skip?: number,
  take?: number
}

findMany

db.model.findMany(params: FindManyArgs): Promise<Model[]>

Params:

{
  where?: WhereInput,
  orderBy?: OrderByInput | OrderByInput[],
  include?: IncludeInput,
  select?: SelectInput,
  skip?: number,
  take?: number
}

create

db.model.create(params: CreateArgs): Promise<Model>

Params:

{
  data: CreateInput,
  include?: IncludeInput,
  select?: SelectInput
}

createMany

db.model.createMany(params: CreateManyArgs): Promise<BatchPayload>

Params:

{
  data: CreateInput[],
  skipDuplicates?: boolean
}

update

db.model.update(params: UpdateArgs): Promise<Model>

Params:

{
  where: WhereInput,
  data: UpdateInput,
  include?: IncludeInput,
  select?: SelectInput
}

updateMany

db.model.updateMany(params: UpdateManyArgs): Promise<BatchPayload>

Params:

{
  where?: WhereInput,
  data: UpdateInput
}

upsert

db.model.upsert(params: UpsertArgs): Promise<Model>

Params:

{
  where: WhereInput,
  create: CreateInput,
  update: UpdateInput
}

delete

db.model.delete(params: DeleteArgs): Promise<Model>

Params:

{
  where: WhereInput
}

deleteMany

db.model.deleteMany(params: DeleteManyArgs): Promise<BatchPayload>

Params:

{
  where?: WhereInput
}

count

db.model.count(params?: CountArgs): Promise<number>

aggregate

db.model.aggregate(params: AggregateArgs): Promise<AggregateResult>

Params:

{
  where?: WhereInput,
  _count?: boolean,
  _sum?: { field: boolean },
  _avg?: { field: boolean },
  _min?: { field: boolean },
  _max?: { field: boolean }
}

groupBy

db.model.groupBy(params: GroupByArgs): Promise<GroupByResult[]>

Params:

{
  by: ScalarFieldEnum | ScalarFieldEnum[],
  where?: WhereInput,
  orderBy?: OrderByInput | OrderByInput[],
  skip?: number,
  take?: number,
  _count?: true | { _all?: true; field?: true },
  _sum?: { numericField?: true },
  _avg?: { numericField?: true },
  _min?: { field?: true },
  _max?: { field?: true }
}

vectorSearch

db.model.vectorSearch(params: VectorSearchArgs): Promise<Model[]>

Params:

{
  vector: number[],
  vectorField?: string,
  take?: number,
  distanceMetric?: 'cosine' | 'euclidean' | 'dot',
  vectorElementType?: 'float32' | 'float16' | 'uint8',
  where?: WhereInput,
  include?: IncludeInput
}

Returns (Model & { distance: number })[], ordered by distance ascending.

Each provider ranks in the database when it can, and scores the column in the client when it cannot: dedicated vector databases (NBase, Qdrant, Chroma, Pinecone, Weaviate, Milvus), then pgvector on PostgreSQL, VECTOR_DISTANCE on SQL Server 2025, then — on SQLite — sqlite-vec, the runtime’s own an5_vec_* functions, or json_each. A row whose stored vector cannot be scored is left out rather than returned with a null distance.

vectorElementType applies to SQL Server only; SQLite stores a VECTOR(n) column as a BLOB of little-endian float32 and decodes both that and the older JSON text form on read. include is not applied to vector results: a hit is the whole row.

Where Input

Basic Operators

{
  // Equality
  field: 'value',
  status: { equals: 'active' },
  deletedAt: null,
  archivedAt: { equals: null },
  role: { not: 'banned' },
  email: { not: null },
  name: { not: { contains: 'legacy' } },
  
  // Comparison
  score: { gt: 10 },
  age: { gte: 18 },
  views: { lt: 1000 },
  orderCount: { lte: 10 },
  
  // String
  title: { contains: 'text' },
  firstName: { startsWith: 'Jo' },
  lastName: { endsWith: 'son' },
  
  // List
  team: { in: ['a', 'b'] },
  tag: { notIn: ['archived', 'deleted'] }
}

Logical Operators

{
  AND: [{ field: 'value' }, { field2: 'value' }],
  OR: [{ field: 'value' }, { field2: 'value' }],
  NOT: [{ field: 'value' }, { field2: { startsWith: 'tmp' } }]
}

AND and NOT accept either a single object or an array of objects.

Relation Filters

{
  posts: { some: { title: 'Hello' } },
  posts: { none: {} },
  posts: { every: { published: true } }
}

Empty relation filters are meaningful: some: {} checks that at least one related row exists, none: {} checks that no related rows exist, and every: {} is treated as true.

Update Input

Scalar fields accept direct replacement values. Numeric fields also accept field operations:

{
  name: 'Updated',
  score: { increment: 1 },
  total: { decrement: 10 },
  multiplier: { multiply: 2 },
  ratio: { divide: 4 },
  count: { set: 0 }
}

Common nested writes are supported on relation fields:

{
  posts: {
    create: [{ title: 'New' }],
    connect: [{ id: 'post-1' }],
    set: [{ id: 'post-2' }],
    disconnect: [{ id: 'post-3' }],
    delete: [{ id: 'post-4' }],
    update: [{ where: { id: 'post-5' }, data: { title: 'Updated' } }],
    upsert: [{
      where: { id: 'post-6' },
      create: { title: 'Created' },
      update: { title: 'Updated' }
    }]
  }
}

Include Input

{
  // Simple include
  posts: true,
  
  // With ordering / projection
  posts: {
    select: { id: true, title: true },
    orderBy: { createdAt: 'desc' }
  },
  
  // Nested
  posts: {
    include: {
      comments: true,
      author: true
    }
  },
  
  // Count
  _count: {
    select: { posts: true }
  }
}

Select Input

{
  id: true,
  email: true,
  name: true,
  posts: {
    select: {
      id: true,
      title: true
    }
  },
  _count: true
}

Relation fields inside select behave as implicit includes. Helper keys needed to resolve selected relations are fetched internally and removed from the final projection when not explicitly selected.

{
  name: true,
  orders: {
    select: { id: true }
  },
  _count: {
    select: { orders: true }
  }
}

Order By Input

// Single field
{ createdAt: 'desc' }

// Multiple fields
[
  { role: 'asc' },
  { createdAt: 'desc' }
]

For regular find* queries, only scalar columns are supported in orderBy. groupBy can also order grouped rows through its orderBy argument.

Transaction

$transaction

await db.$transaction(async (tx) => {
  // Operations using tx instead of db
  const user = await tx.user.create({...});
  const order = await tx.order.create({...});
});

$transaction is callback-based and automatically commits or rolls back. Calling tx.$transaction() inside an active transaction reuses the same transactional executor when the adapter does not provide native nested transactions.

Interactive Transactions

const tx = await db.$begin();

try {
  await tx.user.update({ where: { id: userId }, data: { active: true } });
  await tx.$commit();
} catch (error) {
  await tx.$rollback();
  throw error;
}

$begin() requires the underlying adapter or custom executor to expose interactive transaction support. Google Sheets does not support interactive transactions.

Raw Queries

$queryRaw

// Template tag
const users = await db.$queryRaw`
  SELECT * FROM users 
  WHERE email LIKE ${'%@example.com'}
`;

$executeRaw

const result = await db.$executeRaw`
  UPDATE users SET active = 0 
  WHERE last_login < ${dateThreshold}
`;

Batch Payload

{
  count: number  // Number of affected rows
}

Error Handling

import { An5ClientKnownRequestError } from '@an5/orm';

try {
  await db.user.create({
    data: { email: 'john@example.com' }
  });
} catch (error) {
  if (error instanceof An5ClientKnownRequestError) {
    console.log('Code:', error.code);
    console.log('Message:', error.message);
  }
}

Known Error Codes

Code Description
P2002 Unique constraint violation
P2003 Foreign key constraint
P2025 Record not found

Other failures surface as the underlying driver error.


@an5/adapters

The @an5/adapters package provides database and spreadsheet execution for the ORM and can also be used standalone. The full public API is exported from the package root.

Factory functions

Function Description
createAn5Adapter(config) Create an adapter from An5AdapterConfig. Detects the dialect from the config type or from a connectionString scheme (sqlserver://, postgres://, mysql://, sqlite://, googlesheets://)
createAn5SheetsAdapter(config) Create a Google Sheets adapter from An5SheetsAdapterConfig
parseSheetsConnectionString(url) Parse a googlesheets:// connection string into An5SheetsAdapterConfig
import {
  createAn5Adapter,
  createAn5SheetsAdapter,
  parseSheetsConnectionString,
} from '@an5/adapters';

// Dialect auto-detection from connection string
const db = createAn5Adapter({
  connectionString: 'googlesheets://spreadsheetId;clientEmail=...;privateKey=...',
});

// Direct Sheets configuration
const sheets = createAn5SheetsAdapter({
  spreadsheetId: 'spreadsheetId',
  clientEmail: 'sa@project.iam.gserviceaccount.com',
  privateKey: '...',
  sheetMapping: { users: 'Users' },
});

// Parse a connection string
const cfg = parseSheetsConnectionString('googlesheets://spreadsheetId;apiKey=...');

Adapter classes

Class Description
An5Adapter Dialect-agnostic adapter (exec, executeRaw, table, $transaction, $connect, $disconnect)
An5SheetsAdapter Spreadsheet adapter. Adds readRange, writeRange, appendRange, listSheets, deleteSheet
SheetsTableClient<T> Typed table client over a sheet (findMany, findFirst, create, update, delete, clear, deleteAll, …)

Config functions

Function Description
getLlmConfig() / setLlmConfig(config) Read/update the active LLM configuration
getEmbeddingConfig() / setEmbeddingConfig(config) Read/update the active embedding configuration
resetAdapter() Clear cached adapter/config state
setAdapterMetadata(metadata) Pass schema metadata explicitly to the adapter

Subpaths

The package also exposes scoped entry points:

Subpath Contents
@an5/adapters/browser Browser-safe bundle (Sheets via fetch + metadata helpers, no SQL engines)
@an5/adapters/googlesheets Google Sheets adapter only
@an5/adapters/config LlmConfigData / EmbeddingConfigData types and helpers
@an5/adapters/mssql SQL Server engine
@an5/adapters/postgres PostgreSQL engine
@an5/adapters/mysql MySQL engine
@an5/adapters/sqlite SQLite engine
@an5/adapters/base Base types and metadata helpers
@an5/adapters/python Packaged Python adapter facade source
@an5/adapters/dotnet Packaged .NET adapter facade source
@an5/adapters/golang Packaged Go adapter facade source
@an5/adapters/rust Packaged Rust adapter Cargo crate
@an5/adapters/vector Unified vector store factory (createVectorStore) and providers
@an5/adapters/nbase NBase dialect adapter
@an5/adapters/qdrant Qdrant vector client
@an5/adapters/chroma ChromaDB vector client
@an5/adapters/pinecone Pinecone vector client
@an5/adapters/weaviate Weaviate vector client
@an5/adapters/milvus Milvus / Zilliz vector client

Sheets config (An5SheetsAdapterConfig)

Field Type Description
spreadsheetId string Google Sheets spreadsheet id
clientEmail? string OAuth service-account email (use with privateKey)
privateKey? string Service-account private key
credentials? object Alternative: full service-account JSON credentials
accessToken? string OAuth access token (browser mode)
apiKey? string Google API key (browser mode)
sheetMapping? Record<string, string> Model → sheet name mapping (defaults to model name)

Browser Adapters API (@an5/adapters/browser)

The @an5/adapters/browser entrypoint provides zero-dependency browser-safe database adapters for Web Browsers, WASM, and Client Components.

createBrowserSqliteAdapter

Creates a type-safe AN5 ORM adapter for in-browser SQLite execution drivers (such as sql.js, WASM, OPFS, or Capacitor/Expo SQLite).

import { createBrowserSqliteAdapter } from '@an5/adapters/browser';

const adapter = createBrowserSqliteAdapter({
  driver: {
    exec: (sql: string, params?: any[]) => rows
  },
  dialect: 'sqlite'
});

An5SheetsAdapter / createAn5SheetsAdapter

Creates a browser-safe Google Sheets database adapter.

import { createAn5SheetsAdapter } from '@an5/adapters/browser';

const sheetsDb = createAn5SheetsAdapter({
  spreadsheetId: 'YOUR_SHEET_ID',
  accessToken: 'YOUR_OAUTH_TOKEN' // or apiKey: 'YOUR_API_KEY'
});

An5Agent Class

Constructor

import { An5Agent } from '@an5/agent';

const agent = new An5Agent(tools?: Tool[]);

Registers the 7 default tools unless overridden; custom tools can be appended.

Methods

Method Returns Description
process(context) Promise<AgentResponse> Process AgentContext ({ userQuestion, database?, toolContext? })
executeTool(name, input, context?) Promise<unknown> Execute a specific tool
getTools() Tool[] Get all registered tools
getTool(name) Tool \| undefined Get tool by name
addTool(tool) void Register a new tool

Tools (8 consolidated)

Tool Actions Description
schema list, describe, relations Explore data models
query generate, explain, validate Work with SQL queries
database execute, describe, health Database operations
generateClientCode - Generate client code
generateCode - Request-specific application code through a model callback, or schema/API context for the calling model
analyzeSchema - Analyze schema issues
retrieve schema, queries Semantic search
task create, list, update, delete Manage tasks

For detailed tool documentation, see AI Agent Tools.


CLI & Automation Commands

Schema/database workflows run as npm scripts from the an5Orm/ directory or workspace root, while delivery, tunneling, and dashboard operations run via an5-cli (npx an5-cli).

Schema Management

Command Description
npm run generate Generate client code from schema
npm run db:push Push schema to database
npm run db:pull Pull schema from database
npm run db:seed Seed database with sample data
npm run db:migrate diff Compare schema with database
npm run db:migrate:generate Generate migration SQL
npm run db:migrate:apply Apply pending migration files; pass -- --preview to preview SQL
npm run db:migrate:rollback Roll back the latest applied migration; pass -- --preview, -- 3, or -- --to <file>
npm run db:migrate:status Show migration status

Development

The following are workspace-root scripts (run from the repository root, not from an5Orm/):

Command Where Description
npm run build workspace root Build all workspace packages
npm test an5Orm/ or workspace root Run tests (an5Orm) or the full workspace suite
npm run test:full workspace root Run workspace tests plus generator, package smoke, and Python/.NET/Go compile gates
npm run test:integration:live workspace root Run live adapter Postgres/SQL Server checks plus ORM SQL Server relation/transaction/vector fallback checks when database URLs are configured
npm run ui workspace root Start local UI

Release

Command Description
npm run preview Preview release changes
npm run release Release across the workspace

For more CLI commands, see CLI Commands.