@maykonpaulo/maestro-provider-firestore

📖 Guia completo — criar o admin de qualquer sistema: está no README do pacote @maykonpaulo/maestro-server no npm → https://www.npmjs.com/package/@maykonpaulo/maestro-server

A Firestore provider for @maykonpaulo/maestro-core — continuing ADR 0007 — Universal Provider Strategy into the document-family, alongside provider-mongodb/provider-couchbase. It implements all three of the core's provider contracts against a real Firestore database (or emulator):

• IntrospectionProvider — discovers top-level collections and infers each one's shape by sampling documents, mapping Firestore's native Timestamp/GeoPoint/DocumentReference types to dedicated FieldTypes where one exists. Every entity is reported with schemaless: true.
• DatasourceProvider — real list/findById/create/update/delete/count against the native @google-cloud/firestore SDK.
• SchemaWriteProvider — ensureEntity is a documented no-op (see below).

Installation

npm install @maykonpaulo/maestro-provider-firestore @maykonpaulo/maestro-core

@maykonpaulo/maestro-core and @google-cloud/firestore are peer dependencies — install the versions your project already uses.

Usage

import { runIntrospectionProvider } from '@maykonpaulo/maestro-core';
import { createFirestoreProvider } from '@maykonpaulo/maestro-provider-firestore';

const provider = createFirestoreProvider({ projectId: 'my-gcp-project' });

// Introspection — samples documents, validated/normalized via the core
const { result } = await runIntrospectionProvider(provider);

// Real CRUD against the same database
const created = await provider.create({ table: 'users', primaryKey: 'id', data: { name: 'Ada' } });
const page = await provider.list({ table: 'users', primaryKey: 'id', pagination: { strategy: 'page', page: 1, pageSize: 20 } });

Configuration

export interface FirestoreProviderOptions {
  firestore?: Firestore;   // an already-constructed client — for tests/embedding; caller owns its lifecycle
  projectId?: string;      // the GCP project ID
  host?: string;            // emulator host, e.g. 'localhost' — omit to use real Firestore with Application Default Credentials
  port?: number;            // emulator port
  ssl?: boolean;             // set false when pointing at a local emulator over plain HTTP
  maxDocuments?: number;    // caps documents read per top-level collection during introspection — unset by default (scans the whole collection)
}

Exactly one of firestore or projectId must be provided.

id handling

Firestore always assigns a native auto-ID to a document unless the caller supplies one. This provider follows that default:

• create() without a value at data[primaryKey] calls collection.add(data), letting Firestore generate the ID.
• create() with a value at data[primaryKey] calls collection.doc(id).set(data) instead.
• findById/update/delete always address the document by its Firestore document ID.

What is introspected

Since there is no system catalog, introspection reads every document in every top-level collection by default (maxDocuments is unset unless you explicitly cap it) and infers fields, nullability and types the same way provider-mongodb does, with native-type awareness:

• Timestamp fields are reported as 'datetime'.
• GeoPoint and DocumentReference fields are reported as 'json' (see "known limitations").
• Every other value maps the same way Mongo's sampling does (arrays, booleans, integers vs. floats, nested objects as 'json').
• schemaless: true on every entity, for the same honesty reason provider-mongodb's README documents.

What is not introspected (known limitations)

• Relations — Firestore has no foreign-key constraint to read, same reasoning as every other NoSQL provider in this monorepo; relations is always [].
• Subcollections — only top-level collections are discovered; subcollection recursion is out of scope for v1.
• GeoPoint — normalized to a plain { latitude, longitude } object; there is no native geo FieldType.
• DocumentReference — normalized to { path }; the reference path is preserved but not resolved or typed further.

Schema creation (ensureEntity)

Firestore has no explicit "create collection" API and no non-circular "does this collection exist" signal (listCollections() only lists collections that already contain at least one document — checking existence by writing a sentinel document would itself create the collection, and is destructive/side-effecting). ensureEntity therefore always reports created: false; the collection "exists" the moment its first document is written via create(). See src/FirestoreSchemaWrite.ts for the full reasoning.

Testing

Unit tests (tests/firestore-provider-construction.test.ts, tests/firestore-values.test.ts) cover constructor validation and native-type normalization/inference in isolation, no Docker required. Integration tests (tests/firestore-integration.test.ts) run against a real Firestore emulator started per test run via @testcontainers/gcloud's FirestoreEmulatorContainer — run them with pnpm test:integration (requires a running Docker daemon).

Turnkey admin (point at your database, get a UI)

This provider plugs straight into the Maestro turnkey layer: install @maykonpaulo/maestro-server and @maykonpaulo/maestro-admin, point them at your database and get a full governed admin (list/CRUD/RBAC/audit + a metadata-driven UI) with no per-entity code.

import { createFirestoreProvider } from '@maykonpaulo/maestro-provider-firestore';
import { createMaestroServer, createIntrospectedEngine } from '@maykonpaulo/maestro-server';

const provider = createFirestoreProvider({ projectId: 'my-gcp-project' });
const engine = await createIntrospectedEngine({ provider, access: 'full' });
await createMaestroServer({ engine }).listen(3000);

See the Turnkey admin guide.