API Reference

getReadStats()

Returns current read statistics.

Returns: Object with totalReads, topCollections, worstOffender

const stats = window.ReadMeter.getReadStats()
// { totalReads: 42, topCollections: [['users', 30], ...], worstOffender: { caller, collection, reads, executions } }

resetReads()

Resets all read counters to zero.

window.ReadMeter.resetReads()

subscribe(callback)

Subscribe to read updates. Called whenever a new read is recorded.

Returns: Unsubscribe function

const unsub = window.ReadMeter.subscribe(() => {
  console.log('Reads:', window.ReadMeter.getReadStats().totalReads)
})
unsub() // stop listening

recordRead(op)

Record a read from external code (e.g. modular SDK wrapper or your own tracker). Not needed when using the compat SDK — the widget patches Firestore automatically.

Parameter shape: op — object with:

• reads (number, required) — number of document reads
• collection (string, required) — collection name
• type (string, optional) — e.g. 'getDoc', 'getDocs', 'onSnapshot'
• caller (string, optional) — e.g. feature name or file:line
• page (string, optional) — page path (e.g. /dashboard). Defaults to window.location.pathname if omitted

window.ReadMeter.recordRead({
  reads: 10,
  collection: 'users',
  type: 'getDocs',
  caller: 'loadUsers (App.tsx:42)'
})

Bridge from existing tracker: If you already track reads (e.g. firestoreReadTracker.track()), add: window.ReadMeter?.recordRead({ reads, collection, type, caller })

init()

Manually initialize the widget (normally runs on DOMContentLoaded).

window.ReadMeter.init()

instrumentAdminFirestore(db)

Wraps a firebase-admin Firestore instance so .get() / getAll() record estimated document reads. Idempotent.

import { getFirestore } from 'firebase-admin/firestore'
import { instrumentAdminFirestore } from '@/lib/readmeter-admin-firestore'

export const db = instrumentAdminFirestore(getFirestore())

getAdminReadStats() / resetAdminReadStats()

Process-local stats: totalReads, byCollection, byType, recentOperations.

GET /api/readmeter-admin

Added on Next.js init. Returns getAdminReadStats() JSON in development. ?reset=1 clears counters. Production returns 404 unless READMETER_ADMIN_API=1. Optional console: READMETER_ADMIN_LOG=1.