@mantiq/filesystem 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/filesystem
+
+Filesystem abstraction for MantiqJS — Local, S3, GCS, Azure Blob, FTP, and SFTP drivers.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/filesystem
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@mantiq/filesystem",
+  "version": "0.0.1",
+  "description": "Filesystem abstraction — local, S3, GCS, R2, Azure, FTP, SFTP drivers with uniform API",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/filesystem",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/filesystem"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "filesystem"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@google-cloud/storage": "^7.0.0",
+    "@azure/storage-blob": "^12.0.0",
+    "basic-ftp": "^5.0.0",
+    "ssh2-sftp-client": "^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@google-cloud/storage": {
+      "optional": true
+    },
+    "@azure/storage-blob": {
+      "optional": true
+    },
+    "basic-ftp": {
+      "optional": true
+    },
+    "ssh2-sftp-client": {
+      "optional": true
+    }
+  }
+}

package/src/FilesystemManager.ts

@@ -0,0 +1,177 @@
+import type { DriverManager } from '@mantiq/core'
+import type { FilesystemDriver, PutOptions } from './contracts/FilesystemDriver.ts'
+import type { FilesystemConfig, DiskConfig } from './contracts/FilesystemConfig.ts'
+import { LocalDriver } from './drivers/LocalDriver.ts'
+import { NullDriver } from './drivers/NullDriver.ts'
+import { S3Driver } from './drivers/S3Driver.ts'
+import { GCSDriver } from './drivers/GCSDriver.ts'
+import { AzureBlobDriver } from './drivers/AzureBlobDriver.ts'
+import { FTPDriver } from './drivers/FTPDriver.ts'
+import { SFTPDriver } from './drivers/SFTPDriver.ts'
+
+export class FilesystemManager implements DriverManager<FilesystemDriver>, FilesystemDriver {
+  private readonly config: FilesystemConfig
+  private readonly disks = new Map<string, FilesystemDriver>()
+  private readonly customCreators = new Map<string, (config: DiskConfig) => FilesystemDriver>()
+
+  constructor(config?: Partial<FilesystemConfig>) {
+    this.config = {
+      default: config?.default ?? 'local',
+      disks: config?.disks ?? {},
+    }
+  }
+
+  // ── DriverManager ─────────────────────────────────────────────────────────
+
+  driver(name?: string): FilesystemDriver {
+    const diskName = name ?? this.getDefaultDriver()
+
+    if (!this.disks.has(diskName)) {
+      this.disks.set(diskName, this.createDriver(diskName))
+    }
+
+    return this.disks.get(diskName)!
+  }
+
+  disk(name?: string): FilesystemDriver {
+    return this.driver(name)
+  }
+
+  extend(name: string, factory: (config: DiskConfig) => FilesystemDriver): void {
+    this.customCreators.set(name, factory)
+  }
+
+  getDefaultDriver(): string {
+    return this.config.default
+  }
+
+  forgetDisk(name: string): void {
+    this.disks.delete(name)
+  }
+
+  forgetDisks(): void {
+    this.disks.clear()
+  }
+
+  // ── FilesystemDriver (delegates to default disk) ──────────────────────────
+
+  exists(path: string) { return this.driver().exists(path) }
+  get(path: string) { return this.driver().get(path) }
+  getBytes(path: string) { return this.driver().getBytes(path) }
+  stream(path: string) { return this.driver().stream(path) }
+
+  put(path: string, contents: string | Uint8Array, options?: PutOptions) { return this.driver().put(path, contents, options) }
+  putStream(path: string, stream: ReadableStream, options?: PutOptions) { return this.driver().putStream(path, stream, options) }
+  append(path: string, contents: string) { return this.driver().append(path, contents) }
+  prepend(path: string, contents: string) { return this.driver().prepend(path, contents) }
+
+  delete(path: string | string[]) { return this.driver().delete(path) }
+  copy(from: string, to: string) { return this.driver().copy(from, to) }
+  move(from: string, to: string) { return this.driver().move(from, to) }
+
+  size(path: string) { return this.driver().size(path) }
+  lastModified(path: string) { return this.driver().lastModified(path) }
+  mimeType(path: string) { return this.driver().mimeType(path) }
+  path(filePath: string) { return this.driver().path(filePath) }
+
+  url(path: string) { return this.driver().url(path) }
+  temporaryUrl(path: string, expiration: number, options?: Record<string, any>) { return this.driver().temporaryUrl(path, expiration, options) }
+
+  files(directory?: string) { return this.driver().files(directory) }
+  allFiles(directory?: string) { return this.driver().allFiles(directory) }
+  directories(directory?: string) { return this.driver().directories(directory) }
+  allDirectories(directory?: string) { return this.driver().allDirectories(directory) }
+  makeDirectory(path: string) { return this.driver().makeDirectory(path) }
+  deleteDirectory(directory: string) { return this.driver().deleteDirectory(directory) }
+
+  setVisibility(path: string, visibility: 'public' | 'private') { return this.driver().setVisibility(path, visibility) }
+  getVisibility(path: string) { return this.driver().getVisibility(path) }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): FilesystemDriver {
+    const diskConfig = this.config.disks[name]
+    const driverName = diskConfig?.driver ?? name
+
+    const custom = this.customCreators.get(driverName)
+    if (custom) return custom(diskConfig ?? { driver: driverName })
+
+    if (!diskConfig) {
+      throw new Error(`Disk "${name}" is not configured. Define it in config/filesystem.ts or use extend().`)
+    }
+
+    switch (driverName) {
+      case 'local':
+        return new LocalDriver(
+          diskConfig.root ?? '/tmp/mantiq-storage',
+          diskConfig.url as string | undefined,
+          (diskConfig.visibility as 'public' | 'private') ?? 'public',
+        )
+      case 'null':
+        return new NullDriver()
+      case 's3':
+      case 'r2':
+      case 'spaces':
+      case 'minio':
+        return new S3Driver({
+          bucket: diskConfig.bucket as string,
+          region: diskConfig.region as string | undefined,
+          key: diskConfig.key as string | undefined,
+          secret: diskConfig.secret as string | undefined,
+          token: diskConfig.token as string | undefined,
+          endpoint: diskConfig.endpoint as string | undefined,
+          forcePathStyle: diskConfig.forcePathStyle as boolean | undefined,
+          root: diskConfig.root,
+          url: diskConfig.url,
+          visibility: diskConfig.visibility,
+        })
+      case 'gcs':
+        return new GCSDriver({
+          bucket: diskConfig.bucket as string,
+          projectId: diskConfig.projectId as string | undefined,
+          keyFilename: diskConfig.keyFilename as string | undefined,
+          credentials: diskConfig.credentials as Record<string, any> | undefined,
+          root: diskConfig.root,
+          url: diskConfig.url,
+          visibility: diskConfig.visibility,
+        })
+      case 'azure':
+        return new AzureBlobDriver({
+          container: diskConfig.container as string,
+          connectionString: diskConfig.connectionString as string | undefined,
+          accountName: diskConfig.accountName as string | undefined,
+          accountKey: diskConfig.accountKey as string | undefined,
+          sasToken: diskConfig.sasToken as string | undefined,
+          root: diskConfig.root,
+          url: diskConfig.url,
+          visibility: diskConfig.visibility,
+        })
+      case 'ftp':
+        return new FTPDriver({
+          host: diskConfig.host as string,
+          port: diskConfig.port as number | undefined,
+          username: diskConfig.username as string | undefined,
+          password: diskConfig.password as string | undefined,
+          secure: diskConfig.secure as boolean | 'implicit' | undefined,
+          timeout: diskConfig.timeout as number | undefined,
+          root: diskConfig.root,
+          url: diskConfig.url,
+          visibility: diskConfig.visibility,
+        })
+      case 'sftp':
+        return new SFTPDriver({
+          host: diskConfig.host as string,
+          port: diskConfig.port as number | undefined,
+          username: diskConfig.username as string | undefined,
+          password: diskConfig.password as string | undefined,
+          privateKey: diskConfig.privateKey as string | undefined,
+          passphrase: diskConfig.passphrase as string | undefined,
+          root: diskConfig.root,
+          url: diskConfig.url,
+          visibility: diskConfig.visibility,
+        })
+      default:
+        throw new Error(`Unsupported filesystem driver: "${driverName}". Use extend() to register custom drivers.`)
+    }
+  }
+}

package/src/FilesystemServiceProvider.ts

@@ -0,0 +1,30 @@
+import { ServiceProvider, ConfigRepository, Application } from '@mantiq/core'
+import { FilesystemManager } from './FilesystemManager.ts'
+import { FILESYSTEM_MANAGER } from './helpers/storage.ts'
+import type { FilesystemConfig } from './contracts/FilesystemConfig.ts'
+
+const DEFAULT_CONFIG: FilesystemConfig = {
+  default: 'local',
+  disks: {
+    local: { driver: 'local', root: 'storage/app' },
+  },
+}
+
+export class FilesystemServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(FilesystemManager, (c) => {
+      const config = c.make(ConfigRepository).get<FilesystemConfig>('filesystem', DEFAULT_CONFIG)
+      const app = c.make(Application)
+
+      // Normalize relative root paths to absolute using the app base path
+      for (const disk of Object.values(config.disks)) {
+        if (disk.root && !disk.root.startsWith('/')) {
+          disk.root = app.basePath_(disk.root)
+        }
+      }
+
+      return new FilesystemManager(config)
+    })
+    this.app.alias(FilesystemManager, FILESYSTEM_MANAGER)
+  }
+}

package/src/contracts/FilesystemConfig.ts

@@ -0,0 +1,60 @@
+export interface DiskConfig {
+  driver: string
+  root?: string
+  url?: string
+  visibility?: 'public' | 'private'
+  [key: string]: unknown
+}
+
+export interface S3DiskConfig extends DiskConfig {
+  driver: 's3'
+  bucket: string
+  region?: string
+  key?: string
+  secret?: string
+  token?: string
+  endpoint?: string
+  forcePathStyle?: boolean
+}
+
+export interface GCSDiskConfig extends DiskConfig {
+  driver: 'gcs'
+  bucket: string
+  projectId?: string
+  keyFilename?: string
+  credentials?: Record<string, any>
+}
+
+export interface AzureDiskConfig extends DiskConfig {
+  driver: 'azure'
+  container: string
+  connectionString?: string
+  accountName?: string
+  accountKey?: string
+  sasToken?: string
+}
+
+export interface FTPDiskConfig extends DiskConfig {
+  driver: 'ftp'
+  host: string
+  port?: number
+  username?: string
+  password?: string
+  secure?: boolean | 'implicit'
+  timeout?: number
+}
+
+export interface SFTPDiskConfig extends DiskConfig {
+  driver: 'sftp'
+  host: string
+  port?: number
+  username?: string
+  password?: string
+  privateKey?: string
+  passphrase?: string
+}
+
+export interface FilesystemConfig {
+  default: string
+  disks: Record<string, DiskConfig>
+}

package/src/contracts/FilesystemDriver.ts

@@ -0,0 +1,45 @@
+export interface PutOptions {
+  visibility?: 'public' | 'private'
+  mimeType?: string
+}
+
+export interface FilesystemDriver {
+  // ── Reads ───────────────────────────────────────────────────────────────────
+  exists(path: string): Promise<boolean>
+  get(path: string): Promise<string | null>
+  getBytes(path: string): Promise<Uint8Array | null>
+  stream(path: string): Promise<ReadableStream | null>
+
+  // ── Writes ──────────────────────────────────────────────────────────────────
+  put(path: string, contents: string | Uint8Array, options?: PutOptions): Promise<void>
+  putStream(path: string, stream: ReadableStream, options?: PutOptions): Promise<void>
+  append(path: string, contents: string): Promise<void>
+  prepend(path: string, contents: string): Promise<void>
+
+  // ── Operations ──────────────────────────────────────────────────────────────
+  delete(path: string | string[]): Promise<boolean>
+  copy(from: string, to: string): Promise<void>
+  move(from: string, to: string): Promise<void>
+
+  // ── Metadata ────────────────────────────────────────────────────────────────
+  size(path: string): Promise<number>
+  lastModified(path: string): Promise<number>
+  mimeType(path: string): Promise<string | null>
+  path(filePath: string): string
+
+  // ── URLs ────────────────────────────────────────────────────────────────────
+  url(path: string): string
+  temporaryUrl(path: string, expiration: number, options?: Record<string, any>): Promise<string>
+
+  // ── Directories ─────────────────────────────────────────────────────────────
+  files(directory?: string): Promise<string[]>
+  allFiles(directory?: string): Promise<string[]>
+  directories(directory?: string): Promise<string[]>
+  allDirectories(directory?: string): Promise<string[]>
+  makeDirectory(path: string): Promise<void>
+  deleteDirectory(directory: string): Promise<boolean>
+
+  // ── Visibility ──────────────────────────────────────────────────────────────
+  setVisibility(path: string, visibility: 'public' | 'private'): Promise<void>
+  getVisibility(path: string): Promise<string>
+}