js-bao 0.2.10 → 0.3.0-alpha.0

package/dist/client.d.cts

@@ -0,0 +1,1084 @@
+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>;
+}
+
+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;
+}
+
+type DocumentPermissionHint = "read" | "read-write";
+interface SaveOptions$1 {
+    targetDocument?: string;
+    forceWrite?: boolean;
+}
+
+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;
+
+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$1 {
+    field: string;
+    contains: string;
+}
+type GroupByField$1 = string | StringSetMembership$1;
+interface AggregationOperation$1 {
+    type: "count" | "sum" | "avg" | "min" | "max";
+    field?: string;
+}
+interface AggregationOptions$1 {
+    groupBy: GroupByField$1[];
+    operations: AggregationOperation$1[];
+    filter?: DocumentFilter;
+    limit?: number;
+    sort?: {
+        field: string;
+        direction: 1 | -1;
+    };
+}
+type AggregationResult$1 = 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 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$1): 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$1): Promise<AggregationResult$1>;
+    /**
+     * Build SQL query for structured aggregation
+     */
+    protected static buildAggregationQuery(options: AggregationOptions$1, 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$1, translator: DocumentQueryTranslator, modelName: string): AggregationQueryPlan;
+    /**
+     * Build query for regular field aggregation
+     */
+    protected static buildRegularAggregationQuery(regularGroupBy: string[], stringSetMemberships: StringSetMembership$1[], options: AggregationOptions$1, translator: DocumentQueryTranslator, modelName: string): AggregationQueryPlan;
+    /**
+     * Process aggregation results into nested structure
+     */
+    protected static processAggregationResults(results: any[], options: AggregationOptions$1, aliasMetadata?: AggregationAliasDetail[]): AggregationResult$1;
+    /**
+     * 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;
+}
+
+/**
+ * Durable Object Engine
+ *
+ * Database engine implementation that runs inside a Cloudflare Durable Object.
+ * Uses the DO's embedded SQLite database via ctx.storage.sql.
+ *
+ * Key characteristics:
+ * - Synchronous SQL execution (DO SQLite is sync)
+ * - No doc ID column needed (one DO = one document)
+ * - Uses JSON schema (records + stringset_index tables)
+ * - Schemaless: any model/field can be saved and queried without registration
+ * - Indexes are additive: register/drop individual field indexes independently
+ */
+
+/** Row shape from the _indexes table */
+interface IndexEntry {
+    model_name: string;
+    field_name: string;
+    field_type: string;
+    is_unique: number;
+    created_at: string;
+}
+/** Row shape from the _unique_constraints table */
+interface UniqueConstraintEntry {
+    model_name: string;
+    constraint_name: string;
+    fields: string[];
+    created_at: string;
+}
+/** Row shape from the _model_fields table */
+interface ModelFieldInfo {
+    model_name: string;
+    field_name: string;
+    inferred_type: string;
+    first_seen_at: string;
+}
+
+/**
+ * Aggregation types shared between Yjs and DO backends.
+ */
+
+/**
+ * Describes a StringSet membership check in a groupBy clause.
+ * Groups records by whether they have a specific value in a StringSet field.
+ */
+interface StringSetMembership {
+    field: string;
+    contains: string;
+}
+/**
+ * A groupBy field can be a plain field name or a StringSet membership check.
+ */
+type GroupByField = string | StringSetMembership;
+/**
+ * An aggregation operation (count, sum, avg, min, max).
+ */
+interface AggregationOperation {
+    type: "count" | "sum" | "avg" | "min" | "max";
+    /** Required for sum, avg, min, max; not used for count */
+    field?: string;
+}
+/**
+ * Options for an aggregation query.
+ */
+interface AggregationOptions {
+    groupBy: GroupByField[];
+    operations: AggregationOperation[];
+    filter?: DocumentFilter;
+    limit?: number;
+    sort?: {
+        /** Can be operation result field like 'count', 'sum_fieldName', etc. */
+        field: string;
+        /** 1 for ascending, -1 for descending */
+        direction: 1 | -1;
+    };
+}
+/**
+ * Result of an aggregation query — nested object keyed by group values.
+ */
+type AggregationResult = Record<string, any> | Record<string, any>[];
+
+/**
+ * Database Durable Object Factory
+ *
+ * Creates a Durable Object class that serves as a schemaless database store.
+ * Each DO instance has its own SQLite database.
+ *
+ * Usage:
+ * ```typescript
+ * import { createDatabaseDO } from 'js-bao/cloudflare/do';
+ *
+ * export const MyDatabaseDO = createDatabaseDO({
+ *   hooks: {
+ *     beforeSave: async (ctx) => {
+ *       // Access control logic
+ *       return { allow: true };
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Request body types for RPC endpoints
+ */
+interface QueryRequest {
+    modelName: string;
+    filter: DocumentFilter;
+    options?: QueryOptions;
+}
+interface SaveRequest {
+    modelName: string;
+    id: string;
+    data: Record<string, any>;
+    stringSets?: Record<string, string[]>;
+    ifNotExists?: boolean;
+    condition?: DocumentFilter;
+}
+interface DeleteRequest {
+    modelName: string;
+    id: string;
+    condition?: DocumentFilter;
+}
+interface CountRequest {
+    modelName: string;
+    filter: DocumentFilter;
+}
+/**
+ * Response types
+ */
+interface QueryResponse {
+    data: Record<string, any>[];
+    hasMore?: boolean;
+    nextCursor?: string;
+    prevCursor?: string;
+}
+interface SaveResponse {
+    success: boolean;
+    id: string;
+}
+interface DeleteResponse {
+    success: boolean;
+}
+interface CountResponse {
+    count: number;
+}
+interface ErrorResponse {
+    error: string;
+    code?: string;
+}
+interface AggregateRequest {
+    modelName: string;
+    options: AggregationOptions;
+}
+interface AggregateResponse {
+    result: AggregationResult;
+}
+interface SyncIndexesRequest {
+    models: Array<{
+        modelName: string;
+        indexes: Array<{
+            fieldName: string;
+            fieldType: string;
+            unique: boolean;
+        }>;
+        uniqueConstraints: Array<{
+            name: string;
+            fields: string[];
+        }>;
+    }>;
+}
+interface SyncIndexesResponse {
+    registered: number;
+}
+interface PatchRequest {
+    modelName: string;
+    id: string;
+    data: Record<string, any>;
+    stringSets?: Record<string, string[]>;
+    condition?: DocumentFilter;
+}
+interface PatchResponse {
+    success: boolean;
+    id: string;
+}
+interface BatchOperation {
+    op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
+    modelName: string;
+    id: string;
+    data?: Record<string, any>;
+    stringSets?: Record<string, string[]>;
+    fields?: Record<string, number>;
+    ifNotExists?: boolean;
+    condition?: DocumentFilter;
+}
+interface BatchRequest {
+    operations: BatchOperation[];
+}
+interface BatchOperationResult {
+    success: boolean;
+    id: string;
+    error?: string;
+    values?: Record<string, number>;
+}
+interface BatchResponse {
+    results: BatchOperationResult[];
+}
+interface IncrementRequest {
+    modelName: string;
+    id: string;
+    fields: Record<string, number>;
+    condition?: DocumentFilter;
+}
+interface IncrementResponse {
+    success: boolean;
+    id: string;
+    values: Record<string, number>;
+}
+interface StringSetUpdateRequest {
+    modelName: string;
+    id: string;
+    sets: Record<string, string[]>;
+    condition?: DocumentFilter;
+}
+interface StringSetUpdateResponse {
+    success: boolean;
+}
+interface DescribeResponse {
+    modelName: string;
+    fields: ModelFieldInfo[];
+}
+
+/**
+ * Durable Object Client Engine
+ *
+ * Client-side engine that proxies database operations to a Cloudflare
+ * Durable Object via HTTP fetch calls.
+ *
+ * This engine runs in the browser or Node.js and communicates with
+ * the DO-based backend.
+ */
+
+interface DOClientEngineConfig {
+    /**
+     * Base URL of the Cloudflare Worker
+     * e.g., "https://my-worker.my-subdomain.workers.dev"
+     */
+    endpoint: string;
+    /**
+     * Optional custom fetch function (useful for testing)
+     */
+    fetch?: typeof fetch;
+    /**
+     * Optional authorization header value
+     */
+    authorization?: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+}
+declare class DOClientEngine extends DatabaseEngine {
+    private endpoint;
+    private customFetch;
+    private authorization?;
+    private timeout;
+    private currentDocId;
+    constructor(config: DOClientEngineConfig);
+    /**
+     * Set the current document ID for subsequent operations.
+     */
+    setCurrentDocument(docId: string): void;
+    /**
+     * Get the current document ID.
+     */
+    getCurrentDocument(): string | null;
+    /**
+     * Build the URL for a DO endpoint.
+     */
+    private buildUrl;
+    /**
+     * Make a fetch request to the DO.
+     */
+    private doFetch;
+    /**
+     * Query records from the DO.
+     */
+    queryModel(modelName: string, filter?: DocumentFilter, options?: QueryOptions): Promise<PaginatedResult<Record<string, any>>>;
+    /**
+     * Save a record to the DO.
+     */
+    saveModel(modelName: string, id: string, data: Record<string, any>, stringSets?: Record<string, string[]>, options?: {
+        ifNotExists?: boolean;
+        condition?: DocumentFilter;
+    }): Promise<string>;
+    /**
+     * Patch (partial update) a record in the DO.
+     * Only the provided fields are updated; existing fields are preserved.
+     */
+    patchModel(modelName: string, id: string, data: Record<string, any>, stringSets?: Record<string, string[]>, options?: {
+        condition?: DocumentFilter;
+    }): Promise<string>;
+    /**
+     * Delete a record from the DO.
+     */
+    deleteModel(modelName: string, id: string, options?: {
+        condition?: DocumentFilter;
+    }): Promise<boolean>;
+    /**
+     * Count records matching a filter.
+     */
+    countModel(modelName: string, filter?: DocumentFilter): Promise<number>;
+    /**
+     * Aggregate records with groupBy and operations (count, sum, avg, min, max).
+     */
+    aggregateModel(modelName: string, options: AggregationOptions): Promise<AggregationResult>;
+    /**
+     * Atomically add values to StringSet fields on a record.
+     */
+    addToStringSet(modelName: string, id: string, sets: Record<string, string[]>, options?: {
+        condition?: DocumentFilter;
+    }): Promise<void>;
+    /**
+     * Atomically remove values from StringSet fields on a record.
+     */
+    removeFromStringSet(modelName: string, id: string, sets: Record<string, string[]>, options?: {
+        condition?: DocumentFilter;
+    }): Promise<void>;
+    /**
+     * Atomically increment/decrement numeric fields on a record.
+     * Returns the new values after the increment.
+     */
+    incrementFields(modelName: string, id: string, fields: Record<string, number>, options?: {
+        condition?: DocumentFilter;
+    }): Promise<Record<string, number>>;
+    /**
+     * Execute multiple save/patch/delete operations in a single request.
+     * All operations run in a single transaction on the server.
+     */
+    batchWrite(operations: BatchOperation[]): Promise<BatchOperationResult[]>;
+    /**
+     * Check if the DO is healthy.
+     */
+    healthCheck(): Promise<{
+        status: string;
+    }>;
+    /**
+     * Batch sync indexes: send all desired indexes in one request.
+     * The DO compares against its _indexes table and registers only what's missing.
+     * Returns the number of indexes/constraints newly registered.
+     */
+    syncIndexesBatch(request: SyncIndexesRequest): Promise<number>;
+    /**
+     * Register an index on a model field.
+     * Creates a SQLite index on json_extract(data_json, '$.fieldName').
+     * Set unique=true to enforce uniqueness on this field.
+     */
+    registerIndex(modelName: string, fieldName: string, fieldType?: string, unique?: boolean): Promise<void>;
+    /**
+     * Drop an index from a model field.
+     */
+    dropIndex(modelName: string, fieldName: string): Promise<void>;
+    /**
+     * List indexes, optionally filtered by model name.
+     */
+    listIndexes(modelName?: string): Promise<IndexEntry[]>;
+    /**
+     * Describe tracked fields for a model.
+     */
+    describe(modelName: string): Promise<ModelFieldInfo[]>;
+    /**
+     * Register a composite unique constraint across multiple fields.
+     */
+    registerUniqueConstraint(modelName: string, constraintName: string, fields: string[]): Promise<void>;
+    /**
+     * Drop a composite unique constraint.
+     */
+    dropUniqueConstraint(modelName: string, constraintName: string): Promise<void>;
+    /**
+     * List composite unique constraints, optionally filtered by model name.
+     */
+    listUniqueConstraints(modelName?: string): Promise<UniqueConstraintEntry[]>;
+    /**
+     * Ensure the engine is ready.
+     * For DOClient, this verifies connectivity.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Execute raw SQL.
+     * Not supported in DO client mode - use queryModel instead.
+     */
+    query(_sql: string, _params?: any[]): Promise<any[]>;
+    /**
+     * Get last error message.
+     */
+    getLastErrorMessage(): string | undefined;
+    /**
+     * Get table schema.
+     * Not directly supported - schema is managed by the DO.
+     */
+    getTableSchema(_tableName: string): Promise<any>;
+    /**
+     * Destroy the engine.
+     * Nothing to clean up for the client.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Create table.
+     * No-op in DO client mode - schema is managed by the DO.
+     */
+    createTable(_modelName: string, _schema: Map<string, FieldOptions>, _options: ModelOptions): Promise<void>;
+    /**
+     * Create StringSet junction table.
+     * No-op in DO client mode.
+     */
+    createStringSetJunctionTable(_modelName: string, _fieldName: string): Promise<void>;
+    /**
+     * Insert a record.
+     * Delegates to saveModel.
+     */
+    insert(modelName: string, data: any): Promise<void>;
+    /**
+     * Delete a record.
+     * Delegates to deleteModel.
+     */
+    delete(modelName: string, id: string): Promise<void>;
+    /**
+     * Get table name.
+     * All models use 'records' in JSON schema.
+     */
+    getTableName(_modelName: string): string;
+    /**
+     * Transaction support.
+     * DO client doesn't support client-side transactions.
+     * Operations are atomic on the DO side.
+     */
+    withTransaction<T>(callback: (operations: ITransactionalDatabaseOperations) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Durable Object Mode Initialization
+ *
+ * Alternative initialization for js-bao that uses Cloudflare Durable Objects
+ * instead of yjs for document storage.
+ *
+ * Key differences from yjs mode:
+ * - No yjs dependency
+ * - Server-authoritative (DO is source of truth)
+ * - HTTP-based communication with DO backend
+ * - One DO per document
+ * - Schemaless: any field can be saved/queried without registration
+ * - Only indexes need explicit registration for performance
+ */
+
+/**
+ * A model can be identified by either a BaseModel subclass or a plain string name.
+ * Use a string when you don't have a model class (e.g., schemaless / CSV import).
+ */
+type ModelIdentifier = typeof BaseModel | string;
+/**
+ * Configuration for connectDoDb
+ */
+interface ConnectDoDbOptions {
+    /** Base URL of the Cloudflare Worker */
+    endpoint: string;
+    /** Document ID to connect to */
+    id: string;
+    /** Model classes to create pre-bound accessors for */
+    models?: (typeof BaseModel)[];
+    /** Optional authorization header value */
+    authorization?: string;
+    /** Optional custom fetch function (for testing) */
+    fetch?: typeof fetch;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Pre-bound model accessor — all methods are scoped to a specific model.
+ */
+interface SaveOptions {
+    stringSets?: Record<string, string[]>;
+    ifNotExists?: boolean;
+    condition?: DocumentFilter;
+}
+interface PatchOptions {
+    stringSets?: Record<string, string[]>;
+    condition?: DocumentFilter;
+}
+interface WriteCondition {
+    condition?: DocumentFilter;
+}
+interface ModelAccessor {
+    query<T extends Record<string, any> = Record<string, any>>(filter?: DocumentFilter, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    find<T extends Record<string, any> = Record<string, any>>(id: string): Promise<T | null>;
+    save(data: Record<string, any>, options?: SaveOptions | Record<string, string[]>): Promise<string>;
+    patch(id: string, data: Record<string, any>, options?: PatchOptions | Record<string, string[]>): Promise<string>;
+    delete(id: string, options?: WriteCondition): Promise<boolean>;
+    count(filter?: DocumentFilter): Promise<number>;
+    aggregate(options: AggregationOptions): Promise<AggregationResult>;
+    increment(id: string, fields: Record<string, number>, options?: WriteCondition): Promise<Record<string, number>>;
+    addToSet(id: string, sets: Record<string, string[]>, options?: WriteCondition): Promise<void>;
+    removeFromSet(id: string, sets: Record<string, string[]>, options?: WriteCondition): Promise<void>;
+}
+/**
+ * Result of connectDoDb — provides both ad-hoc and pre-bound model access.
+ *
+ * Ad-hoc: `db.query(User, filter)` — works with any model class.
+ * Pre-bound: `db.User.query(filter)` — only for models passed in `models` array.
+ */
+interface DoDb {
+    /** The underlying DO client engine */
+    readonly engine: DOClientEngine;
+    /** The connected document ID */
+    readonly docId: string;
+    query<T extends Record<string, any> = Record<string, any>>(model: ModelIdentifier, filter?: DocumentFilter, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    find<T extends Record<string, any> = Record<string, any>>(model: ModelIdentifier, id: string): Promise<T | null>;
+    save(model: ModelIdentifier, data: Record<string, any>, options?: SaveOptions | Record<string, string[]>): Promise<string>;
+    patch(model: ModelIdentifier, id: string, data: Record<string, any>, options?: PatchOptions | Record<string, string[]>): Promise<string>;
+    delete(model: ModelIdentifier, id: string, options?: WriteCondition): Promise<boolean>;
+    count(model: ModelIdentifier, filter?: DocumentFilter): Promise<number>;
+    aggregate(model: ModelIdentifier, options: AggregationOptions): Promise<AggregationResult>;
+    increment(model: ModelIdentifier, id: string, fields: Record<string, number>, options?: WriteCondition): Promise<Record<string, number>>;
+    addToSet(model: ModelIdentifier, id: string, sets: Record<string, string[]>, options?: WriteCondition): Promise<void>;
+    removeFromSet(model: ModelIdentifier, id: string, sets: Record<string, string[]>, options?: WriteCondition): Promise<void>;
+    batch(operations: BatchOperation[]): Promise<BatchOperationResult[]>;
+    describe(modelName: string): Promise<ModelFieldInfo[]>;
+    registerIndex(modelName: string, fieldName: string, fieldType?: string, unique?: boolean): Promise<void>;
+    dropIndex(modelName: string, fieldName: string): Promise<void>;
+    listIndexes(modelName?: string): Promise<IndexEntry[]>;
+    registerUniqueConstraint(modelName: string, constraintName: string, fields: string[]): Promise<void>;
+    dropUniqueConstraint(modelName: string, constraintName: string): Promise<void>;
+    listUniqueConstraints(modelName?: string): Promise<UniqueConstraintEntry[]>;
+    syncIndexes(modelClass: typeof BaseModel): Promise<number>;
+    /**
+     * Sync indexes for all models passed in the `models` array at init.
+     * Returns total number of indexes/constraints newly registered.
+     */
+    syncAllIndexes(): Promise<number>;
+    [modelName: string]: any;
+}
+/**
+ * Connect to a Durable Object document database.
+ *
+ * Combines initialization and document connection into a single call.
+ * Returns an object with both ad-hoc and pre-bound model access.
+ *
+ * Usage:
+ * ```typescript
+ * import { connectDoDb } from 'js-bao/cloudflare';
+ * import { User, Post } from './models';
+ *
+ * const db = connectDoDb({
+ *   endpoint: 'https://my-worker.workers.dev',
+ *   id: 'my-document',
+ *   models: [User, Post],
+ * });
+ *
+ * // Pre-bound model access (models registered at init)
+ * await db.User.save({ id: 'u-1', name: 'Alice' });
+ * const users = await db.User.query({ name: 'Alice' });
+ * const user = await db.User.find('u-1');
+ *
+ * // Ad-hoc model access (any model class)
+ * await db.save(User, { id: 'u-2', name: 'Bob' });
+ * const results = await db.query(User, { name: 'Bob' });
+ * ```
+ */
+declare function connectDoDb(options: ConnectDoDbOptions): DoDb;
+
+export { type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DeleteRequest, type DeleteResponse, type DescribeResponse, type DoDb, type DocumentFilter, type ErrorResponse, type GroupByField, type IncrementRequest, type IncrementResponse, type IndexEntry, type ModelAccessor, type ModelFieldInfo, type ModelIdentifier, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type WriteCondition, connectDoDb };