@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: "[email protected]",
  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: "[email protected]", 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.