{"id":16433853,"url":"https://github.com/brodanoel/firebase-firestore-helper","last_synced_at":"2026-05-08T01:49:08.016Z","repository":{"id":57236602,"uuid":"429239180","full_name":"BrodaNoel/firebase-firestore-helper","owner":"BrodaNoel","description":"Firebase Firestore Helper - DB access","archived":false,"fork":false,"pushed_at":"2024-03-03T13:08:54.000Z","size":221,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T17:25:30.196Z","etag":null,"topics":["backend","database","database-management","firebase","firestore","google-cloud","google-cloud-firestore","google-cloud-functions","google-cloud-platform","helper","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BrodaNoel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-18T00:05:47.000Z","updated_at":"2023-08-29T22:11:10.000Z","dependencies_parsed_at":"2024-12-17T19:42:45.677Z","dependency_job_id":"941dd3da-20f7-4384-ba63-940f9e44f860","html_url":"https://github.com/BrodaNoel/firebase-firestore-helper","commit_stats":{"total_commits":45,"total_committers":1,"mean_commits":45.0,"dds":0.0,"last_synced_commit":"55bef7afea7e11aff8f1c3ceba1c76b10d51b4a5"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrodaNoel%2Ffirebase-firestore-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrodaNoel%2Ffirebase-firestore-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrodaNoel%2Ffirebase-firestore-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrodaNoel%2Ffirebase-firestore-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrodaNoel","download_url":"https://codeload.github.com/BrodaNoel/firebase-firestore-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208371,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","database","database-management","firebase","firestore","google-cloud","google-cloud-firestore","google-cloud-functions","google-cloud-platform","helper","nodejs"],"created_at":"2024-10-11T08:47:26.605Z","updated_at":"2026-05-08T01:49:08.005Z","avatar_url":"https://github.com/BrodaNoel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Firebase Firestore Helper\n\n## Supports\n\n- `firebase-firestore-helper@^1.0.0` supports `firebase-admin@^8.0.0`\n- `firebase-firestore-helper@^2.0.0` supports `firebase-admin@^9.0.0`\n- `firebase-firestore-helper@^3.0.0` supports `firebase-admin@^10.0.0`\n- `firebase-firestore-helper@^4.0.0` supports `firebase-admin@^10.0.0`\n- `firebase-firestore-helper@^5.0.0` supports `firebase-admin@^11.0.0`\n- `firebase-firestore-helper@^6.0.0` supports `firebase-admin@^12.0.0`\n- `firebase-firestore-helper@^7.0.0` supports `firebase-admin@^13.0.0`\n\n## How to use it\n\n### Initializing the Helper\n\nIn your `./src/index.js` file (or whatever is called your root file), initialize the helper by doing:\n\n```js\nconst { initHelper } = require('firebase-firestore-helper');\n// import { initHelper } from 'firebase-firestore-helper';\n\ninitHelper();\n```\n\n### Using the Helper\n\nWhen `.add` function is called, it **must** receive an `id` inside the object to save, which is the one is going to be used as document id.\n\nWe recommend to use an `string` as ID (usually `uuid/v4`)\n\nSo, for example:\n\nAfter running this:\n\n```js\nconst { helperCreator } = require('firebase-firestore-helper');\n\nconst db = helperCreator({ entity: 'users' });\n\ndb.add({\n  id: 'asd123',\n  username: 'BrodaNoel',\n  age: 31,\n});\n```\n\nYour Firestore DB will look like:\n\n```json\n{\n  \"users\": {\n    \"asd123\": {\n      \"id\": \"asd123\",\n      \"username\": \"Broda Noel\",\n      \"age\": 31\n    }\n  }\n}\n```\n\n## Full Example, and recommended use\n\nYour folder tree should contain 3 important parts:\n\n```\n|-\u003e db\n|    |-\u003e users\n|    |-\u003e photos\n|    |-\u003e ...\n|-\u003e actions\n|    |-\u003e users\n|    |-\u003e photos\n|    |-\u003e ...\n|-\u003e app\n|    |-\u003e users\n|    |-\u003e photos\n|    |-\u003e ...\n|-\u003e index.js\n```\n\n- `index.js` will initialize the helper, by using `initHelper` function, just before you call `initializeApp` from `firebase-admin/app`\n- `db/users` will **expose** the object created by this library, which will handle the `users` collections in Firestore. You'll be able to override here.\n- `actions/users` will **use** the object exposed by `db/users`, and where you'll write all the business logic.\n- `app/*` is just the regular file where you are listeining for the `httpRequests`, which will user `actions/*` in order to handle business logic.\n\nIdeally, you will never user `db` files from `app` files.\n\n```js\n// db/users.js\nconst { helperCreator } = require('firebase-firestore-helper');\n\nconst ENTITY = 'users';\n\n// This will expouse all the functions of this library (check functions documentation)\nmodule.exports = {\n  // `useCache` is `true` BY DEFAULT!!!\n  ...helperCreator({ entity: ENTITY, useCache: true }),\n};\n```\n\n```js\n// actions/users.js\nconst { actionsHelperCreator } = require('firebase-firestore-helper');\nconst db = require('../db/users');\n\nconst login = async (email, password) =\u003e {\n  const user = await db.getBy({ where: { email }, limit: 1 });\n\n  if (!user || user.password !== password) {\n    // ...\n  }\n};\n\nmodule.exports = {\n  ...actionsHelperCreator(db),\n  login,\n};\n```\n\n```js\n// app/users.js\nconst actions = require('../actions/users');\n\nconst login = async (req, res) =\u003e {\n  const isPasswordCorrect = await actions.login(/* ... */);\n  // Your logic here\n  return req.send(/* ... */);\n}\n\nconst edit = async (req, res) =\u003e {\n  // Your logic here\n  const user = req.body.user;\n  const firstname = req.body.newData.firstname;\n  const lastname = req.body.newData.lastname;\n\n  await actions.editById(user.id, { firstname, lastname });\n  return req.send(/* ... */);\n}\n\nmodule.exports = app =\u003e {\n  app.post('/v1/user/login', login);\n  app.post('/v1/user/edit', edit);\n```\n\n## Creator Functions\n\nThese are the functions exposed by `firebase-firestore-helper`.\n\n### `helperCreator({ entity, useCache })`\n\nThis should be used in the `db` files.\n\n- `entity` is the collection name.\n- `useCache` is `true` by default. It will create a local cache. Very dangerous if you are editing `users` collection from another side, with no using this library.\n\nExample:\n\n```js\n// db/users.js\nconst { helperCreator } = require('firebase-firestore-helper');\n\n// This will expouse all the functions of this library (check functions documentation)\nmodule.exports = {\n  ...helperCreator({\n    entity: 'users',\n    // `useCache` is `true` BY DEFAULT!!!\n    useCache: true,\n  }),\n};\n```\n\n### `actionsHelperCreator(db)`\n\nThis should be used in the `actions` files.\n\nReceives only 1 parameter. The DB object created in the `db` file.\n\nExample:\n\n```js\n// actions/users.js\nconst { actionsHelperCreator } = require('firebase-firestore-helper');\nconst db = require('../db/users');\n\nconst login = async (email, password) =\u003e {\n  const user = await db.getBy({ where: { email }, limit: 1 });\n\n  if (!user || user.password !== password) {\n    // ...\n  }\n};\n\nmodule.exports = {\n  ...actionsHelperCreator(db),\n  login,\n};\n```\n\n## Firestore Functions (`db` object)\n\n### `add()`\n\nReceives an object, that **must** contain an `id`. It saves it in the DB.\n\n```js\ndb.add({\n  id: 'asd123',\n  username: 'BrodaNoel',\n});\n```\n\n### `getBy`\n\nJust a regular query.\n\n```js\n// These will return AN ARRAY (empty, or with elements)\ndb.getBy({ where: { username: 'BrodaNoel' } });\ndb.getBy({ where: { username: 'BrodaNoel' }, limit: 2 });\ndb.getBy({ where: { age: 10, status: 1 } });\ndb.getBy({ where: [{ age: 10 }, ['status', 'in', [1, 2, 3]]] });\ndb.getBy({ where: [{ age: 10 }, ['status', '\u003e=', 2]] });\n\n// This will return `null` or and `object` (because of limit === 1)\ndb.getBy({ where: { username: 'BrodaNoel' }, limit: 1 });\n\n// Select just some parts of the resulting object (SQL: SELECT id, name, FROM...)\ndb.getBy({ where: { age: 10 }, select: 'id' });\ndb.getBy({ where: { age: 10 }, select: ['id', 'name'] });\n\n// Add orders\ndb.getBy({ where: { age: 10 }, orderBy: 'createdAt' });\ndb.getBy({ where: { age: 10 }, orderBy: ['createdAt', 'desc'] });\ndb.getBy({\n  where: { age: 10 },\n  orderBy: [\n    ['createdAt', 'desc'],\n    ['age', 'asc'],\n  ],\n});\n```\n\n### `getById`\n\nEasy one.\n\n```js\n// Returns null or the object\ndb.getById('ads123');\n```\n\n### `getAll`\n\nEasy one.\n\n```js\n// Always an array, empty or with items\ndb.getAll();\n```\n\n### `deleteById`\n\nEasy one. Deletes a document. Say goodbye. Not able to get back.\n\nWe maaaay add `removeById` in the future, which will add a status to \"hide\" the document, instead of removing it. \"\"\"@TODO\"\"\"\n\n```js\ndb.deleteById('ads123');\n```\n\n### `editById`\n\nReceives and `id` and the `newData` object. It works as a merge. (firebase `update()`)\n\n```js\ndb.editById('ads123', { age: 32 });\n```\n\n### `clearCache`\n\nJust clean the cache, in case of necessary.\n\n```js\ndb.clearCache();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrodanoel%2Ffirebase-firestore-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrodanoel%2Ffirebase-firestore-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrodanoel%2Ffirebase-firestore-helper/lists"}