Documentation

fireclass-js API

Complete reference for the Firebase Admin, Node.js, and Express Fireclass runtime.

@dharayush7/fireclass-js binds the shared model API to firebase-admin/firestore. Use it in Node.js servers, Express applications, workers, and other trusted server runtimes.

npm install @dharayush7/fireclass-js firebase-admin class-validator class-transformer reflect-metadata

Server-side package

This package uses Firebase Admin credentials and bypasses client Security Rules. Never import it into browser code or expose service-account values to clients.

Export index

Export	Kind	Purpose
`createFireclass`	Function	Bind models to an Admin Firestore instance.
`Fireclass`	Type	Return type of `createFireclass`.
`getBaseModel`	Function	Migration alias for the legacy package API.
`AdminAdapter`	Class	Firebase Admin implementation of `FirestoreAdapter`.
`fireclassErrorHandler`	Function	Express error-handling middleware.
`FireclassErrorHandlerOptions`	Interface	Configure middleware status codes.

The package also re-exports every fireclass-core value and type, including decorators, query types, and errors.

createFireclass

function createFireclass(db: Firestore): {
  BaseModel: BaseModelClass;
  adapter: AdminAdapter;
};
 
type Fireclass = ReturnType<typeof createFireclass>;

Creates one AdminAdapter and a BaseModel bound to it.

src/lib/fireclass.ts

import "reflect-metadata";
import { createFireclass } from "@dharayush7/fireclass-js";
import { getDb } from "./firebase.js";
 
export const { BaseModel, adapter } = createFireclass(getDb());

Reuse the returned values. Creating multiple bindings produces separate adapter and base-class identities, even when they point to the same Firestore instance.

getBaseModel

function getBaseModel(db: Firestore): BaseModelClass;

Compatibility alias for applications migrating from the deprecated @dharayush7/fireclass package.

const BaseModel = getBaseModel(db);

Prefer createFireclass, which also exposes the adapter.

AdminAdapter

class AdminAdapter implements FirestoreAdapter {
  constructor(db: Firestore);
}

Methods

Method	Result	Firebase Admin operation
`add(collection, data)`	`Promise<{ id: string }>`	`collection().add()`
`set(collection, id, data, options)`	`Promise<void>`	`doc().set()` with `merge`
`get(collection, id)`	`Promise<Record<string, unknown> \| null>`	Document get
`query(collection, spec)`	`Promise<DocSnapshot[]>`	Query get
`delete(collection, id)`	`Promise<void>`	Document delete
`batchDelete(collection, ids)`	`Promise<void>`	Write batches of at most 500 deletes
`count(collection, spec)`	`Promise<number>`	Aggregate count query
`convert(data)`	`Record<string, unknown>`	Recursive Timestamp-to-Date conversion

AdminAdapter supports filters, one normalized order, limit, and startAfter. It intentionally does not implement subscribe; realtime belongs to the client runtime.

Application models normally use the adapter indirectly through BaseModel. Direct calls are useful for integrations and adapter-level tests.

fireclassErrorHandler

interface FireclassErrorHandlerOptions {
  validationStatus?: number;
  fireclassStatus?: number;
}
 
function fireclassErrorHandler(
  options?: FireclassErrorHandlerOptions,
): (err: unknown, req: unknown, res: ResponseLike, next: NextLike) => void;

Returns Express-compatible error middleware without taking a direct dependency on Express. Register it after routes and other middleware.

src/server.ts

import express from "express";
import { fireclassErrorHandler } from "@dharayush7/fireclass-js";
 
const app = express();
 
app.post("/users", async (req, res, next) => {
  try {
    const user = new User(req.body);
    const id = await user.save();
    res.status(201).json({ id });
  } catch (error) {
    next(error);
  }
});
 
app.use(
  fireclassErrorHandler({
    validationStatus: 422,
    fireclassStatus: 400,
  }),
);

Both status options default to 400.

Validation response

{
  "error": "ValidationError",
  "message": "Validation failed for \"User\": email (email must be an email)",
  "details": [
    {
      "property": "email",
      "constraints": {
        "isEmail": "email must be an email"
      }
    }
  ]
}

Other Fireclass response

{
  "error": "MissingIdError",
  "message": "Cannot delete a document without an id."
}

Non-Fireclass errors are passed to next(error) unchanged. Nested validation children are retained on ValidationFailedError, but this middleware response maps only each top-level error's property and constraints.

Core imports

Import decorators and errors directly from this runtime package:

import {
  Collection,
  ValidationFailedError,
  type QueryOptions,
} from "@dharayush7/fireclass-js";

The local initialized Fireclass file should export bound values such as BaseModel and adapter, not re-export SDK symbols.

Previousfireclass-core Next fireclass-ssr