{"id":15019368,"url":"https://github.com/freshfox/firestore-storage","last_synced_at":"2025-04-14T14:10:50.309Z","repository":{"id":30819945,"uuid":"125522976","full_name":"freshfox/firestore-storage","owner":"freshfox","description":"A typed wrapper around Firestore incluing a querybuilder and an in-memory implementation for testing","archived":false,"fork":false,"pushed_at":"2024-07-24T14:02:56.000Z","size":1894,"stargazers_count":38,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-29T23:07:28.572Z","etag":null,"topics":["firebase","firestore","inversify","repository-pattern"],"latest_commit_sha":null,"homepage":"https://firebaseopensource.com/projects/freshfox/firestore-storage/","language":"TypeScript","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/freshfox.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2018-03-16T13:54:57.000Z","updated_at":"2024-08-06T20:06:56.000Z","dependencies_parsed_at":"2023-10-14T19:05:30.330Z","dependency_job_id":"bcddb9d2-e2de-4422-ad73-ad69c68813dc","html_url":"https://github.com/freshfox/firestore-storage","commit_stats":{"total_commits":451,"total_committers":2,"mean_commits":225.5,"dds":0.006651884700665134,"last_synced_commit":"49dea4ba2e65b4702eeb2c840d7c3a32afce493b"},"previous_names":[],"tags_count":154,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshfox%2Ffirestore-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshfox%2Ffirestore-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshfox%2Ffirestore-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freshfox%2Ffirestore-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freshfox","download_url":"https://codeload.github.com/freshfox/firestore-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248894939,"owners_count":21179152,"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":["firebase","firestore","inversify","repository-pattern"],"created_at":"2024-09-24T19:53:23.460Z","updated_at":"2025-04-14T14:10:50.273Z","avatar_url":"https://github.com/freshfox.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Firestore Storage\n[![Build Status](https://github.com/freshfox/firestore-storage/actions/workflows/main.yml/badge.svg)](https://github.com/freshfox/firestore-storage/actions)\n\nTypesafe repositories around Firestore providing a straightforward API to read and write documents.\n\n## Usage\n```bash\nnpm i firestore-storage-core firestore-storage\n```\n\n```typescript\nimport { BaseModel } from 'firebase-storage-core';\nimport { initializeApp } from 'firebase-admin/app';\nimport { getFirestore } from 'firebase-admin/firestore';\ninitializeApp();\n\n// restaurants/{restaurantId}\nconst restaurantRepo = new RestaurantRepository(getFirestore());\n\nconst restaurant = await restaurantRepo.save({\n\tname: 'FreshFoods',\n\ttype: 'vegan'\n});\nconsole.log(restaurant);\n/*\n{\n  id: '0vdxYqEisf5vwJLhyLjA',\n  name: 'FreshFoods',\n  _rawPath: 'restaurants/0vdxYqEisf5vwJLhyLjA'\n}*/\n\n// Query restaurants based on properties\nawait restaurantRepo.list({\n\ttype: 'vegan'\n});\n\n// More complex queries\nawait restaurantRepo.query((qb) =\u003e {\n\treturn qb\n\t\t.where((r) =\u003e r.type, '==', 'steak')\n\t\t.where((r) =\u003e r.address.city, '==', 'NY')\n});\n```\nThe properties `id` and `_rawPath` from `BaseModel` are dynamically added during reads\nand removed before writes.\n\n### Nested collections\n\nWhen working with nested collections, read and write methods require a parameter\nto supply a map of all parent document ids\n```typescript\n// restaurants/{restaurantId}/reviews/{reviewId}\nconst reviewRepo = new ReviewRepository(getFirestore());\n\nconst review = await reviewRepo.save({\n\tuserId: 'my-user-uid-123',\n\tstars: 5\n}, {\n\trestaurantId: '0vdxYqEisf5vwJLhyLjA'\n});\nconsole.log(review);\n/*\n{\n  id: 'a393f73b884c4a0981c0',\n  userId: 'my-user-uid-123',\n  stars: 5\n  _rawPath: 'restaurants/0vdxYqEisf5vwJLhyLjA/reviews/a393f73b884c4a0981c0'\n}*/\n```\n\n## Defining collections and repositories\n\nCreate repository classes for each collection you want to query documents from. For example,\nif you want to query documents to query from the `users` collection you create a class `UserRepository` extending `BaseRepository`.\nEach repository provides a list of functions for saving, querying and deleting documents,\nand you can extend each repository based on your needs.\n\n```typescript\nexport namespace Collections  {\n  // To define restaurants/{restaurantId}.\n  export const Restaurants = new CollectionPath(\n    // Name of the collection\n    'restaurants',\n    // Template variable name and property name on the id map\n    'restaurantId');\n\n  // When defining nested collections a few generics are required\n  // restaurants/{restaurantId}/reviews/{reviewId}\n  export const Restaurants_Reviews = new CollectionPath\u003c\n    // Template variable\n    'reviewId',\n    // Type of the id on the model\n    string,\n    // Type of the id map from the parent collection\n    DocumentIds\u003ctypeof Restaurants\u003e\n  \u003e(\n    // Name of the collection\n    'reviews',\n    // Template variable name and property name on the id map\n    'reviewId',\n    // Path of the parent collection\n    Restaurants\n  );\n}\n```\n```typescript\n// Path to document: restaurants/0vdxYqEisf5vwJLhyLjA/reviews/a393f73b884c4a0981c0\nCollections.Restaurants_Reviews.doc({\n  restaurantId: '0vdxYqEisf5vwJLhyLjA',\n  reviewId: 'a393f73b884c4a0981c0'\n})\n\n// Path to collection: restaurants/0vdxYqEisf5vwJLhyLjA/reviews\nCollections.Restaurants_Reviews.collection({\n  restaurantId: '0vdxYqEisf5vwJLhyLjA'\n})\n\n// Path template: restaurants/{restaurantId}/reviews/{reviewId}\nCollections.Restaurants_Reviews.path();\n\n// Parse ids from path\nCollections.Restaurants_Reviews.parse(\n  'restaurants/0vdxYqEisf5vwJLhyLjA/reviews/a393f73b884c4a0981c0'\n);\n/**\n * {\n *   restaurantId: '0vdxYqEisf5vwJLhyLjA',\n *   reviewId: 'a393f73b884c4a0981c0'\n * }\n */\n```\n\n### Creating repositories\n\n```typescript\nimport { BaseRepository } from 'firestore-storage';\nimport { Repository } from 'firestore-storage-core';\n\ninterface Review {\n\tuserId: string;\n\tstars: number;\n}\n\n@Repository({\n\tpath: Collections.Restaurants_Reviews\n})\nexport class ReviewRepository extends BaseRepository\u003cReview, typeof Collections.Restaurants_Reviews\u003e {\n\n\tconstructor() {\n\t\tsuper(getFirestore());\n\t}\n}\n```\n\n### Return value conventions for methods\n\n- `find*()` methods return the document or null when no result was found\n- `get*()` methods always return the document and will throw an error when no result was found\n- `list*()` methods always return an array and never null. When no result is found, the array is empty\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreshfox%2Ffirestore-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreshfox%2Ffirestore-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreshfox%2Ffirestore-storage/lists"}