ai-database

library2.1.3jsnpmunverified

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.

database ai-ml llm-agents serialization

npm install ai-database

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AI-DATABASE

ai-database

databasejavascriptv2.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { DB } from 'ai-database'

✗ const DB = require('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

✓ import type { ReadonlyProxy } from 'ai-database'

✗ import { 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.

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

Debug

Known issues

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

affects: >=2.0.0

deprecatedThe '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.

affects: >=2.1.0 <3.0.0

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

affects: *

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

affects: *

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

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

TypeError: db.Lead is not a function

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' } })

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

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'

Upgrade

Version history

2.1.3latest on npm

Audit

Dependencies

vitestoptionalRequired for testing; peer dependency that developers must install to run tests

Agent activity

66 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/ai-primitives/primitives.org.ai ↗

packagehttps://www.npmjs.com/package/ai-database ↗

homepagehttps://ai-database.ai ↗