ai-database 0.1.0 → 0.2.0

package/dist/schema.d.ts

@@ -0,0 +1,899 @@
+/**
+ * Schema-first Database Definition
+ *
+ * Declarative schema with automatic bi-directional relationships.
+ * Uses mdxld conventions for entity structure.
+ *
+ * @example
+ * ```ts
+ * const { db } = DB({
+ *   Post: {
+ *     title: 'string',
+ *     author: 'Author.posts',     // one-to-many: Post.author -> Author, Author.posts -> Post[]
+ *     tags: ['Tag.posts'],        // many-to-many: Post.tags -> Tag[], Tag.posts -> Post[]
+ *   },
+ *   Author: {
+ *     name: 'string',
+ *     // posts: Post[] auto-created from backref
+ *   },
+ *   Tag: {
+ *     name: 'string',
+ *     // posts: Post[] auto-created from backref
+ *   }
+ * })
+ *
+ * // Typed access
+ * const post = await db.Post.get('123')
+ * post.author  // Author (single)
+ * post.tags    // Tag[] (array)
+ * ```
+ */
+import { DBPromise, type ForEachOptions, type ForEachResult } from './ai-promise-db.js';
+export type { ThingFlat, ThingExpanded, PrimitiveType, FieldDefinition, EntitySchema, DatabaseSchema, ParsedField, ParsedEntity, ParsedSchema, Verb, Noun, NounProperty, NounRelationship, TypeMeta, EntityId, Thing, Relationship, QueryOptions, ThingSearchOptions, CreateOptions, UpdateOptions, RelateOptions, Event, ActionStatus, Action, ArtifactType, Artifact, StoreArtifactOptions, EventQueryOptions, ActionQueryOptions, DBClient, DBClientExtended, CreateEventOptions as GraphCreateEventOptions, CreateActionOptions as GraphCreateActionOptions, } from './types.js';
+export { toExpanded, toFlat, Verbs, resolveUrl, resolveShortUrl, parseUrl } from './types.js';
+export { conjugate, pluralize, singularize, inferNoun, createTypeMeta, getTypeMeta, Type, getVerbFields, } from './linguistic.js';
+import type { EntitySchema, DatabaseSchema, ParsedEntity, ParsedSchema, Verb, Noun } from './types.js';
+/**
+ * Create a Noun definition with type inference
+ *
+ * @example
+ * ```ts
+ * const Post = defineNoun({
+ *   singular: 'post',
+ *   plural: 'posts',
+ *   description: 'A blog post',
+ *   properties: {
+ *     title: { type: 'string', description: 'Post title' },
+ *     content: { type: 'markdown' },
+ *   },
+ *   relationships: {
+ *     author: { type: 'Author', backref: 'posts' },
+ *   },
+ * })
+ * ```
+ */
+export declare function defineNoun<T extends Noun>(noun: T): T;
+/**
+ * Create a Verb definition with type inference
+ *
+ * @example
+ * ```ts
+ * const publish = defineVerb({
+ *   action: 'publish',
+ *   actor: 'publisher',
+ *   act: 'publishes',
+ *   activity: 'publishing',
+ *   result: 'publication',
+ *   reverse: { at: 'publishedAt', by: 'publishedBy' },
+ *   inverse: 'unpublish',
+ * })
+ * ```
+ */
+export declare function defineVerb<T extends Verb>(verb: T): T;
+/**
+ * Convert a Noun to an EntitySchema for use with DB()
+ *
+ * @example
+ * ```ts
+ * const postNoun = defineNoun({
+ *   singular: 'post',
+ *   plural: 'posts',
+ *   properties: { title: { type: 'string' } },
+ *   relationships: { author: { type: 'Author', backref: 'posts' } },
+ * })
+ *
+ * const db = DB({
+ *   Post: nounToSchema(postNoun),
+ * })
+ * ```
+ */
+export declare function nounToSchema(noun: Noun): EntitySchema;
+/**
+ * Built-in Thing schema - base type for all entities
+ *
+ * Every entity instance is a Thing with a relationship to its Noun.
+ * This creates a complete graph: Thing.type -> Noun.things
+ *
+ * @example
+ * ```ts
+ * // Every post instance:
+ * post.$type   // 'Post' (string)
+ * post.type    // -> Noun('Post') (relationship)
+ *
+ * // From Noun, get all instances:
+ * const postNoun = await db.Noun.get('Post')
+ * const allPosts = await postNoun.things  // -> Post[]
+ * ```
+ */
+export declare const ThingSchema: EntitySchema;
+/**
+ * Built-in Noun schema for storing type definitions
+ *
+ * Every Type/Collection automatically gets a Noun record stored in the database.
+ * This enables introspection and self-describing schemas.
+ *
+ * @example
+ * ```ts
+ * // When you define:
+ * const db = DB({ Post: { title: 'string' } })
+ *
+ * // The database auto-creates:
+ * // db.Noun.get('Post') => { singular: 'post', plural: 'posts', ... }
+ *
+ * // Query all types:
+ * const types = await db.Noun.list()
+ *
+ * // Get all instances of a type:
+ * const postNoun = await db.Noun.get('Post')
+ * const allPosts = await postNoun.things
+ *
+ * // Listen for new types:
+ * on.Noun.created(noun => console.log(`New type: ${noun.name}`))
+ * ```
+ */
+export declare const NounSchema: EntitySchema;
+/**
+ * Built-in Verb schema for storing action definitions
+ */
+export declare const VerbSchema: EntitySchema;
+/**
+ * Built-in Edge schema for relationships between types
+ *
+ * Every relationship in a schema creates an Edge record.
+ * This enables graph queries across the type system.
+ *
+ * @example
+ * ```ts
+ * // Post.author -> Author creates:
+ * // Edge { from: 'Post', name: 'author', to: 'Author', backref: 'posts', cardinality: 'many-to-one' }
+ *
+ * // Query the graph:
+ * const edges = await db.Edge.find({ to: 'Author' })
+ * // => [{ from: 'Post', name: 'author' }, { from: 'Comment', name: 'author' }]
+ *
+ * // What types reference Author?
+ * const referencing = edges.map(e => e.from)  // ['Post', 'Comment']
+ * ```
+ */
+export declare const EdgeSchema: EntitySchema;
+/**
+ * System types that are auto-created in every database
+ *
+ * The graph structure:
+ * - Thing.type -> Noun (every instance links to its type)
+ * - Noun.things -> Thing[] (every type has its instances)
+ * - Edge connects Nouns (relationships between types)
+ * - Verb describes actions on Nouns
+ */
+export declare const SystemSchema: DatabaseSchema;
+/**
+ * Create Edge records from schema relationships
+ *
+ * @internal Used by DB() to auto-populate Edge records
+ */
+export declare function createEdgeRecords(typeName: string, schema: EntitySchema, parsedEntity: ParsedEntity): Array<Record<string, unknown>>;
+/**
+ * Create a Noun record from a type name and optional schema
+ *
+ * @internal Used by DB() to auto-populate Noun records
+ */
+export declare function createNounRecord(typeName: string, schema?: EntitySchema, nounDef?: Partial<Noun>): Record<string, unknown>;
+/**
+ * Parse a database schema and resolve bi-directional relationships
+ */
+export declare function parseSchema(schema: DatabaseSchema): ParsedSchema;
+/**
+ * Map field type to TypeScript type
+ */
+type FieldToTS<T extends string> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'date' | 'datetime' ? Date : T extends 'json' ? Record<string, unknown> : T extends 'markdown' ? string : T extends 'url' ? string : unknown;
+/**
+ * Infer entity type from schema definition
+ */
+export type InferEntity<TSchema extends DatabaseSchema, TEntity extends keyof TSchema> = {
+    $id: string;
+    $type: TEntity;
+} & {
+    [K in keyof TSchema[TEntity]]: TSchema[TEntity][K] extends `${infer Type}.${string}` ? Type extends keyof TSchema ? InferEntity<TSchema, Type> : unknown : TSchema[TEntity][K] extends `${infer Type}[]` ? Type extends keyof TSchema ? InferEntity<TSchema, Type>[] : FieldToTS<Type>[] : TSchema[TEntity][K] extends `${infer Type}?` ? FieldToTS<Type> | undefined : FieldToTS<TSchema[TEntity][K] & string>;
+};
+/**
+ * Operations available on each entity type
+ */
+export interface EntityOperations<T> {
+    /** Get an entity by ID */
+    get(id: string): Promise<T | null>;
+    /** List all entities */
+    list(options?: ListOptions): Promise<T[]>;
+    /** Find entities matching criteria */
+    find(where: Partial<T>): Promise<T[]>;
+    /** Search entities */
+    search(query: string, options?: SearchOptions): Promise<T[]>;
+    /** Create a new entity */
+    create(data: Omit<T, '$id' | '$type'>): Promise<T>;
+    create(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Update an entity */
+    update(id: string, data: Partial<Omit<T, '$id' | '$type'>>): Promise<T>;
+    /** Upsert an entity */
+    upsert(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Delete an entity */
+    delete(id: string): Promise<boolean>;
+    /** Iterate over entities */
+    forEach(callback: (entity: T) => void | Promise<void>): Promise<void>;
+    forEach(options: ListOptions, callback: (entity: T) => void | Promise<void>): Promise<void>;
+}
+/**
+ * Operations with promise pipelining support
+ *
+ * Query methods return DBPromise for chainable operations:
+ * - `.map()` with batch optimization
+ * - `.filter()`, `.sort()`, `.limit()`
+ * - Property access tracking for projections
+ *
+ * @example
+ * ```ts
+ * // Chain without await
+ * const leads = db.Lead.list()
+ * const qualified = await leads
+ *   .filter(l => l.score > 80)
+ *   .map(l => ({ name: l.name, company: l.company }))
+ *
+ * // Batch relationship loading
+ * const orders = await db.Order.list().map(o => ({
+ *   order: o,
+ *   customer: o.customer,  // Batch loaded!
+ * }))
+ * ```
+ */
+export interface PipelineEntityOperations<T> {
+    /** Get an entity by ID */
+    get(id: string): DBPromise<T | null>;
+    /** List all entities */
+    list(options?: ListOptions): DBPromise<T[]>;
+    /** Find entities matching criteria */
+    find(where: Partial<T>): DBPromise<T[]>;
+    /** Search entities */
+    search(query: string, options?: SearchOptions): DBPromise<T[]>;
+    /** Get first matching entity */
+    first(): DBPromise<T | null>;
+    /** Create a new entity */
+    create(data: Omit<T, '$id' | '$type'>): Promise<T>;
+    create(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Update an entity */
+    update(id: string, data: Partial<Omit<T, '$id' | '$type'>>): Promise<T>;
+    /** Upsert an entity */
+    upsert(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Delete an entity */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Process each entity with concurrency control, progress tracking, and error handling
+     *
+     * Designed for large-scale operations like AI generations or workflows.
+     *
+     * @example
+     * ```ts
+     * // Simple iteration
+     * await db.Lead.forEach(lead => console.log(lead.name))
+     *
+     * // With AI and concurrency
+     * const result = await db.Lead.forEach(async lead => {
+     *   const analysis = await ai`analyze ${lead}`
+     *   await db.Lead.update(lead.$id, { analysis })
+     * }, {
+     *   concurrency: 10,
+     *   onProgress: p => console.log(`${p.completed}/${p.total}`),
+     * })
+     *
+     * // With error handling
+     * await db.Order.forEach(async order => {
+     *   await sendInvoice(order)
+     * }, {
+     *   maxRetries: 3,
+     *   onError: (err, order) => err.code === 'RATE_LIMIT' ? 'retry' : 'continue',
+     * })
+     * ```
+     */
+    forEach<U>(callback: (entity: T, index: number) => U | Promise<U>, options?: ForEachOptions<T>): Promise<ForEachResult>;
+}
+export interface ListOptions {
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+export interface SearchOptions extends ListOptions {
+    fields?: string[];
+    minScore?: number;
+}
+/**
+ * Natural language query result
+ */
+export interface NLQueryResult<T = unknown> {
+    /** The interpreted query */
+    interpretation: string;
+    /** Confidence in the interpretation (0-1) */
+    confidence: number;
+    /** The results */
+    results: T[];
+    /** SQL/filter equivalent (for debugging) */
+    query?: string;
+    /** Explanation of what was found */
+    explanation?: string;
+}
+/**
+ * Tagged template for natural language queries
+ *
+ * @example
+ * ```ts
+ * // Query across all types
+ * const results = await db`what is happening with joe in ca?`
+ *
+ * // Query specific type
+ * const orders = await db.Orders`what pending orders are delayed?`
+ *
+ * // With interpolation
+ * const name = 'joe'
+ * const results = await db`find all orders for ${name}`
+ * ```
+ */
+export type NLQueryFn<T = unknown> = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<NLQueryResult<T>>;
+/**
+ * Typed database client based on schema
+ *
+ * Entity operations return DBPromise for chainable queries:
+ * ```ts
+ * const { db } = DB({ Lead: { name: 'string', company: 'Company.leads' } })
+ *
+ * // Chain without await
+ * const leads = db.Lead.list()
+ * const qualified = await leads.filter(l => l.score > 80)
+ *
+ * // Batch relationship loading
+ * const withCompanies = await leads.map(l => ({
+ *   lead: l,
+ *   company: l.company,  // Batch loaded!
+ * }))
+ * ```
+ */
+export type TypedDB<TSchema extends DatabaseSchema> = {
+    [K in keyof TSchema]: PipelineEntityOperations<InferEntity<TSchema, K>> & NLQueryFn<InferEntity<TSchema, K>>;
+} & {
+    /** The parsed schema */
+    readonly $schema: ParsedSchema;
+    /** Get any entity by URL */
+    get(url: string): Promise<unknown>;
+    /** Search across all entities */
+    search(query: string, options?: SearchOptions): Promise<unknown[]>;
+    /** Count entities of a type */
+    count(type: string, where?: Record<string, unknown>): Promise<number>;
+    /** Iterate over entities with a callback */
+    forEach(options: {
+        type: string;
+        where?: Record<string, unknown>;
+        concurrency?: number;
+    }, callback: (entity: unknown) => void | Promise<void>): Promise<void>;
+    /** Set entity data by ID (creates or replaces) */
+    set(type: string, id: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Generate entities using AI */
+    generate(options: GenerateOptions): Promise<unknown | {
+        id: string;
+    }>;
+    /**
+     * Natural language query across all types
+     *
+     * @example
+     * ```ts
+     * const results = await db`what orders are pending for customers in california?`
+     * const results = await db`show me joe's recent activity`
+     * const results = await db`what changed in the last hour?`
+     * ```
+     */
+    ask: NLQueryFn;
+};
+/**
+ * Options for AI-powered entity generation
+ */
+export interface GenerateOptions {
+    type: string;
+    count?: number;
+    data?: Record<string, unknown>;
+    mode?: 'sync' | 'background';
+}
+/**
+ * Actor data - who performed the action
+ *
+ * @example
+ * ```ts
+ * const actorData: ActorData = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   org: 'Acme Corp',
+ *   role: 'admin',
+ * }
+ * ```
+ */
+export interface ActorData {
+    /** Actor's display name */
+    name?: string;
+    /** Actor's email */
+    email?: string;
+    /** Actor's organization */
+    org?: string;
+    /** Actor's role or access level */
+    role?: string;
+    /** Additional actor metadata */
+    [key: string]: unknown;
+}
+/**
+ * Event data structure - Actor-Event-Object-Result pattern
+ *
+ * Following ActivityStreams semantics:
+ * - Actor: Who did it (user, system, agent)
+ * - Event: What happened (created, updated, published)
+ * - Object: What it was done to (the entity)
+ * - Result: What was the outcome (optional)
+ *
+ * @example
+ * ```ts
+ * const event: DBEvent = {
+ *   id: '01HGXYZ...',
+ *   actor: 'user:john',
+ *   actorData: { name: 'John Doe', email: 'john@example.com' },
+ *   event: 'Post.published',
+ *   object: 'https://example.com/Post/hello-world',
+ *   objectData: { title: 'Hello World' },
+ *   result: 'https://example.com/Publication/123',
+ *   resultData: { url: 'https://blog.example.com/hello-world' },
+ *   timestamp: new Date(),
+ * }
+ * ```
+ */
+export interface DBEvent {
+    /** Unique event ID (ULID recommended) */
+    id: string;
+    /** Actor identifier (user:id, system, agent:name) */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Event type (Entity.action format, e.g., Post.created) */
+    event: string;
+    /** Object URL/identifier that was acted upon */
+    object?: string;
+    /** Object data snapshot at time of event */
+    objectData?: Record<string, unknown>;
+    /** Result URL/identifier (outcome of the action) */
+    result?: string;
+    /** Result data */
+    resultData?: Record<string, unknown>;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** When the event occurred */
+    timestamp: Date;
+    /** @deprecated Use 'event' instead */
+    type?: string;
+    /** @deprecated Use 'objectData' instead */
+    data?: unknown;
+    /** @deprecated Use 'object' instead */
+    url?: string;
+}
+/**
+ * Options for creating an event
+ */
+export interface CreateEventOptions {
+    /** Actor identifier */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Event type */
+    event: string;
+    /** Object URL/identifier */
+    object?: string;
+    /** Object data */
+    objectData?: Record<string, unknown>;
+    /** Result URL/identifier */
+    result?: string;
+    /** Result data */
+    resultData?: Record<string, unknown>;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Events API for subscribing to and emitting events
+ */
+export interface EventsAPI {
+    /** Subscribe to events matching a pattern */
+    on(pattern: string, handler: (event: DBEvent) => void | Promise<void>): () => void;
+    /** Emit an event using Actor-Event-Object-Result pattern */
+    emit(options: CreateEventOptions): Promise<DBEvent>;
+    /** Emit a simple event (legacy compatibility) */
+    emit(type: string, data: unknown): Promise<DBEvent>;
+    /** List events with optional filters */
+    list(options?: {
+        event?: string;
+        actor?: string;
+        object?: string;
+        since?: Date;
+        until?: Date;
+        limit?: number;
+        /** @deprecated Use 'event' instead */
+        type?: string;
+    }): Promise<DBEvent[]>;
+    /** Replay events through a handler */
+    replay(options: {
+        event?: string;
+        actor?: string;
+        since?: Date;
+        handler: (event: DBEvent) => void | Promise<void>;
+        /** @deprecated Use 'event' instead */
+        type?: string;
+    }): Promise<void>;
+}
+/**
+ * Action data structure for durable execution
+ *
+ * Uses linguistic verb conjugations for semantic clarity:
+ * - act: Present tense 3rd person (creates, publishes)
+ * - action: Base verb form (create, publish)
+ * - activity: Gerund/progressive (creating, publishing)
+ *
+ * @example
+ * ```ts
+ * const action: DBAction = {
+ *   id: '01HGXYZ...',
+ *   actor: 'user:john',
+ *   actorData: { name: 'John Doe' },
+ *   // Verb conjugations
+ *   act: 'generates',        // Present tense: "system generates posts"
+ *   action: 'generate',      // Base form for lookups
+ *   activity: 'generating',  // Progressive: "currently generating posts"
+ *   // Target
+ *   object: 'Post',
+ *   objectData: { count: 100 },
+ *   // Status
+ *   status: 'active',
+ *   progress: 50,
+ *   total: 100,
+ *   // Result
+ *   result: { created: 50 },
+ *   timestamp: new Date(),
+ * }
+ * ```
+ */
+export interface DBAction {
+    /** Unique action ID (ULID recommended) */
+    id: string;
+    /** Actor identifier (user:id, system, agent:name) */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Present tense 3rd person verb (creates, publishes, generates) */
+    act: string;
+    /** Base verb form - imperative (create, publish, generate) */
+    action: string;
+    /** Gerund/progressive form (creating, publishing, generating) */
+    activity: string;
+    /** Object being acted upon (type name or URL) */
+    object?: string;
+    /** Object data/parameters for the action */
+    objectData?: Record<string, unknown>;
+    /** Action status */
+    status: 'pending' | 'active' | 'completed' | 'failed' | 'cancelled';
+    /** Current progress count */
+    progress?: number;
+    /** Total items to process */
+    total?: number;
+    /** Result data on completion */
+    result?: Record<string, unknown>;
+    /** Error message on failure */
+    error?: string;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** When the action was created */
+    createdAt: Date;
+    /** When the action started executing */
+    startedAt?: Date;
+    /** When the action completed/failed */
+    completedAt?: Date;
+    /** @deprecated Use 'action' instead */
+    type?: string;
+    /** @deprecated Use 'objectData' instead */
+    data?: unknown;
+}
+/**
+ * Options for creating an action
+ */
+export interface CreateActionOptions {
+    /** Actor identifier */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Base verb (will auto-conjugate to act/activity) */
+    action: string;
+    /** Object being acted upon */
+    object?: string;
+    /** Object data/parameters */
+    objectData?: Record<string, unknown>;
+    /** Total items for progress tracking */
+    total?: number;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** @deprecated Use 'action' instead */
+    type?: string;
+    /** @deprecated Use 'objectData' instead */
+    data?: unknown;
+}
+/**
+ * Actions API for durable execution tracking
+ *
+ * @example
+ * ```ts
+ * // Create an action with verb conjugation
+ * const action = await actions.create({
+ *   actor: 'system',
+ *   action: 'generate',  // auto-conjugates to act='generates', activity='generating'
+ *   object: 'Post',
+ *   objectData: { count: 100 },
+ *   total: 100,
+ * })
+ *
+ * // Update progress
+ * await actions.update(action.id, { progress: 50 })
+ *
+ * // Complete with result
+ * await actions.update(action.id, {
+ *   status: 'completed',
+ *   result: { created: 100 },
+ * })
+ * ```
+ */
+export interface ActionsAPI {
+    /** Create a new action (auto-conjugates verb forms) */
+    create(options: CreateActionOptions): Promise<DBAction>;
+    /** Create with legacy format (deprecated) */
+    create(data: {
+        type: string;
+        data: unknown;
+        total?: number;
+    }): Promise<DBAction>;
+    /** Get an action by ID */
+    get(id: string): Promise<DBAction | null>;
+    /** Update action progress/status */
+    update(id: string, updates: Partial<Pick<DBAction, 'status' | 'progress' | 'result' | 'error'>>): Promise<DBAction>;
+    /** List actions with optional filters */
+    list(options?: {
+        status?: DBAction['status'];
+        action?: string;
+        actor?: string;
+        object?: string;
+        since?: Date;
+        until?: Date;
+        limit?: number;
+        /** @deprecated Use 'action' instead */
+        type?: string;
+    }): Promise<DBAction[]>;
+    /** Retry a failed action */
+    retry(id: string): Promise<DBAction>;
+    /** Cancel a pending/active action */
+    cancel(id: string): Promise<void>;
+    /** Conjugate a verb to get all forms */
+    conjugate(action: string): Verb;
+}
+/**
+ * Artifact data structure for cached content
+ */
+export interface DBArtifact {
+    url: string;
+    type: string;
+    sourceHash: string;
+    content: unknown;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+}
+/**
+ * Artifacts API for cached embeddings and computed content
+ */
+export interface ArtifactsAPI {
+    /** Get an artifact by URL and type */
+    get(url: string, type: string): Promise<DBArtifact | null>;
+    /** Set an artifact */
+    set(url: string, type: string, data: {
+        content: unknown;
+        sourceHash: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Delete an artifact */
+    delete(url: string, type?: string): Promise<void>;
+    /** List artifacts for a URL */
+    list(url: string): Promise<DBArtifact[]>;
+}
+/**
+ * Nouns API for type introspection
+ */
+export interface NounsAPI {
+    /** Get a noun definition by type name */
+    get(name: string): Promise<Noun | null>;
+    /** List all noun definitions */
+    list(): Promise<Noun[]>;
+    /** Define a new noun */
+    define(noun: Noun): Promise<void>;
+}
+/**
+ * Verbs API for action introspection
+ */
+export interface VerbsAPI {
+    /** Get a verb definition by action name */
+    get(action: string): Verb | null;
+    /** List all verb definitions */
+    list(): Verb[];
+    /** Define a new verb */
+    define(verb: Verb): void;
+    /** Conjugate a verb from base form */
+    conjugate(action: string): Verb;
+}
+/**
+ * Result of DB() factory - supports both direct and destructured usage
+ *
+ * @example
+ * ```ts
+ * // Direct usage - everything on one object
+ * const db = DB(schema)
+ * db.User.create(...)      // entity operations
+ * db.events.on(...)        // events API
+ * db.actions.create(...)   // actions API
+ *
+ * // Destructured usage - cleaner separation
+ * const { db, events, actions } = DB(schema)
+ * db.User.create(...)      // just entity ops
+ * events.on(...)           // separate events
+ * ```
+ */
+export type DBResult<TSchema extends DatabaseSchema> = TypedDB<TSchema> & {
+    /** Self-reference for destructuring - same as the parent object but cleaner semantically */
+    db: TypedDB<TSchema>;
+    /** Event subscription and emission */
+    events: EventsAPI;
+    /** Durable action execution */
+    actions: ActionsAPI;
+    /** Cached embeddings and computed content */
+    artifacts: ArtifactsAPI;
+    /** Type introspection */
+    nouns: NounsAPI;
+    /** Action introspection */
+    verbs: VerbsAPI;
+};
+/**
+ * AI generator function type for NL queries
+ * This is injected by the user or resolved from environment
+ */
+export type NLQueryGenerator = (prompt: string, context: NLQueryContext) => Promise<NLQueryPlan>;
+/**
+ * Context provided to the AI for query generation
+ */
+export interface NLQueryContext {
+    /** Available types with their schemas */
+    types: Array<{
+        name: string;
+        singular: string;
+        plural: string;
+        fields: string[];
+        relationships: Array<{
+            name: string;
+            to: string;
+            cardinality: string;
+        }>;
+    }>;
+    /** The specific type being queried (if any) */
+    targetType?: string;
+    /** Recent events for context */
+    recentEvents?: Array<{
+        type: string;
+        timestamp: Date;
+    }>;
+}
+/**
+ * Query plan generated by AI
+ */
+export interface NLQueryPlan {
+    /** Types to query */
+    types: string[];
+    /** Filters to apply */
+    filters?: Record<string, unknown>;
+    /** Search terms */
+    search?: string;
+    /** Time range */
+    timeRange?: {
+        since?: Date;
+        until?: Date;
+    };
+    /** Relationships to follow */
+    include?: string[];
+    /** How to interpret results */
+    interpretation: string;
+    /** Confidence score */
+    confidence: number;
+}
+/**
+ * Set the AI generator for natural language queries
+ *
+ * @example
+ * ```ts
+ * import { generate } from 'ai-functions'
+ *
+ * setNLQueryGenerator(async (prompt, context) => {
+ *   return generate({
+ *     prompt: `Given this schema: ${JSON.stringify(context.types)}
+ *              Answer this question: ${prompt}
+ *              Return a query plan as JSON.`,
+ *     schema: NLQueryPlanSchema
+ *   })
+ * })
+ * ```
+ */
+export declare function setNLQueryGenerator(generator: NLQueryGenerator): void;
+/**
+ * Database provider interface that adapters must implement
+ */
+export interface DBProvider {
+    /** Get an entity */
+    get(type: string, id: string): Promise<Record<string, unknown> | null>;
+    /** List entities */
+    list(type: string, options?: ListOptions): Promise<Record<string, unknown>[]>;
+    /** Search entities */
+    search(type: string, query: string, options?: SearchOptions): Promise<Record<string, unknown>[]>;
+    /** Create an entity */
+    create(type: string, id: string | undefined, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Update an entity */
+    update(type: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Delete an entity */
+    delete(type: string, id: string): Promise<boolean>;
+    /** Get related entities */
+    related(type: string, id: string, relation: string): Promise<Record<string, unknown>[]>;
+    /** Create a relationship */
+    relate(fromType: string, fromId: string, relation: string, toType: string, toId: string): Promise<void>;
+    /** Remove a relationship */
+    unrelate(fromType: string, fromId: string, relation: string, toType: string, toId: string): Promise<void>;
+}
+/**
+ * Set the global database provider
+ */
+export declare function setProvider(provider: DBProvider): void;
+/**
+ * Create a typed database from a schema definition
+ *
+ * Supports both direct usage and destructuring for flexibility:
+ *
+ * @example Direct usage - everything on one object
+ * ```ts
+ * const db = DB({
+ *   Post: { title: 'string', author: 'Author.posts' },
+ *   Author: { name: 'string' },
+ * })
+ *
+ * // Entity operations
+ * const post = await db.Post.create({ title: 'Hello' })
+ *
+ * // Events, actions, etc. are also available directly
+ * db.events.on('Post.created', (event) => console.log(event))
+ * db.actions.create({ type: 'generate', data: {} })
+ * ```
+ *
+ * @example Destructured usage - cleaner separation
+ * ```ts
+ * const { db, events, actions, artifacts, nouns, verbs } = DB({
+ *   Post: { title: 'string', author: 'Author.posts' },
+ *   Author: { name: 'string' },
+ * })
+ *
+ * // CRUD operations on db
+ * const post = await db.Post.create({ title: 'Hello' })
+ * await db.Post.update(post.$id, { title: 'Updated' })
+ *
+ * // Separate events API
+ * events.on('Post.created', (event) => console.log(event))
+ *
+ * // Separate actions API
+ * const action = await actions.create({ type: 'generate', data: {} })
+ * ```
+ */
+export declare function DB<TSchema extends DatabaseSchema>(schema: TSchema): DBResult<TSchema>;
+export { parseSchema as parse };
+//# sourceMappingURL=schema.d.ts.map