Runtime-neutral TypeScript models, typed queries, validation, adapter contracts, and in-memory testing for Firestore.

API reference | Core concepts | Testing API | GitHub | npm

@dharayush7/fireclass-core defines the shared Fireclass model API. It contains no Firebase Admin, Firebase client, React, Express, or Next.js imports. Runtime packages bind this core to a concrete Firestore SDK:

Most applications should install one runtime package because each runtime re-exports the complete core API. Install core directly when writing an adapter or testing models without Firebase.

npm install @dharayush7/fireclass-core class-validator class-transformer reflect-metadata

Enable legacy TypeScript decorators in the configuration that compiles models:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Import reflect-metadata once before decorated models load.

import "reflect-metadata";
import {
  Collection,
  defineBaseModel,
} from "@dharayush7/fireclass-core";
import { FakeAdapter } from "@dharayush7/fireclass-core/testing";
import { IsEmail, IsInt, Min } from "class-validator";

const adapter = new FakeAdapter();
const BaseModel = defineBaseModel(adapter);

@Collection("users")
class User extends BaseModel<User> {
  @IsEmail()
  email!: string;

  @IsInt()
  @Min(0)
  age!: number;

  constructor(data?: Partial<User>) {
    super(data);
    Object.assign(this, data);
  }
}

const id = await new User({
  email: "ada@example.com",
  age: 36,
}).save();

const adults = await User.findMany({
  where: { age: { gte: 18 } },
  orderBy: { age: "asc" },
  limit: 20,
});

defineBaseModel(adapter) creates a base class bound to one adapter. Core intentionally does not export a process-global BaseModel.

Reads and deletes do not run validation. save() validates before every write.

const activeAdults = await User.findMany({
  where: {
    age: { gte: 18, lt: 65 },
    status: { in: ["active", "invited"] },
  },
  orderBy: { age: "asc" },
  limit: 50,
  cursor: { startAfter: [36] },
});

Supported filters are equals, gt, gte, lt, lte, in, notIn, arrayContains, and arrayContainsAny.

Defined filters use AND semantics. Undefined values are skipped; false, zero, empty strings, and null are preserved. Only the first orderBy property is used. Firestore SDKs still enforce their operator, index, and cursor rules.

buildQuerySpec(query) converts public options into the normalized adapter representation without calling an adapter.

@Collection("posts")
class Post extends BaseModel<Post> {}

Collection records the top-level collection name. getCollectionName(Model) reads that metadata without throwing.

@Subcollection("comments", { parent: Post })
class Comment extends BaseModel<Comment> {}

Subcollection currently records collection and parent metadata only. Current model methods do not construct nested document paths automatically.

Required operations are add, set, get, query, and delete. Optional capabilities are batchDelete, count, subscribe, and convert.

Core falls back to sequential deletes when batch delete is absent. Missing count or subscription support throws UnsupportedAdapterCapabilityError.

runValidation(model) transforms a plain copy into the model constructor, runs class-validator, and throws ValidationFailedError when constraints fail. The original ValidationError[] is available as error.errors.

convertFirestoreTypes(value) recursively converts Timestamp-like values that provide toDate() while preserving arrays and nested objects.

FireclassError
|- MissingCollectionError
|- MissingIdError
|- ValidationFailedError
+- UnsupportedAdapterCapabilityError

The @dharayush7/fireclass-core/testing entry exports FakeAdapter, a deterministic in-memory implementation for CRUD, filters, ordering, limits, counts, batch deletes, and subscriptions.

const adapter = new FakeAdapter({
  seed: {
    users: {
      "user-1": { email: "ada@example.com", age: 36 },
    },
  },
});

const BaseModel = defineBaseModel(adapter);

Use the Firebase Emulator Suite for Firebase SDK behavior, Security Rules, transactions, and index tests.

• Models and BaseModel
• Decorators
• Validation
• Query options
• Adapters
• Errors
• Complete core API
• Testing API

See CHANGELOG.md for version history and RELEASE_NOTES.md for the current release summary.

MIT. Copyright Ayush Dhar.