@svadmin/storage 0.0.0-stage → 0.2.1

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@svadmin/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Storage adapters — S3, Cloudflare R2, and in-memory storage provider for svadmin",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@svadmin/core": "^0.76.0"
+  },
+  "keywords": [
+    "svadmin",
+    "storage",
+    "s3",
+    "r2",
+    "storage-provider"
+  ],
+  "license": "MIT",
+  "author": "zuohuadong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibeunion/svadmin.git",
+    "directory": "packages/storage"
+  },
+  "homepage": "https://github.com/vibeunion/svadmin#readme",
+  "bugs": {
+    "url": "https://github.com/vibeunion/svadmin/issues"
+  },
+  "svadmin": {
+    "capabilities": [
+      "storage"
+    ],
+    "core": "^0.55.0",
+    "stability": "stable",
+    "migration": null
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { createMemoryStorageProvider } from './memory-storage';
+export type { MemoryStorageOptions } from './memory-storage';
+
+export { createS3StorageProvider } from './s3-storage';
+export type { FetchLike, S3StorageOptions } from './s3-storage';
+
+export { validateFile, uploadBatch } from './upload-utils';
+export type { FileValidationOptions, BatchUploadOptions } from './upload-utils';
+
+export type {
+  StorageProvider,
+  StorageUploadOptions,
+  StorageUploadResult,
+  StoragePresignedUrlOptions,
+  StorageFileItem,
+  StorageListOptions,
+} from '@svadmin/core';

package/src/memory-storage.ts

@@ -0,0 +1,89 @@
+import type {
+  StorageProvider,
+  StorageUploadOptions,
+  StorageUploadResult,
+  StorageFileItem,
+  StorageListOptions,
+  StoragePresignedUrlOptions,
+} from '@svadmin/core';
+
+export interface MemoryStorageOptions {
+  baseUrl?: string;
+}
+
+export function createMemoryStorageProvider(options: MemoryStorageOptions = {}): StorageProvider {
+  const baseUrl = (options.baseUrl ?? 'https://storage.local').replace(/\/+$/, '');
+  const files = new Map<string, { bytes: Uint8Array; contentType: string; metadata?: Record<string, string>; updatedAt: Date }>();
+
+  return {
+    async upload(file: File | Blob | ArrayBuffer | Uint8Array, uploadOptions?: StorageUploadOptions): Promise<StorageUploadResult> {
+      const filename = uploadOptions?.filename ?? (file instanceof File ? file.name : 'upload.bin');
+      const dir = uploadOptions?.path ? uploadOptions.path.replace(/^\/+|\/+$/g, '') : '';
+      const fullPath = dir ? `${dir}/${filename}` : filename;
+
+      let bytes: Uint8Array;
+      if (file instanceof Uint8Array) {
+        bytes = file;
+      } else if (file instanceof ArrayBuffer) {
+        bytes = new Uint8Array(file);
+      } else {
+        bytes = new Uint8Array(await file.arrayBuffer());
+      }
+
+      const contentType = uploadOptions?.contentType ?? (typeof File !== 'undefined' && file instanceof File ? file.type : 'application/octet-stream');
+      files.set(fullPath, {
+        bytes,
+        contentType: contentType || 'application/octet-stream',
+        updatedAt: new Date(),
+        ...(uploadOptions?.metadata === undefined ? {} : { metadata: uploadOptions.metadata }),
+      });
+
+      uploadOptions?.onProgress?.({
+        loaded: bytes.byteLength,
+        total: bytes.byteLength,
+        percentage: 100,
+      });
+
+      return {
+        url: `${baseUrl}/${fullPath}`,
+        path: fullPath,
+        size: bytes.byteLength,
+        contentType,
+        ...(uploadOptions?.metadata === undefined ? {} : { metadata: uploadOptions.metadata }),
+      };
+    },
+
+    async delete(path: string): Promise<void> {
+      const cleanPath = path.replace(/^\/+/, '');
+      files.delete(cleanPath);
+    },
+
+    async getPresignedUrl(path: string, presignedOptions?: StoragePresignedUrlOptions): Promise<string> {
+      const cleanPath = path.replace(/^\/+/, '');
+      const op = presignedOptions?.operation ?? 'get';
+      const expires = presignedOptions?.expiresInSeconds ?? 3600;
+      return `${baseUrl}/${cleanPath}?op=${op}&expires=${expires}&signature=mock-sig`;
+    },
+
+    async list(listOptions?: StorageListOptions): Promise<StorageFileItem[]> {
+      const prefix = listOptions?.prefix ? listOptions.prefix.replace(/^\/+/, '') : '';
+      const limit = listOptions?.limit ?? 1000;
+      const result: StorageFileItem[] = [];
+
+      for (const [key, value] of files.entries()) {
+        if (!prefix || key.startsWith(prefix)) {
+          result.push({
+            name: key.split('/').pop() ?? key,
+            path: key,
+            size: value.bytes.byteLength,
+            lastModified: value.updatedAt,
+            url: `${baseUrl}/${key}`,
+          });
+          if (result.length >= limit) break;
+        }
+      }
+
+      return result;
+    },
+  };
+}

package/src/s3-storage.ts

@@ -0,0 +1,112 @@
+import type {
+  StorageProvider,
+  StorageUploadOptions,
+  StorageUploadResult,
+  StorageFileItem,
+  StorageListOptions,
+  StoragePresignedUrlOptions,
+} from '@svadmin/core';
+
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export interface S3StorageOptions {
+  /** S3 or S3-compatible (Cloudflare R2, MinIO, Wasabi) bucket name */
+  bucket: string;
+  /** Public or CDN base URL for downloading files */
+  publicUrl?: string;
+  /**
+   * Function to request a presigned PUT URL from your backend or serverless handler.
+   * Enables direct client-to-storage uploads without exposing credentials.
+   */
+  getPresignedUploadUrl?: (params: { path: string; contentType?: string }) => Promise<{ uploadUrl: string; downloadUrl?: string }>;
+  /** Request a signed download or upload URL from the backend. */
+  getPresignedUrl?: (params: { path: string; operation: 'get' | 'put'; expiresInSeconds: number }) => Promise<string>;
+  /** List objects through a backend endpoint; direct bucket listing is not exposed to browsers. */
+  listFiles?: (options?: StorageListOptions) => Promise<StorageFileItem[]>;
+  /**
+   * Custom fetch implementation
+   */
+  fetch?: FetchLike;
+}
+
+export function createS3StorageProvider(options: S3StorageOptions): StorageProvider {
+  const customFetch = options.fetch ?? fetch;
+  const publicBaseUrl = (options.publicUrl ?? `https://${options.bucket}.s3.amazonaws.com`).replace(/\/+$/, '');
+
+  return {
+    async upload(file: File | Blob | ArrayBuffer | Uint8Array, uploadOptions?: StorageUploadOptions): Promise<StorageUploadResult> {
+      const filename = uploadOptions?.filename ?? (typeof File !== 'undefined' && file instanceof File ? file.name : 'upload.bin');
+      const dir = uploadOptions?.path ? uploadOptions.path.replace(/^\/+|\/+$/g, '') : '';
+      const fullPath = dir ? `${dir}/${filename}` : filename;
+      const contentType = uploadOptions?.contentType ?? (typeof File !== 'undefined' && file instanceof File ? file.type : 'application/octet-stream');
+
+      let bodyData: BodyInit;
+      let byteSize: number | undefined;
+
+      if (file instanceof Uint8Array || file instanceof ArrayBuffer) {
+        bodyData = file as BodyInit;
+        byteSize = file.byteLength;
+      } else {
+        bodyData = file;
+        byteSize = file.size;
+      }
+
+      if (options.getPresignedUploadUrl) {
+        const presigned = await options.getPresignedUploadUrl({
+          path: fullPath,
+          contentType,
+        });
+
+        const uploadRes = await customFetch(presigned.uploadUrl, {
+          method: 'PUT',
+          headers: {
+            'Content-Type': contentType || 'application/octet-stream',
+          },
+          body: bodyData,
+        });
+
+        if (!uploadRes.ok) {
+          throw new Error(`Failed to upload to presigned S3 URL: ${uploadRes.status} ${uploadRes.statusText}`);
+        }
+
+        uploadOptions?.onProgress?.({
+          loaded: byteSize ?? 100,
+          total: byteSize ?? 100,
+          percentage: 100,
+        });
+
+        return {
+          url: presigned.downloadUrl ?? `${publicBaseUrl}/${fullPath}`,
+          path: fullPath,
+          size: byteSize,
+          contentType,
+          ...(uploadOptions?.metadata === undefined ? {} : { metadata: uploadOptions.metadata }),
+        };
+      }
+
+      throw new Error('S3 storage upload requires getPresignedUploadUrl');
+    },
+
+    async delete(path: string): Promise<void> {
+      // In client mode, delete operations typically call the backend API
+      const cleanPath = path.replace(/^\/+/, '');
+      const response = await customFetch(`${publicBaseUrl}/${cleanPath}`, {
+        method: 'DELETE',
+      });
+      if (!response.ok) throw new Error(`Failed to delete storage object: ${response.status} ${response.statusText}`);
+    },
+
+    async getPresignedUrl(path: string, presignedOptions?: StoragePresignedUrlOptions): Promise<string> {
+      const cleanPath = path.replace(/^\/+/, '');
+      const op = presignedOptions?.operation ?? 'get';
+      const expires = presignedOptions?.expiresInSeconds ?? 3600;
+      if (!options.getPresignedUrl) throw new Error('S3 storage presigned URLs require getPresignedUrl');
+      return options.getPresignedUrl({ path: cleanPath, operation: op, expiresInSeconds: expires });
+    },
+
+    async list(listOptions?: StorageListOptions): Promise<StorageFileItem[]> {
+      if (!options.listFiles) throw new Error('S3 storage listing requires listFiles');
+      return options.listFiles(listOptions);
+    },
+  };
+}

package/src/upload-utils.ts

@@ -0,0 +1,81 @@
+import type { StorageProvider, StorageUploadOptions, StorageUploadResult } from '@svadmin/core';
+
+export interface FileValidationOptions {
+  maxSizeBytes?: number;
+  allowedMimeTypes?: string[];
+}
+
+export function validateFile(file: File | Blob, options: FileValidationOptions): { valid: boolean; error?: string } {
+  if (options.maxSizeBytes && file.size > options.maxSizeBytes) {
+    const maxMb = (options.maxSizeBytes / (1024 * 1024)).toFixed(1);
+    return {
+      valid: false,
+      error: `File size exceeds maximum limit of ${maxMb}MB`,
+    };
+  }
+
+  if (options.allowedMimeTypes && options.allowedMimeTypes.length > 0 && file.type) {
+    const isAllowed = options.allowedMimeTypes.some((pattern) => {
+      if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -1);
+        return file.type.startsWith(prefix);
+      }
+      return file.type === pattern;
+    });
+
+    if (!isAllowed) {
+      return {
+        valid: false,
+        error: `File type "${file.type}" is not allowed. Supported: ${options.allowedMimeTypes.join(', ')}`,
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
+export interface BatchUploadOptions extends StorageUploadOptions {
+  concurrency?: number;
+  onOverallProgress?: (progress: { completed: number; total: number; percentage: number }) => void;
+}
+
+export async function uploadBatch(
+  storage: StorageProvider,
+  files: (File | Blob)[],
+  options: BatchUploadOptions = {},
+): Promise<StorageUploadResult[]> {
+  const total = files.length;
+  if (total === 0) return [];
+
+  const { concurrency: requestedConcurrency, onOverallProgress, ...uploadOptions } = options;
+  const concurrency = Math.max(1, requestedConcurrency ?? 3);
+  const results: StorageUploadResult[] = new Array(total);
+  let completed = 0;
+
+  async function uploadWorker(startIndex: number, step: number) {
+    for (let i = startIndex; i < total; i += step) {
+      const file = files[i];
+      if (!file) throw new Error(`Missing file at batch index ${i}`);
+      const filename = typeof File !== 'undefined' && file instanceof File ? file.name : `file-${i}.bin`;
+      const res = await storage.upload(file, {
+        ...uploadOptions,
+        filename: uploadOptions.filename ? `${i}-${uploadOptions.filename}` : filename,
+      });
+      results[i] = res;
+      completed++;
+      onOverallProgress?.({
+        completed,
+        total,
+        percentage: Math.round((completed / total) * 100),
+      });
+    }
+  }
+
+  const workers: Promise<void>[] = [];
+  for (let c = 0; c < Math.min(concurrency, total); c++) {
+    workers.push(uploadWorker(c, concurrency));
+  }
+
+  await Promise.all(workers);
+  return results;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.