Registry / database / firestore-db-orm

firestore-db-orm

JSON →
library1.5.3jsnpmunverified

Firestore DB ORM is a lightweight, TypeScript-first ORM for Google Firestore (Firebase). It provides a promise-based API for CRUD operations, flexible querying, and automatic ID generation. The current stable version is 1.5.3, with weekly releases. Key differentiators include TypeScript type safety, automatic UUID generation, and a simple API for common Firestore interactions, targeting Node.js 20+. It does not support advanced Firestore features like transactions or batch writes.

npm install firestore-db-orm
INSTALL
IMPORT
SIG · FIRESTORE-DB-ORM
F
firestore-db-orm
databasejavascriptv1.5.3
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FirestoreORM
import { FirestoreORM } from 'firestore-db-orm'
const FirestoreORM = require('firestore-db-orm')
ESM-only package; CommonJS require will fail.

Initializes Firebase Admin, instantiates FirestoreORM for a 'users' collection, and demonstrates add, get, update, findOne, and delete operations.

import { initializeApp, cert } from 'firebase-admin/app'; import { getFirestore } from 'firebase-admin/firestore'; import { FirestoreORM } from 'firestore-db-orm'; // Initialize Firebase Admin with service account (use environment variable for key path) const serviceAccount = process.env.SERVICE_ACCOUNT_KEY ?? './serviceAccountKey.json'; initializeApp({ credential: cert(require(serviceAccount)) }); const db = getFirestore(); interface IUser { id?: string; name: string; email: string; age?: number; } const userORM = new FirestoreORM<IUser>(db, 'users'); async function main() { // Add a new user (id auto-generated) const newUser = await userORM.add({ name: 'Alice', email: 'alice@example.com' }); console.log('Added user:', newUser); // Get user by ID const user = await userORM.get(newUser.id!); console.log('Retrieved user:', user); // Update user await userORM.update(newUser.id!, { age: 30 }); // Find one user by email const foundUser = await userORM.findOne({ field: 'email', operator: '==', value: 'alice@example.com' }); console.log('Found user:', foundUser); // Delete user await userORM.delete(newUser.id!); } main().catch(console.error);
Debug
Known issues
gotchaThe `add` method automatically generates an `id` field using `uuid`. If your data model already has an `id` field, it will be overwritten.
fix
Ensure your data model does not include an `id` property, or use a different field name for your identifier.
affects: >=1.0.0
breakingNode.js 20+ is required. Using older Node versions will cause runtime errors due to unsupported features.
fix
Upgrade Node.js to version 20 or later.
affects: >=1.5.0
deprecatedThe `findOne` method uses a `SearchParams` object. In future versions, the API may change to support more query operators.
fix
None currently; refer to future changelogs.
affects: 1.x
gotchaThe ORM does not support transactions, batch writes, or Firestore security rules simulation. It is intended for simple CRUD operations only.
fix
For advanced use cases, use the Firestore Admin SDK directly.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'firestore-db-orm'
Package not installed or not in node_modules
fix
Run `npm install firestore-db-orm`
TypeError: FirestoreORM is not a constructor
Using CommonJS require instead of ESM import
fix
Use `import { FirestoreORM } from 'firestore-db-orm'` in an ESM context.
FirebaseError: Missing or insufficient permissions.
Firestore security rules or service account permissions not configured correctly
fix
Ensure your service account has appropriate Firestore roles (e.g., 'datastore.user') and that security rules allow operations.
Upgrade
Version history
1.5.3latest on npm
Audit
Dependencies
firebase-adminrequiredRequired to initialize Firestore instance used by ORM
uuidrequiredUsed internally for automatic ID generation
Agent activity
4 hits · last 30 days
node
4
Resources
firestore-db-orm — npm install firestore-db-orm · libregistry