Skip to content
FlintFire

Documentation overview

Topic index for flintfire. New to the library? Start with Getting Started, then follow the Guides pillar in order (the sidebar gives you prev/next). Reach for the Reference pillar when you need an exact signature.

How this is organized

Section titled “How this is organized”

The docs split into two pillars:

  • Guides — learn the library in a sensible order: get started, the core concepts (the mental model), working with data day to day, designing your data model, advanced features, framework integrations, and upgrading.
  • Reference — look up exact signatures and contracts: the repository and query-builder classes, exported types, runtime helpers, error classes, scope, and troubleshooting.

Guides

Section titled “Guides”

Get started

Section titled “Get started”
Page What it covers
Getting Started Install, initialize, define a schema, and CRUD
Documentation overview This page — the docs map

Core concepts

Section titled “Core concepts”
Page What it covers
Core Concepts Repository pattern, the four generics, delete behavior
Document Identity Virtual identity, no top-level id, repo.id(), whereId
Schema Validation Zod validation lifecycle, derived create/update schemas
Read Converters Read-only readConverter, required storedSchema, id overlay
Per-Field Sentinel Approval Write combinators and sentinelPolicy: 'strict'
Timestamps ↔ Millis createMillisTimestampConverter and the timestamp pattern
Lifecycle Hooks before*/after* hooks, payloads, and ordering

Working with data

Section titled “Working with data”
Page What it covers
CRUD Operations Create, read, update, delete, and bulk variants
Queries Query builder, composite filters, collection groups, aggregations, streaming, real-time
Transactions runInTransaction and the transaction-scoped methods
Subcollections Nested collections, collection-group reads, per-instance converters
Dot Notation Field-path updates, merge/patch, and FieldValue sentinels

Designing your data

Section titled “Designing your data”
Page What it covers
Data Modeling Maps vs subcollections, arrays, denormalized query flags
ID Strategies Auto, deterministic, and shared document ids
Schema Evolution Read-side normalization without a data migration
Trust Boundary & Security Admin SDK bypasses rules; validate at the boundary
Best Practices Recommended patterns for production use
Performance & Cost Firestore cost model, optimization tips, benchmarks

Advanced

Section titled “Advanced”
Page What it covers
Real-time & Listeners listenOne and query onSnapshot
Advanced Patterns Custom repository methods, denormalization, and more
Real-World Examples End-to-end e-commerce, multi-tenant, and social feed
Vector Search The optional ./vector extension and findNearest

Integrations & upgrading

Section titled “Integrations & upgrading”
Page What it covers
Express Route handlers and the errorHandler middleware
NestJS DI module/service/controller stack
Cloud Functions & Triggers Mapping trigger snapshots with fromSnapshot
Testing with the Emulator Testing repositories against the local emulator
Migrating from v2 to v3 Breaking changes and step-by-step upgrade from 2.x

Reference

Section titled “Reference”
Page What it covers
FirestoreRepository Construction, reads, writes, identity, hooks, txns
FirestoreQueryBuilder Filtering, projection, aggregation, pagination, collection-group builder
Exported Types FirestoreDocument, DataOf, FieldPaths, …
Helpers & Utilities Validation combinators, timestamp & dot-notation
Error Handling Error classes and parseFirestoreError
Scope & Capabilities Supported surface and deferred capabilities
Troubleshooting Common errors and their fixes