@cross-deck/buckets 0.1.0 → 0.1.2

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAoB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAa,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAyB,MAAM,yBAAyB,CAAC;AAsBvF;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,OAAoB;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpG,cAAc,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7F,IAAI,OAAO,CAAC,SAAS;QAAE,qBAAqB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClE,CAAC;AAED,4DAA4D;AAC5D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,CAAC;AAE/B,qEAAqE;AACrE,OAAO,EACL,MAAM,EACN,cAAc,EACd,YAAY,EACZ,aAAa,EACb,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,OAAO,EACL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,KAAK,GAIN,MAAM,iBAAiB,CAAC;AAEzB,iEAAiE;AACjE,OAAO,EAAE,qBAAqB,EAAyB,MAAM,yBAAyB,CAAC;AAEvF,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAuE,MAAM,WAAW,CAAC"}
+{"version":3,"sources":["../src/cost-context.ts","../src/cost-meter.ts","../src/sink.ts","../src/adapters/firestore.ts","../src/index.ts"],"names":["AsyncLocalStorage","sink"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * cost-context — the request-scoped tag every counted operation attributes\n * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it\n * rides Node's AsyncLocalStorage down through every async fan-out, so one\n * handler that triggers 15 reads attributes all 15 to the same bucket — with\n * zero per-call-site work.\n *\n * Generic by design: unlike a hardcoded product taxonomy, the only meaningful\n * field a consumer sets is the free-form `label` (the bucket name). `feature`\n * is an optional coarse grouping if you want one; nothing here is\n * Crossdeck-specific.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport interface CostTag {\n  /** Optional coarse grouping (a caller-defined surface name). */\n  feature?: string;\n  /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */\n  label?: string;\n}\n\nconst DEFAULT_TAG: CostTag = {};\nconst store = new AsyncLocalStorage<CostTag>();\n\n/** Run `fn` with `tag` bound for its entire async subtree. */\nexport function runWithCostTag<T>(tag: CostTag, fn: () => T): T {\n  return store.run({ ...tag }, fn);\n}\n\n/** Bind a tag for the remainder of the current async context (no closure to wrap). */\nexport function enterCostTag(tag: CostTag): void {\n  store.enterWith({ ...tag });\n}\n\n/** Refine the live tag in place (e.g. stamp a feature after the boundary). */\nexport function refineCostTag(patch: Partial<CostTag>): void {\n  const cur = store.getStore();\n  if (cur) Object.assign(cur, patch);\n}\n\n/** The current tag, or a safe empty default outside any bound context. */\nexport function currentCostTag(): CostTag {\n  return store.getStore() ?? DEFAULT_TAG;\n}\n\n/**\n * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with\n * every operation inside it attributed to the bucket `name`; the attribution\n * rides the async subtree automatically. The one verb most developers ever touch:\n *\n *   await bucket(\"nightly-export\", async () => {\n *     const rows = await db.collection(\"events\").where(...).get(); // → \"nightly-export\"\n *   });\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  return runWithCostTag({ ...currentCostTag(), label: name }, fn);\n}\n","/**\n * cost-meter — counts operations against the ambient tag and flushes them to the\n * configured Sink cheaply.\n *\n * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them\n * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one\n * network call per counted operation. A flush coalesces the whole window into one\n * report per UTC day and hands it to the Sink. At steady state that is ~1 small\n * request a minute, regardless of how many ops you served.\n *\n * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder\n * swallows its own errors; a failed flush drops that window's counts (surfaced via\n * `onError` if you pass one) rather than disturbing the app.\n */\nimport { currentCostTag } from \"./cost-context\";\nimport type { Sink, BucketsReport, OpCounts } from \"./sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n/** Optional read-site hint — the collection touched, derived at the trap from the\n *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */\nexport interface CostHint {\n  collection?: string;\n  projectId?: string;\n}\n\n// NUL separator — a bucket/collection name can contain almost anything except\n// this, so the key never collides with a name that has a \"|\" or \":\" in it.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <NUL> op <NUL> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <NUL> op <NUL> hour → count */\nconst hourBuffer = new Map<string, number>();\n\nlet sink: Sink | null = null;\nlet flushIntervalMs = 60_000;\nlet onError: ((e: unknown) => void) | null = null;\nlet timer: ReturnType<typeof setInterval> | null = null;\nlet flushing = false;\n/** Safety valve — flush early if a burst fills the buffer between intervals. */\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface MeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\n/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */\nexport function configureMeter(config: MeterConfig): void {\n  sink = config.sink;\n  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;\n  onError = config.onError ?? null;\n}\n\nconst utcDate = (): string => new Date().toISOString().slice(0, 10);\nconst utcHour = (): string => new Date().toISOString().slice(11, 13);\n\nfunction ensureFlushLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flush(), flushIntervalMs);\n  // Don't keep the event loop alive just for metering.\n  (timer as { unref?: () => void }).unref?.();\n  // Flush the last window on shutdown.\n  process.once?.(\"SIGTERM\", () => void flush());\n  process.once?.(\"beforeExit\", () => void flush());\n}\n\n/** Count `n` ops of `op` against the live tag. Never throws. */\nexport function recordFirestore(op: OpType, n: number, hint?: CostHint): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const t = currentCostTag();\n    const date = utcDate();\n    // CASCADE — every op gets a label, by design (no blind spots): the bucket name\n    // wins; else the collection it actually touched (`col:posts`); else\n    // \"uncategorized\" as a loud last resort. A read is never invisible.\n    const label = t.label || (hint?.collection ? `col:${hint.collection}` : \"uncategorized\");\n    const lk = date + SEP + op + SEP + label;\n    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);\n    const hk = date + SEP + op + SEP + utcHour();\n    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);\n    ensureFlushLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();\n  } catch {\n    /* metering is best-effort — never disturb the caller */\n  }\n}\n\n/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */\nexport function recordReads(n: number, hint?: CostHint): void {\n  recordFirestore(\"read\", Math.max(n, 1), hint);\n}\nexport function recordWrites(n = 1): void {\n  recordFirestore(\"write\", n);\n}\nexport function recordDeletes(n = 1): void {\n  recordFirestore(\"delete\", n);\n}\n\nfunction add(target: Record<string, OpCounts>, key: string, op: OpType, n: number): void {\n  const bag = (target[key] ??= {});\n  bag[op] = (bag[op] ?? 0) + n;\n}\n\n/**\n * Coalesce the buffer into one report per UTC day and hand each to the Sink.\n * Snapshots + clears up front so concurrent records land in the next window.\n * Never throws; a sink failure drops that window (surfaced via `onError`).\n */\nexport async function flush(): Promise<void> {\n  if (flushing) return;\n  // Not configured (init not called) — drop, don't grow unbounded.\n  if (!sink) {\n    labelBuffer.clear();\n    hourBuffer.clear();\n    return;\n  }\n  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;\n  flushing = true;\n\n  const labels = new Map(labelBuffer);\n  const hours = new Map(hourBuffer);\n  labelBuffer.clear();\n  hourBuffer.clear();\n\n  try {\n    const byDate = new Map<string, BucketsReport>();\n    const reportFor = (date: string): BucketsReport => {\n      let r = byDate.get(date);\n      if (!r) {\n        r = { date, byLabel: {}, byHour: {} };\n        byDate.set(date, r);\n      }\n      return r;\n    };\n    for (const [k, n] of labels) {\n      const [date, op, label] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byLabel, label, op, n);\n    }\n    for (const [k, n] of hours) {\n      const [date, op, hour] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byHour!, hour, op, n);\n    }\n    for (const report of byDate.values()) {\n      await sink.flush(report);\n    }\n  } catch (e) {\n    // Drop this window rather than risk a partial/double report on retry.\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * sink — where the meter sends a coalesced rollup, and the wire shape it sends.\n *\n * Abstracting the sink is what makes Buckets storage-agnostic: the meter never\n * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's\n * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that\n * wants to self-host can implement `Sink` against anything (Postgres, a file, your\n * own API) without touching the meter.\n */\n\nexport interface OpCounts {\n  read?: number;\n  write?: number;\n  delete?: number;\n}\n\n/**\n * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter\n * produces one of these per UTC day in a flush window (usually exactly one).\n */\nexport interface BucketsReport {\n  /** UTC day \"YYYY-MM-DD\". */\n  date: string;\n  /** bucket name → counts. The heart of the report. */\n  byLabel: Record<string, OpCounts>;\n  /** UTC hour \"HH\" → counts, for the hourly \"did my fix land this hour?\" view. */\n  byHour?: Record<string, OpCounts>;\n}\n\n/**\n * A destination for coalesced rollups. `flush` MAY throw on failure — the meter\n * catches it, drops that one window, and never lets it reach your app.\n */\nexport interface Sink {\n  flush(report: BucketsReport): Promise<void>;\n}\n\nexport interface ReportSinkConfig {\n  /** The project's `cd_sk_` secret key. Server-to-server only. */\n  apiKey: string;\n  /** Defaults to https://api.cross-deck.com/v1/buckets/report */\n  endpoint?: string;\n  /** Request timeout (ms); a slow Crossdeck must never stall your flush. */\n  timeoutMs?: number;\n}\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\n/**\n * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.\n * The ingest folds it into the day's maintained doc with `increment`, so many\n * reports a minute coalesce safely. This path does ZERO database reads — it sends\n * a summary, it does not read. Throws on a non-202 so the meter can log/drop the\n * window; the meter guarantees it never reaches your app.\n */\nexport class ReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly timeoutMs: number;\n\n  constructor(config: ReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n    this.timeoutMs = config.timeoutMs ?? 5000;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      signal: AbortSignal.timeout(this.timeoutMs),\n      headers: {\n        \"content-type\": \"application/json\",\n        authorization: `Bearer ${this.apiKey}`,\n      },\n      body: JSON.stringify(report),\n    });\n    if (res.status !== 202) {\n      throw new Error(`Buckets report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * adapters/firestore — the universal Firestore read meter (the trap).\n *\n * THE LESSON (learned on a real product): per-call-site `recordReads()`\n * instrumentation MISSES paths. You meter the read sites you're looking at and\n * leave the cron / trigger / ingest path uncounted — often the majority of reads,\n * invisible. Humans tag what they see and miss the path that matters.\n *\n * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY\n * read — anywhere, on any code path — is counted under the ambient tag, with zero\n * per-call-site work and no blind spots.\n *\n * SAFETY CONTRACT — this sits on your production read path, so it is defensive by\n * construction. Each wrapper:\n *   1. calls the REAL method first and captures the result,\n *   2. counts in a try/catch that can never throw into the caller,\n *   3. ALWAYS returns the real result, untouched.\n * It cannot break a read, change a result, or add latency beyond one in-memory\n * counter increment. A wrong count is a measurement error, never a correctness or\n * availability one. Idempotent — calling it twice patches once.\n *\n * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills\n * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.\n * CollectionReference.get IS Query.get (shared prototype method), so patching Query\n * covers collections with no double-count.\n */\nimport { recordReads, type CostHint } from \"../cost-meter\";\n\nlet installed = false;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\ntype AnyFn = (...args: any[]) => any;\n\n/**\n * The firebase-admin Firestore classes to patch. Pass the module namespace from\n * `firebase-admin/firestore` — only the prototypes present are patched.\n */\nexport interface FirestoreClasses {\n  Query?: { prototype: { get?: AnyFn } };\n  DocumentReference?: { prototype: { get?: AnyFn } };\n  Transaction?: { prototype: { get?: AnyFn; getAll?: AnyFn } };\n  Firestore?: { prototype: { getAll?: AnyFn } };\n}\n\n/** `projects/{id}/…` → the project id, else undefined. Pure string op. */\nfunction projectFromPath(path: string): string | undefined {\n  const parts = path.split(\"/\");\n  const i = parts.indexOf(\"projects\");\n  return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;\n}\n\n/**\n * Derive { collection, projectId } from the read target's path so an UNtagged read\n * cascades to `col:<collection>` instead of \"uncategorized\". PURE CPU; never reads,\n * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered\n * queries (which don't expose `.path`).\n */\nfunction hintFrom(target: any): CostHint | undefined {\n  try {\n    const p = typeof target?.path === \"string\" ? target.path : \"\";\n    if (p) {\n      const parts = p.split(\"/\").filter(Boolean);\n      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];\n      return { collection, projectId: projectFromPath(p) };\n    }\n    const qo = target?._queryOptions;\n    if (qo) {\n      const collection = typeof qo.collectionId === \"string\" ? qo.collectionId : undefined;\n      const parent =\n        typeof qo.parentPath?.relativeName === \"string\"\n          ? qo.parentPath.relativeName\n          : typeof qo.parentPath?.toString === \"function\"\n            ? String(qo.parentPath.toString())\n            : \"\";\n      return { collection, projectId: parent ? projectFromPath(parent) : undefined };\n    }\n  } catch {\n    /* the meter must never throw */\n  }\n  return undefined;\n}\n\nfunction meterSnap(snap: unknown, hint?: CostHint): void {\n  try {\n    const size = (snap as { size?: number } | null)?.size;\n    recordReads(typeof size === \"number\" ? size : 1, hint);\n  } catch {\n    /* best-effort */\n  }\n}\nfunction meterCount(n: number, hint?: CostHint): void {\n  try {\n    recordReads(n, hint);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/**\n * Install the universal read meter on the firebase-admin Firestore classes. Call\n * ONCE at process start, before any reads. Pass the namespace from\n * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:\n *\n *   import * as Firestore from \"firebase-admin/firestore\";\n *   installFirestoreMeter(Firestore);\n */\nexport function installFirestoreMeter(classes: FirestoreClasses): void {\n  if (installed) return;\n  installed = true;\n  const { Query, DocumentReference, Transaction, Firestore } = classes;\n\n  // Query.get — covers Query AND CollectionReference (shared prototype method).\n  const qGet = Query?.prototype?.get;\n  if (qGet) {\n    Query!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await qGet.apply(this, args);\n      meterSnap(snap, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // DocumentReference.get — a single doc = 1 read.\n  const dGet = DocumentReference?.prototype?.get;\n  if (dGet) {\n    DocumentReference!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await dGet.apply(this, args);\n      meterCount(1, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // Transaction.get — query or doc; size when present, else 1.\n  const tGet = Transaction?.prototype?.get;\n  if (tGet) {\n    Transaction!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const res = await tGet.apply(this, args);\n      meterSnap(res, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Transaction.getAll(...refs) — one read per ref.\n  const tGetAll = Transaction?.prototype?.getAll;\n  if (tGetAll) {\n    Transaction!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await tGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Firestore.getAll(...refs) — batched doc reads.\n  const fGetAll = Firestore?.prototype?.getAll;\n  if (fGetAll) {\n    Firestore!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await fGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n}\n\n/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */\nexport function __resetFirestoreMeterForTests(): void {\n  installed = false;\n}\n","/**\n * @cross-deck/buckets — know exactly what every database read costs you, and who\n * caused it. A tiny, never-throws collector for Firestore.\n *\n * The whole footprint a consumer sees:\n *   1. init({ apiKey, firestore })  — configure once, install the trap once\n *   2. bucket(name, fn)             — name the read paths that matter\n *   3. (the dashboard shows the rest — and names the ones you haven't yet)\n */\nimport { configureMeter, type MeterConfig } from \"./cost-meter\";\nimport { ReportSink, type Sink } from \"./sink\";\nimport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\nexport interface InitOptions {\n  /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */\n  apiKey: string;\n  /**\n   * Pass the namespace from `firebase-admin/firestore` to auto-install the read\n   * trap (recommended — this is what makes every read count with no per-call work).\n   * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only\n   * use the manual `recordReads()` recorders.\n   */\n  firestore?: FirestoreClasses;\n  /** Override the report endpoint (defaults to Crossdeck's ingest). */\n  endpoint?: string;\n  /** How often to flush coalesced counts (ms). Default 60_000. */\n  flushIntervalMs?: number;\n  /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */\n  sink?: Sink;\n  /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */\n  onError?: MeterConfig[\"onError\"];\n}\n\n/**\n * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's\n * ingest by default) and — if you pass `firestore` — installs the universal read\n * trap so every read counts automatically.\n */\nexport function init(options: InitOptions): void {\n  const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n  if (options.firestore) installFirestoreMeter(options.firestore);\n}\n\n/** Alias — reads well next to `bucket()` at a call site. */\nexport { init as initBuckets };\n\n// The headline verb + the lower-level tag controls it is sugar over.\nexport {\n  bucket,\n  runWithCostTag,\n  enterCostTag,\n  refineCostTag,\n  currentCostTag,\n  type CostTag,\n} from \"./cost-context\";\n\n// Manual recorders (for non-Firestore ops, or when you don't install the trap).\nexport {\n  recordReads,\n  recordWrites,\n  recordDeletes,\n  flush,\n  type CostHint,\n  type OpType,\n  type MeterConfig,\n} from \"./cost-meter\";\n\n// The trap (the only datastore adapter today) + its class shape.\nexport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\n// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.\nexport { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from \"./sink\";\n"]}

package/dist/index.mjs

@@ -0,0 +1,236 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+// src/cost-context.ts
+var DEFAULT_TAG = {};
+var store = new AsyncLocalStorage();
+function runWithCostTag(tag, fn) {
+  return store.run({ ...tag }, fn);
+}
+function enterCostTag(tag) {
+  store.enterWith({ ...tag });
+}
+function refineCostTag(patch) {
+  const cur = store.getStore();
+  if (cur) Object.assign(cur, patch);
+}
+function currentCostTag() {
+  return store.getStore() ?? DEFAULT_TAG;
+}
+function bucket(name, fn) {
+  return runWithCostTag({ ...currentCostTag(), label: name }, fn);
+}
+
+// src/cost-meter.ts
+var SEP = "";
+var labelBuffer = /* @__PURE__ */ new Map();
+var hourBuffer = /* @__PURE__ */ new Map();
+var sink = null;
+var flushIntervalMs = 6e4;
+var onError = null;
+var timer = null;
+var flushing = false;
+var MAX_BUFFER_KEYS = 5e3;
+function configureMeter(config) {
+  sink = config.sink;
+  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;
+  onError = config.onError ?? null;
+}
+var utcDate = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+var utcHour = () => (/* @__PURE__ */ new Date()).toISOString().slice(11, 13);
+function ensureFlushLoop() {
+  if (timer) return;
+  timer = setInterval(() => void flush(), flushIntervalMs);
+  timer.unref?.();
+  process.once?.("SIGTERM", () => void flush());
+  process.once?.("beforeExit", () => void flush());
+}
+function recordFirestore(op, n, hint) {
+  try {
+    if (!Number.isFinite(n) || n <= 0) return;
+    const t = currentCostTag();
+    const date = utcDate();
+    const label = t.label || (hint?.collection ? `col:${hint.collection}` : "uncategorized");
+    const lk = date + SEP + op + SEP + label;
+    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);
+    const hk = date + SEP + op + SEP + utcHour();
+    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);
+    ensureFlushLoop();
+    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();
+  } catch {
+  }
+}
+function recordReads(n, hint) {
+  recordFirestore("read", Math.max(n, 1), hint);
+}
+function recordWrites(n = 1) {
+  recordFirestore("write", n);
+}
+function recordDeletes(n = 1) {
+  recordFirestore("delete", n);
+}
+function add(target, key, op, n) {
+  const bag = target[key] ??= {};
+  bag[op] = (bag[op] ?? 0) + n;
+}
+async function flush() {
+  if (flushing) return;
+  if (!sink) {
+    labelBuffer.clear();
+    hourBuffer.clear();
+    return;
+  }
+  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;
+  flushing = true;
+  const labels = new Map(labelBuffer);
+  const hours = new Map(hourBuffer);
+  labelBuffer.clear();
+  hourBuffer.clear();
+  try {
+    const byDate = /* @__PURE__ */ new Map();
+    const reportFor = (date) => {
+      let r = byDate.get(date);
+      if (!r) {
+        r = { date, byLabel: {}, byHour: {} };
+        byDate.set(date, r);
+      }
+      return r;
+    };
+    for (const [k, n] of labels) {
+      const [date, op, label] = k.split(SEP);
+      add(reportFor(date).byLabel, label, op, n);
+    }
+    for (const [k, n] of hours) {
+      const [date, op, hour] = k.split(SEP);
+      add(reportFor(date).byHour, hour, op, n);
+    }
+    for (const report of byDate.values()) {
+      await sink.flush(report);
+    }
+  } catch (e) {
+    onError?.(e);
+  } finally {
+    flushing = false;
+  }
+}
+
+// src/sink.ts
+var DEFAULT_ENDPOINT = "https://api.cross-deck.com/v1/buckets/report";
+var ReportSink = class {
+  endpoint;
+  apiKey;
+  timeoutMs;
+  constructor(config) {
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? 5e3;
+  }
+  async flush(report) {
+    const res = await fetch(this.endpoint, {
+      method: "POST",
+      signal: AbortSignal.timeout(this.timeoutMs),
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(report)
+    });
+    if (res.status !== 202) {
+      throw new Error(`Buckets report rejected: HTTP ${res.status}`);
+    }
+  }
+};
+
+// src/adapters/firestore.ts
+var installed = false;
+function projectFromPath(path) {
+  const parts = path.split("/");
+  const i = parts.indexOf("projects");
+  return i >= 0 && parts[i + 1] ? parts[i + 1] : void 0;
+}
+function hintFrom(target) {
+  try {
+    const p = typeof target?.path === "string" ? target.path : "";
+    if (p) {
+      const parts = p.split("/").filter(Boolean);
+      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];
+      return { collection, projectId: projectFromPath(p) };
+    }
+    const qo = target?._queryOptions;
+    if (qo) {
+      const collection = typeof qo.collectionId === "string" ? qo.collectionId : void 0;
+      const parent = typeof qo.parentPath?.relativeName === "string" ? qo.parentPath.relativeName : typeof qo.parentPath?.toString === "function" ? String(qo.parentPath.toString()) : "";
+      return { collection, projectId: parent ? projectFromPath(parent) : void 0 };
+    }
+  } catch {
+  }
+  return void 0;
+}
+function meterSnap(snap, hint) {
+  try {
+    const size = snap?.size;
+    recordReads(typeof size === "number" ? size : 1, hint);
+  } catch {
+  }
+}
+function meterCount(n, hint) {
+  try {
+    recordReads(n, hint);
+  } catch {
+  }
+}
+function installFirestoreMeter(classes) {
+  if (installed) return;
+  installed = true;
+  const { Query, DocumentReference, Transaction, Firestore } = classes;
+  const qGet = Query?.prototype?.get;
+  if (qGet) {
+    Query.prototype.get = async function(...args) {
+      const snap = await qGet.apply(this, args);
+      meterSnap(snap, hintFrom(this));
+      return snap;
+    };
+  }
+  const dGet = DocumentReference?.prototype?.get;
+  if (dGet) {
+    DocumentReference.prototype.get = async function(...args) {
+      const snap = await dGet.apply(this, args);
+      meterCount(1, hintFrom(this));
+      return snap;
+    };
+  }
+  const tGet = Transaction?.prototype?.get;
+  if (tGet) {
+    Transaction.prototype.get = async function(...args) {
+      const res = await tGet.apply(this, args);
+      meterSnap(res, hintFrom(args[0]));
+      return res;
+    };
+  }
+  const tGetAll = Transaction?.prototype?.getAll;
+  if (tGetAll) {
+    Transaction.prototype.getAll = async function(...args) {
+      const res = await tGetAll.apply(this, args);
+      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));
+      return res;
+    };
+  }
+  const fGetAll = Firestore?.prototype?.getAll;
+  if (fGetAll) {
+    Firestore.prototype.getAll = async function(...args) {
+      const res = await fGetAll.apply(this, args);
+      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));
+      return res;
+    };
+  }
+}
+
+// src/index.ts
+function init(options) {
+  const sink2 = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });
+  configureMeter({ sink: sink2, flushIntervalMs: options.flushIntervalMs, onError: options.onError });
+  if (options.firestore) installFirestoreMeter(options.firestore);
+}
+
+export { ReportSink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cost-context.ts","../src/cost-meter.ts","../src/sink.ts","../src/adapters/firestore.ts","../src/index.ts"],"names":["sink"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * cost-context — the request-scoped tag every counted operation attributes\n * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it\n * rides Node's AsyncLocalStorage down through every async fan-out, so one\n * handler that triggers 15 reads attributes all 15 to the same bucket — with\n * zero per-call-site work.\n *\n * Generic by design: unlike a hardcoded product taxonomy, the only meaningful\n * field a consumer sets is the free-form `label` (the bucket name). `feature`\n * is an optional coarse grouping if you want one; nothing here is\n * Crossdeck-specific.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport interface CostTag {\n  /** Optional coarse grouping (a caller-defined surface name). */\n  feature?: string;\n  /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */\n  label?: string;\n}\n\nconst DEFAULT_TAG: CostTag = {};\nconst store = new AsyncLocalStorage<CostTag>();\n\n/** Run `fn` with `tag` bound for its entire async subtree. */\nexport function runWithCostTag<T>(tag: CostTag, fn: () => T): T {\n  return store.run({ ...tag }, fn);\n}\n\n/** Bind a tag for the remainder of the current async context (no closure to wrap). */\nexport function enterCostTag(tag: CostTag): void {\n  store.enterWith({ ...tag });\n}\n\n/** Refine the live tag in place (e.g. stamp a feature after the boundary). */\nexport function refineCostTag(patch: Partial<CostTag>): void {\n  const cur = store.getStore();\n  if (cur) Object.assign(cur, patch);\n}\n\n/** The current tag, or a safe empty default outside any bound context. */\nexport function currentCostTag(): CostTag {\n  return store.getStore() ?? DEFAULT_TAG;\n}\n\n/**\n * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with\n * every operation inside it attributed to the bucket `name`; the attribution\n * rides the async subtree automatically. The one verb most developers ever touch:\n *\n *   await bucket(\"nightly-export\", async () => {\n *     const rows = await db.collection(\"events\").where(...).get(); // → \"nightly-export\"\n *   });\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  return runWithCostTag({ ...currentCostTag(), label: name }, fn);\n}\n","/**\n * cost-meter — counts operations against the ambient tag and flushes them to the\n * configured Sink cheaply.\n *\n * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them\n * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one\n * network call per counted operation. A flush coalesces the whole window into one\n * report per UTC day and hands it to the Sink. At steady state that is ~1 small\n * request a minute, regardless of how many ops you served.\n *\n * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder\n * swallows its own errors; a failed flush drops that window's counts (surfaced via\n * `onError` if you pass one) rather than disturbing the app.\n */\nimport { currentCostTag } from \"./cost-context\";\nimport type { Sink, BucketsReport, OpCounts } from \"./sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n/** Optional read-site hint — the collection touched, derived at the trap from the\n *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */\nexport interface CostHint {\n  collection?: string;\n  projectId?: string;\n}\n\n// NUL separator — a bucket/collection name can contain almost anything except\n// this, so the key never collides with a name that has a \"|\" or \":\" in it.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <NUL> op <NUL> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <NUL> op <NUL> hour → count */\nconst hourBuffer = new Map<string, number>();\n\nlet sink: Sink | null = null;\nlet flushIntervalMs = 60_000;\nlet onError: ((e: unknown) => void) | null = null;\nlet timer: ReturnType<typeof setInterval> | null = null;\nlet flushing = false;\n/** Safety valve — flush early if a burst fills the buffer between intervals. */\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface MeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\n/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */\nexport function configureMeter(config: MeterConfig): void {\n  sink = config.sink;\n  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;\n  onError = config.onError ?? null;\n}\n\nconst utcDate = (): string => new Date().toISOString().slice(0, 10);\nconst utcHour = (): string => new Date().toISOString().slice(11, 13);\n\nfunction ensureFlushLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flush(), flushIntervalMs);\n  // Don't keep the event loop alive just for metering.\n  (timer as { unref?: () => void }).unref?.();\n  // Flush the last window on shutdown.\n  process.once?.(\"SIGTERM\", () => void flush());\n  process.once?.(\"beforeExit\", () => void flush());\n}\n\n/** Count `n` ops of `op` against the live tag. Never throws. */\nexport function recordFirestore(op: OpType, n: number, hint?: CostHint): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const t = currentCostTag();\n    const date = utcDate();\n    // CASCADE — every op gets a label, by design (no blind spots): the bucket name\n    // wins; else the collection it actually touched (`col:posts`); else\n    // \"uncategorized\" as a loud last resort. A read is never invisible.\n    const label = t.label || (hint?.collection ? `col:${hint.collection}` : \"uncategorized\");\n    const lk = date + SEP + op + SEP + label;\n    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);\n    const hk = date + SEP + op + SEP + utcHour();\n    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);\n    ensureFlushLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();\n  } catch {\n    /* metering is best-effort — never disturb the caller */\n  }\n}\n\n/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */\nexport function recordReads(n: number, hint?: CostHint): void {\n  recordFirestore(\"read\", Math.max(n, 1), hint);\n}\nexport function recordWrites(n = 1): void {\n  recordFirestore(\"write\", n);\n}\nexport function recordDeletes(n = 1): void {\n  recordFirestore(\"delete\", n);\n}\n\nfunction add(target: Record<string, OpCounts>, key: string, op: OpType, n: number): void {\n  const bag = (target[key] ??= {});\n  bag[op] = (bag[op] ?? 0) + n;\n}\n\n/**\n * Coalesce the buffer into one report per UTC day and hand each to the Sink.\n * Snapshots + clears up front so concurrent records land in the next window.\n * Never throws; a sink failure drops that window (surfaced via `onError`).\n */\nexport async function flush(): Promise<void> {\n  if (flushing) return;\n  // Not configured (init not called) — drop, don't grow unbounded.\n  if (!sink) {\n    labelBuffer.clear();\n    hourBuffer.clear();\n    return;\n  }\n  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;\n  flushing = true;\n\n  const labels = new Map(labelBuffer);\n  const hours = new Map(hourBuffer);\n  labelBuffer.clear();\n  hourBuffer.clear();\n\n  try {\n    const byDate = new Map<string, BucketsReport>();\n    const reportFor = (date: string): BucketsReport => {\n      let r = byDate.get(date);\n      if (!r) {\n        r = { date, byLabel: {}, byHour: {} };\n        byDate.set(date, r);\n      }\n      return r;\n    };\n    for (const [k, n] of labels) {\n      const [date, op, label] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byLabel, label, op, n);\n    }\n    for (const [k, n] of hours) {\n      const [date, op, hour] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byHour!, hour, op, n);\n    }\n    for (const report of byDate.values()) {\n      await sink.flush(report);\n    }\n  } catch (e) {\n    // Drop this window rather than risk a partial/double report on retry.\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * sink — where the meter sends a coalesced rollup, and the wire shape it sends.\n *\n * Abstracting the sink is what makes Buckets storage-agnostic: the meter never\n * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's\n * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that\n * wants to self-host can implement `Sink` against anything (Postgres, a file, your\n * own API) without touching the meter.\n */\n\nexport interface OpCounts {\n  read?: number;\n  write?: number;\n  delete?: number;\n}\n\n/**\n * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter\n * produces one of these per UTC day in a flush window (usually exactly one).\n */\nexport interface BucketsReport {\n  /** UTC day \"YYYY-MM-DD\". */\n  date: string;\n  /** bucket name → counts. The heart of the report. */\n  byLabel: Record<string, OpCounts>;\n  /** UTC hour \"HH\" → counts, for the hourly \"did my fix land this hour?\" view. */\n  byHour?: Record<string, OpCounts>;\n}\n\n/**\n * A destination for coalesced rollups. `flush` MAY throw on failure — the meter\n * catches it, drops that one window, and never lets it reach your app.\n */\nexport interface Sink {\n  flush(report: BucketsReport): Promise<void>;\n}\n\nexport interface ReportSinkConfig {\n  /** The project's `cd_sk_` secret key. Server-to-server only. */\n  apiKey: string;\n  /** Defaults to https://api.cross-deck.com/v1/buckets/report */\n  endpoint?: string;\n  /** Request timeout (ms); a slow Crossdeck must never stall your flush. */\n  timeoutMs?: number;\n}\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\n/**\n * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.\n * The ingest folds it into the day's maintained doc with `increment`, so many\n * reports a minute coalesce safely. This path does ZERO database reads — it sends\n * a summary, it does not read. Throws on a non-202 so the meter can log/drop the\n * window; the meter guarantees it never reaches your app.\n */\nexport class ReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly timeoutMs: number;\n\n  constructor(config: ReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n    this.timeoutMs = config.timeoutMs ?? 5000;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      signal: AbortSignal.timeout(this.timeoutMs),\n      headers: {\n        \"content-type\": \"application/json\",\n        authorization: `Bearer ${this.apiKey}`,\n      },\n      body: JSON.stringify(report),\n    });\n    if (res.status !== 202) {\n      throw new Error(`Buckets report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * adapters/firestore — the universal Firestore read meter (the trap).\n *\n * THE LESSON (learned on a real product): per-call-site `recordReads()`\n * instrumentation MISSES paths. You meter the read sites you're looking at and\n * leave the cron / trigger / ingest path uncounted — often the majority of reads,\n * invisible. Humans tag what they see and miss the path that matters.\n *\n * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY\n * read — anywhere, on any code path — is counted under the ambient tag, with zero\n * per-call-site work and no blind spots.\n *\n * SAFETY CONTRACT — this sits on your production read path, so it is defensive by\n * construction. Each wrapper:\n *   1. calls the REAL method first and captures the result,\n *   2. counts in a try/catch that can never throw into the caller,\n *   3. ALWAYS returns the real result, untouched.\n * It cannot break a read, change a result, or add latency beyond one in-memory\n * counter increment. A wrong count is a measurement error, never a correctness or\n * availability one. Idempotent — calling it twice patches once.\n *\n * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills\n * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.\n * CollectionReference.get IS Query.get (shared prototype method), so patching Query\n * covers collections with no double-count.\n */\nimport { recordReads, type CostHint } from \"../cost-meter\";\n\nlet installed = false;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\ntype AnyFn = (...args: any[]) => any;\n\n/**\n * The firebase-admin Firestore classes to patch. Pass the module namespace from\n * `firebase-admin/firestore` — only the prototypes present are patched.\n */\nexport interface FirestoreClasses {\n  Query?: { prototype: { get?: AnyFn } };\n  DocumentReference?: { prototype: { get?: AnyFn } };\n  Transaction?: { prototype: { get?: AnyFn; getAll?: AnyFn } };\n  Firestore?: { prototype: { getAll?: AnyFn } };\n}\n\n/** `projects/{id}/…` → the project id, else undefined. Pure string op. */\nfunction projectFromPath(path: string): string | undefined {\n  const parts = path.split(\"/\");\n  const i = parts.indexOf(\"projects\");\n  return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;\n}\n\n/**\n * Derive { collection, projectId } from the read target's path so an UNtagged read\n * cascades to `col:<collection>` instead of \"uncategorized\". PURE CPU; never reads,\n * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered\n * queries (which don't expose `.path`).\n */\nfunction hintFrom(target: any): CostHint | undefined {\n  try {\n    const p = typeof target?.path === \"string\" ? target.path : \"\";\n    if (p) {\n      const parts = p.split(\"/\").filter(Boolean);\n      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];\n      return { collection, projectId: projectFromPath(p) };\n    }\n    const qo = target?._queryOptions;\n    if (qo) {\n      const collection = typeof qo.collectionId === \"string\" ? qo.collectionId : undefined;\n      const parent =\n        typeof qo.parentPath?.relativeName === \"string\"\n          ? qo.parentPath.relativeName\n          : typeof qo.parentPath?.toString === \"function\"\n            ? String(qo.parentPath.toString())\n            : \"\";\n      return { collection, projectId: parent ? projectFromPath(parent) : undefined };\n    }\n  } catch {\n    /* the meter must never throw */\n  }\n  return undefined;\n}\n\nfunction meterSnap(snap: unknown, hint?: CostHint): void {\n  try {\n    const size = (snap as { size?: number } | null)?.size;\n    recordReads(typeof size === \"number\" ? size : 1, hint);\n  } catch {\n    /* best-effort */\n  }\n}\nfunction meterCount(n: number, hint?: CostHint): void {\n  try {\n    recordReads(n, hint);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/**\n * Install the universal read meter on the firebase-admin Firestore classes. Call\n * ONCE at process start, before any reads. Pass the namespace from\n * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:\n *\n *   import * as Firestore from \"firebase-admin/firestore\";\n *   installFirestoreMeter(Firestore);\n */\nexport function installFirestoreMeter(classes: FirestoreClasses): void {\n  if (installed) return;\n  installed = true;\n  const { Query, DocumentReference, Transaction, Firestore } = classes;\n\n  // Query.get — covers Query AND CollectionReference (shared prototype method).\n  const qGet = Query?.prototype?.get;\n  if (qGet) {\n    Query!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await qGet.apply(this, args);\n      meterSnap(snap, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // DocumentReference.get — a single doc = 1 read.\n  const dGet = DocumentReference?.prototype?.get;\n  if (dGet) {\n    DocumentReference!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await dGet.apply(this, args);\n      meterCount(1, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // Transaction.get — query or doc; size when present, else 1.\n  const tGet = Transaction?.prototype?.get;\n  if (tGet) {\n    Transaction!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const res = await tGet.apply(this, args);\n      meterSnap(res, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Transaction.getAll(...refs) — one read per ref.\n  const tGetAll = Transaction?.prototype?.getAll;\n  if (tGetAll) {\n    Transaction!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await tGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Firestore.getAll(...refs) — batched doc reads.\n  const fGetAll = Firestore?.prototype?.getAll;\n  if (fGetAll) {\n    Firestore!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await fGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n}\n\n/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */\nexport function __resetFirestoreMeterForTests(): void {\n  installed = false;\n}\n","/**\n * @cross-deck/buckets — know exactly what every database read costs you, and who\n * caused it. A tiny, never-throws collector for Firestore.\n *\n * The whole footprint a consumer sees:\n *   1. init({ apiKey, firestore })  — configure once, install the trap once\n *   2. bucket(name, fn)             — name the read paths that matter\n *   3. (the dashboard shows the rest — and names the ones you haven't yet)\n */\nimport { configureMeter, type MeterConfig } from \"./cost-meter\";\nimport { ReportSink, type Sink } from \"./sink\";\nimport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\nexport interface InitOptions {\n  /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */\n  apiKey: string;\n  /**\n   * Pass the namespace from `firebase-admin/firestore` to auto-install the read\n   * trap (recommended — this is what makes every read count with no per-call work).\n   * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only\n   * use the manual `recordReads()` recorders.\n   */\n  firestore?: FirestoreClasses;\n  /** Override the report endpoint (defaults to Crossdeck's ingest). */\n  endpoint?: string;\n  /** How often to flush coalesced counts (ms). Default 60_000. */\n  flushIntervalMs?: number;\n  /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */\n  sink?: Sink;\n  /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */\n  onError?: MeterConfig[\"onError\"];\n}\n\n/**\n * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's\n * ingest by default) and — if you pass `firestore` — installs the universal read\n * trap so every read counts automatically.\n */\nexport function init(options: InitOptions): void {\n  const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n  if (options.firestore) installFirestoreMeter(options.firestore);\n}\n\n/** Alias — reads well next to `bucket()` at a call site. */\nexport { init as initBuckets };\n\n// The headline verb + the lower-level tag controls it is sugar over.\nexport {\n  bucket,\n  runWithCostTag,\n  enterCostTag,\n  refineCostTag,\n  currentCostTag,\n  type CostTag,\n} from \"./cost-context\";\n\n// Manual recorders (for non-Firestore ops, or when you don't install the trap).\nexport {\n  recordReads,\n  recordWrites,\n  recordDeletes,\n  flush,\n  type CostHint,\n  type OpType,\n  type MeterConfig,\n} from \"./cost-meter\";\n\n// The trap (the only datastore adapter today) + its class shape.\nexport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\n// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.\nexport { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from \"./sink\";\n"]}

package/package.json

@@ -1,20 +1,17 @@
 {
   "name": "@cross-deck/buckets",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Know exactly what every database read costs you — and who caused it. A tiny, never-throws read-cost collector for Firestore.",
   "license": "MIT",
   "author": "Crossdeck",
-  "type": "module",
   "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./adapters/firestore": {
-      "types": "./dist/adapters/firestore.d.ts",
-      "import": "./dist/adapters/firestore.js"
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
     }
   },
   "files": [
@@ -24,10 +21,10 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc --noEmit",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },
@@ -61,6 +58,7 @@
   "devDependencies": {
     "@types/node": "^20.11.0",
     "firebase-admin": "^12.0.0",
+    "tsup": "^8.0.0",
     "typescript": "^5.4.0",
     "vitest": "^1.6.0"
   },

package/dist/adapters/firestore.d.ts

@@ -1,41 +0,0 @@
-type AnyFn = (...args: any[]) => any;
-/**
- * The firebase-admin Firestore classes to patch. Pass the module namespace from
- * `firebase-admin/firestore` — only the prototypes present are patched.
- */
-export interface FirestoreClasses {
-    Query?: {
-        prototype: {
-            get?: AnyFn;
-        };
-    };
-    DocumentReference?: {
-        prototype: {
-            get?: AnyFn;
-        };
-    };
-    Transaction?: {
-        prototype: {
-            get?: AnyFn;
-            getAll?: AnyFn;
-        };
-    };
-    Firestore?: {
-        prototype: {
-            getAll?: AnyFn;
-        };
-    };
-}
-/**
- * Install the universal read meter on the firebase-admin Firestore classes. Call
- * ONCE at process start, before any reads. Pass the namespace from
- * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:
- *
- *   import * as Firestore from "firebase-admin/firestore";
- *   installFirestoreMeter(Firestore);
- */
-export declare function installFirestoreMeter(classes: FirestoreClasses): void;
-/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */
-export declare function __resetFirestoreMeterForTests(): void;
-export {};
-//# sourceMappingURL=firestore.d.ts.map

package/dist/adapters/firestore.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"firestore.d.ts","sourceRoot":"","sources":["../../src/adapters/firestore.ts"],"names":[],"mappings":"AA+BA,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;IACvC,iBAAiB,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;IACnD,WAAW,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,CAAC,EAAE,KAAK,CAAC;YAAC,MAAM,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;IAC7D,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,MAAM,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/C;AAwDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAsDrE;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/adapters/firestore.js

@@ -1,145 +0,0 @@
-/**
- * adapters/firestore — the universal Firestore read meter (the trap).
- *
- * THE LESSON (learned on a real product): per-call-site `recordReads()`
- * instrumentation MISSES paths. You meter the read sites you're looking at and
- * leave the cron / trigger / ingest path uncounted — often the majority of reads,
- * invisible. Humans tag what they see and miss the path that matters.
- *
- * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY
- * read — anywhere, on any code path — is counted under the ambient tag, with zero
- * per-call-site work and no blind spots.
- *
- * SAFETY CONTRACT — this sits on your production read path, so it is defensive by
- * construction. Each wrapper:
- *   1. calls the REAL method first and captures the result,
- *   2. counts in a try/catch that can never throw into the caller,
- *   3. ALWAYS returns the real result, untouched.
- * It cannot break a read, change a result, or add latency beyond one in-memory
- * counter increment. A wrong count is a measurement error, never a correctness or
- * availability one. Idempotent — calling it twice patches once.
- *
- * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills
- * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.
- * CollectionReference.get IS Query.get (shared prototype method), so patching Query
- * covers collections with no double-count.
- */
-import { recordReads } from "../cost-meter.js";
-let installed = false;
-/** `projects/{id}/…` → the project id, else undefined. Pure string op. */
-function projectFromPath(path) {
-    const parts = path.split("/");
-    const i = parts.indexOf("projects");
-    return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;
-}
-/**
- * Derive { collection, projectId } from the read target's path so an UNtagged read
- * cascades to `col:<collection>` instead of "uncategorized". PURE CPU; never reads,
- * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered
- * queries (which don't expose `.path`).
- */
-function hintFrom(target) {
-    try {
-        const p = typeof target?.path === "string" ? target.path : "";
-        if (p) {
-            const parts = p.split("/").filter(Boolean);
-            const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];
-            return { collection, projectId: projectFromPath(p) };
-        }
-        const qo = target?._queryOptions;
-        if (qo) {
-            const collection = typeof qo.collectionId === "string" ? qo.collectionId : undefined;
-            const parent = typeof qo.parentPath?.relativeName === "string"
-                ? qo.parentPath.relativeName
-                : typeof qo.parentPath?.toString === "function"
-                    ? String(qo.parentPath.toString())
-                    : "";
-            return { collection, projectId: parent ? projectFromPath(parent) : undefined };
-        }
-    }
-    catch {
-        /* the meter must never throw */
-    }
-    return undefined;
-}
-function meterSnap(snap, hint) {
-    try {
-        const size = snap?.size;
-        recordReads(typeof size === "number" ? size : 1, hint);
-    }
-    catch {
-        /* best-effort */
-    }
-}
-function meterCount(n, hint) {
-    try {
-        recordReads(n, hint);
-    }
-    catch {
-        /* best-effort */
-    }
-}
-/**
- * Install the universal read meter on the firebase-admin Firestore classes. Call
- * ONCE at process start, before any reads. Pass the namespace from
- * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:
- *
- *   import * as Firestore from "firebase-admin/firestore";
- *   installFirestoreMeter(Firestore);
- */
-export function installFirestoreMeter(classes) {
-    if (installed)
-        return;
-    installed = true;
-    const { Query, DocumentReference, Transaction, Firestore } = classes;
-    // Query.get — covers Query AND CollectionReference (shared prototype method).
-    const qGet = Query?.prototype?.get;
-    if (qGet) {
-        Query.prototype.get = async function (...args) {
-            const snap = await qGet.apply(this, args);
-            meterSnap(snap, hintFrom(this));
-            return snap;
-        };
-    }
-    // DocumentReference.get — a single doc = 1 read.
-    const dGet = DocumentReference?.prototype?.get;
-    if (dGet) {
-        DocumentReference.prototype.get = async function (...args) {
-            const snap = await dGet.apply(this, args);
-            meterCount(1, hintFrom(this));
-            return snap;
-        };
-    }
-    // Transaction.get — query or doc; size when present, else 1.
-    const tGet = Transaction?.prototype?.get;
-    if (tGet) {
-        Transaction.prototype.get = async function (...args) {
-            const res = await tGet.apply(this, args);
-            meterSnap(res, hintFrom(args[0]));
-            return res;
-        };
-    }
-    // Transaction.getAll(...refs) — one read per ref.
-    const tGetAll = Transaction?.prototype?.getAll;
-    if (tGetAll) {
-        Transaction.prototype.getAll = async function (...args) {
-            const res = await tGetAll.apply(this, args);
-            meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));
-            return res;
-        };
-    }
-    // Firestore.getAll(...refs) — batched doc reads.
-    const fGetAll = Firestore?.prototype?.getAll;
-    if (fGetAll) {
-        Firestore.prototype.getAll = async function (...args) {
-            const res = await fGetAll.apply(this, args);
-            meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));
-            return res;
-        };
-    }
-}
-/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */
-export function __resetFirestoreMeterForTests() {
-    installed = false;
-}
-//# sourceMappingURL=firestore.js.map

package/dist/adapters/firestore.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"firestore.js","sourceRoot":"","sources":["../../src/adapters/firestore.ts"],"names":[],"mappings":"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"}

package/dist/cost-context.d.ts

@@ -1,25 +0,0 @@
-export interface CostTag {
-    /** Optional coarse grouping (a caller-defined surface name). */
-    feature?: string;
-    /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */
-    label?: string;
-}
-/** Run `fn` with `tag` bound for its entire async subtree. */
-export declare function runWithCostTag<T>(tag: CostTag, fn: () => T): T;
-/** Bind a tag for the remainder of the current async context (no closure to wrap). */
-export declare function enterCostTag(tag: CostTag): void;
-/** Refine the live tag in place (e.g. stamp a feature after the boundary). */
-export declare function refineCostTag(patch: Partial<CostTag>): void;
-/** The current tag, or a safe empty default outside any bound context. */
-export declare function currentCostTag(): CostTag;
-/**
- * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with
- * every operation inside it attributed to the bucket `name`; the attribution
- * rides the async subtree automatically. The one verb most developers ever touch:
- *
- *   await bucket("nightly-export", async () => {
- *     const rows = await db.collection("events").where(...).get(); // → "nightly-export"
- *   });
- */
-export declare function bucket<T>(name: string, fn: () => T): T;
-//# sourceMappingURL=cost-context.d.ts.map