{"id":18100,"library":"ai-database","title":"ai-database","description":"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.","status":"active","version":"2.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/ai-primitives/primitives.org.ai","tags":["javascript","ai","database","linked-data","mdxld","primitives","typescript"],"install":[{"cmd":"npm install ai-database","lang":"bash","label":"npm"},{"cmd":"yarn add ai-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add ai-database","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for testing; peer dependency that developers must install to run tests","package":"vitest","optional":true}],"imports":[{"note":"Package is ESM-only; CommonJS require will not work. TypeScript types are bundled.","wrong":"const DB = require('ai-database')","symbol":"DB","correct":"import { DB } from 'ai-database'"},{"note":"The package also exports DB as a default export. Both default and named imports work.","wrong":"","symbol":"DB (default import)","correct":"import DB from 'ai-database'"},{"note":"Use import type for type-only imports to avoid runtime overhead in TypeScript.","wrong":"import { ReadonlyProxy } from 'ai-database'","symbol":"type ReadonlyProxy","correct":"import type { ReadonlyProxy } from 'ai-database'"},{"note":"This type is only available as a type export; do not import as a value.","wrong":"","symbol":"DatabaseConfig","correct":"import type { DatabaseConfig } from 'ai-database'"}],"quickstart":{"code":"import { DB } from 'ai-database'\n\nconst { db } = DB({\n  Lead: { name: 'string', company: 'Company.leads', score: 'number' },\n  Company: { name: 'string', industry: 'string' }\n})\n\n// Create a lead with cascade\nconst lead = await db.Lead.create({ name: 'John', score: 85 }, { cascade: true })\n// Resolve relationship\nconst company = await lead.company\n\n// List and filter with promise pipelining\nconst topLeads = await db.Lead.list().filter(l => l.score > 80)\n\n// Natural language query\nconst results = await db.Lead`who closed deals this month?`","lang":"typescript","description":"Shows schema definition, cascade creation, relationship resolution, promise pipelining filtering, and natural language query."},"warnings":[{"fix":"Add { cascade: true } to create calls that should generate related entities.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use matchMode: 'fuzzy' instead of fuzzyMatch: true.","message":"The 'fuzzyMatch' option has been renamed to 'matchMode' in v2.1. fuzzyMatch still works but logs a deprecation warning.","severity":"deprecated","affected_versions":">=2.1.0 <3.0.0"},{"fix":"Always define the referenced type in the schema. Use TypeScript's strict mode to catch missing types.","message":"Syntax errors in relationship references (e.g., using '->' without defining the target type) will throw cryptic runtime errors, not compile-time errors.","severity":"gotcha","affected_versions":"*"},{"fix":"Do not interpolate untrusted user input directly into template literal queries. Validate and sanitize input.","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"Convert project to ESM, or use dynamic import() if in a CommonJS context.","message":"ESM-only since v2. No CommonJS support. Import with require() will fail.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use import: import { DB } from 'ai-database' or switch to dynamic import(): const { DB } = await import('ai-database')","cause":"Package is ESM-only and cannot be loaded with require() in CommonJS.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure DB is called with a valid schema object: const { db } = DB({ Lead: { name: 'string' } })","cause":"The DB() call expects a schema object, but was called without arguments or with invalid schema definition.","error":"TypeError: db.Lead is not a function"},{"fix":"Define the relationship in the schema using the correct operator, e.g., company: 'Company.leads'","cause":"TypeScript type inference fails when relationship operator is missing or has typos.","error":"Property 'company' does not exist on type 'Lead'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}