@nu-art/firebase-backend 0.400.5

package/index.d.ts

@@ -0,0 +1,21 @@
+export * from './auth/firebase-session.js';
+export * from './auth/FirebaseSession_Admin.js';
+export * from './functions/firebase-function.js';
+export * from './ModuleBE_Firebase.js';
+export * from './firestore/FirestoreInterface.js';
+export * from './firestore/FirestoreCollection.js';
+export * from './firestore/FirestoreTransaction.js';
+export * from './firestore/FirestoreWrapperBE.js';
+export * from './firestore/types.js';
+export * from './database/DatabaseWrapperBE.js';
+export * from './storage/types.js';
+export * from './storage/StorageWrapperBE.js';
+export * from './push/PushMessagesWrapperBE.js';
+export * from './push/types.js';
+export * from './functions-v2/ModuleBE_BaseFunction.js';
+export * from './functions-v2/ModuleBE_ExpressFunction_V2.js';
+export * from './functions-v2/ModuleBE_FirebaseDBListener.js';
+export * from './functions-v2/ModuleBE_FirebaseScheduler.js';
+export * from './functions-v2/ModuleBE_FirestoreListener.js';
+export * from './functions-v2/ModuleBE_PubSubFunction.js';
+export * from './functions-v2/ModuleBE_StorageListener.js';

package/index.js

@@ -0,0 +1,38 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './auth/firebase-session.js';
+export * from './auth/FirebaseSession_Admin.js';
+export * from './functions/firebase-function.js';
+export * from './ModuleBE_Firebase.js';
+export * from './firestore/FirestoreInterface.js';
+export * from './firestore/FirestoreCollection.js';
+export * from './firestore/FirestoreTransaction.js';
+export * from './firestore/FirestoreWrapperBE.js';
+export * from './firestore/types.js';
+export * from './database/DatabaseWrapperBE.js';
+export * from './storage/types.js';
+export * from './storage/StorageWrapperBE.js';
+export * from './push/PushMessagesWrapperBE.js';
+export * from './push/types.js';
+export * from './functions-v2/ModuleBE_BaseFunction.js';
+export * from './functions-v2/ModuleBE_ExpressFunction_V2.js';
+export * from './functions-v2/ModuleBE_FirebaseDBListener.js';
+export * from './functions-v2/ModuleBE_FirebaseScheduler.js';
+export * from './functions-v2/ModuleBE_FirestoreListener.js';
+export * from './functions-v2/ModuleBE_PubSubFunction.js';
+export * from './functions-v2/ModuleBE_StorageListener.js';

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@nu-art/firebase-backend",
+  "version": "0.400.5",
+  "description": "Storm - Express & Typescript based backend framework Backend",
+  "keywords": [
+    "TacB0sS",
+    "infra",
+    "nu-art",
+    "storm",
+    "thunderstorm",
+    "typescript"
+  ],
+  "homepage": "https://github.com/nu-art-js/firebase",
+  "bugs": {
+    "url": "https://github.com/nu-art-js/firebase/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:nu-art-js/firebase.git"
+  },
+  "publishConfig": {
+    "directory": "dist",
+    "linkDirectory": true
+  },
+  "license": "Apache-2.0",
+  "author": "TacB0sS",
+  "files": [
+    "**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "run-tests": "firebase emulators:exec \"npm run test\"",
+    "test": "ts-mocha -w -p src/test/tsconfig.json --timeout 0 --inspect=8107 --watch-files '**/*.ts' src/test/firestore-v2/__test.ts",
+    "rtv2": "firebase emulators:exec \"npm run test-v2\"",
+    "test-v2": "ts-mocha -w -p src/test/tsconfig.json --timeout 0 --inspect=8107 --watch-files '**/*.ts' src/test/firestore-v2/__test.ts"
+  },
+  "dependencies": {
+    "@nu-art/firebase-shared": "0.400.5",
+    "@google-cloud/common": "^5.0.2",
+    "@google-cloud/firestore": "^7.11.0",
+    "@google-cloud/storage": "^7.15.0",
+    "@nu-art/google-services-backend": "0.400.5",
+    "@nu-art/ts-common": "0.400.5",
+    "express": "^4.18.2",
+    "firebase": "^11.9.0",
+    "firebase-admin": "13.4.0",
+    "firebase-functions": "6.3.2",
+    "google-auth-library": "^10.0.0",
+    "http-proxy": "1.18.1",
+    "url": "0.11.3",
+    "ws": "^8.13.0"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.0.1",
+    "@types/chai": "^4.3.4",
+    "@types/mocha": "^10.0.1",
+    "@types/http-proxy": "1.17.14",
+    "teeny-request": "~7.2.0",
+    "@types/ws": "^8.5.5"
+  },
+  "unitConfig": {
+    "type": "typescript-lib"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./*": {
+      "types": "./*.d.ts",
+      "import": "./*.js"
+    }
+  }
+}

package/push/PushMessagesWrapperBE.d.ts

@@ -0,0 +1,14 @@
+import { FirebaseType_BatchResponse, FirebaseType_SubscriptionResponse } from './types.js';
+import { FirebaseBaseWrapper } from '../auth/FirebaseBaseWrapper.js';
+import { FirebaseSession } from '../auth/firebase-session.js';
+import { Message, MulticastMessage } from 'firebase-admin/messaging';
+export declare class PushMessagesWrapperBE extends FirebaseBaseWrapper {
+    private readonly messaging;
+    constructor(firebaseSession: FirebaseSession<any>);
+    send(message: Message, dryRun?: boolean): Promise<string>;
+    sendAll(messages: Message[], dryRun?: boolean): Promise<FirebaseType_BatchResponse>;
+    sendMultiCast(messages: MulticastMessage, dryRun?: boolean): Promise<FirebaseType_BatchResponse>;
+    subscribeToTopic(tokens: string[], topic: string): Promise<FirebaseType_SubscriptionResponse>;
+    unsubscribeFromTopic(tokens: string[], topic: string): Promise<FirebaseType_SubscriptionResponse>;
+    isEmulator(): boolean;
+}

package/push/PushMessagesWrapperBE.js

@@ -0,0 +1,44 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { FirebaseBaseWrapper } from '../auth/FirebaseBaseWrapper.js';
+import { getMessaging } from 'firebase-admin/messaging';
+export class PushMessagesWrapperBE extends FirebaseBaseWrapper {
+    messaging;
+    constructor(firebaseSession) {
+        super(firebaseSession);
+        this.messaging = getMessaging(firebaseSession.app);
+    }
+    async send(message, dryRun) {
+        return this.messaging.send(message, dryRun);
+    }
+    async sendAll(messages, dryRun) {
+        return this.messaging.sendEach(messages, dryRun);
+    }
+    async sendMultiCast(messages, dryRun) {
+        return this.messaging.sendEachForMulticast(messages, dryRun);
+    }
+    async subscribeToTopic(tokens, topic) {
+        return this.messaging.subscribeToTopic(tokens, topic);
+    }
+    async unsubscribeFromTopic(tokens, topic) {
+        return this.messaging.unsubscribeFromTopic(tokens, topic);
+    }
+    isEmulator() {
+        return false;
+    }
+}

package/push/types.d.ts

@@ -0,0 +1,3 @@
+import { BatchResponse, MessagingTopicManagementResponse } from 'firebase-admin/messaging';
+export type FirebaseType_BatchResponse = BatchResponse;
+export type FirebaseType_SubscriptionResponse = MessagingTopicManagementResponse;

package/push/types.js

@@ -0,0 +1,18 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/storage/StorageWrapperBE.d.ts

@@ -0,0 +1,63 @@
+import { Bucket, CreateReadStreamOptions, CreateWriteStreamOptions, File, FileMetadata, MakeFilePublicResponse } from '@google-cloud/storage';
+import { FirebaseSession } from '../auth/firebase-session.js';
+import { FirebaseBaseWrapper } from '../auth/FirebaseBaseWrapper.js';
+import { Response } from 'teeny-request';
+import { Writable } from 'stream';
+export declare const END_OF_STREAM: {
+    END_OF_STREAM: string;
+};
+export declare class StorageWrapperBE extends FirebaseBaseWrapper {
+    private storage;
+    constructor(firebaseSession: FirebaseSession<any>);
+    getMainBucket(): Promise<BucketWrapper>;
+    getOrCreateBucket(bucketName?: string): Promise<BucketWrapper>;
+    getFile(pathToRemoteFile: string, bucketName?: string): Promise<FileWrapper>;
+    isEmulator(): boolean;
+}
+export declare class BucketWrapper {
+    readonly bucketName: string;
+    readonly bucket: Bucket;
+    readonly storage: StorageWrapperBE;
+    private constructor();
+    getFile(pathToRemoteFile: string): Promise<FileWrapper>;
+    listFiles(folder?: string, filter?: (file: File) => boolean): Promise<File[]>;
+    getBucketName(): string;
+    deleteFiles(folder?: string, filter?: (file: File) => boolean): Promise<void>;
+    private iterateOverFiles;
+}
+export declare class FileWrapper {
+    static emulatorStorageProxy: string;
+    readonly file: File;
+    readonly path: string;
+    readonly bucket: BucketWrapper;
+    private readonly isEmulator?;
+    constructor(path: string, file: File, bucket: BucketWrapper, isEmulator?: boolean);
+    getWriteSignedUrl(contentType: string, expiresInMs: number): Promise<{
+        fileName: string;
+        signedUrl: string;
+        publicUrl: string;
+    } | {
+        fileName: string;
+        signedUrl: string;
+    }>;
+    getReadSignedUrl(expiresInMs?: number, contentType?: string): Promise<{
+        fileName: string;
+        signedUrl: string;
+        publicUrl: string;
+    }>;
+    exists(): Promise<boolean>;
+    write(data: string | number | object | boolean): Promise<void>;
+    read(): Promise<Buffer>;
+    copy(destination: string | BucketWrapper | FileWrapper): Promise<File>;
+    private copyImpl;
+    private copyByStream;
+    move(destination: string | BucketWrapper | FileWrapper): Promise<void>;
+    delete(): Promise<[Response<any>] | undefined>;
+    private getSignedUrl;
+    writeToStream(feeder: (writable: Writable) => Promise<void | typeof END_OF_STREAM>): Promise<void>;
+    createWriteStream(options?: CreateWriteStreamOptions): Writable;
+    createReadStream(options?: CreateReadStreamOptions): import("stream").Readable;
+    makePublic(): Promise<MakeFilePublicResponse>;
+    setMetadata(metadata: FileMetadata, options?: object): Promise<FileMetadata>;
+    getMetadata(options?: object): Promise<FileMetadata>;
+}

package/storage/StorageWrapperBE.js

@@ -0,0 +1,246 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { BadImplementationException, currentTimeMillis, Minute, ThisShouldNotHappenException } from '@nu-art/ts-common';
+import { FirebaseBaseWrapper } from '../auth/FirebaseBaseWrapper.js';
+import { getStorage } from 'firebase-admin/storage';
+export const END_OF_STREAM = { END_OF_STREAM: 'END_OF_STREAM' };
+export class StorageWrapperBE extends FirebaseBaseWrapper {
+    // readonly storage: FirebaseType_Storage;
+    storage;
+    constructor(firebaseSession) {
+        super(firebaseSession);
+        this.storage = getStorage(firebaseSession.app);
+    }
+    async getMainBucket() {
+        return this.getOrCreateBucket();
+    }
+    async getOrCreateBucket(bucketName) {
+        const originBucketName = bucketName;
+        const gcpBucketPrefix = 'gs://';
+        bucketName ??= `${gcpBucketPrefix}${process.env.GCLOUD_PROJECT}.appspot.com`;
+        if (!bucketName.startsWith(gcpBucketPrefix))
+            throw new BadImplementationException(`Bucket name MUST start with '${gcpBucketPrefix}', received '${bucketName}'`);
+        let bucket = this.storage.bucket(bucketName);
+        if (!this.isEmulator())
+            bucket = (await bucket.get({ autoCreate: true }))[0];
+        this.logWarningBold(`Creating bucket name: ${bucketName},\norigin bucket name: ${originBucketName}\nactual bucket name: ${bucket.name}`);
+        // @ts-ignore
+        return new BucketWrapper(bucketName, bucket, this);
+    }
+    async getFile(pathToRemoteFile, bucketName) {
+        const bucket = await this.getOrCreateBucket(bucketName);
+        return bucket.getFile(pathToRemoteFile);
+    }
+    isEmulator() {
+        return !!(process.env.FIREBASE_STORAGE_EMULATOR_HOST || process.env.FUNCTIONS_EMULATOR) || false;
+    }
+}
+export class BucketWrapper {
+    bucketName;
+    bucket;
+    storage;
+    constructor(bucketName, bucket, storage) {
+        this.bucketName = bucketName;
+        this.bucket = bucket;
+        this.storage = storage;
+    }
+    async getFile(pathToRemoteFile) {
+        const emulator = this.storage.isEmulator();
+        return new FileWrapper(pathToRemoteFile, this.bucket.file(pathToRemoteFile), this, emulator);
+    }
+    async listFiles(folder = '', filter = () => true) {
+        const filteredFiles = [];
+        await this.iterateOverFiles(folder, filter, async (file) => filteredFiles.push(file));
+        return filteredFiles;
+    }
+    getBucketName() {
+        return this.bucket.name;
+    }
+    async deleteFiles(folder = '', filter = () => true) {
+        await this.iterateOverFiles(folder, filter, (file) => file.delete());
+    }
+    async iterateOverFiles(folder, filter, action) {
+        return new Promise((resolve, reject) => {
+            const callback = async (err, files, nextQuery) => {
+                if (err)
+                    return reject(err);
+                if (files) {
+                    await Promise.all(files.filter(filter).map(file => action(file)));
+                }
+                if (!nextQuery)
+                    return resolve();
+                this.bucket.getFiles(nextQuery, callback);
+            };
+            this.bucket.getFiles({
+                prefix: folder,
+                autoPaginate: false
+            }, callback);
+        });
+    }
+}
+export class FileWrapper {
+    static emulatorStorageProxy;
+    file;
+    path;
+    bucket;
+    isEmulator;
+    constructor(path, file, bucket, isEmulator) {
+        this.file = file;
+        this.bucket = bucket;
+        this.path = path;
+        this.isEmulator = isEmulator;
+    }
+    async getWriteSignedUrl(contentType, expiresInMs) {
+        const options = {
+            action: 'write',
+            contentType: contentType,
+            expires: currentTimeMillis() + expiresInMs,
+        };
+        if (this.isEmulator) {
+            const signedUrl = `${(FileWrapper.emulatorStorageProxy)}/emulatorUpload?path=${encodeURIComponent(this.path)}`;
+            return {
+                fileName: this.path,
+                signedUrl: signedUrl,
+            };
+        }
+        return this.getSignedUrl(options);
+    }
+    async getReadSignedUrl(expiresInMs = 5 * Minute, contentType) {
+        const options = {
+            action: 'read',
+            contentType,
+            expires: currentTimeMillis() + expiresInMs,
+        };
+        if (this.isEmulator) {
+            return {
+                fileName: this.path,
+                signedUrl: this.file.publicUrl(), // this works for read operations locally
+                publicUrl: this.file.publicUrl()
+            };
+        }
+        return this.getSignedUrl(options);
+    }
+    async exists() {
+        return (await this.file.exists())[0];
+    }
+    async write(data) {
+        if (Buffer.isBuffer(data))
+            return this.file.save(data);
+        switch (typeof data) {
+            case 'function':
+            case 'symbol':
+            case 'bigint':
+            case 'undefined':
+                throw new BadImplementationException(`Cannot save file: ${this.file.name}, data is ${typeof data}`);
+            case 'object':
+                return this.file.save(JSON.stringify(data));
+            case 'boolean':
+            case 'number':
+            case 'string':
+                return this.file.save(`${data}`);
+        }
+    }
+    async read() {
+        const downloadResponse = await this.file.download();
+        return downloadResponse[0];
+    }
+    async copy(destination) {
+        const copy = await this.copyImpl(destination);
+        return copy[0];
+    }
+    copyImpl(destination) {
+        if (typeof destination === 'string')
+            return this.file.copy(destination);
+        const bucketWrapper = destination instanceof FileWrapper ? destination.bucket : destination;
+        if (this.bucket.storage.firebaseSession !== bucketWrapper.storage.firebaseSession)
+            return this.copyByStream(destination);
+        if (destination instanceof FileWrapper)
+            return this.file.copy(destination.file);
+        return this.file.copy(destination.bucket);
+    }
+    async copyByStream(destination) {
+        const destinationFile = destination instanceof FileWrapper ? destination.file : (await destination.getFile(this.path)).file;
+        return new Promise((resolve, reject) => {
+            this
+                .file
+                .createReadStream()
+                .pipe(destinationFile
+                .createWriteStream()
+                .on('error', reject)
+                .on('finish', () => resolve([destinationFile, undefined])))
+                .on('error', reject);
+        });
+    }
+    async move(destination) {
+        const file = await this.copy(destination);
+        try {
+            await this.delete();
+        }
+        catch (e) {
+            try {
+                await file.delete();
+            }
+            catch (err) {
+                throw new ThisShouldNotHappenException('Error during the deletion of the recently copied file, check the attached error', err);
+            }
+            throw new BadImplementationException('Error during the deletion of the file after a successful copy, attached error stack', e);
+        }
+    }
+    async delete() {
+        if (!await this.file.exists())
+            return;
+        return this.file.delete();
+    }
+    async getSignedUrl(options) {
+        const results = await this.file.getSignedUrl(options);
+        const url = results[0]; // An array with a single string is returned
+        return {
+            fileName: this.path,
+            signedUrl: url,
+            publicUrl: encodeURI(`https://storage.googleapis.com/${this.bucket.bucketName.replace(`gs://`, '')}${this.path}`)
+        };
+    }
+    async writeToStream(feeder) {
+        const writeable = this.createWriteStream({ gzip: true });
+        const promise = new Promise((resolve, reject) => {
+            writeable.on('close', () => resolve());
+            writeable.on('error', (e) => reject(e));
+        });
+        let data;
+        do {
+            data = await feeder(writeable);
+        } while (data !== END_OF_STREAM);
+        writeable.end();
+        return promise;
+    }
+    createWriteStream(options) {
+        return this.file.createWriteStream(options);
+    }
+    createReadStream(options) {
+        return this.file.createReadStream(options);
+    }
+    async makePublic() {
+        return this.file.makePublic();
+    }
+    async setMetadata(metadata, options) {
+        return (await this.file.setMetadata(metadata, options))[0];
+    }
+    async getMetadata(options) {
+        return (await this.file.getMetadata(options))[0];
+    }
+}

package/storage/emulator.d.ts

@@ -0,0 +1,4 @@
+export declare const firebaseStorageEmulatorProxy: {
+    emulatorUpload: import("firebase-functions/https").HttpsFunction;
+    emulatorDownload: import("firebase-functions/https").HttpsFunction;
+};

package/storage/emulator.js

@@ -0,0 +1,46 @@
+import { onRequest } from 'firebase-functions/v2/https';
+import { ModuleBE_Firebase } from '../ModuleBE_Firebase.js';
+import { HttpCodes } from '@nu-art/ts-common/core/exceptions/http-codes';
+export const firebaseStorageEmulatorProxy = {
+    emulatorUpload: onRequest({ maxInstances: 10, concurrency: 1, }, async (request, response) => {
+        if (request.method.toLowerCase() !== 'put')
+            response.send('method not supported').end(HttpCodes._4XX.METHOD_NOT_ALLOWED.code);
+        const pathToFile = request.query['path'];
+        const file = await ModuleBE_Firebase.createAdminSession().getStorage().getFile(String(pathToFile));
+        const writable = file.createWriteStream({ gzip: true });
+        request.pipe(writable)
+            .on('error', (err) => {
+            console.error('Stream error:', err);
+            response.status(500).send('Error uploading file');
+        })
+            .on('finish', () => {
+            response.status(200).send('File uploaded successfully');
+        });
+    }),
+    emulatorDownload: onRequest({ maxInstances: 10, concurrency: 1, }, async (request, response) => {
+        if (request.method.toLowerCase() !== 'get')
+            response.send('method not supported').end(HttpCodes._4XX.METHOD_NOT_ALLOWED.code);
+        const pathToFile = request.query['path'];
+        const contentType = request.query['content-type'];
+        const fileName = request.query['file-name'];
+        const file = await ModuleBE_Firebase.createAdminSession().getStorage().getFile(String(pathToFile));
+        file.createReadStream({ decompress: false })
+            .on('error', (err) => {
+            console.error('Stream error:', err);
+            response.status(500).send('Error downloading file');
+        })
+            .on('response', (fileResponse) => {
+            console.log('response', fileResponse);
+            Object.keys(fileResponse.headers).forEach(key => {
+                response.set(key, fileResponse.headers[key]);
+            });
+            response.set('content-disposition', `attachment; filename=${fileName}`);
+            response.set('content-type', contentType || fileResponse.headers['content-type']);
+        })
+            .on('end', () => {
+            console.log('File download completed.');
+            response.end();
+        })
+            .pipe(response);
+    })
+};

package/storage/types.d.ts

@@ -0,0 +1,4 @@
+import { CopyResponse } from '@google-cloud/storage';
+import { Storage } from 'firebase-admin/storage';
+export type FirebaseType_Storage = Storage;
+export type Firebase_CopyResponse = [CopyResponse[0], CopyResponse[1] | undefined];

package/storage/types.js

@@ -0,0 +1,18 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/tools/lock-operation.d.ts

@@ -0,0 +1,10 @@
+import { CustomException } from '@nu-art/ts-common';
+/**
+ * # <ins>OperationLockedException</ins>
+ * This class inherits {@link CustomException} and functions like it, after setting the exceptionType property as "OperationLockedException",
+ * @category - Exceptions
+ */
+export declare class OperationLockedException extends CustomException {
+    constructor(message: string, cause?: Error);
+}
+export declare function lockedOperation<T>(key: string, timeout: number, action: () => Promise<T>, exception?: CustomException): Promise<T>;

package/tools/lock-operation.js

@@ -0,0 +1,35 @@
+import { currentTimeMillis, CustomException } from '@nu-art/ts-common';
+import { ModuleBE_Firebase } from '../ModuleBE_Firebase.js';
+/**
+ * # <ins>OperationLockedException</ins>
+ * This class inherits {@link CustomException} and functions like it, after setting the exceptionType property as "OperationLockedException",
+ * @category - Exceptions
+ */
+export class OperationLockedException extends CustomException {
+    constructor(message, cause) {
+        super(OperationLockedException, message, cause);
+    }
+}
+const FirebaseLockState_LOCKED = 'LOCKED';
+const FirebaseLockState_UNLOCKED = 'UNLOCKED';
+export async function lockedOperation(key, timeout, action, exception = new OperationLockedException('This action is already in progress')) {
+    const ref = ModuleBE_Firebase.createAdminSession().getDatabase().ref(`/lock/${key}`);
+    const now = currentTimeMillis();
+    const transactionResult = await ref.transaction(current => {
+        // Check if the lock is held and not expired
+        if (current && current.status === FirebaseLockState_LOCKED && now < current.timeout) {
+            return current; // Returning current to keep the existing value
+        }
+        // Lock is either not held or expired, so we can acquire it
+        return { status: FirebaseLockState_LOCKED, timeout: now + timeout };
+    });
+    // Check if the transaction was committed and lock was acquired
+    if (!transactionResult.committed || transactionResult.value.status !== FirebaseLockState_LOCKED)
+        throw exception; // Lock could not be acquired
+    try {
+        return await action();
+    }
+    finally {
+        await ref.patch({ status: FirebaseLockState_UNLOCKED }); // Setting the status to 'UNLOCKED'
+    }
+}