@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/StorageManager-oZTHqaza.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Options for putting files.
+ */
+interface PutOptions {
+    /**
+     * File visibility.
+     */
+    visibility?: 'public' | 'private';
+    /**
+     * Content type (MIME type).
+     */
+    contentType?: string;
+    /**
+     * Custom metadata.
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * File metadata.
+ */
+interface FileMetadata {
+    /**
+     * File path.
+     */
+    path: string;
+    /**
+     * File size in bytes.
+     */
+    size: number;
+    /**
+     * Last modified date.
+     */
+    lastModified: Date;
+    /**
+     * Content type (if available).
+     */
+    contentType?: string;
+    /**
+     * File visibility.
+     */
+    visibility?: 'public' | 'private';
+    /**
+     * Custom metadata.
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * Storage driver interface.
+ */
+interface StorageDriver {
+    /**
+     * Put a file into storage.
+     * @param path File path
+     * @param content File content
+     * @param options Put options
+     * @returns The stored file path
+     */
+    put(path: string, content: Buffer | string, options?: PutOptions): Promise<string>;
+    /**
+     * Put a file from a local path.
+     * @param path Destination path
+     * @param localPath Local file path
+     * @param options Put options
+     * @returns The stored file path
+     */
+    putFile(path: string, localPath: string, options?: PutOptions): Promise<string>;
+    /**
+     * Get file contents.
+     * @param path File path
+     * @returns File contents or null if not found
+     */
+    get(path: string): Promise<Buffer | null>;
+    /**
+     * Get file contents as string.
+     * @param path File path
+     * @returns File contents as string or null if not found
+     */
+    getAsString(path: string): Promise<string | null>;
+    /**
+     * Check if a file exists.
+     * @param path File path
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Delete a file.
+     * @param path File path
+     * @returns True if deleted, false if not found
+     */
+    delete(path: string): Promise<boolean>;
+    /**
+     * Delete multiple files.
+     * @param paths File paths
+     * @returns Number of deleted files
+     */
+    deleteMany(paths: string[]): Promise<number>;
+    /**
+     * Copy a file.
+     * @param from Source path
+     * @param to Destination path
+     * @returns The destination path
+     */
+    copy(from: string, to: string): Promise<string>;
+    /**
+     * Move a file.
+     * @param from Source path
+     * @param to Destination path
+     * @returns The destination path
+     */
+    move(from: string, to: string): Promise<string>;
+    /**
+     * Get the public URL for a file.
+     * @param path File path
+     */
+    url(path: string): string;
+    /**
+     * Get a temporary (signed) URL for a file.
+     * @param path File path
+     * @param expiration Expiration date
+     */
+    temporaryUrl(path: string, expiration: Date): Promise<string>;
+    /**
+     * Get the file size in bytes.
+     * @param path File path
+     */
+    size(path: string): Promise<number>;
+    /**
+     * Get the last modified date.
+     * @param path File path
+     */
+    lastModified(path: string): Promise<Date>;
+    /**
+     * Get file metadata.
+     * @param path File path
+     */
+    metadata(path: string): Promise<FileMetadata | null>;
+    /**
+     * List files in a directory.
+     * @param directory Directory path
+     */
+    files(directory: string): Promise<string[]>;
+    /**
+     * List subdirectories in a directory.
+     * @param directory Directory path
+     */
+    directories(directory: string): Promise<string[]>;
+    /**
+     * List all files recursively.
+     * @param directory Directory path
+     */
+    allFiles(directory: string): Promise<string[]>;
+    /**
+     * Create a directory.
+     * @param path Directory path
+     */
+    makeDirectory(path: string): Promise<void>;
+    /**
+     * Delete a directory and its contents.
+     * @param path Directory path
+     */
+    deleteDirectory(path: string): Promise<void>;
+    /**
+     * Set file visibility.
+     * @param path File path
+     * @param visibility Visibility setting
+     */
+    setVisibility(path: string, visibility: 'public' | 'private'): Promise<void>;
+    /**
+     * Get file visibility.
+     * @param path File path
+     */
+    getVisibility(path: string): Promise<'public' | 'private'>;
+}
+/**
+ * Storage driver factory function.
+ */
+type StorageDriverFactory = () => StorageDriver;
+/**
+ * Local driver options.
+ */
+interface LocalDriverOptions {
+    /**
+     * Root directory for file storage.
+     */
+    root: string;
+    /**
+     * Base URL for public files.
+     */
+    url?: string;
+    /**
+     * Default visibility for new files.
+     * @default 'private'
+     */
+    visibility?: 'public' | 'private';
+}
+/**
+ * S3 driver options.
+ */
+interface S3DriverOptions {
+    /**
+     * S3 client instance (@aws-sdk/client-s3).
+     */
+    client?: unknown;
+    /**
+     * S3 bucket name.
+     */
+    bucket: string;
+    /**
+     * AWS region.
+     */
+    region?: string;
+    /**
+     * Custom endpoint URL.
+     */
+    endpoint?: string;
+    /**
+     * Access key ID.
+     */
+    accessKeyId?: string;
+    /**
+     * Secret access key.
+     */
+    secretAccessKey?: string;
+    /**
+     * Key prefix.
+     */
+    prefix?: string;
+    /**
+     * Base URL for public files.
+     */
+    url?: string;
+    /**
+     * Default visibility for new files.
+     * @default 'private'
+     */
+    visibility?: 'public' | 'private';
+}
+/**
+ * Memory driver options.
+ */
+interface MemoryDriverOptions {
+    /**
+     * Base URL for public files.
+     */
+    url?: string;
+}
+/**
+ * Driver configuration union type.
+ */
+type DriverConfig = ({
+    driver: 'local';
+} & LocalDriverOptions) | ({
+    driver: 's3';
+} & S3DriverOptions) | ({
+    driver: 'memory';
+} & MemoryDriverOptions);
+type DiskConfig = DriverConfig;
+/**
+ * Storage configuration.
+ */
+interface StorageConfig {
+    /**
+     * Default disk name.
+     * @default 'local'
+     */
+    default?: string;
+    /**
+     * Disk configurations.
+     */
+    disks?: Record<string, DriverConfig>;
+}
+
+/**
+ * Storage manager for handling multiple storage disks.
+ *
+ * @example
+ * ```ts
+ * const storage = new StorageManager({
+ *   default: 'local',
+ *   disks: {
+ *     local: { driver: 'local', root: './storage/app' },
+ *     s3: { driver: 's3', bucket: 'my-bucket', region: 'ap-northeast-1' },
+ *   }
+ * })
+ *
+ * // Use the default disk
+ * await storage.disk().put('avatars/user-1.jpg', imageBuffer)
+ *
+ * // Use a specific disk
+ * await storage.disk('s3').put('avatars/user-1.jpg', imageBuffer)
+ * ```
+ */
+declare class StorageManager {
+    private readonly defaultDiskName;
+    private readonly diskFactories;
+    private readonly resolvedDisks;
+    private driverFactories;
+    constructor(config?: StorageConfig);
+    /**
+     * Register built-in disk drivers.
+     */
+    private registerBuiltinDrivers;
+    /**
+     * Register a disk from configuration.
+     */
+    private registerDiskFromConfig;
+    /**
+     * Get a storage disk by name.
+     * Returns the default disk if no name is specified.
+     */
+    disk(name?: string): StorageDriver;
+    /**
+     * Register a custom disk factory.
+     */
+    registerDisk(name: string, factory: StorageDriverFactory): void;
+    /**
+     * Register a custom driver.
+     */
+    registerDriver(name: string, factory: (options: unknown) => StorageDriver): void;
+    /**
+     * Check if a disk is registered.
+     */
+    hasDisk(name: string): boolean;
+    /**
+     * Get the default disk name.
+     */
+    getDefaultDiskName(): string;
+    /**
+     * Get all registered disk names.
+     */
+    getDiskNames(): string[];
+}
+/**
+ * Create a storage manager with configuration.
+ */
+declare function createStorageManager(config?: StorageConfig): StorageManager;
+
+export { type DiskConfig as D, type FileMetadata as F, type LocalDriverOptions as L, type MemoryDriverOptions as M, type PutOptions as P, StorageManager as S, type StorageConfig as a, type StorageDriver as b, type StorageDriverFactory as c, createStorageManager as d, type S3DriverOptions as e, type DriverConfig as f };