cloud-adapter-azure API

Everything the package exports, by the path you import it from. Open an export for its signature and options.

@evolve-framework/cloud-adapter-azure

Messaging: ServiceBusPublisher, EventGridPublisher, createServiceBusHandler and createEventGridHandler. Storage: AzureBlobServiceStorageClient. Configuration: azureAppConfigSource. Cache: createEntraIdCredentialsProvider

Classes

AzureBlobServiceStorageClientStores files in Blob Storage, as core's StorageClient: a bucket is a container and a key is a blob name.

import { AzureBlobServiceStorageClient } from "@evolve-framework/cloud-adapter-azure";

new AzureBlobServiceStorageClient(serviceUrl: string, credential?: TokenCredential)

Method	Description
save( bucket: string, key: string, data: string, options?: SaveOptions, ): Promise<void>	Writes data as the object key in bucket, replacing what was stored there, with options.ContentType as its content type.
signUpload( bucket: string, key: string, options: SignedUploadOptions, ): Promise<string>	A SAS cannot bind the Content-Type of a PUT, so the client sets the x-ms-blob-content-type header itself and stat reports what it sent.
signRead( bucket: string, key: string, options: SignedUrlOptions, ): Promise<string>	A URL a client GETs the object from until it expires.
stat(bucket: string, key: string): Promise<StoredObject | undefined>	The object, or undefined when nothing was stored under the key.

EventGridPublisherPublishes internal events to one Event Grid topic as CloudEvents, with the publish options' type and origin as the event's type and source.

import { EventGridPublisher } from "@evolve-framework/cloud-adapter-azure";

new EventGridPublisher(target: string)

Method	Description
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>	Hand a message to the provider.

ServiceBusPublisherPublishes messages to a queue in Azure Service Bus.

import { ServiceBusPublisher } from "@evolve-framework/cloud-adapter-azure";

Handles the authentication and connection to the Service Bus namespace, and holds a long-lived sender that is reused across publish() calls. Call close() on shutdown to release the sender and client.

e.g:

• Service Bus Queue URL https://evolve.servicebus.windows.net/notifications
• Connection String Endpoint=sb://evolve.servicebus.windows.net/;SharedAccessKeyName=your_key_name;SharedAccessKey=your_key;EntityPath=notifications

new ServiceBusPublisher(target: string)

Method	Description
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>	Hand a message to the provider.
close(): Promise<void>	Close the sender, when one was opened, and then the client.

Functions

azureAppConfigSourceReads Azure App Configuration through Microsoft's configuration provider.

import { azureAppConfigSource } from "@evolve-framework/cloud-adapter-azure";

The provider rather than the bare SDK client, because it already does what this source would otherwise reimplement worse: it trims key prefixes, follows Key Vault references, decodes application/json values, retries a failed first load, and re-reads rotated secrets. Feature flags stay out unless asked for, so they need no filtering here.

Its remaining capabilities -- refresh, feature flags -- are reached through providerOptions.

One thing it does differently, and it is worth knowing: references are resolved for everything the selector matches, not only for the fields a config class declares. A namespace holding secrets nothing reads will still have them fetched, so scope keyPrefix to one service rather than at the whole store.

function azureAppConfigSource(
  options: AzureAppConfigSourceOptions,
): ConfigSource

Option	Type	Description
endpoint?	string	The App Configuration endpoint.
credential?	TokenCredential	Azure credential used to reach App Configuration and Key Vault. Defaults to the ambient DefaultAzureCredential.
keyPrefix?	string	The key namespace this source reads, for example /evolve/tst/purchase/. Keys are selected under it, and it is trimmed before folding.
label?	string	Restricts the read to one App Configuration label.
snapshotName?	string	Reads an immutable snapshot instead of the store's live keys, so a release can be pinned to one set of values and an older revision keeps its own. More Nothing creates a snapshot here yet: the azurerm provider has no resource for one, and Terraform would be the wrong place regardless -- a snapshot per release is append-only, so converging on it would destroy the one an older revision still reads. Creating them belongs in the release path, whenever that is worth doing.
prefix?	string	Tried within the namespace before the bare name.
prefixFallback?	boolean
keys?	KeyTransformer
startupTimeoutMs?	number	How long the first load may spend retrying. Configuration is on the critical path at startup, and a role assignment made moments earlier may not have propagated yet, so a transient failure here should not be fatal.
secretRefreshIntervalMs?	number	How often a Key Vault reference is re-read, so a rotated secret reaches the service. The reference in App Configuration does not change when the secret behind it does, so nothing else would notice.
providerOptions?	AzureAppConfigurationOptions	Anything else the provider accepts, merged last: refresh options, feature flags, tag filters.
load?	(() => Promise<LoadedSettings>)	Loads the store. Defaults to the Azure provider; injected in tests, which is the only seam a module-level load leaves.

Returns ConfigSource

createEntraIdCredentialsProviderCreate a Redis credentials provider that authenticates to Azure Managed Redis using Microsoft Entra ID.

import { createEntraIdCredentialsProvider } from "@evolve-framework/cloud-adapter-azure";

Inject the returned provider into the cache at the application composition root — core stays free of any Azure SDK:

import { cache } from "@evolve-framework/core/cache";
import { createEntraIdCredentialsProvider } from "@evolve-framework/cloud-adapter-azure";

await cache.configure({
  url: process.env.REDIS_URL,
  credentialsProvider: createEntraIdCredentialsProvider(),
});

function createEntraIdCredentialsProvider(
  options?: EntraIdCredentialsProviderOptions,
): CredentialsProvider

Option	Type	Description
credential?	TokenCredential	Azure credential used to obtain access tokens. Defaults to the ambient DefaultAzureCredential.
scopes?	string | string[]	OAuth scopes to request. Defaults to the Redis default scope.
expirationRefreshRatio?	number	Refresh the token once this fraction of its lifetime has elapsed. Defaults to 0.8 (refresh after 80% of the token lifetime).

Returns CredentialsProvider

createEventGridHandlerAn Azure Function handler for an Event Grid trigger, handing each event to handler.

import { createEventGridHandler } from "@evolve-framework/cloud-adapter-azure";

function createEventGridHandler(
  handler: MessageHandler<EventGridPartialEvent>,
): FunctionHandler

Returns FunctionHandler

createServiceBusHandlerCreates a Service Bus handler from a given handler function.

import { createServiceBusHandler } from "@evolve-framework/cloud-adapter-azure";

function createServiceBusHandler<T>(
  handler: HandlerFn<T>,
  deserializer?: ((message: unknown) => T),
): ServiceBusQueueHandler

Returns ServiceBusQueueHandler

Types

LoadedSettingsWhat a load hands back: every selected key, with its value resolved.

import { type LoadedSettings } from "@evolve-framework/cloud-adapter-azure";

export type LoadedSettings = ReadonlyMap<string, unknown>;

Not listed: 2 options types. They appear as the tables under the constructors and functions they type.