db4ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1281 @@
+import type { ComponentType } from 'react';
+export { SerializedFunction, serializeFunction, type EntityHandlerType, type SchemaHandlerType, type LifecycleHandlerType, type StateHandlerType, type HandlerExecutionResult, type HandlerLogEntry, } from './handlers';
+import { type SerializedFunction } from './handlers';
+/**
+ * Error codes for schema validation errors.
+ */
+export type SchemaValidationErrorCode = 'MISSING_CONTEXT' | 'MISSING_NAMESPACE' | 'INVALID_FIELD_TYPE';
+/**
+ * Error thrown when schema validation fails.
+ *
+ * @example
+ * try {
+ *   DB({ User: { name: 'User name' } }) // Missing $id or $context
+ * } catch (error) {
+ *   if (error instanceof SchemaValidationError) {
+ *     console.log(error.code) // 'MISSING_CONTEXT'
+ *   }
+ * }
+ */
+export declare class SchemaValidationError extends Error {
+    code: SchemaValidationErrorCode;
+    constructor(code: SchemaValidationErrorCode, message: string);
+}
+/**
+ * Error codes for API errors.
+ */
+export type APIErrorCode = 'REGISTRATION_FAILED' | 'GENERATION_FAILED' | 'REFERENCE_RESOLUTION_FAILED';
+/**
+ * Error thrown when API operations fail.
+ *
+ * @example
+ * try {
+ *   await db.User('john-doe')
+ * } catch (error) {
+ *   if (error instanceof APIError) {
+ *     console.log(error.code) // 'GENERATION_FAILED'
+ *     console.log(error.statusCode) // 404
+ *   }
+ * }
+ */
+export declare class APIError extends Error {
+    code: APIErrorCode;
+    statusCode?: number;
+    constructor(code: APIErrorCode, message: string, statusCode?: number);
+}
+export type Components = {
+    App: ComponentType;
+    List: ComponentType;
+    ListItem: ComponentType;
+    View: ComponentType;
+    Edit: ComponentType;
+    Chat: ComponentType;
+};
+export declare function UI(components: Components): Components;
+/**
+ * Parse namespace from a $id URL.
+ *
+ * @example
+ * parseNamespaceFromId('https://db.sb/sales') // 'sales' (from path)
+ * parseNamespaceFromId('https://db4.ai/startups') // 'startups' (from path)
+ * parseNamespaceFromId('https://db.sb/org/team') // 'org/team' (from path)
+ * parseNamespaceFromId('https://startup.db.sb') // 'startup' (from subdomain)
+ * parseNamespaceFromId('https://startups.db.sb') // 'startups' (from subdomain)
+ * parseNamespaceFromId('https://db.sb/') // null
+ * parseNamespaceFromId('invalid') // null
+ */
+export declare function parseNamespaceFromId(id: string): string | null;
+export type FieldValue = string | string[] | Record<string, string>;
+export interface SchemaMetadata {
+    $id?: string;
+    $context?: string;
+    $version?: string;
+}
+export type TypeDefinition = Record<string, FieldValue>;
+export type SchemaDefinition = SchemaMetadata & Record<string, TypeDefinition | string>;
+export interface StringField {
+    type: 'string';
+    description: string;
+    optional?: boolean;
+}
+/**
+ * Reference operators used in the schema DSL.
+ *
+ * - `->` (FORWARD_EXACT): Forward exact reference - resolves by ID
+ * - `~>` (FORWARD_FUZZY): Forward fuzzy reference - resolves by semantic matching
+ * - `<-` (BACKWARD_EXACT): Backward exact reference - reverse lookup by ID
+ * - `<~` (BACKWARD_FUZZY): Backward fuzzy reference - reverse lookup by semantic matching
+ *
+ * @example
+ * // Forward references (existing)
+ * { author: '->User' }     // Exact forward ref
+ * { avatar: '~>Image' }    // Fuzzy forward ref
+ *
+ * // Backward references (new)
+ * { posts: '<-Post' }      // Find Posts that reference this entity
+ * { related: '<~Article' } // Find semantically related Articles
+ */
+export declare const OPERATORS: {
+    /** Forward exact reference: `->Type` - resolves to exact ID match */
+    readonly FORWARD_EXACT: "->";
+    /** Forward fuzzy reference: `~>Type` - resolves by semantic similarity */
+    readonly FORWARD_FUZZY: "~>";
+    /** Backward exact reference: `<-Type` - finds entities referencing this one */
+    readonly BACKWARD_EXACT: "<-";
+    /** Backward fuzzy reference: `<~Type` - finds semantically related entities */
+    readonly BACKWARD_FUZZY: "<~";
+};
+/** Type for all valid reference operators */
+export type ReferenceOperator = (typeof OPERATORS)[keyof typeof OPERATORS];
+/** Parsed operator information returned by parseOperator */
+export type ParsedOperator = {
+    direction: 'forward';
+    fuzzy: boolean;
+} | {
+    direction: 'backward';
+    mode: 'exact' | 'fuzzy';
+};
+/**
+ * Parse a reference operator prefix into its direction and mode/fuzzy properties.
+ *
+ * This helper function converts the two-character operator prefix into structured
+ * properties for building ReferenceField objects.
+ *
+ * @param prefix - The operator prefix (`->`, `~>`, `<-`, or `<~`)
+ * @returns Parsed operator with direction and either fuzzy (forward) or mode (backward)
+ *
+ * @example
+ * parseOperator('->') // { direction: 'forward', fuzzy: false }
+ * parseOperator('~>') // { direction: 'forward', fuzzy: true }
+ * parseOperator('<-') // { direction: 'backward', mode: 'exact' }
+ * parseOperator('<~') // { direction: 'backward', mode: 'fuzzy' }
+ */
+export declare function parseOperator(prefix: string): ParsedOperator;
+/**
+ * Parsed reference field from the schema DSL.
+ *
+ * The `direction` and `mode` properties are used for backward references (`<-`, `<~`),
+ * while the `fuzzy` property is used for forward references (`->`, `~>`) for
+ * backward compatibility.
+ *
+ * ## Forward References (direction omitted)
+ * - `->Type` produces `{ fuzzy: false, ... }` - exact ID lookup
+ * - `~>Type` produces `{ fuzzy: true, ... }` - semantic matching
+ *
+ * ## Backward References
+ * - `<-Type` produces `{ direction: 'backward', mode: 'exact', ... }` - find by ID
+ * - `<~Type` produces `{ direction: 'backward', mode: 'fuzzy', ... }` - find by semantics
+ *
+ * @example
+ * // Forward exact reference
+ * parseFieldType('->User')
+ * // { type: 'reference', ref: 'User', isArray: false, optional: false, fuzzy: false }
+ *
+ * // Backward fuzzy array reference
+ * parseFieldType('<~Post[]')
+ * // { type: 'reference', ref: 'Post', isArray: true, optional: false, direction: 'backward', mode: 'fuzzy' }
+ */
+export interface ReferenceField {
+    type: 'reference';
+    /** Single reference target type (mutually exclusive with `refs`) */
+    ref?: string;
+    /** Union type reference targets (mutually exclusive with `ref`) */
+    refs?: string[];
+    /** Whether this is an array of references (e.g., `->Type[]`) */
+    isArray: boolean;
+    /** Whether the reference is optional (e.g., `->Type?`) */
+    optional?: boolean;
+    /** For forward references: true if fuzzy (`~>`), false if exact (`->`) */
+    fuzzy?: boolean;
+    /** For backward references: always 'backward' when present */
+    direction?: 'forward' | 'backward';
+    /** For backward references: 'exact' (`<-`) or 'fuzzy' (`<~`) */
+    mode?: 'exact' | 'fuzzy';
+}
+export interface ArrayField {
+    type: 'array';
+    items: {
+        type: 'string';
+    };
+    description: string;
+    optional?: boolean;
+    refs?: string[];
+    backRef?: string;
+    count?: number | {
+        min: number;
+        max: number;
+    };
+}
+export interface ObjectField {
+    type: 'object';
+    properties: Record<string, StringField>;
+    optional?: boolean;
+}
+export interface EmbeddedField {
+    type: 'embedded';
+    embeddedType: string;
+    isArray?: boolean;
+    optional?: boolean;
+}
+export interface JSONPathField {
+    type: 'jsonpath';
+    path: string;
+    transform?: string;
+}
+export interface JSONPathEmbeddedField {
+    type: 'jsonpath-embedded';
+    path: string;
+    embeddedType: string;
+    isArray: boolean;
+    optional?: boolean;
+}
+export interface ComputedField {
+    type: 'computed';
+    source: string;
+}
+export interface PromptField {
+    type: 'prompt';
+    prompt: string;
+}
+export type ParsedField = StringField | ReferenceField | ArrayField | ObjectField | EmbeddedField | JSONPathField | JSONPathEmbeddedField | ComputedField | PromptField;
+export interface TypeReference {
+    field: string;
+    ref: string;
+    refs?: string[];
+    isArray: boolean;
+    optional?: boolean;
+    fuzzy?: boolean;
+    backRef?: boolean;
+}
+export interface SeedConfig {
+    url: string;
+    format?: 'tsv' | 'csv' | 'json';
+    idField?: string;
+    id?: string;
+    idTransform?: string;
+    next?: string;
+    data?: string;
+}
+/**
+ * Parse $id field which can be:
+ * - Simple JSONPath: $.slug
+ * - Transform with path: PascalCase($.example)
+ * - Column name (legacy): slug
+ *
+ * @example
+ * parseIdConfig('$.slug')                    // { path: '$.slug' }
+ * parseIdConfig('PascalCase($.example)')     // { path: '$.example', transform: 'PascalCase' }
+ * parseIdConfig('kebab-case($.title)')       // { path: '$.title', transform: 'kebab-case' }
+ * parseIdConfig('slug')                      // { path: 'slug' }
+ */
+export declare function parseIdConfig(idField: string): {
+    path: string;
+    transform?: string;
+};
+/**
+ * Validates that a string is a valid JSONPath expression.
+ *
+ * A valid JSONPath must:
+ * - Start with `$.` (root reference)
+ * - Contain valid property names, array indices, or bracket notation
+ *
+ * Supported patterns:
+ * - `$.field` - Simple property access
+ * - `$.nested.field` - Nested property access
+ * - `$.array[0]` - Array index access
+ * - `$.array[*]` - Array wildcard
+ * - `$.items[?(@.active)]` - Filter expressions
+ *
+ * @example
+ * isValidJSONPath('$.title')           // true
+ * isValidJSONPath('$.data.items[0]')   // true
+ * isValidJSONPath('$.tags[*]')         // true
+ * isValidJSONPath('title')             // false (missing $.)
+ * isValidJSONPath('$50 price')         // false (not a valid path)
+ */
+export declare function isValidJSONPath(path: string): boolean;
+/**
+ * Type guard to check if a ParsedField is a JSONPathField.
+ *
+ * @example
+ * const field = parseFieldType('$.title')
+ * if (isJSONPathField(field)) {
+ *   console.log(field.path)  // TypeScript knows field.path exists
+ * }
+ */
+export declare function isJSONPathField(field: ParsedField): field is JSONPathField;
+/**
+ * Type guard to check if a ParsedField is a JSONPathEmbeddedField.
+ *
+ * @example
+ * const field = parseFieldType('$.author ->Author')
+ * if (isJSONPathEmbeddedField(field)) {
+ *   console.log(field.embeddedType)  // TypeScript knows field.embeddedType exists
+ * }
+ */
+export declare function isJSONPathEmbeddedField(field: ParsedField): field is JSONPathEmbeddedField;
+/**
+ * Type guard to check if a ParsedField is a PromptField.
+ *
+ * @example
+ * const field = parsed.types.Task.fields.description
+ * if (isPromptField(field)) {
+ *   console.log(field.prompt)  // TypeScript knows field.prompt exists
+ * }
+ */
+export declare function isPromptField(field: ParsedField): field is PromptField;
+/**
+ * Type guard to check if a ParsedField is a StringField.
+ */
+export declare function isStringField(field: ParsedField): field is StringField;
+/** Evaluation definition - stub type for schema parsing. */
+export type EvalDefinition = Record<string, unknown>;
+/** Schema experiment definition - stub type for schema parsing. */
+export type SchemaExperiment = Record<string, unknown>;
+/** Schema analytics configuration - stub type for schema parsing. */
+export type SchemaAnalytics = Record<string, unknown>;
+export interface OAuthConfig {
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
+export interface AsyncConfig {
+    start: string;
+    result: string;
+}
+export interface SourceConfig {
+    $api: string;
+    $apiKey?: string;
+    $bearer?: string;
+    $oauth?: OAuthConfig;
+    $data?: string;
+    $async?: AsyncConfig;
+}
+export type SourceInput = Record<string, 'string' | 'string?'>;
+export interface ImageConfig {
+    aspectRatio?: string;
+    style?: string;
+}
+export interface SpeechConfig {
+    voice?: string;
+    speed?: number;
+    format?: string;
+}
+export interface DiagramConfig {
+    type?: string;
+    direction?: string;
+    format?: string;
+}
+export interface ConventionsConfig {
+    nodes?: string;
+    edges?: string;
+    events?: string;
+}
+export interface CodeConfig {
+    language?: string;
+    runtime?: string;
+    framework?: string;
+}
+/** Transition configuration - simple string or complex object */
+export interface TransitionConfig {
+    to: string | null;
+    if?: SerializedFunction;
+    do?: SerializedFunction;
+}
+/** State configuration with transitions */
+export interface StateConfig {
+    transitions: Record<string, TransitionConfig>;
+    $entry?: SerializedFunction;
+    $exit?: SerializedFunction;
+}
+/** Parsed state machine configuration */
+export interface ParsedStateConfig {
+    $initial: string;
+    states: Record<string, StateConfig>;
+}
+/** Raw state config - input format before parsing */
+export type RawStateConfig = {
+    $initial: string;
+} & Record<string, unknown>;
+/** State validation error */
+export interface StateValidationError {
+    code: string;
+    message: string;
+    state?: string;
+    event?: string;
+    transition?: string;
+}
+/** State validation result */
+export interface StateValidationResult {
+    valid: boolean;
+    errors: StateValidationError[];
+}
+/**
+ * Validate a raw state machine configuration.
+ * Checks for: valid $initial, reachable states, no orphan states, valid transitions.
+ */
+export declare function validateStateConfig(config: RawStateConfig): StateValidationResult;
+/**
+ * Parse a raw state machine configuration into the normalized format.
+ * Converts string functions to SerializedFunction objects.
+ *
+ * @param config - Raw state machine config from schema
+ * @returns Parsed state machine configuration
+ *
+ * @example
+ * const parsed = parseStateConfig({
+ *   $initial: 'draft',
+ *   draft: {
+ *     submit: 'pending',
+ *     $entry: (entity) => { console.log('entered draft') }
+ *   },
+ *   pending: {
+ *     approve: { to: 'approved', if: (e) => e.score >= 80 }
+ *   },
+ *   approved: null  // terminal state
+ * })
+ */
+export declare function parseStateConfig(config: RawStateConfig): ParsedStateConfig;
+export interface ParsedType {
+    name: string;
+    fields: Record<string, ParsedField>;
+    references: TypeReference[];
+    seed?: SeedConfig;
+    icon?: string;
+    group?: string;
+    $created?: SerializedFunction;
+    $updated?: SerializedFunction;
+    $deleted?: SerializedFunction;
+    handlers?: Record<string, SerializedFunction>;
+    $state?: ParsedStateConfig;
+    source?: SourceConfig;
+    input?: SourceInput;
+    from?: string[];
+    cache?: string;
+    isSourceFunction?: boolean;
+    image?: ImageConfig;
+    speech?: SpeechConfig;
+    diagram?: DiagramConfig;
+    conventions?: ConventionsConfig;
+    code?: CodeConfig;
+    isGenerative?: boolean;
+    eval?: Record<string, EvalDefinition>;
+    experiment?: SchemaExperiment;
+}
+export interface SchemaSettings {
+    iconLibrary?: string;
+}
+export interface ParsedSchema {
+    types: Record<string, ParsedType>;
+    hash: string;
+    settings?: SchemaSettings;
+    fn?: Record<string, SerializedFunction>;
+    on?: Record<string, SerializedFunction>;
+    eval?: Record<string, EvalDefinition>;
+    experiment?: Record<string, SchemaExperiment>;
+    analytics?: SchemaAnalytics;
+    handlers?: Record<string, SerializedFunction>;
+}
+export interface JSONSchemaProperty {
+    type: string;
+    description?: string;
+    items?: {
+        type: string;
+        properties?: Record<string, JSONSchemaProperty>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface JSONSchema {
+    type: 'object';
+    properties: Record<string, JSONSchemaProperty>;
+    required: string[];
+    additionalProperties: boolean;
+}
+export declare function extractCountFromDescription(description: string): number | {
+    min: number;
+    max: number;
+} | undefined;
+/**
+ * Parse a field value into its structured field type representation.
+ *
+ * Converts the shorthand field notation used in schema definitions into
+ * a fully parsed field object with type information, references, and options.
+ *
+ * ## Reference Operators
+ *
+ * This function parses all four reference operators defined in {@link OPERATORS}:
+ *
+ * | Operator | Direction | Mode  | Description                    |
+ * |----------|-----------|-------|--------------------------------|
+ * | `->`     | forward   | exact | Resolves to exact ID match     |
+ * | `~>`     | forward   | fuzzy | Resolves by semantic similarity|
+ * | `<-`     | backward  | exact | Finds entities referencing this|
+ * | `<~`     | backward  | fuzzy | Finds semantically related     |
+ *
+ * @param value - The field value to parse. Can be:
+ *   - `string` - A field description or reference pattern (e.g., `'User name'`, `'->User'`, `'~>Image?'`, `'<-Post[]'`)
+ *   - `string[]` - An array field with description (e.g., `['Tag labels']`, `['<-Post']`)
+ *   - `Record<string, string>` - A nested object with field descriptions
+ *   - `Function` - A computed field
+ *
+ * @returns A ParsedField object representing the field type:
+ *   - `StringField` - Plain text field with description
+ *   - `ReferenceField` - Reference to another type (forward or backward)
+ *   - `ArrayField` - Array of strings or references
+ *   - `ObjectField` - Nested object with properties
+ *   - `EmbeddedField` - Embedded type (detected in second pass)
+ *   - `JSONPathField` - JSONPath expression for data mapping
+ *   - `ComputedField` - Field computed from a function
+ *
+ * @example
+ * // String field
+ * parseFieldType('User name')
+ * // { type: 'string', description: 'User name' }
+ *
+ * @example
+ * // Forward exact reference
+ * parseFieldType('->User')
+ * // { type: 'reference', ref: 'User', isArray: false, optional: false, fuzzy: false }
+ *
+ * @example
+ * // Forward fuzzy reference (optional)
+ * parseFieldType('~>Image?')
+ * // { type: 'reference', ref: 'Image', isArray: false, optional: true, fuzzy: true }
+ *
+ * @example
+ * // Forward array reference
+ * parseFieldType('->Tag[]')
+ * // { type: 'reference', ref: 'Tag', isArray: true, optional: false, fuzzy: false }
+ *
+ * @example
+ * // Backward exact reference - finds Posts that reference this entity
+ * parseFieldType('<-Post')
+ * // { type: 'reference', ref: 'Post', isArray: false, optional: false, direction: 'backward', mode: 'exact' }
+ *
+ * @example
+ * // Backward fuzzy reference array - finds semantically related Articles
+ * parseFieldType('<~Article[]')
+ * // { type: 'reference', ref: 'Article', isArray: true, optional: false, direction: 'backward', mode: 'fuzzy' }
+ *
+ * @example
+ * // Union type reference
+ * parseFieldType('->User|Organization')
+ * // { type: 'reference', refs: ['User', 'Organization'], isArray: false, optional: false, fuzzy: false }
+ *
+ * @example
+ * // String array with count hint
+ * parseFieldType(['List 5 keywords'])
+ * // { type: 'array', items: { type: 'string' }, description: 'List 5 keywords', count: 5 }
+ *
+ * @example
+ * // Nested object
+ * parseFieldType({ street: 'Street address', city: 'City name' })
+ * // { type: 'object', properties: { street: {...}, city: {...} } }
+ */
+export declare function parseFieldType(value: FieldValue | Function): ParsedField;
+/**
+ * Parsed reference field info for generation.
+ * Used by the two-phase generation pipeline to understand reference fields.
+ */
+export interface ParsedGenerationReference {
+    /** Reference mode: exact (->) or fuzzy (~>) */
+    mode: 'exact' | 'fuzzy';
+    /** Target type name (or first type for union types) */
+    targetType: string;
+    /** All target types for union types */
+    targetTypes?: string[];
+    /** Whether this reference is optional */
+    isOptional: boolean;
+    /** Whether this is an array reference */
+    isArray: boolean;
+}
+/**
+ * Parse a reference field definition for generation.
+ *
+ * Handles patterns like:
+ * - `->Person` - exact reference
+ * - `~>Industry` - fuzzy reference
+ * - `->Type[]` - array of exact references
+ * - `~>Type?` - optional fuzzy reference
+ * - `->User|Organization` - union type reference
+ *
+ * @param fieldDef - The field definition string (e.g., '->Person', '~>Industry?')
+ * @returns ParsedGenerationReference or null if not a reference field
+ *
+ * @example
+ * parseGenerationReference('->Person')
+ * // { mode: 'exact', targetType: 'Person', isOptional: false, isArray: false }
+ *
+ * @example
+ * parseGenerationReference('~>Industry?')
+ * // { mode: 'fuzzy', targetType: 'Industry', isOptional: true, isArray: false }
+ *
+ * @example
+ * parseGenerationReference('->User|Organization')
+ * // { mode: 'exact', targetType: 'User', targetTypes: ['User', 'Organization'], isOptional: false, isArray: false }
+ */
+export declare function parseGenerationReference(fieldDef: string): ParsedGenerationReference | null;
+/**
+ * Parse array field definition for generation.
+ *
+ * Handles array shorthand like `['~>Investor']` or `['->Person']`.
+ *
+ * @param fieldDef - The field definition array (e.g., ['~>Investor'])
+ * @returns ParsedGenerationReference or null if not a reference array
+ *
+ * @example
+ * parseGenerationArrayReference(['~>Investor'])
+ * // { mode: 'fuzzy', targetType: 'Investor', isOptional: false, isArray: true }
+ */
+export declare function parseGenerationArrayReference(fieldDef: string[]): ParsedGenerationReference | null;
+/**
+ * Check if a field definition is a reference field.
+ *
+ * @param fieldDef - The field definition (string or array)
+ * @returns true if this is a reference field
+ *
+ * @example
+ * isReferenceField('->User')  // true
+ * isReferenceField('~>Industry?')  // true
+ * isReferenceField(['~>Investor'])  // true
+ * isReferenceField('User name')  // false
+ * isReferenceField(['tags'])  // false
+ */
+export declare function isReferenceField(fieldDef: string | string[]): boolean;
+/**
+ * Extract reference mode from a field definition.
+ *
+ * @param fieldDef - The field definition
+ * @returns 'exact' | 'fuzzy' | null
+ */
+export declare function getReferenceMode(fieldDef: string | string[]): 'exact' | 'fuzzy' | null;
+/**
+ * Extract target type(s) from a reference field.
+ *
+ * @param fieldDef - The field definition
+ * @returns Target type string, array of types for unions, or null if not a reference
+ */
+export declare function getReferenceTargetType(fieldDef: string | string[]): string | string[] | null;
+/**
+ * Parse seed configuration from a schema type's `$seed` field.
+ *
+ * Seed configuration tells the system where to fetch initial data for a type,
+ * supporting TSV, CSV, and JSON formats with pagination support.
+ *
+ * @param value - The seed configuration. Can be:
+ *   - `string` - A URL (format inferred from extension: `.csv`, `.json`, or default `.tsv`)
+ *   - `Record<string, string>` - Object with explicit options
+ *
+ * @returns A SeedConfig object with:
+ *   - `url` - The data source URL
+ *   - `format` - Data format ('tsv', 'csv', or 'json')
+ *   - `idField` - Optional field to use as entity ID
+ *   - `next` - Optional JSONPath to pagination URL
+ *   - `data` - Optional JSONPath to data array in response
+ *
+ * @example
+ * // Simple URL (format inferred)
+ * parseSeedConfig('https://example.com/data.csv')
+ * // { url: 'https://example.com/data.csv', format: 'csv' }
+ *
+ * @example
+ * // URL with TSV default
+ * parseSeedConfig('https://example.com/data')
+ * // { url: 'https://example.com/data', format: 'tsv' }
+ *
+ * @example
+ * // Object config with pagination
+ * parseSeedConfig({
+ *   url: 'https://api.example.com/items',
+ *   format: 'json',
+ *   data: '$.items',
+ *   next: '$.pagination.next'
+ * })
+ * // { url: '...', format: 'json', data: '$.items', next: '$.pagination.next' }
+ */
+export declare function parseSeedConfig(value: string | Record<string, string>): SeedConfig;
+/**
+ * Converts string fields to prompt fields in a seeded type's field map.
+ *
+ * In seeded schemas, plain string values represent prompts for AI generation
+ * rather than simple field descriptions. This function performs the conversion
+ * after initial field parsing, ensuring that JSONPath fields and reference
+ * fields remain unchanged while string fields become prompt fields.
+ *
+ * @param fields - The parsed fields map from parseFieldType calls
+ * @returns A new fields map with string fields converted to prompt fields
+ *
+ * @example
+ * // Input: fields from a seeded type
+ * const fields = {
+ *   title: { type: 'string', description: 'Some title' },
+ *   jsonField: { type: 'jsonpath', path: '$.name' },
+ *   ref: { type: 'reference', ref: 'Other', isArray: false },
+ * }
+ *
+ * // Output: string -> prompt, others unchanged
+ * const converted = convertStringsToPromptsInSeededType(fields)
+ * // converted.title = { type: 'prompt', prompt: 'Some title' }
+ * // converted.jsonField = { type: 'jsonpath', path: '$.name' }
+ * // converted.ref = { type: 'reference', ref: 'Other', isArray: false }
+ *
+ * @remarks
+ * This function is called during parseSchema when a type has `$seed` defined.
+ * Only StringField types are converted; all other field types pass through unchanged.
+ */
+export declare function convertStringsToPromptsInSeededType(fields: Record<string, ParsedField>): Record<string, ParsedField>;
+/**
+ * Parse an entire schema definition into a structured ParsedSchema.
+ *
+ * This is the main parsing function that takes a schema definition object and
+ * produces a fully parsed representation with all types, fields, references,
+ * and metadata resolved.
+ *
+ * @param schema - The schema definition object containing type definitions and metadata.
+ *   Metadata fields are prefixed with `$` (e.g., `$id`, `$context`, `$settings`).
+ *   All other keys are treated as type definitions.
+ *
+ * @returns A ParsedSchema object containing:
+ *   - `types` - Record of parsed type definitions with fields and references
+ *   - `hash` - Deterministic hash of the schema for versioning
+ *   - `settings` - Optional schema-level settings (e.g., iconLibrary)
+ *
+ * @example
+ * const schema = parseSchema({
+ *   $id: 'https://db.sb/blog',
+ *   Post: {
+ *     title: 'Post title',
+ *     content: 'Main content',
+ *     author: '->User',
+ *     tags: ['Tag labels']
+ *   },
+ *   User: {
+ *     name: 'User name',
+ *     email: 'Email address',
+ *     posts: '->Post[]'
+ *   }
+ * })
+ *
+ * // schema.types.Post.fields.title
+ * // { type: 'string', description: 'Post title' }
+ *
+ * // schema.types.Post.references
+ * // [{ field: 'author', ref: 'User', isArray: false }]
+ *
+ * @example
+ * // Schema with seed configuration and icons
+ * const schema = parseSchema({
+ *   $context: 'startups',
+ *   $settings: { iconLibrary: 'lucide' },
+ *   Company: {
+ *     $icon: 'building',
+ *     $seed: 'https://api.example.com/companies.json',
+ *     name: 'Company name',
+ *     website: 'Website URL'
+ *   }
+ * })
+ *
+ * // schema.types.Company.icon === 'building'
+ * // schema.types.Company.seed.url === 'https://api.example.com/companies.json'
+ */
+export declare function parseSchema(schema: SchemaDefinition): ParsedSchema;
+/**
+ * Convert a parsed type definition to a JSON Schema representation.
+ *
+ * Transforms the internal ParsedType format into a standard JSON Schema object
+ * that can be used for validation, documentation, or AI generation prompts.
+ *
+ * @param parsedType - The parsed type definition to convert
+ * @param parsedSchema - Optional full schema for resolving embedded types.
+ *   When provided, embedded types (e.g., `Address` in `address: 'Address'`) are
+ *   recursively expanded into their full JSON Schema representation.
+ * @param seen - Internal set for tracking visited types to prevent infinite recursion
+ *   in circular reference scenarios. Do not pass this parameter manually.
+ *
+ * @returns A JSON Schema object with:
+ *   - `type: 'object'` - Always an object schema
+ *   - `properties` - Map of field names to their JSON Schema definitions
+ *   - `required` - Array of required field names (non-optional fields)
+ *   - `additionalProperties: false` - Strict schema, no extra fields allowed
+ *
+ * @example
+ * const parsed = parseSchema({
+ *   $context: 'blog',
+ *   Post: {
+ *     title: 'Post title',
+ *     author: '->User',
+ *     tags: ['List 3-5 keywords']
+ *   }
+ * })
+ *
+ * const jsonSchema = toJSONSchema(parsed.types.Post, parsed)
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     title: { type: 'string', description: 'Post title' },
+ * //     author: { type: 'string', description: 'Reference to User (ID)' },
+ * //     tags: { type: 'array', items: { type: 'string' }, minItems: 3, maxItems: 5 }
+ * //   },
+ * //   required: ['title', 'author', 'tags'],
+ * //   additionalProperties: false
+ * // }
+ *
+ * @example
+ * // With embedded types expanded
+ * const schema = parseSchema({
+ *   $context: 'app',
+ *   User: {
+ *     name: 'User name',
+ *     address: 'Address'  // Embedded type
+ *   },
+ *   Address: {
+ *     street: 'Street',
+ *     city: 'City'
+ *   }
+ * })
+ *
+ * const jsonSchema = toJSONSchema(schema.types.User, schema)
+ * // properties.address will contain the full Address schema inline
+ */
+export declare function toJSONSchema(parsedType: ParsedType, parsedSchemaOrIncludeRefs?: ParsedSchema | boolean, seen?: Set<string>): JSONSchema;
+/**
+ * Generate a deterministic hash for a schema definition.
+ *
+ * Creates a consistent 8-character hexadecimal hash that uniquely identifies
+ * a schema's structure. The hash is computed using the FNV-1a algorithm on
+ * the JSON-serialized schema with sorted keys, ensuring the same schema
+ * always produces the same hash regardless of property order.
+ *
+ * @param schema - The schema definition to hash
+ *
+ * @returns An 8-character hexadecimal hash string
+ *
+ * @example
+ * const hash1 = schemaHash({
+ *   $context: 'blog',
+ *   Post: { title: 'Title' }
+ * })
+ * // e.g., 'a1b2c3d4'
+ *
+ * // Same schema, different property order = same hash
+ * const hash2 = schemaHash({
+ *   Post: { title: 'Title' },
+ *   $context: 'blog'
+ * })
+ * // hash1 === hash2
+ *
+ * @example
+ * // Used for schema versioning
+ * const schema = parseSchema({ $context: 'app', User: { name: 'Name' } })
+ * console.log(schema.hash)
+ * // The hash can be used to detect schema changes and trigger migrations
+ */
+export declare function schemaHash(schema: SchemaDefinition): string;
+export type JobStatus = 'queued' | 'running' | 'completed' | 'failed';
+export interface Job<T = void> {
+    id: string;
+    status: JobStatus;
+    result?: T;
+    error?: Error;
+}
+/**
+ * EntityCollection is both a factory function and an iterable collection.
+ * - As factory: `await db.Idea('id', { concept: '...' })`
+ * - As collection: `for (const idea of db.Idea) { ... }`
+ */
+export interface EntityCollection<T extends Record<string, unknown> = Record<string, unknown>> extends Iterable<T> {
+    /** The type name of entities in this collection */
+    readonly $type: string;
+    /** Current count of entities in the local collection */
+    readonly $count: number;
+    /** Execute a function for each entity, returns a Job for tracking */
+    forEach(fn: (item: T) => void): Job<void>;
+    /** Transform each entity, returns a Combinable for chaining */
+    map<R>(fn: (item: T) => R): Combinable<R>;
+    /** Filter entities by predicate, returns a Combinable for chaining */
+    where(predicate: (item: T) => boolean): Combinable<T>;
+    /** Fetch all entities from API and populate collection */
+    fetchAll(): Promise<T[]>;
+    /** Factory function signature - call the collection to generate/fetch an entity */
+    (id: string, context?: Record<string, unknown>): Promise<T>;
+}
+export interface DBInstance<T = Record<string, unknown>> {
+    id: string;
+    type: string;
+    data: T;
+}
+export type GeneratedObject = Record<string, unknown>;
+export type TypeFactory = (id: string, context?: Record<string, unknown>) => Promise<GeneratedObject>;
+export interface DBResultBase {
+    schema: SchemaDefinition;
+    types: Record<string, ParsedType>;
+    hash: string;
+    id?: string;
+    context?: string;
+    namespace: string;
+    baseUrl: string;
+    instances: DBInstance[];
+    toJSONSchema: (typeName: string) => JSONSchema;
+    registerSchema: () => Promise<void>;
+}
+export type DBResult = DBResultBase & Record<string, EntityCollection>;
+/**
+ * Create a database instance from a schema definition.
+ *
+ * This is the main entry point for defining and working with a db4.ai schema.
+ * It parses the schema, registers it with the API, and returns a typed object
+ * that provides access to all defined types as EntityCollections.
+ *
+ * ## API Base URL Configuration
+ *
+ * The SDK determines the API base URL in the following priority order:
+ * 1. Host from `$id` if it's a full URL (e.g., `'https://custom.api.com/myapp'`)
+ * 2. `DB4AI_API_BASE` environment variable
+ * 3. Default: `'https://db4ai.dev'`
+ *
+ * @param schema - The schema definition object. Must include either:
+ *   - `$id` - A URL or namespace identifier (e.g., `'https://db.sb/blog'` or `'blog'`)
+ *   - `$context` - A namespace string (e.g., `'my-app'`)
+ *
+ *   Type definitions are records where keys are type names and values define fields.
+ *
+ * @returns A DBResult object providing:
+ *   - `schema` - The original schema definition
+ *   - `types` - Parsed type definitions
+ *   - `hash` - Schema version hash
+ *   - `namespace` - The resolved namespace
+ *   - `baseUrl` - API base URL
+ *   - `toJSONSchema(typeName)` - Convert a type to JSON Schema
+ *   - `registerSchema()` - Manually register the schema with the API
+ *   - Dynamic type accessors (e.g., `db.Post`, `db.User`) as EntityCollections
+ *
+ * @throws Error if neither `$id` nor `$context` is provided
+ *
+ * @example
+ * // Define a blog schema
+ * const db = DB({
+ *   $context: 'blog',
+ *   Post: {
+ *     title: 'Post title',
+ *     content: 'Main content',
+ *     author: '->User',
+ *     tags: ['List 3-5 keywords']
+ *   },
+ *   User: {
+ *     name: 'User name',
+ *     email: 'Email address'
+ *   }
+ * })
+ *
+ * @example
+ * // Generate a new post
+ * const post = await db.Post('my-first-post', { topic: 'AI' })
+ * console.log(post.title, post.content)
+ *
+ * @example
+ * // Fetch all posts and iterate
+ * await db.Post.fetchAll()
+ * for (const post of db.Post) {
+ *   console.log(post.title)
+ * }
+ *
+ * @example
+ * // Use with full URL
+ * const db = DB({
+ *   $id: 'https://db.sb/startups',
+ *   Company: {
+ *     name: 'Company name',
+ *     description: 'Company description'
+ *   }
+ * })
+ */
+export declare function DB(schema: SchemaDefinition): DBResult;
+/**
+ * A lazy pipeline builder for cartesian products and collection transformations.
+ *
+ * Combinable provides a fluent API for building transformation pipelines where
+ * no computation happens until a terminal operation is invoked. This enables
+ * efficient processing of large datasets and cartesian products.
+ *
+ * Key features:
+ * - Lazy evaluation: transformations are only applied when results are consumed
+ * - Chainable: all intermediate operations return new Combinable instances
+ * - Iterable: works with for...of loops and spread operator
+ *
+ * Intermediate operations (return Combinable):
+ * - `where(predicate)` - Filter items by predicate
+ * - `map(fn)` - Transform each item
+ * - `take(n)` - Limit to first n items
+ * - `skip(n)` - Skip first n items
+ *
+ * Terminal operations (trigger evaluation):
+ * - `all()` - Collect all results into an array
+ * - `first()` - Get the first result or undefined
+ * - `count()` - Count total results
+ * - Iteration via for...of or spread
+ *
+ * @example
+ * // Basic cartesian product
+ * const pairs = combine([1, 2, 3], ['a', 'b']).all()
+ * // [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b'], [3, 'a'], [3, 'b']]
+ *
+ * @example
+ * // Chained transformations
+ * const result = combine([1, 2, 3], [10, 20, 30])
+ *   .where(([a, b]) => a + b > 15)
+ *   .map(([a, b]) => a * b)
+ *   .take(3)
+ *   .all()
+ * // [20, 30, 40]
+ *
+ * @example
+ * // Lazy evaluation with for...of
+ * for (const [x, y] of combine(range(1000), range(1000)).take(10)) {
+ *   console.log(x, y)  // Only computes first 10 pairs
+ * }
+ *
+ * @example
+ * // From EntityCollection
+ * await db.User.fetchAll()
+ * const activeUsers = db.User
+ *   .where(user => user.isActive)
+ *   .map(user => user.email)
+ *   .all()
+ */
+export declare class Combinable<T> implements Iterable<T> {
+    private readonly source;
+    constructor(source: () => Generator<T>);
+    /**
+     * Filter combinations by predicate
+     */
+    where(predicate: (item: T) => boolean): Combinable<T>;
+    /**
+     * Transform each combination
+     */
+    map<R>(fn: (item: T) => R): Combinable<R>;
+    /**
+     * Limit to first n items
+     */
+    take(n: number): Combinable<T>;
+    /**
+     * Skip first n items
+     */
+    skip(n: number): Combinable<T>;
+    /**
+     * Collect all results into an array (terminal operation)
+     */
+    all(): T[];
+    /**
+     * Get the first result or undefined (terminal operation)
+     */
+    first(): T | undefined;
+    /**
+     * Count total results (terminal operation)
+     */
+    count(): number;
+    /**
+     * Make Combinable iterable with for...of and spread operator
+     */
+    [Symbol.iterator](): Iterator<T>;
+}
+export declare function combine<A, B>(a: Iterable<A>, b: Iterable<B>): Combinable<[A, B]>;
+export declare function combine<A, B, C>(a: Iterable<A>, b: Iterable<B>, c: Iterable<C>): Combinable<[A, B, C]>;
+export declare function combine<A, B, C, D>(a: Iterable<A>, b: Iterable<B>, c: Iterable<C>, d: Iterable<D>): Combinable<[A, B, C, D]>;
+export declare function combine<A, B, C, D, E>(a: Iterable<A>, b: Iterable<B>, c: Iterable<C>, d: Iterable<D>, e: Iterable<E>): Combinable<[A, B, C, D, E]>;
+/**
+ * Result of parsing MDX frontmatter
+ */
+export interface ParseMDXResult {
+    /** Parsed schema definition from YAML frontmatter */
+    schema: SchemaDefinition;
+    /** Remaining MDX body after frontmatter */
+    body: string;
+}
+/**
+ * Parse MDX frontmatter and extract schema definition.
+ *
+ * @param mdx - The MDX content with optional YAML frontmatter
+ * @returns Object with parsed schema and remaining body
+ * @throws Error if YAML syntax is invalid
+ *
+ * @example
+ * const mdx = `---
+ * $context: https://db.sb
+ * Idea:
+ *   concept: What is the concept?
+ * ---
+ *
+ * <App>content</App>`
+ *
+ * const { schema, body } = parseMDX(mdx)
+ * // schema = { $context: 'https://db.sb', Idea: { concept: 'What is the concept?' } }
+ * // body = '\n<App>content</App>'
+ */
+export declare function parseMDX(mdx: string): ParseMDXResult;
+/**
+ * Hook context passed to entity hooks
+ */
+export interface HookContext {
+    generate: (types: string | string[]) => Promise<void>;
+    changed?: Record<string, boolean>;
+}
+/**
+ * Entity lifecycle hooks
+ */
+export interface EntityHooks {
+    onCreate?: (entity: unknown, ctx: HookContext) => Promise<void>;
+    onUpdate?: (entity: unknown, ctx: HookContext) => Promise<void>;
+    onDelete?: (entity: unknown) => Promise<void>;
+}
+/**
+ * Navigation group in the sidebar
+ */
+export interface NavigationGroup {
+    name: string;
+    icon?: string;
+    children: (NavigationGroup | string)[];
+}
+/**
+ * Field configuration from <Field> elements
+ */
+export interface FieldConfig {
+    name: string;
+    lines?: number;
+    placeholder?: string;
+    display?: 'card' | 'link' | 'inline';
+    allowCreate?: boolean;
+    searchable?: boolean;
+    preview?: string[];
+    collapsed?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    span?: number;
+    autoFocus?: boolean;
+}
+/**
+ * Section configuration from <Section> elements
+ */
+export interface SectionConfig {
+    label: string;
+    collapsed?: boolean;
+    children?: (FieldConfig | SectionConfig)[];
+}
+/**
+ * Search configuration from <Search> elements
+ */
+export interface SearchConfig {
+    fields?: string[];
+}
+/**
+ * Filter configuration from <Filter> elements
+ */
+export interface FilterConfig {
+    field: string;
+    exists?: boolean;
+}
+/**
+ * Action configuration for generate/built-in actions
+ */
+export interface ActionConfig {
+    type: 'generate' | 'delete' | 'duplicate' | 'export' | 'import';
+    entity?: string;
+    context?: string[];
+    confirm?: string;
+    formats?: string[];
+}
+/**
+ * Role-based permission configuration
+ */
+export interface RoleConfig {
+    name: string;
+    actions: string[];
+}
+/**
+ * Template configuration for Cards/Detail views
+ */
+export interface TemplateConfig {
+    jsx: string;
+}
+/**
+ * Form configuration from <Form> elements
+ */
+export interface FormConfig {
+    layout?: 'stack' | 'grid';
+    fields?: string[];
+    children?: (FieldConfig | SectionConfig)[];
+}
+/**
+ * Display component configuration
+ */
+export interface DisplayConfig {
+    type: 'table' | 'grid' | 'cards';
+    columns?: string[];
+    sortable?: boolean;
+    template?: TemplateConfig;
+}
+/**
+ * View configuration (List, Detail, Edit, Create)
+ */
+export interface ViewConfig {
+    search?: SearchConfig;
+    filters?: FilterConfig[];
+    display?: DisplayConfig;
+    form?: FormConfig;
+    template?: TemplateConfig;
+    editor?: {
+        language: string;
+    };
+}
+/**
+ * Collection configuration for a schema type
+ */
+export interface CollectionConfig {
+    view?: 'table' | 'cards' | 'grid';
+    columns?: string[];
+    searchable?: boolean;
+    path?: string;
+    slug?: string;
+    list?: ViewConfig;
+    detail?: ViewConfig;
+    edit?: ViewConfig;
+    create?: ViewConfig;
+    actions?: ActionConfig[];
+    permissions?: RoleConfig[];
+    hooks?: EntityHooks;
+}
+/**
+ * Complete UI configuration parsed from JSX
+ */
+export interface UIConfig {
+    hooks: Record<string, EntityHooks>;
+    navigation: NavigationGroup[];
+    collections: Record<string, CollectionConfig>;
+}
+/**
+ * Parse JSX UI specification into UIConfig
+ *
+ * @param jsx - The JSX string to parse
+ * @param schema - The parsed schema to determine which elements are collections
+ * @returns Parsed UI configuration
+ * @throws Error if JSX syntax is invalid or no App root element
+ *
+ * @example
+ * const jsx = `
+ *   <App hooks={{ Startup: { onCreate: async () => {} } }}>
+ *     <Planning icon="lightbulb">
+ *       <Idea view="cards" />
+ *     </Planning>
+ *   </App>
+ * `
+ * const config = parseJSXUI(jsx, schema)
+ * // config.hooks = { Startup: { onCreate: ... } }
+ * // config.navigation = [{ name: 'Planning', icon: 'lightbulb', children: ['Idea'] }]
+ * // config.collections = { Idea: { view: 'cards' } }
+ */
+export declare function parseJSXUI(jsx: string, schema: ParsedSchema): UIConfig;
+/**
+ * Result of processing an MDX file
+ */
+export interface ProcessMDXResult {
+    /** Raw YAML schema definition */
+    schema: SchemaDefinition;
+    /** Parsed schema with types, fields, and references */
+    parsedSchema: ParsedSchema;
+    /** Parsed JSX UI configuration */
+    uiConfig: UIConfig;
+    /** Original JSX body (after frontmatter) */
+    rawBody: string;
+}
+/**
+ * Process an MDX file and return all parsed components.
+ */
+export declare function processMDX(mdx: string): ProcessMDXResult;
+//# sourceMappingURL=index.d.ts.map