Skip to content

v2.0.8

Choose a tag to compare

View all tags
@dharayush7 dharayush7 released this 09 Jul 12:03
v2.0.8
387d8f8

fireclass-core v2.0.8

@dharayush7/fireclass-core — the first public release of the Fireclass suite core.

This is the zero-dependency, SDK-agnostic modeling layer at the heart of Fireclass. It defines what a Firestore model is, how validation runs, and the adapter contract that the runtime packages implement — so the model API stays identical whether you're on the server or the client. It supersedes the deprecated @dharayush7/fireclass (v0.2.12).

You usually don't install this directly — install a runtime package (fireclass-js, fireclass-react, or fireclass-ssr), which re-exports everything here. Install -core only to write your own adapter or unit-test models with the in-memory adapter.

Highlights

  • FirestoreAdapter contract — a neutral QuerySpec / WhereOp boundary between the model layer and any Firestore SDK. Implement it once, get the whole model API.
  • defineBaseModel(adapter) — a typed BaseModel with save, delete, findById, findMany, findOne, count, deleteById, and deleteMany.
  • QueryOptions<T> — nine typed operators (equals, gt, gte, lt, lte, in, notIn, arrayContains, arrayContainsAny) plus orderBy, limit, and a startAfter cursor.
  • Decorators — @Collection and @Subcollection, with no reflect-metadata requirement.
  • Validation — a class-validator / class-transformer pipeline that surfaces a typed ValidationFailedError.
  • convertFirestoreTypes — a deep Timestamp → Date normalizer for adapters, and a typed FireclassError hierarchy for clean instanceof branching.
  • FakeAdapter at @dharayush7/fireclass-core/testing — an in-memory adapter so you can unit-test models with zero emulator.

Install

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

Enable decorators in tsconfig.json:

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

Quick look

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

const BaseModel = defineBaseModel(new FakeAdapter());

@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: "desc" } });

Notes vs. the deprecated @dharayush7/fireclass

  • The query operator is equals (the old docs incorrectly showed equal).
  • The real entry point is the defineBaseModel(adapter) factory (the old docs implied a bare extends BaseModel that never worked).
  • Models with no validation decorators now save successfully instead of being rejected by class-validator's "unknown value" guard.

Quality

  • 54 unit tests, run entirely against the in-memory adapter (no emulator).
  • Dual ESM + CJS build with type declarations for both the . and ./testing entry points.
  • Published tarball contains only dist/ + README + LICENSE.

The Fireclass suite

Package Runtime For
@dharayush7/fireclass-core none (pure TS) shared modeling core — this package
@dharayush7/fireclass-js firebase-admin Node / Express
@dharayush7/fireclass-ssr firebase-admin Next.js (App Router)
@dharayush7/fireclass-react firebase client SDK React (realtime hooks)

Docs: https://fireclass.ayushdhar.com

Full API and examples: see the README. Changelog: see CHANGELOG.md.

Assets 2
Loading