@better-media/adapter-storage-filesystem 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abenezeratnafu
+
+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, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @better-media/adapter-storage-filesystem
+
+Local filesystem storage adapter for the Better Media framework.
+
+## Features
+
+- **Local Storage**: Store files in a directory on your disk.
+- **Node.js**: Uses `fs-extra` and Node.js built-in streams.
+- **MIME Awareness**: Respects and stores MIME information as needed.
+
+## Installation
+
+```bash
+pnpm add @better-media/adapter-storage-filesystem
+```
+
+## Usage
+
+```ts
+import { FileSystemStorageAdapter } from "@better-media/adapter-storage-filesystem";
+
+const storage = new FileSystemStorageAdapter({
+  baseDir: "./uploads",
+  baseUrl: "http://localhost:3000/public",
+});
+```
+
+For more, visit [better-media.dev/docs/adapters/storage-filesystem](https://better-media.dev/docs/adapters/storage-filesystem).

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+import { StorageAdapter } from '@better-media/core';
+
+interface FilesystemStorageConfig {
+    /** Base directory where all files are stored. Keys are resolved relative to this path. */
+    baseDir: string;
+}
+/**
+ * Filesystem storage adapter for development or single-node deployments.
+ * Stores files on disk under a configurable base directory.
+ *
+ * Works well with Multer in Express/NestJS - Multer saves to disk, then you
+ * can read the file and put it into this storage using the desired key.
+ */
+declare class FileSystemStorageAdapter implements StorageAdapter {
+    private readonly baseDir;
+    constructor(config: FilesystemStorageConfig);
+    get(key: string): Promise<Buffer | null>;
+    put(key: string, value: Buffer): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getSize(key: string): Promise<number | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+}
+
+export { FileSystemStorageAdapter, type FilesystemStorageConfig };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { StorageAdapter } from '@better-media/core';
+
+interface FilesystemStorageConfig {
+    /** Base directory where all files are stored. Keys are resolved relative to this path. */
+    baseDir: string;
+}
+/**
+ * Filesystem storage adapter for development or single-node deployments.
+ * Stores files on disk under a configurable base directory.
+ *
+ * Works well with Multer in Express/NestJS - Multer saves to disk, then you
+ * can read the file and put it into this storage using the desired key.
+ */
+declare class FileSystemStorageAdapter implements StorageAdapter {
+    private readonly baseDir;
+    constructor(config: FilesystemStorageConfig);
+    get(key: string): Promise<Buffer | null>;
+    put(key: string, value: Buffer): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getSize(key: string): Promise<number | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+}
+
+export { FileSystemStorageAdapter, type FilesystemStorageConfig };

package/dist/index.js

@@ -0,0 +1,87 @@
+'use strict';
+
+var fs = require('fs/promises');
+var fs$1 = require('fs');
+var path = require('path');
+var stream = require('stream');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// src/index.ts
+function resolveSafePath(baseDir, key) {
+  const base = path__default.default.resolve(baseDir);
+  const resolved = path__default.default.resolve(base, key);
+  const relative = path__default.default.relative(base, resolved);
+  if (relative.startsWith("..") || path__default.default.isAbsolute(relative)) {
+    throw new Error(`Storage key resolves outside base directory: ${key}`);
+  }
+  return resolved;
+}
+var FileSystemStorageAdapter = class {
+  baseDir;
+  constructor(config) {
+    this.baseDir = path__default.default.resolve(config.baseDir);
+  }
+  async get(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      return await fs__default.default.readFile(filePath);
+    } catch (err) {
+      if (isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async put(key, value) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    const dir = path__default.default.dirname(filePath);
+    await fs__default.default.mkdir(dir, { recursive: true });
+    await fs__default.default.writeFile(filePath, value);
+  }
+  async delete(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      await fs__default.default.unlink(filePath);
+    } catch (err) {
+      if (isNotFoundError(err)) return;
+      throw err;
+    }
+  }
+  async exists(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      await fs__default.default.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getSize(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      const stat = await fs__default.default.stat(filePath);
+      return stat.isFile() ? stat.size : null;
+    } catch {
+      return null;
+    }
+  }
+  async getStream(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      await fs__default.default.access(filePath);
+    } catch {
+      return null;
+    }
+    const nodeStream = fs$1.createReadStream(filePath);
+    return stream.Readable.toWeb(nodeStream);
+  }
+};
+function isNotFoundError(err) {
+  return err instanceof Error && err.code === "ENOENT";
+}
+
+exports.FileSystemStorageAdapter = FileSystemStorageAdapter;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["path","fs","createReadStream","Readable"],"mappings":"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","file":"index.js","sourcesContent":["import fs from \"node:fs/promises\";\nimport { createReadStream } from \"node:fs\";\nimport path from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport type { StorageAdapter } from \"@better-media/core\";\n\nexport interface FilesystemStorageConfig {\n  /** Base directory where all files are stored. Keys are resolved relative to this path. */\n  baseDir: string;\n}\n\n/**\n * Resolve a storage key to a safe filesystem path inside baseDir.\n * Prevents directory traversal (e.g. \"../../etc/passwd\").\n */\nfunction resolveSafePath(baseDir: string, key: string): string {\n  const base = path.resolve(baseDir);\n  const resolved = path.resolve(base, key);\n  const relative = path.relative(base, resolved);\n  if (relative.startsWith(\"..\") || path.isAbsolute(relative)) {\n    throw new Error(`Storage key resolves outside base directory: ${key}`);\n  }\n  return resolved;\n}\n\n/**\n * Filesystem storage adapter for development or single-node deployments.\n * Stores files on disk under a configurable base directory.\n *\n * Works well with Multer in Express/NestJS - Multer saves to disk, then you\n * can read the file and put it into this storage using the desired key.\n */\nexport class FileSystemStorageAdapter implements StorageAdapter {\n  private readonly baseDir: string;\n\n  constructor(config: FilesystemStorageConfig) {\n    this.baseDir = path.resolve(config.baseDir);\n  }\n\n  async get(key: string): Promise<Buffer | null> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      return await fs.readFile(filePath);\n    } catch (err) {\n      if (isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async put(key: string, value: Buffer): Promise<void> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    const dir = path.dirname(filePath);\n    await fs.mkdir(dir, { recursive: true });\n    await fs.writeFile(filePath, value);\n  }\n\n  async delete(key: string): Promise<void> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      await fs.unlink(filePath);\n    } catch (err) {\n      if (isNotFoundError(err)) return;\n      throw err;\n    }\n  }\n\n  async exists(key: string): Promise<boolean> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      await fs.access(filePath);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  async getSize(key: string): Promise<number | null> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      const stat = await fs.stat(filePath);\n      return stat.isFile() ? stat.size : null;\n    } catch {\n      return null;\n    }\n  }\n\n  async getStream(key: string): Promise<ReadableStream<Uint8Array> | null> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      await fs.access(filePath);\n    } catch {\n      return null;\n    }\n    const nodeStream = createReadStream(filePath);\n    return Readable.toWeb(nodeStream) as ReadableStream<Uint8Array>;\n  }\n}\n\nfunction isNotFoundError(err: unknown): boolean {\n  return err instanceof Error && (err as NodeJS.ErrnoException).code === \"ENOENT\";\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,80 @@
+import fs from 'fs/promises';
+import { createReadStream } from 'fs';
+import path from 'path';
+import { Readable } from 'stream';
+
+// src/index.ts
+function resolveSafePath(baseDir, key) {
+  const base = path.resolve(baseDir);
+  const resolved = path.resolve(base, key);
+  const relative = path.relative(base, resolved);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Storage key resolves outside base directory: ${key}`);
+  }
+  return resolved;
+}
+var FileSystemStorageAdapter = class {
+  baseDir;
+  constructor(config) {
+    this.baseDir = path.resolve(config.baseDir);
+  }
+  async get(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      return await fs.readFile(filePath);
+    } catch (err) {
+      if (isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async put(key, value) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, value);
+  }
+  async delete(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      await fs.unlink(filePath);
+    } catch (err) {
+      if (isNotFoundError(err)) return;
+      throw err;
+    }
+  }
+  async exists(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getSize(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      const stat = await fs.stat(filePath);
+      return stat.isFile() ? stat.size : null;
+    } catch {
+      return null;
+    }
+  }
+  async getStream(key) {
+    const filePath = resolveSafePath(this.baseDir, key);
+    try {
+      await fs.access(filePath);
+    } catch {
+      return null;
+    }
+    const nodeStream = createReadStream(filePath);
+    return Readable.toWeb(nodeStream);
+  }
+};
+function isNotFoundError(err) {
+  return err instanceof Error && err.code === "ENOENT";
+}
+
+export { FileSystemStorageAdapter };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import fs from \"node:fs/promises\";\nimport { createReadStream } from \"node:fs\";\nimport path from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport type { StorageAdapter } from \"@better-media/core\";\n\nexport interface FilesystemStorageConfig {\n  /** Base directory where all files are stored. Keys are resolved relative to this path. */\n  baseDir: string;\n}\n\n/**\n * Resolve a storage key to a safe filesystem path inside baseDir.\n * Prevents directory traversal (e.g. \"../../etc/passwd\").\n */\nfunction resolveSafePath(baseDir: string, key: string): string {\n  const base = path.resolve(baseDir);\n  const resolved = path.resolve(base, key);\n  const relative = path.relative(base, resolved);\n  if (relative.startsWith(\"..\") || path.isAbsolute(relative)) {\n    throw new Error(`Storage key resolves outside base directory: ${key}`);\n  }\n  return resolved;\n}\n\n/**\n * Filesystem storage adapter for development or single-node deployments.\n * Stores files on disk under a configurable base directory.\n *\n * Works well with Multer in Express/NestJS - Multer saves to disk, then you\n * can read the file and put it into this storage using the desired key.\n */\nexport class FileSystemStorageAdapter implements StorageAdapter {\n  private readonly baseDir: string;\n\n  constructor(config: FilesystemStorageConfig) {\n    this.baseDir = path.resolve(config.baseDir);\n  }\n\n  async get(key: string): Promise<Buffer | null> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      return await fs.readFile(filePath);\n    } catch (err) {\n      if (isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async put(key: string, value: Buffer): Promise<void> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    const dir = path.dirname(filePath);\n    await fs.mkdir(dir, { recursive: true });\n    await fs.writeFile(filePath, value);\n  }\n\n  async delete(key: string): Promise<void> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      await fs.unlink(filePath);\n    } catch (err) {\n      if (isNotFoundError(err)) return;\n      throw err;\n    }\n  }\n\n  async exists(key: string): Promise<boolean> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      await fs.access(filePath);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  async getSize(key: string): Promise<number | null> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      const stat = await fs.stat(filePath);\n      return stat.isFile() ? stat.size : null;\n    } catch {\n      return null;\n    }\n  }\n\n  async getStream(key: string): Promise<ReadableStream<Uint8Array> | null> {\n    const filePath = resolveSafePath(this.baseDir, key);\n    try {\n      await fs.access(filePath);\n    } catch {\n      return null;\n    }\n    const nodeStream = createReadStream(filePath);\n    return Readable.toWeb(nodeStream) as ReadableStream<Uint8Array>;\n  }\n}\n\nfunction isNotFoundError(err: unknown): boolean {\n  return err instanceof Error && (err as NodeJS.ErrnoException).code === \"ENOENT\";\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@better-media/adapter-storage-filesystem",
+  "version": "0.1.0",
+  "description": "Filesystem storage adapter for Better Media",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@better-media/core": "0.1.0"
+  },
+  "keywords": [
+    "better-media",
+    "storage",
+    "filesystem",
+    "adapter"
+  ],
+  "author": "Abenezer Atnafu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AbenezerAtnafu/better-media.git"
+  },
+  "homepage": "https://better-media.dev",
+  "bugs": {
+    "url": "https://github.com/AbenezerAtnafu/better-media/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "jest"
+  }
+}