{"id":15566861,"url":"https://github.com/git-marcopitra/burnbase","last_synced_at":"2025-06-21T20:05:24.194Z","repository":{"id":214117909,"uuid":"732231177","full_name":"git-marcopitra/burnbase","owner":"git-marcopitra","description":"Firebase wrapper to provide a better DevX","archived":false,"fork":false,"pushed_at":"2025-05-18T07:40:47.000Z","size":68,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-18T08:31:49.716Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-marcopitra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-12-16T01:54:07.000Z","updated_at":"2024-08-07T14:09:41.000Z","dependencies_parsed_at":"2023-12-29T02:21:47.069Z","dependency_job_id":"1b13b92c-7fe8-4a1e-b25a-04fc9e726ee1","html_url":"https://github.com/git-marcopitra/burnbase","commit_stats":null,"previous_names":["git-marcopitra/burnbase"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/git-marcopitra/burnbase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-marcopitra%2Fburnbase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-marcopitra%2Fburnbase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-marcopitra%2Fburnbase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-marcopitra%2Fburnbase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-marcopitra","download_url":"https://codeload.github.com/git-marcopitra/burnbase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-marcopitra%2Fburnbase/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260930995,"owners_count":23084780,"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":[],"created_at":"2024-10-02T17:07:40.661Z","updated_at":"2025-06-21T20:05:19.175Z","avatar_url":"https://github.com/git-marcopitra.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BURNBASE\n\nBurnbase is a firebase (module-based) wrapper, to handle the functions in an easier way, with a lot of utils as lib plus\n\n**OBS:** _We are in the alpha version, so something can break, we'll release the first Beta version, once we have everything well tested._\n\n## How to install\n\nYou can install the package on your js-based project with:\n\n### pnpm\n\n```bash\npnpm add burnbase@alpha # yarn-like\n# or\npnpm install burnbase@alpha # npm-like\n```\n\n### yarn\n\n```bash\nyarn add burnbase@alpha\n```\n\n### npm\n\n```bash\nnpm add burnbase@alpha\n```\n\n## How to use\n\n### Init\n\nIn your burnbase folder (api | service | ...), you must create a file with the init scripts exposed on `burnbase/app`:\n\n`/src/api/init.ts`\n\n```ts\nimport { init } from \"burnbase/app\";\n\nexport const firebaseConfig = {\n  apiKey: FIREBASE_API_KEY,\n  authDomain: FIREBASE_AUTH_DOMAIN,\n  projectId: FIREBASE_PROJECT_ID,\n  storageBucket: FIREBASE_STORAGE_BUCKET,\n  messagingSenderId: FIREBASE_MESSAGING_SENDER_ID,\n  appId: FIREBASE_APP_ID,\n};\n\ninit(firebaseConfig);\n```\n\nNote that, `firebaseConfig` constant has the same format of firebase one, so all properties are optional according with what you need to config, or you will use.\n\nAnd then you have the **burnbase** `init` function, that wraps all firebase app creation flow.\n\nKnowing that, you ready to import this code on your main file, warranting that you always has the app in all the code.\n\n`/src/main.ts`\n\n```ts\nimport '../api/init';\n\n...\n```\n\nNow, you are able to use any burnbase and firebase function in your code.\n\n### Auth\n\nFor Firebase Auth, we have the following functions on `burnbase/auth`:\n\n- `getLoggedInUser`;\n- `loginWithEmailAndPassword`;\n- `resetPassword`;\n- `createUser`;\n- `logout`.\n\n#### `getLoggedInUser`\n\nThis function returns the `currentUser` as Firebase **User**.\n\n`./get-current-user.ts`\n\n```ts\nimport { getLoggedInUser } from 'burnbase/auth';\n\nexport const getCurrentUser = async () =\u003e {\n  const currentUser = await getLoggedInUser();\n\n  ...\n\n  return currentUser;\n};\n```\n\n#### `loginWithEmailAndPassword`\n\nThis function returns the `userCredentialInfo` as Firebase **UserCredential**, expecting 2-3 params.\n\n##### Usage (`loginWithEmailAndPassword`)\n\nPassing only the email and password, you can login with an existing account on Firebase auth.\n\n`./login.ts`\n\n```ts\nimport { loginWithEmailAndPassword } from 'burnbase/auth';\n\nexport const login = async (email: string, password: string) =\u003e {\n  const user = await loginWithEmailAndPassword(user, password);\n\n  ...\n\n  return user;\n};\n```\n\n##### Advanced Usage (`loginWithEmailAndPassword`)\n\nPassing options after passing the email and password, you can login with an existing account on Firebase auth, and verify if this account exists on `firestoreCollectionName` in options, and if you want you can add many more conditions to the `firestoreCondition` list.\n\n`./login.ts`\n\n```ts\nimport { loginWithEmailAndPassword } from 'burnbase/auth';\n\nexport const login = async (email: string, password: string) =\u003e {\n  const user = await loginWithEmailAndPassword(\n    user,\n    password,\n    {\n      firestoreCollectionName: 'userCollection' // it will verify if the email exists on this collection, on prop email\n    }\n  );\n\n  ...\n\n  return user;\n};\n```\n\n```ts\nimport { loginWithEmailAndPassword } from \"burnbase/auth\";\n\nconst login = async (email: string, password: string) =\u003e {\n  const user = await loginWithEmailAndPassword(user, password, {\n    firestoreCollectionName: \"userCollection\",\n    firestoreCondition: [\n      [\"role\", \"==\", \"admin\"], // it will verify if the property role is equal to \"admin\"\n      [\"status\", \"\u003e\", 0], // it will verify if the property status is greater than 0 (in my case, means active).\n    ],\n  });\n\n  return user;\n};\n```\n\n#### `resetPassword`\n\nThis function will update the password in your Firebase Auth, expecting an Firebase **User** and a new `string` password\n\n`./renew-password.ts`\n\n```ts\nimport { resetPassword } from \"burnbase/auth\";\nimport type { User } from \"firebase/auth\";\n\nconst renewPassword = async (user: User, newPassword) =\u003e {\n  await resetPassword(user, newPassword);\n};\n```\n\n#### `logout`\n\nThis function will kill the current user session.\n\n`./logout.ts`\n\n```ts\nimport { logout } from \"burnbase/auth\";\n\nconst logoff = async () =\u003e {\n  await logout();\n};\n```\n\n### Firestore\n\nFor Firebase Firestore, we have the following functions on `burnbase/firestore`:\n\n- `getAllData`;\n- `getPagination`;\n- `getCollection`;\n- `getCollectionRef`;\n- `getDocument`;\n- `setDocument`;\n- `updateDocument`;\n- `addDocument`;\n- `deleteDocument`;\n- `getCollectionSize`;\n- `mapQueryParams`.\n\n#### Understanding `queryParams`\n\n`queryParams` is an object parameter composed by:\n\n- `pagination`;\n- `conditions`;\n- `ordinateBy`.\n\n##### `pagination`\n\nPagination is an optional object and `undefined` by default, and there is some utils attributes:\n\n| Attribute          |                                                                                                 Structure |\n| :----------------- | --------------------------------------------------------------------------------------------------------: |\n| `limit`            |                                                           `number` - the limit of the data that you need. |\n| `page`             |                                            `number` (optional) - the exact page that you are looking for. |\n| `target`           |              `\"next\"` or `\"previous\"` (optional) - asks for next or previous page, based on current page. |\n| `targetDocument`\\* |    `QueryDocumentSnapshot\u003cDocumentData\u003e` (optional) - the target document that you must have in the list. |\n| `firstItem`\\*      | `ReadonlyArray\u003cQueryDocumentSnapshot\u003cDocumentData\u003e\u003e` (option) - a list of all pages first items elements. |\n\n**_Note:_** \\* _means that the attribute is mostly for internal use, but is ok if you find a nice tricky to use it by your own, or maybe improve the code xD._\n\n##### `conditions`\n\nConditions is an optional list and `undefined` by default, and it's structure is basically based on an array with 3 position:\n\n`[\u003cfield-name\u003e, \u003coperator\u003e, \u003cvalue\u003e]`\n\nWhere:\n\n- `\u003cfield-name\u003e`: is a `string` that represents the attribute on document;\n- `\u003coperator\u003e`: is a `WhereFilterOp` that represents the operation properly;\n- `\u003cvalue\u003e`: is an `unknown` value, that represents the matching value that you want.\n\nEx.1: Checking if the role is equal to `admin`.\n`['role', '==', 'admin']`\n\nEx.2: Checking if the position represents the podium, that can be 1, 2 oe 3.\n`['position', 'in', [1, 2, 3]]`\n\nAnd then after you understand how conditions works, you can combine them into a list of conditions.\n\n##### `ordinateBy`\n\nThis is the sorting field, that expect a list of sorting objects, that is represented by a `label` and a `orderDirection`.\n\nEx.: `ordinate: [{ label: \"date\" }, { label: \"position\", orderDirection: \"desc\" }]`\n\nWhere:\n\n- `label`: is a required `string` that presents the field to sort;\n- `orderDirection`: is an optional field that by default it's `'asc'`, and you can change to `'desc'`.\n\n#### `getCollectionRef`\n\nThis function expects a collection name, it will return a `CollectionReference\u003cDocumentData\u003e` of the collection.\n\n##### Usage (`getCollectionRef`)\n\n`./get-admin-ref.ts`\n\n```ts\nimport { getCollectionRef } from \"burnbase/firestore\";\n\nconst getAdminRef = async () =\u003e {\n  await getCollectionRef(\"admin\");\n};\n```\n\n#### `getCollectionSize`\n\nThis function expects a collection name and a query if needed, it will return the size of the collection\n\n##### Usage (`getCollectionSize`)\n\n`./get-admin-size.ts`\n\n```ts\nimport { getCollectionSize } from \"burnbase/firestore\";\n\nconst getAdminRef = async () =\u003e {\n  await getCollectionSize(\"admin\");\n};\n```\n\n##### Advanced Usage (`getCollectionSize`)\n\n`./get-admin-size.ts`\n\n```ts\nimport { getCollectionSize } from \"burnbase/firestore\";\n\nconst getActivesAdminsSize = async () =\u003e {\n  await getCollectionSize(\"admin\", {\n    conditions: [[\"active\", \"==\", true]],\n    ordinateBy: [{ label: \"createdAt\" }],\n  });\n};\n```\n\n#### `getCollection`\n\nThis function expects a collection name and a query if needed, it will return a list of the data on the collection, with the respective `uid`.\n\n##### Usage (`getCollection`)\n\n`./get-clients.ts`\n\n```ts\nimport { getCollection } from \"burnbase/firestore\";\n\nconst getClients = async () =\u003e {\n  await getCollection\u003cClient\u003e(\"clients\");\n};\n```\n\n##### Advanced Usage (`getCollection`)\n\n`./get-clients.ts`\n\n```ts\nimport { getCollection } from \"burnbase/firestore\";\n\nconst getActiveClients = async () =\u003e {\n  await getCollection\u003cClient\u003e(\"clients\", {\n    conditions: [[\"active\", \"==\", true]],\n    ordinateBy: [{ label: \"createdAt\" }],\n  });\n};\n```\n\n#### `getAllData`\n\nThis function expects a collection name and then a query if needed, it will return all the data on the collection.\n\n##### Usage (`getAllData`)\n\n`./get-users.ts`\n\n```ts\nimport { getAllData } from \"burnbase/firestore\";\n\nconst getUsers = async () =\u003e {\n  await getAllData(\"users\")();\n};\n```\n\n##### Advanced Usage (`getAllData`)\n\n`./get-admins-sorted.ts`\n\n```ts\nimport { getAllData } from \"burnbase/firestore\";\n\nconst getAdminsSorted = async () =\u003e {\n  await getAllData(\"users\")({\n    conditions: [[\"role\", \"==\", \"admin\"]],\n    ordinateBy: [{ label: \"name\", orderDirection: \"asc\" }],\n  });\n};\n```\n\n`./get-strict-admin-list.ts`\n\n```ts\nimport { getAllData } from \"burnbase/firestore\";\n\nconst getStrictAdminList = async () =\u003e {\n  await getAllData(\"users\")({\n    pagination: { limit: 5, page: 1 },\n    conditions: [[\"role\", \"==\", \"admin\"]],\n    ordinateBy: [{ label: \"name\", orderDirection: \"asc\" }],\n  });\n};\n```\n\n#### `getPagination`\n\nThis function expects a collection name with an optional dataCallback (a transformer function that expects the `QueryDocumentSnapshot\u003cDocumentData, DocumentData\u003e`), and then a query if needed, it will return all the data on the collection.\n\n##### Usage (`getPagination`)\n\n`./get-activities.ts`\n\n```ts\nimport { getPagination } from \"burnbase/firestore\";\n\nconst getActivities = async () =\u003e {\n  const {\n    data, // page data\n    page, // current page (number)\n    next, // handler function to ask the next page\n    previous, // handler function to ask the previous page\n  } = await getPagination(\"activities\")();\n\n  ...\n};\n```\n\n##### Advanced Usage (`getPagination`)\n\n`./get-activities.ts`\n\n```ts\nimport { getPagination } from \"burnbase/firestore\";\n\nconst getActiveActivities = async (defaultPage: number, pageLimit: number) =\u003e {\n  const {\n    data, // page data\n    page, // current page\n    next, // handler function to ask the next page\n    previous, // handler function to ask the previous page\n  } = await getPagination(\"activities\")({\n    pagination: {\n      limit: pageLimit,\n      page: defaultPage\n    },\n    conditions: [[\"active\", \"==\", true]],\n    ordinateBy: [{ label: \"updatedAt\", orderDirection: \"asc\" }],\n  });\n\n  ...\n};\n```\n\n#### `getDocumentRef`\n\nThis function expects a collection name and the docId, it will return a `DocumentReference\u003cDocumentData\u003e` of the collection.\n\n##### Usage (`getDocumentRef`)\n\n`./get-admin-ref.ts`\n\n```ts\nimport { getDocumentRef } from \"burnbase/firestore\";\n\nconst getAdminRef = async (docId: string) =\u003e {\n  await getDocumentRef(\"admin\", docId);\n};\n```\n\n#### `getDocument`\n\nThis function expects a collection name and the docId, it will return the data of the document.\n\n##### Usage (`getDocument`)\n\n`./get-admin.ts`\n\n```ts\nimport { getDocument } from \"burnbase/firestore\";\n\nconst getAdmin = async (docId: string) =\u003e {\n  await getDocument(\"admin\", docId);\n};\n```\n\n#### `setDocument`\n\nThis function expects a collection name, a docId, and the data. It will create a new document with in the docId with this data.\n\n##### Usage (`setDocument`)\n\n`./set-admin.ts`\n\n```ts\nimport { setDocument } from \"burnbase/firestore\";\n\nconst setAdmin = async (docId: string, data: Admin) =\u003e {\n  await setDocument(\"admin\", docId, data);\n};\n```\n\n#### `addDocument`\n\nThis function expects a collection name, and the data. It will create a new document in with a random docId with this data.\n\n##### Usage (`addDocument`)\n\n`./add-admin.ts`\n\n```ts\nimport { addDocument } from \"burnbase/firestore\";\n\nconst addAdmin = async (data: Admin) =\u003e {\n  await addDocument(\"admin\", data);\n};\n```\n\n#### `deleteDocument`\n\nThis function expects a collection name, and the docId. It will delete the document in this docId. \n\n##### Usage (`deleteDocument`)\n\n`./delete-user.ts`\n\n```ts\nimport { deleteDocument } from \"burnbase/firestore\";\n\nconst deleteUser = async (data: User) =\u003e {\n  await deleteDocument(\"admin\", \"NlzIlLHFMcbmtK8ORodq9TvmDFR2\");\n};\n```\n\n#### `updateDocument`\n\nThis function expects a collection name, a docId, and the data. It will update the data in docId.\n\n_Note:_ The data can be only the field that you want to update\n\n##### Usage (`updateDocument`)\n\n`./update-admin.ts`\n\n```ts\nimport { updateDocument } from \"burnbase/firestore\";\n\nconst updateAdmin = async (docId: string, data: Partial\u003cAdmin\u003e) =\u003e {\n  await updateDocument(\"admin\", docId, data);\n};\n```\n\n### Storage\n\nFor Firebase Storage, we have the following functions on `burnbase/storage`:\n\n- `addFile`;\n- `deleteFile`.\n\n#### `addFile`\n\nThis function expects a file, a path, and the options if needed. It will save the File inside the path, and will return the download URL.\n\n##### Usage (`addFile`)\n\n`./add-image.ts`\n\n```ts\nimport { addFile } from \"burnbase/storage\";\n\nconst addImage = async (image: File) =\u003e {\n  const link = await addFile(image, \"pictures\");\n\n  ...\n};\n```\n\n##### Advanced Usage (`addFile`)\n\n`./add-profile-image.ts`\n\n```ts\nimport { addFile } from \"burnbase/storage\";\n\nconst addProfileImage = async (image: File) =\u003e {\n  const link = await addFile(image, \"pictures\", {\n    prefix: 'profile',\n    suffix: 'image',\n    metadata: { // You can find more usage on the typing\n      customMetadata: {\n        name: 'profile-image',\n        createdAt: Date.now()\n      }\n    }\n  });\n\n  ...\n};\n```\n\n#### `deleteFile`\n\nThis function expects a storage url. It will delete the file.\n\n##### Usage (`deleteFile`)\n\n`./delete-image.ts`\n\n```ts\nimport { deleteFile } from \"burnbase/storage\";\n\nconst deleteImage = async (url: string) =\u003e {\n  await deleteFile(url);\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-marcopitra%2Fburnbase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-marcopitra%2Fburnbase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-marcopitra%2Fburnbase/lists"}