ai-database

2.1.3 verified Sat Apr 25 auth: no javascript

ai-database is an npm package (v2.1.3) that provides AI-powered database interface primitives with MDXLD conventions. It allows developers to define typed schemas with relationship operators (->, ~>, <-, <~) for AI-native linking, enabling cascade generation of entity graphs in a single call. Key features include promise pipelining (chain without await), batch relationship loading (eliminates N+1 queries), natural language queries, and full TypeScript support. Released on npm, it uses vitest for testing and is part of the ai-primitives ecosystem. It differs from traditional ORMs by being designed for AI-generated data, automatically matching existing records or creating new ones with fuzzy matching.

Common errors

error ERR_REQUIRE_ESM ↓

cause Package is ESM-only and cannot be loaded with require() in CommonJS.

fix

Use import: import { DB } from 'ai-database' or switch to dynamic import(): const { DB } = await import('ai-database')

error TypeError: db.Lead is not a function ↓

cause The DB() call expects a schema object, but was called without arguments or with invalid schema definition.

fix

Ensure DB is called with a valid schema object: const { db } = DB({ Lead: { name: 'string' } })

error Property 'company' does not exist on type 'Lead' ↓

cause TypeScript type inference fails when relationship operator is missing or has typos.

fix

Define the relationship in the schema using the correct operator, e.g., company: 'Company.leads'

Warnings

breaking In v2.0, the 'cascade' option became required for creating related entities in a single call. Omitting it will create only the top-level entity. ↓

fix Add { cascade: true } to create calls that should generate related entities.

deprecated The 'fuzzyMatch' option has been renamed to 'matchMode' in v2.1. fuzzyMatch still works but logs a deprecation warning. ↓

fix Use matchMode: 'fuzzy' instead of fuzzyMatch: true.

gotcha Syntax errors in relationship references (e.g., using '->' without defining the target type) will throw cryptic runtime errors, not compile-time errors. ↓

fix Always define the referenced type in the schema. Use TypeScript's strict mode to catch missing types.

gotcha Natural language queries (template literals) are not SQL injection-safe if the input contains user-controlled strings. They should only be used with trusted data. ↓

fix Do not interpolate untrusted user input directly into template literal queries. Validate and sanitize input.

breaking ESM-only since v2. No CommonJS support. Import with require() will fail. ↓

fix Convert project to ESM, or use dynamic import() if in a CommonJS context.

Install

npm install ai-database

yarn add ai-database

pnpm add ai-database

Imports

DB
wrong
```
const DB = require('ai-database')
```
correct
```
import { DB } from 'ai-database'
```
Package is ESM-only; CommonJS require will not work. TypeScript types are bundled.
DB (default import)
```
import DB from 'ai-database'
```
The package also exports DB as a default export. Both default and named imports work.
type ReadonlyProxy
wrong
```
import { ReadonlyProxy } from 'ai-database'
```
correct
```
import type { ReadonlyProxy } from 'ai-database'
```
Use import type for type-only imports to avoid runtime overhead in TypeScript.
DatabaseConfig
```
import type { DatabaseConfig } from 'ai-database'
```
This type is only available as a type export; do not import as a value.

Quickstart

Shows schema definition, cascade creation, relationship resolution, promise pipelining filtering, and natural language query.

import { DB } from 'ai-database'

const { db } = DB({
  Lead: { name: 'string', company: 'Company.leads', score: 'number' },
  Company: { name: 'string', industry: 'string' }
})

// Create a lead with cascade
const lead = await db.Lead.create({ name: 'John', score: 85 }, { cascade: true })
// Resolve relationship
const company = await lead.company

// List and filter with promise pipelining
const topLeads = await db.Lead.list().filter(l => l.score > 80)

// Natural language query
const results = await db.Lead`who closed deals this month?`