@noy-db/to-meter 0.1.0-pre.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @noy-db/to-meter
+
+[![npm](https://img.shields.io/npm/v/%40noy-db/to-meter.svg)](https://www.npmjs.com/package/@noy-db/to-meter)
+
+> Pass-through meter for @noy-db/to-* stores
+
+Part of [**`@noy-db/hub`**](https://www.npmjs.com/package/@noy-db/hub) — the zero-knowledge, offline-first, encrypted document store.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/to-meter
+```
+
+## What it is
+
+Pass-through meter for @noy-db/to-* stores — wraps any NoydbStore and records per-method latency percentiles, error rates, and byte counts on real traffic. Optional synthetic liveness probe emits degraded / restored events. No synthetic benchmarks (see @noy-db/to-probe for that) — this measures what your app is actually doing.
+
+## Status
+
+**Pre-release** (`0.1.0-pre.1`). API may change before `1.0`.
+
+## Documentation
+
+See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
+
+- Source — [`packages/to-meter`](https://github.com/vLannaAi/noy-db/tree/main/packages/to-meter)
+- Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db/blob/main/SPEC.md)
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/index.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  toMeter: () => toMeter
+});
+module.exports = __toCommonJS(index_exports);
+var import_hub = require("@noy-db/hub");
+var METHODS = ["get", "put", "delete", "list", "loadAll", "saveAll"];
+function toMeter(inner, options = {}) {
+  const sampleLimit = options.sampleLimit ?? 1024;
+  const degradedMs = options.degradedMs ?? 500;
+  const samples = {
+    get: [],
+    put: [],
+    delete: [],
+    list: [],
+    loadAll: [],
+    saveAll: []
+  };
+  const counts = {
+    get: 0,
+    put: 0,
+    delete: 0,
+    list: 0,
+    loadAll: 0,
+    saveAll: 0
+  };
+  const errors = {
+    get: 0,
+    put: 0,
+    delete: 0,
+    list: 0,
+    loadAll: 0,
+    saveAll: 0
+  };
+  let casConflicts = 0;
+  let windowStart = Date.now();
+  let currentStatus = "ok";
+  const listeners = /* @__PURE__ */ new Set();
+  function recordOp(method, durationMs, success, error) {
+    counts[method]++;
+    if (!success) {
+      errors[method]++;
+      if (error instanceof import_hub.ConflictError) casConflicts++;
+    }
+    const arr = samples[method];
+    arr.push(durationMs);
+    if (arr.length > sampleLimit) {
+      arr.splice(0, arr.length - sampleLimit);
+    }
+    if (method === "put" && counts.put >= 10) {
+      const put = computeMethodStats(samples.put, counts.put, errors.put);
+      const breached = put.p99 > degradedMs;
+      if (breached && currentStatus === "ok") transition("degraded", method, put.p99, `put p99 ${put.p99}ms > ${degradedMs}ms`);
+      else if (!breached && currentStatus === "degraded") transition("ok", method, put.p99, `put p99 recovered to ${put.p99}ms`);
+    }
+  }
+  function transition(next, method, p99, reason = "") {
+    if (next === currentStatus) return;
+    const prior = currentStatus;
+    currentStatus = next;
+    const event = {
+      type: next === "ok" ? "restored" : "degraded",
+      status: next,
+      ...method !== void 0 ? { method } : {},
+      ...p99 !== void 0 ? { p99 } : {},
+      reason,
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    for (const l of listeners) {
+      try {
+        l(event);
+      } catch {
+      }
+    }
+    if (next === "degraded" && prior !== "degraded") options.onDegraded?.(event);
+    if (next === "ok" && prior !== "ok") options.onRestored?.(event);
+  }
+  const metrics = (0, import_hub.wrapStore)(
+    inner,
+    (0, import_hub.withMetrics)({
+      onOperation(op) {
+        recordOp(op.method, op.durationMs, op.success, op.error);
+      }
+    })
+  );
+  const livenessTimer = options.liveness ? startLiveness(inner, options.liveness, transition) : null;
+  const handle = {
+    snapshot() {
+      const byMethod = {};
+      let total = 0;
+      for (const m of METHODS) {
+        byMethod[m] = computeMethodStats(samples[m], counts[m], errors[m]);
+        total += counts[m];
+      }
+      return {
+        byMethod,
+        status: currentStatus,
+        casConflicts,
+        totalCalls: total,
+        windowMs: Date.now() - windowStart,
+        collectedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    },
+    reset() {
+      for (const m of METHODS) {
+        samples[m].length = 0;
+        counts[m] = 0;
+        errors[m] = 0;
+      }
+      casConflicts = 0;
+      windowStart = Date.now();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    close() {
+      if (livenessTimer) clearInterval(livenessTimer);
+      listeners.clear();
+    }
+  };
+  const renamed = {
+    ...metrics,
+    name: inner.name ? `meter(${inner.name})` : "meter"
+  };
+  return { store: renamed, meter: handle };
+}
+function computeMethodStats(sorted, count, errorCount) {
+  if (count === 0) {
+    return { count: 0, errors: 0, p50: 0, p90: 0, p99: 0, max: 0, avg: 0 };
+  }
+  const s = [...sorted].sort((a, b) => a - b);
+  const pct = (q) => s[Math.min(s.length - 1, Math.floor(q * s.length))];
+  const sum = s.reduce((a, b) => a + b, 0);
+  return {
+    count,
+    errors: errorCount,
+    p50: pct(0.5),
+    p90: pct(0.9),
+    p99: pct(0.99),
+    max: s[s.length - 1],
+    avg: Math.round(sum / s.length)
+  };
+}
+function startLiveness(inner, opts, transition) {
+  const vault = opts.vault ?? "probe-vault";
+  const collection = opts.collection ?? "probe-liveness";
+  const pingId = "liveness";
+  const timer = setInterval(() => {
+    void tick();
+  }, opts.interval);
+  async function tick() {
+    try {
+      if (typeof inner.ping === "function") {
+        const ok = await inner.ping();
+        if (!ok) return transition("unreachable", void 0, void 0, "ping returned false");
+      } else {
+        await inner.put(vault, collection, pingId, {
+          _noydb: 1,
+          _v: 1,
+          _ts: (/* @__PURE__ */ new Date()).toISOString(),
+          _iv: "AAAAAAAAAAAAAAAA",
+          _data: "cHJvYmU="
+        });
+        await inner.delete(vault, collection, pingId);
+      }
+      transition("ok", void 0, void 0, "liveness check succeeded");
+    } catch (err) {
+      transition("unreachable", void 0, void 0, `liveness error: ${err.message}`);
+    }
+  }
+  return timer;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  toMeter
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/to-meter** — pass-through meter for `@noy-db/to-*` stores.\n *\n * Wraps any `NoydbStore` and returns a new store that behaves\n * identically but records per-method timing, error rates, byte\n * counts, and (optionally) periodic liveness status. The meter is\n * itself a `NoydbStore`, so it slots anywhere a store fits:\n *\n * ```ts\n * import { toMeter } from '@noy-db/to-meter'\n * import { awsDynamoStore } from '@noy-db/to-aws-dynamo'\n *\n * const dynamo = awsDynamoStore({ table: 'live' })\n * const { store, meter } = toMeter(dynamo, {\n *   liveness:    { interval: 60_000 },    // optional synthetic pings\n *   degradedMs:  200,                     // p99 threshold for `degraded` event\n *   onDegraded:  (e) => console.warn(e),\n * })\n *\n * const db = await createNoydb({ store })\n *\n * // at any time\n * console.log(meter.snapshot())\n * // {\n * //   byMethod: {\n * //     get:  { count: 142, p50: 3, p99: 28, errors: 0 },\n * //     put:  { count:  43, p50: 11, p99: 92, errors: 1 },\n * //     ...\n * //   },\n * //   status: 'ok' | 'degraded' | 'unreachable',\n * //   casConflicts: 2,\n * //   totalCalls: 230,\n * //   windowMs: 45_280,\n * // }\n * ```\n *\n * ## Relation to `withMetrics`\n *\n * This package **uses** hub's `withMetrics` middleware internally —\n * don't think of it as a replacement. `withMetrics` is the raw event\n * stream (one callback per op); `toMeter` is the aggregator that\n * bucketises events into percentiles + a health verdict.\n *\n * ## Relation to `to-probe`\n *\n * - `to-probe` runs **synthetic** benchmarks on an empty store —\n *   answers \"should I adopt this store?\".\n * - `to-meter` observes **real traffic** through the live store —\n *   answers \"how is this store performing right now?\".\n *\n * Composable: `toMeter(probe-recommended-store)` after a probe pass\n * validates adoption.\n *\n * @packageDocumentation\n */\nimport type { NoydbStore } from '@noy-db/hub'\nimport { ConflictError, wrapStore, withMetrics } from '@noy-db/hub'\n\n// ── Types ───────────────────────────────────────────────────────────────\n\nexport type MethodName = 'get' | 'put' | 'delete' | 'list' | 'loadAll' | 'saveAll'\n\nexport type MeterStatus = 'ok' | 'degraded' | 'unreachable'\n\n/** Latency + counts for a single store method. */\nexport interface MethodStats {\n  readonly count: number\n  readonly errors: number\n  readonly p50: number\n  readonly p90: number\n  readonly p99: number\n  readonly max: number\n  readonly avg: number\n}\n\n/** Full snapshot of meter state at one moment. */\nexport interface MeterSnapshot {\n  readonly byMethod: Record<MethodName, MethodStats>\n  readonly status: MeterStatus\n  readonly casConflicts: number\n  readonly totalCalls: number\n  readonly windowMs: number\n  readonly collectedAt: string\n}\n\n/** Degraded/restored event. */\nexport interface MeterEvent {\n  readonly type: 'degraded' | 'restored'\n  readonly status: MeterStatus\n  readonly method?: MethodName\n  readonly p99?: number\n  readonly reason: string\n  readonly at: string\n}\n\nexport interface LivenessOptions {\n  /** Milliseconds between synthetic health checks. */\n  readonly interval: number\n  /** Vault to use for the liveness `put`/`delete` pair. Default `'probe-vault'`. */\n  readonly vault?: string\n  /** Collection to use. Default `'probe-liveness'`. Do NOT use a `_`-prefixed name. */\n  readonly collection?: string\n}\n\nexport interface MeterOptions {\n  /**\n   * Upper bound on retained latency samples per method. When the\n   * sample array grows past this, oldest entries are dropped. Default\n   * 1024 — keeps p50/p99 reasonably accurate with bounded memory.\n   */\n  readonly sampleLimit?: number\n  /**\n   * Optional periodic liveness ping. Uses the store's `ping()` if\n   * available, otherwise falls back to a `put`/`delete` pair on a\n   * dedicated collection.\n   */\n  readonly liveness?: LivenessOptions\n  /**\n   * p99 latency threshold (ms) for `put` — if crossed, emit a\n   * `degraded` event. Default 500.\n   */\n  readonly degradedMs?: number\n  /** Called when the meter transitions to `degraded`. */\n  readonly onDegraded?: (event: MeterEvent) => void\n  /** Called when the meter transitions back to `ok`. */\n  readonly onRestored?: (event: MeterEvent) => void\n}\n\n/** Handle returned alongside the wrapped store. */\nexport interface MeterHandle {\n  /** Current snapshot. Safe to call frequently — O(k log k) on sample sizes. */\n  snapshot(): MeterSnapshot\n  /** Reset all counters and drop samples. Handy for per-request metering. */\n  reset(): void\n  /** Subscribe to degraded/restored transitions. Returns an unsubscribe fn. */\n  subscribe(listener: (event: MeterEvent) => void): () => void\n  /** Stop the liveness timer (if any) and release resources. */\n  close(): void\n}\n\nexport interface ToMeterResult {\n  readonly store: NoydbStore\n  readonly meter: MeterHandle\n}\n\n// ── Implementation ──────────────────────────────────────────────────────\n\nconst METHODS: readonly MethodName[] = ['get', 'put', 'delete', 'list', 'loadAll', 'saveAll']\n\n/**\n * Wrap a store so every call is timed + counted. Returns the wrapped\n * store and a handle for inspecting the aggregate.\n *\n * The wrapped store is a drop-in replacement for the inner store —\n * same 6 methods, same types, same behaviour on success and error. The\n * meter adds zero semantic changes: errors still throw, conflicts\n * still surface as {@link ConflictError}.\n */\nexport function toMeter(inner: NoydbStore, options: MeterOptions = {}): ToMeterResult {\n  const sampleLimit = options.sampleLimit ?? 1024\n  const degradedMs = options.degradedMs ?? 500\n\n  const samples: Record<MethodName, number[]> = {\n    get: [], put: [], delete: [], list: [], loadAll: [], saveAll: [],\n  }\n  const counts: Record<MethodName, number> = {\n    get: 0, put: 0, delete: 0, list: 0, loadAll: 0, saveAll: 0,\n  }\n  const errors: Record<MethodName, number> = {\n    get: 0, put: 0, delete: 0, list: 0, loadAll: 0, saveAll: 0,\n  }\n  let casConflicts = 0\n  let windowStart = Date.now()\n  let currentStatus: MeterStatus = 'ok'\n  const listeners = new Set<(e: MeterEvent) => void>()\n\n  function recordOp(method: MethodName, durationMs: number, success: boolean, error?: Error): void {\n    counts[method]++\n    if (!success) {\n      errors[method]++\n      if (error instanceof ConflictError) casConflicts++\n    }\n    const arr = samples[method]\n    arr.push(durationMs)\n    if (arr.length > sampleLimit) {\n      arr.splice(0, arr.length - sampleLimit)\n    }\n    // Status transition check — only for put-method degraded thresholds\n    if (method === 'put' && counts.put >= 10) {\n      const put = computeMethodStats(samples.put, counts.put, errors.put)\n      const breached = put.p99 > degradedMs\n      if (breached && currentStatus === 'ok') transition('degraded', method, put.p99, `put p99 ${put.p99}ms > ${degradedMs}ms`)\n      else if (!breached && currentStatus === 'degraded') transition('ok', method, put.p99, `put p99 recovered to ${put.p99}ms`)\n    }\n  }\n\n  function transition(next: MeterStatus, method?: MethodName, p99?: number, reason = ''): void {\n    if (next === currentStatus) return\n    const prior = currentStatus\n    currentStatus = next\n    const event: MeterEvent = {\n      type: next === 'ok' ? 'restored' : 'degraded',\n      status: next,\n      ...(method !== undefined ? { method } : {}),\n      ...(p99 !== undefined ? { p99 } : {}),\n      reason, at: new Date().toISOString(),\n    }\n    for (const l of listeners) {\n      try { l(event) } catch { /* isolate listener errors */ }\n    }\n    if (next === 'degraded' && prior !== 'degraded') options.onDegraded?.(event)\n    if (next === 'ok' && prior !== 'ok') options.onRestored?.(event)\n  }\n\n  // Build the wrapped store via hub's withMetrics middleware (one event\n  // per op, already includes success/error + duration).\n  const metrics = wrapStore(\n    inner,\n    withMetrics({\n      onOperation(op) {\n        recordOp(op.method, op.durationMs, op.success, op.error)\n      },\n    }),\n  )\n\n  // Optional synthetic liveness timer\n  const livenessTimer = options.liveness\n    ? startLiveness(inner, options.liveness, transition)\n    : null\n\n  const handle: MeterHandle = {\n    snapshot(): MeterSnapshot {\n      const byMethod = {} as Record<MethodName, MethodStats>\n      let total = 0\n      for (const m of METHODS) {\n        byMethod[m] = computeMethodStats(samples[m], counts[m], errors[m])\n        total += counts[m]\n      }\n      return {\n        byMethod,\n        status: currentStatus,\n        casConflicts,\n        totalCalls: total,\n        windowMs: Date.now() - windowStart,\n        collectedAt: new Date().toISOString(),\n      }\n    },\n    reset(): void {\n      for (const m of METHODS) {\n        samples[m].length = 0\n        counts[m] = 0\n        errors[m] = 0\n      }\n      casConflicts = 0\n      windowStart = Date.now()\n    },\n    subscribe(listener): () => void {\n      listeners.add(listener)\n      return () => { listeners.delete(listener) }\n    },\n    close(): void {\n      if (livenessTimer) clearInterval(livenessTimer)\n      listeners.clear()\n    },\n  }\n\n  // Preserve the store name so routing/logging continues to identify\n  // the underlying backend.\n  const renamed: NoydbStore = {\n    ...metrics,\n    name: inner.name ? `meter(${inner.name})` : 'meter',\n  }\n\n  return { store: renamed, meter: handle }\n}\n\n// ── Internals ───────────────────────────────────────────────────────────\n\nfunction computeMethodStats(sorted: number[], count: number, errorCount: number): MethodStats {\n  if (count === 0) {\n    return { count: 0, errors: 0, p50: 0, p90: 0, p99: 0, max: 0, avg: 0 }\n  }\n  // Sort a copy so reads don't disturb the FIFO buffer\n  const s = [...sorted].sort((a, b) => a - b)\n  const pct = (q: number): number => s[Math.min(s.length - 1, Math.floor(q * s.length))]!\n  const sum = s.reduce((a, b) => a + b, 0)\n  return {\n    count,\n    errors: errorCount,\n    p50: pct(0.5),\n    p90: pct(0.9),\n    p99: pct(0.99),\n    max: s[s.length - 1]!,\n    avg: Math.round(sum / s.length),\n  }\n}\n\nfunction startLiveness(\n  inner: NoydbStore,\n  opts: LivenessOptions,\n  transition: (status: MeterStatus, method?: MethodName, p99?: number, reason?: string) => void,\n): ReturnType<typeof setInterval> {\n  const vault = opts.vault ?? 'probe-vault'\n  const collection = opts.collection ?? 'probe-liveness'\n  const pingId = 'liveness'\n\n  const timer = setInterval(() => {\n    void tick()\n  }, opts.interval)\n\n  async function tick(): Promise<void> {\n    try {\n      if (typeof inner.ping === 'function') {\n        const ok = await inner.ping()\n        if (!ok) return transition('unreachable', undefined, undefined, 'ping returned false')\n      } else {\n        // Fallback: put + delete — exercises the write path\n        await inner.put(vault, collection, pingId, {\n          _noydb: 1, _v: 1,\n          _ts: new Date().toISOString(),\n          _iv: 'AAAAAAAAAAAAAAAA',\n          _data: 'cHJvYmU=',\n        })\n        await inner.delete(vault, collection, pingId)\n      }\n      // On a successful check, transition back to ok if we were unreachable\n      transition('ok', undefined, undefined, 'liveness check succeeded')\n    } catch (err) {\n      transition('unreachable', undefined, undefined, `liveness error: ${(err as Error).message}`)\n    }\n  }\n\n  return timer\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,146 @@
+import { NoydbStore } from '@noy-db/hub';
+
+/**
+ * **@noy-db/to-meter** — pass-through meter for `@noy-db/to-*` stores.
+ *
+ * Wraps any `NoydbStore` and returns a new store that behaves
+ * identically but records per-method timing, error rates, byte
+ * counts, and (optionally) periodic liveness status. The meter is
+ * itself a `NoydbStore`, so it slots anywhere a store fits:
+ *
+ * ```ts
+ * import { toMeter } from '@noy-db/to-meter'
+ * import { awsDynamoStore } from '@noy-db/to-aws-dynamo'
+ *
+ * const dynamo = awsDynamoStore({ table: 'live' })
+ * const { store, meter } = toMeter(dynamo, {
+ *   liveness:    { interval: 60_000 },    // optional synthetic pings
+ *   degradedMs:  200,                     // p99 threshold for `degraded` event
+ *   onDegraded:  (e) => console.warn(e),
+ * })
+ *
+ * const db = await createNoydb({ store })
+ *
+ * // at any time
+ * console.log(meter.snapshot())
+ * // {
+ * //   byMethod: {
+ * //     get:  { count: 142, p50: 3, p99: 28, errors: 0 },
+ * //     put:  { count:  43, p50: 11, p99: 92, errors: 1 },
+ * //     ...
+ * //   },
+ * //   status: 'ok' | 'degraded' | 'unreachable',
+ * //   casConflicts: 2,
+ * //   totalCalls: 230,
+ * //   windowMs: 45_280,
+ * // }
+ * ```
+ *
+ * ## Relation to `withMetrics`
+ *
+ * This package **uses** hub's `withMetrics` middleware internally —
+ * don't think of it as a replacement. `withMetrics` is the raw event
+ * stream (one callback per op); `toMeter` is the aggregator that
+ * bucketises events into percentiles + a health verdict.
+ *
+ * ## Relation to `to-probe`
+ *
+ * - `to-probe` runs **synthetic** benchmarks on an empty store —
+ *   answers "should I adopt this store?".
+ * - `to-meter` observes **real traffic** through the live store —
+ *   answers "how is this store performing right now?".
+ *
+ * Composable: `toMeter(probe-recommended-store)` after a probe pass
+ * validates adoption.
+ *
+ * @packageDocumentation
+ */
+
+type MethodName = 'get' | 'put' | 'delete' | 'list' | 'loadAll' | 'saveAll';
+type MeterStatus = 'ok' | 'degraded' | 'unreachable';
+/** Latency + counts for a single store method. */
+interface MethodStats {
+    readonly count: number;
+    readonly errors: number;
+    readonly p50: number;
+    readonly p90: number;
+    readonly p99: number;
+    readonly max: number;
+    readonly avg: number;
+}
+/** Full snapshot of meter state at one moment. */
+interface MeterSnapshot {
+    readonly byMethod: Record<MethodName, MethodStats>;
+    readonly status: MeterStatus;
+    readonly casConflicts: number;
+    readonly totalCalls: number;
+    readonly windowMs: number;
+    readonly collectedAt: string;
+}
+/** Degraded/restored event. */
+interface MeterEvent {
+    readonly type: 'degraded' | 'restored';
+    readonly status: MeterStatus;
+    readonly method?: MethodName;
+    readonly p99?: number;
+    readonly reason: string;
+    readonly at: string;
+}
+interface LivenessOptions {
+    /** Milliseconds between synthetic health checks. */
+    readonly interval: number;
+    /** Vault to use for the liveness `put`/`delete` pair. Default `'probe-vault'`. */
+    readonly vault?: string;
+    /** Collection to use. Default `'probe-liveness'`. Do NOT use a `_`-prefixed name. */
+    readonly collection?: string;
+}
+interface MeterOptions {
+    /**
+     * Upper bound on retained latency samples per method. When the
+     * sample array grows past this, oldest entries are dropped. Default
+     * 1024 — keeps p50/p99 reasonably accurate with bounded memory.
+     */
+    readonly sampleLimit?: number;
+    /**
+     * Optional periodic liveness ping. Uses the store's `ping()` if
+     * available, otherwise falls back to a `put`/`delete` pair on a
+     * dedicated collection.
+     */
+    readonly liveness?: LivenessOptions;
+    /**
+     * p99 latency threshold (ms) for `put` — if crossed, emit a
+     * `degraded` event. Default 500.
+     */
+    readonly degradedMs?: number;
+    /** Called when the meter transitions to `degraded`. */
+    readonly onDegraded?: (event: MeterEvent) => void;
+    /** Called when the meter transitions back to `ok`. */
+    readonly onRestored?: (event: MeterEvent) => void;
+}
+/** Handle returned alongside the wrapped store. */
+interface MeterHandle {
+    /** Current snapshot. Safe to call frequently — O(k log k) on sample sizes. */
+    snapshot(): MeterSnapshot;
+    /** Reset all counters and drop samples. Handy for per-request metering. */
+    reset(): void;
+    /** Subscribe to degraded/restored transitions. Returns an unsubscribe fn. */
+    subscribe(listener: (event: MeterEvent) => void): () => void;
+    /** Stop the liveness timer (if any) and release resources. */
+    close(): void;
+}
+interface ToMeterResult {
+    readonly store: NoydbStore;
+    readonly meter: MeterHandle;
+}
+/**
+ * Wrap a store so every call is timed + counted. Returns the wrapped
+ * store and a handle for inspecting the aggregate.
+ *
+ * The wrapped store is a drop-in replacement for the inner store —
+ * same 6 methods, same types, same behaviour on success and error. The
+ * meter adds zero semantic changes: errors still throw, conflicts
+ * still surface as {@link ConflictError}.
+ */
+declare function toMeter(inner: NoydbStore, options?: MeterOptions): ToMeterResult;
+
+export { type LivenessOptions, type MeterEvent, type MeterHandle, type MeterOptions, type MeterSnapshot, type MeterStatus, type MethodName, type MethodStats, type ToMeterResult, toMeter };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { NoydbStore } from '@noy-db/hub';
+
+/**
+ * **@noy-db/to-meter** — pass-through meter for `@noy-db/to-*` stores.
+ *
+ * Wraps any `NoydbStore` and returns a new store that behaves
+ * identically but records per-method timing, error rates, byte
+ * counts, and (optionally) periodic liveness status. The meter is
+ * itself a `NoydbStore`, so it slots anywhere a store fits:
+ *
+ * ```ts
+ * import { toMeter } from '@noy-db/to-meter'
+ * import { awsDynamoStore } from '@noy-db/to-aws-dynamo'
+ *
+ * const dynamo = awsDynamoStore({ table: 'live' })
+ * const { store, meter } = toMeter(dynamo, {
+ *   liveness:    { interval: 60_000 },    // optional synthetic pings
+ *   degradedMs:  200,                     // p99 threshold for `degraded` event
+ *   onDegraded:  (e) => console.warn(e),
+ * })
+ *
+ * const db = await createNoydb({ store })
+ *
+ * // at any time
+ * console.log(meter.snapshot())
+ * // {
+ * //   byMethod: {
+ * //     get:  { count: 142, p50: 3, p99: 28, errors: 0 },
+ * //     put:  { count:  43, p50: 11, p99: 92, errors: 1 },
+ * //     ...
+ * //   },
+ * //   status: 'ok' | 'degraded' | 'unreachable',
+ * //   casConflicts: 2,
+ * //   totalCalls: 230,
+ * //   windowMs: 45_280,
+ * // }
+ * ```
+ *
+ * ## Relation to `withMetrics`
+ *
+ * This package **uses** hub's `withMetrics` middleware internally —
+ * don't think of it as a replacement. `withMetrics` is the raw event
+ * stream (one callback per op); `toMeter` is the aggregator that
+ * bucketises events into percentiles + a health verdict.
+ *
+ * ## Relation to `to-probe`
+ *
+ * - `to-probe` runs **synthetic** benchmarks on an empty store —
+ *   answers "should I adopt this store?".
+ * - `to-meter` observes **real traffic** through the live store —
+ *   answers "how is this store performing right now?".
+ *
+ * Composable: `toMeter(probe-recommended-store)` after a probe pass
+ * validates adoption.
+ *
+ * @packageDocumentation
+ */
+
+type MethodName = 'get' | 'put' | 'delete' | 'list' | 'loadAll' | 'saveAll';
+type MeterStatus = 'ok' | 'degraded' | 'unreachable';
+/** Latency + counts for a single store method. */
+interface MethodStats {
+    readonly count: number;
+    readonly errors: number;
+    readonly p50: number;
+    readonly p90: number;
+    readonly p99: number;
+    readonly max: number;
+    readonly avg: number;
+}
+/** Full snapshot of meter state at one moment. */
+interface MeterSnapshot {
+    readonly byMethod: Record<MethodName, MethodStats>;
+    readonly status: MeterStatus;
+    readonly casConflicts: number;
+    readonly totalCalls: number;
+    readonly windowMs: number;
+    readonly collectedAt: string;
+}
+/** Degraded/restored event. */
+interface MeterEvent {
+    readonly type: 'degraded' | 'restored';
+    readonly status: MeterStatus;
+    readonly method?: MethodName;
+    readonly p99?: number;
+    readonly reason: string;
+    readonly at: string;
+}
+interface LivenessOptions {
+    /** Milliseconds between synthetic health checks. */
+    readonly interval: number;
+    /** Vault to use for the liveness `put`/`delete` pair. Default `'probe-vault'`. */
+    readonly vault?: string;
+    /** Collection to use. Default `'probe-liveness'`. Do NOT use a `_`-prefixed name. */
+    readonly collection?: string;
+}
+interface MeterOptions {
+    /**
+     * Upper bound on retained latency samples per method. When the
+     * sample array grows past this, oldest entries are dropped. Default
+     * 1024 — keeps p50/p99 reasonably accurate with bounded memory.
+     */
+    readonly sampleLimit?: number;
+    /**
+     * Optional periodic liveness ping. Uses the store's `ping()` if
+     * available, otherwise falls back to a `put`/`delete` pair on a
+     * dedicated collection.
+     */
+    readonly liveness?: LivenessOptions;
+    /**
+     * p99 latency threshold (ms) for `put` — if crossed, emit a
+     * `degraded` event. Default 500.
+     */
+    readonly degradedMs?: number;
+    /** Called when the meter transitions to `degraded`. */
+    readonly onDegraded?: (event: MeterEvent) => void;
+    /** Called when the meter transitions back to `ok`. */
+    readonly onRestored?: (event: MeterEvent) => void;
+}
+/** Handle returned alongside the wrapped store. */
+interface MeterHandle {
+    /** Current snapshot. Safe to call frequently — O(k log k) on sample sizes. */
+    snapshot(): MeterSnapshot;
+    /** Reset all counters and drop samples. Handy for per-request metering. */
+    reset(): void;
+    /** Subscribe to degraded/restored transitions. Returns an unsubscribe fn. */
+    subscribe(listener: (event: MeterEvent) => void): () => void;
+    /** Stop the liveness timer (if any) and release resources. */
+    close(): void;
+}
+interface ToMeterResult {
+    readonly store: NoydbStore;
+    readonly meter: MeterHandle;
+}
+/**
+ * Wrap a store so every call is timed + counted. Returns the wrapped
+ * store and a handle for inspecting the aggregate.
+ *
+ * The wrapped store is a drop-in replacement for the inner store —
+ * same 6 methods, same types, same behaviour on success and error. The
+ * meter adds zero semantic changes: errors still throw, conflicts
+ * still surface as {@link ConflictError}.
+ */
+declare function toMeter(inner: NoydbStore, options?: MeterOptions): ToMeterResult;
+
+export { type LivenessOptions, type MeterEvent, type MeterHandle, type MeterOptions, type MeterSnapshot, type MeterStatus, type MethodName, type MethodStats, type ToMeterResult, toMeter };

package/dist/index.js

@@ -0,0 +1,175 @@
+// src/index.ts
+import { ConflictError, wrapStore, withMetrics } from "@noy-db/hub";
+var METHODS = ["get", "put", "delete", "list", "loadAll", "saveAll"];
+function toMeter(inner, options = {}) {
+  const sampleLimit = options.sampleLimit ?? 1024;
+  const degradedMs = options.degradedMs ?? 500;
+  const samples = {
+    get: [],
+    put: [],
+    delete: [],
+    list: [],
+    loadAll: [],
+    saveAll: []
+  };
+  const counts = {
+    get: 0,
+    put: 0,
+    delete: 0,
+    list: 0,
+    loadAll: 0,
+    saveAll: 0
+  };
+  const errors = {
+    get: 0,
+    put: 0,
+    delete: 0,
+    list: 0,
+    loadAll: 0,
+    saveAll: 0
+  };
+  let casConflicts = 0;
+  let windowStart = Date.now();
+  let currentStatus = "ok";
+  const listeners = /* @__PURE__ */ new Set();
+  function recordOp(method, durationMs, success, error) {
+    counts[method]++;
+    if (!success) {
+      errors[method]++;
+      if (error instanceof ConflictError) casConflicts++;
+    }
+    const arr = samples[method];
+    arr.push(durationMs);
+    if (arr.length > sampleLimit) {
+      arr.splice(0, arr.length - sampleLimit);
+    }
+    if (method === "put" && counts.put >= 10) {
+      const put = computeMethodStats(samples.put, counts.put, errors.put);
+      const breached = put.p99 > degradedMs;
+      if (breached && currentStatus === "ok") transition("degraded", method, put.p99, `put p99 ${put.p99}ms > ${degradedMs}ms`);
+      else if (!breached && currentStatus === "degraded") transition("ok", method, put.p99, `put p99 recovered to ${put.p99}ms`);
+    }
+  }
+  function transition(next, method, p99, reason = "") {
+    if (next === currentStatus) return;
+    const prior = currentStatus;
+    currentStatus = next;
+    const event = {
+      type: next === "ok" ? "restored" : "degraded",
+      status: next,
+      ...method !== void 0 ? { method } : {},
+      ...p99 !== void 0 ? { p99 } : {},
+      reason,
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    for (const l of listeners) {
+      try {
+        l(event);
+      } catch {
+      }
+    }
+    if (next === "degraded" && prior !== "degraded") options.onDegraded?.(event);
+    if (next === "ok" && prior !== "ok") options.onRestored?.(event);
+  }
+  const metrics = wrapStore(
+    inner,
+    withMetrics({
+      onOperation(op) {
+        recordOp(op.method, op.durationMs, op.success, op.error);
+      }
+    })
+  );
+  const livenessTimer = options.liveness ? startLiveness(inner, options.liveness, transition) : null;
+  const handle = {
+    snapshot() {
+      const byMethod = {};
+      let total = 0;
+      for (const m of METHODS) {
+        byMethod[m] = computeMethodStats(samples[m], counts[m], errors[m]);
+        total += counts[m];
+      }
+      return {
+        byMethod,
+        status: currentStatus,
+        casConflicts,
+        totalCalls: total,
+        windowMs: Date.now() - windowStart,
+        collectedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    },
+    reset() {
+      for (const m of METHODS) {
+        samples[m].length = 0;
+        counts[m] = 0;
+        errors[m] = 0;
+      }
+      casConflicts = 0;
+      windowStart = Date.now();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    close() {
+      if (livenessTimer) clearInterval(livenessTimer);
+      listeners.clear();
+    }
+  };
+  const renamed = {
+    ...metrics,
+    name: inner.name ? `meter(${inner.name})` : "meter"
+  };
+  return { store: renamed, meter: handle };
+}
+function computeMethodStats(sorted, count, errorCount) {
+  if (count === 0) {
+    return { count: 0, errors: 0, p50: 0, p90: 0, p99: 0, max: 0, avg: 0 };
+  }
+  const s = [...sorted].sort((a, b) => a - b);
+  const pct = (q) => s[Math.min(s.length - 1, Math.floor(q * s.length))];
+  const sum = s.reduce((a, b) => a + b, 0);
+  return {
+    count,
+    errors: errorCount,
+    p50: pct(0.5),
+    p90: pct(0.9),
+    p99: pct(0.99),
+    max: s[s.length - 1],
+    avg: Math.round(sum / s.length)
+  };
+}
+function startLiveness(inner, opts, transition) {
+  const vault = opts.vault ?? "probe-vault";
+  const collection = opts.collection ?? "probe-liveness";
+  const pingId = "liveness";
+  const timer = setInterval(() => {
+    void tick();
+  }, opts.interval);
+  async function tick() {
+    try {
+      if (typeof inner.ping === "function") {
+        const ok = await inner.ping();
+        if (!ok) return transition("unreachable", void 0, void 0, "ping returned false");
+      } else {
+        await inner.put(vault, collection, pingId, {
+          _noydb: 1,
+          _v: 1,
+          _ts: (/* @__PURE__ */ new Date()).toISOString(),
+          _iv: "AAAAAAAAAAAAAAAA",
+          _data: "cHJvYmU="
+        });
+        await inner.delete(vault, collection, pingId);
+      }
+      transition("ok", void 0, void 0, "liveness check succeeded");
+    } catch (err) {
+      transition("unreachable", void 0, void 0, `liveness error: ${err.message}`);
+    }
+  }
+  return timer;
+}
+export {
+  toMeter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/to-meter** — pass-through meter for `@noy-db/to-*` stores.\n *\n * Wraps any `NoydbStore` and returns a new store that behaves\n * identically but records per-method timing, error rates, byte\n * counts, and (optionally) periodic liveness status. The meter is\n * itself a `NoydbStore`, so it slots anywhere a store fits:\n *\n * ```ts\n * import { toMeter } from '@noy-db/to-meter'\n * import { awsDynamoStore } from '@noy-db/to-aws-dynamo'\n *\n * const dynamo = awsDynamoStore({ table: 'live' })\n * const { store, meter } = toMeter(dynamo, {\n *   liveness:    { interval: 60_000 },    // optional synthetic pings\n *   degradedMs:  200,                     // p99 threshold for `degraded` event\n *   onDegraded:  (e) => console.warn(e),\n * })\n *\n * const db = await createNoydb({ store })\n *\n * // at any time\n * console.log(meter.snapshot())\n * // {\n * //   byMethod: {\n * //     get:  { count: 142, p50: 3, p99: 28, errors: 0 },\n * //     put:  { count:  43, p50: 11, p99: 92, errors: 1 },\n * //     ...\n * //   },\n * //   status: 'ok' | 'degraded' | 'unreachable',\n * //   casConflicts: 2,\n * //   totalCalls: 230,\n * //   windowMs: 45_280,\n * // }\n * ```\n *\n * ## Relation to `withMetrics`\n *\n * This package **uses** hub's `withMetrics` middleware internally —\n * don't think of it as a replacement. `withMetrics` is the raw event\n * stream (one callback per op); `toMeter` is the aggregator that\n * bucketises events into percentiles + a health verdict.\n *\n * ## Relation to `to-probe`\n *\n * - `to-probe` runs **synthetic** benchmarks on an empty store —\n *   answers \"should I adopt this store?\".\n * - `to-meter` observes **real traffic** through the live store —\n *   answers \"how is this store performing right now?\".\n *\n * Composable: `toMeter(probe-recommended-store)` after a probe pass\n * validates adoption.\n *\n * @packageDocumentation\n */\nimport type { NoydbStore } from '@noy-db/hub'\nimport { ConflictError, wrapStore, withMetrics } from '@noy-db/hub'\n\n// ── Types ───────────────────────────────────────────────────────────────\n\nexport type MethodName = 'get' | 'put' | 'delete' | 'list' | 'loadAll' | 'saveAll'\n\nexport type MeterStatus = 'ok' | 'degraded' | 'unreachable'\n\n/** Latency + counts for a single store method. */\nexport interface MethodStats {\n  readonly count: number\n  readonly errors: number\n  readonly p50: number\n  readonly p90: number\n  readonly p99: number\n  readonly max: number\n  readonly avg: number\n}\n\n/** Full snapshot of meter state at one moment. */\nexport interface MeterSnapshot {\n  readonly byMethod: Record<MethodName, MethodStats>\n  readonly status: MeterStatus\n  readonly casConflicts: number\n  readonly totalCalls: number\n  readonly windowMs: number\n  readonly collectedAt: string\n}\n\n/** Degraded/restored event. */\nexport interface MeterEvent {\n  readonly type: 'degraded' | 'restored'\n  readonly status: MeterStatus\n  readonly method?: MethodName\n  readonly p99?: number\n  readonly reason: string\n  readonly at: string\n}\n\nexport interface LivenessOptions {\n  /** Milliseconds between synthetic health checks. */\n  readonly interval: number\n  /** Vault to use for the liveness `put`/`delete` pair. Default `'probe-vault'`. */\n  readonly vault?: string\n  /** Collection to use. Default `'probe-liveness'`. Do NOT use a `_`-prefixed name. */\n  readonly collection?: string\n}\n\nexport interface MeterOptions {\n  /**\n   * Upper bound on retained latency samples per method. When the\n   * sample array grows past this, oldest entries are dropped. Default\n   * 1024 — keeps p50/p99 reasonably accurate with bounded memory.\n   */\n  readonly sampleLimit?: number\n  /**\n   * Optional periodic liveness ping. Uses the store's `ping()` if\n   * available, otherwise falls back to a `put`/`delete` pair on a\n   * dedicated collection.\n   */\n  readonly liveness?: LivenessOptions\n  /**\n   * p99 latency threshold (ms) for `put` — if crossed, emit a\n   * `degraded` event. Default 500.\n   */\n  readonly degradedMs?: number\n  /** Called when the meter transitions to `degraded`. */\n  readonly onDegraded?: (event: MeterEvent) => void\n  /** Called when the meter transitions back to `ok`. */\n  readonly onRestored?: (event: MeterEvent) => void\n}\n\n/** Handle returned alongside the wrapped store. */\nexport interface MeterHandle {\n  /** Current snapshot. Safe to call frequently — O(k log k) on sample sizes. */\n  snapshot(): MeterSnapshot\n  /** Reset all counters and drop samples. Handy for per-request metering. */\n  reset(): void\n  /** Subscribe to degraded/restored transitions. Returns an unsubscribe fn. */\n  subscribe(listener: (event: MeterEvent) => void): () => void\n  /** Stop the liveness timer (if any) and release resources. */\n  close(): void\n}\n\nexport interface ToMeterResult {\n  readonly store: NoydbStore\n  readonly meter: MeterHandle\n}\n\n// ── Implementation ──────────────────────────────────────────────────────\n\nconst METHODS: readonly MethodName[] = ['get', 'put', 'delete', 'list', 'loadAll', 'saveAll']\n\n/**\n * Wrap a store so every call is timed + counted. Returns the wrapped\n * store and a handle for inspecting the aggregate.\n *\n * The wrapped store is a drop-in replacement for the inner store —\n * same 6 methods, same types, same behaviour on success and error. The\n * meter adds zero semantic changes: errors still throw, conflicts\n * still surface as {@link ConflictError}.\n */\nexport function toMeter(inner: NoydbStore, options: MeterOptions = {}): ToMeterResult {\n  const sampleLimit = options.sampleLimit ?? 1024\n  const degradedMs = options.degradedMs ?? 500\n\n  const samples: Record<MethodName, number[]> = {\n    get: [], put: [], delete: [], list: [], loadAll: [], saveAll: [],\n  }\n  const counts: Record<MethodName, number> = {\n    get: 0, put: 0, delete: 0, list: 0, loadAll: 0, saveAll: 0,\n  }\n  const errors: Record<MethodName, number> = {\n    get: 0, put: 0, delete: 0, list: 0, loadAll: 0, saveAll: 0,\n  }\n  let casConflicts = 0\n  let windowStart = Date.now()\n  let currentStatus: MeterStatus = 'ok'\n  const listeners = new Set<(e: MeterEvent) => void>()\n\n  function recordOp(method: MethodName, durationMs: number, success: boolean, error?: Error): void {\n    counts[method]++\n    if (!success) {\n      errors[method]++\n      if (error instanceof ConflictError) casConflicts++\n    }\n    const arr = samples[method]\n    arr.push(durationMs)\n    if (arr.length > sampleLimit) {\n      arr.splice(0, arr.length - sampleLimit)\n    }\n    // Status transition check — only for put-method degraded thresholds\n    if (method === 'put' && counts.put >= 10) {\n      const put = computeMethodStats(samples.put, counts.put, errors.put)\n      const breached = put.p99 > degradedMs\n      if (breached && currentStatus === 'ok') transition('degraded', method, put.p99, `put p99 ${put.p99}ms > ${degradedMs}ms`)\n      else if (!breached && currentStatus === 'degraded') transition('ok', method, put.p99, `put p99 recovered to ${put.p99}ms`)\n    }\n  }\n\n  function transition(next: MeterStatus, method?: MethodName, p99?: number, reason = ''): void {\n    if (next === currentStatus) return\n    const prior = currentStatus\n    currentStatus = next\n    const event: MeterEvent = {\n      type: next === 'ok' ? 'restored' : 'degraded',\n      status: next,\n      ...(method !== undefined ? { method } : {}),\n      ...(p99 !== undefined ? { p99 } : {}),\n      reason, at: new Date().toISOString(),\n    }\n    for (const l of listeners) {\n      try { l(event) } catch { /* isolate listener errors */ }\n    }\n    if (next === 'degraded' && prior !== 'degraded') options.onDegraded?.(event)\n    if (next === 'ok' && prior !== 'ok') options.onRestored?.(event)\n  }\n\n  // Build the wrapped store via hub's withMetrics middleware (one event\n  // per op, already includes success/error + duration).\n  const metrics = wrapStore(\n    inner,\n    withMetrics({\n      onOperation(op) {\n        recordOp(op.method, op.durationMs, op.success, op.error)\n      },\n    }),\n  )\n\n  // Optional synthetic liveness timer\n  const livenessTimer = options.liveness\n    ? startLiveness(inner, options.liveness, transition)\n    : null\n\n  const handle: MeterHandle = {\n    snapshot(): MeterSnapshot {\n      const byMethod = {} as Record<MethodName, MethodStats>\n      let total = 0\n      for (const m of METHODS) {\n        byMethod[m] = computeMethodStats(samples[m], counts[m], errors[m])\n        total += counts[m]\n      }\n      return {\n        byMethod,\n        status: currentStatus,\n        casConflicts,\n        totalCalls: total,\n        windowMs: Date.now() - windowStart,\n        collectedAt: new Date().toISOString(),\n      }\n    },\n    reset(): void {\n      for (const m of METHODS) {\n        samples[m].length = 0\n        counts[m] = 0\n        errors[m] = 0\n      }\n      casConflicts = 0\n      windowStart = Date.now()\n    },\n    subscribe(listener): () => void {\n      listeners.add(listener)\n      return () => { listeners.delete(listener) }\n    },\n    close(): void {\n      if (livenessTimer) clearInterval(livenessTimer)\n      listeners.clear()\n    },\n  }\n\n  // Preserve the store name so routing/logging continues to identify\n  // the underlying backend.\n  const renamed: NoydbStore = {\n    ...metrics,\n    name: inner.name ? `meter(${inner.name})` : 'meter',\n  }\n\n  return { store: renamed, meter: handle }\n}\n\n// ── Internals ───────────────────────────────────────────────────────────\n\nfunction computeMethodStats(sorted: number[], count: number, errorCount: number): MethodStats {\n  if (count === 0) {\n    return { count: 0, errors: 0, p50: 0, p90: 0, p99: 0, max: 0, avg: 0 }\n  }\n  // Sort a copy so reads don't disturb the FIFO buffer\n  const s = [...sorted].sort((a, b) => a - b)\n  const pct = (q: number): number => s[Math.min(s.length - 1, Math.floor(q * s.length))]!\n  const sum = s.reduce((a, b) => a + b, 0)\n  return {\n    count,\n    errors: errorCount,\n    p50: pct(0.5),\n    p90: pct(0.9),\n    p99: pct(0.99),\n    max: s[s.length - 1]!,\n    avg: Math.round(sum / s.length),\n  }\n}\n\nfunction startLiveness(\n  inner: NoydbStore,\n  opts: LivenessOptions,\n  transition: (status: MeterStatus, method?: MethodName, p99?: number, reason?: string) => void,\n): ReturnType<typeof setInterval> {\n  const vault = opts.vault ?? 'probe-vault'\n  const collection = opts.collection ?? 'probe-liveness'\n  const pingId = 'liveness'\n\n  const timer = setInterval(() => {\n    void tick()\n  }, opts.interval)\n\n  async function tick(): Promise<void> {\n    try {\n      if (typeof inner.ping === 'function') {\n        const ok = await inner.ping()\n        if (!ok) return transition('unreachable', undefined, undefined, 'ping returned false')\n      } else {\n        // Fallback: put + delete — exercises the write path\n        await inner.put(vault, collection, pingId, {\n          _noydb: 1, _v: 1,\n          _ts: new Date().toISOString(),\n          _iv: 'AAAAAAAAAAAAAAAA',\n          _data: 'cHJvYmU=',\n        })\n        await inner.delete(vault, collection, pingId)\n      }\n      // On a successful check, transition back to ok if we were unreachable\n      transition('ok', undefined, undefined, 'liveness check succeeded')\n    } catch (err) {\n      transition('unreachable', undefined, undefined, `liveness error: ${(err as Error).message}`)\n    }\n  }\n\n  return timer\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@noy-db/to-meter",
+  "version": "0.1.0-pre.3",
+  "description": "Pass-through meter for @noy-db/to-* stores — wraps any NoydbStore and records per-method latency percentiles, error rates, and byte counts on real traffic. Optional synthetic liveness probe emits degraded / restored events. No synthetic benchmarks (see @noy-db/to-probe for that) — this measures what your app is actually doing.",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/to-meter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/to-meter"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "keywords": [
+    "noy-db",
+    "to-meter",
+    "metrics",
+    "percentiles",
+    "observability",
+    "monitoring",
+    "pass-through",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}