AzureBlobStore

AzureBlobStore Reference for the Azure Blob Storage store. Overview Azure Blob Storage is an object store: opaque byte blobs addressed by a container + blob name pair, with no query language, no joins, and no ad hoc filtering. Because it does not fit the SQL-shaped Dialect interface, AzureBlobStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) and exposes Blob Storage's object-level operations directly. Key facts: name = 'azure-blob' library = '@azure/storage-blob' Built on the official @azure/storage-blob SDK, which is an optional peer dependency. The SDK is lazy-loaded via require('@azure/storage-blob') inside connect() only when a client isn't injected, so importing this module never forces the SDK to be installed. An injected client (a BlobServiceClient) option is supported. When you pass one, connect() uses it as-is and never calls require() — this is how the tests inject a mock and avoid the real SDK entirely. AzureBlobStore implements only the NoSqlStore lifecycle (connect, disconnect, isConnected, getClient) plus the blob operations below. There is no query(sql) because Blob Storage has no query language. Source: src/nosql/azure-blob/index.ts · Tests: tests/nosql/azure-blob.test.ts Connection Provide exactly one of the following via AzureBlobStoreOptions: Option | Meaning | --- | --- | client | A pre-built BlobServiceClient. Used as-is; the SDK is never require()d. | connectionString | An Azure Storage connection string. Builds a client via BlobServiceClient.fromConnectionString(...). | account + accountKey | Synthesizes a connection string from an account name and key. Optional endpointSuffix defaults to core.windows.net. | Connection string Account name + key When you provide account and accountKey, the store synthesizes the connection string for you: The synthesized string is: If none of client, connectionString, or account + accountKey is provided, connect() throws a ConnectionError (wrapping the message AzureBlobStore requires one of: 'client', 'connectionString', or 'account' + 'accountKey'.). Injected client Pass a pre-built BlobServiceClient to skip the SDK entirely — the module never calls require('@azure/storage-blob'): Methods Lifecycle connect(): Promise<void> Establishes the store's client. If a client was injected, it is used directly. Otherwise, @azure/storage-blob is lazy-require()d and a client is built from the resolved connection string. Idempotent: if already connected with a client, it returns immediately. On any failure, resets internal state and throws a ConnectionError with database: 'azure-blob'. disconnect(): Promise<void> Drops the client reference and flips the connected flag to false. There is no persistent socket to close — each Blob Storage request is an independent HTTPS call. isConnected(): boolean Returns true only when connected and a client is present. getClient(): BlobServiceClientLike Returns the underlying BlobServiceClient for operations not wrapped here. Throws a ConnectionError (Not connected to Azure Blob Storage. Call connect() first.) if called before connect(). Blob operations All blob operations resolve the target block blob through the SDK chain client.getContainerClient(container).getBlockBlobClient(key), and every operation requires a live connection (they throw ConnectionError if called before connect()). Errors from the underlying SDK are wrapped in a DatabaseError with a message of the form Azure Blob <action> failed: <original message>. uploadBlob(container: string, key: string, data: BlobUploadData): Promise<void> Uploads data to container/key, creating or overwriting the block blob. The input is normalized to a Buffer, then passed to the SDK as blockBlob.upload(buffer, buffer.length). BlobUploadData is Buffer | string | Uint8Array | ArrayBuffer. downloadBlob(container: string, key: string): Promise<Buffer> Downloads container/key and returns its full contents as a Buffer. Calls blockBlob.download(), then: If response.readableStreamBody is present (Node.js server build), the readable stream is collected into a single Buffer. Otherwise falls back to the browser build's blobBody ?? contentAsBlob, awaiting the blob and reading its arrayBuffer(). If neither is present, returns an empty Buffer (Buffer.alloc(0)). deleteBlob(container: string, key: string): Promise<void> Deletes container/key via blockBlob.delete(). blobExists(container: string, key: string): Promise<boolean> Returns the boolean result of blockBlob.exists(). listBlobs(container: string, prefix?: string): Promise<string[]> Lists the names of all blobs in container, optionally filtered to those whose name starts with prefix. Obtains the container client (client.getContainerClient(container)), then fully iterates the SDK's async paging iterator listBlobsFlat({ prefix }), collecting each blob.name into a flat array. When prefix is omitted, listBlobsFlat is still called with { prefix: undefined }. Returns [] when the container is empty. createContainer(container: string): Promise<void> Creates container via client.getContainerClient(container).create(). Example Verification status Unit / mock-verified. The test suite (tests/nosql/azure-blob.test.ts) exercises the full public surface — connection lifecycle, uploadBlob, downloadBlob, deleteBlob, blobExists, listBlobs, and createContainer, including error-wrapping and not-connected paths. The real @azure/storage-blob SDK is not installed and is never imported by the tests. A hand-built mock BlobServiceClient is injected via the client option, so connect() uses it directly and skips the SDK require(). Every assertion runs against that mock's spies — no network calls and no real SDK are involved. Behavior against a live Azure Storage account has not been verified here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories