@wild-framework/storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+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,26 @@
+# @wild-framework/storage
+
+File storage abstraction for [Wild Framework](https://github.com/your-org/wild-framework).
+
+## Install
+
+```bash
+pnpm add @wild-framework/storage
+```
+
+## Usage
+
+```ts
+import { Storage } from "@wild-framework/storage";
+
+await storage.put("avatars/photo.jpg", buffer);
+const contents = await storage.get("avatars/photo.jpg");
+await storage.exists("avatars/photo.jpg");
+await storage.delete("avatars/photo.jpg");
+```
+
+Ships with a local filesystem driver. Implement `StorageDriver` for S3/GCS.
+
+## License
+
+MIT

package/dist/driver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Storage driver contract.
+ *
+ * Implement this to add backends (Local, S3, GCS, etc.).
+ * App code depends on `Storage`, never on a driver directly.
+ */
+export interface StorageDriver {
+    /** Store a file at the given path. Returns the stored path. */
+    put(path: string, contents: Buffer | string): Promise<string>;
+    /** Read a file's contents. */
+    get(path: string): Promise<Buffer>;
+    /** Delete a file. */
+    delete(path: string): Promise<void>;
+    /** Check whether a file exists. */
+    exists(path: string): Promise<boolean>;
+    /** Get a public URL for a file. */
+    url(path: string): Promise<string>;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,+DAA+D;IAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,8BAA8B;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,qBAAqB;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,mCAAmC;IACnC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC"}

package/dist/driver.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Storage } from "./storage.js";
+export { StorageProvider } from "./provider.js";
+export { LocalStorageDriver } from "./local-driver.js";
+export type { StorageDriver } from "./driver.js";
+//# 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,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Storage } from "./storage.js";
+export { StorageProvider } from "./provider.js";
+export { LocalStorageDriver } from "./local-driver.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/local-driver.d.ts

@@ -0,0 +1,17 @@
+import type { StorageDriver } from "./driver.js";
+/**
+ * Filesystem-backed storage driver.
+ *
+ * Files are stored under a base directory on the local filesystem.
+ */
+export declare class LocalStorageDriver implements StorageDriver {
+    private basePath;
+    constructor(basePath: string);
+    put(filePath: string, contents: Buffer | string): Promise<string>;
+    get(filePath: string): Promise<Buffer>;
+    delete(filePath: string): Promise<void>;
+    exists(filePath: string): Promise<boolean>;
+    url(filePath: string): Promise<string>;
+    private resolve;
+}
+//# sourceMappingURL=local-driver.d.ts.map

package/dist/local-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-driver.d.ts","sourceRoot":"","sources":["../src/local-driver.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACxC,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAM9B,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKtC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK5C,OAAO,CAAC,OAAO;CAWlB"}

package/dist/local-driver.js

@@ -0,0 +1,54 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * Filesystem-backed storage driver.
+ *
+ * Files are stored under a base directory on the local filesystem.
+ */
+export class LocalStorageDriver {
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath;
+        if (!basePath) {
+            throw new Error("LocalStorageDriver requires a base path.");
+        }
+    }
+    async put(filePath, contents) {
+        const absolute = this.resolve(filePath);
+        await fs.mkdir(path.dirname(absolute), { recursive: true });
+        await fs.writeFile(absolute, contents);
+        return filePath;
+    }
+    async get(filePath) {
+        const absolute = this.resolve(filePath);
+        return fs.readFile(absolute);
+    }
+    async delete(filePath) {
+        const absolute = this.resolve(filePath);
+        await fs.unlink(absolute);
+    }
+    async exists(filePath) {
+        const absolute = this.resolve(filePath);
+        try {
+            await fs.access(absolute);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async url(filePath) {
+        // Local files don't have a public URL — return the path.
+        return filePath;
+    }
+    resolve(filePath) {
+        const base = path.resolve(this.basePath);
+        const resolved = path.resolve(base, filePath);
+        // Prevent path traversal outside the base directory
+        if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+            throw new Error(`Path "${filePath}" escapes the storage base directory.`);
+        }
+        return resolved;
+    }
+}
+//# sourceMappingURL=local-driver.js.map

package/dist/local-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-driver.js","sourceRoot":"","sources":["../src/local-driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IACP;IAApB,YAAoB,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;QAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAChE,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,QAAyB;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACvC,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxC,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC;YACD,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,IAAI,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB;QACtB,yDAAyD;QACzD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,OAAO,CAAC,QAAgB;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAE9C,oDAAoD;QACpD,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,SAAS,QAAQ,uCAAuC,CAAC,CAAC;QAC9E,CAAC;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;CACJ"}

package/dist/provider.d.ts

@@ -0,0 +1,12 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers the file storage with the application.
+ *
+ * Binds a `Storage` backed by the local filesystem driver.
+ * Swap drivers by implementing `StorageDriver` and binding a new
+ * `Storage` — app code never changes.
+ */
+export declare class StorageProvider implements Provider {
+    register(app: Application): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKlE;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC5C,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;CAKnC"}

package/dist/provider.js

@@ -0,0 +1,18 @@
+import { Container } from "@wild-framework/container";
+import { Storage } from "./storage.js";
+import { LocalStorageDriver } from "./local-driver.js";
+/**
+ * Registers the file storage with the application.
+ *
+ * Binds a `Storage` backed by the local filesystem driver.
+ * Swap drivers by implementing `StorageDriver` and binding a new
+ * `Storage` — app code never changes.
+ */
+export class StorageProvider {
+    register(app) {
+        const container = app.resolve(Container);
+        const storage = new Storage(new LocalStorageDriver("./storage"));
+        container.singleton(Storage, () => storage);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IACxB,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC;QACjE,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACJ"}

package/dist/storage.d.ts

@@ -0,0 +1,22 @@
+import type { StorageDriver } from "./driver.js";
+/**
+ * File storage facade.
+ *
+ * Wraps a `StorageDriver` and exposes a consistent API.
+ * Resolved from the container: `app.resolve(Storage)`.
+ */
+export declare class Storage {
+    private driver;
+    constructor(driver: StorageDriver);
+    /** Store a file at the given path. Returns the stored path. */
+    put(path: string, contents: Buffer | string): Promise<string>;
+    /** Read a file's contents. */
+    get(path: string): Promise<Buffer>;
+    /** Delete a file. */
+    delete(path: string): Promise<void>;
+    /** Check whether a file exists. */
+    exists(path: string): Promise<boolean>;
+    /** Get a public URL for a file. */
+    url(path: string): Promise<string>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;GAKG;AACH,qBAAa,OAAO;IACJ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEzC,+DAA+D;IAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7D,8BAA8B;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlC,qBAAqB;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInC,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,mCAAmC;IACnC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGrC"}

package/dist/storage.js

@@ -0,0 +1,33 @@
+/**
+ * File storage facade.
+ *
+ * Wraps a `StorageDriver` and exposes a consistent API.
+ * Resolved from the container: `app.resolve(Storage)`.
+ */
+export class Storage {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /** Store a file at the given path. Returns the stored path. */
+    put(path, contents) {
+        return this.driver.put(path, contents);
+    }
+    /** Read a file's contents. */
+    get(path) {
+        return this.driver.get(path);
+    }
+    /** Delete a file. */
+    delete(path) {
+        return this.driver.delete(path);
+    }
+    /** Check whether a file exists. */
+    exists(path) {
+        return this.driver.exists(path);
+    }
+    /** Get a public URL for a file. */
+    url(path) {
+        return this.driver.url(path);
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,OAAO;IACI;IAApB,YAAoB,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAE7C,+DAA+D;IAC/D,GAAG,CAAC,IAAY,EAAE,QAAyB;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,8BAA8B;IAC9B,GAAG,CAAC,IAAY;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,qBAAqB;IACrB,MAAM,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,mCAAmC;IACnC,MAAM,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,mCAAmC;IACnC,GAAG,CAAC,IAAY;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;CACJ"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@wild-framework/storage",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "File storage abstraction for Wild Framework.",
+  "keywords": [
+    "wild",
+    "framework",
+    "storage",
+    "files",
+    "s3"
+  ],
+  "dependencies": {
+    "@wild-framework/core": "0.1.0",
+    "@wild-framework/container": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}