@jant/core 0.3.7 → 0.3.9

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/lib/theme-components.ts

@@ -0,0 +1,76 @@
+/**
+ * Theme Component Resolution
+ *
+ * Resolves theme-overridable components, falling back to defaults.
+ */
+
+import type { FC } from "hono/jsx";
+import type {
+  PostType,
+  ThemeComponents,
+  TimelineCardProps,
+  ThreadPreviewProps,
+  TimelineFeedProps,
+} from "../types.js";
+
+const THEME_KEY_MAP: Record<PostType, keyof ThemeComponents> = {
+  note: "NoteCard",
+  article: "ArticleCard",
+  link: "LinkCard",
+  quote: "QuoteCard",
+  image: "ImageCard",
+  page: "NoteCard",
+};
+
+/**
+ * Resolves the card component for a given post type.
+ *
+ * Checks theme overrides first, then falls back to the provided default card component.
+ *
+ * @param type - The post type to resolve a card for
+ * @param defaults - Map of post type to default card component
+ * @param themeComponents - Optional theme component overrides
+ * @returns The resolved card component
+ *
+ * @example
+ * ```ts
+ * const Card = resolveCardComponent("article", DEFAULT_CARD_MAP, c.var.config.theme?.components);
+ * ```
+ */
+export function resolveCardComponent(
+  type: PostType,
+  defaults: Record<PostType, FC<TimelineCardProps>>,
+  themeComponents?: ThemeComponents,
+): FC<TimelineCardProps> {
+  const key = THEME_KEY_MAP[type];
+  const override = themeComponents?.[key] as FC<TimelineCardProps> | undefined;
+  return override ?? defaults[type];
+}
+
+/**
+ * Resolves the ThreadPreview component.
+ *
+ * @param defaultComponent - The default ThreadPreview component
+ * @param themeComponents - Optional theme component overrides
+ * @returns The resolved ThreadPreview component
+ */
+export function resolveThreadPreview(
+  defaultComponent: FC<ThreadPreviewProps>,
+  themeComponents?: ThemeComponents,
+): FC<ThreadPreviewProps> {
+  return themeComponents?.ThreadPreview ?? defaultComponent;
+}
+
+/**
+ * Resolves the TimelineFeed component.
+ *
+ * @param defaultComponent - The default TimelineFeed component
+ * @param themeComponents - Optional theme component overrides
+ * @returns The resolved TimelineFeed component
+ */
+export function resolveTimelineFeed(
+  defaultComponent: FC<TimelineFeedProps>,
+  themeComponents?: ThemeComponents,
+): FC<TimelineFeedProps> {
+  return themeComponents?.TimelineFeed ?? defaultComponent;
+}

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: "uploads/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: "uploads/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: "uploads/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: "uploads/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: "uploads/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: "uploads/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: "uploads/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: "uploads/a.jpg",
+        storageKey: "media/2025/01/a.jpg",
       });
 
       await services.media.attachToPost(post.id, [m1.id]);

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

@@ -0,0 +1,242 @@
+/**
+ * Timeline API Tests
+ *
+ * Tests the timeline data assembly logic via the service layer.
+ * The actual route handler renders JSX components which require the Lingui SWC
+ * plugin (not available in vitest). We test the underlying service operations
+ * that power the timeline API instead.
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { createTestDatabase } from "../../../__tests__/helpers/db.js";
+import { createPostService } from "../../../services/post.js";
+import { createMediaService } from "../../../services/media.js";
+import { buildMediaMap } from "../../../lib/media-helpers.js";
+import type { Database } from "../../../db/index.js";
+import type { PostWithMedia, TimelineItemData } from "../../../types.js";
+
+describe("Timeline data assembly", () => {
+  let db: Database;
+  let postService: ReturnType<typeof createPostService>;
+  let mediaService: ReturnType<typeof createMediaService>;
+
+  beforeEach(() => {
+    const testDb = createTestDatabase();
+    db = testDb.db as unknown as Database;
+    postService = createPostService(db);
+    mediaService = createMediaService(db);
+  });
+
+  it("assembles timeline items with media attachments", async () => {
+    const post = await postService.create({
+      type: "note",
+      content: "Hello",
+      visibility: "featured",
+    });
+
+    const posts = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: 21,
+    });
+
+    expect(posts).toHaveLength(1);
+    expect(posts[0]?.id).toBe(post.id);
+
+    // Build media map
+    const postIds = posts.map((p) => p.id);
+    const rawMediaMap = await mediaService.getByPostIds(postIds);
+    const mediaMap = buildMediaMap(rawMediaMap);
+
+    // Assemble items
+    const items: TimelineItemData[] = posts.map((p) => ({
+      post: { ...p, mediaAttachments: mediaMap.get(p.id) ?? [] },
+    }));
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.post.mediaAttachments).toEqual([]);
+  });
+
+  it("identifies thread roots and builds thread previews", async () => {
+    const root = await postService.create({
+      type: "note",
+      content: "Thread root",
+      visibility: "featured",
+    });
+    await postService.create({
+      type: "note",
+      content: "Reply 1",
+      replyToId: root.id,
+    });
+    await postService.create({
+      type: "note",
+      content: "Reply 2",
+      replyToId: root.id,
+    });
+
+    const posts = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: 21,
+    });
+
+    expect(posts).toHaveLength(1);
+
+    const postIds = posts.map((p) => p.id);
+    const replyCounts = await postService.getReplyCounts(postIds);
+    const threadRootIds = postIds.filter(
+      (id) => (replyCounts.get(id) ?? 0) > 0,
+    );
+
+    expect(threadRootIds).toEqual([root.id]);
+    expect(replyCounts.get(root.id)).toBe(2);
+
+    const threadPreviews = await postService.getThreadPreviews(threadRootIds);
+    const replies = threadPreviews.get(root.id);
+    expect(replies).toHaveLength(2);
+    expect(replies?.[0]?.content).toBe("Reply 1");
+
+    // Assemble items
+    const rawMediaMap = await mediaService.getByPostIds(postIds);
+    const mediaMap = buildMediaMap(rawMediaMap);
+
+    const items: TimelineItemData[] = posts.map((post) => {
+      const postWithMedia: PostWithMedia = {
+        ...post,
+        mediaAttachments: mediaMap.get(post.id) ?? [],
+      };
+
+      const replyCount = replyCounts.get(post.id) ?? 0;
+      const previewReplies = threadPreviews.get(post.id);
+
+      if (replyCount > 0 && previewReplies) {
+        return {
+          post: postWithMedia,
+          threadPreview: {
+            replies: previewReplies.map((r) => ({
+              ...r,
+              mediaAttachments: [],
+            })),
+            totalReplyCount: replyCount,
+          },
+        };
+      }
+
+      return { post: postWithMedia };
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.threadPreview).toBeDefined();
+    expect(items[0]?.threadPreview?.replies).toHaveLength(2);
+    expect(items[0]?.threadPreview?.totalReplyCount).toBe(2);
+  });
+
+  it("excludes pages from timeline", async () => {
+    await postService.create({
+      type: "note",
+      content: "A note",
+      visibility: "quiet",
+    });
+    await postService.create({
+      type: "page",
+      content: "A page",
+      visibility: "quiet",
+    });
+
+    const posts = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: 21,
+    });
+
+    expect(posts).toHaveLength(1);
+    expect(posts[0]?.type).toBe("note");
+  });
+
+  it("excludes replies from top-level list", async () => {
+    const root = await postService.create({
+      type: "note",
+      content: "Root",
+      visibility: "quiet",
+    });
+    await postService.create({
+      type: "note",
+      content: "Reply",
+      replyToId: root.id,
+    });
+
+    const posts = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: 21,
+    });
+
+    expect(posts).toHaveLength(1);
+    expect(posts[0]?.content).toBe("Root");
+  });
+
+  it("supports cursor pagination for load more", async () => {
+    const posts = [];
+    for (let i = 0; i < 5; i++) {
+      posts.push(
+        await postService.create({
+          type: "note",
+          content: `Post ${i}`,
+          visibility: "quiet",
+          publishedAt: 1000 + i,
+        }),
+      );
+    }
+
+    // First page
+    const page1 = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: 3,
+    });
+    expect(page1).toHaveLength(3);
+
+    // Second page using cursor
+    const lastPost = page1[page1.length - 1];
+    expect(lastPost).toBeDefined();
+    const page2 = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: 3,
+      cursor: lastPost?.id,
+    });
+    expect(page2).toHaveLength(2);
+    expect(page2.every((p) => p.id < (lastPost?.id ?? 0))).toBe(true);
+  });
+
+  it("correctly determines hasMore flag", async () => {
+    for (let i = 0; i < 3; i++) {
+      await postService.create({
+        type: "note",
+        content: `Post ${i}`,
+        visibility: "quiet",
+      });
+    }
+
+    // Request limit + 1 to check for more
+    const pageSize = 2;
+    const posts = await postService.list({
+      visibility: ["featured", "quiet"],
+      excludeReplies: true,
+      excludeTypes: ["page"],
+      limit: pageSize + 1,
+    });
+
+    const hasMore = posts.length > pageSize;
+    expect(hasMore).toBe(true);
+
+    const displayPosts = posts.slice(0, pageSize);
+    expect(displayPosts).toHaveLength(2);
+  });
+});