tiny-essentials 1.0.0

package/dist/legacy/firebase/cookieSession.mjs

@@ -0,0 +1,114 @@
+/**
+ * Class representing an authentication system for generating session cookies.
+ *
+ * The AuthSystem handles checking the authentication time and generating session cookies based on
+ * ID token verification. It supports custom time checking and cookie generation logic.
+ *
+ * @class AuthSystem
+ */
+class AuthSystem {
+    /**
+     * Creates an instance of AuthSystem.
+     * Initializes default configurations for authentication time checking and session cookie expiration.
+     *
+     * @constructor
+     */
+    constructor() {
+        this.auth_time = 5;
+        // Default Values
+        const authSystem = this;
+        this.default = {
+            /**
+             * Checks whether the authentication time is within the last 5 minutes.
+             *
+             * @param {Object} decodedIdToken - The decoded ID token object.
+             * @param {number} decodedIdToken.auth_time - The authentication time from the ID token.
+             * @returns {boolean} Returns `true` if the authentication time is within the last 5 minutes.
+             */
+            checkAuthTime: (decodedIdToken) => {
+                // Only process if the user just signed in in the last {this.auth_time} minutes.
+                if (new Date().getTime() / 1000 - decodedIdToken.auth_time < authSystem.auth_time * 60)
+                    return true;
+                // Nope
+                else
+                    return false;
+            },
+            /**
+             * Generates the session cookie expiration time ({this.auth_time} days by default).
+             *
+             * @returns {number} Returns the expiration time in milliseconds (5 days).
+             */
+            cookieTimeGenerator: () => {
+                // Set session expiration to 5 days.
+                const expiresIn = 60 * 60 * 24 * authSystem.auth_time * 1000;
+                // Create the session cookie. This will also verify the ID token in the process.
+                // The session cookie will have the same claims as the ID token.
+                // To only allow session cookie setting on recent sign-in, auth_time in ID token
+                // can be checked to ensure user was recently signed in before creating a session cookie.
+                // Complete
+                return expiresIn;
+            },
+        };
+        // Set Value
+        this.checkAuthTime = this.default.checkAuthTime;
+        this.cookieTimeGenerator = this.default.cookieTimeGenerator;
+    }
+    /**
+     * Sets a custom callback to check authentication time.
+     *
+     * @param {Function} callback - The callback function to validate authentication time.
+     * @returns {void}
+     */
+    setCookieTimeGenerator(callback) {
+        if (typeof callback === 'function')
+            this.cookieTimeGenerator = callback;
+    }
+    /**
+     * Sets a custom callback to generate the cookie expiration time.
+     *
+     * @param {Function} callback - The callback function to generate cookie expiration time.
+     * @returns {void}
+     */
+    setCheckAuthTime(callback) {
+        if (typeof callback === 'function')
+            this.checkAuthTime = callback;
+    }
+    /**
+     * Generates a session cookie for the user after verifying the ID token.
+     *
+     * @param {Object} auth - The authentication object used to verify the ID token and create session cookies.
+     * @param {string} token - The ID token of the authenticated user.
+     * @returns {Promise<string>} A promise that resolves with the session cookie or rejects with an error.
+     */
+    genCookieSession(auth, token) {
+        const tinyThis = this;
+        return new Promise(function (resolve, reject) {
+            auth
+                .verifyIdToken(token)
+                .then(async (decodedIdToken) => {
+                try {
+                    // Validate the authentication time
+                    const checkedTime = await tinyThis.checkAuthTime(decodedIdToken);
+                    if (checkedTime) {
+                        // Generate session cookie
+                        const expiresIn = await tinyThis.cookieTimeGenerator(decodedIdToken);
+                        auth.createSessionCookie(token, { expiresIn }).then(resolve).catch(reject);
+                    }
+                    // Nope
+                    else {
+                        const err = new Error('Invalid Account ID Token Time.');
+                        err.code = 401;
+                        reject(err);
+                    }
+                }
+                catch (err) {
+                    // Fail
+                    reject(err);
+                }
+            })
+                .catch(reject);
+        });
+    }
+}
+// Module
+export default AuthSystem;

package/dist/legacy/firebase/database/index.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+var presence = require('./presence.cjs');
+var saveAsync = require('./saveAsync.cjs');
+
+const database = {
+  presence: presence,
+  SaveAsync: saveAsync,
+};
+
+module.exports = database;

package/dist/legacy/firebase/database/index.d.mts

@@ -0,0 +1,7 @@
+export default database;
+declare namespace database {
+    export { presenceSystem as presence };
+    export { SaveAsync };
+}
+import presenceSystem from './presence.mjs';
+import SaveAsync from './saveAsync.mjs';

package/dist/legacy/firebase/database/index.mjs

@@ -0,0 +1,7 @@
+import presenceSystem from './presence.mjs';
+import SaveAsync from './saveAsync.mjs';
+const database = {
+    presence: presenceSystem,
+    SaveAsync,
+};
+export default database;

package/dist/legacy/firebase/database/presence.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+var moment = require('moment-timezone');
+var _ = require('lodash');
+
+/**
+ * Firebase Presence System
+ *
+ * This module allows real-time tracking of user presence using Firebase Realtime Database.
+ * It handles multiple connections (tabs/devices), updates online status, and records the last time online.
+ *
+ * @module presenceSystem
+ */
+const presenceSystem = {
+  /**
+   * Returns the source code of the `start` function as a string, with placeholders replaced.
+   *
+   * This function is useful to retrieve a browser-compatible version of the `start` function
+   * for client-side injection (e.g., for Firebase emulators or test UIs).
+   *
+   * @param {string} [lodash='_'] - The lodash import replacement string (usually `_`).
+   * @returns {string} JavaScript source code as a string with `lodash` and `moment` replaced or removed.
+   */
+  browserVersion: function (lodash = '_') {
+    // Get Browser Version
+    return presenceSystem.start
+      .toString()
+      .replace(`import _ from 'lodash'`, lodash)
+      .replace('let moment;', '')
+      .replace('moment = null;', 'console.error(err);')
+      .replace(
+        `import moment from 'moment-timezone'`,
+        "const tinypudding = 'Tiny Jasmini's Pudding.'",
+      );
+  },
+
+  /**
+   * Starts presence tracking for a given user in Firebase Realtime Database.
+   *
+   * It sets up handlers for `.info/connected`, manages disconnect events,
+   * and updates the last online time in UTC format.
+   *
+   * @param {object} database - Firebase database reference (usually `admin.database()` or `firebase.database()`).
+   * @param {string|object} myConnectionsRef - Path or database ref to the user's `connections` node.
+   * @param {string|object} lastOnlineRef - Path or database ref to the user's `lastOnline` node.
+   * @param {object} [data] - Optional configuration overrides.
+   * @param {boolean|object} [data.connected=true] - Data to store when device is connected.
+   * @param {Function} [data.removeError] - Callback for `onDisconnect().remove()` errors.
+   * @param {Function} [data.getDate] - Function to return a UTC-based timestamp object (uses `moment` if available).
+   */
+  start: (database, myConnectionsRef, lastOnlineRef, data) => {
+    // Since I can connect from multiple devices or browser tabs, we store each connection instance separately
+    // any time that connectionsRef's value is null (i.e. has no children) I am offline
+    if (typeof myConnectionsRef === 'string') {
+      myConnectionsRef = database.ref(myConnectionsRef);
+    }
+
+    // stores the timestamp of my last disconnect (the last time I was seen online)
+    if (typeof lastOnlineRef === 'string') {
+      lastOnlineRef = database.ref(lastOnlineRef);
+    }
+
+    // Get Base
+    data = _.defaultsDeep({}, data, {
+      // Remove Error
+      removeError: (err) => {
+        if (err) {
+          console.group('could not establish onDisconnect event');
+          console.error(err);
+          console.groupEnd();
+        }
+      },
+
+      // Is Connected
+      connected: true,
+
+      // Get Data
+      getDate: function () {
+        // Prepare Values
+        let momentTime;
+
+        // Timezone Module
+        if (moment) {
+          momentTime = moment.utc().toObject();
+        }
+
+        // Vanilla
+        else {
+          const date = new Date();
+          momentTime = {
+            date: date.getUTCDate(),
+            hours: date.getUTCHours(),
+            milliseconds: date.getUTCMilliseconds(),
+            minutes: date.getUTCMinutes(),
+            months: date.getUTCMonth(),
+            seconds: date.getUTCSeconds(),
+            years: date.getUTCFullYear(),
+          };
+        }
+
+        // Insert Timezone Name
+        momentTime.timezone = 'Universal';
+
+        // Return the value
+        return momentTime;
+      },
+    });
+
+    // Prepare Connection
+    const connectedRef = database.ref('.info/connected');
+    connectedRef.on('value', (snap) => {
+      if (snap.val() === true) {
+        // We're connected (or reconnected)! Do anything here that should happen only if online (or on reconnect)
+        const con = myConnectionsRef.push();
+
+        // When I disconnect, remove this device
+        con.onDisconnect().remove(data.removeError);
+
+        // Add this device to my connections list
+        // this value could contain info about the device or a timestamp too
+        con.set(data.connected);
+
+        // When I disconnect, update the last time I was seen online
+        const momentTime = data.getDate();
+        lastOnlineRef.onDisconnect().set(momentTime);
+      }
+    });
+  },
+};
+
+module.exports = presenceSystem;

package/dist/legacy/firebase/database/presence.d.mts

@@ -0,0 +1,9 @@
+export default presenceSystem;
+declare namespace presenceSystem {
+    function browserVersion(lodash?: string): string;
+    function start(database: object, myConnectionsRef: string | object, lastOnlineRef: string | object, data?: {
+        connected?: boolean | object | undefined;
+        removeError?: Function | undefined;
+        getDate?: Function | undefined;
+    }): void;
+}

package/dist/legacy/firebase/database/presence.mjs

@@ -0,0 +1,111 @@
+import moment from 'moment-timezone';
+import _ from 'lodash';
+/**
+ * Firebase Presence System
+ *
+ * This module allows real-time tracking of user presence using Firebase Realtime Database.
+ * It handles multiple connections (tabs/devices), updates online status, and records the last time online.
+ *
+ * @module presenceSystem
+ */
+const presenceSystem = {
+    /**
+     * Returns the source code of the `start` function as a string, with placeholders replaced.
+     *
+     * This function is useful to retrieve a browser-compatible version of the `start` function
+     * for client-side injection (e.g., for Firebase emulators or test UIs).
+     *
+     * @param {string} [lodash='_'] - The lodash import replacement string (usually `_`).
+     * @returns {string} JavaScript source code as a string with `lodash` and `moment` replaced or removed.
+     */
+    browserVersion: function (lodash = '_') {
+        // Get Browser Version
+        return presenceSystem.start
+            .toString()
+            .replace(`import _ from 'lodash'`, lodash)
+            .replace('let moment;', '')
+            .replace('moment = null;', 'console.error(err);')
+            .replace(`import moment from 'moment-timezone'`, "const tinypudding = 'Tiny Jasmini's Pudding.'");
+    },
+    /**
+     * Starts presence tracking for a given user in Firebase Realtime Database.
+     *
+     * It sets up handlers for `.info/connected`, manages disconnect events,
+     * and updates the last online time in UTC format.
+     *
+     * @param {object} database - Firebase database reference (usually `admin.database()` or `firebase.database()`).
+     * @param {string|object} myConnectionsRef - Path or database ref to the user's `connections` node.
+     * @param {string|object} lastOnlineRef - Path or database ref to the user's `lastOnline` node.
+     * @param {object} [data] - Optional configuration overrides.
+     * @param {boolean|object} [data.connected=true] - Data to store when device is connected.
+     * @param {Function} [data.removeError] - Callback for `onDisconnect().remove()` errors.
+     * @param {Function} [data.getDate] - Function to return a UTC-based timestamp object (uses `moment` if available).
+     */
+    start: (database, myConnectionsRef, lastOnlineRef, data) => {
+        // Since I can connect from multiple devices or browser tabs, we store each connection instance separately
+        // any time that connectionsRef's value is null (i.e. has no children) I am offline
+        if (typeof myConnectionsRef === 'string') {
+            myConnectionsRef = database.ref(myConnectionsRef);
+        }
+        // stores the timestamp of my last disconnect (the last time I was seen online)
+        if (typeof lastOnlineRef === 'string') {
+            lastOnlineRef = database.ref(lastOnlineRef);
+        }
+        // Get Base
+        data = _.defaultsDeep({}, data, {
+            // Remove Error
+            removeError: (err) => {
+                if (err) {
+                    console.group('could not establish onDisconnect event');
+                    console.error(err);
+                    console.groupEnd();
+                }
+            },
+            // Is Connected
+            connected: true,
+            // Get Data
+            getDate: function () {
+                // Prepare Values
+                let momentTime;
+                // Timezone Module
+                if (moment) {
+                    momentTime = moment.utc().toObject();
+                }
+                // Vanilla
+                else {
+                    const date = new Date();
+                    momentTime = {
+                        date: date.getUTCDate(),
+                        hours: date.getUTCHours(),
+                        milliseconds: date.getUTCMilliseconds(),
+                        minutes: date.getUTCMinutes(),
+                        months: date.getUTCMonth(),
+                        seconds: date.getUTCSeconds(),
+                        years: date.getUTCFullYear(),
+                    };
+                }
+                // Insert Timezone Name
+                momentTime.timezone = 'Universal';
+                // Return the value
+                return momentTime;
+            },
+        });
+        // Prepare Connection
+        const connectedRef = database.ref('.info/connected');
+        connectedRef.on('value', (snap) => {
+            if (snap.val() === true) {
+                // We're connected (or reconnected)! Do anything here that should happen only if online (or on reconnect)
+                const con = myConnectionsRef.push();
+                // When I disconnect, remove this device
+                con.onDisconnect().remove(data.removeError);
+                // Add this device to my connections list
+                // this value could contain info about the device or a timestamp too
+                con.set(data.connected);
+                // When I disconnect, update the last time I was seen online
+                const momentTime = data.getDate();
+                lastOnlineRef.onDisconnect().set(momentTime);
+            }
+        });
+    },
+};
+export default presenceSystem;

package/dist/legacy/firebase/database/saveAsync.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * Class representing an asynchronous save system with callback support.
+ *
+ * This class is designed to handle database operations asynchronously and supports
+ * adding multiple operations to a queue, as well as running callbacks after each action.
+ *
+ * @class SaveAsync
+ */
+class SaveAsync {
+  /**
+   * Creates an instance of SaveAsync.
+   *
+   * @param {object} db - The database reference to interact with (e.g., Firebase or other DB).
+   */
+  constructor(db) {
+    this.db = db;
+    this.list = [];
+    this.callbacks = {};
+    this.using = false;
+  }
+
+  /**
+   * Registers a callback to be run when a specific action type is executed.
+   *
+   * @param {string} where - The action type (e.g., "set", "push", etc.).
+   * @param {Function} callback - The callback function to run when the action is performed.
+   * @returns {boolean} Returns `true` if the callback is successfully registered.
+   */
+  on(where, callback) {
+    if (!Array.isArray(this.callbacks[where])) this.callbacks[where] = [];
+    this.callbacks[where].push(callback);
+    return true;
+  }
+
+  /**
+   * Runs all callbacks associated with a specific action type.
+   *
+   * @param {string} type - The action type (e.g., "set", "push", etc.).
+   * @param {any} data - The data passed to the callback(s).
+   * @param {string} [where] - The location (optional) where the action was performed.
+   */
+  _runCallbacks(type, data, where) {
+    if (Array.isArray(this.callbacks[type]))
+      for (const item in this.callbacks[type])
+        if (typeof this.callbacks[type][item] === 'function')
+          this.callbacks[type][item](data, where);
+  }
+
+  /**
+   * Processes the queued actions and executes them one by one.
+   *
+   * Each action in the queue is processed asynchronously. Once one action completes,
+   * the next action in the queue is triggered.
+   */
+  action() {
+    // Insert
+    if (this.list.length > 0) {
+      // Get Item
+      const post = this.list.shift();
+      const tinyThis = this;
+
+      // Try
+      try {
+        if (typeof post.where !== 'string') {
+          if (post.data) {
+            this.db[post.type](post.data)
+              .then(() => {
+                this._runCallbacks(post.type, post.data);
+                tinyThis.action();
+              })
+              .catch((err) => {
+                console.error(err);
+              });
+          } else {
+            this.db[post.type]()
+              .then(() => {
+                this._runCallbacks(post.type);
+                tinyThis.action();
+              })
+              .catch((err) => {
+                console.error(err);
+              });
+          }
+        } else {
+          if (post.data) {
+            this.db
+              .child(post.where)
+              [post.type](post.data)
+              .then(() => {
+                this._runCallbacks(post.type, post.data, post.where);
+                tinyThis.action();
+              })
+              .catch((err) => {
+                console.error(err);
+              });
+          } else {
+            this.db
+              .child(post.where)
+              [post.type]()
+              .then(() => {
+                this._runCallbacks(post.type, null, post.where);
+                tinyThis.action();
+              })
+              .catch((err) => {
+                console.error(err);
+              });
+          }
+        }
+      } catch (err) {
+        // Error
+        console.error(err);
+      }
+    }
+
+    // Nope
+    else this.using = false;
+  }
+
+  /**
+   * Inserts a new action into the queue.
+   *
+   * The action will be executed when the system is ready (i.e., when the queue is not in use).
+   *
+   * @param {object} [data={}] - The data to be saved (optional).
+   * @param {string} [type='set'] - The type of the database action (e.g., 'set', 'push', etc.).
+   * @param {string|null} [where=null] - The location where the data should be stored (optional).
+   */
+  insert(data = {}, type = 'set', where = null) {
+    // Insert
+    if (data !== null) {
+      if (where !== null) this.list.push({ where: String(where), data: data, type: type });
+      else this.list.push({ data: data, type: type });
+    } else {
+      if (where !== null) this.list.push({ where: String(where), type: type });
+      else this.list.push({ type: type });
+    }
+
+    if (!this.using) {
+      this.using = true;
+      this.action();
+    }
+  }
+}
+
+module.exports = SaveAsync;

package/dist/legacy/firebase/database/saveAsync.d.mts

@@ -0,0 +1,54 @@
+export default SaveAsync;
+/**
+ * Class representing an asynchronous save system with callback support.
+ *
+ * This class is designed to handle database operations asynchronously and supports
+ * adding multiple operations to a queue, as well as running callbacks after each action.
+ *
+ * @class SaveAsync
+ */
+declare class SaveAsync {
+    /**
+     * Creates an instance of SaveAsync.
+     *
+     * @param {object} db - The database reference to interact with (e.g., Firebase or other DB).
+     */
+    constructor(db: object);
+    db: object;
+    list: any[];
+    callbacks: {};
+    using: boolean;
+    /**
+     * Registers a callback to be run when a specific action type is executed.
+     *
+     * @param {string} where - The action type (e.g., "set", "push", etc.).
+     * @param {Function} callback - The callback function to run when the action is performed.
+     * @returns {boolean} Returns `true` if the callback is successfully registered.
+     */
+    on(where: string, callback: Function): boolean;
+    /**
+     * Runs all callbacks associated with a specific action type.
+     *
+     * @param {string} type - The action type (e.g., "set", "push", etc.).
+     * @param {any} data - The data passed to the callback(s).
+     * @param {string} [where] - The location (optional) where the action was performed.
+     */
+    _runCallbacks(type: string, data: any, where?: string): void;
+    /**
+     * Processes the queued actions and executes them one by one.
+     *
+     * Each action in the queue is processed asynchronously. Once one action completes,
+     * the next action in the queue is triggered.
+     */
+    action(): void;
+    /**
+     * Inserts a new action into the queue.
+     *
+     * The action will be executed when the system is ready (i.e., when the queue is not in use).
+     *
+     * @param {object} [data={}] - The data to be saved (optional).
+     * @param {string} [type='set'] - The type of the database action (e.g., 'set', 'push', etc.).
+     * @param {string|null} [where=null] - The location where the data should be stored (optional).
+     */
+    insert(data?: object, type?: string, where?: string | null): void;
+}