@uploadista/data-store-filesystem 0.0.3

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> @uploadista/data-store-filesystem@0.0.2 build /Users/denislaboureyras/Documents/uploadista/dev/uploadista-workspace/uploadista-sdk/packages/data-stores/filesystem
+> tsc -b
+

package/.turbo/turbo-check.log

@@ -0,0 +1,5 @@
+
+> @uploadista/data-store-filesystem@ check /Users/denislaboureyras/Documents/uploadista/dev/uploadista/packages/uploadista/data-stores/filesystem
+> biome check --write ./src
+
+Checked 2 files in 56ms. No fixes applied.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 uploadista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,583 @@
+# @uploadista/data-store-filesystem
+
+Local filesystem data store for Uploadista - Store files on disk.
+
+Provides file system-based storage perfect for development, testing, and self-hosted deployments. Supports sequential uploads with resumable transfers and automatic cleanup of old files.
+
+## Features
+
+- **Local Storage** - Files stored on server disk or shared volume
+- **Resumable Uploads** - Resume failed transfers at specific offsets
+- **Sequential Mode** - Safe, ordered chunk uploads
+- **Auto-Cleanup** - Automatic expiration of incomplete uploads
+- **Simple Setup** - No external services required
+- **Full Observability** - Metrics and logging included
+- **TypeScript** - Full type safety with comprehensive JSDoc
+
+## Installation
+
+```bash
+npm install @uploadista/data-store-filesystem @uploadista/core
+# or
+pnpm add @uploadista/data-store-filesystem @uploadista/core
+```
+
+## Requirements
+
+- Node.js 18+
+- Writable disk space
+- Linux/macOS/Windows
+- TypeScript 5.0+ (optional but recommended)
+
+## Quick Start
+
+### 1. Create Filesystem Data Store
+
+```typescript
+import { createFileStore } from "@uploadista/data-store-filesystem";
+import { createUploadServerLayer } from "@uploadista/server";
+import { memoryKvStore } from "@uploadista/kv-store-memory";
+import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+import { Effect } from "effect";
+
+// Create file store
+const fileStore = createFileStore({
+  directory: "./uploads",
+  deliveryUrl: "http://localhost:3000/uploads",
+});
+
+// Use in upload server
+const uploadLayer = createUploadServerLayer({
+  dataStore: fileStore,
+  kvStore: memoryKvStore,
+  eventEmitter: webSocketEventEmitter,
+});
+```
+
+### 2. Configure Upload Directory
+
+```typescript
+import path from "path";
+import { createFileStore } from "@uploadista/data-store-filesystem";
+
+// Development
+const devStore = createFileStore({
+  directory: "./uploads",
+  deliveryUrl: "http://localhost:3000/files",
+});
+
+// Production
+const prodStore = createFileStore({
+  directory: "/var/uploads",
+  deliveryUrl: "https://cdn.example.com/files",
+});
+
+// Docker/Kubernetes (mounted volume)
+const containerStore = createFileStore({
+  directory: "/mnt/uploads",
+  deliveryUrl: "https://uploads.example.com",
+});
+```
+
+### 3. Serve Files
+
+```typescript
+import express from "express";
+import path from "path";
+
+const app = express();
+
+// Serve uploaded files statically
+app.use("/uploads", express.static("./uploads"));
+
+// Or with caching headers
+app.use("/uploads", express.static("./uploads", {
+  maxAge: "1d",
+  etag: false,
+}));
+```
+
+## Configuration
+
+### `FileStoreOptions`
+
+```typescript
+type FileStoreOptions = {
+  // Required
+  directory: string;        // Base directory for file storage (created if missing)
+  deliveryUrl: string;      // URL prefix for serving files
+
+  // Optional (from parent config)
+  kvStore?: KvStore;        // Metadata store (defaults to in-memory)
+};
+```
+
+### Upload Behavior
+
+The filesystem store operates in **sequential mode** only:
+
+```typescript
+// Upload state tracking
+// File 1: upload-123 (1MB file)
+// ├── write chunk 0-512KB
+// ├── write chunk 512KB-1MB
+// └── complete
+//
+// Cannot write chunks out of order - must resume from last successful position
+```
+
+## Storage Layout
+
+Files are stored with metadata:
+
+```
+./uploads/
+├── upload-123/
+│   ├── file.bin              # Actual file content
+│   ├── .metadata.json        # Upload metadata
+│   └── .locks/               # Concurrency locks
+├── upload-456/
+│   ├── file.bin
+│   └── .metadata.json
+└── .expiration.log           # Expiration tracking
+```
+
+Metadata example:
+```json
+{
+  "id": "upload-123",
+  "filename": "document.pdf",
+  "size": 1048576,
+  "uploadedAt": "2024-01-15T10:30:00Z",
+  "expiresAt": "2024-01-22T10:30:00Z",
+  "mimeType": "application/pdf"
+}
+```
+
+## Complete Server Example
+
+```typescript
+import express, { Express } from "express";
+import path from "path";
+import { createExpressUploadistaAdapter } from "@uploadista/adapters-express";
+import { createFileStore } from "@uploadista/data-store-filesystem";
+import { memoryKvStore } from "@uploadista/kv-store-memory";
+import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+import { memoryEventBroadcaster } from "@uploadista/event-broadcaster-memory";
+import http from "http";
+import WebSocket from "ws";
+
+const app: Express = express();
+
+// Serve uploaded files
+app.use("/files", express.static("./uploads"));
+
+// Create file store
+const fileStore = createFileStore({
+  directory: process.env.UPLOAD_DIR || "./uploads",
+  deliveryUrl: process.env.DELIVERY_URL || "http://localhost:3000/files",
+});
+
+// Create adapter
+const adapter = await createExpressUploadistaAdapter({
+  baseUrl: "uploadista",
+  dataStore: fileStore,
+  kvStore: memoryKvStore,
+  eventEmitter: webSocketEventEmitter,
+  eventBroadcaster: memoryEventBroadcaster,
+  flows: createFlowsEffect,
+});
+
+// Mount HTTP handler
+app.use(`/${adapter.baseUrl}`, (req, res) => {
+  adapter.handler(req, res);
+});
+
+// WebSocket server
+const server = http.createServer(app);
+const wss = new WebSocket.Server({ server });
+
+wss.on("connection", (ws, req) => {
+  adapter.websocketConnectionHandler(ws, req);
+});
+
+server.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+  console.log(`Files stored in: ${process.env.UPLOAD_DIR || './uploads'}`);
+});
+```
+
+## Environment Configuration
+
+### .env File
+
+```env
+# Storage
+UPLOAD_DIR=./uploads
+DELIVERY_URL=http://localhost:3000/files
+
+# Or with subdirectory for temporary uploads
+UPLOAD_DIR=/tmp/uploads
+
+# Production with volume mount
+UPLOAD_DIR=/mnt/persistent-storage/uploads
+DELIVERY_URL=https://files.example.com
+```
+
+### Creating Upload Directory
+
+```typescript
+import fs from "fs";
+import path from "path";
+
+// Automatically created by the store
+// But you can pre-create it:
+const uploadDir = process.env.UPLOAD_DIR || "./uploads";
+if (!fs.existsSync(uploadDir)) {
+  fs.mkdirSync(uploadDir, { recursive: true, mode: 0o755 });
+}
+
+const fileStore = createFileStore({
+  directory: uploadDir,
+  deliveryUrl: process.env.DELIVERY_URL,
+});
+```
+
+## Use Cases
+
+### Development
+
+Perfect for local development without external dependencies:
+
+```typescript
+const devStore = createFileStore({
+  directory: "./uploads",
+  deliveryUrl: "http://localhost:3000/uploads",
+});
+
+// Server runs on your machine - files stored locally
+```
+
+### Testing
+
+Use temporary directories for test isolation:
+
+```typescript
+import { tmpdir } from "os";
+import path from "path";
+
+const testDir = path.join(tmpdir(), `uploadista-test-${Date.now()}`);
+const testStore = createFileStore({
+  directory: testDir,
+  deliveryUrl: "http://localhost:3000/uploads",
+});
+
+// Clean up after tests
+afterEach(() => {
+  fs.rmSync(testDir, { recursive: true });
+});
+```
+
+### Docker/Kubernetes
+
+Mount volumes for persistent storage:
+
+```typescript
+const k8sStore = createFileStore({
+  directory: "/mnt/uploads",  // Kubernetes PersistentVolume
+  deliveryUrl: "https://files.example.com",
+});
+
+// Deployment YAML:
+// volumeMounts:
+// - name: uploads-volume
+//   mountPath: /mnt/uploads
+// volumes:
+// - name: uploads-volume
+//   persistentVolumeClaim:
+//     claimName: uploads-pvc
+```
+
+### NFS/Shared Storage
+
+For distributed deployments:
+
+```typescript
+const nfsStore = createFileStore({
+  directory: "/mnt/nfs/uploads",  // NFS mount point
+  deliveryUrl: "https://files.example.com",
+});
+
+// Multiple servers share the same storage
+// Files visible to all instances
+```
+
+## Storage Considerations
+
+### Disk Space
+
+Calculate required storage:
+
+```
+Daily uploads = 100 files × 5MB = 500MB/day
+Monthly = 500MB × 30 = 15GB/month
+Yearly = 15GB × 12 = 180GB/year
+
+Reserve 20% buffer for OS and system = 216GB required
+```
+
+### Backup Strategy
+
+```bash
+# Daily backup to cloud storage
+# Example: rsync to AWS S3
+0 2 * * * aws s3 sync /mnt/uploads s3://my-backup-bucket/uploads/$(date +\%Y-\%m-\%d)
+
+# Or with tar
+0 2 * * * tar czf /backups/uploads-$(date +\%Y-\%m-\%d).tar.gz /mnt/uploads
+```
+
+### Cleanup
+
+```typescript
+// Old uploads automatically cleaned up after expiration
+// Default: 7 days (configurable in KV store)
+
+// Manual cleanup
+import fs from "fs";
+const uploadDir = "./uploads";
+const files = fs.readdirSync(uploadDir);
+
+files.forEach(file => {
+  const stats = fs.statSync(`${uploadDir}/${file}`);
+  const age = Date.now() - stats.mtimeMs;
+
+  // Delete files older than 30 days
+  if (age > 30 * 24 * 60 * 60 * 1000) {
+    fs.rmSync(`${uploadDir}/${file}`, { recursive: true });
+  }
+});
+```
+
+## Performance Characteristics
+
+**Sequential uploads only:**
+```
+✓ Slow uploads (must resume from last position)
+✗ Cannot parallel write chunks (safety constraint)
+✓ Stable and reliable for small-medium files
+✓ Good for development and testing
+```
+
+**Use for:**
+- Development environments
+- Testing scenarios
+- Small to medium files (<1GB)
+- Self-hosted deployments with local disk
+- Shared storage (NFS, SMB)
+
+**Don't use for:**
+- High-concurrency production (use S3/Azure/GCS instead)
+- Very large files (>10GB)
+- Cloud-native applications (no S3/GCS/Azure integration)
+
+## Docker Deployment
+
+### Dockerfile
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY dist ./dist
+
+ENV NODE_ENV=production
+ENV UPLOAD_DIR=/data/uploads
+ENV DELIVERY_URL=https://files.example.com
+
+VOLUME ["/data/uploads"]
+
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+### docker-compose.yml
+
+```yaml
+version: "3.8"
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    volumes:
+      - uploads:/data/uploads
+      - ./uploads:/app/public/uploads:ro  # serve from web
+    environment:
+      UPLOAD_DIR: /data/uploads
+      DELIVERY_URL: http://localhost:3000/files
+
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+    volumes:
+      - uploads:/usr/share/nginx/html/files:ro
+      - ./nginx.conf:/etc/nginx/nginx.conf
+
+volumes:
+  uploads:
+```
+
+### Kubernetes
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: uploads-pvc
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 100Gi
+
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: uploadista-server
+spec:
+  replicas: 1  # Note: Single replica due to sequential writes
+  selector:
+    matchLabels:
+      app: uploadista
+  template:
+    metadata:
+      labels:
+        app: uploadista
+    spec:
+      containers:
+      - name: app
+        image: uploadista:latest
+        ports:
+        - containerPort: 3000
+        env:
+        - name: UPLOAD_DIR
+          value: /mnt/uploads
+        - name: DELIVERY_URL
+          value: https://files.example.com
+        volumeMounts:
+        - name: uploads
+          mountPath: /mnt/uploads
+      volumes:
+      - name: uploads
+        persistentVolumeClaim:
+          claimName: uploads-pvc
+```
+
+## Monitoring
+
+### Disk Usage
+
+```bash
+# Check disk usage
+du -sh ./uploads
+
+# Monitor in real-time
+watch 'du -sh ./uploads && ls -la ./uploads | wc -l'
+```
+
+### Metrics
+
+```typescript
+// Track storage metrics
+import fs from "fs";
+
+const uploadDir = "./uploads";
+const files = fs.readdirSync(uploadDir);
+const totalSize = files.reduce((sum, file) => {
+  const stats = fs.statSync(`${uploadDir}/${file}`);
+  return sum + stats.size;
+}, 0);
+
+console.log(`Total files: ${files.length}`);
+console.log(`Total size: ${(totalSize / 1024 / 1024).toFixed(2)}MB`);
+```
+
+## Limitations
+
+Due to sequential-only uploads:
+
+1. **Single Replica Only** - Multiple servers can't share same directory
+2. **No Parallel Chunks** - Chunks must upload in order
+3. **Slower Resume** - Must re-upload from last position
+4. **Disk Dependent** - Speed limited by disk I/O
+5. **No Cloud Scaling** - Can't span multiple servers
+
+For high-scale production, use S3/Azure/GCS instead.
+
+## Related Packages
+
+- **[@uploadista/data-store-s3](../s3/)** - AWS S3 (recommended for production)
+- **[@uploadista/data-store-azure](../azure/)** - Azure Blob Storage
+- **[@uploadista/data-store-gcs](../gcs/)** - Google Cloud Storage
+- **[@uploadista/server](../../servers/server/)** - Core server utilities
+- **[@uploadista/kv-store-memory](../../kv-stores/memory/)** - In-memory KV store
+- **[@uploadista/core](../../core/)** - Core engine
+
+## TypeScript Support
+
+Full TypeScript support:
+
+```typescript
+import type { FileStoreOptions } from "@uploadista/data-store-filesystem";
+import { createFileStore, fileStore } from "@uploadista/data-store-filesystem";
+```
+
+## Troubleshooting
+
+### Permission Denied
+
+```bash
+# Check directory permissions
+ls -ld ./uploads
+
+# Fix permissions
+chmod 755 ./uploads
+chmod 644 ./uploads/*
+```
+
+### Disk Full
+
+```bash
+# Check available space
+df -h
+
+# Find largest files
+du -sh ./uploads/* | sort -rh | head -10
+
+# Clean old uploads
+find ./uploads -mtime +30 -delete  # Files older than 30 days
+```
+
+### Upload Fails
+
+```bash
+# Check if directory exists
+test -d ./uploads && echo "exists" || echo "missing"
+
+# Create if missing
+mkdir -p ./uploads
+
+# Verify write permissions
+touch ./uploads/test && rm ./uploads/test
+```
+
+## License
+
+MIT

package/dist/file-store.d.ts

@@ -0,0 +1,15 @@
+import type { DataStore, UploadFile } from "@uploadista/core/types";
+import { UploadFileKVStore } from "@uploadista/core/types";
+import { Effect } from "effect";
+export type FileStoreOptions = {
+    directory: string;
+    deliveryUrl: string;
+};
+/**
+ * A data store that stores files in the filesystem.
+ * @param options - The options for the file store.
+ * @returns A data store that stores files in the filesystem.
+ */
+export declare const createFileStore: ({ directory, deliveryUrl }: FileStoreOptions) => Effect.Effect<DataStore<UploadFile>, never, UploadFileKVStore>;
+export declare const fileStore: (options: FileStoreOptions) => Effect.Effect<DataStore<UploadFile>, never, UploadFileKVStore>;
+//# sourceMappingURL=file-store.d.ts.map

package/dist/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,SAAS,EAGT,UAAU,EAEX,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAc3D,OAAO,EAAE,MAAM,EAAqB,MAAM,QAAQ,CAAC;AAEnD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAqGF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,4BAA4B,gBAAgB,mEA0OxE,CAAC;AAEL,eAAO,MAAM,SAAS,GAAI,SAAS,gBAAgB,mEACzB,CAAC"}

package/dist/file-store.js

@@ -0,0 +1,257 @@
+import fs from "node:fs";
+import fsProm from "node:fs/promises";
+import path from "node:path";
+import { UploadistaError } from "@uploadista/core/errors";
+import { UploadFileKVStore } from "@uploadista/core/types";
+import { filesystemActiveUploadsGauge as activeUploadsGauge, filesystemFileSizeHistogram as fileSizeHistogram, logFilesystemUploadCompletion, filesystemPartSizeHistogram as partSizeHistogram, trackFilesystemError, filesystemUploadDurationHistogram as uploadDurationHistogram, filesystemUploadPartsTotal as uploadPartsTotal, filesystemUploadRequestsTotal as uploadRequestsTotal, filesystemUploadSuccessTotal as uploadSuccessTotal, withFilesystemTimingMetrics as withTimingMetrics, withFilesystemUploadMetrics as withUploadMetrics, } from "@uploadista/observability";
+import { Effect, Ref, Sink, Stream } from "effect";
+const MASK = "0777";
+const IGNORED_MKDIR_ERROR = "EEXIST";
+// const FILE_DOESNT_EXIST = "ENOENT";
+const checkOrCreateDirectory = (directory) => Effect.tryPromise({
+    try: () => fsProm.mkdir(directory, { mode: MASK, recursive: true }),
+    catch: (error) => {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === IGNORED_MKDIR_ERROR) {
+            // Directory already exists, not an error
+            return new UploadistaError({
+                code: "UNKNOWN_ERROR",
+                status: 200,
+                body: "Directory already exists",
+                details: "Directory already exists",
+            });
+        }
+        return new UploadistaError({
+            code: "UNKNOWN_ERROR",
+            status: 500,
+            body: "Failed to create directory",
+            details: `Directory creation failed: ${String(error)}`,
+        });
+    },
+}).pipe(Effect.orElse(() => Effect.void));
+const createWriteStream = (file_path, offset) => Effect.sync(() => fs.createWriteStream(file_path, {
+    flags: "r+",
+    start: offset,
+}));
+const writeChunk = ({ writeStream, bytesReceived, onProgress, }) => (chunk) => Effect.gen(function* () {
+    yield* Effect.async((resume) => {
+        writeStream.write(chunk, (err) => {
+            if (err) {
+                resume(Effect.fail(new UploadistaError({
+                    code: "FILE_WRITE_ERROR",
+                    status: 500,
+                    body: "Failed to write chunk",
+                    details: `Chunk write failed: ${String(err)}`,
+                })));
+            }
+            else {
+                resume(Effect.succeed(void 0));
+            }
+        });
+    });
+    yield* Ref.update(bytesReceived, (size) => size + chunk.length);
+    onProgress?.(chunk.length);
+});
+const endWriteStream = (writeStream) => Effect.async((resume) => {
+    writeStream.end((err) => {
+        if (err) {
+            resume(Effect.fail(new UploadistaError({
+                code: "FILE_WRITE_ERROR",
+                status: 500,
+                body: "Failed to close write stream",
+                details: `Stream close failed: ${String(err)}`,
+            })));
+        }
+        else {
+            resume(Effect.succeed(void 0));
+        }
+    });
+});
+const destroyWriteStream = (writeStream) => Effect.sync(() => {
+    if (!writeStream.destroyed) {
+        writeStream.destroy();
+    }
+});
+/**
+ * A data store that stores files in the filesystem.
+ * @param options - The options for the file store.
+ * @returns A data store that stores files in the filesystem.
+ */
+export const createFileStore = ({ directory, deliveryUrl }) => Effect.gen(function* () {
+    yield* checkOrCreateDirectory(directory);
+    const kvStore = yield* UploadFileKVStore;
+    const getCapabilities = () => {
+        return {
+            supportsParallelUploads: false, // Filesystem operations are sequential
+            supportsConcatenation: false, // No native concatenation support
+            supportsDeferredLength: false,
+            supportsResumableUploads: true, // Can write at specific offsets
+            supportsTransactionalUploads: false,
+            maxConcurrentUploads: 1, // Sequential writes only
+            minChunkSize: undefined,
+            maxChunkSize: undefined,
+            maxParts: undefined,
+            optimalChunkSize: 1024 * 1024, // 1MB default
+            requiresOrderedChunks: true, // Sequential offset-based writes
+            requiresMimeTypeValidation: true,
+            maxValidationSize: undefined, // no size limit
+        };
+    };
+    const validateUploadStrategy = (strategy) => {
+        const capabilities = getCapabilities();
+        switch (strategy) {
+            case "parallel":
+                return Effect.succeed(capabilities.supportsParallelUploads);
+            case "single":
+                return Effect.succeed(true);
+            default:
+                return Effect.succeed(false);
+        }
+    };
+    return {
+        bucket: directory,
+        create: (file) => {
+            const fileName = file.metadata?.fileName?.toString();
+            const fileExtension = fileName?.split(".").pop();
+            const dirs = file.id.split("/").slice(0, -1);
+            const filePath = path.join(directory, fileExtension ? `${file.id}.${fileExtension}` : file.id);
+            return Effect.gen(function* () {
+                yield* uploadRequestsTotal(Effect.succeed(1));
+                yield* activeUploadsGauge(Effect.succeed(1));
+                yield* fileSizeHistogram(Effect.succeed(file.size || 0));
+                yield* Effect.tryPromise({
+                    try: () => fsProm.mkdir(path.join(directory, ...dirs), {
+                        recursive: true,
+                    }),
+                    catch: (error) => {
+                        Effect.runSync(trackFilesystemError("create", error, {
+                            upload_id: file.id,
+                            path: filePath,
+                        }));
+                        return new UploadistaError({
+                            code: "UNKNOWN_ERROR",
+                            status: 500,
+                            body: "Failed to create file directory",
+                            details: `Directory creation failed: ${String(error)}`,
+                        });
+                    },
+                });
+                yield* Effect.tryPromise({
+                    try: () => fsProm.writeFile(filePath, ""),
+                    catch: (error) => {
+                        Effect.runSync(trackFilesystemError("create", error, {
+                            upload_id: file.id,
+                            path: filePath,
+                        }));
+                        return new UploadistaError({
+                            code: "UNKNOWN_ERROR",
+                            status: 500,
+                            body: "Failed to create file",
+                            details: `File creation failed: ${String(error)}`,
+                        });
+                    },
+                });
+                const fileId = fileExtension
+                    ? `${file.id}.${fileExtension}`
+                    : file.id;
+                file.storage = {
+                    id: fileId,
+                    type: file.storage.type,
+                    path: filePath,
+                    bucket: directory,
+                };
+                file.url = `${deliveryUrl}/${fileId}`;
+                // Store file metadata in KV store
+                yield* kvStore.set(file.id, file);
+                return file;
+            });
+        },
+        remove: (file_id) => {
+            return Effect.gen(function* () {
+                const uploadFile = yield* kvStore.get(file_id);
+                const file_path = uploadFile.storage.path || path.join(directory, file_id);
+                yield* Effect.tryPromise({
+                    try: () => fsProm.unlink(file_path),
+                    catch: (error) => {
+                        Effect.runSync(trackFilesystemError("remove", error, {
+                            upload_id: file_id,
+                            path: file_path,
+                        }));
+                        return UploadistaError.fromCode("FILE_NOT_FOUND");
+                    },
+                });
+                yield* kvStore.delete(file_id);
+                yield* activeUploadsGauge(Effect.succeed(-1));
+            });
+        },
+        write: ({ file_id, stream, offset }, { onProgress }) => {
+            return withUploadMetrics(file_id, withTimingMetrics(uploadDurationHistogram, Effect.gen(function* () {
+                const startTime = Date.now();
+                // Get the upload file from KV store to retrieve the actual file path
+                const uploadFile = yield* kvStore.get(file_id);
+                const file_path = uploadFile.storage.path || path.join(directory, file_id);
+                const bytesReceived = yield* Ref.make(0);
+                try {
+                    const result = yield* Effect.acquireUseRelease(createWriteStream(file_path, offset), (writeStream) => Effect.gen(function* () {
+                        const sink = Sink.forEach(writeChunk({ writeStream, bytesReceived, onProgress }));
+                        yield* uploadPartsTotal(Effect.succeed(1));
+                        yield* Stream.run(stream, sink);
+                        yield* endWriteStream(writeStream);
+                        const totalBytes = yield* Ref.get(bytesReceived);
+                        yield* partSizeHistogram(Effect.succeed(totalBytes));
+                        return offset + totalBytes;
+                    }), destroyWriteStream);
+                    // Check if upload is complete
+                    if (uploadFile.size && result === uploadFile.size) {
+                        yield* logFilesystemUploadCompletion(file_id, {
+                            fileSize: uploadFile.size,
+                            totalDurationMs: Date.now() - startTime,
+                            partsCount: 1,
+                            averagePartSize: uploadFile.size,
+                            throughputBps: uploadFile.size / (Date.now() - startTime),
+                            retryCount: 0,
+                        });
+                        yield* uploadSuccessTotal(Effect.succeed(1));
+                        yield* activeUploadsGauge(Effect.succeed(-1));
+                    }
+                    return result;
+                }
+                catch (error) {
+                    Effect.runSync(trackFilesystemError("write", error, {
+                        upload_id: file_id,
+                        path: file_path,
+                        offset,
+                    }));
+                    throw error;
+                }
+            })));
+        },
+        getUpload: (id) => Effect.gen(function* () {
+            const uploadFile = yield* kvStore.get(id);
+            // For filesystem, get the actual file size from disk
+            const file_path = uploadFile.storage.path || path.join(directory, id);
+            const stats = yield* Effect.tryPromise({
+                try: () => fsProm.stat(file_path),
+                catch: () => UploadistaError.fromCode("FILE_NOT_FOUND"),
+            });
+            return {
+                ...uploadFile,
+                offset: stats.size,
+                size: uploadFile.size,
+            };
+        }),
+        read: (id) => Effect.gen(function* () {
+            const uploadFile = yield* kvStore.get(id);
+            const file_path = uploadFile.storage.path || path.join(directory, id);
+            const buffer = yield* Effect.tryPromise({
+                try: () => fsProm.readFile(file_path),
+                catch: () => UploadistaError.fromCode("FILE_READ_ERROR"),
+            });
+            return new Uint8Array(buffer);
+        }),
+        getCapabilities,
+        validateUploadStrategy,
+    };
+});
+export const fileStore = (options) => createFileStore(options);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./file-store";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./file-store";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@uploadista/data-store-filesystem",
+  "type": "module",
+  "version": "0.0.3",
+  "description": "File system data store for Uploadista",
+  "license": "MIT",
+  "author": "Uploadista",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "effect": "3.18.4",
+    "@uploadista/observability": "0.0.3",
+    "@uploadista/core": "0.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.8.1",
+    "@uploadista/typescript-config": "0.0.3"
+  },
+  "scripts": {
+    "dev": "tsc -b",
+    "build": "tsc -b",
+    "format": "biome format --write ./src",
+    "lint": "biome lint --write ./src",
+    "check": "biome check --write ./src"
+  }
+}

package/src/file-store.ts

@@ -0,0 +1,374 @@
+import fs from "node:fs";
+import fsProm from "node:fs/promises";
+import path from "node:path";
+import { UploadistaError } from "@uploadista/core/errors";
+import type {
+  DataStore,
+  DataStoreCapabilities,
+  DataStoreWriteOptions,
+  UploadFile,
+  UploadStrategy,
+} from "@uploadista/core/types";
+import { UploadFileKVStore } from "@uploadista/core/types";
+import {
+  filesystemActiveUploadsGauge as activeUploadsGauge,
+  filesystemFileSizeHistogram as fileSizeHistogram,
+  logFilesystemUploadCompletion,
+  filesystemPartSizeHistogram as partSizeHistogram,
+  trackFilesystemError,
+  filesystemUploadDurationHistogram as uploadDurationHistogram,
+  filesystemUploadPartsTotal as uploadPartsTotal,
+  filesystemUploadRequestsTotal as uploadRequestsTotal,
+  filesystemUploadSuccessTotal as uploadSuccessTotal,
+  withFilesystemTimingMetrics as withTimingMetrics,
+  withFilesystemUploadMetrics as withUploadMetrics,
+} from "@uploadista/observability";
+import { Effect, Ref, Sink, Stream } from "effect";
+
+export type FileStoreOptions = {
+  directory: string;
+  deliveryUrl: string;
+};
+
+const MASK = "0777";
+const IGNORED_MKDIR_ERROR = "EEXIST";
+// const FILE_DOESNT_EXIST = "ENOENT";
+
+const checkOrCreateDirectory = (directory: string) =>
+  Effect.tryPromise({
+    try: () => fsProm.mkdir(directory, { mode: MASK, recursive: true }),
+    catch: (error) => {
+      if (
+        error instanceof Error &&
+        "code" in error &&
+        error.code === IGNORED_MKDIR_ERROR
+      ) {
+        // Directory already exists, not an error
+        return new UploadistaError({
+          code: "UNKNOWN_ERROR",
+          status: 200,
+          body: "Directory already exists",
+          details: "Directory already exists",
+        });
+      }
+      return new UploadistaError({
+        code: "UNKNOWN_ERROR",
+        status: 500,
+        body: "Failed to create directory",
+        details: `Directory creation failed: ${String(error)}`,
+      });
+    },
+  }).pipe(Effect.orElse(() => Effect.void));
+
+const createWriteStream = (file_path: string, offset: number) =>
+  Effect.sync(() =>
+    fs.createWriteStream(file_path, {
+      flags: "r+",
+      start: offset,
+    }),
+  );
+
+const writeChunk =
+  ({
+    writeStream,
+    bytesReceived,
+    onProgress,
+  }: {
+    writeStream: fs.WriteStream;
+    bytesReceived: Ref.Ref<number>;
+    onProgress?: (chunkSize: number) => void;
+  }) =>
+  (chunk: Uint8Array) =>
+    Effect.gen(function* () {
+      yield* Effect.async<void, UploadistaError>((resume) => {
+        writeStream.write(chunk, (err) => {
+          if (err) {
+            resume(
+              Effect.fail(
+                new UploadistaError({
+                  code: "FILE_WRITE_ERROR",
+                  status: 500,
+                  body: "Failed to write chunk",
+                  details: `Chunk write failed: ${String(err)}`,
+                }),
+              ),
+            );
+          } else {
+            resume(Effect.succeed(void 0));
+          }
+        });
+      });
+
+      yield* Ref.update(bytesReceived, (size) => size + chunk.length);
+      onProgress?.(chunk.length);
+    });
+
+const endWriteStream = (writeStream: fs.WriteStream) =>
+  Effect.async<void, UploadistaError>((resume) => {
+    writeStream.end((err: Error | null | undefined) => {
+      if (err) {
+        resume(
+          Effect.fail(
+            new UploadistaError({
+              code: "FILE_WRITE_ERROR",
+              status: 500,
+              body: "Failed to close write stream",
+              details: `Stream close failed: ${String(err)}`,
+            }),
+          ),
+        );
+      } else {
+        resume(Effect.succeed(void 0));
+      }
+    });
+  });
+
+const destroyWriteStream = (writeStream: fs.WriteStream) =>
+  Effect.sync(() => {
+    if (!writeStream.destroyed) {
+      writeStream.destroy();
+    }
+  });
+/**
+ * A data store that stores files in the filesystem.
+ * @param options - The options for the file store.
+ * @returns A data store that stores files in the filesystem.
+ */
+export const createFileStore = ({ directory, deliveryUrl }: FileStoreOptions) =>
+  Effect.gen(function* () {
+    yield* checkOrCreateDirectory(directory);
+    const kvStore = yield* UploadFileKVStore;
+
+    const getCapabilities = (): DataStoreCapabilities => {
+      return {
+        supportsParallelUploads: false, // Filesystem operations are sequential
+        supportsConcatenation: false, // No native concatenation support
+        supportsDeferredLength: false,
+        supportsResumableUploads: true, // Can write at specific offsets
+        supportsTransactionalUploads: false,
+        maxConcurrentUploads: 1, // Sequential writes only
+        minChunkSize: undefined,
+        maxChunkSize: undefined,
+        maxParts: undefined,
+        optimalChunkSize: 1024 * 1024, // 1MB default
+        requiresOrderedChunks: true, // Sequential offset-based writes
+        requiresMimeTypeValidation: true,
+        maxValidationSize: undefined, // no size limit
+      };
+    };
+
+    const validateUploadStrategy = (
+      strategy: UploadStrategy,
+    ): Effect.Effect<boolean, never> => {
+      const capabilities = getCapabilities();
+
+      switch (strategy) {
+        case "parallel":
+          return Effect.succeed(capabilities.supportsParallelUploads);
+        case "single":
+          return Effect.succeed(true);
+        default:
+          return Effect.succeed(false);
+      }
+    };
+
+    return {
+      bucket: directory,
+      create: (
+        file: UploadFile,
+      ): Effect.Effect<UploadFile, UploadistaError> => {
+        const fileName = file.metadata?.fileName?.toString();
+        const fileExtension = fileName?.split(".").pop();
+
+        const dirs = file.id.split("/").slice(0, -1);
+        const filePath = path.join(
+          directory,
+          fileExtension ? `${file.id}.${fileExtension}` : file.id,
+        );
+
+        return Effect.gen(function* () {
+          yield* uploadRequestsTotal(Effect.succeed(1));
+          yield* activeUploadsGauge(Effect.succeed(1));
+          yield* fileSizeHistogram(Effect.succeed(file.size || 0));
+
+          yield* Effect.tryPromise({
+            try: () =>
+              fsProm.mkdir(path.join(directory, ...dirs), {
+                recursive: true,
+              }),
+            catch: (error) => {
+              Effect.runSync(
+                trackFilesystemError("create", error, {
+                  upload_id: file.id,
+                  path: filePath,
+                }),
+              );
+              return new UploadistaError({
+                code: "UNKNOWN_ERROR",
+                status: 500,
+                body: "Failed to create file directory",
+                details: `Directory creation failed: ${String(error)}`,
+              });
+            },
+          });
+
+          yield* Effect.tryPromise({
+            try: () => fsProm.writeFile(filePath, ""),
+            catch: (error) => {
+              Effect.runSync(
+                trackFilesystemError("create", error, {
+                  upload_id: file.id,
+                  path: filePath,
+                }),
+              );
+              return new UploadistaError({
+                code: "UNKNOWN_ERROR",
+                status: 500,
+                body: "Failed to create file",
+                details: `File creation failed: ${String(error)}`,
+              });
+            },
+          });
+
+          const fileId = fileExtension
+            ? `${file.id}.${fileExtension}`
+            : file.id;
+          file.storage = {
+            id: fileId,
+            type: file.storage.type,
+            path: filePath,
+            bucket: directory,
+          };
+          file.url = `${deliveryUrl}/${fileId}`;
+
+          // Store file metadata in KV store
+          yield* kvStore.set(file.id, file);
+
+          return file;
+        });
+      },
+      remove: (file_id: string): Effect.Effect<void, UploadistaError> => {
+        return Effect.gen(function* () {
+          const uploadFile = yield* kvStore.get(file_id);
+          const file_path =
+            uploadFile.storage.path || path.join(directory, file_id);
+
+          yield* Effect.tryPromise({
+            try: () => fsProm.unlink(file_path),
+            catch: (error) => {
+              Effect.runSync(
+                trackFilesystemError("remove", error, {
+                  upload_id: file_id,
+                  path: file_path,
+                }),
+              );
+              return UploadistaError.fromCode("FILE_NOT_FOUND");
+            },
+          });
+
+          yield* kvStore.delete(file_id);
+          yield* activeUploadsGauge(Effect.succeed(-1));
+        });
+      },
+      write: (
+        { file_id, stream, offset }: DataStoreWriteOptions,
+        { onProgress }: { onProgress?: (chunkSize: number) => void },
+      ): Effect.Effect<number, UploadistaError> => {
+        return withUploadMetrics(
+          file_id,
+          withTimingMetrics(
+            uploadDurationHistogram,
+            Effect.gen(function* () {
+              const startTime = Date.now();
+              // Get the upload file from KV store to retrieve the actual file path
+              const uploadFile = yield* kvStore.get(file_id);
+              const file_path =
+                uploadFile.storage.path || path.join(directory, file_id);
+
+              const bytesReceived = yield* Ref.make(0);
+
+              try {
+                const result = yield* Effect.acquireUseRelease(
+                  createWriteStream(file_path, offset),
+                  (writeStream) =>
+                    Effect.gen(function* () {
+                      const sink = Sink.forEach(
+                        writeChunk({ writeStream, bytesReceived, onProgress }),
+                      );
+
+                      yield* uploadPartsTotal(Effect.succeed(1));
+                      yield* Stream.run(stream, sink);
+                      yield* endWriteStream(writeStream);
+
+                      const totalBytes = yield* Ref.get(bytesReceived);
+                      yield* partSizeHistogram(Effect.succeed(totalBytes));
+                      return offset + totalBytes;
+                    }),
+                  destroyWriteStream,
+                );
+
+                // Check if upload is complete
+                if (uploadFile.size && result === uploadFile.size) {
+                  yield* logFilesystemUploadCompletion(file_id, {
+                    fileSize: uploadFile.size,
+                    totalDurationMs: Date.now() - startTime,
+                    partsCount: 1,
+                    averagePartSize: uploadFile.size,
+                    throughputBps: uploadFile.size / (Date.now() - startTime),
+                    retryCount: 0,
+                  });
+                  yield* uploadSuccessTotal(Effect.succeed(1));
+                  yield* activeUploadsGauge(Effect.succeed(-1));
+                }
+
+                return result;
+              } catch (error) {
+                Effect.runSync(
+                  trackFilesystemError("write", error, {
+                    upload_id: file_id,
+                    path: file_path,
+                    offset,
+                  }),
+                );
+                throw error;
+              }
+            }),
+          ),
+        );
+      },
+      getUpload: (id: string) =>
+        Effect.gen(function* () {
+          const uploadFile = yield* kvStore.get(id);
+
+          // For filesystem, get the actual file size from disk
+          const file_path = uploadFile.storage.path || path.join(directory, id);
+          const stats = yield* Effect.tryPromise({
+            try: () => fsProm.stat(file_path),
+            catch: () => UploadistaError.fromCode("FILE_NOT_FOUND"),
+          });
+
+          return {
+            ...uploadFile,
+            offset: stats.size,
+            size: uploadFile.size,
+          };
+        }),
+      read: (id: string) =>
+        Effect.gen(function* () {
+          const uploadFile = yield* kvStore.get(id);
+          const file_path = uploadFile.storage.path || path.join(directory, id);
+
+          const buffer = yield* Effect.tryPromise({
+            try: () => fsProm.readFile(file_path),
+            catch: () => UploadistaError.fromCode("FILE_READ_ERROR"),
+          });
+
+          return new Uint8Array(buffer);
+        }),
+      getCapabilities,
+      validateUploadStrategy,
+    } as DataStore<UploadFile>;
+  });
+
+export const fileStore = (options: FileStoreOptions) =>
+  createFileStore(options);

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./file-store";

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@uploadista/typescript-config/server.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/file-store.ts","./src/index.ts"],"version":"5.9.3"}