@wild-framework/storage-auto 0.0.0-stage → 0.2.2

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

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @wild-framework/storage-auto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Env-driven storage provider for [Wild Framework](https://github.com/KhandaSoftware/wild-framework).
+
+## Install
+
+```bash
+pnpm add @wild-framework/storage-auto
+```
+
+## Usage
+
+Register `StorageProvider` and set `STORAGE_DRIVER` to swap backends without touching app code:
+
+```ts
+import { StorageProvider } from "@wild-framework/storage-auto";
+
+app.register(StorageProvider);
+```
+
+| `STORAGE_DRIVER` | Backend | Env vars |
+| ---------------- | ------- | -------- |
+| `s3` / `aws`     | S3      | `AWS_BUCKET`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT`, `AWS_PUBLIC_URL` |
+| `gcs` / `gcp`    | GCS     | `GCS_BUCKET`, `GCS_PROJECT_ID`, `GCS_PUBLIC_URL` (+ `GOOGLE_APPLICATION_CREDENTIALS`) |
+| unset / other    | Local   | `STORAGE_PATH` (default `./storage`) |
+
+## License
+
+MIT

package/dist/classify.d.ts

@@ -0,0 +1,11 @@
+/** Which concrete storage backend a driver name maps to. */
+export type StorageBackend = "s3" | "gcs" | "local";
+/**
+ * Classify a `STORAGE_DRIVER` value.
+ *
+ *   "s3" | "aws"                          → "s3"
+ *   "gcs" | "gcp" | "google"              → "gcs"
+ *   anything else / undefined             → "local"
+ */
+export declare function classifyStorageDriver(driver: string | undefined): StorageBackend;
+//# sourceMappingURL=classify.d.ts.map

package/dist/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,KAAK,GAAG,OAAO,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAKhF"}

package/dist/classify.js

@@ -0,0 +1,16 @@
+/**
+ * Classify a `STORAGE_DRIVER` value.
+ *
+ *   "s3" | "aws"                          → "s3"
+ *   "gcs" | "gcp" | "google"              → "gcs"
+ *   anything else / undefined             → "local"
+ */
+export function classifyStorageDriver(driver) {
+    const d = driver?.trim().toLowerCase();
+    if (d === "s3" || d === "aws")
+        return "s3";
+    if (d === "gcs" || d === "gcp" || d === "google" || d === "google-cloud")
+        return "gcs";
+    return "local";
+}
+//# sourceMappingURL=classify.js.map

package/dist/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA0B;IAC5D,MAAM,CAAC,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,cAAc;QAAE,OAAO,KAAK,CAAC;IACvF,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { StorageProvider } from "./provider.js";
+export { classifyStorageDriver } from "./classify.js";
+export type { StorageBackend } from "./classify.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,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { StorageProvider } from "./provider.js";
+export { classifyStorageDriver } from "./classify.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,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,34 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Unified, env-driven storage provider.
+ *
+ * Selects a concrete driver from `STORAGE_DRIVER` and binds a `Storage`
+ * into the container. This is the "one provider to rule them all" —
+ * register it and set env vars to swap backends without touching app code:
+ *
+ *   STORAGE_DRIVER=s3    → S3    (AWS_BUCKET, AWS_REGION, AWS_ACCESS_KEY_ID, …)
+ *   STORAGE_DRIVER=gcs   → GCS   (GCS_BUCKET, GCS_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS)
+ *   (unset)              → local (STORAGE_PATH, default "./storage")
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * StorageProvider.driver = "s3"; // optional — force a backend
+ * StorageProvider.basePath = "./uploads"; // local only
+ * ```
+ *
+ * The explicit providers (`StorageProvider` from `@wild-framework/storage`,
+ * `S3StorageProvider`, `GcsStorageProvider`) remain available when you want
+ * to be explicit.
+ */
+export declare class StorageProvider implements Provider {
+    /** Force a backend; defaults to `STORAGE_DRIVER` (s3 | gcs | local). */
+    static driver: "s3" | "gcs" | "local" | undefined;
+    /** Local filesystem base path (local backend). Defaults to `STORAGE_PATH` or "./storage". */
+    static basePath: string;
+    private instance;
+    register(app: Application): void;
+    boot(): Promise<void>;
+    shutdown(): Promise<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;AAOlE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC5C,wEAAwE;IACxE,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;IAClD,6FAA6F;IAC7F,MAAM,CAAC,QAAQ,SAAe;IAE9B,OAAO,CAAC,QAAQ,CAAsE;IAEtF,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAwC1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/provider.js

@@ -0,0 +1,79 @@
+import { Container } from "@wild-framework/container";
+import { Storage, LocalStorageDriver } from "@wild-framework/storage";
+import { S3StorageDriver } from "@wild-framework/storage-s3";
+import { GcsStorageDriver } from "@wild-framework/storage-gcs";
+import { classifyStorageDriver } from "./classify.js";
+/**
+ * Unified, env-driven storage provider.
+ *
+ * Selects a concrete driver from `STORAGE_DRIVER` and binds a `Storage`
+ * into the container. This is the "one provider to rule them all" —
+ * register it and set env vars to swap backends without touching app code:
+ *
+ *   STORAGE_DRIVER=s3    → S3    (AWS_BUCKET, AWS_REGION, AWS_ACCESS_KEY_ID, …)
+ *   STORAGE_DRIVER=gcs   → GCS   (GCS_BUCKET, GCS_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS)
+ *   (unset)              → local (STORAGE_PATH, default "./storage")
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * StorageProvider.driver = "s3"; // optional — force a backend
+ * StorageProvider.basePath = "./uploads"; // local only
+ * ```
+ *
+ * The explicit providers (`StorageProvider` from `@wild-framework/storage`,
+ * `S3StorageProvider`, `GcsStorageProvider`) remain available when you want
+ * to be explicit.
+ */
+export class StorageProvider {
+    /** Force a backend; defaults to `STORAGE_DRIVER` (s3 | gcs | local). */
+    static driver;
+    /** Local filesystem base path (local backend). Defaults to `STORAGE_PATH` or "./storage". */
+    static basePath = "./storage";
+    instance;
+    register(app) {
+        const container = app.resolve(Container);
+        const backend = classifyStorageDriver(StorageProvider.driver ?? process.env.STORAGE_DRIVER);
+        let driver;
+        if (backend === "s3") {
+            driver = new S3StorageDriver({
+                bucket: process.env.AWS_BUCKET ?? "",
+                region: process.env.AWS_REGION ?? "",
+                credentials: process.env.AWS_ACCESS_KEY_ID
+                    ? {
+                        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+                        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
+                    }
+                    : undefined,
+                endpoint: process.env.AWS_ENDPOINT,
+                // Custom S3-compatible endpoints (MinIO, s3mock, R2) need
+                // path-style addressing unless they explicitly support
+                // virtual-hosted style.
+                forcePathStyle: process.env.AWS_FORCE_PATH_STYLE === undefined
+                    ? !!process.env.AWS_ENDPOINT
+                    : process.env.AWS_FORCE_PATH_STYLE === "true",
+                publicUrl: process.env.AWS_PUBLIC_URL,
+            });
+        }
+        else if (backend === "gcs") {
+            driver = new GcsStorageDriver({
+                bucket: process.env.GCS_BUCKET ?? "",
+                projectId: process.env.GCS_PROJECT_ID,
+                apiEndpoint: process.env.GCS_ENDPOINT,
+                publicUrl: process.env.GCS_PUBLIC_URL,
+            });
+        }
+        else {
+            driver = new LocalStorageDriver(process.env.STORAGE_PATH ?? StorageProvider.basePath);
+        }
+        this.instance = driver;
+        container.singleton(Storage, () => new Storage(driver));
+    }
+    async boot() {
+        await this.instance?.connect();
+    }
+    async shutdown() {
+        await this.instance?.close();
+    }
+}
+//# 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,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,eAAe;IACxB,wEAAwE;IACxE,MAAM,CAAC,MAAM,CAAqC;IAClD,6FAA6F;IAC7F,MAAM,CAAC,QAAQ,GAAG,WAAW,CAAC;IAEtB,QAAQ,CAAsE;IAEtF,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,qBAAqB,CAAC,eAAe,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAE5F,IAAI,MAA+D,CAAC;QACpE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,MAAM,GAAG,IAAI,eAAe,CAAC;gBACzB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE;gBACpC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE;gBACpC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;oBACtC,CAAC,CAAC;wBACI,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;wBAC1C,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,EAAE;qBAC3D;oBACH,CAAC,CAAC,SAAS;gBACf,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY;gBAClC,0DAA0D;gBAC1D,uDAAuD;gBACvD,wBAAwB;gBACxB,cAAc,EACV,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,SAAS;oBAC1C,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY;oBAC5B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,MAAM;gBACrD,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;aACxC,CAAC,CAAC;QACP,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;YAC3B,MAAM,GAAG,IAAI,gBAAgB,CAAC;gBAC1B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE;gBACpC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;gBACrC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY;gBACrC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;aACxC,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,MAAM,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;QAC1F,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;QACvB,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,IAAI;QACN,MAAM,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,QAAQ;QACV,MAAM,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC;IACjC,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@wild-framework/storage-auto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.2",
+  "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": "Env-driven storage provider — auto-selects local, S3, or GCS from STORAGE_DRIVER.",
+  "keywords": [
+    "wild",
+    "framework",
+    "storage",
+    "files",
+    "s3",
+    "gcs",
+    "local",
+    "auto"
+  ],
+  "dependencies": {
+    "@wild-framework/core": "0.2.2",
+    "@wild-framework/storage": "0.2.2",
+    "@wild-framework/container": "0.2.2",
+    "@wild-framework/storage-s3": "0.2.2",
+    "@wild-framework/storage-gcs": "0.2.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
 }