@eik/sink-gcs 1.2.31 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [2.0.0](https://github.com/eik-lib/sink-gcs/compare/v1.2.32...v2.0.0) (2024-11-15)
+
+
+### Bug Fixes
+
+* update dependencies ([#280](https://github.com/eik-lib/sink-gcs/issues/280)) ([8f2568a](https://github.com/eik-lib/sink-gcs/commit/8f2568aede7dd77e827cec575feb5b6f38070725))
+
+
+### BREAKING CHANGES
+
+* Requires Node >=20.5.0
+
+## [1.2.32](https://github.com/eik-lib/sink-gcs/compare/v1.2.31...v1.2.32) (2024-08-09)
+
+
+### Bug Fixes
+
+* add type definitions ([a24ea1e](https://github.com/eik-lib/sink-gcs/commit/a24ea1e2ed8d66b0bb4b1c3ef44640adaa56bac0))
+
 ## [1.2.31](https://github.com/eik-lib/sink-gcs/compare/v1.2.30...v1.2.31) (2024-07-03)
 
 

package/README.md

@@ -2,10 +2,6 @@
 
 A sink for writing to and reading from [Google Cloud Storage][gcs].
 
-[![Dependencies](https://img.shields.io/david/eik-lib/sink-gcs.svg)](https://david-dm.org/eik-lib/sink-gcs)
-[![GitHub Actions status](https://github.com/eik-lib/sink-gcs/workflows/Run%20Lint%20and%20Tests/badge.svg)](https://github.com/eik-lib/sink-gcs/actions?query=workflow%3A%22Run+Lint+and+Tests%22)
-[![Known Vulnerabilities](https://snyk.io/test/github/eik-lib/sink-gcs/badge.svg?targetFile=package.json)](https://snyk.io/test/github/eik-lib/sink-gcs?targetFile=package.json)
-
 The intention of the [Eik][eik] sink modules is to be able to write to and read from
 files in different storage backends by swapping sink modules. Because each sink
 implements the same public API it is possible to use this sink in one environment and
@@ -22,22 +18,25 @@ $ npm install @eik/sink-gcs
 Read a file from [Google Cloud Storage][gcs] and serve it on HTTP:
 
 ```js
-const { pipeline } = require('stream');
-const express = require("express");
-const Sink = require("@eik/sink-gcs");
+import { pipeline } from 'node:stream';
+import express from 'express';
+import Sink from '@eik/sink-gcs';
 
 const app = express();
-const sink = new Sink({
-    credentials: {
-        client_email: 'a@email.address',
-        private_key: '[ ...snip... ]',
-        projectId: 'myProject',
+const sink = new Sink(
+    {
+        credentials: {
+            client_email: 'a@email.address',
+            private_key: '[ ...snip... ]',
+            projectId: 'myProject',
+        },
     },
-}, {
-    writeTimeout: 20000,
-});
+    {
+        writeTimeout: 20000,
+    },
+);
 
-app.get("/file.js", async (req, res, next) => {
+app.get('/file.js', async (req, res, next) => {
     try {
         const file = await sink.read('/path/to/file/file.js');
         pipeline(file.stream, res, (error) => {
@@ -56,7 +55,7 @@ app.listen(8000);
 Create a new Sink instance.
 
 ```js
-const Sink = require("@eik/sink-gcs");
+import Sink from '@eik/sink-gcs';
 
 const sink = new Sink({
     credentials: {
@@ -71,12 +70,12 @@ const sink = new Sink({
 
 This constructor takes the following arguments:
 
- * `storageOptions` - Object - A Google Cloud Storage [storage options object][gcs-storage-options] - Required.
- * `options` - Object - Other options related to storage and behavior - Optional.
-    * `writeTimeout` - Number - Timeout, in milliseconds, for write operations to the sink - Default: `60000` - Optional.
-    * `writeGzip` - Boolean - If files should be written with gzip compression - Default: `false` - Optional.
-    * `rootPath` - String - Root directory for where to store files in the GCS bucket - Default: `eik` - Optional.
-    * `bucket` - String - Name of the bucket to store files in - Default: `eik_files` - Optional.
+-   `storageOptions` - Object - A Google Cloud Storage [storage options object][gcs-storage-options] - Required.
+-   `options` - Object - Other options related to storage and behavior - Optional.
+    -   `writeTimeout` - Number - Timeout, in milliseconds, for write operations to the sink - Default: `60000` - Optional.
+    -   `writeGzip` - Boolean - If files should be written with gzip compression - Default: `false` - Optional.
+    -   `rootPath` - String - Root directory for where to store files in the GCS bucket - Default: `eik` - Optional.
+    -   `bucket` - String - Name of the bucket to store files in - Default: `eik_files` - Optional.
 
 ## API
 
@@ -88,8 +87,8 @@ Async method for writing a file to storage.
 
 This method takes the following arguments:
 
-* `filePath` - String - Path to the file to be stored - Required.
-* `contentType` - String - The content type of the file - Required.
+-   `filePath` - String - Path to the file to be stored - Required.
+-   `contentType` - String - The content type of the file - Required.
 
 Resolves with a writable stream.
 
@@ -115,14 +114,14 @@ Async method for reading a file from storage.
 
 This method takes the following arguments:
 
-* `filePath` - String - Path to the file to be read - Required.
+-   `filePath` - String - Path to the file to be read - Required.
 
 Resolves with a [ReadFile][read-file] object which holds metadata about
 the file and a readable stream with the byte stream of the file on the
 `.stream` property.
 
 ```js
-const { pipeline } = require('stream);
+import { pipeline } from 'node:stream';
 
 const toStream = new SomeWritableStream();
 const sink = new Sink({ ... });
@@ -143,7 +142,7 @@ Async method for deleting a file in storage.
 
 This method takes the following arguments:
 
-* `filePath` - String - Path to the file to be deleted - Required.
+-   `filePath` - String - Path to the file to be deleted - Required.
 
 Resolves if file is deleted and rejects if file could not be deleted.
 
@@ -163,7 +162,7 @@ Async method for checking if a file exist in the storage.
 
 This method takes the following arguments:
 
-* `filePath` - String - Path to the file to be checked for existence - Required.
+-   `filePath` - String - Path to the file to be checked for existence - Required.
 
 Resolves if file exists and rejects if file does not exist.
 
@@ -216,13 +215,13 @@ The stream will emit an event of the following character for each metric:
 
 The metric will have the following labels:
 
- * `operation` - `String` - The operation which triggered the metric. Can be `write`, `read`, `delete` or `exist`.
- * `success` - `Boolean` - If the operation was successfull in terms of being a valid operation and running the operation against the Google Cloud Storage without erroring. 
- * `access` - `Boolean` - If the operation triggered access to the Google Cloud Storage.
+-   `operation` - `String` - The operation which triggered the metric. Can be `write`, `read`, `delete` or `exist`.
+-   `success` - `Boolean` - If the operation was successfull in terms of being a valid operation and running the operation against the Google Cloud Storage without erroring.
+-   `access` - `Boolean` - If the operation triggered access to the Google Cloud Storage.
 
-Do note that the `access` label is `true` when the Sink runs an operation against the 
+Do note that the `access` label is `true` when the Sink runs an operation against the
 Google Cloud Storage which can generate a cost. In other words; this can be used to
-monitor excessive access to prevent cost. 
+monitor excessive access to prevent cost.
 
 ## License
 
@@ -250,4 +249,4 @@ SOFTWARE.
 [gcs-auth]: https://googlecloudplatform.github.io/google-cloud-node/#/docs/google-cloud/0.50.0/google-cloud
 [gcs-storage-options]: https://googleapis.dev/nodejs/storage/latest/global.html#StorageOptions
 [gcs]: https://cloud.google.com/storage/
-[read-file]: https://github.com/eik-lib/common/blob/master/lib/classes/read-file.js
+[read-file]: https://github.com/eik-lib/common/blob/main/lib/classes/read-file.js

package/lib/main.js

@@ -1,216 +1,242 @@
-import { Storage } from '@google-cloud/storage';
-import { ReadFile } from '@eik/common';
-import Metrics from '@metrics/client';
-import Sink from '@eik/sink';
-import path from 'node:path';
+import { Storage } from "@google-cloud/storage";
+import { ReadFile } from "@eik/common";
+import Metrics from "@metrics/client";
+import Sink from "@eik/sink";
+import path from "node:path";
 
-const DEFAULT_ROOT_PATH = 'eik';
-const DEFAULT_BUCKET = 'eik_files';
+const DEFAULT_ROOT_PATH = "eik";
+const DEFAULT_BUCKET = "eik_files";
+
+/**
+ * @typedef {object} SinkGCSOptions
+ * @property {number} [writeTimeout=60_000]
+ * @property {boolean} [writeGzip=false]
+ * @property {string} [rootPath="eik"]
+ * @property {string} [bucket="eik_files"]
+ */
 
 /**
  * A sink for uploading files to Google Cloud Storage
  * https://googleapis.dev/nodejs/storage/latest/
- *
- * @class SinkGCS
  */
-
 const SinkGCS = class SinkGCS extends Sink {
-    constructor(storageOptions, {
-        writeTimeout = 60000,
-        writeGzip = false,
-        rootPath = DEFAULT_ROOT_PATH,
-        bucket = DEFAULT_BUCKET,
-    } = {}) {
-        super();
-        if (typeof storageOptions !== 'object' || storageOptions === null) throw new Error('"storageOptions" argument must be provided');;
-        this._writeTimeout = writeTimeout;
-        this._writeGzip = writeGzip;
-        this._rootPath = rootPath;
-        this._storage = new Storage(storageOptions);
-        this._bucket = this._storage.bucket(bucket);
-        this._metrics = new Metrics();
-        this._counter = this._metrics.counter({
-            name: 'eik_core_sink_gcs',
-            description: 'Counter measuring access to the Google Cloud Storage sink',
-            labels: {
-                operation: 'n/a',
-                success: false,
-                access: false,
-            },
-        });
-    }
-
-    get metrics() {
-        return this._metrics;
-    }
-
-    write(filePath, contentType) {
-        return new Promise((resolve, reject) => {
-            const operation = 'write';
-
-            try {
-                super.constructor.validateFilePath(filePath);
-                super.constructor.validateContentType(contentType);
-            } catch (error) {
-                this._counter.inc({ labels: { operation } });
-                reject(error);
-                return;
-            }
-
-            const pathname = path.join(this._rootPath, filePath);
-
-            if (pathname.indexOf(this._rootPath) !== 0) {
-                this._counter.inc({ labels: { operation } });
-                reject(new Error(`Directory traversal - ${filePath}`));
-                return;
-            }
-
-            const src = this._bucket.file(pathname);
-            const gcsStream = src.createWriteStream({
-                resumable: false,
-                metadata: {
-                    cacheControl: 'public, max-age=31536000',
-                    contentType,
-                },
-                timeout: this._writeTimeout,
-                gzip: this._writeGzip,
-            });
-
-            gcsStream.on('error', () => {
-                this._counter.inc({ labels: { access: true, operation } });
-            });
-
-            gcsStream.on('finish', () => {
-                this._counter.inc({ labels: { success: true, access: true, operation } });
-            });
-
-            resolve(gcsStream);
-        });
-    }
-
-    read(filePath) {
-        return new Promise((resolve, reject) => {
-            const operation = 'read';
-
-            try {
-                super.constructor.validateFilePath(filePath);
-            } catch (error) {
-                this._counter.inc({ labels: { operation } });
-                reject(error);
-                return;
-            }
-
-            const pathname = path.join(this._rootPath, filePath);
-
-            if (pathname.indexOf(this._rootPath) !== 0) {
-                this._counter.inc({ labels: { operation } });
-                reject(new Error(`Directory traversal - ${filePath}`));
-                return;
-            }
-
-            let streamClosed = true;
-
-            const src = this._bucket.file(pathname);
-            const gcsStream = src.createReadStream();
-
-            gcsStream.on('readable', () => {
-                gcsStream.read();
-            });
-
-            gcsStream.on('error', error => {
-                if (streamClosed) {
-                    this._counter.inc({ labels: { access: true, operation } });
-                    reject(error);
-                }
-            });
-
-            gcsStream.on('response', response => {
-                this._counter.inc({ labels: { success: true, access: true, operation } });
-
-                if (response.statusCode === 200) {
-                    streamClosed = false;
-                    const obj = new ReadFile({
-                        mimeType: response.headers['content-type'],
-                        etag: response.headers.etag,
-                    });
-                    obj.stream = gcsStream;
-                    resolve(obj);
-                } else {
-                    reject(new Error(`Could not read file. Got http status code ${response.statusCode} from GCS`));
-                }
-            });
-        });
-    }
-
-    delete(filePath) {
-        return new Promise((resolve, reject) => {
-            const operation = 'delete';
-
-            try {
-                super.constructor.validateFilePath(filePath);
-            } catch (error) {
-                this._counter.inc({ labels: { operation } });
-                reject(error);
-                return;
-            }
-
-            const pathname = path.join(this._rootPath, filePath);
-
-            if (pathname.indexOf(this._rootPath) !== 0) {
-                this._counter.inc({ labels: { operation } });
-                reject(new Error(`Directory traversal - ${filePath}`));
-                return;
-            }
-
-            this._counter.inc({ labels: { success: true, access: true, operation } });
-
-            this._bucket.deleteFiles(
-                {
-                    prefix: pathname,
-                    force: true,
-                },
-                error => {
-                    if (error) return reject(error);
-                    return resolve();
-                },
-            );
-        });
-    }
-
-    exist(filePath) {
-        return new Promise((resolve, reject) => {
-            const operation = 'exist';
-
-            try {
-                super.constructor.validateFilePath(filePath);
-            } catch (error) {
-                this._counter.inc({ labels: { operation } });
-                reject(error);
-                return;
-            }
-
-            const pathname = path.join(this._rootPath, filePath);
-
-            if (pathname.indexOf(this._rootPath) !== 0) {
-                this._counter.inc({ labels: { operation } });
-                reject(new Error(`Directory traversal - ${filePath}`));
-                return;
-            }
-
-            this._counter.inc({ labels: { success: true, access: true, operation } });
-
-            const src = this._bucket.file(pathname);
-
-            src.exists((error, exists) => {
-                if (error) return reject(error);
-                if (exists) return resolve();
-                return reject();
-            });
-        });
-    }
-
-    get [Symbol.toStringTag]() {
-        return 'SinkGCS';
-    }
+	/**
+	 *
+	 * @param {import('@google-cloud/storage').StorageOptions} storageOptions
+	 * @param {SinkGCSOptions} sinkOptions
+	 */
+	constructor(
+		storageOptions,
+		{
+			writeTimeout = 60000,
+			writeGzip = false,
+			rootPath = DEFAULT_ROOT_PATH,
+			bucket = DEFAULT_BUCKET,
+		} = {},
+	) {
+		super();
+		if (typeof storageOptions !== "object" || storageOptions === null)
+			throw new Error('"storageOptions" argument must be provided');
+		this._writeTimeout = writeTimeout;
+		this._writeGzip = writeGzip;
+		this._rootPath = rootPath;
+		this._storage = new Storage(storageOptions);
+		this._bucket = this._storage.bucket(bucket);
+		this._metrics = new Metrics();
+		this._counter = this._metrics.counter({
+			name: "eik_core_sink_gcs",
+			description: "Counter measuring access to the Google Cloud Storage sink",
+			labels: {
+				operation: "n/a",
+				success: false,
+				access: false,
+			},
+		});
+	}
+
+	get metrics() {
+		return this._metrics;
+	}
+
+	write(filePath, contentType) {
+		return new Promise((resolve, reject) => {
+			const operation = "write";
+
+			try {
+				Sink.validateFilePath(filePath);
+				Sink.validateContentType(contentType);
+			} catch (error) {
+				this._counter.inc({ labels: { operation } });
+				reject(error);
+				return;
+			}
+
+			const pathname = path.join(this._rootPath, filePath);
+
+			if (pathname.indexOf(this._rootPath) !== 0) {
+				this._counter.inc({ labels: { operation } });
+				reject(new Error(`Directory traversal - ${filePath}`));
+				return;
+			}
+
+			const src = this._bucket.file(pathname);
+			const gcsStream = src.createWriteStream({
+				resumable: false,
+				metadata: {
+					cacheControl: "public, max-age=31536000",
+					contentType,
+				},
+				timeout: this._writeTimeout,
+				gzip: this._writeGzip,
+			});
+
+			gcsStream.on("error", () => {
+				this._counter.inc({ labels: { access: true, operation } });
+			});
+
+			gcsStream.on("finish", () => {
+				this._counter.inc({
+					labels: { success: true, access: true, operation },
+				});
+			});
+
+			resolve(gcsStream);
+		});
+	}
+
+	read(filePath) {
+		return new Promise((resolve, reject) => {
+			const operation = "read";
+
+			try {
+				Sink.validateFilePath(filePath);
+			} catch (error) {
+				this._counter.inc({ labels: { operation } });
+				reject(error);
+				return;
+			}
+
+			const pathname = path.join(this._rootPath, filePath);
+
+			if (pathname.indexOf(this._rootPath) !== 0) {
+				this._counter.inc({ labels: { operation } });
+				reject(new Error(`Directory traversal - ${filePath}`));
+				return;
+			}
+
+			let streamClosed = true;
+
+			const src = this._bucket.file(pathname);
+			const gcsStream = src.createReadStream();
+
+			gcsStream.on("readable", () => {
+				gcsStream.read();
+			});
+
+			gcsStream.on("error", (error) => {
+				if (streamClosed) {
+					this._counter.inc({ labels: { access: true, operation } });
+					reject(error);
+				}
+			});
+
+			gcsStream.on("response", (response) => {
+				this._counter.inc({
+					labels: { success: true, access: true, operation },
+				});
+
+				if (response.statusCode === 200) {
+					streamClosed = false;
+					const obj = new ReadFile({
+						mimeType: response.headers["content-type"],
+						etag: response.headers.etag,
+					});
+					obj.stream = gcsStream;
+					resolve(obj);
+				} else {
+					reject(
+						new Error(
+							`Could not read file. Got http status code ${response.statusCode} from GCS`,
+						),
+					);
+				}
+			});
+		});
+	}
+
+	delete(filePath) {
+		return new Promise((resolve, reject) => {
+			const operation = "delete";
+
+			try {
+				Sink.validateFilePath(filePath);
+			} catch (error) {
+				this._counter.inc({ labels: { operation } });
+				reject(error);
+				return;
+			}
+
+			const pathname = path.join(this._rootPath, filePath);
+
+			if (pathname.indexOf(this._rootPath) !== 0) {
+				this._counter.inc({ labels: { operation } });
+				reject(new Error(`Directory traversal - ${filePath}`));
+				return;
+			}
+
+			this._counter.inc({
+				labels: { success: true, access: true, operation },
+			});
+
+			this._bucket.deleteFiles(
+				{
+					prefix: pathname,
+					force: true,
+				},
+				(error) => {
+					if (error) return reject(error);
+					return resolve();
+				},
+			);
+		});
+	}
+
+	exist(filePath) {
+		return new Promise((resolve, reject) => {
+			const operation = "exist";
+
+			try {
+				Sink.validateFilePath(filePath);
+			} catch (error) {
+				this._counter.inc({ labels: { operation } });
+				reject(error);
+				return;
+			}
+
+			const pathname = path.join(this._rootPath, filePath);
+
+			if (pathname.indexOf(this._rootPath) !== 0) {
+				this._counter.inc({ labels: { operation } });
+				reject(new Error(`Directory traversal - ${filePath}`));
+				return;
+			}
+
+			this._counter.inc({
+				labels: { success: true, access: true, operation },
+			});
+
+			const src = this._bucket.file(pathname);
+
+			src.exists((error, exists) => {
+				if (error) return reject(error);
+				if (exists) return resolve();
+				return reject();
+			});
+		});
+	}
+
+	get [Symbol.toStringTag]() {
+		return "SinkGCS";
+	}
 };
 export default SinkGCS;

package/package.json

@@ -1,20 +1,26 @@
 {
   "name": "@eik/sink-gcs",
-  "version": "1.2.31",
+  "version": "2.0.0",
   "description": "Sink for Google Cloud Storage",
   "main": "lib/main.js",
+  "types": "./types/main.d.ts",
   "type": "module",
   "files": [
     "CHANGELOG.md",
     "package.json",
     "README.md",
-    "lib"
+    "lib",
+    "types"
   ],
   "scripts": {
+    "clean": "rimraf .tap node_modules types",
     "test": "tap --disable-coverage --allow-empty-coverage",
-    "test:snapshots:update": "tap test/**/*.js --snapshot",
+    "test:snapshots": "tap test/**/*.js --snapshot",
     "lint:fix": "eslint --fix .",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "types": "run-s types:module types:test",
+    "types:module": "tsc",
+    "types:test": "tsc --project tsconfig.test.json"
   },
   "repository": {
     "type": "git",
@@ -27,23 +33,24 @@
   },
   "homepage": "https://github.com/eik-lib/sink-gcs#readme",
   "dependencies": {
-    "@eik/common": "3.0.1",
-    "@eik/sink": "1.2.1",
+    "@eik/common": "5.0.0",
+    "@eik/sink": "1.2.5",
     "@google-cloud/storage": "6.12.0",
-    "@metrics/client": "^2.5.0"
+    "@metrics/client": "2.5.4"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "7.24.7",
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/git": "10.0.1",
-    "eslint": "8.57.0",
-    "eslint-config-airbnb-base": "15.0.0",
-    "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-prettier": "5.1.3",
-    "prettier": "3.3.2",
-    "semantic-release": "23.1.1",
-    "tap": "18.8.0",
-    "unique-slug": "2.0.2"
+    "@eik/eslint-config": "1.0.2",
+    "@eik/prettier-config": "1.0.1",
+    "@eik/semantic-release-config": "1.0.0",
+    "@eik/typescript-config": "1.0.0",
+    "@types/readable-stream": "4.0.18",
+    "eslint": "9.14.0",
+    "npm-run-all2": "7.0.1",
+    "prettier": "3.3.3",
+    "rimraf": "6.0.1",
+    "semantic-release": "24.2.0",
+    "tap": "21.0.1",
+    "typescript": "5.6.3",
+    "unique-slug": "5.0.0"
   }
 }

package/types/main.d.ts

@@ -0,0 +1,39 @@
+export default SinkGCS;
+export type SinkGCSOptions = {
+    writeTimeout?: number;
+    writeGzip?: boolean;
+    rootPath?: string;
+    bucket?: string;
+};
+/**
+ * @typedef {object} SinkGCSOptions
+ * @property {number} [writeTimeout=60_000]
+ * @property {boolean} [writeGzip=false]
+ * @property {string} [rootPath="eik"]
+ * @property {string} [bucket="eik_files"]
+ */
+/**
+ * A sink for uploading files to Google Cloud Storage
+ * https://googleapis.dev/nodejs/storage/latest/
+ */
+declare const SinkGCS: {
+    new (storageOptions: import("@google-cloud/storage").StorageOptions, { writeTimeout, writeGzip, rootPath, bucket, }?: SinkGCSOptions): {
+        _writeTimeout: number;
+        _writeGzip: boolean;
+        _rootPath: string;
+        _storage: Storage;
+        _bucket: import("@google-cloud/storage").Bucket;
+        _metrics: Metrics;
+        _counter: Metrics.MetricsCounter;
+        readonly metrics: Metrics;
+        write(filePath: any, contentType: any): Promise<any>;
+        read(filePath: any): Promise<any>;
+        delete(filePath: any): Promise<any>;
+        exist(filePath: any): Promise<any>;
+        readonly [Symbol.toStringTag]: string;
+    };
+    validateFilePath(filePath: string): string;
+    validateContentType(contentType: string): string;
+};
+import { Storage } from "@google-cloud/storage";
+import Metrics from "@metrics/client";