millas 0.1.0

package/src/storage/Storage.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const path = require('path');
+const os   = require('os');
+
+/**
+ * Storage
+ *
+ * The primary file storage facade.
+ *
+ * Usage:
+ *   const { Storage } = require('millas/src');
+ *
+ *   // Write a file
+ *   await Storage.put('avatars/alice.jpg', buffer);
+ *
+ *   // Read a file
+ *   const buffer = await Storage.get('avatars/alice.jpg');
+ *
+ *   // Check existence
+ *   const ok = await Storage.exists('avatars/alice.jpg');
+ *
+ *   // Delete
+ *   await Storage.delete('avatars/alice.jpg');
+ *
+ *   // URL
+ *   const url = Storage.url('avatars/alice.jpg');  // /storage/avatars/alice.jpg
+ *
+ *   // Use a different disk
+ *   await Storage.disk('public').put('images/logo.png', buffer);
+ */
+class Storage {
+  constructor() {
+    this._disks  = new Map();  // name → driver instance
+    this._config = null;
+    this._default = 'local';
+  }
+
+  // ─── Configuration ─────────────────────────────────────────────────────────
+
+  configure(config) {
+    this._config  = config;
+    this._default = config.default || 'local';
+    this._disks.clear();
+  }
+
+  // ─── Disk selector ─────────────────────────────────────────────────────────
+
+  /**
+   * Select a named disk.
+   * Storage.disk('public').put(...)
+   */
+  disk(name) {
+    return new DiskProxy(this._getDisk(name));
+  }
+
+  // ─── Default disk proxy methods ────────────────────────────────────────────
+
+  async put(filePath, content, options = {})   { return this._getDisk().put(filePath, content, options); }
+  async get(filePath)                          { return this._getDisk().get(filePath); }
+  async getString(filePath)                    { return this._getDisk().getString(filePath); }
+  async exists(filePath)                       { return this._getDisk().exists(filePath); }
+  async delete(filePath)                       { return this._getDisk().delete(filePath); }
+  async deleteDirectory(dirPath)               { return this._getDisk().deleteDirectory(dirPath); }
+  async copy(from, to)                         { return this._getDisk().copy(from, to); }
+  async move(from, to)                         { return this._getDisk().move(from, to); }
+  async files(dirPath)                         { return this._getDisk().files(dirPath); }
+  async allFiles(dirPath)                      { return this._getDisk().allFiles(dirPath); }
+  async directories(dirPath)                   { return this._getDisk().directories(dirPath); }
+  async makeDirectory(dirPath)                 { return this._getDisk().makeDirectory(dirPath); }
+  async metadata(filePath)                     { return this._getDisk().metadata(filePath); }
+  url(filePath)                                { return this._getDisk().url(filePath); }
+  path(filePath)                               { return this._getDisk().path(filePath); }
+  stream(filePath, res, options)               { return this._getDisk().stream(filePath, res, options); }
+
+  /**
+   * Store an uploaded file from a Multer/Busboy req.file object.
+   *
+   * const path = await Storage.putFile('avatars', req.file);
+   */
+  async putFile(directory, file, options = {}) {
+    const ext      = path.extname(file.originalname || file.filename || '');
+    const filename = options.name
+      ? `${options.name}${ext}`
+      : `${this._uniqueId()}${ext}`;
+    const filePath = `${directory}/${filename}`.replace(/\/+/g, '/');
+
+    const content = file.buffer || file.path
+      ? (file.buffer || await require('fs-extra').readFile(file.path))
+      : Buffer.from('');
+
+    await this._getDisk().put(filePath, content);
+    return filePath;
+  }
+
+  /**
+   * Store a base64-encoded data URI.
+   *
+   * const path = await Storage.putDataUri('avatars', 'data:image/png;base64,...');
+   */
+  async putDataUri(directory, dataUri, filename) {
+    const match = dataUri.match(/^data:([^;]+);base64,(.+)$/);
+    if (!match) throw new Error('Invalid data URI');
+
+    const mimeType = match[1];
+    const buffer   = Buffer.from(match[2], 'base64');
+    const ext      = mimeType.split('/')[1] || 'bin';
+    const name     = filename || `${this._uniqueId()}.${ext}`;
+    const filePath = `${directory}/${name}`.replace(/\/+/g, '/');
+
+    await this._getDisk().put(filePath, buffer);
+    return filePath;
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  _getDisk(name) {
+    const diskName = name || this._default;
+
+    if (this._disks.has(diskName)) return this._disks.get(diskName);
+
+    const driver = this._buildDriver(diskName);
+    this._disks.set(diskName, driver);
+    return driver;
+  }
+
+  _buildDriver(name) {
+    const diskConf  = this._config?.disks?.[name] || {};
+    const driverName = diskConf.driver || name || 'local';
+
+    switch (driverName) {
+      case 'local':
+      default: {
+        const LocalDriver = require('./drivers/LocalDriver');
+        return new LocalDriver(diskConf);
+      }
+    }
+  }
+
+  _uniqueId() {
+    return `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+}
+
+// ── DiskProxy ─────────────────────────────────────────────────────────────────
+
+class DiskProxy {
+  constructor(driver) { this._d = driver; }
+  async put(f, c, o)    { return this._d.put(f, c, o); }
+  async get(f)          { return this._d.get(f); }
+  async getString(f)    { return this._d.getString(f); }
+  async exists(f)       { return this._d.exists(f); }
+  async delete(f)       { return this._d.delete(f); }
+  async deleteDirectory(d){ return this._d.deleteDirectory(d); }
+  async copy(f, t)      { return this._d.copy(f, t); }
+  async move(f, t)      { return this._d.move(f, t); }
+  async files(d)        { return this._d.files(d); }
+  async allFiles(d)     { return this._d.allFiles(d); }
+  async directories(d)  { return this._d.directories(d); }
+  async makeDirectory(d){ return this._d.makeDirectory(d); }
+  async metadata(f)     { return this._d.metadata(f); }
+  url(f)                { return this._d.url(f); }
+  path(f)               { return this._d.path(f); }
+  stream(f, r, o)       { return this._d.stream(f, r, o); }
+}
+
+// Singleton
+const storage = new Storage();
+module.exports = storage;
+module.exports.Storage = Storage;

package/src/storage/drivers/LocalDriver.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const fs   = require('fs-extra');
+const path = require('path');
+
+/**
+ * LocalDriver
+ *
+ * Stores files on the local filesystem.
+ * Default driver — zero config required.
+ *
+ * STORAGE_DRIVER=local
+ */
+class LocalDriver {
+  constructor(config = {}) {
+    this._root    = config.root    || path.join(process.cwd(), 'storage/uploads');
+    this._baseUrl = config.baseUrl || '/storage';
+    fs.ensureDirSync(this._root);
+  }
+
+  /**
+   * Write a file. Returns the stored path.
+   * @param {string}          filePath — relative path inside storage
+   * @param {Buffer|string}   content
+   * @param {object}          options
+   */
+  async put(filePath, content, options = {}) {
+    const dest = this._abs(filePath);
+    await fs.ensureDir(path.dirname(dest));
+    await fs.writeFile(dest, content, options.encoding || null);
+    return filePath;
+  }
+
+  /**
+   * Read a file. Returns a Buffer.
+   */
+  async get(filePath) {
+    const abs = this._abs(filePath);
+    if (!(await fs.pathExists(abs))) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    return fs.readFile(abs);
+  }
+
+  /**
+   * Read a file as a UTF-8 string.
+   */
+  async getString(filePath) {
+    const buf = await this.get(filePath);
+    return buf.toString('utf8');
+  }
+
+  /**
+   * Check if a file exists.
+   */
+  async exists(filePath) {
+    return fs.pathExists(this._abs(filePath));
+  }
+
+  /**
+   * Delete a file.
+   */
+  async delete(filePath) {
+    const abs = this._abs(filePath);
+    if (await fs.pathExists(abs)) {
+      await fs.remove(abs);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Delete a directory and all its contents.
+   */
+  async deleteDirectory(dirPath) {
+    await fs.remove(this._abs(dirPath));
+    return true;
+  }
+
+  /**
+   * Copy a file within storage.
+   */
+  async copy(from, to) {
+    await fs.ensureDir(path.dirname(this._abs(to)));
+    await fs.copy(this._abs(from), this._abs(to));
+    return to;
+  }
+
+  /**
+   * Move a file within storage.
+   */
+  async move(from, to) {
+    await fs.ensureDir(path.dirname(this._abs(to)));
+    await fs.move(this._abs(from), this._abs(to), { overwrite: true });
+    return to;
+  }
+
+  /**
+   * List all files in a directory.
+   */
+  async files(dirPath = '') {
+    const abs = this._abs(dirPath);
+    if (!(await fs.pathExists(abs))) return [];
+    const entries = await fs.readdir(abs, { withFileTypes: true });
+    return entries
+      .filter(e => e.isFile())
+      .map(e => path.join(dirPath, e.name).replace(/\\/g, '/'));
+  }
+
+  /**
+   * List all files recursively.
+   */
+  async allFiles(dirPath = '') {
+    const abs = this._abs(dirPath);
+    if (!(await fs.pathExists(abs))) return [];
+    return this._walk(abs, dirPath);
+  }
+
+  /**
+   * List all directories.
+   */
+  async directories(dirPath = '') {
+    const abs = this._abs(dirPath);
+    if (!(await fs.pathExists(abs))) return [];
+    const entries = await fs.readdir(abs, { withFileTypes: true });
+    return entries
+      .filter(e => e.isDirectory())
+      .map(e => path.join(dirPath, e.name).replace(/\\/g, '/'));
+  }
+
+  /**
+   * Create a directory.
+   */
+  async makeDirectory(dirPath) {
+    await fs.ensureDir(this._abs(dirPath));
+    return true;
+  }
+
+  /**
+   * Get file metadata.
+   */
+  async metadata(filePath) {
+    const abs  = this._abs(filePath);
+    const stat = await fs.stat(abs);
+    return {
+      path:     filePath,
+      size:     stat.size,
+      mimeType: this._mime(filePath),
+      lastModified: stat.mtime,
+    };
+  }
+
+  /**
+   * Get the public URL for a file.
+   */
+  url(filePath) {
+    return `${this._baseUrl}/${filePath}`.replace(/\/+/g, '/');
+  }
+
+  /**
+   * Get the absolute filesystem path.
+   */
+  path(filePath) {
+    return this._abs(filePath);
+  }
+
+  /**
+   * Stream a file to an Express response.
+   */
+  stream(filePath, res, options = {}) {
+    const abs = this._abs(filePath);
+    if (options.download) {
+      res.download(abs, path.basename(filePath));
+    } else {
+      res.sendFile(abs);
+    }
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  _abs(filePath) {
+    return path.join(this._root, filePath || '');
+  }
+
+  async _walk(absDir, relDir) {
+    const entries = await fs.readdir(absDir, { withFileTypes: true });
+    const files   = [];
+    for (const e of entries) {
+      const relPath = path.join(relDir, e.name).replace(/\\/g, '/');
+      if (e.isDirectory()) {
+        files.push(...await this._walk(path.join(absDir, e.name), relPath));
+      } else {
+        files.push(relPath);
+      }
+    }
+    return files;
+  }
+
+  _mime(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const types = {
+      '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+      '.gif': 'image/gif',  '.webp': 'image/webp', '.svg': 'image/svg+xml',
+      '.pdf': 'application/pdf', '.txt': 'text/plain',
+      '.html': 'text/html',      '.css': 'text/css',
+      '.js':   'application/javascript',
+      '.json': 'application/json',
+      '.zip':  'application/zip',
+      '.mp4':  'video/mp4',      '.mp3': 'audio/mpeg',
+    };
+    return types[ext] || 'application/octet-stream';
+  }
+}
+
+module.exports = LocalDriver;

package/src/storage/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const Storage     = require('./Storage');
+const LocalDriver = require('./drivers/LocalDriver');
+
+module.exports = { Storage, LocalDriver };