js-bao 0.2.11 → 0.2.12

package/dist/cloudflare-do.d.ts

@@ -0,0 +1,1366 @@
+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>;
+}
+
+/**
+ * JSON Schema DDL Generator
+ *
+ * Generates SQL DDL statements for the JSON schema approach where all records
+ * are stored in a single `records` table with a `_data` column.
+ *
+ * Internal columns use a `_` prefix convention:
+ *   _id, _type, _data (records table)
+ *   _record_id, _type (stringset_index table)
+ *   _meta_doc_id, _meta_permission_hint (yjs mode metadata)
+ *
+ * This schema is used by both:
+ * - OPFS SQLite (browser, with _meta_doc_id for multi-document support)
+ * - Durable Objects SQLite (server, one DO per document, no _meta_doc_id needed)
+ */
+interface JsonSchemaOptions {
+    /**
+     * Whether to include the _meta_doc_id column.
+     * - true: For yjs mode where multiple documents share the same SQLite DB
+     * - false: For DO mode where each DO is a single document
+     */
+    includeDocIdColumn: boolean;
+}
+declare class JsonSchemaDDL {
+    /**
+     * Generate CREATE TABLE statement for the records table
+     */
+    static createRecordsTable(options: JsonSchemaOptions): string;
+    /**
+     * Generate CREATE TABLE statement for the stringset_index table
+     */
+    static createStringSetIndexTable(options: JsonSchemaOptions): string;
+    /**
+     * Generate base indexes for the schema
+     */
+    static createBaseIndexes(options: JsonSchemaOptions): string[];
+    /**
+     * Generate CREATE INDEX statement for a model field
+     * Uses json_extract for JSON schema
+     */
+    static createFieldIndex(modelName: string, fieldName: string): string;
+    /**
+     * Generate DROP INDEX statement for a model field
+     */
+    static dropFieldIndex(modelName: string, fieldName: string): string;
+    /**
+     * Generate CREATE TABLE statement for the _indexes table.
+     * Stores per-field index registrations (one row per index).
+     */
+    static createIndexesTable(): string;
+    /**
+     * Generate CREATE TABLE statement for the _unique_constraints table.
+     * Stores composite (multi-field) unique constraints.
+     */
+    static createUniqueConstraintsTable(): string;
+    /**
+     * Generate CREATE TABLE statement for the _model_fields table.
+     * Tracks field names and inferred types as records are written.
+     */
+    static createModelFieldsTable(): string;
+    /**
+     * Generate all DDL statements needed to initialize the schema
+     */
+    static getAllDDL(options: JsonSchemaOptions): string[];
+    /**
+     * Generate INSERT statement for a record
+     */
+    static buildInsertSQL(options: JsonSchemaOptions): string;
+    /**
+     * Generate DELETE statement for a record by id and type
+     */
+    static buildDeleteSQL(options: JsonSchemaOptions): string;
+    /**
+     * Generate DELETE statement for stringset values
+     */
+    static buildDeleteStringSetSQL(): string;
+    /**
+     * Generate INSERT statement for stringset values
+     */
+    static buildInsertStringSetSQL(options: JsonSchemaOptions): string;
+}
+
+/**
+ * JSON Schema Engine Base Class
+ *
+ * Abstract base class for database engines that use the JSON schema approach.
+ * Provides common implementations for CRUD operations using the single `records`
+ * table with `data_json` column.
+ *
+ * Subclasses must implement:
+ * - execSql(sql, params): Execute SQL and return results
+ * - ensureReady(): Initialize the engine
+ * - destroy(): Clean up resources
+ */
+
+interface JsonSchemaEngineOptions extends JsonSchemaOptions {
+}
+declare abstract class JsonSchemaEngine extends DatabaseEngine {
+    protected schemaOptions: JsonSchemaEngineOptions;
+    initialized: boolean;
+    constructor(options: JsonSchemaEngineOptions);
+    /**
+     * Execute SQL and return results.
+     * Must be implemented by subclasses.
+     */
+    abstract execSql(sql: string, params?: any[]): Promise<any[]>;
+    /**
+     * Execute SQL synchronously (optional, for environments that support it like DO).
+     * Returns undefined if not supported.
+     */
+    execSqlSync?(sql: string, params?: any[]): any[];
+    /**
+     * Initialize the JSON schema tables.
+     * Should be called once during engine setup.
+     */
+    initializeSchema(): Promise<void>;
+    /**
+     * Create table for a model.
+     * In JSON schema, this is a no-op since all models share the `records` table.
+     * However, we can create indexes for indexed fields.
+     */
+    createTable(modelName: string, schema: Map<string, FieldOptions>, _options: ModelOptions): Promise<void>;
+    /**
+     * Create StringSet junction table.
+     * In JSON schema, this is a no-op since we use the shared stringset_index table.
+     */
+    createStringSetJunctionTable(_modelName: string, _fieldName: string): Promise<void>;
+    /**
+     * Insert or update a record.
+     */
+    insert(modelName: string, data: any): Promise<void>;
+    /**
+     * Delete a record by ID.
+     */
+    delete(modelName: string, id: string): Promise<void>;
+    /**
+     * Delete all records for a specific document.
+     * Only applicable in yjs mode with doc ID column.
+     */
+    deleteByDocumentId(modelName: string, docId: string): Promise<void>;
+    /**
+     * Insert StringSet values for a record.
+     */
+    insertStringSetValues(modelName: string, fieldName: string, recordId: string, values: string[], docId?: string): Promise<void>;
+    /**
+     * Remove StringSet values for a record.
+     */
+    removeStringSetValues(modelName: string, fieldName: string, recordId: string, values: string[]): Promise<void>;
+    /**
+     * Get table name for a model.
+     * In JSON schema, all models use the 'records' table.
+     */
+    getTableName(_modelName: string): string;
+    /**
+     * Execute a query and return results.
+     */
+    query(sql: string, params?: any[]): Promise<any[]>;
+    /**
+     * Get the table schema.
+     * Returns information about the records table structure.
+     */
+    getTableSchema(_tableName: string): Promise<any>;
+    /**
+     * Get the last error message.
+     * Subclasses can override this if needed.
+     */
+    getLastErrorMessage(): string | undefined;
+    /**
+     * Transaction support.
+     * Default implementation runs callback without actual transaction.
+     * Subclasses should override for proper transaction support.
+     */
+    withTransaction<T>(callback: (operations: ITransactionalDatabaseOperations) => Promise<T>): Promise<T>;
+    /**
+     * Parse a record row from the database.
+     * Extracts fields from _data and merges with direct columns.
+     */
+    protected parseRecordRow(row: any): Record<string, any>;
+}
+
+/**
+ * Cloudflare Durable Objects Type Definitions
+ *
+ * These types mirror the Cloudflare Workers runtime types for Durable Objects.
+ * They are provided here so js-bao can be built without requiring the
+ * @cloudflare/workers-types package as a dependency.
+ *
+ * When using js-bao in a Cloudflare Worker, you should install
+ * @cloudflare/workers-types for complete type coverage.
+ */
+/**
+ * SqlStorage interface - provides SQLite access in Durable Objects
+ */
+interface SqlStorage {
+    /**
+     * Execute a SQL query with optional parameter bindings.
+     * Returns a cursor for iterating over results.
+     */
+    exec(query: string, ...bindings: any[]): SqlStorageCursor;
+    /**
+     * Get the current database size in bytes.
+     */
+    readonly databaseSize: number;
+}
+/**
+ * SqlStorageCursor - returned by sql.exec() for iterating results
+ */
+interface SqlStorageCursor extends Iterable<Record<string, any>> {
+    /**
+     * Get the next row from the cursor.
+     */
+    next(): IteratorResult<Record<string, any>>;
+    /**
+     * Collect all remaining rows into an array.
+     */
+    toArray(): Record<string, any>[];
+    /**
+     * Get exactly one row. Throws if zero or multiple rows.
+     */
+    one(): Record<string, any>;
+    /**
+     * Return an iterator yielding arrays instead of objects.
+     */
+    raw(): Iterator<any[]>;
+    /**
+     * Column names in result order.
+     */
+    readonly columnNames: string[];
+    /**
+     * Number of rows read so far (affects billing).
+     */
+    readonly rowsRead: number;
+    /**
+     * Number of rows written so far (affects billing).
+     */
+    readonly rowsWritten: number;
+}
+/**
+ * DurableObjectStorage interface
+ */
+interface DurableObjectStorage {
+    /**
+     * SQLite storage interface
+     */
+    readonly sql: SqlStorage;
+    /**
+     * Execute a synchronous transaction with SQLite.
+     */
+    transactionSync<T>(closure: () => T): T;
+    /**
+     * Execute an async transaction.
+     */
+    transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+    put<T>(key: string, value: T): Promise<void>;
+    put<T>(entries: Record<string, T>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    delete(keys: string[]): Promise<number>;
+    deleteAll(): Promise<void>;
+    list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
+}
+/**
+ * DurableObjectTransaction interface
+ */
+interface DurableObjectTransaction {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+    put<T>(key: string, value: T): Promise<void>;
+    put<T>(entries: Record<string, T>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    delete(keys: string[]): Promise<number>;
+    rollback(): void;
+}
+/**
+ * Options for storage.list()
+ */
+interface DurableObjectListOptions {
+    start?: string;
+    startAfter?: string;
+    end?: string;
+    prefix?: string;
+    reverse?: boolean;
+    limit?: number;
+}
+/**
+ * DurableObjectState - passed to DO constructor
+ */
+interface DurableObjectState {
+    /**
+     * The unique ID of this Durable Object instance.
+     */
+    readonly id: DurableObjectId;
+    /**
+     * Storage interface for this Durable Object.
+     */
+    readonly storage: DurableObjectStorage;
+    /**
+     * Wait until the output gate is open.
+     */
+    waitUntil(promise: Promise<any>): void;
+    /**
+     * Block until storage operations complete.
+     */
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+}
+/**
+ * DurableObjectId - unique identifier for a DO instance
+ */
+interface DurableObjectId {
+    toString(): string;
+    equals(other: DurableObjectId): boolean;
+}
+/**
+ * DurableObjectNamespace - for accessing DO instances
+ */
+interface DurableObjectNamespace {
+    /**
+     * Get a DO ID from a name string.
+     */
+    idFromName(name: string): DurableObjectId;
+    /**
+     * Get a DO ID from a hex string.
+     */
+    idFromString(hexId: string): DurableObjectId;
+    /**
+     * Generate a new unique DO ID.
+     */
+    newUniqueId(): DurableObjectId;
+    /**
+     * Get a stub for accessing a DO instance.
+     */
+    get(id: DurableObjectId): DurableObjectStub;
+}
+/**
+ * DurableObjectStub - proxy for calling DO methods
+ */
+interface DurableObjectStub {
+    /**
+     * The ID of this Durable Object.
+     */
+    readonly id: DurableObjectId;
+    /**
+     * The name of this Durable Object (if created via idFromName).
+     */
+    readonly name?: string;
+    /**
+     * Send a fetch request to this Durable Object.
+     */
+    fetch(request: Request | string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * 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
+ */
+
+interface DurableObjectEngineOptions {
+    /**
+     * The SqlStorage interface from ctx.storage.sql
+     */
+    sql: SqlStorage;
+    /**
+     * The full storage interface for transaction support
+     */
+    storage: DurableObjectStorage;
+}
+/** 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;
+}
+declare class DurableObjectEngine extends JsonSchemaEngine {
+    private sql;
+    private storage;
+    constructor(options: DurableObjectEngineOptions);
+    /**
+     * Initialize the engine — creates tables and restores persisted indexes.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Handle schema migrations for existing databases.
+     * Adds columns/tables that were added in later versions.
+     */
+    private _migrateSchema;
+    /**
+     * Load indexes from the _indexes table and re-ensure they exist.
+     */
+    private loadPersistedIndexes;
+    /**
+     * Register an index on a model field.
+     * Idempotent — re-registering the same index is a no-op.
+     */
+    registerIndex(modelName: string, fieldName: string, fieldType: string, unique?: boolean): void;
+    /**
+     * Drop an index on a model field.
+     * Idempotent — dropping a non-existent index is a no-op.
+     */
+    dropIndex(modelName: string, fieldName: string): void;
+    /**
+     * List all registered indexes, optionally filtered by model.
+     */
+    listIndexes(modelName?: string): IndexEntry[];
+    /**
+     * Get unique single-field indexes for a model.
+     */
+    getUniqueIndexes(modelName: string): IndexEntry[];
+    /**
+     * Register a composite unique constraint.
+     * Idempotent — re-registering the same constraint is a no-op.
+     */
+    registerUniqueConstraint(modelName: string, constraintName: string, fields: string[]): void;
+    /**
+     * Drop a composite unique constraint.
+     * Idempotent — dropping a non-existent constraint is a no-op.
+     */
+    dropUniqueConstraint(modelName: string, constraintName: string): void;
+    /**
+     * List composite unique constraints, optionally filtered by model.
+     */
+    listUniqueConstraints(modelName?: string): UniqueConstraintEntry[];
+    /**
+     * Check all unique constraints for a model before saving.
+     * Returns null if no violation, or an error message string if violated.
+     */
+    checkUniqueConstraints(modelName: string, id: string, data: Record<string, any>): string | null;
+    /**
+     * Check if a record exists (used by hooks to determine isNew).
+     */
+    recordExists(modelName: string, id: string): boolean;
+    /**
+     * Execute SQL asynchronously.
+     * Wraps the synchronous DO SQLite API.
+     */
+    execSql(sql: string, params?: any[]): Promise<any[]>;
+    /**
+     * Execute SQL synchronously.
+     * This is the native mode for DO SQLite.
+     */
+    execSqlSync(sql: string, params?: any[]): any[];
+    /**
+     * Transaction support using DO's transactionSync.
+     */
+    withTransaction<T>(callback: (operations: ITransactionalDatabaseOperations) => Promise<T>): Promise<T>;
+    /**
+     * Run operations within a synchronous transaction.
+     */
+    transactionSync<T>(callback: () => T): T;
+    /**
+     * Clean up resources.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Insert a record with StringSet support.
+     */
+    insertWithStringSets(modelName: string, data: any, stringSets: Record<string, string[]>): Promise<void>;
+    /**
+     * Add values to StringSet fields without replacing the entire set.
+     * Also updates the arrays stored in data_json.
+     */
+    addToStringSets(modelName: string, id: string, sets: Record<string, string[]>): void;
+    /**
+     * Non-transactional core of addToStringSets.
+     * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+     * @internal
+     */
+    addToStringSetsRaw(modelName: string, id: string, sets: Record<string, string[]>): void;
+    /**
+     * Remove values from StringSet fields without replacing the entire set.
+     * Also updates the arrays stored in data_json.
+     */
+    removeFromStringSets(modelName: string, id: string, sets: Record<string, string[]>): void;
+    /**
+     * Non-transactional core of removeFromStringSets.
+     * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+     * @internal
+     */
+    removeFromStringSetsRaw(modelName: string, id: string, sets: Record<string, string[]>): void;
+    /**
+     * Sync stringset_index state back into data_json arrays for the given fields.
+     * @internal
+     */
+    private _syncStringSetsToJson;
+    /**
+     * Patch a record: merge provided fields into existing data_json.
+     * Only the specified fields are updated; all other fields are preserved.
+     * If stringSets are provided, those StringSet fields are fully replaced.
+     * Returns false if the record does not exist.
+     */
+    patchRecord(modelName: string, id: string, fields: Record<string, any>, stringSets?: Record<string, string[]>): boolean;
+    /**
+     * Non-transactional core of patchRecord.
+     * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+     * @internal
+     */
+    patchRecordRaw(modelName: string, id: string, fields: Record<string, any>, stringSets?: Record<string, string[]>): boolean;
+    /**
+     * Atomically increment/decrement numeric fields on a record.
+     * Each key in `fields` is a field name and its value is the delta.
+     * Missing fields are initialised to 0 before adding the delta.
+     * Returns the new values, or null if the record doesn't exist.
+     */
+    incrementFields(modelName: string, id: string, fields: Record<string, number>): Record<string, number> | null;
+    /**
+     * Non-transactional core of incrementFields.
+     * Call this from an outer transaction (e.g. batch) to avoid nested transactions.
+     * @internal
+     */
+    incrementFieldsRaw(modelName: string, id: string, fields: Record<string, number>): Record<string, number> | null;
+    /**
+     * Delete a record and its StringSet values atomically.
+     */
+    deleteWithStringSets(modelName: string, id: string): Promise<void>;
+    /**
+     * Track field names and inferred types for a model based on written data.
+     * Uses INSERT OR IGNORE so the first-seen type wins.
+     */
+    trackModelFields(modelName: string, data: Record<string, any>): void;
+    /**
+     * Get tracked fields for a model, or all models if no name given.
+     */
+    getModelFields(modelName?: string): ModelFieldInfo[];
+}
+
+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 IncludeSpec {
+    model: string;
+    type: "refersTo" | "hasMany" | "refersToMany";
+    sourceField?: string;
+    foreignKey?: string;
+    localField?: string;
+    as?: string;
+    projection?: ProjectionSpec;
+    limit?: number;
+    sort?: SortSpec;
+    filter?: DocumentFilter;
+    include?: IncludeSpec[];
+}
+interface QueryOptions {
+    sort?: SortSpec;
+    projection?: ProjectionSpec;
+    documents?: string | string[];
+    limit?: number;
+    uniqueStartKey?: string;
+    direction?: 1 | -1;
+    include?: IncludeSpec[];
+}
+interface TranslatedQuery {
+    sql: string;
+    params: any[];
+    sortFields: string[];
+    sortDirections?: (1 | -1)[];
+}
+
+/**
+ * JSON Query Translator
+ *
+ * Translates document-style queries to SQL for the JSON schema approach.
+ * All records are in a single `records` table with fields stored in `_data`.
+ *
+ * Key differences from DocumentQueryTranslator:
+ * - Uses json_extract(_data, '$.field') instead of direct column access
+ * - Uses shared stringset_index table instead of per-model junction tables
+ * - Adds _type = ? filter to all queries
+ * - Optionally handles _meta_doc_id for yjs mode
+ */
+
+interface JsonQueryTranslatorOptions {
+    /**
+     * Whether to include document scoping (_meta_doc_id) in queries.
+     * - true: For yjs mode where multiple documents share the same SQLite DB
+     * - false: For DO mode where each DO is a single document
+     */
+    includeDocId: boolean;
+}
+declare class JsonQueryTranslator {
+    private modelName;
+    private schema?;
+    private options;
+    private fieldSqlCache;
+    constructor(modelName: string, schema?: Map<string, FieldOptions>, options?: JsonQueryTranslatorOptions);
+    /**
+     * Get SQL expression for a field.
+     * System fields (id, type) map to internal columns (_id, _type);
+     * others use json_extract(_data, ...).
+     * When no schema is provided, any field is accepted (schemaless mode).
+     */
+    getFieldSql(fieldName: string): string;
+    /**
+     * 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.
+     * Returns the conditions and params without the type = ? prefix.
+     */
+    translateFilter(filter: DocumentFilter): {
+        sql: string;
+        params: any[];
+    };
+    /**
+     * 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
+     * For JSON schema, we need to extract fields from data_json
+     */
+    private buildSelectClause;
+    /**
+     * Build LIMIT clause
+     */
+    private buildLimitClause;
+    /**
+     * Build pagination WHERE clause from cursor
+     */
+    private buildPaginationClause;
+    /**
+     * Validate projection fields — skipped in schemaless mode
+     */
+    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;
+}
+
+/**
+ * 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>[];
+
+/**
+ * Hook type definitions for Durable Object access control.
+ *
+ * Hooks run server-side inside the DO before CRUD operations.
+ * They can allow/deny operations and inject query filters.
+ */
+
+/** Context passed to all hooks */
+interface HookContext {
+    /** The model (type discriminator) being operated on */
+    modelName: string;
+    /** The document ID (derived from the DO instance) */
+    docId: string;
+    /** The raw request (for reading headers, auth tokens, etc.) */
+    request: Request;
+    /** The DO's SQLite engine (for direct queries, e.g. lookup functions) */
+    engine: any;
+}
+/** Context for beforeSave hooks */
+interface BeforeSaveContext extends HookContext {
+    /** Record ID being saved */
+    id: string;
+    /** Data being saved */
+    data: Record<string, any>;
+    /** StringSet values being saved (if any) */
+    stringSets?: Record<string, string[]>;
+    /** Whether this is a new record (true) or an update (false) */
+    isNew: boolean;
+}
+/** Context for beforeDelete hooks */
+interface BeforeDeleteContext extends HookContext {
+    /** Record ID being deleted */
+    id: string;
+    /** The existing record being deleted (parsed from data_json) */
+    record: Record<string, any> | null;
+}
+/** Context for beforeQuery hooks */
+interface BeforeQueryContext extends HookContext {
+    /** The filter being applied */
+    filter: DocumentFilter;
+    /** Query options (sort, limit, etc.) */
+    options?: QueryOptions;
+}
+/** Context for afterQuery hooks */
+interface AfterQueryContext extends HookContext {
+    /** The query results to filter */
+    results: Record<string, any>[];
+}
+/** Result from beforeSave/beforeDelete hooks */
+interface HookResult {
+    allow: boolean;
+    /** Reason for denial (returned to client as error message) */
+    reason?: string;
+}
+/** Result from beforeQuery hooks — can inject additional filters */
+interface BeforeQueryResult extends HookResult {
+    /** Additional filter merged into the query via $and */
+    injectFilter?: DocumentFilter;
+}
+/** Result from afterQuery hooks — returns filtered results */
+interface AfterQueryResult {
+    /** The filtered results to return */
+    results: Record<string, any>[];
+}
+/** Hook definitions for createDatabaseDO */
+interface DatabaseDOHooks {
+    beforeSave?: (ctx: BeforeSaveContext) => Promise<HookResult>;
+    beforeDelete?: (ctx: BeforeDeleteContext) => Promise<HookResult>;
+    beforeQuery?: (ctx: BeforeQueryContext) => Promise<BeforeQueryResult>;
+    afterQuery?: (ctx: AfterQueryContext) => Promise<AfterQueryResult>;
+}
+
+/**
+ * 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 };
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+interface DatabaseDOConfig {
+    /**
+     * Hooks for access control. All hooks are async.
+     */
+    hooks?: DatabaseDOHooks;
+}
+/**
+ * @deprecated Use DatabaseDOConfig instead
+ */
+type DocumentDOConfig = DatabaseDOConfig;
+/**
+ * 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;
+}
+interface RegisterIndexRequest {
+    modelName: string;
+    fieldName: string;
+    fieldType: string;
+    unique?: boolean;
+}
+interface DropIndexRequest {
+    modelName: string;
+    fieldName: string;
+}
+interface RegisterUniqueConstraintRequest {
+    modelName: string;
+    constraintName: string;
+    fields: string[];
+}
+interface DropUniqueConstraintRequest {
+    modelName: string;
+    constraintName: string;
+}
+/**
+ * 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 RegisterIndexResponse {
+    success: boolean;
+    modelName: string;
+    fieldName: string;
+}
+interface DropIndexResponse {
+    success: boolean;
+    modelName: string;
+    fieldName: string;
+}
+interface IndexListResponse {
+    indexes: IndexEntry[];
+}
+interface RegisterUniqueConstraintResponse {
+    success: boolean;
+    modelName: string;
+    constraintName: string;
+}
+interface DropUniqueConstraintResponse {
+    success: boolean;
+    modelName: string;
+    constraintName: string;
+}
+interface UniqueConstraintListResponse {
+    constraints: UniqueConstraintEntry[];
+}
+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;
+}
+/**
+ * Create a Durable Object class for schemaless database storage.
+ *
+ * The returned class can be exported and used in wrangler.toml:
+ * ```toml
+ * [durable_objects]
+ * bindings = [
+ *   { name = "DATABASE_DO", class_name = "MyDatabaseDO" }
+ * ]
+ * ```
+ */
+declare function createDatabaseDO(config?: DatabaseDOConfig): {
+    new (state: DurableObjectState, _env: unknown): {
+        /** @internal */
+        _doState: DurableObjectState;
+        /** @internal */
+        _engine: DurableObjectEngine;
+        /** @internal */
+        _initialized: boolean;
+        /** @internal — cache for $contains misuse check: "model:field" keys known to be in data_json */
+        _containsMisuseCache: Set<string>;
+        get state(): DurableObjectState;
+        get engine(): DurableObjectEngine;
+        /** @internal */
+        _ensureInitialized(): Promise<void>;
+        fetch(request: Request): Promise<Response>;
+        /** @internal */
+        _handleQuery(request: Request, docId: string): Promise<Response>;
+        /** @internal — Check for reserved field names in record data */
+        _checkReservedFields(data: Record<string, any>): string | null;
+        /** @internal */
+        _handleSave(request: Request, docId: string): Promise<Response>;
+        /** @internal — Partial update: merge provided fields into existing record */
+        _handlePatch(request: Request, docId: string): Promise<Response>;
+        /** @internal */
+        _handleDelete(request: Request, docId: string): Promise<Response>;
+        /** @internal — Execute multiple save/patch/delete operations in a single transaction */
+        _handleBatch(request: Request, docId: string): Promise<Response>;
+        /** @internal */
+        _handleCount(request: Request, docId: string): Promise<Response>;
+        /** @internal — Atomically increment/decrement numeric fields */
+        _handleIncrement(request: Request, _docId: string): Promise<Response>;
+        /** @internal — Atomically add values to StringSet fields */
+        _handleStringSetAdd(request: Request, _docId: string): Promise<Response>;
+        /** @internal — Atomically remove values from StringSet fields */
+        _handleStringSetRemove(request: Request, _docId: string): Promise<Response>;
+        _handleAggregate(request: Request, docId: string): Promise<Response>;
+        /** @internal — Build SQL for StringSet facet aggregation */
+        _buildStringSetFacetSql(modelName: string, facetField: string, aggOptions: AggregationOptions, filter: DocumentFilter, translator: JsonQueryTranslator): {
+            sql: string;
+            params: any[];
+        };
+        /** @internal — Build SQL for regular field aggregation */
+        _buildRegularAggregationSql(modelName: string, regularGroupBy: string[], stringSetMemberships: Array<{
+            field: string;
+            contains: string;
+        }>, aggOptions: AggregationOptions, filter: DocumentFilter, translator: JsonQueryTranslator): {
+            sql: string;
+            params: any[];
+            aliasMap: Array<{
+                alias: string;
+                field: string;
+                contains: string;
+            }>;
+        };
+        /** @internal — Extract operation value(s) from a row. Flattens single-op results. */
+        _extractOpValue(row: any, operations: AggregationOptions["operations"]): any;
+        /** @internal — Process raw aggregation rows into nested result */
+        _processAggregationResults(results: any[], aggOptions: AggregationOptions, aliasMap: Array<{
+            alias: string;
+            field: string;
+            contains: string;
+        }>, stringSetFacetField: string | null): AggregationResult;
+        /** @internal */
+        /** @internal — Batch sync: compare desired indexes against _indexes table, register missing */
+        _handleIndexesSync(request: Request): Promise<Response>;
+        /** @internal */
+        _handleIndexRegister(request: Request): Promise<Response>;
+        /** @internal */
+        _handleIndexDrop(request: Request): Promise<Response>;
+        /** @internal */
+        _handleIndexList(request: Request): Response;
+        /** @internal */
+        _handleUniqueConstraintRegister(request: Request): Promise<Response>;
+        /** @internal */
+        _handleUniqueConstraintDrop(request: Request): Promise<Response>;
+        /** @internal */
+        _handleUniqueConstraintList(request: Request): Response;
+        /** @internal */
+        /**
+         * Extract field names that use $contains from a filter tree.
+         * @internal
+         */
+        _findContainsFields(filter: DocumentFilter): string[];
+        /**
+         * Check for $contains misuse with caching.
+         * Returns an error Response if misuse is detected, or null if OK.
+         * @internal
+         */
+        _checkContainsMisuse(modelName: string, filter: DocumentFilter): Response | null;
+        /**
+         * Check a write condition against the current state of a record.
+         * Returns true if the condition is met (record exists and matches the filter).
+         * Returns false if the record doesn't exist or doesn't match.
+         * @internal
+         */
+        _checkCondition(modelName: string, id: string, condition: DocumentFilter): boolean;
+        _handleHealth(): Response;
+        /** @internal — Return tracked field names and types for a model */
+        _handleDescribe(request: Request): Response;
+        /** @internal — List all known model names from records and _model_fields */
+        _handleModelList(): Response;
+        /** @internal */
+        _errorResponse(message: string, status: number): Response;
+        /** @internal */
+        _parseRow(row: Record<string, any>): Record<string, any>;
+        /** @internal — Validate an IncludeSpec, returning an error message or null */
+        _validateIncludeSpec(spec: IncludeSpec): string | null;
+        /** @internal — Resolve all includes for a set of records */
+        _resolveIncludes(records: Record<string, any>[], includes: IncludeSpec[], depth: number, _parentModelName?: string): Record<string, any>[];
+        /** @internal — Resolve a refersTo include (parent FK → single related record) */
+        _resolveRefersTo(records: Record<string, any>[], spec: IncludeSpec, resultKey: string): void;
+        /** @internal — Resolve a refersToMany include (parent StringSet field → array of related records) */
+        _resolveRefersToMany(records: Record<string, any>[], spec: IncludeSpec, resultKey: string): void;
+        /** @internal — Resolve a hasMany include (target FK → array of related records) */
+        _resolveHasMany(records: Record<string, any>[], spec: IncludeSpec, resultKey: string): void;
+        /** @internal — Simple hasMany without per-parent limit */
+        _resolveHasManySimple(spec: IncludeSpec, parentValues: any[]): Record<string, any>[];
+        /** @internal — hasMany with per-parent limit using ROW_NUMBER() */
+        _resolveHasManyWithLimit(spec: IncludeSpec, parentValues: any[]): Record<string, any>[];
+        /**
+         * @internal — Execute IN queries in chunks to stay under Cloudflare DO's
+         * 100 bound parameter limit per SQL statement.
+         */
+        _chunkedIn(model: string, field: string, values: any[], extraFilter?: DocumentFilter, extraOptions?: {
+            sort?: SortSpec;
+            projection?: ProjectionSpec;
+        }): Record<string, any>[];
+        /** @internal — Apply projection to a single record */
+        _applyProjection(record: Record<string, any>, projection: ProjectionSpec): Record<string, any>;
+    };
+};
+/**
+ * @deprecated Use createDatabaseDO instead
+ */
+declare const createDocumentDO: typeof createDatabaseDO;
+
+/**
+ * Cloudflare Worker Router Template
+ *
+ * This file provides a template for routing requests to Document Durable Objects.
+ * Copy and customize this for your worker implementation.
+ *
+ * Usage:
+ * 1. Copy this file to your worker project
+ * 2. Import your models and create the DO class
+ * 3. Configure wrangler.toml with the DO binding
+ * 4. Deploy with `wrangler deploy`
+ *
+ * Example wrangler.toml:
+ * ```toml
+ * name = "my-worker"
+ * main = "src/index.ts"
+ * compatibility_date = "2024-01-01"
+ *
+ * [[durable_objects.bindings]]
+ * name = "DOCUMENT_DO"
+ * class_name = "DocumentDO"
+ *
+ * [[migrations]]
+ * tag = "v1"
+ * new_sqlite_classes = ["DocumentDO"]
+ * ```
+ */
+
+/**
+ * Environment interface - customize for your worker
+ */
+interface Env {
+    /**
+     * The Durable Object namespace binding
+     */
+    DOCUMENT_DO: DurableObjectNamespace;
+}
+/**
+ * Create the worker export
+ *
+ * Example usage in your worker:
+ * ```typescript
+ * import { createDocumentDO } from 'js-bao/cloudflare/do';
+ * import { Statement } from './models';
+ *
+ * // Create the DO class
+ * export const DocumentDO = createDocumentDO({ models: [Statement] });
+ *
+ * // Export the worker
+ * export default {
+ *   async fetch(request: Request, env: Env): Promise<Response> {
+ *     return handleRequest(request, env);
+ *   }
+ * };
+ * ```
+ */
+declare function handleRequest(request: Request, env: Env): Promise<Response>;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type Env, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SqlStorage, type SqlStorageCursor, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, createDatabaseDO, createDocumentDO, handleRequest };