@visulima/storage 1.0.0-alpha.8 → 1.0.0

package/dist/handler/utils/response-builder.d.ts

@@ -1,83 +0,0 @@
-import type { UploadFile } from "../../storage/utils/index.d.ts";
-import type { Header } from "../../utils/types.d.ts";
-import type { ResponseFile } from "../types.d.ts";
-/**
- * Builds a standard ResponseFile from a file object and headers.
- * @param file The file object to convert to a response
- * @param headers Additional headers to include
- * @param statusCode HTTP status code (default: 200)
- * @returns ResponseFile with file data and headers
- */
-export declare const buildResponseFile: <TFile extends UploadFile>(file: TFile, headers?: Record<string, string | number>, statusCode?: number) => ResponseFile<TFile>;
-/**
- * Builds standard file headers including Location, expiration, and ETag.
- * @param file The file object
- * @param locationUrl The Location header URL
- * @param additionalHeaders Additional headers to merge in
- * @returns Headers object with standard file headers
- */
-export declare const buildFileHeaders: <TFile extends UploadFile>(file: TFile, locationUrl: string, additionalHeaders?: Record<string, string | number>) => Record<string, string | number>;
-/**
- * Builds chunked upload headers for progress tracking.
- * @param file The file object with chunked upload metadata
- * @param isComplete Whether the upload is complete
- * @returns Headers object with chunked upload progress headers
- */
-export declare const buildChunkedUploadHeaders: <TFile extends UploadFile>(file: TFile, isComplete: boolean) => Record<string, string | number>;
-/**
- * Builds a Location header URL for a file.
- * @param requestUrl The request URL or originalUrl
- * @param fileId The file ID
- * @param contentType The file content type (for extension)
- * @param useRelativeLocation Whether to use relative URLs
- * @param baseUrl The base URL (for absolute URLs)
- * @returns Location URL string
- */
-export declare const buildLocationHeader: (requestUrl: string | undefined, fileId: string, contentType: string, useRelativeLocation: boolean, baseUrl?: string) => string;
-/**
- * Builds standard file metadata headers for HEAD requests.
- * @param file The file object
- * @returns Headers object with file metadata
- */
-export declare const buildFileMetadataHeaders: <TFile extends UploadFile>(file: TFile) => Record<string, string | number>;
-/**
- * Converts headers from Record format to string format, handling arrays.
- * @param headers Headers object that may contain arrays
- * @returns Headers object with all values as strings
- */
-export declare const convertHeadersToString: (headers: Record<string, Header>) => Record<string, string>;
-/**
- * Builds an error response body in standard format.
- * @param error The error object
- * @returns Error response body object
- */
-export declare const buildErrorResponseBody: (error: {
-    code?: string;
-    message?: string;
-    name?: string;
-}) => {
-    error: {
-        code: string;
-        message: string;
-        name: string;
-    };
-};
-/**
- * Prepares response body and headers for sending, handling different body types.
- * @param body The response body (string, Buffer, or object)
- * @param headers Existing headers
- * @returns Object with prepared data and headers
- */
-export declare const prepareResponseBody: (body: string | Buffer | object | undefined, headers?: Record<string, string | number>) => {
-    data: Buffer | string;
-    headers: Record<string, string | number>;
-};
-/**
- * Cleans file data for serialization by removing non-serializable properties.
- * @param fileData File data object
- * @returns Cleaned file data object
- */
-export declare const cleanFileData: <TFile extends UploadFile>(fileData: TFile & {
-    content?: unknown;
-    stream?: unknown;
-}) => Omit<TFile, "content" | "stream">;

package/dist/handler/utils/storage-utils.d.ts

@@ -1,10 +0,0 @@
-/**
- * Wait for storage to be ready before handling requests.
- * This ensures storage initialization (e.g., AWS S3, GCS) completes before processing uploads.
- * @param storage Storage instance with isReady property
- * @param timeoutMs Maximum time to wait in milliseconds (default: 5000)
- * @throws Error if storage doesn't become ready within timeout
- */
-export declare const waitForStorage: (storage: {
-    isReady: boolean;
-}, timeoutMs?: number) => Promise<void>;

package/dist/handler/utils/stream-utils.d.ts

@@ -1,29 +0,0 @@
-import type { ServerResponse } from "node:http";
-import type { Readable } from "node:stream";
-/**
- * Creates a range-limited stream that properly handles backpressure.
- * @param sourceStream Source readable stream to limit
- * @param start Start byte position (inclusive)
- * @param end End byte position (inclusive)
- * @returns New readable stream limited to the specified byte range
- */
-export declare const createRangeLimitedStream: (sourceStream: Readable, start: number, end: number) => Readable;
-/**
- * Pipes streams with proper backpressure handling and error management.
- * @param source Source readable stream to pipe from
- * @param destination Destination response stream to pipe to
- * @param sendError Function to send error responses
- */
-export declare const pipeWithBackpressure: <TResponse extends ServerResponse>(source: Readable, destination: TResponse, sendError: (response: TResponse, error: Error) => Promise<void>) => void;
-/**
- * Creates a stream response configuration object.
- * @param stream The readable stream
- * @param size Optional total size of the stream
- * @param headers Optional headers to include
- * @returns Stream response configuration
- */
-export declare const createStreamResponse: (stream: Readable, size?: number, headers?: Record<string, string | number>) => {
-    headers: Record<string, string | number>;
-    size?: number;
-    stream: Readable;
-};

package/dist/handler/utils/upload-handlers.d.ts

@@ -1,76 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { Readable } from "node:stream";
-import type { UploadFile } from "../../storage/utils/index.d.ts";
-import type { ResponseBody, UploadResponse } from "../../utils/types.d.ts";
-import type { ResponseFile, ResponseList } from "../types.d.ts";
-/**
- * Handles HEAD/OPTIONS requests.
- * @param file Response file with headers and status code
- * @param send Function to send response
- */
-export declare const handleHeadOptionsRequest: <TFile extends UploadFile, NodeResponse extends ServerResponse>(file: ResponseFile<TFile>, send: (response: NodeResponse, data: {
-    headers: Record<string, string | number>;
-    statusCode: number;
-}) => void, response: NodeResponse) => void;
-/**
- * Handles GET requests with streaming support.
- * @param file Response file (may contain stream)
- * @param request HTTP request
- * @param response HTTP response
- * @param next Optional Express next function
- * @param send Function to send regular response
- * @param sendStream Function to send stream response
- * @param parseRangeHeader Function to parse range header
- */
-export declare const handleGetRequest: <TFile extends UploadFile, NodeResponse extends ServerResponse>(file: ResponseFile<TFile> | ResponseList<TFile>, request: IncomingMessage, response: NodeResponse, next: (() => void) | undefined, send: (response: NodeResponse, data: UploadResponse<ResponseBody>) => void, sendStream: (response: NodeResponse, stream: Readable, options: {
-    headers: Record<string, string | number>;
-    range?: {
-        end: number;
-        start: number;
-    };
-    size?: number;
-    statusCode: number;
-}) => void, parseRangeHeader: (rangeHeader: string | undefined, fileSize: number) => {
-    end: number;
-    start: number;
-} | undefined) => void;
-/**
- * Handles completed upload responses.
- * @param file Response file
- * @param request HTTP request
- * @param response HTTP response
- * @param next Optional Express next function
- * @param storage Storage instance for onComplete hook
- * @param logger Optional logger
- * @param finish Function to finish the response
- */
-export declare const handleCompletedUpload: <TFile extends UploadFile, NodeResponse extends ServerResponse>(file: ResponseFile<TFile>, request: IncomingMessage, response: NodeResponse, next: (() => void) | undefined, storage: {
-    onComplete: (file: TFile, responseFile: ResponseFile<TFile>, request?: IncomingMessage) => void | Promise<void>;
-}, logger: {
-    error?: (message: string, error: unknown) => void;
-} | undefined, finish: (request: IncomingMessage, response: NodeResponse, uploadResponse: ResponseFile<TFile>) => void) => Promise<void>;
-/**
- * Handles partial upload responses.
- * @param file Response file
- * @param request HTTP request
- * @param response HTTP response
- * @param send Function to send response
- */
-export declare const handlePartialUpload: <TFile extends UploadFile, NodeResponse extends ServerResponse>(file: ResponseFile<TFile>, request: IncomingMessage, response: NodeResponse, send: (response: NodeResponse, data: {
-    body: Buffer | string | undefined;
-    headers: Record<string, string>;
-    statusCode: number;
-}) => void) => void;
-/**
- * Handles errors during upload processing.
- * @param error The error that occurred
- * @param request HTTP request
- * @param emit Function to emit events
- * @param listenerCount Function to count event listeners
- * @param logger Optional logger
- * @param sendError Function to send error response
- * @param response HTTP response
- */
-export declare const handleUploadError: <NodeResponse extends ServerResponse>(error: unknown, request: IncomingMessage, emit: (event: string, data: unknown) => boolean, listenerCount: (event: string) => number, logger: {
-    error?: (message: string, error: unknown) => void;
-} | undefined, sendError: (response: NodeResponse, error: Error) => Promise<void>, response: NodeResponse) => Promise<void>;

package/dist/metrics/index.d.ts

@@ -1,2 +0,0 @@
-export { default as NoOpMetrics } from "./no-op-metrics.d.ts";
-export { default as OpenTelemetryMetrics } from "./opentelemetry-metrics.d.ts";

package/dist/metrics/no-op-metrics.d.ts

@@ -1,15 +0,0 @@
-/**
- * No-op metrics implementation.
- * Used when metrics are not provided, ensuring no overhead when metrics are disabled.
- */
-import type { Metrics } from "../utils/types.d.ts";
-/**
- * No-op metrics that does nothing.
- * Used as a default when metrics are not provided.
- */
-declare class NoOpMetrics implements Metrics {
-    increment(_name: string, _value?: number, _attributes?: Record<string, string | number>): void;
-    timing(_name: string, _duration: number, _attributes?: Record<string, string | number>): void;
-    gauge(_name: string, _value: number, _attributes?: Record<string, string | number>): void;
-}
-export default NoOpMetrics;

package/dist/metrics/opentelemetry-metrics.d.ts

@@ -1,55 +0,0 @@
-/**
- * OpenTelemetry Metrics implementation for storage operations.
- *
- * Provides counters, timers, and gauges using OpenTelemetry Metrics API.
- * This allows integration with any OpenTelemetry-compatible observability backend
- * (Prometheus, Datadog, New Relic, etc.).
- * @example
- * ```typescript
- * import { metrics } from "@opentelemetry/api";
- * import { OpenTelemetryMetrics } from "@visulima/storage/metrics";
- * import { S3Storage } from "@visulima/storage/provider/aws";
- *
- * // Initialize OpenTelemetry (typically done once in your app)
- * const meter = metrics.getMeter("@visulima/storage", "1.0.0");
- *
- * // Create metrics instance
- * const storageMetrics = new OpenTelemetryMetrics(meter);
- *
- * // Use with storage
- * const storage = new S3Storage({
- *     bucket: "my-bucket",
- *     metrics: storageMetrics,
- * });
- * ```
- */
-import type { Meter } from "@opentelemetry/api";
-import type { Metrics } from "../utils/types.d.ts";
-/**
- * OpenTelemetry-based metrics implementation.
- */
-declare class OpenTelemetryMetrics implements Metrics {
-    private readonly meter;
-    private readonly counters;
-    private readonly histograms;
-    private readonly gauges;
-    /**
-     * Creates a new OpenTelemetryMetrics instance.
-     * @param meter OpenTelemetry Meter instance. If not provided, uses the default meter.
-     * @throws {Error} If \@opentelemetry/api is not installed
-     */
-    constructor(meter?: Meter);
-    /**
-     * Increment a counter metric.
-     */
-    increment(name: string, value?: number, attributes?: Record<string, string | number>): void;
-    /**
-     * Record a duration/timing metric in milliseconds.
-     */
-    timing(name: string, duration: number, attributes?: Record<string, string | number>): void;
-    /**
-     * Set a gauge metric value.
-     */
-    gauge(name: string, value: number, attributes?: Record<string, string | number>): void;
-}
-export default OpenTelemetryMetrics;

package/dist/openapi/rest.d.ts

@@ -1,7 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-declare const swaggerSpec: (origin: string, path: string, options: {
-    supportedTransformerFormat?: string[];
-    tags?: string[] | undefined;
-    transformer?: boolean | "audio" | "video" | "image";
-}) => Partial<OpenAPIV3.Document>;
-export default swaggerSpec;

package/dist/openapi/shared.d.ts

@@ -1,13 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-type TransformType = boolean | "audio" | "video" | "image";
-declare const getOrganizedTransformationParameters: (transform?: TransformType, format?: string[]) => {
-    groups: Record<string, string[]>;
-    parameters: OpenAPIV3.ParameterObject[];
-};
-export { getOrganizedTransformationParameters };
-export declare const sharedGet: (operationId: string, tags: string[] | undefined, transform?: TransformType, transformerFormat?: string[]) => OpenAPIV3.OperationObject;
-export declare const sharedGetMeta: (operationId: string, tags: string[] | undefined) => OpenAPIV3.OperationObject;
-export declare const sharedErrorSchemaObject: Record<string, OpenAPIV3.NonArraySchemaObject>;
-export declare const sharedFileMetaSchemaObject: Record<string, OpenAPIV3.NonArraySchemaObject>;
-export declare const sharedFileMetaExampleObject: Record<string, OpenAPIV3.ExampleObject>;
-export declare const sharedGetList: (operationId: string, tags: string[] | undefined) => OpenAPIV3.OperationObject;

package/dist/openapi/transform.d.ts

@@ -1,3 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-declare const swaggerSpec: (path?: string, tags?: string[] | undefined) => Partial<OpenAPIV3.Document>;
-export default swaggerSpec;

package/dist/openapi/tus.d.ts

@@ -1,7 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-declare const swaggerSpec: (path: string, options: {
-    supportedTransformerFormat?: string[];
-    tags?: string[] | undefined;
-    transformer?: boolean | "audio" | "video" | "image";
-}) => Partial<OpenAPIV3.Document>;
-export default swaggerSpec;

package/dist/openapi/xhr.d.ts

@@ -1,7 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-declare const swaggerSpec: (origin: string, path: string, options: {
-    supportedTransformerFormat?: string[];
-    tags?: string[] | undefined;
-    transformer?: boolean | "audio" | "video" | "image";
-}) => Partial<OpenAPIV3.Document>;
-export default swaggerSpec;

package/dist/packem_shared/AwsLightFile-tTneXZgG.js

@@ -1,11 +0,0 @@
-import File from './File-Bb3P23dr.js';
-
-class AwsLightFile extends File {
-  Parts;
-  UploadId;
-  uri;
-  partsUrls;
-  partSize;
-}
-
-export { AwsLightFile as default };

package/dist/packem_shared/AwsLightMetaStorage-BWSOtVaN.js

@@ -1,4 +0,0 @@
-import './MetaStorage-pECeFOad.js';
-import './Metadata-DRLXeJ0F.js';
-export { A as default } from './aws-light-meta-storage-DKJBgbR6.js';
-import './is-expired-CTThU1q5.js';

package/dist/packem_shared/AwsLightStorage-Blv-GP4v.js

@@ -1,133 +0,0 @@
-import { Readable } from 'node:stream';
-import { S as S3BaseStorage } from './s3-base-storage-C1DIHTYY.js';
-import { a as AwsLightApiAdapter, A as AwsLightMetaStorage } from './aws-light-meta-storage-DKJBgbR6.js';
-import AwsLightFile from './AwsLightFile-tTneXZgG.js';
-
-class AwsLightStorage extends S3BaseStorage {
-  static name = "aws-light";
-  s3Api;
-  constructor(config) {
-    const { bucket = process.env.S3_BUCKET || process.env.AWS_S3_BUCKET, region = process.env.S3_REGION || process.env.AWS_REGION } = config;
-    if (!bucket) {
-      throw new Error("S3 bucket is not defined");
-    }
-    if (!region) {
-      throw new Error("S3 region is not defined");
-    }
-    if (!config.accessKeyId) {
-      throw new Error("accessKeyId is required");
-    }
-    if (!config.secretAccessKey) {
-      throw new Error("secretAccessKey is required");
-    }
-    super({
-      bucket,
-      clientDirectUpload: config.clientDirectUpload,
-      expiration: config.expiration?.maxAge ? { maxAge: String(config.expiration.maxAge) } : void 0,
-      filename: config.filename,
-      logger: config.logger,
-      metaStorage: config.metaStorage,
-      metaStorageConfig: config.metaStorageConfig ? { ...config.metaStorageConfig, ...config } : { ...config },
-      partSize: config.partSize,
-      retryConfig: {
-        ...config.retryConfig,
-        shouldRetry: (error) => {
-          const errorWithStatus = error;
-          if (errorWithStatus.statusCode && [408, 429, 500, 502, 503, 504].includes(errorWithStatus.statusCode)) {
-            return true;
-          }
-          return errorWithStatus.retryable ?? false;
-        }
-      }
-    });
-    this.s3Api = new AwsLightApiAdapter({
-      accessKeyId: config.accessKeyId,
-      bucket,
-      endpoint: config.endpoint,
-      region,
-      secretAccessKey: config.secretAccessKey,
-      service: config.service,
-      sessionToken: config.sessionToken
-    });
-    const { metaStorage, metaStorageConfig } = config;
-    if (!metaStorage) {
-      const metaConfig = { ...config, ...metaStorageConfig, logger: this.logger };
-      this.meta = new AwsLightMetaStorage(metaConfig);
-    }
-  }
-  /**
-   * Normalizes AWS S3 errors with S3-specific context.
-   */
-  normalizeError(error) {
-    const awsError = error;
-    if (awsError.statusCode || awsError.code) {
-      return {
-        code: awsError.code || awsError.name,
-        message: awsError.message,
-        name: awsError.name,
-        statusCode: awsError.statusCode || 500
-      };
-    }
-    return super.normalizeError(error);
-  }
-  async update({ id }, metadata) {
-    if (this.config.clientDirectUpload) {
-      const file = await this.getMeta(id);
-      return this.buildPresigned({ ...file, ...metadata });
-    }
-    return super.update({ id }, metadata);
-  }
-  async getStream({ id }) {
-    return this.instrumentOperation("getStream", async () => {
-      const s3Api = this.getS3Api();
-      const { Body, ContentLength, ContentType, ETag, Expires, LastModified } = await this.retry(
-        () => s3Api.getObject({
-          Bucket: this.bucket,
-          Key: id
-        })
-      );
-      await this.checkIfExpired({ expiredAt: Expires });
-      const stream = Body instanceof ReadableStream ? Readable.fromWeb(Body) : Body;
-      const readableStream = new Readable({
-        read() {
-          stream.on("data", (chunk) => {
-            this.push(chunk);
-          });
-          stream.on("end", () => {
-            this.push(null);
-          });
-          stream.on("error", (error) => {
-            this.destroy(error);
-          });
-        }
-      });
-      return {
-        headers: {
-          "Content-Length": ContentLength?.toString() ?? "0",
-          "Content-Type": ContentType,
-          ...ETag && { ETag },
-          ...Expires && { "X-Upload-Expires": Expires.toString() },
-          ...LastModified && { "Last-Modified": LastModified.toString() }
-        },
-        size: Number(ContentLength),
-        stream: readableStream
-      };
-    });
-  }
-  getS3Api() {
-    return this.s3Api;
-  }
-  // eslint-disable-next-line class-methods-use-this
-  getFileClass() {
-    return AwsLightFile;
-  }
-  // eslint-disable-next-line class-methods-use-this
-  getAcl() {
-    return void 0;
-  }
-  async accessCheck(_maxWaitTime = 30) {
-    await this.s3Api.checkBucketAccess({ Bucket: this.bucket });
-  }
-}
-
-export { AwsLightStorage as default };

package/dist/packem_shared/AzureFile-CesgFzps.js

@@ -1,8 +0,0 @@
-import File from './File-Bb3P23dr.js';
-
-class AzureFile extends File {
-  requestId;
-  uri;
-}
-
-export { AzureFile as default };

package/dist/packem_shared/AzureSMetaStorage-CFs-OYJT.js

@@ -1,88 +0,0 @@
-import { BlobServiceClient, StorageSharedKeyCredential } from '@azure/storage-blob';
-import { throwErrorCode, ERRORS } from './ERRORS-D0apMqnc.js';
-import MetaStorage from './MetaStorage-pECeFOad.js';
-import { parseMetadata, stringifyMetadata } from './Metadata-DRLXeJ0F.js';
-
-class AzureMetaStorage extends MetaStorage {
-  constructor(config) {
-    super(config);
-    this.config = config;
-    const { client, ...metaConfig } = config;
-    if (client === void 0) {
-      const connectionString = metaConfig.connectionString || process.env.AZURE_STORAGE_CONNECTION_STRING || void 0;
-      if (connectionString) {
-        this.client = BlobServiceClient.fromConnectionString(connectionString);
-      } else {
-        const accountKey = metaConfig.accountKey || process.env.AZURE_STORAGE_ACCOUNT_KEY || void 0;
-        const accountName = metaConfig.accountName || process.env.AZURE_STORAGE_ACCOUNT || void 0;
-        if (!metaConfig.accountKey) {
-          throw new Error("Missing required parameter: Azure blob storage account key.");
-        }
-        if (!metaConfig.accountName) {
-          throw new Error("Missing required parameter: Azure blob storage account name.");
-        }
-        const signedCredentials = new StorageSharedKeyCredential(accountName, accountKey);
-        this.client = new BlobServiceClient(config.endpoint ?? `https://${accountName}.blob.core.windows.net`, signedCredentials);
-      }
-    } else {
-      this.client = client;
-    }
-    const containerName = metaConfig.containerName || process.env.AZURE_STORAGE_CONTAINER || void 0;
-    if (!containerName) {
-      throw new Error("Missing required parameter: Azure container name.");
-    }
-    this.containerClient = this.client.getContainerClient(metaConfig.containerName);
-  }
-  client;
-  containerClient;
-  async get(id) {
-    const appendBlobClient = this.containerClient.getAppendBlobClient(this.getMetaName(id));
-    let propertyData;
-    try {
-      propertyData = await appendBlobClient.getProperties();
-    } catch {
-      throw throwErrorCode(ERRORS.UNKNOWN_ERROR);
-    }
-    if (!propertyData.metadata) {
-      throw throwErrorCode(ERRORS.FILE_NOT_FOUND);
-    }
-    const file = propertyData.metadata;
-    if (file.metadata && typeof file.metadata === "string") {
-      file.metadata = parseMetadata(file.metadata);
-    }
-    return file;
-  }
-  async touch(id, file) {
-    return this.save(id, file);
-  }
-  async delete(id) {
-    const blobClient = this.containerClient.getBlockBlobClient(this.getMetaName(id));
-    await blobClient.deleteIfExists();
-  }
-  async save(id, file) {
-    const transformedMetadata = { ...file };
-    if (transformedMetadata.metadata) {
-      transformedMetadata.metadata = stringifyMetadata(file.metadata);
-    }
-    const appendBlobClient = this.containerClient.getAppendBlobClient(this.getMetaName(id));
-    await appendBlobClient.setMetadata(transformedMetadata, {});
-    return file;
-  }
-  async list() {
-    const blobs = [];
-    const iterator = this.containerClient.listBlobsFlat({
-      prefix: this.prefix
-    });
-    for await (const blob of iterator) {
-      blobs.push(blob);
-    }
-    return blobs.filter((blob) => blob.name.endsWith(this.suffix)).map((blob) => {
-      return {
-        createdAt: blob.properties.createdOn,
-        id: this.getIdFromMetaName(blob.name)
-      };
-    });
-  }
-}
-
-export { AzureMetaStorage as default };