@veloxts/storage 0.6.91 → 0.6.93

package/dist/types.d.ts

@@ -75,7 +75,7 @@ export interface ListResult {
     hasMore: boolean;
 }
 /**
- * Options for generating signed URLs.
+ * Options for generating signed download URLs.
  */
 export interface SignedUrlOptions {
     /** URL expiration time in seconds (default: 3600 = 1 hour) */
@@ -85,6 +85,19 @@ export interface SignedUrlOptions {
     /** Response content disposition override */
     responseContentDisposition?: string;
 }
+/**
+ * Options for generating signed upload URLs.
+ */
+export interface SignedUploadOptions {
+    /** Object key/path to upload to */
+    key: string;
+    /** URL expiration time in seconds (default: 3600 = 1 hour) */
+    expiresIn?: number;
+    /** Content type for the upload (required for most providers) */
+    contentType?: string;
+    /** Maximum content length in bytes (optional enforcement) */
+    maxContentLength?: number;
+}
 /**
  * Options for copying files.
  */
@@ -128,6 +141,8 @@ export interface S3StorageConfig {
     defaultVisibility?: FileVisibility;
     /** Key prefix for all operations */
     prefix?: string;
+    /** Custom public URL for accessing files (e.g., CDN URL) */
+    publicUrl?: string;
 }
 /**
  * Union type for all storage configurations.
@@ -137,6 +152,13 @@ export type StorageConfig = LocalStorageConfig | S3StorageConfig;
  * Low-level storage store interface implemented by drivers.
  */
 export interface StorageStore {
+    /**
+     * Initialize the storage store.
+     * Called once at boot by the plugin.
+     * Use for config validation, connection verification, directory creation, etc.
+     * Throw to fail fast if the store cannot start.
+     */
+    init?(): Promise<void>;
     /**
      * Upload a file.
      * @param path - Destination path/key
@@ -199,6 +221,15 @@ export interface StorageStore {
      * @returns File metadata, or null if not found
      */
     metadata(path: string): Promise<FileMetadata | null>;
+    /**
+     * Get file metadata, throwing if not found.
+     * Unlike metadata() which returns null for missing files,
+     * head() throws StorageObjectNotFoundError.
+     * @param path - File path/key
+     * @returns File metadata
+     * @throws StorageObjectNotFoundError if file does not exist
+     */
+    head(path: string): Promise<FileMetadata>;
     /**
      * List files in a directory/prefix.
      * @param prefix - Directory prefix
@@ -213,12 +244,19 @@ export interface StorageStore {
      */
     url(path: string): Promise<string>;
     /**
-     * Get a signed/temporary URL for private file access.
+     * Get a signed/temporary URL for private file access (download).
      * @param path - File path/key
      * @param options - Signed URL options
      * @returns Signed URL string
      */
     signedUrl(path: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Get a signed/temporary URL for uploading a file directly to storage.
+     * Enables direct browser-to-storage uploads without proxying through the server.
+     * @param options - Signed upload URL options
+     * @returns Signed URL string for PUT upload
+     */
+    signedUploadUrl(options: SignedUploadOptions): Promise<string>;
     /**
      * Set file visibility.
      * @param path - File path/key
@@ -294,3 +332,8 @@ export type StoragePluginOptions = StorageLocalOptions | StorageS3Options | Stor
  * Storage manager options (alias for plugin options).
  */
 export type StorageManagerOptions = StoragePluginOptions;
+/**
+ * Backwards compatibility alias for StorageStore.
+ * @deprecated Use StorageStore instead. Will be removed in v2.0.
+ */
+export type StorageProvider = StorageStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/storage",
-  "version": "0.6.91",
+  "version": "0.6.93",
   "description": "Multi-driver file storage abstraction for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,30 @@
     "./drivers/s3": {
       "types": "./dist/drivers/s3.d.ts",
       "import": "./dist/drivers/s3.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.js"
+    },
+    "./providers/r2": {
+      "types": "./dist/providers/r2.d.ts",
+      "import": "./dist/providers/r2.js"
+    },
+    "./providers/minio": {
+      "types": "./dist/providers/minio.d.ts",
+      "import": "./dist/providers/minio.js"
+    },
+    "./providers/local": {
+      "types": "./dist/drivers/local.d.ts",
+      "import": "./dist/drivers/local.js"
+    },
+    "./providers/s3": {
+      "types": "./dist/drivers/s3.d.ts",
+      "import": "./dist/drivers/s3.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -32,7 +56,8 @@
   "dependencies": {
     "fastify-plugin": "5.1.0",
     "mime-types": "3.0.2",
-    "@veloxts/core": "0.6.91"
+    "zod": "3.24.4",
+    "@veloxts/core": "0.6.93"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.0.0",
@@ -61,7 +86,7 @@
     "fastify": "5.7.2",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
-    "@veloxts/testing": "0.6.91"
+    "@veloxts/testing": "0.6.93"
   },
   "publishConfig": {
     "access": "public"