@dharayush7/fireclass-core

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:

Package	Runtime	Use case
@dharayush7/fireclass-js	Firebase Admin	Node.js and Express
@dharayush7/fireclass-ssr	Firebase Admin	Next.js App Router
@dharayush7/fireclass-react	Firebase client SDK	React and realtime hooks

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.

Installation

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.

Quick start without Firebase

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,
});

Export index

Group	Exports
Model	defineBaseModel, BaseModelClass
Decorators	Collection, Subcollection, getCollectionName, CollectionMeta
Queries	QueryOptions, FieldFilter, WhereFilter, OrderBy, Cursor, buildQuerySpec
Adapter	FirestoreAdapter, QuerySpec, QueryCondition, WhereOp, DocSnapshot
Validation	runValidation, convertFirestoreTypes
Errors	FireclassError, MissingCollectionError, MissingIdError, ValidationFailedError, UnsupportedAdapterCapabilityError
Testing subpath	FakeAdapter, FakeAdapterOptions

Model API

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

Instance API

Member	Behavior
id?: string	Firestore document id; omitted from stored data
save()	Validate, create without an id, or merge-update with an id; returns the document id
delete()	Delete by id; throws MissingIdError when no id exists

Static API

Method	Result
findById(id)	Hydrated model or null
findMany(query?)	Hydrated models matching the query
findOne(query?)	First match or null
count(query?)	Aggregate count when the adapter supports it
deleteById(id)	Deleted model or null
deleteMany(query?)	Deleted models, using batch delete when available

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

Typed queries

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 decorators

@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.

Adapter contract

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.

Validation and errors

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

Testing API

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.

Documentation

• 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.

License

MIT. Copyright Ayush Dhar.