@uploadista/data-store-filesystem 0.0.13-beta.4 → 0.0.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uploadista/data-store-filesystem",
   "type": "module",
-  "version": "0.0.13-beta.4",
+  "version": "0.0.13",
   "description": "File system data store for Uploadista",
   "license": "MIT",
   "author": "Uploadista",
@@ -14,20 +14,26 @@
     }
   },
   "dependencies": {
-    "effect": "3.19.2",
-    "@uploadista/core": "0.0.13-beta.4",
-    "@uploadista/observability": "0.0.13-beta.4"
+    "effect": "3.19.3",
+    "@uploadista/core": "0.0.13",
+    "@uploadista/observability": "0.0.13"
   },
   "devDependencies": {
-    "@types/node": "24.10.0",
-    "tsdown": "0.16.0",
-    "@uploadista/typescript-config": "0.0.13-beta.4"
+    "@effect/vitest": "0.27.0",
+    "@types/node": "24.10.1",
+    "tsdown": "0.16.3",
+    "vitest": "4.0.8",
+    "@uploadista/typescript-config": "0.0.13",
+    "@uploadista/kv-store-memory": "0.0.13"
   },
   "scripts": {
-    "dev": "tsc -b",
     "build": "tsdown",
+    "check": "biome check --write ./src",
+    "dev": "tsc -b",
     "format": "biome format --write ./src",
     "lint": "biome lint --write ./src",
-    "check": "biome check --write ./src"
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest --watch"
   }
 }

package/tests/filesystem-store.test.ts

@@ -0,0 +1,668 @@
+import type { DataStore, UploadFile } from "@uploadista/core/types";
+import { UploadFileKVStore } from "@uploadista/core/types";
+import { Effect } from "effect";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { fileStore } from "../src/file-store";
+import {
+  compareArrays,
+  createStandardTestFiles,
+  createTestDataStream,
+  generateData,
+  TEST_FILE_SIZES,
+} from "./utils/test-data-generator";
+import {
+  assertFileUploaded,
+  cleanupTestDirectory,
+  createTestDirectory,
+  createTestFilesystemStoreConfig,
+  createTestUploadFile,
+  getFileSize,
+  listFiles,
+  runTestWithTimeout,
+  TestLayersWithMemoryKV,
+} from "./utils/test-setup";
+
+describe("FilesystemStore - Basic Upload Tests", () => {
+  let filesystemStore: DataStore<UploadFile>;
+  let testDirectory: string;
+
+  beforeEach(async () => {
+    await runTestWithTimeout(
+      Effect.gen(function* () {
+        // Create a temporary test directory
+        testDirectory = yield* createTestDirectory();
+
+        // Create filesystem store with test configuration
+        const config = createTestFilesystemStoreConfig(testDirectory);
+
+        filesystemStore = (yield* fileStore(config)) as DataStore<UploadFile>;
+      }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+    );
+  });
+
+  afterEach(async () => {
+    await runTestWithTimeout(
+      Effect.gen(function* () {
+        // Clear all entries from KV store
+        const kvStore = yield* UploadFileKVStore;
+        if (!kvStore.list) {
+          return;
+        }
+        const keys = yield* kvStore.list();
+        if (keys.length > 0) {
+          yield* Effect.all(
+            keys.map((key) => kvStore.delete(key)),
+            { concurrency: "unbounded" },
+          );
+        }
+
+        // Clean up test directory
+        yield* cleanupTestDirectory(testDirectory);
+      }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+    );
+  });
+
+  describe("Store Creation", () => {
+    it("should create filesystem store successfully", async () => {
+      await runTestWithTimeout(
+        Effect.sync(() => {
+          expect(filesystemStore).toBeDefined();
+          expect(filesystemStore.bucket).toBeDefined();
+          expect(filesystemStore.create).toBeDefined();
+          expect(filesystemStore.write).toBeDefined();
+          expect(filesystemStore.read).toBeDefined();
+          expect(filesystemStore.remove).toBeDefined();
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should have correct capabilities", async () => {
+      await runTestWithTimeout(
+        Effect.sync(() => {
+          const capabilities = filesystemStore.getCapabilities();
+
+          expect(capabilities.supportsParallelUploads).toBe(false);
+          expect(capabilities.supportsConcatenation).toBe(false);
+          expect(capabilities.supportsDeferredLength).toBe(false);
+          expect(capabilities.supportsResumableUploads).toBe(true);
+          expect(capabilities.requiresOrderedChunks).toBe(true);
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should validate upload strategies correctly", async () => {
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          const singleStrategy = yield* filesystemStore.validateUploadStrategy(
+            "single",
+          );
+          expect(singleStrategy).toBe(true);
+
+          const parallelStrategy = yield* filesystemStore.validateUploadStrategy(
+            "parallel",
+          );
+          expect(parallelStrategy).toBe(false);
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+
+  describe("Small File Uploads", () => {
+    it("should upload tiny files successfully", async () => {
+      const testFile = createTestUploadFile(
+        "tiny-test",
+        TEST_FILE_SIZES.TINY.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          // Create upload
+          const createdFile = yield* filesystemStore.create(testFile);
+          expect(createdFile.id).toBe(testFile.id);
+          expect(createdFile.size).toBe(testFile.size);
+
+          // Write data
+          const finalOffset = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(finalOffset).toBe(testFile.size);
+
+          // Verify file was uploaded
+          yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            testFile.size ?? 0,
+          );
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should upload small files (1MB) successfully", async () => {
+      const testFile = createTestUploadFile(
+        "small-test",
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0, {
+        type: "random",
+        seed: 12345,
+      });
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          const finalOffset = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(finalOffset).toBe(testFile.size);
+
+          // Verify the uploaded data matches the original
+          const uploadedData = yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            testFile.size ?? 0,
+          );
+          const originalData = generateData(testFile.size ?? 0, {
+            type: "random",
+            seed: 12345,
+          });
+
+          expect(compareArrays(uploadedData, originalData)).toBe(true);
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should upload files with file extensions", async () => {
+      const testFile = createTestUploadFile(
+        "test-file",
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+        {
+          metadata: {
+            fileName: "document.pdf",
+          },
+        },
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          const createdFile = yield* filesystemStore.create(testFile);
+
+          yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          // Should create file with extension
+          yield* assertFileUploaded(
+            testDirectory,
+            "test-file.pdf",
+            testFile.size ?? 0,
+          );
+
+          // Verify storage path includes extension
+          expect(createdFile.storage.id).toContain(".pdf");
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should create subdirectories as needed", async () => {
+      const testFile = createTestUploadFile(
+        "subdir/nested/file",
+        TEST_FILE_SIZES.TINY.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          // Verify file was created in subdirectory
+          yield* assertFileUploaded(
+            testDirectory,
+            "subdir/nested/file",
+            testFile.size ?? 0,
+          );
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+
+  describe("Medium File Uploads", () => {
+    it("should upload medium files (10MB)", async () => {
+      const testFile = createTestUploadFile(
+        "medium-test",
+        TEST_FILE_SIZES.MEDIUM.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0, {
+        type: "pattern",
+        pattern: new Uint8Array([0xab, 0xcd, 0xef]),
+      });
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          const finalOffset = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(finalOffset).toBe(testFile.size);
+
+          const uploadedData = yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            testFile.size ?? 0,
+          );
+
+          // Verify the data integrity
+          const originalData = generateData(testFile.size ?? 0, {
+            type: "pattern",
+            pattern: new Uint8Array([0xab, 0xcd, 0xef]),
+          });
+          expect(compareArrays(uploadedData, originalData)).toBe(true);
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+        20000,
+      );
+    });
+
+    it("should upload large medium files (49MB)", async () => {
+      const testFile = createTestUploadFile(
+        "large-medium-test",
+        TEST_FILE_SIZES.MEDIUM_LARGE.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          const finalOffset = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(finalOffset).toBe(testFile.size);
+          yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            testFile.size ?? 0,
+          );
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+        30000,
+      );
+    });
+  });
+
+  describe("Large File Uploads", () => {
+    it("should upload large files (50MB) efficiently", async () => {
+      const testFile = createTestUploadFile(
+        "large-test",
+        TEST_FILE_SIZES.LARGE.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          const finalOffset = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(finalOffset).toBe(testFile.size);
+          yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            testFile.size ?? 0,
+          );
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+        45000,
+      );
+    });
+  });
+
+  describe("Upload Progress Tracking", () => {
+    it("should track progress for small files", async () => {
+      const testFile = createTestUploadFile(
+        "progress-small",
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+      const progressUpdates: number[] = [];
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          const finalOffset = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            {
+              onProgress: (chunkSize) => progressUpdates.push(chunkSize),
+            },
+          );
+
+          expect(finalOffset).toBe(testFile.size);
+          expect(progressUpdates.length).toBeGreaterThan(0);
+
+          // Sum of all chunks should equal file size
+          const totalBytes = progressUpdates.reduce((sum, size) => sum + size, 0);
+          expect(totalBytes).toBe(testFile.size);
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+
+  describe("Resumable Uploads", () => {
+    it.skip("should support resumable uploads with offset", { timeout: 30000 }, async () => {
+      const testFile = createTestUploadFile(
+        "resumable-test",
+        TEST_FILE_SIZES.MEDIUM.size,
+      );
+
+      // Split the upload into two parts
+      const fileSize = testFile.size ?? 0;
+      const part1Size = Math.floor(fileSize / 2);
+      const part2Size = fileSize - part1Size;
+
+      const part1Data = createTestDataStream(part1Size, { type: "zeros" });
+      const part2Data = createTestDataStream(part2Size, { type: "ones" });
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          // Upload first part
+          const offset1 = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: part1Data,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(offset1).toBe(part1Size);
+
+          // Verify partial upload
+          const partialSize = yield* getFileSize(testDirectory, testFile.id);
+          expect(partialSize).toBe(part1Size);
+
+          // Upload second part (resume)
+          const offset2 = yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: part2Data,
+              offset: offset1,
+            },
+            { onProgress: undefined },
+          );
+
+          expect(offset2).toBe(fileSize);
+
+          // Verify complete file was uploaded
+          const uploadedData = yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            fileSize,
+          );
+
+          // Verify first part is zeros and second part is ones
+          for (let i = 0; i < part1Size; i++) {
+            expect(uploadedData[i]).toBe(0);
+          }
+          for (let i = part1Size; i < fileSize; i++) {
+            expect(uploadedData[i]).toBe(0xff);
+          }
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+        25000,
+      );
+    });
+  });
+
+  describe("File Read Operations", () => {
+    it("should read uploaded file data", async () => {
+      const testFile = createTestUploadFile(
+        "read-test",
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+      );
+      const originalData = generateData(testFile.size ?? 0, {
+        type: "text",
+      });
+      const testData = createTestDataStream(testFile.size ?? 0, {
+        type: "text",
+      });
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          // Upload file
+          yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          // Read file data
+          const readData = yield* filesystemStore.read(testFile.id);
+
+          expect(compareArrays(readData, originalData)).toBe(true);
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should retrieve upload information accurately", async () => {
+      const testFile = createTestUploadFile(
+        "getupload-test",
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          // Upload file
+          yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          // Verify file size matches expected
+          const fileSize = yield* getFileSize(testDirectory, testFile.id);
+          expect(fileSize).toBe(testFile.size); // Should be fully uploaded
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+
+  describe("File Deletion", () => {
+    it("should remove uploaded files", async () => {
+      const testFile = createTestUploadFile(
+        "delete-test",
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+      );
+      const testData = createTestDataStream(testFile.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(testFile);
+
+          // Upload file
+          yield* filesystemStore.write(
+            {
+              file_id: testFile.id,
+              stream: testData,
+              offset: 0,
+            },
+            { onProgress: undefined },
+          );
+
+          // Verify file exists
+          yield* assertFileUploaded(
+            testDirectory,
+            testFile.id,
+            testFile.size ?? 0,
+          );
+
+          // Remove file
+          yield* filesystemStore.remove(testFile.id);
+
+          // Verify file is deleted from KV store
+          const kvStore = yield* UploadFileKVStore;
+          const result = yield* Effect.either(kvStore.get(testFile.id));
+          expect(result._tag).toBe("Left");
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+
+  describe("Standard Test Files", () => {
+    it("should handle all standard test file types", async () => {
+      const testFiles = createStandardTestFiles();
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          for (const testFileData of testFiles) {
+            const testFile = createTestUploadFile(
+              testFileData.id,
+              testFileData.size,
+              {
+                metadata: testFileData.metadata,
+              },
+            );
+
+            yield* filesystemStore.create(testFile);
+
+            const finalOffset = yield* filesystemStore.write(
+              {
+                file_id: testFile.id,
+                stream: testFileData.stream,
+                offset: 0,
+              },
+              { onProgress: undefined },
+            );
+
+            expect(finalOffset).toBe(testFile.size);
+
+            const uploadedData = yield* assertFileUploaded(
+              testDirectory,
+              testFile.id,
+              testFile.size ?? 0,
+            );
+            expect(compareArrays(uploadedData, testFileData.data)).toBe(true);
+          }
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+        60000,
+      );
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should handle file not found errors", async () => {
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          const result = yield* Effect.either(
+            filesystemStore.read("non-existent-file"),
+          );
+
+          expect(result._tag).toBe("Left");
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+
+    it("should handle remove errors for non-existent files", async () => {
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          const result = yield* Effect.either(
+            filesystemStore.remove("non-existent-file"),
+          );
+
+          expect(result._tag).toBe("Left");
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+
+  describe("Filesystem-Specific Features", () => {
+    it("should list all uploaded files", async () => {
+      const file1 = createTestUploadFile("file1", TEST_FILE_SIZES.TINY.size);
+      const file2 = createTestUploadFile("file2", TEST_FILE_SIZES.TINY.size);
+      const data1 = createTestDataStream(file1.size ?? 0);
+      const data2 = createTestDataStream(file2.size ?? 0);
+
+      await runTestWithTimeout(
+        Effect.gen(function* () {
+          yield* filesystemStore.create(file1);
+          yield* filesystemStore.write(
+            { file_id: file1.id, stream: data1, offset: 0 },
+            { onProgress: undefined },
+          );
+
+          yield* filesystemStore.create(file2);
+          yield* filesystemStore.write(
+            { file_id: file2.id, stream: data2, offset: 0 },
+            { onProgress: undefined },
+          );
+
+          const files = yield* listFiles(testDirectory);
+          expect(files.length).toBe(2);
+          expect(files).toContain("file1");
+          expect(files).toContain("file2");
+        }).pipe(Effect.provide(TestLayersWithMemoryKV())),
+      );
+    });
+  });
+});

package/tests/utils/test-data-generator.ts

@@ -0,0 +1,246 @@
+import { Stream } from "effect";
+
+export interface TestFileSize {
+  name: string;
+  size: number;
+  description: string;
+}
+
+export const TEST_FILE_SIZES: Record<string, TestFileSize> = {
+  TINY: {
+    name: "tiny",
+    size: 1024, // 1KB
+    description: "Tiny file for edge cases",
+  },
+  SMALL_BASIC: {
+    name: "small-basic",
+    size: 1024 * 1024, // 1MB
+    description: "Basic small file",
+  },
+  SMALL_LARGE: {
+    name: "small-large",
+    size: Math.floor(4.9 * 1024 * 1024), // 4.9MB
+    description: "Large small file",
+  },
+  MEDIUM: {
+    name: "medium",
+    size: 10 * 1024 * 1024, // 10MB
+    description: "Standard medium file",
+  },
+  MEDIUM_LARGE: {
+    name: "medium-large",
+    size: 49 * 1024 * 1024, // 49MB
+    description: "Large medium file",
+  },
+  LARGE: {
+    name: "large",
+    size: 50 * 1024 * 1024, // 50MB
+    description: "Standard large file",
+  },
+} as const;
+
+export interface TestFilePattern {
+  type: "random" | "zeros" | "ones" | "pattern" | "text";
+  pattern?: Uint8Array;
+  seed?: number;
+}
+
+/**
+ * Generate random data with optional seed for reproducibility
+ */
+export function generateRandomData(size: number, seed?: number): Uint8Array {
+  const data = new Uint8Array(size);
+
+  if (seed !== undefined) {
+    // Simple LCG for reproducible randomness
+    let rng = seed;
+    for (let i = 0; i < size; i++) {
+      rng = (rng * 1664525 + 1013904223) >>> 0;
+      data[i] = (rng >>> 24) & 0xff;
+    }
+  } else {
+    // crypto.getRandomValues has a 65,536 byte limit, so we need to generate in chunks
+    const maxChunkSize = 65536;
+    let offset = 0;
+
+    while (offset < size) {
+      const chunkSize = Math.min(maxChunkSize, size - offset);
+      const chunk = data.subarray(offset, offset + chunkSize);
+      crypto.getRandomValues(chunk);
+      offset += chunkSize;
+    }
+  }
+
+  return data;
+}
+
+/**
+ * Generate data filled with zeros
+ */
+export function generateZeroData(size: number): Uint8Array {
+  return new Uint8Array(size);
+}
+
+/**
+ * Generate data filled with ones
+ */
+export function generateOnesData(size: number): Uint8Array {
+  const data = new Uint8Array(size);
+  data.fill(0xff);
+  return data;
+}
+
+/**
+ * Generate data with repeating pattern
+ */
+export function generatePatternData(
+  size: number,
+  pattern: Uint8Array,
+): Uint8Array {
+  const data = new Uint8Array(size);
+  for (let i = 0; i < size; i++) {
+    data[i] = pattern[i % pattern.length];
+  }
+  return data;
+}
+
+/**
+ * Generate text data
+ */
+export function generateTextData(size: number): Uint8Array {
+  const text = "The quick brown fox jumps over the lazy dog. ";
+  const encoder = new TextEncoder();
+  const pattern = encoder.encode(text);
+  return generatePatternData(size, pattern);
+}
+
+/**
+ * Generate test data based on pattern specification
+ */
+export function generateData(
+  size: number,
+  pattern?: TestFilePattern,
+): Uint8Array {
+  if (!pattern) {
+    return generateRandomData(size);
+  }
+
+  switch (pattern.type) {
+    case "random":
+      return generateRandomData(size, pattern.seed);
+    case "zeros":
+      return generateZeroData(size);
+    case "ones":
+      return generateOnesData(size);
+    case "pattern":
+      return generatePatternData(size, pattern.pattern || new Uint8Array([0]));
+    case "text":
+      return generateTextData(size);
+    default:
+      return generateRandomData(size);
+  }
+}
+
+/**
+ * Create an Effect Stream from test data
+ */
+export function createTestDataStream(
+  size: number,
+  pattern?: TestFilePattern,
+  chunkSize = 64 * 1024, // 64KB chunks by default
+): Stream.Stream<Uint8Array, never, never> {
+  const data = generateData(size, pattern);
+
+  return Stream.make(...chunkData(data, chunkSize));
+}
+
+/**
+ * Split data into chunks
+ */
+function chunkData(data: Uint8Array, chunkSize: number): Uint8Array[] {
+  const chunks: Uint8Array[] = [];
+  let offset = 0;
+
+  while (offset < data.byteLength) {
+    const size = Math.min(chunkSize, data.byteLength - offset);
+    chunks.push(data.subarray(offset, offset + size));
+    offset += size;
+  }
+
+  return chunks;
+}
+
+/**
+ * Compare two Uint8Arrays
+ */
+export function compareArrays(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) {
+    return false;
+  }
+
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Create standard test files with different patterns
+ */
+export function createStandardTestFiles() {
+  return [
+    {
+      id: "test-zeros",
+      size: TEST_FILE_SIZES.SMALL_BASIC.size,
+      stream: createTestDataStream(TEST_FILE_SIZES.SMALL_BASIC.size, {
+        type: "zeros",
+      }),
+      data: generateZeroData(TEST_FILE_SIZES.SMALL_BASIC.size),
+      metadata: { contentType: "application/octet-stream" },
+    },
+    {
+      id: "test-ones",
+      size: TEST_FILE_SIZES.SMALL_BASIC.size,
+      stream: createTestDataStream(TEST_FILE_SIZES.SMALL_BASIC.size, {
+        type: "ones",
+      }),
+      data: generateOnesData(TEST_FILE_SIZES.SMALL_BASIC.size),
+      metadata: { contentType: "application/octet-stream" },
+    },
+    {
+      id: "test-pattern",
+      size: TEST_FILE_SIZES.SMALL_BASIC.size,
+      stream: createTestDataStream(TEST_FILE_SIZES.SMALL_BASIC.size, {
+        type: "pattern",
+        pattern: new Uint8Array([0xaa, 0xbb, 0xcc]),
+      }),
+      data: generatePatternData(
+        TEST_FILE_SIZES.SMALL_BASIC.size,
+        new Uint8Array([0xaa, 0xbb, 0xcc]),
+      ),
+      metadata: { contentType: "application/octet-stream" },
+    },
+    {
+      id: "test-text",
+      size: TEST_FILE_SIZES.SMALL_BASIC.size,
+      stream: createTestDataStream(TEST_FILE_SIZES.SMALL_BASIC.size, {
+        type: "text",
+      }),
+      data: generateTextData(TEST_FILE_SIZES.SMALL_BASIC.size),
+      metadata: { contentType: "text/plain" },
+    },
+    {
+      id: "test-random-seeded",
+      size: TEST_FILE_SIZES.SMALL_BASIC.size,
+      stream: createTestDataStream(TEST_FILE_SIZES.SMALL_BASIC.size, {
+        type: "random",
+        seed: 42,
+      }),
+      data: generateRandomData(TEST_FILE_SIZES.SMALL_BASIC.size, 42),
+      metadata: { contentType: "application/octet-stream" },
+    },
+  ];
+}

package/tests/utils/test-setup.ts

@@ -0,0 +1,144 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { UploadFile } from "@uploadista/core/types";
+import { uploadFileKvStore } from "@uploadista/core/types";
+import { memoryKvStore } from "@uploadista/kv-store-memory";
+import { Effect, Layer } from "effect";
+import type { FileStoreOptions } from "../../src/file-store";
+
+// Test directory configuration
+export const TEST_DELIVERY_URL = "http://localhost:3000/files";
+
+// Helper to create a temporary test directory
+export const createTestDirectory = (): Effect.Effect<string, never> =>
+  Effect.promise(async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "uploadista-test-"));
+    return tmpDir;
+  });
+
+// Helper to clean up test directory
+export const cleanupTestDirectory = (
+  directory: string,
+): Effect.Effect<void, never> =>
+  Effect.promise(async () => {
+    try {
+      await fs.rm(directory, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore errors during cleanup
+      console.warn(`Failed to cleanup test directory ${directory}:`, error);
+    }
+  });
+
+// Common filesystem store configuration for tests
+export const createTestFilesystemStoreConfig = (
+  directory: string,
+  overrides: Partial<FileStoreOptions> = {},
+): FileStoreOptions => ({
+  directory,
+  deliveryUrl: TEST_DELIVERY_URL,
+  ...overrides,
+});
+
+// Layer that provides KV store for testing
+export const TestLayersWithMemoryKV = () => {
+  return uploadFileKvStore.pipe(Layer.provide(memoryKvStore));
+};
+
+// Helper to run tests with timeout
+export const runTestWithTimeout = async <E>(
+  effect: Effect.Effect<void, E>,
+  timeout = 10000,
+) => {
+  await Effect.runPromise(Effect.timeout(effect, `${timeout} millis`));
+};
+
+// Helper to create test upload file
+export const createTestUploadFile = (
+  id: string,
+  size: number,
+  options: {
+    metadata?: Record<string, string | number | boolean>;
+  } = {},
+): UploadFile => ({
+  id,
+  size,
+  offset: 0,
+  metadata: options.metadata,
+  storage: {
+    id: "test-storage",
+    type: "filesystem",
+    path: id,
+    bucket: "test-directory",
+  },
+  sizeIsDeferred: false,
+});
+
+// Helper to assert file exists on filesystem
+export const assertFileExists = (
+  directory: string,
+  fileId: string,
+): Effect.Effect<void, never> =>
+  Effect.promise(async () => {
+    const filePath = path.join(directory, fileId);
+    try {
+      await fs.access(filePath);
+    } catch (_error) {
+      throw new Error(`File ${fileId} not found at ${filePath}`);
+    }
+  });
+
+// Helper to read file from filesystem
+export const readFileFromFilesystem = (
+  directory: string,
+  fileId: string,
+): Effect.Effect<Uint8Array, never> =>
+  Effect.promise(async () => {
+    const filePath = path.join(directory, fileId);
+    const buffer = await fs.readFile(filePath);
+    return new Uint8Array(buffer);
+  });
+
+// Helper to get file size from filesystem
+export const getFileSize = (
+  directory: string,
+  fileId: string,
+): Effect.Effect<number, never> =>
+  Effect.promise(async () => {
+    const filePath = path.join(directory, fileId);
+    const stats = await fs.stat(filePath);
+    return stats.size;
+  });
+
+// Helper to list files in directory
+export const listFiles = (directory: string): Effect.Effect<string[], never> =>
+  Effect.promise(async () => {
+    try {
+      const files = await fs.readdir(directory, { recursive: true });
+      return files.filter((file) => {
+        // Filter out directories
+        return !file.endsWith("/");
+      });
+    } catch (_error) {
+      return [];
+    }
+  });
+
+// Helper to assert file was uploaded correctly
+export const assertFileUploaded = (
+  directory: string,
+  fileId: string,
+  expectedSize: number,
+): Effect.Effect<Uint8Array, never> =>
+  Effect.gen(function* () {
+    yield* assertFileExists(directory, fileId);
+
+    const size = yield* getFileSize(directory, fileId);
+    if (size !== expectedSize) {
+      throw new Error(
+        `File size mismatch: expected ${expectedSize}, got ${size}`,
+      );
+    }
+
+    return yield* readFileFromFilesystem(directory, fileId);
+  });

package/vitest.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Shared vitest configuration template for uploadista-sdk packages
+ *
+ * This template should be used by all SDK packages to ensure consistent
+ * testing configuration across the monorepo.
+ *
+ * Key features:
+ * - Tests in dedicated `tests/` directories (not colocated with src)
+ * - Node environment for server-side code
+ * - V8 coverage provider
+ * - Global test functions available
+ * - Effect testing support via @effect/vitest
+ *
+ * Usage:
+ * Copy this file to your package root as `vitest.config.ts` and customize
+ * if needed (though most packages should use this as-is).
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    exclude: ["node_modules", "dist"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      exclude: [
+        "node_modules/",
+        "dist/",
+        "**/*.d.ts",
+        "**/*.test.ts",
+        "**/*.spec.ts",
+        "tests/",
+      ],
+    },
+  },
+});