js-bao 0.2.8

package/dist/index.d.ts

@@ -0,0 +1,809 @@
+import * as Y from 'yjs';
+
+interface RefersToRelationshipConfig {
+    type: "refersTo";
+    model: string;
+    relatedIdField: string;
+}
+interface HasManyRelationshipConfig {
+    type: "hasMany";
+    model: string;
+    relatedIdField: string;
+    orderByField?: string;
+    orderDirection?: "ASC" | "DESC";
+}
+interface HasManyThroughRelationshipConfig {
+    type: "hasManyThrough";
+    model: string;
+    joinModel: string;
+    joinModelLocalField: string;
+    joinModelRelatedField: string;
+    joinModelOrderByField?: string;
+    joinModelOrderDirection?: "ASC" | "DESC";
+}
+type RelationshipConfig = RefersToRelationshipConfig | HasManyRelationshipConfig | HasManyThroughRelationshipConfig;
+
+type FieldType = "string" | "number" | "boolean" | "date" | "id" | "stringset";
+interface FieldOptions {
+    type: FieldType;
+    indexed?: boolean;
+    required?: boolean;
+    unique?: boolean;
+    default?: any | (() => any);
+    autoAssign?: boolean;
+    maxLength?: number;
+    maxCount?: number;
+}
+interface UniqueConstraintConfig {
+    name: string;
+    fields: string[];
+}
+interface ModelOptions {
+    name: string;
+    uniqueConstraints?: UniqueConstraintConfig[];
+    relationships?: Record<string, RelationshipConfig>;
+}
+
+type NodeSqliteEngineOptions = {
+    filePath?: string;
+    options?: {
+        readonly?: boolean;
+        fileMustExist?: boolean;
+        timeout?: number;
+        verbose?: (...args: any[]) => void;
+    };
+};
+type DatabaseEngineType = "sqljs" | "node-sqlite" | "alasql";
+interface SqljsEngineOptions {
+    wasmURL?: string;
+    locateFile?: (file: string) => string;
+}
+type DatabaseEngineOptions = SqljsEngineOptions | NodeSqliteEngineOptions | Record<string, any>;
+interface DatabaseConfig {
+    type: DatabaseEngineType;
+    options?: DatabaseEngineOptions;
+}
+
+type DocumentPermissionHint = "read" | "read-write";
+interface ConnectedDocument {
+    docId: string;
+    yDoc: Y.Doc;
+    permissionHint: DocumentPermissionHint;
+}
+interface SaveOptions {
+    targetDocument?: string;
+    forceWrite?: boolean;
+}
+interface DocumentManager {
+    connectDocument(docId: string, yDoc: Y.Doc, permissionHint: DocumentPermissionHint): Promise<void>;
+    disconnectDocument(docId: string): Promise<void>;
+    getConnectedDocuments(): Map<string, ConnectedDocument>;
+    isDocumentConnected(docId: string): boolean;
+}
+interface DocumentConnectionEvent {
+    type: "connect" | "disconnect";
+    docId: string;
+    document?: ConnectedDocument;
+}
+type DocumentConnectionCallback = (event: DocumentConnectionEvent) => void;
+declare class DocumentClosedError extends Error {
+    code: string;
+    constructor(message: string);
+}
+declare class DocumentResolutionError extends Error {
+    code: string;
+    constructor(message: string);
+}
+
+interface ComparisonOperators<T = any> {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: T[];
+    $nin?: T[];
+}
+interface StringSetOperators {
+    /**
+     * Exact membership: StringSet contains this specific string
+     */
+    $contains?: string;
+    $all?: string[];
+    $size?: number | ComparisonOperators<number>;
+}
+interface SubstringOperators {
+    /** Prefix match */
+    $startsWith?: string;
+    /** Suffix match */
+    $endsWith?: string;
+    /** Substring anywhere */
+    $containsText?: string;
+}
+interface ExistenceOperators {
+    $exists?: boolean;
+}
+type FieldOperators<T = any> = ComparisonOperators<T> & ExistenceOperators & StringSetOperators & SubstringOperators;
+interface LogicalOperators {
+    $and?: DocumentFilter[];
+    $or?: DocumentFilter[];
+}
+type DocumentFilter = {
+    [field: string]: any | FieldOperators<any>;
+} & LogicalOperators;
+type SortDirection = 1 | -1;
+type SortSpec = {
+    [field: string]: SortDirection;
+};
+type ProjectionSpec = {
+    [field: string]: 1 | 0;
+};
+interface QueryOptions {
+    sort?: SortSpec;
+    projection?: ProjectionSpec;
+    documents?: string | string[];
+    limit?: number;
+    uniqueStartKey?: string;
+    direction?: 1 | -1;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    nextCursor?: string;
+    prevCursor?: string;
+    hasMore: boolean;
+}
+interface TranslatedQuery {
+    sql: string;
+    params: any[];
+    sortFields: string[];
+    sortDirections?: (1 | -1)[];
+}
+type ProjectedResult<T, P extends ProjectionSpec> = {
+    [K in keyof P]: K extends keyof T ? T[K] : never;
+};
+type QueryResult<T, P extends ProjectionSpec | undefined> = P extends ProjectionSpec ? ProjectedResult<T, P> : T;
+
+interface PaginationOptions {
+    limit?: number;
+    afterCursor?: string;
+    beforeCursor?: string;
+    direction?: "forward" | "backward";
+}
+
+interface ITransactionalDatabaseOperations {
+    insert(modelName: string, data: any): Promise<void>;
+    delete(modelName: string, id: string): Promise<void>;
+    query<T extends Record<string, any>>(sql: string, params?: any[]): Promise<T[]>;
+}
+/**
+ * Abstract class defining the interface for database engines.
+ * This allows for different database implementations (e.g., SQL.js, DuckDB) to be used interchangeably.
+ */
+declare abstract class DatabaseEngine {
+    /**
+     * Ensures that the database engine is fully initialized and ready for use.
+     * For WASM-based engines, this might involve loading the WASM module.
+     */
+    abstract ensureReady(): Promise<void>;
+    /**
+     * Executes a SQL query against the database.
+     * @param sql The SQL query string.
+     * @param params Optional array of parameters for prepared statements.
+     * @returns A promise that resolves to an array of query results.
+     */
+    abstract query(sql: string, params?: any[]): Promise<any[]>;
+    /**
+     * Retrieves the last error message from the database engine, if any.
+     * @returns The last error message as a string, or undefined if no error occurred.
+     */
+    abstract getLastErrorMessage(): string | undefined;
+    /**
+     * Retrieves the schema for a given table.
+     * This is useful for understanding table structure, field types, etc.
+     * The exact return type might vary based on the database engine.
+     * @param tableName The name of the table.
+     * @returns A promise that resolves to the table schema information.
+     */
+    abstract getTableSchema(tableName: string): Promise<any>;
+    /**
+     * Destroys the database engine instance and releases any associated resources.
+     * This is crucial for cleanup, especially in testing environments or when the application is shutting down.
+     */
+    abstract destroy(): Promise<void>;
+    createTable(_modelName: string, _schema: Map<string, any>, // Assuming 'any' for field options for now, can be refined
+    _options: ModelOptions): Promise<void>;
+    createStringSetJunctionTable(_modelName: string, _fieldName: string): Promise<void>;
+    insertStringSetValues(_modelName: string, _fieldName: string, _recordId: string, _values: string[]): Promise<void>;
+    removeStringSetValues(_modelName: string, _fieldName: string, _recordId: string, _values: string[]): Promise<void>;
+    insert(_modelName: string, _data: any): Promise<void>;
+    delete(_modelName: string, _id: string): Promise<void>;
+    /**
+     * Deletes all records for a specific document from the given model table.
+     * This is used when disconnecting a document to remove all its data.
+     * @param modelName The name of the model/table
+     * @param docId The document ID to filter by
+     */
+    deleteByDocumentId(_modelName: string, _docId: string): Promise<void>;
+    getTableName(_modelName: string): string;
+    withTransaction<T>(_callback: (operations: ITransactionalDatabaseOperations) => Promise<T>): Promise<T>;
+}
+
+interface StringSetChangeTracker {
+    markStringSetChange(fieldName: string, operation: "add" | "remove" | "clear", value?: string): void;
+}
+declare class StringSet {
+    private _values;
+    private _model;
+    private _fieldName;
+    constructor(model: StringSetChangeTracker, fieldName: string, initialValues?: string[]);
+    /**
+     * Add a string to the set
+     */
+    add(value: string): void;
+    /**
+     * Remove a string from the set
+     */
+    remove(value: string): void;
+    /**
+     * Check if the set contains a string
+     */
+    has(value: string): boolean;
+    /**
+     * Clear all strings from the set
+     */
+    clear(): void;
+    /**
+     * Get the number of strings in the set
+     */
+    get size(): number;
+    /**
+     * Get an iterator of all values
+     */
+    values(): IterableIterator<string>;
+    /**
+     * Make the StringSet iterable
+     */
+    [Symbol.iterator](): IterableIterator<string>;
+    /**
+     * Convert to array
+     */
+    toArray(): string[];
+    /**
+     * Union with another StringSet
+     */
+    union(other: StringSet): StringSet;
+    /**
+     * Intersection with another StringSet
+     */
+    intersection(other: StringSet): StringSet;
+    /**
+     * Difference with another StringSet (values in this set but not in other)
+     */
+    difference(other: StringSet): StringSet;
+    /**
+     * Get the current state including pending changes
+     * This is used internally by the model to determine the current view
+     */
+    _getCurrentState(): Set<string>;
+    /**
+     * Update the internal state (used when loading from Yjs or applying changes)
+     */
+    _updateInternalState(values: string[]): void;
+}
+
+declare class DocumentQueryTranslator {
+    private modelName;
+    private schema;
+    private tableName;
+    private quotedTableName;
+    private fieldSqlCache;
+    constructor(modelName: string, schema: Map<string, FieldOptions>);
+    private getQuotedField;
+    /**
+     * Translate document filter and options to SQL for find operations
+     */
+    translateFind(filter: DocumentFilter, options?: QueryOptions): TranslatedQuery;
+    /**
+     * Translate document filter to SQL for count operations
+     */
+    translateCount(filter: DocumentFilter, options?: Pick<QueryOptions, "documents">): {
+        sql: string;
+        params: any[];
+    };
+    /**
+     * Translate document filter to SQL WHERE clause
+     */
+    private translateFilter;
+    /**
+     * Translate logical operators ($and, $or)
+     */
+    private translateLogicalOperator;
+    /**
+     * Translate field condition to SQL
+     */
+    private translateFieldCondition;
+    /**
+     * Translate field operators to SQL
+     */
+    private translateFieldOperators;
+    /**
+     * Translate individual operator to SQL
+     */
+    private translateOperator;
+    /**
+     * Build SELECT clause based on projection
+     */
+    private buildSelectClause;
+    /**
+     * Build LIMIT clause
+     */
+    private buildLimitClause;
+    /**
+     * Build pagination WHERE clause from cursor
+     */
+    private buildPaginationClause;
+    /**
+     * Validate that field exists in schema
+     */
+    private validateField;
+    /**
+     * Validate projection fields
+     */
+    private validateProjection;
+    /**
+     * Validate operator is supported for field type
+     */
+    private validateOperatorForType;
+    /**
+     * Validate field value matches expected type
+     */
+    private validateFieldValue;
+    /**
+     * Validate array values for $in/$nin operators
+     */
+    private validateArrayValues;
+    /**
+     * Check if value is a primitive (not an object with operators)
+     */
+    private isPrimitiveValue;
+    /**
+     * Get the type of a value for validation
+     */
+    private getValueType;
+    /**
+     * Check if value type is compatible with field type
+     */
+    private isTypeCompatible;
+    /**
+     * Convert value for SQLite compatibility
+     */
+    private convertValueForSQLite;
+    private normalizeDocumentIds;
+    private buildDocumentClause;
+}
+
+interface StringSetMembership {
+    field: string;
+    contains: string;
+}
+type GroupByField = string | StringSetMembership;
+interface AggregationOperation {
+    type: "count" | "sum" | "avg" | "min" | "max";
+    field?: string;
+}
+interface AggregationOptions {
+    groupBy: GroupByField[];
+    operations: AggregationOperation[];
+    filter?: DocumentFilter;
+    limit?: number;
+    sort?: {
+        field: string;
+        direction: 1 | -1;
+    };
+}
+type AggregationResult = Record<string, any> | Record<string, any>[];
+interface AggregationAliasDebugInfo {
+    field: string;
+    contains: string;
+    originalAlias: string;
+}
+interface AggregationAliasDetail extends AggregationAliasDebugInfo {
+    alias: string;
+    membershipKey: string;
+}
+interface AggregationQueryPlan {
+    sql: string;
+    params: any[];
+    aliasMetadata?: AggregationAliasDetail[];
+}
+declare enum LogLevel {
+    SILENT = 0,
+    ERROR = 1,
+    WARN = 2,
+    INFO = 3,
+    DEBUG = 4,
+    VERBOSE = 5
+}
+declare class Logger {
+    private static _logLevel;
+    private static _logCallback;
+    static setLogLevel(level: LogLevel): void;
+    static getLogLevel(): LogLevel;
+    static setLogCallback(callback: ((message: string, level: LogLevel) => void) | null): void;
+    static error(message: string, ...args: any[]): void;
+    static warn(message: string, ...args: any[]): void;
+    static info(message: string, ...args: any[]): void;
+    static debug(message: string, ...args: any[]): void;
+    static verbose(message: string, ...args: any[]): void;
+}
+declare class UniqueConstraintViolationError extends Error {
+    modelName: string;
+    constraintName: string;
+    fields: string[];
+    recordIdAttempted?: string;
+    conflictingRecordId?: string;
+    constructor(message: string, modelName: string, constraintName: string, fields: string[], recordIdAttempted?: string, conflictingRecordId?: string);
+}
+declare class RecordNotFoundError extends Error {
+    constructor(message: string);
+}
+declare function generateULID(): string;
+declare class BaseModel implements StringSetChangeTracker {
+    static modelName?: string;
+    private static listenersMap;
+    private static modelNameToDefaultDocId;
+    private static globalDefaultDocId;
+    private static defaultDocChangedListeners;
+    private static modelDocMappingChangedListeners;
+    private static readonly DEFAULT_LEGACY_DOC_ID;
+    protected static dbInstance: DatabaseEngine | null;
+    protected static connectedDocuments: Map<string, {
+        yDoc: Y.Doc;
+        permissionHint: DocumentPermissionHint;
+    }>;
+    protected static documentYMaps: Map<string, Y.Map<any>>;
+    private _localChanges;
+    private _isDirty;
+    private _isLoadingFromYjs;
+    private _stringSetFields;
+    private _metaDocId;
+    private _metaPermissionHint;
+    /**
+     * Returns the document id this instance is associated with, or null if not resolved yet.
+     */
+    getDocumentId(): string | null;
+    id: string;
+    type: string;
+    static setLogLevel(level: LogLevel): void;
+    static getLogLevel(): LogLevel;
+    static setModelDefaultDocumentId(modelName: string, docId: string): void;
+    static removeModelDefaultDocumentId(modelName: string): void;
+    static clearModelDefaultDocumentIds(): void;
+    static setGlobalDefaultDocumentId(docId: string): void;
+    static clearGlobalDefaultDocumentId(): void;
+    static getModelDefaultDocumentMapping(): Record<string, string>;
+    static getDocumentIdForModel(modelName: string): string | undefined;
+    static getGlobalDefaultDocumentId(): string | undefined;
+    static onDefaultDocChanged(listener: (payload: {
+        previous?: string;
+        current?: string;
+    }) => void): () => void;
+    static onModelDocMappingChanged(listener: (payload: {
+        modelName: string;
+        previous?: string;
+        current?: string;
+    }) => void): () => void;
+    static _clearMappingsForDocId(docId: string): void;
+    private static attachFieldAccessorsSet;
+    static attachFieldAccessors(modelClass: typeof BaseModel, fields: Map<string, FieldOptions>): void;
+    constructor(data?: Partial<any>);
+    private ensureLocalChanges;
+    private hasLocalChange;
+    private getFromYjs;
+    private getValue;
+    private setValue;
+    get isDirty(): boolean;
+    get hasUnsavedChanges(): boolean;
+    private clearLocalChanges;
+    discardChanges(): void;
+    protected validateFieldValue(fieldKey: string, value: any): void;
+    protected validateBeforeSave(): void;
+    getChangedFields(): string[];
+    getOriginalValue(fieldKey: string): any;
+    getCurrentValue(fieldKey: string): any;
+    hasFieldChanged(fieldKey: string): boolean;
+    markStringSetChange(fieldName: string, operation: "add" | "remove" | "clear", value?: string): void;
+    private getStringSetCurrentValues;
+    private getStringSetFromYjs;
+    private getOrCreateStringSet;
+    static initialize(_yDoc: Y.Doc, _db: DatabaseEngine): Promise<void>;
+    static initializeForDocument(yDoc: Y.Doc, db: DatabaseEngine, docId: string, permissionHint: DocumentPermissionHint): Promise<void>;
+    static cleanupDocumentData(docId: string): Promise<void>;
+    static subscribe(callback: () => void): () => void;
+    protected static notifyListeners(): void;
+    /**
+     * Legacy migration method - no longer needed in the new multidoc architecture.
+     * Data migration is now handled during document initialization.
+     */
+    static migrateToNestedYMaps(): Promise<void>;
+    /**
+     * Utility to diff current instance data against YJS nested map data
+     * Returns object with added, modified, and removed fields
+     */
+    protected _diffWithYjsData(): {
+        added: Record<string, any>;
+        modified: Record<string, any>;
+        removed: string[];
+    };
+    /**
+     * Deep equality check for comparing field values
+     */
+    protected _deepEqual(a: any, b: any): boolean;
+    protected static _buildKeyFromValues(fields: string[], keyValues: any[], modelName: string, constraintName: string): string | null;
+    protected _buildUniqueKey(fields: string[], data: Record<string, any>, modelName: string, constraintName: string): string | null;
+    save(options?: SaveOptions): Promise<void>;
+    delete(): Promise<void>;
+    protected getCurrentJSState(): Record<string, any>;
+    protected toJSON(): Record<string, any>;
+    static find<T extends BaseModel>(this: new (...args: any[]) => T, id: string): Promise<T | null>;
+    /**
+     * Document-style query API - returns paginated results
+     */
+    static query<T extends BaseModel, P extends ProjectionSpec | undefined = undefined>(this: new (...args: any[]) => T, filter?: DocumentFilter, options?: QueryOptions & {
+        projection?: P;
+    }): Promise<PaginatedResult<QueryResult<T, P>>>;
+    /**
+     * Main aggregation API - performs grouping, faceting, and statistical operations
+     * @param options Aggregation configuration with groupBy, operations, filter, limit, and sort
+     * @returns Nested object structure with aggregation results
+     *
+     * @example
+     * // Simple facet count
+     * const tagCounts = await Model.aggregate({
+     *   groupBy: ['tags'],
+     *   operations: [{ type: 'count' }]
+     * });
+     * // Result: { red: 15, blue: 8, green: 12 }
+     *
+     * @example
+     * // Multi-dimensional grouping with multiple operations
+     * const categoryStats = await Model.aggregate({
+     *   groupBy: ['category', 'status'],
+     *   operations: [
+     *     { type: 'count' },
+     *     { type: 'sum', field: 'amount' },
+     *     { type: 'avg', field: 'score' }
+     *   ],
+     *   filter: { active: true },
+     *   sort: { field: 'count', direction: 'desc' },
+     *   limit: 10
+     * });
+     *
+     * @example
+     * // StringSet membership grouping
+     * const urgentCounts = await Model.aggregate({
+     *   groupBy: [{ field: 'tags', contains: 'urgent' }],
+     *   operations: [{ type: 'count' }]
+     * });
+     * // Result: { true: 5, false: 23 }
+     */
+    static aggregate<T extends BaseModel>(this: new (...args: any[]) => T, options: AggregationOptions): Promise<AggregationResult>;
+    /**
+     * Build SQL query for structured aggregation
+     */
+    protected static buildAggregationQuery(options: AggregationOptions, schema: any, modelName: string): AggregationQueryPlan;
+    /**
+     * Get the proper database table name (should match database engine naming)
+     */
+    protected static getDatabaseTableName(modelName: string): string;
+    /**
+     * Get the proper database junction table name for StringSet fields
+     */
+    protected static getDatabaseJunctionTableName(modelName: string, fieldName: string): string;
+    private static buildMembershipKey;
+    /**
+     * Build query for StringSet facet counts
+     */
+    protected static buildStringSetFacetQuery(stringSetFields: string[], options: AggregationOptions, translator: DocumentQueryTranslator, modelName: string): AggregationQueryPlan;
+    /**
+     * Build query for regular field aggregation
+     */
+    protected static buildRegularAggregationQuery(regularGroupBy: string[], stringSetMemberships: StringSetMembership[], options: AggregationOptions, translator: DocumentQueryTranslator, modelName: string): AggregationQueryPlan;
+    /**
+     * Process aggregation results into nested structure
+     */
+    protected static processAggregationResults(results: any[], options: AggregationOptions, aliasMetadata?: AggregationAliasDetail[]): AggregationResult;
+    /**
+     * Document-style query API - returns single result or null
+     */
+    static queryOne<T extends BaseModel, P extends ProjectionSpec | undefined = undefined>(this: new (...args: any[]) => T, filter?: DocumentFilter, options?: Omit<QueryOptions, "limit" | "uniqueStartKey" | "direction"> & {
+        projection?: P;
+    }): Promise<QueryResult<T, P> | null>;
+    /**
+     * Document-style count API
+     */
+    static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
+    static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
+    static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
+        id?: string;
+    }, options?: {
+        objectMustExist?: boolean;
+        objectMustNotExist?: boolean;
+        targetDocument?: string;
+    }): Promise<T>;
+    /**
+     * Execute a callback with automatic transaction handling for all modified models
+     */
+    static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Sets up deep observation on a nested YMap to sync field-level changes to the database
+     */
+    protected static setupNestedYMapObserver(recordId: string, recordYMap: Y.Map<any>): void;
+    /**
+     * Sets up deep observation on a nested YMap for a specific document to sync field-level changes to the database
+     */
+    protected static setupNestedYMapObserverForDocument(recordId: string, recordYMap: Y.Map<any>, docId: string, permissionHint: DocumentPermissionHint): void;
+}
+
+interface RegisteredModelInfo {
+    class: typeof BaseModel;
+    options: ModelOptions;
+    fields: Map<string, FieldOptions>;
+}
+declare class ModelRegistry {
+    private static instance;
+    private models;
+    private modelOptions;
+    private activeSessionModels;
+    private dbEngine;
+    private constructor();
+    static getInstance(): ModelRegistry;
+    registerModel(modelClass: any, options: ModelOptions, fields: Map<string, FieldOptions>): void;
+    getModelClass(name: string): typeof BaseModel | undefined;
+    getModelOptions(name: string): ModelOptions | undefined;
+    getModelInfo(modelName: string): RegisteredModelInfo | undefined;
+    getAllRegisteredModelsInfo(): RegisteredModelInfo[];
+    private getModelNameFromClass;
+    setExplicitModelsForSession(modelClasses?: (typeof BaseModel)[]): void;
+    initializeAll(yDoc: Y.Doc, dbEngine: DatabaseEngine): Promise<void>;
+    initializeAllForDocument(yDoc: Y.Doc, dbEngine: DatabaseEngine, docId: string, permissionHint: DocumentPermissionHint): Promise<void>;
+    removeDocumentData(docId: string, dbEngine: DatabaseEngine): Promise<void>;
+    initializeRelationships(): Promise<void>;
+    private addPrototypeMethod;
+    clearSessionState(): void;
+    getActiveModels(): Map<string, typeof BaseModel>;
+    private validateSessionModels;
+}
+
+interface InitJsBaoOptions {
+    databaseConfig: DatabaseConfig;
+    /**
+     * Optional array of model classes to initialize.
+     * If not provided, the ORM will rely on models being registered
+     * via the @Model decorator (assuming they have been imported by the application).
+     */
+    models?: (typeof BaseModel)[];
+}
+interface InitJsBaoResult {
+    dbEngine: DatabaseEngine;
+    modelRegistry: ModelRegistry;
+    connectDocument: (docId: string, yDoc: Y.Doc, permissionHint: DocumentPermissionHint) => Promise<void>;
+    disconnectDocument: (docId: string) => Promise<void>;
+    getConnectedDocuments: () => Map<string, ConnectedDocument>;
+    isDocumentConnected: (docId: string) => boolean;
+    onDocumentConnectionChange: (callback: DocumentConnectionCallback) => () => void;
+    addDocumentModelMapping: (modelName: string, docId: string) => void;
+    removeDocumentModelMapping: (modelName: string) => void;
+    clearDocumentModelMappings: () => void;
+    setDefaultDocumentId: (docId: string) => void;
+    clearDefaultDocumentId: () => void;
+    getDocumentModelMapping: () => Record<string, string>;
+    getDocumentIdForModel: (modelName: string) => string | undefined;
+    getDefaultDocumentId: () => string | undefined;
+    onDefaultDocChanged: (listener: (payload: {
+        previous?: string;
+        current?: string;
+    }) => void) => () => void;
+    onModelDocMappingChanged: (listener: (payload: {
+        modelName: string;
+        previous?: string;
+        current?: string;
+    }) => void) => () => void;
+}
+/**
+ * Initializes the js-bao system with multi-document support.
+ * Sets up the database engine and prepares for document connections.
+ */
+declare function initJsBao(options: InitJsBaoOptions): Promise<InitJsBaoResult>;
+/**
+ * Function to reset the initialization state, primarily for testing or hot-reloading scenarios.
+ */
+declare function resetJsBao(): Promise<void>;
+
+declare function Field(options: FieldOptions): (target: any, propertyKey: string | symbol) => void;
+declare function Model(options: ModelOptions): (targetClass: Function) => void;
+
+interface ResolvedUniqueConstraint {
+    name: string;
+    fields: string[];
+}
+interface ModelSchemaRuntimeShape {
+    class: typeof BaseModel;
+    options: ModelOptions;
+    fields: Map<string, FieldOptions>;
+    resolvedUniqueConstraints: ResolvedUniqueConstraint[];
+}
+interface DefineModelSchemaInput<TFields extends Record<string, FieldOptions>> {
+    name: string;
+    fields: TFields;
+    options?: Omit<ModelOptions, "name">;
+}
+interface DefinedModelSchema<TFields extends Record<string, FieldOptions> = Record<string, FieldOptions>> {
+    name: string;
+    fields: TFields;
+    options: ModelOptions;
+    runtimeShape?: ModelSchemaRuntimeShape;
+    buildRuntimeShape(modelClass: typeof BaseModel): ModelSchemaRuntimeShape;
+}
+declare function defineModelSchema<TFields extends Record<string, FieldOptions>>(input: DefineModelSchemaInput<TFields>): DefinedModelSchema<TFields>;
+type FieldValue<FO extends FieldOptions> = FO["type"] extends "string" ? string : FO["type"] extends "number" ? number : FO["type"] extends "boolean" ? boolean : FO["type"] extends "date" ? string : FO["type"] extends "id" ? string : FO["type"] extends "stringset" ? StringSet : unknown;
+type InferAttrs<TSchema extends DefinedModelSchema<any>> = {
+    [K in keyof TSchema["fields"]]: FieldValue<TSchema["fields"][K]>;
+};
+interface CreateModelClassConfig<TSchema extends DefinedModelSchema<any>, TAttrs extends Record<string, any> = InferAttrs<TSchema>> {
+    schema: TSchema;
+    baseClass?: typeof BaseModel;
+    methods?: () => Record<string | symbol, any>;
+    statics?: (ctor: ModelConstructor<TAttrs>) => Record<string | symbol, any>;
+}
+type ModelConstructor<TAttrs extends Record<string, any>> = typeof BaseModel & {
+    prototype: BaseModel & TAttrs;
+    new (attrs?: Partial<TAttrs>): BaseModel & TAttrs;
+};
+/**
+ * @deprecated Use defineModelSchema + class + attachAndRegisterModel instead.
+ */
+declare function createModelClass<TSchema extends DefinedModelSchema<any>, TAttrs extends Record<string, any> = InferAttrs<TSchema>>(config: CreateModelClassConfig<TSchema, TAttrs>): ModelConstructor<TAttrs>;
+declare function attachSchemaToClass(modelClass: typeof BaseModel, schema: DefinedModelSchema<any>): ModelSchemaRuntimeShape;
+declare function autoRegisterModel(modelClass: typeof BaseModel, runtimeShape?: ModelSchemaRuntimeShape): void;
+declare function attachAndRegisterModel(modelClass: typeof BaseModel, schema: DefinedModelSchema<any>): void;
+
+interface DumpOptions {
+    includeIndexes?: boolean;
+}
+type PlainYDoc = Record<string, Record<string, any>>;
+interface DumpSummaryEntry {
+    count: number;
+    approxBytes: number;
+}
+interface DumpSummary {
+    models: Record<string, DumpSummaryEntry>;
+    totalCount: number;
+    totalApproxBytes: number;
+}
+/**
+ * Dumps a js-bao-shaped Y.Doc into a plain object:
+ * {
+ *   [modelName]: {
+ *     [recordId]: { ...fields },
+ *     ...
+ *   },
+ *   ...
+ * }
+ *
+ * - By default ignores internal unique-index maps (`_uniqueIdx_*`); pass
+ *   `{ includeIndexes: true }` to include them.
+ * - Converts each record's nested Y.Map to a plain object.
+ * - Leaves StringSet fields as the stored `{ value: true }` map.
+ */
+declare function dumpYDocToPlain(yDoc: Y.Doc, options?: DumpOptions): PlainYDoc;
+/**
+ * Creates a compact summary from a PlainYDoc:
+ * - count of records per model
+ * - approximate byte size per model (JSON string length, UTF-8)
+ */
+declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
+
+export { BaseModel, type ConnectedDocument, type DatabaseConfig, DatabaseEngine, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, Field, type FieldOptions, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, Model, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, type SaveOptions, StringSet, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, createModelClass, defineModelSchema, dumpYDocToPlain, generateULID, initJsBao, resetJsBao, summarizePlainYDoc };