@qrvey/object-storage 2.0.1-1165 → 2.0.3-beta

package/dist/types/index-v2.d.ts

@@ -1,417 +0,0 @@
-import { Readable } from 'stream';
-import { AwsCredentialIdentity } from '@aws-sdk/types';
-import { S3Client } from '@aws-sdk/client-s3';
-import { BlobServiceClient } from '@azure/storage-blob';
-
-interface StorageErrorOptions {
-    code: string;
-    message: string;
-    retryable: boolean;
-    provider?: string;
-    requestId?: string;
-    cause?: unknown;
-}
-type SubclassOptions = Omit<StorageErrorOptions, 'code' | 'retryable'> & {
-    code?: string;
-    retryable?: boolean;
-};
-declare class StorageError extends Error {
-    readonly code: string;
-    readonly retryable: boolean;
-    readonly provider?: string;
-    readonly requestId?: string;
-    readonly cause?: unknown;
-    constructor(options: StorageErrorOptions);
-}
-interface ThrottledErrorOptions extends SubclassOptions {
-    retryAfterMs?: number;
-}
-declare class ThrottledError extends StorageError {
-    readonly retryAfterMs?: number;
-    constructor(options: ThrottledErrorOptions);
-}
-declare class NotFoundError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-declare class AuthError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-declare class ValidationError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-declare class ConfigurationError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-declare class NetworkError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-declare class IntegrityError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-declare class MultipartSessionError extends StorageError {
-    constructor(options: SubclassOptions);
-}
-
-interface ObjectSummary {
-    key: string;
-    size?: number;
-    etag?: string;
-    lastModified?: Date;
-}
-interface ListOptions {
-    prefix?: string;
-    limit?: number;
-    continuationToken?: string;
-}
-interface ListResult {
-    items: ObjectSummary[];
-    nextToken?: string;
-}
-interface IterateOptions {
-    prefix?: string;
-    pageSize?: number;
-}
-interface GetObjectOptions {
-    range?: string;
-    versionId?: string;
-}
-interface GetObjectResult {
-    body: Readable;
-    contentLength?: number;
-    contentType?: string;
-    contentEncoding?: string;
-    contentDisposition?: string;
-    contentLanguage?: string;
-    cacheControl?: string;
-    etag?: string;
-    lastModified?: Date;
-    metadata?: Record<string, string>;
-}
-interface ObjectProperties {
-    contentLength?: number;
-    contentType?: string;
-    etag?: string;
-    lastModified?: Date;
-    metadata?: Record<string, string>;
-}
-type UploadBody = Buffer | Uint8Array | string | Readable;
-interface UploadOptions {
-    contentType?: string;
-    contentEncoding?: string;
-    cacheControl?: string;
-    contentDisposition?: string;
-    metadata?: Record<string, string>;
-    partSizeBytes?: number;
-    queueSize?: number;
-}
-interface UploadResult {
-    key: string;
-    etag?: string;
-    versionId?: string;
-}
-interface WriteStreamResult {
-    stream: NodeJS.WritableStream;
-    done: Promise<UploadResult>;
-    abort: () => Promise<void>;
-}
-interface DeleteManyResult {
-    key: string;
-    deleted: boolean;
-    error?: string;
-}
-interface HeadBucketResult {
-    exists: boolean;
-    metadata?: Record<string, string>;
-}
-interface PresignOptions {
-    expiresInSeconds?: number;
-    contentType?: string;
-}
-interface PresignedUpload {
-    key: string;
-    url: string;
-}
-interface MultipartPart {
-    partNumber: number;
-    etag: string;
-}
-interface MultipartPartSummary extends MultipartPart {
-    size?: number;
-    lastModified?: Date;
-}
-interface MultipartUploadSummary {
-    key: string;
-    uploadId: string;
-    initiatedAt?: Date;
-}
-interface MultipartClient {
-    create(key: string, options?: UploadOptions): Promise<{
-        uploadId: string;
-    }>;
-    uploadPart(key: string, uploadId: string, partNumber: number, body: UploadBody, contentLengthBytes?: number): Promise<MultipartPart>;
-    getPartUploadUrl(key: string, uploadId: string, partNumber: number, options?: PresignOptions): Promise<string>;
-    complete(key: string, uploadId: string, parts: MultipartPart[]): Promise<UploadResult>;
-    abort(key: string, uploadId: string): Promise<void>;
-    listParts(key: string, uploadId: string): Promise<MultipartPartSummary[]>;
-    listUploads(prefix?: string): Promise<MultipartUploadSummary[]>;
-}
-interface ObjectStorageClient {
-    readonly bucketName: string;
-    readonly multipart: MultipartClient;
-    getObject(key: string, options?: GetObjectOptions): Promise<GetObjectResult>;
-    getObjectProperties(key: string): Promise<ObjectProperties>;
-    upload(key: string, body: UploadBody, options?: UploadOptions): Promise<UploadResult>;
-    createWriteStream(key: string, options?: UploadOptions): WriteStreamResult;
-    delete(key: string): Promise<void>;
-    deleteMany(keys: string[]): Promise<DeleteManyResult[]>;
-    list(options?: ListOptions): Promise<ListResult>;
-    listAll(options?: IterateOptions): Promise<ObjectSummary[]>;
-    iterate(options?: IterateOptions): AsyncIterable<ObjectSummary>;
-    headBucket(): Promise<HeadBucketResult>;
-    getDownloadUrl(key: string, options?: PresignOptions): Promise<string>;
-    getUploadUrl(key: string, options?: PresignOptions): Promise<PresignedUpload>;
-}
-
-interface HttpOptions {
-    connectionTimeoutMs?: number;
-    requestTimeoutMs?: number;
-    maxSockets?: number;
-}
-interface BaseStorageOptions {
-    provider: string;
-    endpoint?: string;
-    http?: HttpOptions;
-}
-/**
- * Open registry of provider option types, augmented by each provider via
- * declaration merging so new providers never require editing core:
- *
- * declare module '../../core/config' {
- *     interface ProviderOptionsRegistry {
- *         'aws_s3': AwsS3StorageOptions;
- *     }
- * }
- */
-interface ProviderOptionsRegistry {
-}
-type ObjectStorageOptions = ProviderOptionsRegistry[keyof ProviderOptionsRegistry];
-
-declare function resolveOptionsFromEnv(env?: NodeJS.ProcessEnv): ObjectStorageOptions;
-declare function resolveObjectStorageOptions(options?: ObjectStorageOptions, env?: NodeJS.ProcessEnv): ObjectStorageOptions;
-
-interface RetryPolicy {
-    numOfAttempts?: number;
-    startingDelayMs?: number;
-    maxDelayMs?: number;
-    retry?: (error: unknown, attempt: number) => boolean;
-}
-declare function isRetryableError(error: unknown): boolean;
-declare function withRetry<T>(fn: () => Promise<T>, policy?: RetryPolicy): Promise<T>;
-
-interface LimiterOptions {
-    max: number;
-    adaptive?: boolean;
-    minMax?: number;
-    growthThreshold?: number;
-}
-interface Limiter {
-    run<T>(fn: () => Promise<T>): Promise<T>;
-    readonly inFlight: number;
-    readonly pending: number;
-    readonly currentMax: number;
-}
-declare function createLimiter(options: LimiterOptions): Limiter;
-
-declare function chunk<T>(items: readonly T[], size: number): T[][];
-declare function mapBatched<T, R>(items: readonly T[], batchSize: number, limiter: Limiter, fn: (batch: T[], index: number) => Promise<R>): Promise<R[]>;
-
-interface ByteRange {
-    start?: number;
-    end?: number;
-    suffixLength?: number;
-}
-declare function parseRange(input: string): ByteRange;
-declare function toRangeHeader(range: ByteRange): string;
-
-declare const AWS_S3_PROVIDER_ID: "aws_s3";
-type AwsS3Auth = {
-    kind: 'default';
-} | {
-    kind: 'static';
-    credentials: AwsCredentialIdentity;
-} | {
-    kind: 'assumeRole';
-    roleArn: string;
-    externalId?: string;
-} | {
-    kind: 'webIdentity';
-    roleArn: string;
-    tokenFile?: string;
-};
-interface AwsS3StorageOptions extends BaseStorageOptions {
-    provider: typeof AWS_S3_PROVIDER_ID;
-    region: string;
-    auth?: AwsS3Auth;
-}
-declare module '../../core/config' {
-    interface ProviderOptionsRegistry {
-        aws_s3: AwsS3StorageOptions;
-    }
-}
-declare function isAwsS3StorageOptions(options: BaseStorageOptions): options is AwsS3StorageOptions;
-declare function getDefaultAwsS3OptionsFromEnv(env?: NodeJS.ProcessEnv): AwsS3StorageOptions;
-
-declare function getAwsS3Client(options: AwsS3StorageOptions): S3Client;
-declare function clearAwsS3ClientCache(): void;
-
-declare function mapAwsError(error: unknown): StorageError;
-
-interface AwsS3ProviderConfig {
-    bucketName: string;
-    options?: AwsS3StorageOptions;
-    retry?: RetryPolicy;
-    limiter?: Limiter;
-}
-declare class AwsS3Provider implements ObjectStorageClient {
-    readonly bucketName: string;
-    readonly multipart: MultipartClient;
-    private readonly client;
-    private readonly retryPolicy;
-    private readonly limiter;
-    constructor(config: AwsS3ProviderConfig);
-    private send;
-    getObject(key: string, options?: GetObjectOptions): Promise<GetObjectResult>;
-    getObjectProperties(key: string): Promise<ObjectProperties>;
-    upload(key: string, body: UploadBody, options?: UploadOptions): Promise<UploadResult>;
-    private uploadStream;
-    createWriteStream(key: string, options?: UploadOptions): WriteStreamResult;
-    delete(key: string): Promise<void>;
-    deleteMany(keys: string[]): Promise<DeleteManyResult[]>;
-    list(options?: ListOptions): Promise<ListResult>;
-    iterate(options?: IterateOptions): AsyncIterable<ObjectSummary>;
-    listAll(options?: IterateOptions): Promise<ObjectSummary[]>;
-    headBucket(): Promise<HeadBucketResult>;
-    getDownloadUrl(key: string, options?: PresignOptions): Promise<string>;
-    getUploadUrl(key: string, options?: PresignOptions): Promise<PresignedUpload>;
-}
-
-declare const AZURE_BLOB_PROVIDER_ID: "azure_blob_storage";
-type AzureBlobAuth = {
-    kind: 'connectionString';
-    connectionString: string;
-} | {
-    kind: 'accountKey';
-    accountName: string;
-    accountKey: string;
-} | {
-    kind: 'sas';
-    accountName: string;
-    sasToken: string;
-} | {
-    kind: 'workloadIdentity';
-    accountName: string;
-};
-interface AzureBlobStorageOptions extends BaseStorageOptions {
-    provider: typeof AZURE_BLOB_PROVIDER_ID;
-    auth: AzureBlobAuth;
-}
-declare module '../../core/config' {
-    interface ProviderOptionsRegistry {
-        azure_blob_storage: AzureBlobStorageOptions;
-    }
-}
-declare function isAzureBlobStorageOptions(options: BaseStorageOptions): options is AzureBlobStorageOptions;
-declare function getDefaultAzureBlobOptionsFromEnv(env?: NodeJS.ProcessEnv): AzureBlobStorageOptions;
-
-declare function getAzureBlobServiceClient(options: AzureBlobStorageOptions): BlobServiceClient;
-declare function clearAzureBlobClientCache(): void;
-
-declare function mapAzureError(error: unknown): StorageError;
-
-interface MultipartBlockRecord {
-    blockId: string;
-    partNumber: number;
-}
-interface MultipartSession {
-    uploadId: string;
-    blobName: string;
-    containerName: string;
-    blocks: MultipartBlockRecord[];
-    createdAt: number;
-}
-/**
- * Azure has no native multipart upload sessions (S3 UploadId semantics).
- * This store tracks which staged blocks belong to which logical upload so
- * concurrent uploads to the same blob name cannot corrupt each other.
- * Default in-memory implementation is single-process only — multi-pod
- * deployments doing distributed multipart must inject a shared store (Redis).
- */
-interface MultipartSessionStore {
-    create(session: MultipartSession): Promise<void>;
-    get(uploadId: string): Promise<MultipartSession | undefined>;
-    appendBlock(uploadId: string, block: MultipartBlockRecord): Promise<void>;
-    delete(uploadId: string): Promise<void>;
-    list(containerName: string, blobNamePrefix?: string): Promise<MultipartSession[]>;
-}
-declare class InMemoryMultipartSessionStore implements MultipartSessionStore {
-    private readonly ttlMs;
-    private readonly sessions;
-    constructor(ttlMs?: number);
-    create(session: MultipartSession): Promise<void>;
-    get(uploadId: string): Promise<MultipartSession | undefined>;
-    appendBlock(uploadId: string, block: MultipartBlockRecord): Promise<void>;
-    delete(uploadId: string): Promise<void>;
-    list(containerName: string, blobNamePrefix?: string): Promise<MultipartSession[]>;
-    private isExpired;
-    private evictExpired;
-}
-
-interface AzureBlobStorageProviderConfig {
-    bucketName: string;
-    options?: AzureBlobStorageOptions;
-    retry?: RetryPolicy;
-    limiter?: Limiter;
-    multipartStore?: MultipartSessionStore;
-}
-declare class AzureBlobStorageProvider implements ObjectStorageClient {
-    readonly bucketName: string;
-    readonly multipart: MultipartClient;
-    private readonly serviceClient;
-    private readonly container;
-    private readonly retryPolicy;
-    private readonly limiter;
-    constructor(config: AzureBlobStorageProviderConfig);
-    private send;
-    private block;
-    getObject(key: string, options?: GetObjectOptions): Promise<GetObjectResult>;
-    private resolveRange;
-    getObjectProperties(key: string): Promise<ObjectProperties>;
-    upload(key: string, body: UploadBody, options?: UploadOptions): Promise<UploadResult>;
-    createWriteStream(key: string, options?: UploadOptions): WriteStreamResult;
-    delete(key: string): Promise<void>;
-    deleteMany(keys: string[]): Promise<DeleteManyResult[]>;
-    list(options?: ListOptions): Promise<ListResult>;
-    iterate(options?: IterateOptions): AsyncIterable<ObjectSummary>;
-    listAll(options?: IterateOptions): Promise<ObjectSummary[]>;
-    headBucket(): Promise<HeadBucketResult>;
-    getDownloadUrl(key: string, options?: PresignOptions): Promise<string>;
-    getUploadUrl(key: string, options?: PresignOptions): Promise<PresignedUpload>;
-    private generateSasUrl;
-}
-
-/**
- * Returns a cached `ObjectStorageClient` for a bucket. The concrete provider
- * (AWS S3 or Azure Blob) is resolved from `options` or the environment — callers
- * (services, `@repo` wrappers) never pick a provider or manage caching.
- */
-declare function getObjectStorageClient(bucket: string, options?: ObjectStorageOptions): ObjectStorageClient;
-/** Test/teardown helper. */
-declare function clearObjectStorageClientCache(): void;
-
-declare const OBJECT_STORAGE_PROVIDERS: Readonly<{
-    readonly AWS_S3: "aws_s3";
-    readonly AZURE_BLOB_STORAGE: "azure_blob_storage";
-}>;
-type ObjectStorageProvider = (typeof OBJECT_STORAGE_PROVIDERS)[keyof typeof OBJECT_STORAGE_PROVIDERS];
-
-export { AWS_S3_PROVIDER_ID, AZURE_BLOB_PROVIDER_ID, AuthError, AwsS3Auth, AwsS3Provider, AwsS3ProviderConfig, AwsS3StorageOptions, AzureBlobAuth, AzureBlobStorageOptions, AzureBlobStorageProvider, AzureBlobStorageProviderConfig, BaseStorageOptions, ByteRange, ConfigurationError, DeleteManyResult, GetObjectOptions, GetObjectResult, HeadBucketResult, HttpOptions, InMemoryMultipartSessionStore, IntegrityError, IterateOptions, Limiter, LimiterOptions, ListOptions, ListResult, MultipartBlockRecord, MultipartClient, MultipartPart, MultipartPartSummary, MultipartSession, MultipartSessionError, MultipartSessionStore, MultipartUploadSummary, NetworkError, NotFoundError, OBJECT_STORAGE_PROVIDERS, ObjectProperties, ObjectStorageClient, ObjectStorageOptions, ObjectStorageProvider, ObjectSummary, PresignOptions, PresignedUpload, ProviderOptionsRegistry, RetryPolicy, StorageError, StorageErrorOptions, ThrottledError, ThrottledErrorOptions, UploadBody, UploadOptions, UploadResult, ValidationError, WriteStreamResult, chunk, clearAwsS3ClientCache, clearAzureBlobClientCache, clearObjectStorageClientCache, createLimiter, getAwsS3Client, getAzureBlobServiceClient, getDefaultAwsS3OptionsFromEnv, getDefaultAzureBlobOptionsFromEnv, getObjectStorageClient, isAwsS3StorageOptions, isAzureBlobStorageOptions, isRetryableError, mapAwsError, mapAzureError, mapBatched, parseRange, resolveObjectStorageOptions, resolveOptionsFromEnv, toRangeHeader, withRetry };