@visulima/storage 1.0.0-alpha.1 → 1.0.0-alpha.3

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

@@ -0,0 +1,76 @@
+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/index.d.ts

@@ -0,0 +1,17 @@
+export { waitForStorage } from "./handler/utils/storage-utils.d.ts";
+export { NoOpMetrics, OpenTelemetryMetrics } from "./metrics/index.d.ts";
+export { default as DiskStorage } from "./storage/local/disk-storage.d.ts";
+export { default as DiskStorageWithChecksum } from "./storage/local/disk-storage-with-checksum.d.ts";
+export type { LocalMetaStorageOptions } from "./storage/local/local-meta-storage.d.ts";
+export { default as LocalMetaStorage } from "./storage/local/local-meta-storage.d.ts";
+export { default as MetaStorage } from "./storage/meta-storage.d.ts";
+export { BaseStorage as AbstractBaseStorage, defaultCloudStorageFileNameValidation, defaultFilesystemFileNameValidation } from "./storage/storage.d.ts";
+export type { BaseStorageOptions, BatchOperationResponse, BatchOperationResult, DiskStorageOptions, DiskStorageWithChecksumOptions, ExpirationOptions, MetaStorageOptions, OnComplete, OnCreate, OnDelete, OnError, OnUpdate, PurgeList, } from "./storage/types.d.ts";
+export type { FileInit, FilePart, FileQuery, UploadEventType, UploadFile } from "./storage/utils/file/index.d.ts";
+export { File, Metadata } from "./storage/utils/file/index.d.ts";
+export { ErrorMap, ERRORS, isUploadError, throwErrorCode, UploadError } from "./utils/errors.d.ts";
+export type { RetryConfig } from "./utils/retry.d.ts";
+export { createRetryWrapper, isRetryableError, retry } from "./utils/retry.d.ts";
+export type { Header, Headers, HttpError, HttpErrorBody, IncomingMessageWithBody, Metrics, RangeChecksum, RangeHasher, ResponseBody, ResponseBodyType, ResponseTuple, UploadResponse, Validation, ValidationError, ValidatorConfig, } from "./utils/types.d.ts";
+export type { AnyWebReadableByteStreamWithFileType, AnyWebReadableStream, Detector, FileTypeOptions, FileTypeParser, FileTypeResult, StreamOptions, TokenizerPositionError, } from "file-type";
+export { fileTypeFromBlob, fileTypeFromBuffer, fileTypeFromTokenizer, supportedExtensions, supportedMimeTypes } from "file-type";

package/dist/index.js

@@ -0,0 +1,13 @@
+export { waitForStorage } from './packem_shared/waitForStorage-Cscw85sx.js';
+export { D as DiskStorage } from './packem_shared/disk-storage-Bh2wy3YW.js';
+export { default as DiskStorageWithChecksum } from './packem_shared/DiskStorageWithChecksum-BJTmMklc.js';
+export { L as LocalMetaStorage } from './packem_shared/local-meta-storage-By-3SNBI.js';
+export { default as MetaStorage } from './packem_shared/MetaStorage-pECeFOad.js';
+export { B as AbstractBaseStorage, d as defaultCloudStorageFileNameValidation, a as defaultFilesystemFileNameValidation } from './packem_shared/storage-C6NSXb8h.js';
+export { ERRORS, ErrorMap, UploadError, isUploadError, throwErrorCode } from './packem_shared/ERRORS-D0apMqnc.js';
+export { createRetryWrapper, isRetryableError, retry } from './packem_shared/isRetryableError-Dycp7127.js';
+export { fileTypeFromBlob, fileTypeFromBuffer, fileTypeFromTokenizer, supportedExtensions, supportedMimeTypes } from 'file-type';
+export { default as NoOpMetrics } from './packem_shared/NoOpMetrics-DhAk5rXc.js';
+export { default as OpenTelemetryMetrics } from './packem_shared/OpenTelemetryMetrics-BnxhqIaH.js';
+export { default as File } from './packem_shared/File-Bb3P23dr.js';
+export { Metadata } from './packem_shared/Metadata-DRLXeJ0F.js';

package/dist/metrics/index.d.ts

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1,15 @@
+/**
+ * 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

@@ -0,0 +1,55 @@
+/**
+ * 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/index.d.ts

@@ -0,0 +1,5 @@
+export { default as restOpenApiSpec } from "./rest.d.ts";
+export { sharedErrorSchemaObject, sharedFileMetaExampleObject, sharedFileMetaSchemaObject, sharedGet, sharedGetList } from "./shared.d.ts";
+export { default as transformOpenApiSpec } from "./transform.d.ts";
+export { default as tusOpenApiSpec } from "./tus.d.ts";
+export { default as xhrOpenApiSpec } from "./xhr.d.ts";

package/dist/openapi/index.js

@@ -0,0 +1,5 @@
+export { default as restOpenApiSpec } from '../packem_shared/restOpenApiSpec-CwcHHY2C.js';
+export { sharedErrorSchemaObject, sharedFileMetaExampleObject, sharedFileMetaSchemaObject, sharedGet, sharedGetList } from '../packem_shared/sharedGet-Cpo7QUyu.js';
+export { default as transformOpenApiSpec } from '../packem_shared/transformOpenApiSpec-DWM5WtnN.js';
+export { default as tusOpenApiSpec } from '../packem_shared/tusOpenApiSpec-6ohiToBy.js';
+export { default as xhrOpenApiSpec } from '../packem_shared/xhrOpenApiSpec-DS17brnx.js';

package/dist/openapi/rest.d.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,133 @@
+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

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

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

@@ -0,0 +1,88 @@
+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 };