Add a storage provider

StorageService routes uploads and deletions to registered IStorageProvider instances. The built-in provider is LocalFileProvider; cloud providers must be supplied by the application or another package.

Implement the contract#

The example below is a contract skeleton, not a complete cloud adapter: the external SDK call is provider-specific and intentionally left for the application to implement.

import type { IStorageProvider, StorageResult } from "@veap/storage";

export class ExampleObjectStorageProvider implements IStorageProvider {
  id = "object-storage";
  name = "Example Object Storage";

  async upload(file: File): Promise<StorageResult> {
    // Validate and upload with your provider SDK.
    // Return the StorageData shape or { error: "..." }.
    throw new Error("Implement using your object-storage SDK");
  }

  async delete(serviceId: string): Promise<boolean> {
    // Delete the provider object identified by serviceId.
    return false;
  }
}

The StorageData success shape includes name, url, type, size, service, and serviceId. The failure shape is { error: string }.

Register the provider#

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

const storage = await app(StorageService);
storage.registerProvider(new ExampleObjectStorageProvider());
storage.setDefaultProvider("object-storage");

Call this only after the storage provider has booted and registered StorageService. For a clean production design, register custom providers through your own service provider's lifecycle instead of ad hoc request code.

Provider selection and deletion#

upload(file, providerId?) and delete(keyOrUrl, providerId?) accept an optional provider ID. If the requested/default provider is unavailable, the service attempts the "local" provider. delete returns false if no provider is available or the selected provider has no delete method.

Security#

• Enforce file-size limits before buffering the upload.
• Validate actual content as well as the supplied MIME type.
• Restrict accepted file extensions to your business requirements.
• Keep private documents outside a public static directory.
• Use opaque object keys; never trust a user-supplied filesystem path.
• Authorize deletions and avoid exposing provider credentials to the browser.