A basic, extensible ORM (Object-Relational Mapper) / ODM (Object-Document Mapper) for the Firebase Admin SDK in Node.js, built with TypeScript. Simplifies interacting with Firestore using classes, decorators, Zod validation, and relationship handling (DocumentReference).
Key Features:
- Model Definition with Classes: Use TypeScript classes to define your data structures.
- Decorators (
@Collection,@Relation): Declare metadata in a clear, declarative way. - Simplified CRUD Operations:
save(),update(),delete(),findById(),findAll(),findOne(),findWhere(). - Relationship Handling: Store
DocumentReferenceand populate related data on demand. - Zod Validation: Define a
static schemaon your models for automatic validation before save/update. - Hooks (Lifecycle Callbacks): Run custom logic before/after operations (
beforeSave,afterLoad, etc.). - Pagination: Support for
limitandstartAfterinfindAll. - Strongly Typed: Written in TypeScript for better DX and type safety.
npm install fireodm firebase-admin reflect-metadata zod
# ou
yarn add fireodm firebase-admin reflect-metadata zodPeer Dependencies:
firebase-admin: The Firebase Admin SDK (peer dependency).reflect-metadata: Required for decorators to work (peer dependency).zod: Used for schema validation (peer dependency).
You MUST import reflect-metadata once in your application's entry point, before any other code that uses this library or decorators.
// src/index.ts or src/server.ts (or wherever your app starts)
import 'reflect-metadata';
// ... rest of your application initializationBefore using any ORM model, you need to initialize firebase-admin and provide the Firestore instance to the library:
import 'reflect-metadata'; // at the top!
import * as admin from 'firebase-admin';
import { setFirestoreInstance } from 'fireodm'; // replace with your package name
// 1. Initialize Firebase Admin (using your credentials)
admin.initializeApp({
// credential: admin.credential.applicationDefault(), // e.g. using ADC
// credential: admin.credential.cert(serviceAccount), // e.g. using service account key
// databaseURL: 'https://<YOUR_PROJECT_ID>.firebaseio.com' // optional
});
// 2. Get the Firestore instance
const db = admin.firestore();
// (Optional) Firestore settings
// db.settings({ ignoreUndefinedProperties: true });
// 3. Provide the instance to the ORM
setFirestoreInstance(db);
console.log('Firebase Admin initialized and ORM configured.');
// Now you can import and use your ORM-defined models
// import { User } from './models/User';
// ... your application code ...This library uses Jest for testing and relies on the Firestore Emulator for local development.
- Install Firebase CLI: If you haven't already, install the Firebase CLI globally:
npm install -g firebase-tools
- Run Tests: In your main terminal, run the test command. This command will run the firestore emulator and the tests:
npm test # or yarn test
(Add clear examples here showing how to define a model, create, read, update, delete, use relations, validation, and hooks. Use the code from examples/ as a reference).
import {
ArrayField,
BooleanField,
DocumentReferenceField,
EmailField,
NumberField,
StringField,
TimestampField,
} from "fireodm";
@Collection("departments")
export class Department extends BaseModel {
@StringField({ min: 1 })
name!: string;
@StringField({ required: false })
location?: string;
constructor(data: Partial<Department>, id?: string) {
super(data, id);
}
}
@Collection("users")
export class User extends BaseModel {
@StringField({ min: 1, required: true })
name!: string;
@EmailField()
email!: string;
@NumberField({ min: 0, max: 120 })
age?: number;
@BooleanField({ defaultValue: true })
isActive!: boolean;
@TimestampField({ required: false })
lastLogin?: Timestamp;
@ArrayField(z.string(), { required: false })
tags?: string[];
@NumberField({ min: 0, required: false })
loginCount?: number;
@StringField({ required: false })
hookValue?: string;
@TimestampField({ autoFill: true, required: false })
createdAt?: Timestamp;
@TimestampField({ autoFill: true, required: false })
updatedAt?: Timestamp;
@DocumentReferenceField({ required: false })
@Relation(() => Department)
department?: DocumentReference | Department | null;
@DocumentReferenceField({ required: false })
@Relation(() => User)
manager?: DocumentReference | User | null;
constructor(data: Partial<User>, id?: string) {
super(data, id);
}
}const newUser = new User({ name: 'Test User', email: '[email protected]' });
try {
await newUser.save();
console.log('User created with ID:', newUser.id);
} catch (error) {
if (error instanceof ValidationError) {
console.error('Validation failed:', error.issues);
} else {
console.error('Failed to save user:', error);
}
}// By ID
const user = await User.findById('some-user-id');
// By ID with Relations Populated
const userWithDept = await User.findById('some-user-id', { populate: ['department'] });
if (userWithDept?.department instanceof Department) {
console.log(userWithDept.department.name);
}
// All (with pagination)
const { results, lastVisible } = await User.findAll({ limit: 10, orderBy: { field: 'name' } });
// Next page
if (lastVisible) {
const nextPage = await User.findAll({ limit: 10, orderBy: { field: 'name' }, startAfter: lastVisible });
}
// Simple Condition
const activeAdmins = await User.findWhere('tags', 'array-contains', 'admin', {
queryFn: (ref) => ref.where('isActive', '==', true) // Combines findWhere with queryFn
});
// Complex Query
const recentUsers = await User.findOne(
(ref) => ref.orderBy('createdAt', 'desc').limit(1)
);const user = await User.findById('some-user-id');
if (user) {
await user.update({ name: 'Updated Name', /* ... other fields ... */ });
}const user = await User.findById('some-user-id'); // Fetch without populating relations
if (user) {
await user.populate('department'); // Populates the 'department' relation
if (user.department instanceof Department) {
// ... use user.department.name ...
}
}const user = await User.findById('some-user-id');
if (user) {
await user.delete();
}You can perform atomic operations by using the ORM's save, update, and delete methods within Firestore Transactions or Batched Writes.
- Return Value: When passing a transaction or batch object to
save,update, ordelete, the methods returnPromise<void>(indicating the operation was queued) instead ofPromise<WriteResult>. afterHooks Skipped: Lifecycle hooks likeafterSave,afterUpdate, andafterDeleteare NOT executed automatically when using transactions or batches. This is because the operation is only finalized upon committing the transaction/batch externally. You must handle any post-commit logic yourself.beforeHooks & Validation: Lifecycle hooks likebeforeSave,beforeUpdate,beforeDelete, and Zod validation ARE executed before the operation is added to the transaction or batch.
Pass the transaction object provided by db.runTransaction() to the ORM methods. Remember to perform all reads before writes within the transaction callback.
import { getFirestoreInstance, User, Department, Timestamp } from 'fireodm';
const db = getFirestoreInstance();
try {
const result = await db.runTransaction(async (transaction) => {
// --- Reads FIRST ---
const userRef = User.getCollectionRef().doc('userId123');
const userSnap = await transaction.get(userRef); // Use transaction.get()
if (!userSnap.exists) {
throw new Error("Transaction failed: User not found!");
}
// Create ORM instance from snapshot data within the transaction
const userInstance = new User(userSnap.data() as Partial<User>, userSnap.id);
// --- Writes SECOND ---
const updateData = { name: 'Updated in Tx', lastLogin: Timestamp.now() };
// Pass the transaction object to the ORM method
await userInstance.update(updateData, transaction); // Returns Promise<void>
// You can add other ORM operations to the same transaction
const newDept = new Department({ name: `Dept for ${userInstance.name}`});
await newDept.save(transaction); // Returns Promise<void>
return { success: true, newDeptId: newDept.id }; // Return value from runTransaction
});
console.log("Transaction successful:", result);
} catch (error) {
console.error("Transaction failed:", error);
}Create a WriteBatch using db.batch() and pass the batch object to the ORM methods. Commit the batch using batch.commit().
import { getFirestoreInstance, User, Department, WriteResult } from 'fireodm';
const db = getFirestoreInstance();
const batch = db.batch(); // Create a batch
try {
// Prepare instances (no reads needed for batch)
const userToUpdate = new User({}, 'userId1'); // Instance with ID for update
const newUser = new User({ name: 'Batch User', email: '[email protected]' }); // New user
const userToDelete = new User({}, 'userToDeleteId'); // Instance with ID for delete
// Add ORM operations to the batch
await userToUpdate.update({ name: 'Updated in Batch', tags: ['batch-op'] }, batch); // Returns Promise<void>
await newUser.save(batch); // Returns Promise<void>, ID is assigned before adding
await userToDelete.delete(batch); // Returns Promise<void>
// Commit all operations atomically
const results: WriteResult[] = await batch.commit();
console.log(`Batch committed successfully with ${results.length} writes.`);
} catch (error) {
console.error("Batch commit failed:", error);
}FireODM provides several decorators that can be applied to model properties. These decorators enable automatic validation and advanced behaviors using Zod.
Below is a list of all available decorators:
Defines a property as a string with optional constraints.
Options:
min: minimum number of charactersmax: maximum number of charactersmessage: custom error messagerequired: whether the field is required (default:false)
Example:
@StringField({ min: 3, max: 50, required: true })
name!: string;Validates that the property is a valid email address.
Options:
message: custom error message (default:"Invalid email")required: whether the field is required (default:false)
Example:
@EmailField()
email?: string;Defines a property as a number with optional constraints.
Options:
min: minimum valuemax: maximum valuemessage: custom error messagerequired: whether the field is required (default:false)
Example:
@NumberField({ min: 0 })
age?: number;Defines a property as a boolean, with optional default value.
Options:
required: whether the field is required (default:false)defaultValue: default boolean value (trueorfalse)
Example:
@BooleanField({ defaultValue: false })
isActive?: boolean;Defines a property as a Firestore Timestamp and optionally autofills it.
Options:
required: whether the field is required (default:false)autoFill: automatically set the current timestamp (default:false)
Example:
@TimestampField({ autoFill: true })
createdAt?: Firestore.Timestamp;Defines a property as a Firestore GeoPoint.
Options:
required: whether the field is required (default:false)
Example:
@GeoPointField()
location?: Firestore.GeoPoint;Defines a property as an array with a specified schema for its elements.
Options:
required: whether the field is required (default:false)
Example:
@ArrayField(z.string())
tags?: string[];Defines a property as a map (key-value object) where the values follow a specified schema.
Options:
required: whether the field is required (default:false)
Example:
@MapField(z.number())
settings?: Record<string, number>;Defines a property as a Firestore DocumentReference or a related BaseModel instance.
Options:
required: whether the field is required (default:false)
Example:
@DocumentReferenceField()
userRef?: DocumentReference<UserModel>;BaseModel: Abstract base class for your models.@Collection(name: string): Class decorator to set the collection name.@Relation(modelGetter: () => Constructor): Property decorator forDocumentReferencerelations.setFirestoreInstance(db: Firestore): Function to initialize the library.getFirestoreInstance(): Gets the configured Firestore instance.ValidationError: Error class for Zod validation failures.NotFoundError: Error class for documents not found.FindOptions,FindAllResult: Interfaces for query options and results.Timestamp,FieldValue,DocumentReference,CollectionReference, etc.: Types re-exported fromfirebase-admin/firestore.z: Zod object re-exported for convenience when defining schemas.