crossdeckhq/buckets-oss

Buckets is a small TypeScript library that tracks exactly how many database reads, writes, and deletes your app is making, and which user or function caused each one. The core problem it solves is a common billing surprise: your Firestore, MongoDB, or Postgres bill jumps unexpectedly and your database provider's dashboard shows you the total count but not which part of your app triggered the spike or whose request caused it. The library installs as a thin layer in front of your database calls. You initialize it once at app startup and it automatically intercepts every read and write across your entire codebase, counting them in memory without adding extra queries to your database. You can wrap a specific function or API route with a bucket() call to give it a label, and all the database operations inside that wrapper are grouped under that name in the output. Operations you do not label explicitly still appear, grouped by collection or table name. To connect a database read to the specific user who triggered it, you call setActor(userId) at your request boundary, the moment you know who is logged in. From that point, every database operation in that request is tagged with that user's ID. Background jobs and scheduled tasks can be labeled as machine so they are tracked separately from user-driven activity. The readout is a plain Markdown file written to a .crossdeck folder in your project directory, listing each bucket by name and its read count in order of size. You can print it with a single terminal command at any time. A cloud dashboard is available through the Crossdeck service if you supply an API key, but the local readout works with no account at all. Supported databases are Firestore, MongoDB, and Postgres. The library is MIT licensed and published as an npm package. The full README is longer than what was shown.