alepha 0.14.1 → 0.14.3

package/src/api/files/controllers/FileController.spec.ts

@@ -0,0 +1,558 @@
+import { Alepha } from "alepha";
+import { $bucket } from "alepha/bucket";
+import { DateTimeProvider } from "alepha/datetime";
+import { FileSystemProvider } from "alepha/file";
+import { describe, expect, it } from "vitest";
+import { FileController, FileService } from "../index.ts";
+
+describe("FileController", () => {
+  class App {
+    images = $bucket({});
+    documents = $bucket({ name: "documents" });
+  }
+
+  let createFile: (
+    textOrOpts: string | { text: string; name?: string; type?: string },
+    opts?: { name?: string; type?: string },
+  ) => any;
+
+  const setup = async () => {
+    const alepha = Alepha.create();
+    const app = alepha.inject(App);
+    const ctrl = alepha.inject(FileController);
+    const service = alepha.inject(FileService);
+    const dtp = alepha.inject(DateTimeProvider);
+    const fs = alepha.inject(FileSystemProvider);
+    await alepha.start();
+    createFile = (
+      textOrOpts: string | { text: string; name?: string; type?: string },
+      opts?: { name?: string; type?: string },
+    ) => {
+      if (typeof textOrOpts === "string") {
+        return fs.createFile({ text: textOrOpts, ...(opts || {}) });
+      }
+      return fs.createFile(textOrOpts);
+    };
+    return { alepha, app, ctrl, service, dtp, fs };
+  };
+
+  describe("findFiles", () => {
+    it("should return files from specific bucket", async () => {
+      const { app, ctrl } = await setup();
+      await app.images.upload(createFile("test"));
+      const files = await ctrl.findFiles({
+        query: { bucket: app.images.name },
+      });
+      expect(files.content.length).toEqual(1);
+    });
+
+    it("should return empty list when no files exist", async () => {
+      const { ctrl } = await setup();
+      const files = await ctrl.findFiles();
+      expect(files.content).toEqual([]);
+      expect(files.page.totalElements).toBe(0);
+    });
+
+    it("should return files from all buckets when no bucket filter", async () => {
+      const { app, ctrl } = await setup();
+      await app.images.upload(createFile("image.png"));
+      await app.documents.upload(createFile("doc.pdf"));
+
+      const files = await ctrl.findFiles({ query: {} });
+      expect(files.content.length).toEqual(2);
+    });
+
+    it("should filter files by bucket", async () => {
+      const { app, ctrl } = await setup();
+      await app.images.upload(createFile("image.png"));
+      await app.documents.upload(createFile("doc.pdf"));
+
+      const imagesFiles = await ctrl.findFiles({
+        query: { bucket: app.images.name },
+      });
+      expect(imagesFiles.content.length).toEqual(1);
+      expect(imagesFiles.content[0].bucket).toBe(app.images.name);
+
+      const docsFiles = await ctrl.findFiles({
+        query: { bucket: app.documents.name },
+      });
+      expect(docsFiles.content.length).toEqual(1);
+      expect(docsFiles.content[0].bucket).toBe(app.documents.name);
+    });
+
+    it("should filter files by tags", async () => {
+      const { service, ctrl } = await setup();
+      await service.uploadFile(createFile("file1.txt"), {
+        tags: ["important", "work"],
+      });
+      await service.uploadFile(createFile("file2.txt"), { tags: ["personal"] });
+      await service.uploadFile(createFile("file3.txt"), {
+        tags: ["important", "personal"],
+      });
+
+      const importantFiles = await ctrl.findFiles.run({
+        query: { tags: ["important"] },
+      });
+      expect(importantFiles.content.length).toEqual(2);
+    });
+
+    it("should support pagination", async () => {
+      const { app, ctrl } = await setup();
+      await app.images.upload(createFile("file1.txt"));
+      await app.images.upload(createFile("file2.txt"));
+      await app.images.upload(createFile("file3.txt"));
+
+      const page1 = await ctrl.findFiles({
+        query: { bucket: app.images.name, size: 2, page: 0 },
+      });
+
+      expect(page1.content.length).toEqual(2);
+      expect(page1.page.totalElements).toBe(3);
+
+      const page2 = await ctrl.findFiles({
+        query: { bucket: app.images.name, size: 2, page: 1 },
+      });
+      expect(page2.content.length).toEqual(1);
+      expect(page2.page.totalElements).toBe(3);
+    });
+
+    it("should return files sorted by creation date descending by default", async () => {
+      const { app, ctrl } = await setup();
+      const file1 = await app.images.upload(createFile("first.txt"));
+      const file2 = await app.images.upload(createFile("second.txt"));
+      const file3 = await app.images.upload(createFile("third.txt"));
+
+      const files = await ctrl.findFiles({
+        query: { bucket: app.images.name },
+      });
+
+      expect(files.content[0].blobId).toBe(file3);
+      expect(files.content[1].blobId).toBe(file2);
+      expect(files.content[2].blobId).toBe(file1);
+    });
+  });
+
+  describe("uploadFile", () => {
+    it("should upload file to default bucket", async () => {
+      const { ctrl } = await setup();
+      const file = createFile("Hello, World!", {
+        name: "test.txt",
+        type: "text/plain",
+      });
+
+      const result = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      expect(result.name).toBe("test.txt");
+      expect(result.mimeType).toBe("text/plain");
+      expect(result.size).toBeGreaterThan(0);
+      expect(result.blobId).toBeDefined();
+    });
+
+    it("should calculate and store file checksum", async () => {
+      const { ctrl } = await setup();
+      const file = createFile("Hello, World!", {
+        name: "test.txt",
+        type: "text/plain",
+      });
+
+      const result = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      expect(result.checksum).toBeDefined();
+      expect(result.checksum).toMatch(/^[a-f0-9]{64}$/); // SHA-256 hex format
+    });
+
+    it("should upload file to specific bucket", async () => {
+      const { app, ctrl } = await setup();
+      const file = createFile("Document content", {
+        name: "doc.pdf",
+        type: "application/pdf",
+      });
+
+      const result = await ctrl.uploadFile({
+        body: { file },
+        query: { bucket: app.documents.name },
+      });
+
+      expect(result.bucket).toBe(app.documents.name);
+      expect(result.name).toBe("doc.pdf");
+    });
+
+    it("should upload file with expiration date", async () => {
+      const { ctrl, dtp } = await setup();
+      const file = createFile("Temporary file", { name: "temp.txt" });
+      const expirationDate = dtp.now().add(1, "hour").toISOString();
+
+      const result = await ctrl.uploadFile({
+        body: { file },
+        query: { expirationDate },
+      });
+
+      expect(result.expirationDate).toEqual(expirationDate);
+    });
+
+    it("should capture user information when provided", async () => {
+      const { ctrl, service } = await setup();
+      const file = createFile("User file", { name: "user.txt" });
+
+      const result = await service.uploadFile(file, {
+        user: {
+          id: "123e4567-e89b-12d3-a456-426614174000",
+          realm: "test-realm",
+          name: "Test User",
+        },
+      });
+
+      expect(result.creator).toBe("123e4567-e89b-12d3-a456-426614174000");
+      expect(result.creatorRealm).toBe("test-realm");
+      expect(result.creatorName).toBe("Test User");
+    });
+  });
+
+  describe("streamFile", () => {
+    it("should stream uploaded file", async () => {
+      const { ctrl } = await setup();
+      const originalContent = "Hello, World!";
+      const file = createFile(originalContent, {
+        name: "test.txt",
+        type: "text/plain",
+      });
+
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      const streamed = await ctrl.streamFile({ params: { id: uploaded.id } });
+
+      expect(streamed.name).toBe("test.txt");
+      expect(streamed.type).toBe("text/plain");
+      expect(await streamed.text()).toBe(originalContent);
+    });
+
+    it("should throw NotFoundError for non-existent file", async () => {
+      const { ctrl } = await setup();
+
+      await expect(
+        ctrl.streamFile({
+          params: { id: "00000000-0000-0000-0000-000000000000" },
+        }),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("deleteFile", () => {
+    it("should delete existing file", async () => {
+      const { ctrl } = await setup();
+      const file = createFile("To be deleted", { name: "delete-me.txt" });
+
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      const result = await ctrl.deleteFile({
+        params: { id: uploaded.id },
+      });
+
+      expect(result.ok).toBe(true);
+      expect(result.id).toBe(uploaded.id);
+
+      // Verify file is actually deleted
+      await expect(
+        ctrl.streamFile({ params: { id: uploaded.id } }),
+      ).rejects.toThrow();
+    });
+
+    it("should throw NotFoundError when deleting non-existent file", async () => {
+      const { ctrl } = await setup();
+
+      await expect(
+        ctrl.deleteFile({
+          params: { id: "00000000-0000-0000-0000-000000000000" },
+        }),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("updateFile", () => {
+    it("should update file name", async () => {
+      const { ctrl } = await setup();
+      const file = createFile("test content", { name: "original.txt" });
+
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      const updated = await ctrl.updateFile({
+        params: { id: uploaded.id },
+        body: { name: "renamed.txt" },
+      });
+
+      expect(updated.name).toBe("renamed.txt");
+      expect(updated.id).toBe(uploaded.id);
+    });
+
+    it("should update file tags", async () => {
+      const { ctrl } = await setup();
+      const file = createFile("test content", { name: "test.txt" });
+
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      const updated = await ctrl.updateFile({
+        params: { id: uploaded.id },
+        body: { tags: ["important", "work"] },
+      });
+
+      expect(updated.tags).toEqual(["important", "work"]);
+    });
+
+    it("should update file expiration date", async () => {
+      const { ctrl, dtp } = await setup();
+      const file = createFile("test content", { name: "test.txt" });
+
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      const newExpiration = dtp.now().add(2, "days").toISOString();
+
+      const updated = await ctrl.updateFile({
+        params: { id: uploaded.id },
+        body: { expirationDate: newExpiration },
+      });
+
+      expect(updated.expirationDate).toBe(newExpiration);
+    });
+
+    it("should update multiple fields at once", async () => {
+      const { ctrl, dtp } = await setup();
+      const file = createFile("test content", { name: "original.txt" });
+
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      const newExpiration = dtp.now().add(3, "days").toISOString();
+
+      const updated = await ctrl.updateFile({
+        params: { id: uploaded.id },
+        body: {
+          name: "updated.txt",
+          tags: ["tag1", "tag2"],
+          expirationDate: newExpiration,
+        },
+      });
+
+      expect(updated.name).toBe("updated.txt");
+      expect(updated.tags).toEqual(["tag1", "tag2"]);
+      expect(updated.expirationDate).toBe(newExpiration);
+    });
+
+    it("should throw error when updating non-existent file", async () => {
+      const { ctrl } = await setup();
+
+      await expect(
+        ctrl.updateFile({
+          params: { id: "00000000-0000-0000-0000-000000000000" },
+          body: { name: "new-name.txt" },
+        }),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("enhanced search filtering", () => {
+    it("should filter by file name (partial match)", async () => {
+      const { service, ctrl } = await setup();
+      await service.uploadFile(
+        createFile("content", { name: "report-2024.pdf" }),
+      );
+      await service.uploadFile(
+        createFile("content", { name: "invoice-march.pdf" }),
+      );
+      await service.uploadFile(
+        createFile("content", { name: "report-2025.pdf" }),
+      );
+
+      const results = await ctrl.findFiles({ query: { name: "report" } });
+      expect(results.content.length).toBe(2);
+      expect(results.content.every((f) => f.name.includes("report"))).toBe(
+        true,
+      );
+    });
+
+    it("should filter by MIME type", async () => {
+      const { service, ctrl } = await setup();
+      await service.uploadFile(
+        createFile("content", { name: "file1.pdf", type: "application/pdf" }),
+      );
+      await service.uploadFile(
+        createFile("content", { name: "file2.txt", type: "text/plain" }),
+      );
+      await service.uploadFile(
+        createFile("content", { name: "file3.pdf", type: "application/pdf" }),
+      );
+
+      const results = await ctrl.findFiles({
+        query: { mimeType: "application/pdf" },
+      });
+      expect(results.content.length).toBe(2);
+      expect(
+        results.content.every((f) => f.mimeType === "application/pdf"),
+      ).toBe(true);
+    });
+
+    it("should filter by creator", async () => {
+      const { service, ctrl } = await setup();
+      const user1Id = "123e4567-e89b-12d3-a456-426614174000";
+      const user2Id = "223e4567-e89b-12d3-a456-426614174000";
+
+      await service.uploadFile(createFile("content", { name: "file1.txt" }), {
+        user: { id: user1Id, realm: "test", name: "User 1" },
+      });
+      await service.uploadFile(createFile("content", { name: "file2.txt" }), {
+        user: { id: user2Id, realm: "test", name: "User 2" },
+      });
+      await service.uploadFile(createFile("content", { name: "file3.txt" }), {
+        user: { id: user1Id, realm: "test", name: "User 1" },
+      });
+
+      const results = await ctrl.findFiles({ query: { creator: user1Id } });
+      expect(results.content.length).toBe(2);
+      expect(results.content.every((f) => f.creator === user1Id)).toBe(true);
+    });
+
+    it("should filter by date range", async () => {
+      const { service, ctrl, dtp } = await setup();
+
+      const startTime = dtp.nowISOString();
+
+      // ensure time difference
+      await new Promise((resolve) => setTimeout(resolve, 1));
+
+      await service.uploadFile(createFile("content", { name: "file1.txt" }));
+      await service.uploadFile(createFile("content", { name: "file2.txt" }));
+      await service.uploadFile(createFile("content", { name: "file3.txt" }));
+
+      // Filter for files created after start time (should get all 3)
+      const results = await ctrl.findFiles({
+        query: { createdAfter: startTime },
+      });
+
+      expect(results.content.length).toBe(3);
+
+      // Filter for files created before a future date (should get all 3)
+      const futureTime = dtp.now().add(1, "hour").toISOString();
+      const results2 = await ctrl.findFiles({
+        query: { createdBefore: futureTime },
+      });
+
+      expect(results2.content.length).toBe(3);
+    });
+
+    it("should combine multiple filters", async () => {
+      const { service, ctrl } = await setup();
+      const userId = "123e4567-e89b-12d3-a456-426614174000";
+
+      await service.uploadFile(
+        createFile("content", { name: "report.pdf", type: "application/pdf" }),
+        {
+          user: { id: userId, realm: "test", name: "User" },
+          tags: ["important"],
+        },
+      );
+      await service.uploadFile(
+        createFile("content", { name: "invoice.pdf", type: "application/pdf" }),
+        { tags: ["important"] },
+      );
+      await service.uploadFile(
+        createFile("content", { name: "report.txt", type: "text/plain" }),
+        { user: { id: userId, realm: "test", name: "User" } },
+      );
+
+      const results = await ctrl.findFiles({
+        query: {
+          name: "report",
+          mimeType: "application/pdf",
+          creator: userId,
+          tags: ["important"],
+        },
+      });
+
+      expect(results.content.length).toBe(1);
+      expect(results.content[0].name).toBe("report.pdf");
+    });
+  });
+
+  describe("integration scenarios", () => {
+    it("should handle complete file lifecycle", async () => {
+      const { ctrl } = await setup();
+
+      // Upload
+      const file = createFile("Lifecycle test", { name: "lifecycle.txt" });
+      const uploaded = await ctrl.uploadFile({
+        body: { file },
+        query: {},
+      });
+
+      // List
+      const listResult = await ctrl.findFiles({ query: {} });
+      expect(listResult.content).toContainEqual(
+        expect.objectContaining({ id: uploaded.id }),
+      );
+
+      // Stream
+      const streamed = await ctrl.streamFile({
+        params: { id: uploaded.id },
+      });
+      expect(await streamed.text()).toBe("Lifecycle test");
+
+      // Delete
+      await ctrl.deleteFile({ params: { id: uploaded.id } });
+
+      // Verify deletion
+      const finalList = await ctrl.findFiles({ query: {} });
+      expect(
+        finalList.content.find((f) => f.id === uploaded.id),
+      ).toBeUndefined();
+    });
+
+    it("should handle multiple files with different properties", async () => {
+      const { ctrl, dtp, service } = await setup();
+
+      // Upload various files
+      await ctrl.uploadFile({
+        body: { file: createFile("File 1", { name: "file1.txt" }) },
+        query: {},
+      });
+
+      await service.uploadFile(createFile("File 2", { name: "file2.txt" }), {
+        tags: ["important"],
+      });
+
+      await ctrl.uploadFile({
+        body: { file: createFile("File 3", { name: "file3.txt" }) },
+        query: { expirationDate: dtp.now().add(1, "hour").toISOString() },
+      });
+
+      const allFiles = await ctrl.findFiles({ query: {} });
+      expect(allFiles.content.length).toBe(3);
+
+      const taggedFiles = await ctrl.findFiles({
+        query: { tags: ["important"] },
+      });
+      expect(taggedFiles.content.length).toBe(1);
+    });
+  });
+});

package/src/api/files/controllers/FileController.ts

@@ -1,5 +1,4 @@
 import { $inject, t } from "alepha";
-import { pg } from "alepha/orm";
 import { $action, okSchema } from "alepha/server";
 import { fileQuerySchema } from "../schemas/fileQuerySchema.ts";
 import { fileResourceSchema } from "../schemas/fileResourceSchema.ts";
@@ -20,11 +19,11 @@ export class FileController {
    */
   public readonly findFiles = $action({
     path: this.url,
-    group: this.group,
+    group: `admin:${this.group}`,
     description: "List files with filtering and pagination",
     schema: {
       query: fileQuerySchema,
-      response: pg.page(fileResourceSchema),
+      response: t.page(fileResourceSchema),
     },
     handler: ({ query }) => this.fileService.findFiles(query),
   });
@@ -36,7 +35,7 @@ export class FileController {
   public readonly deleteFile = $action({
     method: "DELETE",
     path: `${this.url}/:id`,
-    group: this.group,
+    group: `admin:${this.group}`,
     description: "Delete a file",
     schema: {
       params: t.object({
@@ -80,7 +79,7 @@ export class FileController {
   public readonly updateFile = $action({
     method: "PATCH",
     path: `${this.url}/:id`,
-    group: this.group,
+    group: `admin:${this.group}`,
     description: "Update file metadata",
     schema: {
       params: t.object({

package/src/api/files/entities/files.ts

@@ -1,13 +1,13 @@
 import { type Static, t } from "alepha";
-import { $entity, pg } from "alepha/orm";
+import { $entity, db } from "alepha/orm";
 
 export const files = $entity({
   name: "files",
   schema: t.object({
-    id: pg.primaryKey(t.uuid()),
-    version: pg.version(),
-    createdAt: pg.createdAt(),
-    updatedAt: pg.updatedAt(),
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
     blobId: t.text(),
     creator: t.optional(t.uuid()),
     creatorRealm: t.optional(t.string()),

package/src/api/files/index.browser.ts

@@ -2,8 +2,8 @@ import { $module } from "alepha";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export type * from "./controllers/AdminFileStatsController.ts";
 export type * from "./controllers/FileController.ts";
-export type * from "./controllers/StorageStatsController.ts";
 export * from "./entities/files.ts";
 export * from "./schemas/fileQuerySchema.ts";
 export * from "./schemas/fileResourceSchema.ts";

package/src/api/files/index.ts

@@ -4,15 +4,15 @@ import type { DurationLike } from "alepha/datetime";
 import type { UserAccountToken } from "alepha/security";
 import { AlephaServerCache } from "alepha/server/cache";
 import { AlephaServerMultipart } from "alepha/server/multipart";
+import { AdminFileStatsController } from "./controllers/AdminFileStatsController.ts";
 import { FileController } from "./controllers/FileController.ts";
-import { StorageStatsController } from "./controllers/StorageStatsController.ts";
 import { FileJobs } from "./jobs/FileJobs.ts";
 import { FileService } from "./services/FileService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export * from "./controllers/AdminFileStatsController.ts";
 export * from "./controllers/FileController.ts";
-export * from "./controllers/StorageStatsController.ts";
 export * from "./entities/files.ts";
 export * from "./jobs/FileJobs.ts";
 export * from "./schemas/storageStatsSchema.ts";
@@ -58,14 +58,14 @@ declare module "alepha/bucket" {
  */
 export const AlephaApiFiles = $module({
   name: "alepha.api.files",
-  services: [FileController, StorageStatsController, FileJobs, FileService],
+  services: [FileController, AdminFileStatsController, FileJobs, FileService],
   register: (alepha) => {
     alepha
       .with(AlephaBucket)
       .with(AlephaServerCache)
       .with(AlephaServerMultipart)
       .with(FileController)
-      .with(StorageStatsController)
+      .with(AdminFileStatsController)
       .with(FileJobs);
   },
 });