js-bao-wss-client / BlobManager
Interface: BlobManager
Manages file attachments (blobs) for documents: uploads with a persistent background retry queue, a local cache for reads and offline access, and download URL generation. Most apps use the per-document view returned by forDocument() (exposed as client.document(id).blobs()) rather than calling these methods directly.
Methods
closeIdb()
closeIdb():
void
Close the IDB connection without resetting state. Called on pagehide to release the connection before the page unloads.
Returns
void
configureIdentity()
configureIdentity(
appId,userId):Promise<void>
Configure the BlobManager for the active user context.
Parameters
appId
string
userId
string | null
Returns
Promise<void>
delete()
delete(
documentId,blobId):Promise<{deleted:boolean; }>
Deletes a blob from a document. Any queued upload for the same blob is cancelled and its locally cached bytes are removed before the server delete is issued.
Parameters
documentId
string
blobId
string
Returns
Promise<{ deleted: boolean; }>
forDocument()
forDocument(
documentId):DocumentBlobContext
Returns a DocumentBlobContext with every blob operation bound to the given document — the recommended way to work with blobs, exposed as client.document(id).blobs().
Parameters
documentId
string
Returns
get()
get<
T>(documentId,blobId):Promise<T>
Fetches the server-side metadata record for a single blob (filename, content type, size, and related fields) without downloading its content.
Type Parameters
T
T = unknown
Parameters
documentId
string
blobId
string
Returns
Promise<T>
getDownloadUrl()
getDownloadUrl(
documentId,blobId,params?):string
Builds the download URL for a blob on the API host, optionally forcing a disposition or suggesting an attachment filename. The URL itself carries no credentials — requests to it must still be authenticated (e.g. via a service worker attaching the token).
Parameters
documentId
string
blobId
string
params?
Returns
string
getUploadConcurrency()
getUploadConcurrency():
number
Returns the current limit on parallel background uploads (default 2).
Returns
number
getUploads()
getUploads(
documentId?):BlobUploadStatus[]
Returns a snapshot of the background upload queue — optionally filtered to one document — sorted with the most recently updated entries first.
Parameters
documentId?
string
Returns
handleNetworkMode()
handleNetworkMode(
mode):void
Applies a network mode change to the upload queue: going online (or auto) resumes background upload processing, going offline stops it. Queued uploads are kept and retried once the network is available again.
Parameters
mode
Returns
void
list()
list<
T>(documentId,params?):Promise<BlobListResult<T>>
Lists the blobs attached to a document, one page at a time. Pass the previous page's nextCursor as params.cursor to fetch the next page.
Type Parameters
T
T = unknown
Parameters
documentId
string
params?
Returns
Promise<BlobListResult<T>>
pauseAllUploads()
pauseAllUploads(
documentId?):void
Pauses every queued or in-progress upload, or only those for one document when documentId is given.
Parameters
documentId?
string
Returns
void
pauseUpload()
pauseUpload(
queueId,documentId?):boolean
Pauses a queued or in-progress upload, aborting any in-flight transfer. Pass documentId to guard against pausing an upload that belongs to a different document. Returns false when the upload is unknown, belongs to another document, or is already paused or finished.
Parameters
queueId
string
documentId?
string
Returns
boolean
prefetch()
prefetch(
documentId,blobIds,options?):Promise<void>
Downloads a set of blobs into the local cache ahead of time (e.g. before going offline), running up to concurrency downloads in parallel (default 2). Individual failures are logged and skipped, so the returned promise resolves even when some blobs could not be fetched.
Parameters
documentId
string
blobIds
string[]
options?
Returns
Promise<void>
read()
read(
documentId,blobId,options?):Promise<string|ArrayBuffer|Uint8Array<ArrayBufferLike> |Blob>
Reads a blob's content, preferring the local cache: cached bytes are returned without a network round trip unless forceRedownload is set. On a cache miss the blob is downloaded from the server and cached for next time. Throws when the client is offline and no cached copy exists. The as option selects the return format (default Uint8Array).
Parameters
documentId
string
blobId
string
options?
Returns
Promise<string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob>
reset()
reset():
void
Clears all in-memory blob state — the upload queue, cached bytes, and the active user identity. Called when the user signs out; queued uploads persisted locally are restored the next time an identity is configured.
Returns
void
resumeAllUploads()
resumeAllUploads(
documentId?):void
Resumes every paused upload, or only those for one document when documentId is given, and restarts queue processing if anything was resumed.
Parameters
documentId?
string
Returns
void
resumeUpload()
resumeUpload(
queueId,documentId?):boolean
Resumes a paused upload, marking it eligible for an immediate retry. Returns false when the upload is unknown, belongs to another document, or is not currently paused.
Parameters
queueId
string
documentId?
string
Returns
boolean
setUploadConcurrency()
setUploadConcurrency(
value):void
Sets how many background uploads may run in parallel. Values are rounded down and clamped to at least 1; raising the limit kicks off queue processing immediately.
Parameters
value
number
Returns
void
uploadFromSource()
uploadFromSource(
documentId,source,options?):Promise<BlobUploadResult>
Uploads a file or binary source to a document. Fills in the filename and content type from the source when possible, computes the SHA-256 hash, and assigns a new blob ID. When a user is signed in the blob is stored locally and one immediate upload attempt is made; if that attempt fails with a retryable error the upload stays queued for background retry and the result reports bytesTransferred: 0. Non-retryable failures (e.g. permission errors) reject.
Parameters
documentId
string
source
ArrayBuffer | Uint8Array<ArrayBufferLike> | File | Blob
options?
Returns
Promise<BlobUploadResult>
uploadImmediate()
uploadImmediate(
request,options?):Promise<BlobUploadResult>
Uploads a blob to the server in a single request, bypassing the background queue entirely — no local persistence and no retry on failure. Rejects on any network failure or non-2xx response (the error carries the HTTP status). uploadFromSource uses this internally; prefer that method unless you need direct, one-shot semantics.
Parameters
request
options?
signal?
AbortSignal
Returns
Promise<BlobUploadResult>