js-bao-wss-client

---

js-bao-wss-client / DOClientEngine

Interface: DOClientEngine

Extends

• DatabaseEngine

Properties

createFormat2Sql?

optional createFormat2Sql?: () => Format2StoreSql

A SYNCHRONOUS SQL executor over this engine's database, used by the large-document (format 2) record store. That store commits a merged record row and its pending-operation entry as one transaction — the barrier a save() resolves behind — which the async query() API cannot express. Engines whose underlying SQLite is synchronous (better-sqlite3, SQL.js) provide it; anything else leaves it undefined and cannot host a large document.

Returns

Format2StoreSql

Inherited from

DatabaseEngine.createFormat2Sql

---

createFormat2StoreHost?

optional createFormat2StoreHost?: (docId, options?) => Format2StoreHost | Promise<Format2StoreHost>

A COMMAND HOST for a large document's record store.

How an engine whose SQLite is not on this thread hosts a large document: it returns something that EXECUTES store commands, rather than the synchronous executor it cannot provide. An engine backed by a worker implements this and leaves createFormat2Sql undefined; engines whose SQLite is synchronous and local do the opposite, and are wrapped in an in-process host over createFormat2Sql().

A host, not a store: what crosses the boundary is one command per logical operation, so a record's rows and the marks that vouch for them stay on the same side of it.

Parameters

docId

string

options?

Format2StoreHostOptions

Returns

Format2StoreHost | Promise<Format2StoreHost>

Inherited from

DatabaseEngine.createFormat2StoreHost

---

engineForDocuments?

optional engineForDocuments?: (docIds, modelName) => DatabaseEngine | Promise<DatabaseEngine>

The engine that holds docIds' derived query tables for modelName.

An engine whose large documents' query tables live apart from the ordinary documents' — the browser's worker-hosted engine — answers with the engine to run the statement on, or refuses a scope that would need both. Engines with one database for everything leave it undefined and BaseModel uses the engine itself.

Parameters

docIds

readonly string[]

modelName

string

Returns

DatabaseEngine | Promise<DatabaseEngine>

Inherited from

DatabaseEngine.engineForDocuments

---

format2Purge?

optional format2Purge?: (docId, options) => Promise<Format2PurgeResult>

Remove one large document's local data, and the store holding it when nothing else is in there.

An engine whose store lives somewhere only it can reach — the browser's worker-hosted pool — implements this; engines whose SQLite is synchronous and local leave it undefined and the in-process path purges through createFormat2Sql() instead. Either way the doors an app sees (documents.evict, closeDocument({ evictLocal }), logout({ wipeLocal })) remove the same things.

scope is what the store is namespaced by beside the document, passed by the caller rather than remembered here: a purge at logout is about the user who is signing OUT, and an engine that outlives the sign-in would otherwise resolve the wrong store.

Parameters

docId

string

options

force

boolean

scope?

Format2StoreScope

Returns

Promise<Format2PurgeResult>

Inherited from

DatabaseEngine.format2Purge

---

format2PurgeAll?

optional format2PurgeAll?: (options) => Promise<Format2PurgeAllResult>

Remove every large document's local data within one scope, except keep.

Reaches documents this session never opened, and stores left behind before a purge existed — neither of which has anything in memory naming it.

Parameters

options

force

boolean

keep?

readonly string[]

scope?

Format2StoreScope

Returns

Promise<Format2PurgeAllResult>

Inherited from

DatabaseEngine.format2PurgeAll

---

format2StorageIsDurable?

optional format2StorageIsDurable?: () => boolean

Whether what createFormat2Sql writes survives this process.

On a large document the merged record view IS the document: the Y.Doc holds one epoch's overlay, and everything else — including a record a save() has already resolved, and the pending write that still owes it to the server — lives only in this store. An engine whose database is in memory therefore cannot host one: a reload does not cost a cache, it costs the document and the writes nobody has acknowledged yet.

The platform is asked separately about its storage quota; this answers the half only the engine knows. An engine that does not implement it is taken at the platform's word, which is what keeps hosts with storage of their own — a worker handed a file store, a test — working unchanged.

Returns

boolean

Inherited from

DatabaseEngine.format2StorageIsDurable

---

format2StoredEpoch?

optional format2StoredEpoch?: (docId, scope?) => Promise<number | null>

The epoch a document's local store already follows, asked BEFORE the document is bound.

The synchronous helper reads this through createFormat2Sql(), which an engine hosting the store in a worker does not have. This is that engine's own answer; null means it cannot be asked, which a caller must not read as "follows no epoch".

Parameters

docId

string

scope?

Format2StoreScope

Returns

Promise<number | null>

Inherited from

DatabaseEngine.format2StoredEpoch

Methods

addToStringSet()

addToStringSet(modelName, id, sets, options?): Promise<void>

Atomically add values to StringSet fields on a record.

Parameters

modelName

string

id

string

sets

Record<string, string[]>

options?

condition?

DocumentFilter

Returns

Promise<void>

---

aggregateModel()

aggregateModel(modelName, options): Promise<AggregationResult>

Aggregate records with groupBy and operations (count, sum, avg, min, max).

Parameters

modelName

string

options

AggregationOptions

Returns

Promise<AggregationResult>

---

batchWrite()

batchWrite(operations): Promise<BatchOperationResult[]>

Execute multiple save/patch/delete operations in a single request. All operations run in a single transaction on the server.

Parameters

operations

BatchOperation[]

Returns

Promise<BatchOperationResult[]>

---

countModel()

countModel(modelName, filter?): Promise<number>

Count records matching a filter.

Parameters

modelName

string

filter?

DocumentFilter

Returns

Promise<number>

---

createStringSetJunctionTable()

createStringSetJunctionTable(_modelName, _fieldName): Promise<void>

Create StringSet junction table. No-op in DO client mode.

Parameters

_modelName

string

_fieldName

string

Returns

Promise<void>

Overrides

DatabaseEngine.createStringSetJunctionTable

---

createTable()

createTable(_modelName, _schema, _options): Promise<void>

Create table. No-op in DO client mode - schema is managed by the DO.

Parameters

_modelName

string

_schema

Map<string, FieldOptions>

_options

ModelOptions

Returns

Promise<void>

Overrides

DatabaseEngine.createTable

---

delete()

delete(modelName, id): Promise<void>

Delete a record. Delegates to deleteModel.

Parameters

modelName

string

id

string

Returns

Promise<void>

Overrides

DatabaseEngine.delete

---

deleteByDocumentId()

deleteByDocumentId(_modelName, _docId): 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.

Parameters

_modelName

string

_docId

string

Returns

Promise<void>

Inherited from

DatabaseEngine.deleteByDocumentId

---

deleteModel()

deleteModel(modelName, id, options?): Promise<boolean>

Delete a record from the DO.

Parameters

modelName

string

id

string

options?

condition?

DocumentFilter

Returns

Promise<boolean>

---

describe()

describe(modelName): Promise<ModelFieldInfo[]>

Describe tracked fields for a model.

Parameters

modelName

string

Returns

Promise<ModelFieldInfo[]>

---

destroy()

destroy(): Promise<void>

Destroy the engine. Nothing to clean up for the client.

Returns

Promise<void>

Overrides

DatabaseEngine.destroy

---

dropIndex()

dropIndex(modelName, fieldName): Promise<void>

Drop an index from a model field.

Parameters

modelName

string

fieldName

string

Returns

Promise<void>

---

dropUniqueConstraint()

dropUniqueConstraint(modelName, constraintName): Promise<void>

Drop a composite unique constraint.

Parameters

modelName

string

constraintName

string

Returns

Promise<void>

---

ensureReady()

ensureReady(): Promise<void>

Ensure the engine is ready. For DOClient, this verifies connectivity.

Returns

Promise<void>

Overrides

DatabaseEngine.ensureReady

---

getCurrentDocument()

getCurrentDocument(): string | null

Get the current document ID.

Returns

string | null

---

getLastErrorMessage()

getLastErrorMessage(): string | undefined

Get last error message.

Returns

string | undefined

Overrides

DatabaseEngine.getLastErrorMessage

---

getTableName()

getTableName(_modelName): string

Get table name. All models use 'records' in JSON schema.

Parameters

_modelName

string

Returns

string

Overrides

DatabaseEngine.getTableName

---

getTableSchema()

getTableSchema(_tableName): Promise<any>

Get table schema. Not directly supported - schema is managed by the DO.

Parameters

_tableName

string

Returns

Promise<any>

Overrides

DatabaseEngine.getTableSchema

---

healthCheck()

healthCheck(): Promise<{ status: string; }>

Check if the DO is healthy.

Returns

Promise<{ status: string; }>

---

incrementFields()

incrementFields(modelName, id, fields, options?): Promise<Record<string, number>>

Atomically increment/decrement numeric fields on a record. Returns the new values after the increment.

Parameters

modelName

string

id

string

fields

Record<string, number>

options?

condition?

DocumentFilter

Returns

Promise<Record<string, number>>

---

insert()

insert(modelName, data): Promise<void>

Insert a record. Delegates to saveModel.

Parameters

modelName

string

data

any

Returns

Promise<void>

Overrides

DatabaseEngine.insert

---

insertStringSetValues()

insertStringSetValues(_modelName, _fieldName, _recordId, _values): Promise<void>

Parameters

_modelName

string

_fieldName

string

_recordId

string

_values

string[]

Returns

Promise<void>

Inherited from

DatabaseEngine.insertStringSetValues

---

listIndexes()

listIndexes(modelName?): Promise<IndexEntry[]>

List indexes, optionally filtered by model name.

Parameters

modelName?

string

Returns

Promise<IndexEntry[]>

---

listUniqueConstraints()

listUniqueConstraints(modelName?): Promise<UniqueConstraintEntry[]>

List composite unique constraints, optionally filtered by model name.

Parameters

modelName?

string

Returns

Promise<UniqueConstraintEntry[]>

---

patchModel()

patchModel(modelName, id, data, stringSets?, options?): Promise<string>

Patch (partial update) a record in the DO. Only the provided fields are updated; existing fields are preserved.

Parameters

modelName

string

id

string

data

Record<string, any>

stringSets?

Record<string, string[]>

options?

condition?

DocumentFilter

Returns

Promise<string>

---

query()

query(_sql, _params?): Promise<any[]>

Execute raw SQL. Not supported in DO client mode - use queryModel instead.

Parameters

_sql

string

_params?

any[]

Returns

Promise<any[]>

Overrides

DatabaseEngine.query

---

queryModel()

queryModel(modelName, filter?, options?): Promise<PaginatedResult<Record<string, any>>>

Query records from the DO.

Parameters

modelName

string

filter?

DocumentFilter

options?

QueryOptions

Returns

Promise<PaginatedResult<Record<string, any>>>

---

registerIndex()

registerIndex(modelName, fieldName, fieldType?, unique?): Promise<void>

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.

Parameters

modelName

string

fieldName

string

fieldType?

string

unique?

boolean

Returns

Promise<void>

---

registerUniqueConstraint()

registerUniqueConstraint(modelName, constraintName, fields): Promise<void>

Register a composite unique constraint across multiple fields.

Parameters

modelName

string

constraintName

string

fields

string[]

Returns

Promise<void>

---

removeFromStringSet()

removeFromStringSet(modelName, id, sets, options?): Promise<void>

Atomically remove values from StringSet fields on a record.

Parameters

modelName

string

id

string

sets

Record<string, string[]>

options?

condition?

DocumentFilter

Returns

Promise<void>

---

removeStringSetValues()

removeStringSetValues(_modelName, _fieldName, _recordId, _values): Promise<void>

Parameters

_modelName

string

_fieldName

string

_recordId

string

_values

string[]

Returns

Promise<void>

Inherited from

DatabaseEngine.removeStringSetValues

---

saveModel()

saveModel(modelName, id, data, stringSets?, options?): Promise<string>

Save a record to the DO.

Parameters

modelName

string

id

string | undefined

data

Record<string, any>

stringSets?

Record<string, string[]>

options?

condition?

DocumentFilter

ifNotExists?

boolean

upsertOn?

string

Returns

Promise<string>

---

setCurrentDocument()

setCurrentDocument(docId): void

Set the current document ID for subsequent operations.

Parameters

docId

string

Returns

void

---

syncIndexesBatch()

syncIndexesBatch(request): Promise<number>

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.

Parameters

request

SyncIndexesRequest

Returns

Promise<number>

---

withTransaction()

withTransaction<T>(callback): Promise<T>

Transaction support. DO client doesn't support client-side transactions. Operations are atomic on the DO side.

Type Parameters

T

T

Parameters

callback

(operations) => Promise<T>

Returns

Promise<T>

Overrides

DatabaseEngine.withTransaction