Documentation

Errors

Handle Fireclass model, validation, identity, and adapter capability errors consistently.

Fireclass exposes a small error hierarchy for failures originating in the core modeling layer. Each concrete error extends FireclassError, which extends the native JavaScript Error.

Error hierarchy

Error
  `-- FireclassError
        |-- MissingCollectionError
        |-- MissingIdError
        |-- ValidationFailedError
        `-- UnsupportedAdapterCapabilityError

All classes are exported by every runtime SDK:

import {
  FireclassError,
  MissingCollectionError,
  MissingIdError,
  UnsupportedAdapterCapabilityError,
  ValidationFailedError,
} from "@dharayush7/fireclass-js";

Use FireclassError for a broad library-originated branch and a concrete class when the recovery behavior differs.

Error reference

Error	Trigger	Typical recovery
`MissingCollectionError`	Constructing or statically using a model without `@Collection` or `@Subcollection`.	Add the decorator and import it from the runtime SDK.
`MissingIdError`	Calling an instance operation that requires `id`; currently `delete()`.	Save or hydrate the model before deleting it.
`ValidationFailedError`	A class-validator constraint fails during `save()`.	Return field errors or correct the model data.
`UnsupportedAdapterCapabilityError`	Calling a feature omitted by the active adapter; currently `count()` in `BaseModel`.	Use a capable adapter or avoid the operation.

Handle specific errors

import {
  FireclassError,
  MissingIdError,
  ValidationFailedError,
} from "@dharayush7/fireclass-js";
 
try {
  await user.save();
} catch (error) {
  if (error instanceof ValidationFailedError) {
    return {
      ok: false,
      fields: error.errors.map((issue) => ({
        field: issue.property,
        messages: Object.values(issue.constraints ?? {}),
      })),
    };
  }
 
  if (error instanceof MissingIdError) {
    return { ok: false, message: "Save the user before deleting it." };
  }
 
  if (error instanceof FireclassError) {
    return { ok: false, message: error.message };
  }
 
  throw error;
}

Avoid treating the human-readable message as a stable machine code. Use instanceof and the structured properties available on the concrete error.

Validation details

ValidationFailedError.errors is the original ValidationError[] produced by class-validator.

try {
  await new User({ email: "not-an-email" }).save();
} catch (error) {
  if (error instanceof ValidationFailedError) {
    console.error(error.name); // "ValidationFailedError"
    console.error(error.message); // summarized field constraints
    console.error(error.errors); // complete class-validator result
  }
}

The summary joins top-level property failures for logging. Use errors, including nested children, when building an API or form response.

Missing metadata and identity

Collection metadata is checked as soon as an instance is constructed and before every static operation:

class Undecorated extends BaseModel<Undecorated> {}
 
await Undecorated.findMany(); // MissingCollectionError

Identity is checked by operations that cannot work without a document id:

const user = new User({ name: "Ada" });
await user.delete(); // MissingIdError

save() does not require an id because a missing id selects the create path.

Adapter capability failures

Required adapter methods are guaranteed by the TypeScript contract. Optional methods allow fallback or explicit failure:

await User.count();
// UnsupportedAdapterCapabilityError when adapter.count is absent

deleteMany() does not throw a capability error when batchDelete is absent; it falls back to individual deletes. Realtime hooks require the React runtime's realtime adapter rather than a server adapter.

Firebase and application errors

Fireclass does not wrap errors thrown by an adapter. Authentication failures, permission denials, missing indexes, unavailable services, and other Firebase SDK errors propagate with their original SDK shape.

try {
  await User.findMany({
    where: { role: { equals: "admin" } },
  });
} catch (error) {
  if (error instanceof FireclassError) {
    // Core model, validation, or capability failure.
  } else {
    // Firebase SDK, network, or application failure.
  }
}

Node and Next.js packages provide runtime-specific helpers for translating errors at HTTP or Server Action boundaries. Core error classes remain available for custom handling.

Review Validation for the complete write pipeline and Adapters for optional capability behavior.

PreviousAdapters Next fireclass-core