@haykal/storage-backend

File storage and media management domain package for Haykal applications.

Features

• Provider Abstraction — Swap storage backends (local filesystem, AWS S3) without changing application code
• File Upload — Multipart file upload with validation (size, MIME type, dimensions)
• Image Processing — Automatic thumbnail generation and image transformations via sharp
• Signed URLs — Pre-signed download and upload URLs for private file access
• Polymorphic Ownership — Any entity can own files via ownerType + ownerId
• Soft Delete — Files are soft-deleted with optional cleanup
• OpenAPI Documented — Full Swagger/OpenAPI annotations

Usage

import { StorageModule } from '@haykal/storage-backend';

@Module({
  imports: [
    StorageModule.forRoot({
      provider: 'local',
      local: {
        rootDir: './uploads',
        servePrefix: '/files',
      },
      upload: {
        maxFileSize: 10 * 1024 * 1024, // 10MB
        allowedMimeTypes: ['image/*', 'application/pdf'],
        maxFilesPerRequest: 5,
      },
      signedUrlExpiry: 3600,
    }),
  ],
})
export class AppModule {}

Providers

Local

Stores files on the local filesystem. Ideal for development and self-hosted deployments.

S3

Stores files on AWS S3 or any S3-compatible service (MinIO, DigitalOcean Spaces, etc.).

StorageModule.forRoot({
  provider: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: 'KEY',
    secretAccessKey: 'SECRET',
    endpoint: 'http://localhost:9000', // optional, for MinIO
  },
  upload: { ... },
  signedUrlExpiry: 3600,
});

API Endpoints

| Method | Path | Description | | ------ | ----------------------------- | -------------------------------------- | | POST | /storage/upload | Upload file(s) via multipart form | | POST | /storage/upload/signed-url | Get pre-signed upload URL | | GET | /storage/files | List files (paginated, filterable) | | GET | /storage/files/:id | Get file metadata | | GET | /storage/files/:id/download | Download file / redirect to signed URL | | DELETE | /storage/files/:id | Soft-delete file |

Related Packages

• @haykal/storage-client — React Query hooks for file operations
• @haykal/core-backend — Base infrastructure
• @haykal/profile-management-backend — Stores avatar/cover photos

Further Reading

• API Reference — Full endpoint listing
• Backend Style Guide — Coding conventions