File storage

@veap/storage exposes a StorageService that routes uploads and deletions to registered storage providers. The package includes a local provider and supports custom providers through the IStorageProvider contract.

Register storage#

import { Application } from "@veap/kernel";
import { StorageServiceProvider } from "@veap/storage";

export const app = Application.configure()
  .use(StorageServiceProvider)
  .create();

The local provider uses FILE_STORAGE_FOLDER, documented with a default of public/uploads.

Upload a file#

import { app } from "@veap/kernel";
import { StorageService } from "@veap/storage";

export async function saveUpload(file: File) {
  const storage = await app(StorageService);
  const result = await storage.upload(file, "local");
  if ("error" in result) throw new Error(result.error);
  return result;
}

Call this from server-only code after validating the request. The result type can represent an error; inspect StorageResult from the installed declarations and do not assume every upload returns a URL.

Delete a file#

const storage = await app(StorageService);
const deleted = await storage.delete(keyOrUrl, "local");
if (!deleted) {
  // Handle a missing provider or unsupported deletion.
}

Providers may not support deletion. StorageService.delete() returns false when no provider is available or the selected provider does not expose a delete method.

Security#

• Enforce file size limits before reading large uploads.
• Allow-list extensions and MIME types appropriate to the use case.
• Treat client-supplied MIME types and filenames as untrusted.
• Store private files outside public web roots and authorize downloads separately.
• Do not trust a public URL as proof that a user may access the file.
• Use malware scanning or content processing where the threat model requires it.
• Test path traversal, duplicate names, and deletion semantics with the chosen provider.

Custom providers#

Implement IStorageProvider, register it with StorageService.registerProvider(), and choose a default provider using setDefaultProvider(id). Provider registration is a runtime operation; ensure it occurs before any upload requests use that provider.