@basaltkit/storage-gcs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize 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,37 @@
+# @basaltkit/storage-gcs
+
+**Google Cloud Storage** driver for [`@basaltkit/storage`](https://www.npmjs.com/package/@basaltkit/storage): stores files on GCS without changing your app's code. You need this module when you run on Google Cloud and want GCS instead of S3 or local disk.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/storage-gcs @google-cloud/storage
+```
+
+`@google-cloud/storage` is a **peer dependency**. Credentials follow GCP's standard chain (ADC, `keyFilename`, service account).
+
+## Usage
+
+```ts
+import { storagePlugin } from '@basaltkit/storage'
+import { GcsStorageDriver } from '@basaltkit/storage-gcs'
+
+storagePlugin({
+  disks: { uploads: { driver: new GcsStorageDriver({ bucket: 'my-bucket', projectId: 'my-project' }) } },
+})
+```
+
+Implements the `StorageDriver` contract — `put`, `get`, `exists`, `delete`, `list`, and **signed URLs** (`temporaryUrl`). Like all Basalt disks, per-tenant isolation is automatic via `Disk`.
+
+## Testable without the cloud
+
+The client (bucket) is **injectable**, so the driver's logic can be tested with a fake — no GCS required:
+
+```ts
+new GcsStorageDriver({ bucket: 'b', client: fakeBucket })
+```
+
+## How it connects to other modules
+
+- **`@basaltkit/storage`** — this is a driver for that package; the API (`Disk`, `storagePlugin`) comes from there.
+- Sibling drivers: `S3StorageDriver` (in core) and [`@basaltkit/storage-azure`](https://www.npmjs.com/package/@basaltkit/storage-azure).

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { StorageDriver, PutOptions } from '@basaltkit/storage';
+
+/** The subset of a `@google-cloud/storage` File this driver uses. */
+interface GcsFileLike {
+    save(data: Buffer, options?: {
+        contentType?: string;
+    }): Promise<unknown>;
+    download(): Promise<[Buffer]>;
+    exists(): Promise<[boolean]>;
+    delete(): Promise<unknown>;
+    getSignedUrl(config: {
+        action: 'read';
+        expires: number;
+    }): Promise<[string]>;
+}
+/** The subset of a `@google-cloud/storage` Bucket this driver uses. */
+interface GcsBucketLike {
+    file(path: string): GcsFileLike;
+    getFiles(options?: {
+        prefix?: string;
+    }): Promise<[{
+        name: string;
+    }[]]>;
+}
+interface GcsDriverOptions {
+    bucket: string;
+    projectId?: string;
+    keyFilename?: string;
+    /** Injectable bucket — defaults to `@google-cloud/storage`. Tests pass a fake. */
+    client?: GcsBucketLike;
+}
+/**
+ * Google Cloud Storage driver for `@basaltkit/storage`. Uses
+ * `@google-cloud/storage` (an optional peer dependency) via an injectable
+ * bucket, so its logic is unit-tested without touching GCS.
+ */
+declare class GcsStorageDriver implements StorageDriver {
+    private readonly options;
+    readonly name = "gcs";
+    private bucketPromise;
+    constructor(options: GcsDriverOptions);
+    put(path: string, content: Buffer | string, options?: PutOptions): Promise<void>;
+    get(path: string): Promise<Buffer>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<boolean>;
+    list(prefix: string): Promise<string[]>;
+    temporaryUrl(path: string, expiresInMs: number): Promise<string>;
+    disconnect(): Promise<void>;
+    private bucket;
+}
+
+export { type GcsBucketLike, type GcsDriverOptions, type GcsFileLike, GcsStorageDriver };

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/index.ts
+import { StorageFileNotFoundError } from "@basaltkit/storage";
+var isNotFound = (error) => error?.code === 404;
+var GcsStorageDriver = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  name = "gcs";
+  bucketPromise;
+  async put(path, content, options) {
+    const data = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    await (await this.bucket()).file(path).save(data, options?.contentType !== void 0 ? { contentType: options.contentType } : {});
+  }
+  async get(path) {
+    try {
+      const [buffer] = await (await this.bucket()).file(path).download();
+      return buffer;
+    } catch (error) {
+      if (isNotFound(error)) throw new StorageFileNotFoundError(path);
+      throw error;
+    }
+  }
+  async exists(path) {
+    const [exists] = await (await this.bucket()).file(path).exists();
+    return exists;
+  }
+  async delete(path) {
+    if (!await this.exists(path)) return false;
+    await (await this.bucket()).file(path).delete();
+    return true;
+  }
+  async list(prefix) {
+    const [files] = await (await this.bucket()).getFiles({ prefix });
+    return files.map((file) => file.name);
+  }
+  async temporaryUrl(path, expiresInMs) {
+    const [url] = await (await this.bucket()).file(path).getSignedUrl({ action: "read", expires: Date.now() + expiresInMs });
+    return url;
+  }
+  async disconnect() {
+  }
+  bucket() {
+    if (!this.bucketPromise) {
+      this.bucketPromise = this.options.client ? Promise.resolve(this.options.client) : (async () => {
+        const specifier = "@google-cloud/storage";
+        const mod = await import(specifier);
+        const storage = new mod.Storage({
+          ...this.options.projectId ? { projectId: this.options.projectId } : {},
+          ...this.options.keyFilename ? { keyFilename: this.options.keyFilename } : {}
+        });
+        return storage.bucket(this.options.bucket);
+      })();
+    }
+    return this.bucketPromise;
+  }
+};
+export {
+  GcsStorageDriver
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@basaltkit/storage-gcs",
+  "version": "1.0.0",
+  "description": "Google Cloud Storage driver for @basaltkit/storage — put/get/list/delete/signed URLs over @google-cloud/storage, with an injectable client for testing.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/storage": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@google-cloud/storage": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/storage-gcs"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/storage-gcs#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "storage",
+    "gcs",
+    "google-cloud"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}