@microsoft/rayfin-storage

Type-safe client SDK for experimental Rayfin Storage folders, including client composition, operation options, result shapes, and error codes.

@microsoft/rayfin-storage is the typed client for Rayfin Storage folders declared with @blob().

Experimental Changed in 1.36

Warning

Storage is experimental and is not available in every Fabric region or tenant. Enable it with services.storage.enabled: true or RAYFIN_FEATURE_FLAGS=storage before relying on storage CLI commands or agent skills.

Installation

Install the exact same version as every other @microsoft/rayfin-* package in the project:

npm install @microsoft/rayfin-storage@1.36.2

Exports

export { StorageFolderClient } from './StorageFolderClient.js';
export { StorageApi, createStorageClient } from './StorageClient.js';
export type {
  StorageClient,
  StorageCustomFields,
  StorageDeleteResult,
  StorageDownloadResult,
  StorageError,
  StorageErrorCode,
  StorageListResult,
  StorageObjectRef,
  StorageSchema,
  StorageUploadResult,
  UploadOptions,
  DownloadOptions,
  DeleteOptions,
  ListOptions,
} from '@microsoft/rayfin-storage';
export { STORAGE_ERROR_CODES, isStorageError } from '@microsoft/rayfin-storage';

StorageConflictMode and UploadProgressEvent are not exported in 1.36. Removed in 1.36

Client shape

function createStorageClient<TSchema extends StorageSchema>(apiClient: ApiClient): StorageClient<TSchema>;

class StorageApi<TSchema extends StorageSchema = StorageSchema> extends ServicePlugin {
  getFolderClient<K extends keyof TSchema & string>(
    folderName: K
  ): StorageFolderClient<StorageObjectRef & Partial<StorageCustomFields<TSchema[K]>>>;
  getInstantiatedFolderNames(): (keyof TSchema)[];
}

type StorageClient<TSchema extends StorageSchema> = {
  [K in keyof TSchema]: StorageFolderClient<
    StorageObjectRef & Partial<StorageCustomFields<TSchema[K]>>
  >;
} & StorageApi<TSchema>;

Custom metadata fields declared on the @blob() class are optional on returned objects. The SDK omits intrinsic storage fields and StorageObject fields from StorageCustomFields<T>.

`StorageObjectRef`

interface StorageObjectRef {
  id: string;
  folder: string;
  path: string;
  name: string;
  size: number;
  sizeBig?: bigint;
  contentType?: string;
  contentDisposition?: string;
  cacheControl?: string;
  createdAt?: string;
  updatedAt?: string;
  lastAccessedAt?: string | null;
  etag?: string;
}

storedPath and userMetadata are no longer part of StorageObjectRef. Custom list metadata is flattened onto the returned item instead. Removed in 1.36

Operation signatures

class StorageFolderClient<TObject extends StorageObjectRef = StorageObjectRef> {
  upload(
    name: string,
    data: Blob | ArrayBuffer | Uint8Array | ReadableStream | string,
    options?: UploadOptions<TObject>
  ): Promise<StorageUploadResult<TObject>>;

  download(name: string, options?: DownloadOptions): Promise<StorageDownloadResult>;
  list(options?: ListOptions): Promise<StorageListResult<TObject>>;
  delete(name: string, options?: DeleteOptions): Promise<StorageDeleteResult>;
}

Option type	Properties
`UploadOptions<TObject>`	`prefix?`, `signal?`, `contentType?`, `contentDisposition?`, `cacheControl?`, `expiresInSeconds?`, `fields?: Partial<StorageCustomFields<TObject>>`
`DownloadOptions`	`prefix?`, `signal?`, `expiresInSeconds?`
`ListOptions`	`prefix?`, `limit?`, `continuation?`, `signal?`
`DeleteOptions`	`prefix?`, `signal?`

declaredSize, onProgress, userMetadata, per-call onConflict, download range, download content header overrides, and caller-supplied correlationId are removed. Removed in 1.36

Results

interface StorageUploadResult<TObject = StorageObjectRef> {
  object: TObject;
  correlationId: string;
}

interface StorageDownloadResult {
  stream: ReadableStream<Uint8Array>;
  contentType?: string;
  contentDisposition?: string;
  contentLength?: number;
  etag?: string;
  correlationId: string;
}

interface StorageListResult<TObject = StorageObjectRef> {
  items: TObject[];
  continuation?: string;
  correlationId: string;
}

interface StorageDeleteResult {
  success: boolean;
  deleted: number;
  correlationId: string;
}

download().contentDisposition is the value returned by OneLake when present; the SDK does not synthesize it. Changed in 1.36

Errors

interface StorageError extends Error {
  code: StorageErrorCode;
  status: number;
  correlationId: string;
  response?: Response;
  retryable: boolean;
}

Stable codes are exported as STORAGE_ERROR_CODES: InvalidFolder, InvalidPath, InvalidName, InvalidPrefix, InvalidSasExpiry, TooLarge, UnsupportedContentType, Conflict, NotFound, PermissionDenied, Unauthenticated, InvalidContinuation, UploadSessionExpired, CommitFailed, RateLimited, Unexpected, Aborted, MissingOrMalformedOperationId, and NoStorageEntitiesConfigured.

Something wrong on this page?Report an issueEdit this page