@digibuffer/file-manager-core 1.0.0

package/dist/router-CY6g7nWy.d.ts

@@ -0,0 +1,339 @@
+//#region src/types.d.ts
+/**
+ * File metadata stored in database or retrieved from storage
+ */
+interface FileMetadata {
+  key: string;
+  size: number;
+  lastModified: Date;
+  contentType?: string;
+  etag?: string;
+  customMetadata?: Record<string, string>;
+}
+/**
+ * Database file record (metadata only)
+ */
+interface DatabaseFile extends FileMetadata {
+  id: string;
+  userId?: string;
+  uploadedAt: Date;
+  updatedAt: Date;
+}
+/**
+ * Storage file from cloud provider
+ */
+interface StorageFile extends FileMetadata {
+  bucket: string;
+}
+/**
+ * Unified file type that can come from either source
+ */
+type ManagedFile = DatabaseFile | StorageFile;
+/**
+ * Pagination cursor for listing files
+ */
+interface PaginationCursor {
+  continuationToken?: string;
+  offset?: number;
+}
+/**
+ * Paginated response wrapper
+ */
+interface PaginatedResponse<T> {
+  data: T[];
+  nextCursor?: PaginationCursor;
+  hasMore: boolean;
+  totalCount?: number;
+}
+/**
+ * List options for querying files
+ */
+interface ListOptions {
+  prefix?: string;
+  delimiter?: string;
+  maxKeys?: number;
+  cursor?: PaginationCursor;
+  sortBy?: 'name' | 'size' | 'lastModified';
+  sortOrder?: 'asc' | 'desc';
+  userId?: string;
+}
+/**
+ * Download URL options
+ */
+interface DownloadUrlOptions {
+  expiresIn?: number;
+  disposition?: 'inline' | 'attachment';
+  filename?: string;
+}
+/**
+ * File operation result
+ */
+interface OperationResult {
+  success: boolean;
+  key: string;
+  error?: string;
+}
+/**
+ * Batch operation result
+ */
+interface BatchOperationResult {
+  succeeded: string[];
+  failed: Array<{
+    key: string;
+    error: string;
+  }>;
+  totalProcessed: number;
+}
+/**
+ * Move/Rename operation options
+ */
+interface MoveOptions {
+  sourceKey: string;
+  destinationKey: string;
+  deleteSource?: boolean;
+}
+/**
+ * Copy operation options
+ */
+interface CopyOptions {
+  sourceKey: string;
+  destinationKey: string;
+  metadata?: Record<string, string>;
+}
+/**
+ * Data source mode
+ */
+type DataSource = 'storage' | 'database' | 'both';
+/**
+ * Storage provider interface
+ */
+interface StorageProvider {
+  list(options: ListOptions): Promise<PaginatedResponse<StorageFile>>;
+  delete(key: string): Promise<OperationResult>;
+  deleteBatch(keys: string[]): Promise<BatchOperationResult>;
+  exists(key: string): Promise<boolean>;
+  getMetadata(key: string): Promise<StorageFile | null>;
+  getDownloadUrl(key: string, options?: DownloadUrlOptions): Promise<string>;
+  move(options: MoveOptions): Promise<OperationResult>;
+  copy(options: CopyOptions): Promise<OperationResult>;
+  rename(oldKey: string, newKey: string): Promise<OperationResult>;
+}
+/**
+ * Database provider interface
+ */
+interface DatabaseProvider {
+  list(options: ListOptions): Promise<PaginatedResponse<DatabaseFile>>;
+  get(key: string): Promise<DatabaseFile | null>;
+  create(file: Omit<DatabaseFile, 'id' | 'uploadedAt' | 'updatedAt'>): Promise<DatabaseFile>;
+  update(key: string, data: Partial<DatabaseFile>): Promise<DatabaseFile | null>;
+  delete(key: string): Promise<OperationResult>;
+  deleteBatch(keys: string[]): Promise<BatchOperationResult>;
+  exists(key: string): Promise<boolean>;
+  sync(storageFiles: StorageFile[]): Promise<void>;
+}
+/**
+ * S3/R2 configuration
+ */
+interface StorageConfig {
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  endpoint: string;
+  region?: string;
+  publicUrl?: string;
+}
+/**
+ * PostgreSQL configuration
+ */
+interface DatabaseConfig {
+  connectionString?: string;
+  host?: string;
+  port?: number;
+  database?: string;
+  user?: string;
+  password?: string;
+  tableName?: string;
+}
+/**
+ * File manager configuration
+ */
+interface FileManagerConfig {
+  storage: StorageConfig;
+  database?: DatabaseConfig;
+  defaultSource?: DataSource;
+  autoSync?: boolean;
+}
+/**
+ * Authorization context for file operations
+ */
+interface AuthContext {
+  userId?: string;
+  roles?: string[];
+  permissions?: string[];
+  customData?: Record<string, unknown>;
+}
+/**
+ * Authorization callback
+ */
+type AuthorizationCallback = (context: AuthContext, operation: string, resource: string) => Promise<boolean> | boolean;
+/**
+ * Before/After operation hooks
+ */
+interface OperationHooks {
+  beforeDelete?: (keys: string[]) => Promise<void> | void;
+  afterDelete?: (keys: string[]) => Promise<void> | void;
+  beforeMove?: (options: MoveOptions) => Promise<void> | void;
+  afterMove?: (options: MoveOptions) => Promise<void> | void;
+  beforeCopy?: (options: CopyOptions) => Promise<void> | void;
+  afterCopy?: (options: CopyOptions) => Promise<void> | void;
+}
+/**
+ * Custom error class for file manager operations
+ */
+declare class FileManagerError extends Error {
+  code: string;
+  statusCode: number;
+  details?: unknown | undefined;
+  constructor(message: string, code: string, statusCode?: number, details?: unknown | undefined);
+}
+/**
+ * Request action types
+ */
+type RequestAction = 'list' | 'delete' | 'batchDelete' | 'exists' | 'getMetadata' | 'getUrl' | 'move' | 'copy' | 'rename';
+/**
+ * Request body for file operations
+ */
+interface FileOperationRequest {
+  action: RequestAction;
+  key?: string;
+  keys?: string[];
+  options?: Record<string, unknown>;
+  source?: DataSource;
+}
+/**
+ * Response for file operations
+ */
+interface FileOperationResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  code?: string;
+}
+//#endregion
+//#region src/file-manager.d.ts
+/**
+ * Main FileManager class - Orchestrates file operations across storage and database
+ */
+declare class FileManager {
+  private storage;
+  private database?;
+  private defaultSource;
+  private autoSync;
+  private hooks?;
+  constructor(config: FileManagerConfig, hooks?: OperationHooks);
+  /**
+   * List files from specified source
+   */
+  list(options?: ListOptions, source?: DataSource): Promise<PaginatedResponse<ManagedFile>>;
+  /**
+   * List files from storage only
+   */
+  listFromStorage(options?: ListOptions): Promise<PaginatedResponse<StorageFile>>;
+  /**
+   * List files from database only
+   */
+  listFromDatabase(options?: ListOptions): Promise<PaginatedResponse<DatabaseFile>>;
+  /**
+   * List files from both storage and database, merged
+   */
+  listFromBoth(options?: ListOptions): Promise<PaginatedResponse<ManagedFile>>;
+  /**
+   * Get file metadata
+   */
+  getMetadata(key: string, source?: DataSource): Promise<ManagedFile | null>;
+  /**
+   * Check if file exists
+   */
+  exists(key: string, source?: DataSource): Promise<boolean>;
+  /**
+   * Get download URL for a file
+   */
+  getDownloadUrl(key: string, options?: DownloadUrlOptions): Promise<string>;
+  /**
+   * Delete a single file
+   */
+  delete(key: string): Promise<OperationResult>;
+  /**
+   * Delete multiple files in batch
+   */
+  deleteBatch(keys: string[]): Promise<BatchOperationResult>;
+  /**
+   * Move a file to a new location
+   */
+  move(options: MoveOptions): Promise<OperationResult>;
+  /**
+   * Copy a file to a new location
+   */
+  copy(options: CopyOptions): Promise<OperationResult>;
+  /**
+   * Rename a file (alias for move)
+   */
+  rename(oldKey: string, newKey: string): Promise<OperationResult>;
+  /**
+   * Sync storage files to database
+   */
+  syncToDatabase(options?: ListOptions): Promise<void>;
+  /**
+   * Create a file record in database (useful after upload)
+   */
+  createDatabaseRecord(file: Omit<DatabaseFile, 'id' | 'uploadedAt' | 'updatedAt'>): Promise<DatabaseFile | null>;
+  /**
+   * Update file metadata in database
+   */
+  updateDatabaseRecord(key: string, data: Partial<DatabaseFile>): Promise<DatabaseFile | null>;
+}
+//#endregion
+//#region src/router.d.ts
+/**
+ * Router configuration
+ */
+interface RouterConfig {
+  fileManager: FileManager;
+  authorize?: AuthorizationCallback;
+  getAuthContext?: (request: Request) => Promise<AuthContext> | AuthContext;
+}
+/**
+ * FileManager Router - Handles HTTP requests for file operations
+ */
+declare class FileManagerRouter {
+  private fileManager;
+  private authorize?;
+  private getAuthContext?;
+  constructor(config: RouterConfig);
+  /**
+   * Handle incoming request
+   */
+  handle(request: Request): Promise<Response>;
+  /**
+   * Route action to appropriate handler
+   */
+  private routeAction;
+  /**
+   * Success response
+   */
+  private successResponse;
+  /**
+   * Error response
+   */
+  private errorResponse;
+  /**
+   * Handle errors
+   */
+  private handleError;
+}
+/**
+ * Create a new FileManager router instance
+ */
+declare function createFileManagerRouter(config: RouterConfig): FileManagerRouter;
+//#endregion
+export { PaginatedResponse as C, StorageFile as D, StorageConfig as E, StorageProvider as O, OperationResult as S, RequestAction as T, FileOperationResponse as _, AuthorizationCallback as a, MoveOptions as b, DataSource as c, DatabaseProvider as d, DownloadUrlOptions as f, FileOperationRequest as g, FileMetadata as h, AuthContext as i, DatabaseConfig as l, FileManagerError as m, createFileManagerRouter as n, BatchOperationResult as o, FileManagerConfig as p, FileManager as r, CopyOptions as s, FileManagerRouter as t, DatabaseFile as u, ListOptions as v, PaginationCursor as w, OperationHooks as x, ManagedFile as y };