@opensaas/stack-storage 0.23.0 → 0.25.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @opensaas/stack-storage@0.23.0 build /home/runner/work/stack/stack/packages/storage
+> @opensaas/stack-storage@0.25.0 build /home/runner/work/stack/stack/packages/storage
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @opensaas/stack-storage
 
+## 0.25.0
+
+## 0.24.0
+
+### Minor Changes
+
+- [#551](https://github.com/OpenSaasAU/stack/pull/551) [`fb979b8`](https://github.com/OpenSaasAU/stack/commit/fb979b8978f9bdefd2b4f81e87c1c198582200ae) Thanks [@borisno2](https://github.com/borisno2)! - Add a storage provider registration API so non-`local` and custom providers are constructable.
+
+  `createStorageProvider` now resolves a provider `type` through a registry instead of a hardcoded `switch`, which previously only built `'local'` and threw for everything else. `'local'` is registered as a built-in default, so existing behaviour is unchanged. The host opts into the optional provider packages (`@opensaas/stack-storage-s3`, `@opensaas/stack-storage-vercel`) or a custom provider by registering it — `@opensaas/stack-storage` does not depend on the provider packages, keeping the AWS/Vercel SDKs off every storage user. Reads are unaffected: assembling existing asset metadata only stamps the provider name and never constructs a provider.
+
+  ```typescript
+  // lib/register-storage.ts (server-only, imported at app startup)
+  import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+  import { S3StorageProvider, type S3StorageConfig } from '@opensaas/stack-storage-s3'
+
+  registerStorageProvider<S3StorageConfig>('s3', (config) => new S3StorageProvider(config))
+  ```
+
+  ```typescript
+  // opensaas.config.ts — reference the registered provider by type
+  import { s3Storage } from '@opensaas/stack-storage-s3'
+
+  export default config({
+    storage: {
+      avatars: s3Storage({ bucket: 'user-avatars', region: 'us-east-1' }),
+    },
+    // ...
+  })
+  ```
+
+  Custom providers register the same way: implement `StorageProvider`, give it a `type`, then call `registerStorageProvider(type, (config) => new MyProvider(config))`. An unregistered type throws a clear error pointing at `registerStorageProvider`.
+
 ## 0.23.0
 
 ## 0.22.0

package/CLAUDE.md

@@ -50,7 +50,10 @@ packages/storage-vercel/  # Separate Vercel Blob provider package
 - `uploadImage(config, provider, data, options)` - Upload image with transformations
 - `deleteFile(config, provider, filename)` - Delete file
 - `deleteImage(config, metadata)` - Delete image and all transformations
-- `createStorageProvider(config, providerName)` - Create provider instance
+- `createStorageProvider(config, providerName)` - Create provider instance (resolves the provider `type` through the registry)
+- `registerStorageProvider(type, factory)` - Register a provider `type` → constructor (host opts in to optional/custom providers)
+- `getStorageProviderFactory(type)` / `hasStorageProvider(type)` - Inspect the registry
+- `resetStorageProviderRegistry()` - Reset to built-in defaults (mainly for tests)
 
 ### Utils (`src/utils/`)
 
@@ -352,40 +355,139 @@ avatar: image({
 })
 ```
 
-### Custom Storage Provider
+### Storage Provider Registry
+
+`createStorageProvider` resolves a provider `type` through a **registry** rather
+than a hardcoded `switch`. `'local'` is registered as a built-in default, so it
+works with no setup. Every other provider — the optional packages
+(`@opensaas/stack-storage-s3`, `@opensaas/stack-storage-vercel`) and your own
+custom providers — must be **registered by the host** before
+`createStorageProvider` can build them.
+
+`@opensaas/stack-storage` deliberately does **not** depend on `-s3`/`-vercel`:
+wiring them into the factory directly would force the AWS/Vercel SDKs onto every
+storage user. The host opts in by registering only the provider(s) it uses.
+
+#### Registering an optional provider package
+
+Register once at app startup (e.g. in a server-only module imported by your app
+entry, the upload route, or `instrumentation.ts`):
+
+```typescript
+// lib/register-storage.ts (server-only)
+import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+import { S3StorageProvider, type S3StorageConfig } from '@opensaas/stack-storage-s3'
+
+registerStorageProvider<S3StorageConfig>('s3', (config) => new S3StorageProvider(config))
+```
+
+Then reference the provider by `type` in config (via the package's config
+builder, which sets `type: 's3'`):
+
+```typescript
+import { s3Storage } from '@opensaas/stack-storage-s3'
+
+export default config({
+  storage: {
+    avatars: s3Storage({ bucket: 'user-avatars', region: 'us-east-1' }),
+  },
+  // ...
+})
+```
+
+The Vercel Blob provider follows the same shape:
+
+```typescript
+import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+import {
+  VercelBlobStorageProvider,
+  type VercelBlobStorageConfig,
+} from '@opensaas/stack-storage-vercel'
+
+registerStorageProvider<VercelBlobStorageConfig>(
+  'vercel-blob',
+  (config) => new VercelBlobStorageProvider(config),
+)
+```
+
+#### Registering a custom provider
+
+Implement `StorageProvider`, give it a `type` discriminator, then register it:
 
 ```typescript
 // lib/cloudflare-r2-storage.ts
-import type { StorageProvider } from '@opensaas/stack-storage'
+import type {
+  StorageProvider,
+  UploadOptions,
+  UploadResult,
+  BaseStorageConfig,
+} from '@opensaas/stack-storage'
+
+export interface CloudflareR2Config extends BaseStorageConfig {
+  type: 'cloudflare-r2'
+  bucket: string
+  accountId: string
+}
 
 export class CloudflareR2StorageProvider implements StorageProvider {
-  async upload(file: Buffer, filename: string, options?) {
-    // Upload to Cloudflare R2
-    // ...
-    return { filename, url, size, contentType }
+  constructor(private config: CloudflareR2Config) {}
+
+  async upload(
+    file: Buffer | Uint8Array,
+    filename: string,
+    options?: UploadOptions,
+  ): Promise<UploadResult> {
+    // Upload to Cloudflare R2 ...
+    return {
+      filename,
+      url: this.getUrl(filename),
+      size: file.length,
+      contentType: options?.contentType ?? 'application/octet-stream',
+    }
   }
 
-  async download(filename: string) {
-    // Download from R2
-    // ...
+  async download(filename: string): Promise<Buffer> {
+    // Download from R2 ...
+    return Buffer.from('')
   }
 
-  async delete(filename: string) {
-    // Delete from R2
-    // ...
+  async delete(filename: string): Promise<void> {
+    // Delete from R2 ...
   }
 
-  getUrl(filename: string) {
-    return `https://r2.example.com/${filename}`
+  getUrl(filename: string): string {
+    return `https://r2.example.com/${this.config.bucket}/${filename}`
   }
 }
+```
 
-// Register in runtime
-import { createStorageProvider } from '@opensaas/stack-storage/runtime'
+```typescript
+// lib/register-storage.ts (server-only)
+import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+import { CloudflareR2StorageProvider, type CloudflareR2Config } from './cloudflare-r2-storage'
+
+registerStorageProvider<CloudflareR2Config>(
+  'cloudflare-r2',
+  (config) => new CloudflareR2StorageProvider(config),
+)
+```
 
-// Extend createStorageProvider to support 'cloudflare-r2' type
+```typescript
+// opensaas.config.ts
+export default config({
+  storage: {
+    media: { type: 'cloudflare-r2', bucket: 'media', accountId: process.env.CF_ACCOUNT_ID! },
+  },
+  // ...
+})
 ```
 
+If a field references a provider whose `type` has not been registered,
+`createStorageProvider` throws a clear error
+(`Unknown storage provider type: <type>. Register it with registerStorageProvider(...)`).
+Reads are unaffected — assembling existing asset metadata only stamps the
+provider **name** and never constructs a provider.
+
 ## Type Safety
 
 All types are strongly typed:

package/dist/runtime/index.d.ts

@@ -2,7 +2,17 @@ import type { OpenSaasConfig } from '@opensaas/stack-core';
 import type { StorageProvider, FileMetadata, ImageMetadata, ImageTransformationConfig } from '../config/types.js';
 import { type FileValidationOptions } from '../utils/upload.js';
 /**
- * Creates a storage provider instance from config
+ * Creates a storage provider instance from config.
+ *
+ * The provider `type` is resolved through the provider registry (see
+ * {@link registerStorageProvider}) rather than a closed `switch`. `'local'` is
+ * registered as a built-in default, so it works with no registration step.
+ * Optional providers (`@opensaas/stack-storage-s3`,
+ * `@opensaas/stack-storage-vercel`) and custom providers must be registered by
+ * the host before they can be constructed.
+ *
+ * @throws If the named provider is not present in `config.storage`.
+ * @throws If no provider factory has been registered for the config's `type`.
  */
 export declare function createStorageProvider(config: OpenSaasConfig, providerName: string): StorageProvider;
 /**
@@ -72,4 +82,5 @@ export declare function deleteFile(config: OpenSaasConfig, storageProviderName:
  */
 export declare function deleteImage(config: OpenSaasConfig, metadata: ImageMetadata): Promise<void>;
 export { parseFileFromFormData } from '../utils/upload.js';
+export { registerStorageProvider, getStorageProviderFactory, hasStorageProvider, resetStorageProviderRegistry, type StorageProviderFactory, } from './registry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EACV,eAAe,EAEf,YAAY,EACZ,aAAa,EACb,yBAAyB,EAC1B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG1F;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,MAAM,GACnB,eAAe,CAajB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,UAAU,CAAC,EAAE,qBAAqB,CAAA;IAClC,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;CAC5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE;IACJ,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf,EACD,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA0CvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE;IACJ,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf,EACD,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA8DxB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,mBAAmB,EAAE,MAAM,EAC3B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhG;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,yBAAyB,EAC1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAI1F;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,MAAM,GACnB,eAAe,CAiBjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,UAAU,CAAC,EAAE,qBAAqB,CAAA;IAClC,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;CAC5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE;IACJ,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf,EACD,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA0CvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE;IACJ,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf,EACD,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA8DxB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,mBAAmB,EAAE,MAAM,EAC3B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhG;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAI1D,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,4BAA4B,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAA"}

package/dist/runtime/index.js

@@ -1,20 +1,31 @@
-import { LocalStorageProvider } from '../providers/local.js';
 import { validateFile, getMimeType } from '../utils/upload.js';
 import { getImageDimensions, processImageTransformations } from '../utils/image.js';
+import { getStorageProviderFactory } from './registry.js';
 /**
- * Creates a storage provider instance from config
+ * Creates a storage provider instance from config.
+ *
+ * The provider `type` is resolved through the provider registry (see
+ * {@link registerStorageProvider}) rather than a closed `switch`. `'local'` is
+ * registered as a built-in default, so it works with no registration step.
+ * Optional providers (`@opensaas/stack-storage-s3`,
+ * `@opensaas/stack-storage-vercel`) and custom providers must be registered by
+ * the host before they can be constructed.
+ *
+ * @throws If the named provider is not present in `config.storage`.
+ * @throws If no provider factory has been registered for the config's `type`.
  */
 export function createStorageProvider(config, providerName) {
     if (!config.storage || !config.storage[providerName]) {
         throw new Error(`Storage provider '${providerName}' not found in config`);
     }
     const providerConfig = config.storage[providerName];
-    switch (providerConfig.type) {
-        case 'local':
-            return new LocalStorageProvider(providerConfig);
-        default:
-            throw new Error(`Unknown storage provider type: ${providerConfig.type}`);
+    const factory = getStorageProviderFactory(providerConfig.type);
+    if (!factory) {
+        throw new Error(`Unknown storage provider type: ${providerConfig.type}. ` +
+            `Register it with registerStorageProvider('${providerConfig.type}', ...) from ` +
+            `'@opensaas/stack-storage/runtime' before use.`);
     }
+    return factory(providerConfig);
 }
 /**
  * Uploads a file to the specified storage provider
@@ -154,4 +165,7 @@ export async function deleteImage(config, metadata) {
     }
 }
 export { parseFileFromFormData } from '../utils/upload.js';
+// Provider registration API: hosts register optional/custom providers so
+// createStorageProvider can construct them (see registry.ts).
+export { registerStorageProvider, getStorageProviderFactory, hasStorageProvider, resetStorageProviderRegistry, } from './registry.js';
 //# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}

package/dist/runtime/registry.d.ts

@@ -0,0 +1,57 @@
+import type { StorageProvider, BaseStorageConfig } from '../config/types.js';
+/**
+ * A factory that constructs a {@link StorageProvider} from its provider config.
+ *
+ * The factory is generic over the concrete config shape so a provider package
+ * can register with full type safety (e.g. `S3StorageConfig`), while the
+ * registry stores factories against the {@link BaseStorageConfig} contract that
+ * every provider config satisfies.
+ *
+ * @typeParam TConfig - The provider-specific config type (must extend
+ * {@link BaseStorageConfig}).
+ */
+export type StorageProviderFactory<TConfig extends BaseStorageConfig = BaseStorageConfig> = (config: TConfig) => StorageProvider;
+/**
+ * Registers a storage provider factory for a given provider `type`.
+ *
+ * The host application calls this to opt in to a provider it uses — either one
+ * of the optional provider packages (`@opensaas/stack-storage-s3`,
+ * `@opensaas/stack-storage-vercel`) or a custom provider. Once registered,
+ * {@link createStorageProvider} can construct that provider when a field is
+ * bound to it.
+ *
+ * Registering an already-registered `type` overwrites the previous factory,
+ * allowing a host to replace a built-in (e.g. swap the default `'local'`
+ * provider) if needed.
+ *
+ * @typeParam TConfig - The provider-specific config type.
+ * @param type - The provider `type` discriminator used in storage config
+ * (e.g. `'s3'`, `'vercel-blob'`, `'cloudflare-r2'`).
+ * @param factory - A function that builds the provider from its config.
+ *
+ * @example
+ * ```typescript
+ * import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+ * import { S3StorageProvider, type S3StorageConfig } from '@opensaas/stack-storage-s3'
+ *
+ * registerStorageProvider<S3StorageConfig>('s3', (config) => new S3StorageProvider(config))
+ * ```
+ */
+export declare function registerStorageProvider<TConfig extends BaseStorageConfig>(type: string, factory: StorageProviderFactory<TConfig>): void;
+/**
+ * Returns the factory registered for a provider `type`, or `undefined` when no
+ * provider has been registered under that `type`.
+ */
+export declare function getStorageProviderFactory(type: string): StorageProviderFactory | undefined;
+/**
+ * Returns `true` when a provider factory is registered for the given `type`.
+ */
+export declare function hasStorageProvider(type: string): boolean;
+/**
+ * Resets the registry to only the built-in defaults.
+ *
+ * Primarily useful in tests to guarantee isolation between cases that register
+ * custom providers.
+ */
+export declare function resetStorageProviderRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/runtime/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAsB,MAAM,oBAAoB,CAAA;AAGhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,CAAC,OAAO,SAAS,iBAAiB,GAAG,iBAAiB,IAAI,CAC1F,MAAM,EAAE,OAAO,KACZ,eAAe,CAAA;AAYpB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAS,iBAAiB,EACvE,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACvC,IAAI,CAON;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAE1F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD"}

package/dist/runtime/registry.js

@@ -0,0 +1,81 @@
+import { LocalStorageProvider } from '../providers/local.js';
+/**
+ * Internal registry mapping a provider `type` to its factory.
+ *
+ * Factories are stored against {@link BaseStorageConfig} because every provider
+ * config extends it. `registerStorageProvider` narrows the public input to the
+ * concrete config type, then widens it for storage — this conversion happens
+ * once, internally, so the public API stays free of `any`/casts.
+ */
+const registry = new Map();
+/**
+ * Registers a storage provider factory for a given provider `type`.
+ *
+ * The host application calls this to opt in to a provider it uses — either one
+ * of the optional provider packages (`@opensaas/stack-storage-s3`,
+ * `@opensaas/stack-storage-vercel`) or a custom provider. Once registered,
+ * {@link createStorageProvider} can construct that provider when a field is
+ * bound to it.
+ *
+ * Registering an already-registered `type` overwrites the previous factory,
+ * allowing a host to replace a built-in (e.g. swap the default `'local'`
+ * provider) if needed.
+ *
+ * @typeParam TConfig - The provider-specific config type.
+ * @param type - The provider `type` discriminator used in storage config
+ * (e.g. `'s3'`, `'vercel-blob'`, `'cloudflare-r2'`).
+ * @param factory - A function that builds the provider from its config.
+ *
+ * @example
+ * ```typescript
+ * import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+ * import { S3StorageProvider, type S3StorageConfig } from '@opensaas/stack-storage-s3'
+ *
+ * registerStorageProvider<S3StorageConfig>('s3', (config) => new S3StorageProvider(config))
+ * ```
+ */
+export function registerStorageProvider(type, factory) {
+    // `factory` accepts a narrower `TConfig`; the registry stores it against the
+    // wider `BaseStorageConfig`. This widening wrapper is safe because
+    // `createStorageProvider` only ever invokes a factory with the config whose
+    // `type` selected it, so the runtime config always matches `TConfig`.
+    const widened = (config) => factory(config);
+    registry.set(type, widened);
+}
+/**
+ * Returns the factory registered for a provider `type`, or `undefined` when no
+ * provider has been registered under that `type`.
+ */
+export function getStorageProviderFactory(type) {
+    return registry.get(type);
+}
+/**
+ * Returns `true` when a provider factory is registered for the given `type`.
+ */
+export function hasStorageProvider(type) {
+    return registry.has(type);
+}
+/**
+ * Resets the registry to only the built-in defaults.
+ *
+ * Primarily useful in tests to guarantee isolation between cases that register
+ * custom providers.
+ */
+export function resetStorageProviderRegistry() {
+    registry.clear();
+    registerBuiltinProviders();
+}
+/**
+ * Registers the providers that ship with `@opensaas/stack-storage` itself.
+ *
+ * Currently only `'local'`, which keeps existing behaviour unchanged: hosts get
+ * local filesystem storage with no registration step. Optional providers
+ * (`s3`, `vercel-blob`) are NOT registered here — the host opts into those to
+ * avoid forcing the AWS/Vercel SDKs onto every storage user.
+ */
+function registerBuiltinProviders() {
+    registerStorageProvider('local', (config) => new LocalStorageProvider(config));
+}
+// Register built-in providers on module load so `'local'` works by default.
+registerBuiltinProviders();
+//# sourceMappingURL=registry.js.map

package/dist/runtime/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAiB5D;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAY,EACZ,OAAwC;IAExC,6EAA6E;IAC7E,mEAAmE;IACnE,4EAA4E;IAC5E,sEAAsE;IACtE,MAAM,OAAO,GAA2B,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAiB,CAAC,CAAA;IAC9E,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B;IAC1C,QAAQ,CAAC,KAAK,EAAE,CAAA;IAChB,wBAAwB,EAAE,CAAA;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,wBAAwB;IAC/B,uBAAuB,CAAqB,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAA;AACpG,CAAC;AAED,4EAA4E;AAC5E,wBAAwB,EAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-storage",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "File and image upload field types with pluggable storage providers for OpenSaas Stack",
   "type": "module",
   "exports": {
@@ -35,7 +35,7 @@
     "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@opensaas/stack-core": "0.23.0"
+    "@opensaas/stack-core": "0.25.0"
   },
   "peerDependencies": {
     "@opensaas/stack-core": "^0"

package/src/runtime/index.ts

@@ -1,17 +1,26 @@
 import type { OpenSaasConfig } from '@opensaas/stack-core'
 import type {
   StorageProvider,
-  LocalStorageConfig,
   FileMetadata,
   ImageMetadata,
   ImageTransformationConfig,
 } from '../config/types.js'
-import { LocalStorageProvider } from '../providers/local.js'
 import { validateFile, getMimeType, type FileValidationOptions } from '../utils/upload.js'
 import { getImageDimensions, processImageTransformations } from '../utils/image.js'
+import { getStorageProviderFactory } from './registry.js'
 
 /**
- * Creates a storage provider instance from config
+ * Creates a storage provider instance from config.
+ *
+ * The provider `type` is resolved through the provider registry (see
+ * {@link registerStorageProvider}) rather than a closed `switch`. `'local'` is
+ * registered as a built-in default, so it works with no registration step.
+ * Optional providers (`@opensaas/stack-storage-s3`,
+ * `@opensaas/stack-storage-vercel`) and custom providers must be registered by
+ * the host before they can be constructed.
+ *
+ * @throws If the named provider is not present in `config.storage`.
+ * @throws If no provider factory has been registered for the config's `type`.
  */
 export function createStorageProvider(
   config: OpenSaasConfig,
@@ -23,12 +32,16 @@ export function createStorageProvider(
 
   const providerConfig = config.storage[providerName]
 
-  switch (providerConfig.type) {
-    case 'local':
-      return new LocalStorageProvider(providerConfig as unknown as LocalStorageConfig)
-    default:
-      throw new Error(`Unknown storage provider type: ${providerConfig.type}`)
+  const factory = getStorageProviderFactory(providerConfig.type)
+  if (!factory) {
+    throw new Error(
+      `Unknown storage provider type: ${providerConfig.type}. ` +
+        `Register it with registerStorageProvider('${providerConfig.type}', ...) from ` +
+        `'@opensaas/stack-storage/runtime' before use.`,
+    )
   }
+
+  return factory(providerConfig)
 }
 
 /**
@@ -241,3 +254,13 @@ export async function deleteImage(config: OpenSaasConfig, metadata: ImageMetadat
 }
 
 export { parseFileFromFormData } from '../utils/upload.js'
+
+// Provider registration API: hosts register optional/custom providers so
+// createStorageProvider can construct them (see registry.ts).
+export {
+  registerStorageProvider,
+  getStorageProviderFactory,
+  hasStorageProvider,
+  resetStorageProviderRegistry,
+  type StorageProviderFactory,
+} from './registry.js'

package/src/runtime/registry.ts

@@ -0,0 +1,106 @@
+import type { StorageProvider, BaseStorageConfig, LocalStorageConfig } from '../config/types.js'
+import { LocalStorageProvider } from '../providers/local.js'
+
+/**
+ * A factory that constructs a {@link StorageProvider} from its provider config.
+ *
+ * The factory is generic over the concrete config shape so a provider package
+ * can register with full type safety (e.g. `S3StorageConfig`), while the
+ * registry stores factories against the {@link BaseStorageConfig} contract that
+ * every provider config satisfies.
+ *
+ * @typeParam TConfig - The provider-specific config type (must extend
+ * {@link BaseStorageConfig}).
+ */
+export type StorageProviderFactory<TConfig extends BaseStorageConfig = BaseStorageConfig> = (
+  config: TConfig,
+) => StorageProvider
+
+/**
+ * Internal registry mapping a provider `type` to its factory.
+ *
+ * Factories are stored against {@link BaseStorageConfig} because every provider
+ * config extends it. `registerStorageProvider` narrows the public input to the
+ * concrete config type, then widens it for storage — this conversion happens
+ * once, internally, so the public API stays free of `any`/casts.
+ */
+const registry = new Map<string, StorageProviderFactory>()
+
+/**
+ * Registers a storage provider factory for a given provider `type`.
+ *
+ * The host application calls this to opt in to a provider it uses — either one
+ * of the optional provider packages (`@opensaas/stack-storage-s3`,
+ * `@opensaas/stack-storage-vercel`) or a custom provider. Once registered,
+ * {@link createStorageProvider} can construct that provider when a field is
+ * bound to it.
+ *
+ * Registering an already-registered `type` overwrites the previous factory,
+ * allowing a host to replace a built-in (e.g. swap the default `'local'`
+ * provider) if needed.
+ *
+ * @typeParam TConfig - The provider-specific config type.
+ * @param type - The provider `type` discriminator used in storage config
+ * (e.g. `'s3'`, `'vercel-blob'`, `'cloudflare-r2'`).
+ * @param factory - A function that builds the provider from its config.
+ *
+ * @example
+ * ```typescript
+ * import { registerStorageProvider } from '@opensaas/stack-storage/runtime'
+ * import { S3StorageProvider, type S3StorageConfig } from '@opensaas/stack-storage-s3'
+ *
+ * registerStorageProvider<S3StorageConfig>('s3', (config) => new S3StorageProvider(config))
+ * ```
+ */
+export function registerStorageProvider<TConfig extends BaseStorageConfig>(
+  type: string,
+  factory: StorageProviderFactory<TConfig>,
+): void {
+  // `factory` accepts a narrower `TConfig`; the registry stores it against the
+  // wider `BaseStorageConfig`. This widening wrapper is safe because
+  // `createStorageProvider` only ever invokes a factory with the config whose
+  // `type` selected it, so the runtime config always matches `TConfig`.
+  const widened: StorageProviderFactory = (config) => factory(config as TConfig)
+  registry.set(type, widened)
+}
+
+/**
+ * Returns the factory registered for a provider `type`, or `undefined` when no
+ * provider has been registered under that `type`.
+ */
+export function getStorageProviderFactory(type: string): StorageProviderFactory | undefined {
+  return registry.get(type)
+}
+
+/**
+ * Returns `true` when a provider factory is registered for the given `type`.
+ */
+export function hasStorageProvider(type: string): boolean {
+  return registry.has(type)
+}
+
+/**
+ * Resets the registry to only the built-in defaults.
+ *
+ * Primarily useful in tests to guarantee isolation between cases that register
+ * custom providers.
+ */
+export function resetStorageProviderRegistry(): void {
+  registry.clear()
+  registerBuiltinProviders()
+}
+
+/**
+ * Registers the providers that ship with `@opensaas/stack-storage` itself.
+ *
+ * Currently only `'local'`, which keeps existing behaviour unchanged: hosts get
+ * local filesystem storage with no registration step. Optional providers
+ * (`s3`, `vercel-blob`) are NOT registered here — the host opts into those to
+ * avoid forcing the AWS/Vercel SDKs onto every storage user.
+ */
+function registerBuiltinProviders(): void {
+  registerStorageProvider<LocalStorageConfig>('local', (config) => new LocalStorageProvider(config))
+}
+
+// Register built-in providers on module load so `'local'` works by default.
+registerBuiltinProviders()

package/tests/provider-registry.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import type { OpenSaasConfig } from '@opensaas/stack-core'
+import {
+  createStorageProvider,
+  registerStorageProvider,
+  getStorageProviderFactory,
+  hasStorageProvider,
+  resetStorageProviderRegistry,
+} from '../src/runtime/index.js'
+import { LocalStorageProvider } from '../src/providers/local.js'
+import { assembleImageMetadata, keystoneImageColumnMap } from '../src/utils/multi-column.js'
+import type {
+  StorageProvider,
+  UploadOptions,
+  UploadResult,
+  BaseStorageConfig,
+} from '../src/config/types.js'
+
+/**
+ * A minimal custom provider config + implementation used to prove that a
+ * non-`local`, host-registered provider can be constructed via the registry —
+ * without `@opensaas/stack-storage` depending on `-s3`/`-vercel`.
+ */
+interface FakeStorageConfig extends BaseStorageConfig {
+  type: 'fake'
+  baseUrl: string
+}
+
+class FakeStorageProvider implements StorageProvider {
+  constructor(public readonly config: FakeStorageConfig) {}
+
+  async upload(
+    _file: Buffer | Uint8Array,
+    filename: string,
+    options?: UploadOptions,
+  ): Promise<UploadResult> {
+    return {
+      filename,
+      url: `${this.config.baseUrl}/${filename}`,
+      size: 0,
+      contentType: options?.contentType ?? 'application/octet-stream',
+    }
+  }
+
+  async download(): Promise<Buffer> {
+    return Buffer.from('')
+  }
+
+  async delete(): Promise<void> {}
+
+  getUrl(filename: string): string {
+    return `${this.config.baseUrl}/${filename}`
+  }
+}
+
+/** Builds a minimal, strongly-typed config carrying a single storage provider. */
+function configWith(name: string, providerConfig: BaseStorageConfig): OpenSaasConfig {
+  return {
+    db: { provider: 'sqlite' },
+    lists: {},
+    storage: { [name]: providerConfig },
+  }
+}
+
+describe('storage provider registry', () => {
+  beforeEach(() => {
+    // Restore registry to built-in defaults so registrations don't leak.
+    resetStorageProviderRegistry()
+  })
+
+  describe('built-in defaults', () => {
+    it("registers 'local' by default so createStorageProvider builds it", () => {
+      const config = configWith('files', {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      })
+
+      const provider = createStorageProvider(config, 'files')
+
+      expect(provider).toBeInstanceOf(LocalStorageProvider)
+    })
+
+    it("reports 'local' as registered", () => {
+      expect(hasStorageProvider('local')).toBe(true)
+      expect(getStorageProviderFactory('local')).toBeTypeOf('function')
+    })
+  })
+
+  describe('registering a custom provider', () => {
+    it('lets createStorageProvider construct a registered non-local provider', () => {
+      registerStorageProvider<FakeStorageConfig>(
+        'fake',
+        (providerConfig) => new FakeStorageProvider(providerConfig),
+      )
+
+      const config = configWith('cdn', {
+        type: 'fake',
+        baseUrl: 'https://cdn.example.com',
+      })
+
+      const provider = createStorageProvider(config, 'cdn')
+
+      expect(provider).toBeInstanceOf(FakeStorageProvider)
+      expect(provider.getUrl('photo.jpg')).toBe('https://cdn.example.com/photo.jpg')
+    })
+
+    it('passes the provider config through to the factory', () => {
+      let received: FakeStorageConfig | undefined
+      registerStorageProvider<FakeStorageConfig>('fake', (providerConfig) => {
+        received = providerConfig
+        return new FakeStorageProvider(providerConfig)
+      })
+
+      const providerConfig: FakeStorageConfig = {
+        type: 'fake',
+        baseUrl: 'https://assets.example.com',
+      }
+
+      createStorageProvider(configWith('assets', providerConfig), 'assets')
+
+      expect(received).toEqual(providerConfig)
+    })
+
+    it('reflects registration via hasStorageProvider/getStorageProviderFactory', () => {
+      expect(hasStorageProvider('fake')).toBe(false)
+
+      registerStorageProvider<FakeStorageConfig>(
+        'fake',
+        (providerConfig) => new FakeStorageProvider(providerConfig),
+      )
+
+      expect(hasStorageProvider('fake')).toBe(true)
+      expect(getStorageProviderFactory('fake')).toBeTypeOf('function')
+    })
+
+    it('overwrites a previous registration for the same type', () => {
+      registerStorageProvider<FakeStorageConfig>(
+        'fake',
+        (providerConfig) => new FakeStorageProvider({ ...providerConfig, baseUrl: 'first' }),
+      )
+      registerStorageProvider<FakeStorageConfig>(
+        'fake',
+        (providerConfig) => new FakeStorageProvider({ ...providerConfig, baseUrl: 'second' }),
+      )
+
+      const provider = createStorageProvider(
+        configWith('cdn', { type: 'fake', baseUrl: 'ignored' }),
+        'cdn',
+      )
+
+      expect(provider.getUrl('x')).toBe('second/x')
+    })
+  })
+
+  describe('unregistered providers', () => {
+    it('throws a clear error for an unregistered type', () => {
+      const config = configWith('cdn', { type: 's3', bucket: 'my-bucket' })
+
+      expect(() => createStorageProvider(config, 'cdn')).toThrow(
+        /Unknown storage provider type: s3/,
+      )
+      expect(() => createStorageProvider(config, 'cdn')).toThrow(/registerStorageProvider/)
+    })
+
+    it('still throws when the named provider is absent from config', () => {
+      const config = configWith('files', {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      })
+
+      expect(() => createStorageProvider(config, 'missing')).toThrow(
+        /Storage provider 'missing' not found in config/,
+      )
+    })
+  })
+
+  describe('read path is unaffected by the registry', () => {
+    it('assembleImageMetadata stamps the provider name without constructing a provider', () => {
+      // No provider registered for 'remote'; the read path must not care.
+      expect(hasStorageProvider('remote')).toBe(false)
+
+      const map = keystoneImageColumnMap('image')
+      const row = {
+        image_url: 'https://cdn.example.com/pic.jpg',
+        image_width: 800,
+        image_height: 600,
+        image_filesize: 1234,
+        image_contentType: 'image/jpeg',
+        image_pathname: 'pic.jpg',
+      }
+
+      const meta = assembleImageMetadata(row, map, 'remote')
+
+      expect(meta).not.toBeNull()
+      expect(meta?.storageProvider).toBe('remote')
+      expect(meta?.url).toBe('https://cdn.example.com/pic.jpg')
+    })
+  })
+})