@heilgar/file-storage-adapter-core 1.0.0

package/dist/base-adapter.d.ts

@@ -0,0 +1,40 @@
+import type { DownloadOptions, FileMetadata, FileObject, FileStorageAdapter, FileStorageAdapterConfig, ListOptions, ListResult, SignedUrlOptions, SignedUrlUploadResult, UploadOptions } from './types';
+export declare abstract class BaseAdapter implements FileStorageAdapter {
+    protected config: FileStorageAdapterConfig;
+    constructor(config?: FileStorageAdapterConfig);
+    /**
+     * Prepends the base path to the given key if a base path is configured.
+     *
+     * @param key - The original file key
+     *
+     * @returns The full file key with base path prepended if applicable
+     */
+    protected getFullKey(key: string): string;
+    /**
+     * Removes the base path from the given full key if a base path is configured.
+     *
+     * @param fullKey - The full file fullKey
+     *
+     * @returns The file key without the base path if applicable
+     */
+    protected stripBasePath(fullKey: string): string;
+    /**
+     * Converts various file input types to a Buffer.
+     *
+     * @param file - The file input (Buffer, Stream, or File)
+     *
+     * @returns A Promise that resolves to a Buffer
+     */
+    protected toBuffer(file: Buffer | NodeJS.ReadableStream | File): Promise<Buffer>;
+    abstract upload(key: string, file: Buffer | NodeJS.ReadableStream | File, options?: UploadOptions): Promise<FileMetadata>;
+    abstract download(key: string, options?: DownloadOptions): Promise<FileObject>;
+    abstract getMetadata(key: string): Promise<FileMetadata | null>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract exists(key: string): Promise<boolean>;
+    abstract list(options?: ListOptions): Promise<ListResult>;
+    abstract getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>;
+    abstract getSignedUrlUpload(key: string, options: SignedUrlOptions): Promise<SignedUrlUploadResult>;
+    abstract copy(sourceKey: string, destinationKey: string): Promise<FileMetadata>;
+    abstract move(sourceKey: string, destinationKey: string): Promise<FileMetadata>;
+}
+//# sourceMappingURL=base-adapter.d.ts.map

package/dist/base-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.d.ts","sourceRoot":"","sources":["../src/base-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,wBAAwB,EACxB,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,8BAAsB,WAAY,YAAW,kBAAkB;IACjD,SAAS,CAAC,MAAM,EAAE,wBAAwB;gBAAhC,MAAM,GAAE,wBAA6B;IAE3D;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQzC;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQhD;;;;;;OAMG;cACa,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBtF,QAAQ,CAAC,MAAM,CACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,EAC3C,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAC9E,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAC/D,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IACzD,QAAQ,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9E,QAAQ,CAAC,kBAAkB,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,qBAAqB,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAC/E,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAChF"}

package/dist/base-adapter.js

@@ -0,0 +1,54 @@
+import { join } from 'node:path';
+export class BaseAdapter {
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Prepends the base path to the given key if a base path is configured.
+     *
+     * @param key - The original file key
+     *
+     * @returns The full file key with base path prepended if applicable
+     */
+    getFullKey(key) {
+        if (this.config.basePath) {
+            return join(this.config.basePath, key);
+        }
+        return key;
+    }
+    /**
+     * Removes the base path from the given full key if a base path is configured.
+     *
+     * @param fullKey - The full file fullKey
+     *
+     * @returns The file key without the base path if applicable
+     */
+    stripBasePath(fullKey) {
+        if (this.config.basePath && fullKey.startsWith(this.config.basePath)) {
+            return fullKey.slice(this.config.basePath.length + 1);
+        }
+        return fullKey;
+    }
+    /**
+     * Converts various file input types to a Buffer.
+     *
+     * @param file - The file input (Buffer, Stream, or File)
+     *
+     * @returns A Promise that resolves to a Buffer
+     */
+    async toBuffer(file) {
+        if (Buffer.isBuffer(file)) {
+            return file;
+        }
+        if ('stream' in file && typeof file.stream === 'function') {
+            const arrayBuffer = await file.arrayBuffer();
+            return Buffer.from(arrayBuffer);
+        }
+        const chunks = [];
+        for await (const chunk of file) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+}
+//# sourceMappingURL=base-adapter.js.map

package/dist/base-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.js","sourceRoot":"","sources":["../src/base-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAcjC,MAAM,OAAgB,WAAW;IAC/B,YAAsB,SAAmC,EAAE;QAArC,WAAM,GAAN,MAAM,CAA+B;IAAG,CAAC;IAE/D;;;;;;OAMG;IACO,UAAU,CAAC,GAAW;QAC9B,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;;OAMG;IACO,aAAa,CAAC,OAAe;QACrC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrE,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,QAAQ,CAAC,IAA2C;QAClE,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,QAAQ,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1D,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;YAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;QAED,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAA6B,EAAE,CAAC;YACxD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;CAmBF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './base-adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './base-adapter';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+export interface FileMetadata {
+    name: string;
+    mimeType: string;
+    size: number;
+    uploadedAt: Date;
+    metadata?: Record<string, any>;
+}
+export interface FileObject extends FileMetadata {
+    content: Buffer;
+}
+export interface UploadOptions {
+    contentType?: string;
+    cacheControl?: string;
+    path?: string;
+    metadata?: Record<string, any>;
+}
+export interface ListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface ListResult {
+    files: FileMetadata[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export interface DownloadOptions {
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+export interface SignedUrlOptions {
+    expiresIn: number;
+    contentType?: string;
+}
+export interface SignedUrlUploadResult {
+    url: string;
+    headers?: Record<string, string>;
+}
+export interface FileStorageAdapterConfig {
+    basePath?: string;
+}
+export interface FileStorageAdapter {
+    /**
+     *  Uploads a file to the storage system.
+     *
+     * @param key - unique identifier for the file
+     * @param file - File content (Buffer, Stream, or File)
+     * @param options - Upload options
+     *
+     * @returns FileMetadata
+     */
+    upload(key: string, file: Buffer | NodeJS.ReadableStream | File, options?: UploadOptions): Promise<FileMetadata>;
+    /**
+     * Downloads a file from the storage system.
+     *
+     * @param key - File identifier
+     * @param options - Download options
+     *
+     * @returns FileObject
+     */
+    download(key: string, options?: DownloadOptions): Promise<FileObject>;
+    /**
+     * Retrieves metadata for a file.
+     *
+     * @param key - File identifier
+     *
+     * @returns void
+     */
+    getMetadata(key: string): Promise<FileMetadata | null>;
+    /**
+     * Deletes a file from the storage system.
+     *
+     * @param key - File identifier
+     *
+     * @returns boolean
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Checks if a file exists in the storage system.
+     *
+     * @param key - File identifier
+     *
+     * @returns boolean
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Lists files in the storage system.
+     *
+     * @param options - List options
+     *
+     * @returns ListResult
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /**
+     * Generates a signed URL for accessing a file.
+     *
+     * @param key - File identifier
+     * @param options - Signed URL options
+     *
+     * @returns string - Signed URL
+     */
+    getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>;
+    /**
+     * Generates a signed URL for uploading a file.
+     *
+     * @param key - File identifier
+     * @param options - Signed URL options
+     *
+     * @returns object - Signed URL and optional headers
+     */
+    getSignedUrlUpload(key: string, options: SignedUrlOptions): Promise<SignedUrlUploadResult>;
+    /**
+     * Copies a file within the storage system.
+     *
+     * @param sourceKey - Source file identifier
+     * @param destinationKey - Destination file identifier
+     *
+     * @returns FileMetadata
+     */
+    copy(sourceKey: string, destinationKey: string): Promise<FileMetadata>;
+    /**
+     * Moves a file within the storage system.
+     *
+     * @param sourceKey - Source file identifier
+     * @param destinationKey - Destination file identifier
+     *
+     * @returns FileMetadata
+     */
+    move(sourceKey: string, destinationKey: string): Promise<FileMetadata>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@heilgar/file-storage-adapter-core",
+  "version": "1.0.0",
+  "description": "Core types and interfaces for storage adapters",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run --config ../../vitest.config.js",
+    "test:watch": "vitest --config ../../vitest.config.js"
+  },
+  "keywords": [
+    "storage",
+    "adapter"
+  ],
+  "author": "Oleh Hrebeniuk",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}