@jant/core 0.3.8 → 0.3.9

package/src/lib/__tests__/storage.test.ts

@@ -0,0 +1,162 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion -- Test assertions use ! for readability */
+import { describe, it, expect, vi } from "vitest";
+import { createR2Driver, createStorageDriver } from "../storage.js";
+import type { Bindings } from "../../types.js";
+
+describe("createStorageDriver", () => {
+  it("returns null when no storage is configured", () => {
+    const env = { DB: {} } as Bindings;
+    const driver = createStorageDriver(env);
+    expect(driver).toBeNull();
+  });
+
+  it("returns R2 driver when R2 binding is present", () => {
+    const env = {
+      DB: {},
+      R2: { put: vi.fn(), get: vi.fn(), delete: vi.fn() },
+    } as unknown as Bindings;
+    const driver = createStorageDriver(env);
+    expect(driver).not.toBeNull();
+  });
+
+  it("returns R2 driver by default even with STORAGE_DRIVER unset", () => {
+    const env = {
+      DB: {},
+      R2: { put: vi.fn(), get: vi.fn(), delete: vi.fn() },
+    } as unknown as Bindings;
+    const driver = createStorageDriver(env);
+    expect(driver).not.toBeNull();
+  });
+
+  it("returns null for S3 driver when S3 config is incomplete", () => {
+    const env = {
+      DB: {},
+      STORAGE_DRIVER: "s3",
+      S3_ENDPOINT: "https://s3.example.com",
+      // Missing S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY
+    } as unknown as Bindings;
+    const driver = createStorageDriver(env);
+    expect(driver).toBeNull();
+  });
+
+  it("returns S3 driver when fully configured", () => {
+    const env = {
+      DB: {},
+      STORAGE_DRIVER: "s3",
+      S3_ENDPOINT: "https://s3.example.com",
+      S3_BUCKET: "my-bucket",
+      S3_ACCESS_KEY_ID: "access-key",
+      S3_SECRET_ACCESS_KEY: "secret-key",
+      S3_REGION: "us-east-1",
+    } as unknown as Bindings;
+    const driver = createStorageDriver(env);
+    expect(driver).not.toBeNull();
+  });
+
+  it("defaults S3_REGION to 'auto' when not set", () => {
+    const env = {
+      DB: {},
+      STORAGE_DRIVER: "s3",
+      S3_ENDPOINT: "https://s3.example.com",
+      S3_BUCKET: "my-bucket",
+      S3_ACCESS_KEY_ID: "access-key",
+      S3_SECRET_ACCESS_KEY: "secret-key",
+    } as unknown as Bindings;
+    // Should not throw - region defaults to "auto"
+    const driver = createStorageDriver(env);
+    expect(driver).not.toBeNull();
+  });
+
+  it("prefers S3 driver over R2 when STORAGE_DRIVER=s3", () => {
+    const env = {
+      DB: {},
+      R2: { put: vi.fn(), get: vi.fn(), delete: vi.fn() },
+      STORAGE_DRIVER: "s3",
+      S3_ENDPOINT: "https://s3.example.com",
+      S3_BUCKET: "my-bucket",
+      S3_ACCESS_KEY_ID: "access-key",
+      S3_SECRET_ACCESS_KEY: "secret-key",
+    } as unknown as Bindings;
+    const driver = createStorageDriver(env);
+    expect(driver).not.toBeNull();
+  });
+});
+
+describe("createR2Driver", () => {
+  it("delegates put to R2 bucket", async () => {
+    const mockR2 = {
+      put: vi.fn().mockResolvedValue(undefined),
+      get: vi.fn(),
+      delete: vi.fn(),
+    } as unknown as R2Bucket;
+
+    const driver = createR2Driver(mockR2);
+    const body = new ReadableStream();
+    await driver.put("media/test.jpg", body, { contentType: "image/jpeg" });
+
+    expect(mockR2.put).toHaveBeenCalledWith("media/test.jpg", body, {
+      httpMetadata: { contentType: "image/jpeg" },
+    });
+  });
+
+  it("delegates put without contentType", async () => {
+    const mockR2 = {
+      put: vi.fn().mockResolvedValue(undefined),
+      get: vi.fn(),
+      delete: vi.fn(),
+    } as unknown as R2Bucket;
+
+    const driver = createR2Driver(mockR2);
+    await driver.put("media/test.jpg", new ReadableStream());
+
+    expect(mockR2.put).toHaveBeenCalledWith(
+      "media/test.jpg",
+      expect.any(ReadableStream),
+      { httpMetadata: undefined },
+    );
+  });
+
+  it("delegates get and returns body and contentType", async () => {
+    const mockBody = new ReadableStream();
+    const mockR2 = {
+      put: vi.fn(),
+      get: vi.fn().mockResolvedValue({
+        body: mockBody,
+        httpMetadata: { contentType: "image/jpeg" },
+      }),
+      delete: vi.fn(),
+    } as unknown as R2Bucket;
+
+    const driver = createR2Driver(mockR2);
+    const result = await driver.get("media/test.jpg");
+
+    expect(result).not.toBeNull();
+    expect(result!.body).toBe(mockBody);
+    expect(result!.contentType).toBe("image/jpeg");
+  });
+
+  it("returns null when R2 get returns null", async () => {
+    const mockR2 = {
+      put: vi.fn(),
+      get: vi.fn().mockResolvedValue(null),
+      delete: vi.fn(),
+    } as unknown as R2Bucket;
+
+    const driver = createR2Driver(mockR2);
+    const result = await driver.get("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  it("delegates delete to R2 bucket", async () => {
+    const mockR2 = {
+      put: vi.fn(),
+      get: vi.fn(),
+      delete: vi.fn().mockResolvedValue(undefined),
+    } as unknown as R2Bucket;
+
+    const driver = createR2Driver(mockR2);
+    await driver.delete("media/test.jpg");
+
+    expect(mockR2.delete).toHaveBeenCalledWith("media/test.jpg");
+  });
+});

package/src/lib/image.ts

@@ -71,37 +71,67 @@ export function getImageUrl(
   return `${transformUrl}/${params.join(",")}/${originalUrl}`;
 }
 
+/**
+ * Returns the appropriate public URL base for a given storage provider.
+ *
+ * For `"s3"` provider, returns `s3PublicUrl`. For all other providers
+ * (including `"r2"`), returns `r2PublicUrl`. Falls back to `undefined`
+ * if the matching URL is not configured.
+ *
+ * @param provider - The storage provider identifier (e.g., `"r2"`, `"s3"`)
+ * @param r2PublicUrl - Optional R2 public URL
+ * @param s3PublicUrl - Optional S3 public URL
+ * @returns The public URL base for the provider, or undefined
+ *
+ * @example
+ * ```ts
+ * getPublicUrlForProvider("r2", "https://r2.example.com", "https://s3.example.com");
+ * // Returns: "https://r2.example.com"
+ *
+ * getPublicUrlForProvider("s3", "https://r2.example.com", "https://s3.example.com");
+ * // Returns: "https://s3.example.com"
+ * ```
+ */
+export function getPublicUrlForProvider(
+  provider: string,
+  r2PublicUrl?: string,
+  s3PublicUrl?: string,
+): string | undefined {
+  if (provider === "s3") return s3PublicUrl;
+  return r2PublicUrl;
+}
+
 /**
  * Generates a media URL using UUIDv7-based paths.
  *
- * Returns a public URL for a media file. If `r2PublicUrl` is set, uses that directly
- * with the r2Key. Otherwise, generates a `/media/{id}.{ext}` URL.
+ * Returns a public URL for a media file. If `publicUrl` is set, uses that directly
+ * with the storage key. Otherwise, generates a `/media/{id}.{ext}` local proxy URL.
  *
  * @param mediaId - The UUIDv7 database ID of the media
- * @param r2Key - The R2 storage key (used to extract extension)
- * @param r2PublicUrl - Optional R2 public URL for direct CDN access
+ * @param storageKey - The storage object key (used to build CDN path and extract extension)
+ * @param publicUrl - Optional public URL base for direct CDN access
  * @returns The public URL for the media file
  *
  * @example
  * ```ts
- * // Without R2 public URL - uses UUID with extension
- * getMediaUrl("01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "media/2025/01/01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f.webp");
- * // Returns: "/media/01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f.webp"
+ * // Without public URL - uses local proxy with UUID and extension
+ * getMediaUrl("01902a9f-1a2b-7c3d", "media/2025/01/01902a9f-1a2b-7c3d.webp");
+ * // Returns: "/media/01902a9f-1a2b-7c3d.webp"
  *
- * // With R2 public URL - uses direct CDN
- * getMediaUrl("01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "media/2025/01/01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f.webp", "https://cdn.example.com");
- * // Returns: "https://cdn.example.com/media/2025/01/01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f.webp"
+ * // With public URL - uses direct CDN
+ * getMediaUrl("01902a9f-1a2b-7c3d", "media/2025/01/01902a9f-1a2b-7c3d.webp", "https://cdn.example.com");
+ * // Returns: "https://cdn.example.com/media/2025/01/01902a9f-1a2b-7c3d.webp"
  * ```
  */
 export function getMediaUrl(
   mediaId: string,
-  r2Key: string,
-  r2PublicUrl?: string,
+  storageKey: string,
+  publicUrl?: string,
 ): string {
-  if (r2PublicUrl) {
-    return `${r2PublicUrl}/${r2Key}`;
+  if (publicUrl) {
+    return `${publicUrl.replace(/\/+$/, "")}/${storageKey}`;
   }
-  // Extract extension from r2Key
-  const ext = r2Key.split(".").pop() || "bin";
+  // Extract extension from storage key
+  const ext = storageKey.split(".").pop() || "bin";
   return `/media/${mediaId}.${ext}`;
 }

package/src/lib/media-helpers.ts

@@ -5,49 +5,60 @@
  */
 
 import type { Media, MediaAttachment } from "../types.js";
-import { getMediaUrl, getImageUrl } from "./image.js";
+import { getMediaUrl, getImageUrl, getPublicUrlForProvider } from "./image.js";
 
 /**
  * Builds a map of post IDs to MediaAttachment arrays from raw media data.
  *
- * Transforms raw Media objects (with R2 keys) into MediaAttachment objects
+ * Transforms raw Media objects (with storage keys) into MediaAttachment objects
  * (with public URLs and preview URLs) suitable for rendering.
+ * Automatically resolves the correct public URL based on each media item's
+ * storage provider (`"r2"` or `"s3"`).
  *
  * @param rawMediaMap - Map of post IDs to raw Media arrays from the media service
  * @param r2PublicUrl - Optional R2 public URL for direct CDN access
  * @param imageTransformUrl - Optional image transformation service URL
+ * @param s3PublicUrl - Optional S3 public URL for direct CDN access
  * @returns Map of post IDs to MediaAttachment arrays
  *
  * @example
  * ```ts
  * const rawMediaMap = await services.media.getByPostIds(postIds);
- * const mediaMap = buildMediaMap(rawMediaMap, c.env.R2_PUBLIC_URL, c.env.IMAGE_TRANSFORM_URL);
+ * const mediaMap = buildMediaMap(rawMediaMap, c.env.R2_PUBLIC_URL, c.env.IMAGE_TRANSFORM_URL, c.env.S3_PUBLIC_URL);
  * ```
  */
 export function buildMediaMap(
   rawMediaMap: Map<number, Media[]>,
   r2PublicUrl?: string,
   imageTransformUrl?: string,
+  s3PublicUrl?: string,
 ): Map<number, MediaAttachment[]> {
   const mediaMap = new Map<number, MediaAttachment[]>();
   for (const [postId, mediaList] of rawMediaMap) {
     mediaMap.set(
       postId,
-      mediaList.map((m) => ({
-        id: m.id,
-        url: getMediaUrl(m.id, m.r2Key, r2PublicUrl),
-        previewUrl: getImageUrl(
-          getMediaUrl(m.id, m.r2Key, r2PublicUrl),
-          imageTransformUrl,
-          { width: 400, quality: 80, format: "auto", fit: "cover" },
-        ),
-        alt: m.alt,
-        blurhash: m.blurhash,
-        width: m.width,
-        height: m.height,
-        position: m.position,
-        mimeType: m.mimeType,
-      })),
+      mediaList.map((m) => {
+        const publicUrl = getPublicUrlForProvider(
+          m.provider,
+          r2PublicUrl,
+          s3PublicUrl,
+        );
+        return {
+          id: m.id,
+          url: getMediaUrl(m.id, m.storageKey, publicUrl),
+          previewUrl: getImageUrl(
+            getMediaUrl(m.id, m.storageKey, publicUrl),
+            imageTransformUrl,
+            { width: 400, quality: 80, format: "auto", fit: "cover" },
+          ),
+          alt: m.alt,
+          blurhash: m.blurhash,
+          width: m.width,
+          height: m.height,
+          position: m.position,
+          mimeType: m.mimeType,
+        };
+      }),
     );
   }
   return mediaMap;

package/src/lib/storage.ts

@@ -0,0 +1,236 @@
+/**
+ * Storage Driver Abstraction
+ *
+ * Provides a common interface for file storage with R2 and S3-compatible backends.
+ */
+
+import type { Bindings } from "../types.js";
+
+/**
+ * Common interface for storage operations.
+ *
+ * Both R2 and S3-compatible drivers implement this interface,
+ * allowing the rest of the application to be storage-agnostic.
+ */
+export interface StorageDriver {
+  /** Upload a file to storage */
+  put(
+    key: string,
+    body: ReadableStream | Uint8Array,
+    opts?: { contentType?: string },
+  ): Promise<void>;
+
+  /** Retrieve a file from storage. Returns null if not found. */
+  get(
+    key: string,
+  ): Promise<{ body: ReadableStream; contentType?: string } | null>;
+
+  /** Delete a file from storage */
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Creates an R2 storage driver that delegates to a Cloudflare R2 bucket binding.
+ *
+ * @param r2 - The R2 bucket binding from the Cloudflare Workers environment
+ * @returns A StorageDriver backed by R2
+ */
+export function createR2Driver(r2: R2Bucket): StorageDriver {
+  return {
+    async put(key, body, opts) {
+      await r2.put(key, body, {
+        httpMetadata: opts?.contentType
+          ? { contentType: opts.contentType }
+          : undefined,
+      });
+    },
+
+    async get(key) {
+      const object = await r2.get(key);
+      if (!object) return null;
+      return {
+        body: object.body,
+        contentType: object.httpMetadata?.contentType ?? undefined,
+      };
+    },
+
+    async delete(key) {
+      await r2.delete(key);
+    },
+  };
+}
+
+/**
+ * Configuration for the S3-compatible storage driver.
+ */
+export interface S3DriverConfig {
+  endpoint: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+}
+
+/**
+ * Creates an S3-compatible storage driver using the AWS SDK.
+ *
+ * Supports any S3-compatible service: AWS S3, Backblaze B2, MinIO, etc.
+ * Uses path-style addressing for non-AWS endpoints.
+ *
+ * @param config - S3 connection configuration
+ * @returns A StorageDriver backed by S3
+ */
+export function createS3Driver(config: S3DriverConfig): StorageDriver {
+  // Lazy-load the AWS SDK to avoid bundling it when using R2
+  let clientPromise: Promise<{
+    send: (command: unknown) => Promise<unknown>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
+    S3Client: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
+    PutObjectCommand: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
+    GetObjectCommand: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
+    DeleteObjectCommand: any;
+    bucket: string;
+  }> | null = null;
+
+  function getClient() {
+    if (!clientPromise) {
+      clientPromise = import("@aws-sdk/client-s3").then((sdk) => {
+        const forcePathStyle = !config.endpoint.includes("amazonaws.com");
+        const client = new sdk.S3Client({
+          endpoint: config.endpoint,
+          region: config.region,
+          credentials: {
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+          },
+          forcePathStyle,
+        });
+        return {
+          send: (cmd: unknown) => client.send(cmd as never),
+          S3Client: sdk.S3Client,
+          PutObjectCommand: sdk.PutObjectCommand,
+          GetObjectCommand: sdk.GetObjectCommand,
+          DeleteObjectCommand: sdk.DeleteObjectCommand,
+          bucket: config.bucket,
+        };
+      });
+    }
+    return clientPromise;
+  }
+
+  return {
+    async put(key, body, opts) {
+      const s3 = await getClient();
+
+      // Buffer the stream to Uint8Array for the S3 SDK
+      let bodyBytes: Uint8Array;
+      if (body instanceof Uint8Array) {
+        bodyBytes = body;
+      } else {
+        const reader = body.getReader();
+        const chunks: Uint8Array[] = [];
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          chunks.push(value);
+        }
+        let totalLength = 0;
+        for (const chunk of chunks) totalLength += chunk.length;
+        bodyBytes = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+          bodyBytes.set(chunk, offset);
+          offset += chunk.length;
+        }
+      }
+
+      const command = new s3.PutObjectCommand({
+        Bucket: s3.bucket,
+        Key: key,
+        Body: bodyBytes,
+        ContentType: opts?.contentType,
+      });
+      await s3.send(command);
+    },
+
+    async get(key) {
+      const s3 = await getClient();
+      try {
+        const command = new s3.GetObjectCommand({
+          Bucket: s3.bucket,
+          Key: key,
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- AWS SDK response type
+        const response = (await s3.send(command)) as any;
+        if (!response.Body) return null;
+        return {
+          body: response.Body.transformToWebStream() as ReadableStream,
+          contentType: response.ContentType ?? undefined,
+        };
+      } catch (err: unknown) {
+        // NoSuchKey → return null instead of throwing
+        if (
+          err instanceof Error &&
+          (err.name === "NoSuchKey" || err.name === "NotFound")
+        ) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async delete(key) {
+      const s3 = await getClient();
+      const command = new s3.DeleteObjectCommand({
+        Bucket: s3.bucket,
+        Key: key,
+      });
+      await s3.send(command);
+    },
+  };
+}
+
+/**
+ * Creates the appropriate storage driver based on environment configuration.
+ *
+ * Returns `null` if no storage is configured (no R2 binding and no S3 config).
+ *
+ * @param env - The Cloudflare Workers environment bindings
+ * @returns A StorageDriver instance or null
+ *
+ * @example
+ * ```ts
+ * const storage = createStorageDriver(c.env);
+ * if (storage) {
+ *   await storage.put("media/file.jpg", stream, { contentType: "image/jpeg" });
+ * }
+ * ```
+ */
+export function createStorageDriver(env: Bindings): StorageDriver | null {
+  const driver = env.STORAGE_DRIVER || "r2";
+
+  if (driver === "s3") {
+    if (
+      !env.S3_ENDPOINT ||
+      !env.S3_BUCKET ||
+      !env.S3_ACCESS_KEY_ID ||
+      !env.S3_SECRET_ACCESS_KEY
+    ) {
+      return null;
+    }
+    return createS3Driver({
+      endpoint: env.S3_ENDPOINT,
+      bucket: env.S3_BUCKET,
+      accessKeyId: env.S3_ACCESS_KEY_ID,
+      secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+      region: env.S3_REGION || "auto",
+    });
+  }
+
+  // Default: R2
+  if (!env.R2) return null;
+  return createR2Driver(env.R2);
+}

package/src/routes/api/__tests__/posts.test.ts

@@ -50,7 +50,7 @@ describe("Posts API Routes", () => {
         originalName: "test.jpg",
         mimeType: "image/jpeg",
         size: 1024,
-        r2Key: "media/2025/01/test.jpg",
+        storageKey: "media/2025/01/test.jpg",
         width: 800,
         height: 600,
       });
@@ -145,7 +145,7 @@ describe("Posts API Routes", () => {
         originalName: "test.jpg",
         mimeType: "image/jpeg",
         size: 1024,
-        r2Key: "media/2025/01/test.jpg",
+        storageKey: "media/2025/01/test.jpg",
       });
 
       await services.media.attachToPost(post.id, [media.id]);
@@ -223,14 +223,14 @@ describe("Posts API Routes", () => {
         originalName: "a.jpg",
         mimeType: "image/jpeg",
         size: 1024,
-        r2Key: "media/2025/01/a.jpg",
+        storageKey: "media/2025/01/a.jpg",
       });
       const m2 = await services.media.create({
         filename: "b.jpg",
         originalName: "b.jpg",
         mimeType: "image/jpeg",
         size: 2048,
-        r2Key: "media/2025/01/b.jpg",
+        storageKey: "media/2025/01/b.jpg",
       });
 
       const res = await app.request("/api/posts", {
@@ -282,7 +282,7 @@ describe("Posts API Routes", () => {
         originalName: "a.jpg",
         mimeType: "image/jpeg",
         size: 1024,
-        r2Key: "media/2025/01/a.jpg",
+        storageKey: "media/2025/01/a.jpg",
       });
 
       const res = await app.request("/api/posts", {
@@ -404,7 +404,7 @@ describe("Posts API Routes", () => {
         originalName: "a.jpg",
         mimeType: "image/jpeg",
         size: 1024,
-        r2Key: "media/2025/01/a.jpg",
+        storageKey: "media/2025/01/a.jpg",
       });
 
       await services.media.attachToPost(post.id, [m1.id]);
@@ -414,7 +414,7 @@ describe("Posts API Routes", () => {
         originalName: "b.jpg",
         mimeType: "image/jpeg",
         size: 2048,
-        r2Key: "media/2025/01/b.jpg",
+        storageKey: "media/2025/01/b.jpg",
       });
 
       const res = await app.request(`/api/posts/${sqid.encode(post.id)}`, {
@@ -443,7 +443,7 @@ describe("Posts API Routes", () => {
         originalName: "a.jpg",
         mimeType: "image/jpeg",
         size: 1024,
-        r2Key: "media/2025/01/a.jpg",
+        storageKey: "media/2025/01/a.jpg",
       });
 
       await services.media.attachToPost(post.id, [m1.id]);