@x12i/helpers 1.0.1 → 1.1.0

package/src/helpers/firebaseRtdb.js

@@ -0,0 +1,471 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+let _singleton = null;
+
+function fileExists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseDotEnv(contents) {
+  const out = {};
+  const lines = String(contents || "").split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+
+    val = val
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t");
+
+    if (key) out[key] = val;
+  }
+  return out;
+}
+
+function loadEnvFromFile(envPath, { override = false } = {}) {
+  const p = envPath ? path.resolve(envPath) : path.resolve(process.cwd(), ".env");
+  if (!fileExists(p)) return { loaded: false, path: p };
+
+  const parsed = parseDotEnv(fs.readFileSync(p, "utf8"));
+  for (const [k, v] of Object.entries(parsed)) {
+    if (!override && process.env[k] !== undefined) continue;
+    process.env[k] = v;
+  }
+  return { loaded: true, path: p };
+}
+
+function deepGet(obj, p) {
+  if (!obj || typeof obj !== "object") return undefined;
+  const segs = String(p || "").split(".").filter(Boolean);
+  let cur = obj;
+  for (const s of segs) {
+    if (cur == null) return undefined;
+    cur = cur[s];
+  }
+  return cur;
+}
+
+function matchesFilter(doc, filter) {
+  if (!filter || typeof filter !== "object") return true;
+  for (const [k, expected] of Object.entries(filter)) {
+    if (k === "_id" || k === "id") {
+      if (doc?._id !== expected && doc?.id !== expected) return false;
+      continue;
+    }
+    const actual = deepGet(doc, k);
+    if (actual !== expected) return false;
+  }
+  return true;
+}
+
+function applyUpdateOperators(doc, update) {
+  if (!update || typeof update !== "object") return doc;
+  const out = doc && typeof doc === "object" ? { ...doc } : {};
+
+  const isOperatorDoc = Object.keys(update).some((k) => k.startsWith("$"));
+  if (!isOperatorDoc) return { ...out, ...update };
+
+  if (update.$set && typeof update.$set === "object") {
+    for (const [k, v] of Object.entries(update.$set)) out[k] = v;
+  }
+
+  if (update.$unset && typeof update.$unset === "object") {
+    for (const k of Object.keys(update.$unset)) delete out[k];
+  }
+
+  if (update.$inc && typeof update.$inc === "object") {
+    for (const [k, v] of Object.entries(update.$inc)) {
+      const cur = Number(out[k] ?? 0);
+      const by = Number(v ?? 0);
+      out[k] = cur + by;
+    }
+  }
+
+  if (update.$push && typeof update.$push === "object") {
+    for (const [k, v] of Object.entries(update.$push)) {
+      const cur = out[k];
+      const arr = Array.isArray(cur) ? cur.slice() : [];
+      arr.push(v);
+      out[k] = arr;
+    }
+  }
+
+  if (update.$pull && typeof update.$pull === "object") {
+    for (const [k, v] of Object.entries(update.$pull)) {
+      const cur = out[k];
+      if (!Array.isArray(cur)) continue;
+      out[k] = cur.filter((item) => item !== v);
+    }
+  }
+
+  return out;
+}
+
+function envFirst(...keys) {
+  for (const k of keys) {
+    const v = process.env[k];
+    if (v != null && String(v).trim() !== "") return v;
+  }
+  return undefined;
+}
+
+function readServiceAccountFromEnvOrOptions(opts = {}) {
+  const inlineJson =
+    opts.serviceAccountJson ??
+    envFirst("FIREBASE_SERVICE_ACCOUNT_JSON", "GOOGLE_SERVICE_ACCOUNT_JSON");
+  const base64 =
+    opts.serviceAccountBase64 ??
+    envFirst("FIREBASE_SERVICE_ACCOUNT_BASE64", "GOOGLE_SERVICE_ACCOUNT_BASE64");
+  let jsonPath =
+    opts.serviceAccountPath ??
+    envFirst("FIREBASE_SERVICE_ACCOUNT_PATH", "GOOGLE_APPLICATION_CREDENTIALS");
+
+  // Smart default for this repo: if nothing set, use .secrets/firebase-service-account.json when it exists
+  if (!jsonPath) {
+    const defaultSecretsPath = path.resolve(process.cwd(), ".secrets", "firebase-service-account.json");
+    if (fileExists(defaultSecretsPath)) jsonPath = defaultSecretsPath;
+  }
+
+  if (inlineJson) {
+    return JSON.parse(inlineJson);
+  }
+  if (base64) {
+    const decoded = Buffer.from(String(base64), "base64").toString("utf8");
+    return JSON.parse(decoded);
+  }
+  if (jsonPath) {
+    const p = path.resolve(String(jsonPath));
+    const raw = fs.readFileSync(p, "utf8");
+    return JSON.parse(raw);
+  }
+  return null;
+}
+
+function normalizeDatabaseUrl(url) {
+  const s = String(url || "").trim();
+  if (!s) return "";
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function initFirebaseRtdb(options = {}) {
+  const {
+    envPath = ".env",
+    envOverride = false,
+    singleton = true,
+    appName,
+  } = options;
+
+  loadEnvFromFile(envPath, { override: envOverride });
+
+  const credentialJson = readServiceAccountFromEnvOrOptions(options);
+  if (!credentialJson) {
+    throw new Error(
+      "firebaseRtdb.init: missing service account credentials (set FIREBASE_SERVICE_ACCOUNT_PATH to .secrets/firebase-service-account.json, or set FIREBASE_SERVICE_ACCOUNT_JSON, or pass { serviceAccountPath/serviceAccountJson })"
+    );
+  }
+
+  const databaseURL = normalizeDatabaseUrl(
+    options.databaseURL ?? envFirst("FIREBASE_DATABASE_URL", "FIREBASE_DB_URL")
+  );
+  if (!databaseURL) {
+    throw new Error(
+      "firebaseRtdb.init: missing database URL (set FIREBASE_DATABASE_URL in .env or pass { databaseURL })"
+    );
+  }
+
+  // Lazy require so consumers that don't use Firebase don't pay cost on import.
+  const admin = require("firebase-admin");
+
+  const name = appName ?? envFirst("FIREBASE_APP_NAME") ?? undefined;
+  const existing = admin.apps.find((a) => a.name === (name || "[DEFAULT]"));
+  const app =
+    existing ||
+    admin.initializeApp(
+      {
+        credential: admin.credential.cert(credentialJson),
+        databaseURL,
+      },
+      name
+    );
+
+  const db = admin.database(app);
+  const client = createMongoLikeRtdbClient({ admin, app, db });
+
+  if (singleton) _singleton = client;
+  return client;
+}
+
+function getFirebaseRtdb() {
+  if (!_singleton) {
+    throw new Error(
+      "firebaseRtdb.get: not initialized. Call initFirebaseRtdb() first."
+    );
+  }
+  return _singleton;
+}
+
+function createMongoLikeRtdbClient({ admin, app, db }) {
+  function ref(p = "/") {
+    const clean = String(p || "/").replace(/^\/+/, "");
+    return clean ? db.ref(clean) : db.ref();
+  }
+
+  function collection(name) {
+    if (!name) throw new TypeError("collection(name) requires a name");
+    const basePath = String(name).replace(/^\/+|\/+$/g, "");
+    const baseRef = ref(basePath);
+
+    function doc(id) {
+      if (!id) throw new TypeError("doc(id) requires an id");
+      const idStr = String(id);
+      const r = baseRef.child(idStr);
+
+      return {
+        id: idStr,
+        ref: r,
+        async get() {
+          const snap = await r.get();
+          const val = snap.val();
+          if (val == null) return null;
+          return { _id: idStr, ...val };
+        },
+        async set(value, { merge = false } = {}) {
+          if (!merge) {
+            await r.set(value);
+            return { acknowledged: true, _id: idStr };
+          }
+          const cur = (await r.get()).val() || {};
+          await r.set({ ...cur, ...value });
+          return { acknowledged: true, _id: idStr };
+        },
+        async update(update) {
+          const cur = (await r.get()).val();
+          if (cur == null) return { acknowledged: true, matchedCount: 0, modifiedCount: 0 };
+          const next = applyUpdateOperators(cur, update);
+          await r.set(next);
+          return { acknowledged: true, matchedCount: 1, modifiedCount: 1 };
+        },
+        async delete() {
+          const cur = (await r.get()).exists();
+          await r.remove();
+          return { acknowledged: true, deletedCount: cur ? 1 : 0 };
+        },
+      };
+    }
+
+    async function _readAll({ query } = {}) {
+      if (query) {
+        const snap = await query.get();
+        const val = snap.val();
+        if (!val || typeof val !== "object") return [];
+        return Object.entries(val).map(([id, data]) => ({ _id: id, ...data }));
+      }
+
+      const snap = await baseRef.get();
+      const val = snap.val();
+      if (!val || typeof val !== "object") return [];
+      return Object.entries(val).map(([id, data]) => ({ _id: id, ...data }));
+    }
+
+    function _buildQuery(q) {
+      let queryRef = baseRef;
+      if (!q || typeof q !== "object") return queryRef;
+      if (q.orderByChild) queryRef = queryRef.orderByChild(String(q.orderByChild));
+      else if (q.orderByKey) queryRef = queryRef.orderByKey();
+      else if (q.orderByValue) queryRef = queryRef.orderByValue();
+
+      if (q.equalTo !== undefined) queryRef = queryRef.equalTo(q.equalTo);
+      if (q.startAt !== undefined) queryRef = queryRef.startAt(q.startAt);
+      if (q.endAt !== undefined) queryRef = queryRef.endAt(q.endAt);
+      if (q.limitToFirst !== undefined) queryRef = queryRef.limitToFirst(Number(q.limitToFirst));
+      if (q.limitToLast !== undefined) queryRef = queryRef.limitToLast(Number(q.limitToLast));
+
+      return queryRef;
+    }
+
+    return {
+      name: basePath,
+      ref: baseRef,
+      doc,
+
+      /**
+       * Mongo-ish query builder for RTDB native queries:
+       *   col.query({ orderByChild: "email", equalTo: "a@b.com", limitToFirst: 10 }).find()
+       */
+      query(q) {
+        const built = _buildQuery(q);
+        return {
+          ref: built,
+          async find(filter, opts) {
+            return (await _readAll({ query: built })).filter((d) => matchesFilter(d, filter));
+          },
+          async findOne(filter, opts) {
+            const all = await _readAll({ query: built });
+            return all.find((d) => matchesFilter(d, filter)) || null;
+          },
+        };
+      },
+
+      async find(filter = {}, opts = {}) {
+        const { limit } = opts || {};
+        const docs = (await _readAll()).filter((d) => matchesFilter(d, filter));
+        return typeof limit === "number" ? docs.slice(0, limit) : docs;
+      },
+
+      async findOne(filter = {}, opts = {}) {
+        const { sortBy, sortDir = "asc" } = opts || {};
+        let docs = (await _readAll()).filter((d) => matchesFilter(d, filter));
+        if (sortBy) {
+          const dir = String(sortDir).toLowerCase() === "desc" ? -1 : 1;
+          docs = docs.sort((a, b) => {
+            const av = deepGet(a, sortBy);
+            const bv = deepGet(b, sortBy);
+            if (av === bv) return 0;
+            if (av == null) return 1;
+            if (bv == null) return -1;
+            return av > bv ? dir : -dir;
+          });
+        }
+        return docs[0] || null;
+      },
+
+      async insertOne(document, opts = {}) {
+        const { id } = opts || {};
+        const docToWrite = document && typeof document === "object" ? { ...document } : {};
+        delete docToWrite._id;
+        delete docToWrite.id;
+
+        if (id) {
+          const idStr = String(id);
+          await baseRef.child(idStr).set(docToWrite);
+          return { acknowledged: true, insertedId: idStr };
+        }
+
+        const newRef = baseRef.push();
+        await newRef.set(docToWrite);
+        return { acknowledged: true, insertedId: newRef.key };
+      },
+
+      async insertMany(documents, opts = {}) {
+        if (!Array.isArray(documents)) throw new TypeError("insertMany(documents) expects an array");
+        const ids = [];
+        for (const d of documents) {
+          // eslint-disable-next-line no-await-in-loop
+          const r = await this.insertOne(d, opts);
+          ids.push(r.insertedId);
+        }
+        return { acknowledged: true, insertedCount: ids.length, insertedIds: ids };
+      },
+
+      async updateOne(filter, update, opts = {}) {
+        const { upsert = false } = opts || {};
+        const found = await this.findOne(filter);
+        if (!found) {
+          if (!upsert) return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
+          const insertDoc = applyUpdateOperators({}, update);
+          const r = await this.insertOne(insertDoc);
+          return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: r.insertedId };
+        }
+
+        const next = applyUpdateOperators(found, update);
+        const { _id } = found;
+        const payload = { ...next };
+        delete payload._id;
+        await baseRef.child(String(_id)).set(payload);
+        return { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null };
+      },
+
+      async updateMany(filter, update, opts = {}) {
+        const docs = await this.find(filter);
+        if (!docs.length) return { acknowledged: true, matchedCount: 0, modifiedCount: 0 };
+
+        const updates = {};
+        for (const d of docs) {
+          const next = applyUpdateOperators(d, update);
+          const payload = { ...next };
+          delete payload._id;
+          updates[String(d._id)] = payload;
+        }
+        await baseRef.update(updates);
+        return { acknowledged: true, matchedCount: docs.length, modifiedCount: docs.length };
+      },
+
+      async replaceOne(filter, replacement, opts = {}) {
+        const { upsert = false } = opts || {};
+        const found = await this.findOne(filter);
+        if (!found) {
+          if (!upsert) return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
+          const r = await this.insertOne(replacement);
+          return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: r.insertedId };
+        }
+        const payload = replacement && typeof replacement === "object" ? { ...replacement } : {};
+        delete payload._id;
+        delete payload.id;
+        await baseRef.child(String(found._id)).set(payload);
+        return { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null };
+      },
+
+      async deleteOne(filter) {
+        const found = await this.findOne(filter);
+        if (!found) return { acknowledged: true, deletedCount: 0 };
+        await baseRef.child(String(found._id)).remove();
+        return { acknowledged: true, deletedCount: 1 };
+      },
+
+      async deleteMany(filter) {
+        const docs = await this.find(filter);
+        if (!docs.length) return { acknowledged: true, deletedCount: 0 };
+        const updates = {};
+        for (const d of docs) updates[String(d._id)] = null;
+        await baseRef.update(updates);
+        return { acknowledged: true, deletedCount: docs.length };
+      },
+
+      async countDocuments(filter = {}) {
+        const docs = await this.find(filter);
+        return docs.length;
+      },
+    };
+  }
+
+  return {
+    admin,
+    app,
+    db,
+    ref,
+    collection,
+  };
+}
+
+module.exports = {
+  initFirebaseRtdb,
+  getFirebaseRtdb,
+  // for advanced usage / tests
+  _internal: {
+    loadEnvFromFile,
+    parseDotEnv,
+    applyUpdateOperators,
+    matchesFilter,
+    createMongoLikeRtdbClient,
+  },
+};
+

package/src/helpers/json-mapper.js

@@ -0,0 +1,3 @@
+// Back-compat alias: earlier drafts referenced `json-mapper.js`.
+module.exports = require("./objectsMapper.js");
+