![\"Fireclass](\"https://fireclass.ayushdhar.com/logo.png\"){kind=logo}
\n \n\n \n \n \n
\n Type-safe Firestore models, validated CRUD, typed queries, and Express error handling for Node.js with Firebase Admin.\n
\n\n\n Setup |\n API reference |\n Express guide |\n GitHub |\n npm\n
\n\n@dharayush7/fireclass-js binds the shared Fireclass model API to\nfirebase-admin/firestore. Use it in Node.js servers, Express\napplications, workers, Cloud Functions, and other trusted server runtimes.\n\n> **Server-only package:** Firebase Admin bypasses client Firestore Security\n> Rules. Never import this package into browser code or expose service-account\n> values to clients.\n\n## Prerequisites\n\n- Node.js application with TypeScript decorators enabled.\n- Firebase project with Firestore enabled.\n- Application Default Credentials or Firebase Admin service-account values.\n- A gitignored environment file or managed secret store for private keys.\n\n## Installation\n\n~~~bash\nnpm install @dharayush7/fireclass-js firebase-admin class-validator class-transformer reflect-metadata\n~~~\n\nEnable decorators:\n\n~~~jsonc\n{\n \"compilerOptions\": {\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"experimentalDecorators\": true,\n \"emitDecoratorMetadata\": true\n }\n}\n~~~\n\n## Firebase Admin setup\n\nStore credentials outside source control:\n\n~~~bash\nPROJECT_ID=your-project-id\nCLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project-id.iam.gserviceaccount.com\nPRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\"\n~~~\n\nCreate a memoized Firebase entry:\n\n~~~ts\n// src/lib/firebase.ts\nimport \"dotenv/config\";\nimport { cert, getApps, initializeApp } from \"firebase-admin/app\";\nimport { getFirestore, type Firestore } from \"firebase-admin/firestore\";\n\nexport function getDb(): Firestore {\n if (getApps().length === 0) {\n initializeApp({\n credential: cert({\n projectId: process.env.PROJECT_ID,\n clientEmail: process.env.CLIENT_EMAIL,\n privateKey: process.env.PRIVATE_KEY?.replace(/\\\\n/g, \"\\n\"),\n }),\n });\n }\n\n return getFirestore();\n}\n~~~\n\nCreate the application binding:\n\n~~~ts\n// src/lib/fireclass.ts\nimport \"reflect-metadata\";\nimport { createFireclass } from \"@dharayush7/fireclass-js\";\nimport { getDb } from \"./firebase.js\";\n\nexport const { BaseModel, adapter } = createFireclass(getDb());\n~~~\n\nThe local Fireclass file should export initialized values only. Import\ndecorators, query types, errors, and middleware directly from this package where\nthey are used.\n\n## Define a model\n\n~~~ts\n// src/models/user.ts\nimport { Collection } from \"@dharayush7/fireclass-js\";\nimport { IsEmail, IsInt, IsString, Length, Min } from \"class-validator\";\nimport { BaseModel } from \"../lib/fireclass.js\";\n\n@Collection(\"users\")\nexport class User extends BaseModelsave() and delete(). Model\nclasses provide findById, findMany,\nfindOne, count, deleteById, and\ndeleteMany.\n\nSupported query operators are equals, gt,\ngte, lt, lte, in,\nnotIn, arrayContains, and\narrayContainsAny, plus ordering, limits, and\nstartAfter.\n\n## Export index\n\n| Export | Purpose |\n| --- | --- |\n| createFireclass(db) | Return a bound BaseModel and AdminAdapter |\n| Fireclass | Return type of createFireclass |\n| getBaseModel(db) | Compatibility alias for the deprecated package |\n| AdminAdapter | Firebase Admin implementation of the core adapter |\n| fireclassErrorHandler(options?) | Express-compatible Fireclass error middleware |\n| FireclassErrorHandlerOptions | Middleware status-code options |\n| Core exports | Decorators, query types, validation, conversion, and errors |\n\n### createFireclass\n\n~~~ts\nfunction createFireclass(db: Firestore): {\n BaseModel: BaseModelClass;\n adapter: AdminAdapter;\n};\n~~~\n\nCreate one binding and reuse it. Multiple calls create separate adapter and\nbase-class identities even when they reference the same Firestore instance.\n\n### AdminAdapter\n\n| Method | Firebase Admin operation |\n| --- | --- |\n| add | Collection add |\n| set | Document set with merge |\n| get | Document get |\n| query | Query get |\n| delete | Document delete |\n| batchDelete | Write batches of at most 500 deletes |\n| count | Aggregate count |\n| convert | Recursive Timestamp-to-Date conversion |\n\nRealtime subscriptions are intentionally absent; browser realtime support lives\nin @dharayush7/fireclass-react.\n\n## Express error middleware\n\nRegister Fireclass error middleware after routes:\n\n~~~ts\nimport express from \"express\";\nimport { fireclassErrorHandler } from \"@dharayush7/fireclass-js\";\n\nconst app = express();\napp.use(express.json());\n\n// Register application routes first.\n\napp.use(\n fireclassErrorHandler({\n validationStatus: 422,\n fireclassStatus: 400,\n }),\n);\n~~~\n\nBoth status options default to 400. Validation failures become:\n\n~~~json\n{\n \"error\": \"ValidationError\",\n \"message\": \"Validation failed for \\\"User\\\": email (email must be an email)\",\n \"details\": [\n {\n \"property\": \"email\",\n \"constraints\": {\n \"isEmail\": \"email must be an email\"\n }\n }\n ]\n}\n~~~\n\nOther Fireclass failures include their concrete error name and message.\nNon-Fireclass errors are passed to next(error) unchanged.\n\n## Migration from the deprecated package\n\n~~~diff\n- import { getBaseModel } from \"@dharayush7/fireclass/core\";\n+ import { getBaseModel } from \"@dharayush7/fireclass-js\";\n~~~\n\ngetBaseModel(db) remains available as a migration alias. Prefer\ncreateFireclass(db) for new code because it also exposes the\nadapter. Replace legacy subpath imports with direct runtime imports:\n\n~~~ts\nimport {\n Collection,\n ValidationFailedError,\n type QueryOptions,\n} from \"@dharayush7/fireclass-js\";\n~~~\n\nSee the complete\n[legacy migration guide](https://fireclass.ayushdhar.com/docs/guides/migration)\nfor changed errors, return values, and query capabilities.\n\n## CLI setup\n\nAfter Firebase initialization exists, the CLI can create\nfireclass.json, the Fireclass binding, models, and decorator\nconfiguration:\n\n~~~bash\nnpx fireclass init\nnpx fireclass doctor\n~~~\n\nFor an Express factory export, configure getDb() so generated code\ncalls the function.\n\n## Documentation and examples\n\n- [Express installation](https://fireclass.ayushdhar.com/docs/installation/express)\n- [Complete Node/Express API](https://fireclass.ayushdhar.com/docs/api/js)\n- [Express CRUD guide](https://fireclass.ayushdhar.com/docs/guides/express)\n- [Core model API](https://fireclass.ayushdhar.com/docs/api/core)\n- [Runnable Express application](https://github.com/dharayush7/fireclass-cli/tree/main/example/fireclass-express-app)\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history and\n[RELEASE_NOTES.md](./RELEASE_NOTES.md) for the current release summary.\n\n## License\n\nMIT. Copyright Ayush Dhar.\n","readmeFilename":"README.md"}