@x12i/countex 1.0.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (317) hide show
  1. package/README.md +215 -4
  2. package/dist/backup/export.d.ts +2 -0
  3. package/dist/backup/export.d.ts.map +1 -1
  4. package/dist/backup/export.js +2 -0
  5. package/dist/backup/export.js.map +1 -1
  6. package/dist/backup/manifest.d.ts +49 -0
  7. package/dist/backup/manifest.d.ts.map +1 -0
  8. package/dist/backup/manifest.js +103 -0
  9. package/dist/backup/manifest.js.map +1 -0
  10. package/dist/backup/snapshot-encoding.d.ts +8 -0
  11. package/dist/backup/snapshot-encoding.d.ts.map +1 -0
  12. package/dist/backup/snapshot-encoding.js +27 -0
  13. package/dist/backup/snapshot-encoding.js.map +1 -0
  14. package/dist/cli.d.ts +12 -0
  15. package/dist/cli.d.ts.map +1 -0
  16. package/dist/cli.js +206 -0
  17. package/dist/cli.js.map +1 -0
  18. package/dist/core/buffer.d.ts +4 -3
  19. package/dist/core/buffer.d.ts.map +1 -1
  20. package/dist/core/buffer.js +65 -9
  21. package/dist/core/buffer.js.map +1 -1
  22. package/dist/core/countex.d.ts +14 -1
  23. package/dist/core/countex.d.ts.map +1 -1
  24. package/dist/core/countex.js +171 -48
  25. package/dist/core/countex.js.map +1 -1
  26. package/dist/core/extraction.d.ts +14 -6
  27. package/dist/core/extraction.d.ts.map +1 -1
  28. package/dist/core/extraction.js +117 -1
  29. package/dist/core/extraction.js.map +1 -1
  30. package/dist/core/mapping.d.ts +5 -0
  31. package/dist/core/mapping.d.ts.map +1 -1
  32. package/dist/core/mapping.js +71 -1
  33. package/dist/core/mapping.js.map +1 -1
  34. package/dist/core/timeframe.d.ts +7 -0
  35. package/dist/core/timeframe.d.ts.map +1 -1
  36. package/dist/core/timeframe.js +88 -0
  37. package/dist/core/timeframe.js.map +1 -1
  38. package/dist/index.d.ts +4 -1
  39. package/dist/index.d.ts.map +1 -1
  40. package/dist/index.js +13 -1
  41. package/dist/index.js.map +1 -1
  42. package/dist/insights/advisors/fanout-health.d.ts +3 -0
  43. package/dist/insights/advisors/fanout-health.d.ts.map +1 -0
  44. package/dist/insights/advisors/fanout-health.js +3 -0
  45. package/dist/insights/advisors/fanout-health.js.map +1 -0
  46. package/dist/insights/advisors/map-health.d.ts +6 -0
  47. package/dist/insights/advisors/map-health.d.ts.map +1 -0
  48. package/dist/insights/advisors/map-health.js +154 -0
  49. package/dist/insights/advisors/map-health.js.map +1 -0
  50. package/dist/insights/advisors/resource-advisor.d.ts +4 -0
  51. package/dist/insights/advisors/resource-advisor.d.ts.map +1 -0
  52. package/dist/insights/advisors/resource-advisor.js +102 -0
  53. package/dist/insights/advisors/resource-advisor.js.map +1 -0
  54. package/dist/insights/advisors/retention-advisor.d.ts +2 -0
  55. package/dist/insights/advisors/retention-advisor.d.ts.map +1 -0
  56. package/dist/insights/advisors/retention-advisor.js +6 -0
  57. package/dist/insights/advisors/retention-advisor.js.map +1 -0
  58. package/dist/insights/advisors-subpath.d.ts +4 -0
  59. package/dist/insights/advisors-subpath.d.ts.map +1 -0
  60. package/dist/insights/advisors-subpath.js +10 -0
  61. package/dist/insights/advisors-subpath.js.map +1 -0
  62. package/dist/insights/anomaly/baseline.d.ts +4 -0
  63. package/dist/insights/anomaly/baseline.d.ts.map +1 -0
  64. package/dist/insights/anomaly/baseline.js +54 -0
  65. package/dist/insights/anomaly/baseline.js.map +1 -0
  66. package/dist/insights/anomaly/detect-anomalies.d.ts +6 -0
  67. package/dist/insights/anomaly/detect-anomalies.d.ts.map +1 -0
  68. package/dist/insights/anomaly/detect-anomalies.js +245 -0
  69. package/dist/insights/anomaly/detect-anomalies.js.map +1 -0
  70. package/dist/insights/anomaly/ewma.d.ts +2 -0
  71. package/dist/insights/anomaly/ewma.d.ts.map +1 -0
  72. package/dist/insights/anomaly/ewma.js +15 -0
  73. package/dist/insights/anomaly/ewma.js.map +1 -0
  74. package/dist/insights/anomaly/missing-activity.d.ts +3 -0
  75. package/dist/insights/anomaly/missing-activity.d.ts.map +1 -0
  76. package/dist/insights/anomaly/missing-activity.js +8 -0
  77. package/dist/insights/anomaly/missing-activity.js.map +1 -0
  78. package/dist/insights/anomaly/robust-zscore.d.ts +2 -0
  79. package/dist/insights/anomaly/robust-zscore.d.ts.map +1 -0
  80. package/dist/insights/anomaly/robust-zscore.js +9 -0
  81. package/dist/insights/anomaly/robust-zscore.js.map +1 -0
  82. package/dist/insights/anomaly-subpath.d.ts +7 -0
  83. package/dist/insights/anomaly-subpath.d.ts.map +1 -0
  84. package/dist/insights/anomaly-subpath.js +20 -0
  85. package/dist/insights/anomaly-subpath.js.map +1 -0
  86. package/dist/insights/comparison/compare-periods.d.ts +5 -0
  87. package/dist/insights/comparison/compare-periods.d.ts.map +1 -0
  88. package/dist/insights/comparison/compare-periods.js +64 -0
  89. package/dist/insights/comparison/compare-periods.js.map +1 -0
  90. package/dist/insights/comparison/growth-rate.d.ts +3 -0
  91. package/dist/insights/comparison/growth-rate.d.ts.map +1 -0
  92. package/dist/insights/comparison/growth-rate.js +3 -0
  93. package/dist/insights/comparison/growth-rate.js.map +1 -0
  94. package/dist/insights/comparison/moving-average.d.ts +2 -0
  95. package/dist/insights/comparison/moving-average.d.ts.map +1 -0
  96. package/dist/insights/comparison/moving-average.js +6 -0
  97. package/dist/insights/comparison/moving-average.js.map +1 -0
  98. package/dist/insights/comparison/trend.d.ts +5 -0
  99. package/dist/insights/comparison/trend.d.ts.map +1 -0
  100. package/dist/insights/comparison/trend.js +84 -0
  101. package/dist/insights/comparison/trend.js.map +1 -0
  102. package/dist/insights/errors.d.ts +25 -0
  103. package/dist/insights/errors.d.ts.map +1 -0
  104. package/dist/insights/errors.js +54 -0
  105. package/dist/insights/errors.js.map +1 -0
  106. package/dist/insights/forecast/budget.d.ts +2 -0
  107. package/dist/insights/forecast/budget.d.ts.map +1 -0
  108. package/dist/insights/forecast/budget.js +6 -0
  109. package/dist/insights/forecast/budget.js.map +1 -0
  110. package/dist/insights/forecast/capacity.d.ts +2 -0
  111. package/dist/insights/forecast/capacity.d.ts.map +1 -0
  112. package/dist/insights/forecast/capacity.js +3 -0
  113. package/dist/insights/forecast/capacity.js.map +1 -0
  114. package/dist/insights/forecast/forecast.d.ts +5 -0
  115. package/dist/insights/forecast/forecast.d.ts.map +1 -0
  116. package/dist/insights/forecast/forecast.js +103 -0
  117. package/dist/insights/forecast/forecast.js.map +1 -0
  118. package/dist/insights/forecast/retention.d.ts +2 -0
  119. package/dist/insights/forecast/retention.d.ts.map +1 -0
  120. package/dist/insights/forecast/retention.js +3 -0
  121. package/dist/insights/forecast/retention.js.map +1 -0
  122. package/dist/insights/index.d.ts +4 -0
  123. package/dist/insights/index.d.ts.map +1 -0
  124. package/dist/insights/index.js +23 -0
  125. package/dist/insights/index.js.map +1 -0
  126. package/dist/insights/insights-client.d.ts +33 -0
  127. package/dist/insights/insights-client.d.ts.map +1 -0
  128. package/dist/insights/insights-client.js +344 -0
  129. package/dist/insights/insights-client.js.map +1 -0
  130. package/dist/insights/llm-subpath.d.ts +4 -0
  131. package/dist/insights/llm-subpath.d.ts.map +1 -0
  132. package/dist/insights/llm-subpath.js +10 -0
  133. package/dist/insights/llm-subpath.js.map +1 -0
  134. package/dist/insights/optimization/cost-optimizer.d.ts +6 -0
  135. package/dist/insights/optimization/cost-optimizer.d.ts.map +1 -0
  136. package/dist/insights/optimization/cost-optimizer.js +98 -0
  137. package/dist/insights/optimization/cost-optimizer.js.map +1 -0
  138. package/dist/insights/optimization/latency-optimizer.d.ts +3 -0
  139. package/dist/insights/optimization/latency-optimizer.d.ts.map +1 -0
  140. package/dist/insights/optimization/latency-optimizer.js +3 -0
  141. package/dist/insights/optimization/latency-optimizer.js.map +1 -0
  142. package/dist/insights/optimization/threshold-advisor.d.ts +2 -0
  143. package/dist/insights/optimization/threshold-advisor.d.ts.map +1 -0
  144. package/dist/insights/optimization/threshold-advisor.js +3 -0
  145. package/dist/insights/optimization/threshold-advisor.js.map +1 -0
  146. package/dist/insights/optimization/token-optimizer.d.ts +4 -0
  147. package/dist/insights/optimization/token-optimizer.d.ts.map +1 -0
  148. package/dist/insights/optimization/token-optimizer.js +133 -0
  149. package/dist/insights/optimization/token-optimizer.js.map +1 -0
  150. package/dist/insights/ranking/contribution.d.ts +2 -0
  151. package/dist/insights/ranking/contribution.d.ts.map +1 -0
  152. package/dist/insights/ranking/contribution.js +6 -0
  153. package/dist/insights/ranking/contribution.js.map +1 -0
  154. package/dist/insights/ranking/helpers.d.ts +22 -0
  155. package/dist/insights/ranking/helpers.d.ts.map +1 -0
  156. package/dist/insights/ranking/helpers.js +88 -0
  157. package/dist/insights/ranking/helpers.js.map +1 -0
  158. package/dist/insights/ranking/pareto.d.ts +2 -0
  159. package/dist/insights/ranking/pareto.d.ts.map +1 -0
  160. package/dist/insights/ranking/pareto.js +6 -0
  161. package/dist/insights/ranking/pareto.js.map +1 -0
  162. package/dist/insights/ranking/slices.d.ts +2 -0
  163. package/dist/insights/ranking/slices.d.ts.map +1 -0
  164. package/dist/insights/ranking/slices.js +6 -0
  165. package/dist/insights/ranking/slices.js.map +1 -0
  166. package/dist/insights/ranking/top-bottom.d.ts +2 -0
  167. package/dist/insights/ranking/top-bottom.d.ts.map +1 -0
  168. package/dist/insights/ranking/top-bottom.js +7 -0
  169. package/dist/insights/ranking/top-bottom.js.map +1 -0
  170. package/dist/insights/recommendations/evidence.d.ts +2 -0
  171. package/dist/insights/recommendations/evidence.d.ts.map +1 -0
  172. package/dist/insights/recommendations/evidence.js +3 -0
  173. package/dist/insights/recommendations/evidence.js.map +1 -0
  174. package/dist/insights/recommendations/recommendation.d.ts +6 -0
  175. package/dist/insights/recommendations/recommendation.d.ts.map +1 -0
  176. package/dist/insights/recommendations/recommendation.js +25 -0
  177. package/dist/insights/recommendations/recommendation.js.map +1 -0
  178. package/dist/insights/recommendations/severity.d.ts +2 -0
  179. package/dist/insights/recommendations/severity.d.ts.map +1 -0
  180. package/dist/insights/recommendations/severity.js +3 -0
  181. package/dist/insights/recommendations/severity.js.map +1 -0
  182. package/dist/insights/rules/evaluate-rules.d.ts +5 -0
  183. package/dist/insights/rules/evaluate-rules.d.ts.map +1 -0
  184. package/dist/insights/rules/evaluate-rules.js +156 -0
  185. package/dist/insights/rules/evaluate-rules.js.map +1 -0
  186. package/dist/insights/types.d.ts +405 -0
  187. package/dist/insights/types.d.ts.map +1 -0
  188. package/dist/insights/types.js +3 -0
  189. package/dist/insights/types.js.map +1 -0
  190. package/dist/insights/utils/formatting.d.ts +4 -0
  191. package/dist/insights/utils/formatting.d.ts.map +1 -0
  192. package/dist/insights/utils/formatting.js +21 -0
  193. package/dist/insights/utils/formatting.js.map +1 -0
  194. package/dist/insights/utils/grouping.d.ts +2 -0
  195. package/dist/insights/utils/grouping.d.ts.map +1 -0
  196. package/dist/insights/utils/grouping.js +8 -0
  197. package/dist/insights/utils/grouping.js.map +1 -0
  198. package/dist/insights/utils/query-builder.d.ts +21 -0
  199. package/dist/insights/utils/query-builder.d.ts.map +1 -0
  200. package/dist/insights/utils/query-builder.js +107 -0
  201. package/dist/insights/utils/query-builder.js.map +1 -0
  202. package/dist/insights/utils/row-value.d.ts +5 -0
  203. package/dist/insights/utils/row-value.d.ts.map +1 -0
  204. package/dist/insights/utils/row-value.js +36 -0
  205. package/dist/insights/utils/row-value.js.map +1 -0
  206. package/dist/insights/utils/stats.d.ts +28 -0
  207. package/dist/insights/utils/stats.d.ts.map +1 -0
  208. package/dist/insights/utils/stats.js +125 -0
  209. package/dist/insights/utils/stats.js.map +1 -0
  210. package/dist/query/formatter.d.ts +2 -2
  211. package/dist/query/formatter.d.ts.map +1 -1
  212. package/dist/query/formatter.js +211 -30
  213. package/dist/query/formatter.js.map +1 -1
  214. package/dist/query/planner.d.ts +10 -2
  215. package/dist/query/planner.d.ts.map +1 -1
  216. package/dist/query/planner.js +55 -4
  217. package/dist/query/planner.js.map +1 -1
  218. package/dist/simulation/context.d.ts +5 -0
  219. package/dist/simulation/context.d.ts.map +1 -0
  220. package/dist/simulation/context.js +56 -0
  221. package/dist/simulation/context.js.map +1 -0
  222. package/dist/simulation/events.d.ts +3 -0
  223. package/dist/simulation/events.d.ts.map +1 -0
  224. package/dist/simulation/events.js +67 -0
  225. package/dist/simulation/events.js.map +1 -0
  226. package/dist/simulation/index.d.ts +7 -0
  227. package/dist/simulation/index.d.ts.map +1 -0
  228. package/dist/simulation/index.js +16 -0
  229. package/dist/simulation/index.js.map +1 -0
  230. package/dist/simulation/prng.d.ts +4 -0
  231. package/dist/simulation/prng.d.ts.map +1 -0
  232. package/dist/simulation/prng.js +18 -0
  233. package/dist/simulation/prng.js.map +1 -0
  234. package/dist/simulation/resource-estimate.d.ts +6 -0
  235. package/dist/simulation/resource-estimate.d.ts.map +1 -0
  236. package/dist/simulation/resource-estimate.js +11 -0
  237. package/dist/simulation/resource-estimate.js.map +1 -0
  238. package/dist/simulation/simulator.d.ts +15 -0
  239. package/dist/simulation/simulator.d.ts.map +1 -0
  240. package/dist/simulation/simulator.js +67 -0
  241. package/dist/simulation/simulator.js.map +1 -0
  242. package/dist/simulation/tracker.d.ts +8 -0
  243. package/dist/simulation/tracker.d.ts.map +1 -0
  244. package/dist/simulation/tracker.js +18 -0
  245. package/dist/simulation/tracker.js.map +1 -0
  246. package/dist/simulation/types.d.ts +49 -0
  247. package/dist/simulation/types.d.ts.map +1 -0
  248. package/dist/simulation/types.js +21 -0
  249. package/dist/simulation/types.js.map +1 -0
  250. package/dist/storage/memory.d.ts +3 -0
  251. package/dist/storage/memory.d.ts.map +1 -1
  252. package/dist/storage/memory.js +113 -4
  253. package/dist/storage/memory.js.map +1 -1
  254. package/dist/storage/mongo.d.ts +5 -0
  255. package/dist/storage/mongo.d.ts.map +1 -1
  256. package/dist/storage/mongo.js +129 -17
  257. package/dist/storage/mongo.js.map +1 -1
  258. package/dist/storage/redis.d.ts +12 -9
  259. package/dist/storage/redis.d.ts.map +1 -1
  260. package/dist/storage/redis.js +126 -47
  261. package/dist/storage/redis.js.map +1 -1
  262. package/dist/types/index.d.ts +139 -4
  263. package/dist/types/index.d.ts.map +1 -1
  264. package/docs/DEPLOYMENT.md +40 -2
  265. package/docs/INSIGHTS.md +59 -0
  266. package/docs/INSIGHTS_ANOMALY_DETECTION.md +33 -0
  267. package/docs/INSIGHTS_LLM_COST_AND_TOKENS.md +26 -0
  268. package/docs/INSIGHTS_RESOURCE_ADVISOR.md +31 -0
  269. package/docs/countex_gap_analysis_complete_checklist.md +1340 -0
  270. package/docs/guides/README.md +34 -0
  271. package/docs/guides/adapter-memory.md +48 -0
  272. package/docs/guides/adapter-mongo.md +62 -0
  273. package/docs/guides/adapter-redis.md +53 -0
  274. package/docs/guides/backup-export.md +83 -0
  275. package/docs/guides/cardinality.md +50 -0
  276. package/docs/guides/cli.md +53 -0
  277. package/docs/guides/client-events.md +49 -0
  278. package/docs/guides/counter-maps.md +122 -0
  279. package/docs/guides/idempotency.md +39 -0
  280. package/docs/guides/ingestion-and-flush.md +67 -0
  281. package/docs/guides/insights-advisors-and-optimization.md +39 -0
  282. package/docs/guides/insights-anomalies-and-rules.md +48 -0
  283. package/docs/guides/insights-comparison-and-trends.md +47 -0
  284. package/docs/guides/insights-forecasting-and-budget.md +61 -0
  285. package/docs/guides/insights-overview.md +82 -0
  286. package/docs/guides/insights-ranking.md +81 -0
  287. package/docs/guides/measures.md +71 -0
  288. package/docs/guides/querying.md +119 -0
  289. package/docs/guides/simulation-profiles.md +33 -0
  290. package/docs/guides/simulation-resource-estimation.md +30 -0
  291. package/docs/guides/simulation.md +36 -0
  292. package/docs/guides/timeframes-and-bucketing.md +55 -0
  293. package/docs/internals/README.md +21 -0
  294. package/docs/internals/internal-architecture-overview.md +65 -0
  295. package/docs/internals/internal-backup-stream.md +23 -0
  296. package/docs/internals/internal-buffer-merge-and-flush.md +51 -0
  297. package/docs/internals/internal-cardinality.md +30 -0
  298. package/docs/internals/internal-dimension-hash.md +34 -0
  299. package/docs/internals/internal-idempotency.md +36 -0
  300. package/docs/internals/internal-ingest-pipeline.md +52 -0
  301. package/docs/internals/internal-insights-layer.md +36 -0
  302. package/docs/internals/internal-mapping-validation-and-extraction.md +59 -0
  303. package/docs/internals/internal-measures-and-scales.md +35 -0
  304. package/docs/internals/internal-query-path.md +46 -0
  305. package/docs/internals/internal-storage-memory.md +13 -0
  306. package/docs/internals/internal-storage-mongo.md +24 -0
  307. package/docs/internals/internal-storage-redis.md +31 -0
  308. package/docs/internals/internal-timeframe-bucketing.md +33 -0
  309. package/docs/use-cases/README.md +56 -0
  310. package/docs/use-cases/audit-security-log-counts.md +550 -0
  311. package/docs/use-cases/llm-cost-and-token-metering.md +255 -0
  312. package/docs/use-cases/multi-tenant-isolation.md +203 -0
  313. package/docs/use-cases/ops-dashboard-daily-rollups.md +255 -0
  314. package/docs/use-cases/processing-workflow-activity.md +165 -0
  315. package/docs/use-cases/product-feature-usage.md +240 -0
  316. package/docs/use-cases/webhook-idempotent-ingestion.md +188 -0
  317. package/package.json +61 -2
package/README.md CHANGED
@@ -3,10 +3,14 @@
3
3
  > Generic sparse counter matrices for JSON events.
4
4
  > Dynamic counting, aggregation, and retrieval from mapped JSON inputs.
5
5
 
6
- `@x12i/countex` is a source-agnostic counting engine. You give it any JSON event, a declarative mapping config, and storage adapters; it projects events into sparse counter cells, batches deltas locally, and persists them atomically to a durable store (MongoDB) and a hot cache (Redis).
6
+ `@x12i/countex` is a **generic mapped-event counter**: a source-agnostic counting engine. You give it any JSON event, a declarative mapping config, and storage adapters; it projects events into sparse counter cells, batches deltas locally, and persists them atomically to a durable store (MongoDB) and a hot cache (Redis).
7
7
 
8
8
  It does **not** know about users, organizations, documents, labels, or events. It only knows generic primitives: **scope, subject, metric, dimensions, timeframe, delta**. Whatever your domain calls those things — Countex doesn't care.
9
9
 
10
+ **Terminology:** `metric` is the generic Countex name for the thing being counted or categorized. In your domain that may be a label, status, event name, operation, outcome, class, model result, or business category — the `metrics` array in a map simply lists JSON paths that resolve to those categories. Storage and APIs refer to dictionary **`sourceKey`** (the string extracted from the event); avoid confusing that with application-level UUIDs unless your map uses UUIDs as keys.
11
+
12
+ **Process memory vs retained state:** Each worker keeps **unflushed deltas** in an in-memory buffer. After flush, authoritative aggregates live in **durable** storage (MongoDB); **Redis** holds a hot cache. Restarting a worker loses only buffered deltas that were not flushed yet — tune flush intervals accordingly.
13
+
10
14
  ```
11
15
  event JSON ──► map ──► raw increments ──► buffer ──► flush ──► Mongo (durable)
12
16
  └───► Redis (hot cache)
@@ -34,6 +38,45 @@ These guides are included in the published tarball under `docs/` and exposed as
34
38
  |-------|-----------------|------|
35
39
  | Release & production deployment | `@x12i/countex/docs/deployment` | `docs/DEPLOYMENT.md` |
36
40
  | Tutorial — install → map → ingest → query | `@x12i/countex/docs/end-to-end-example` | `docs/END_TO_END_EXAMPLE.md` |
41
+ | Feature guides index | `@x12i/countex/docs/guides` | `docs/guides/README.md` |
42
+ | Counter maps | `@x12i/countex/docs/guides/counter-maps` | `docs/guides/counter-maps.md` |
43
+ | Ingestion & flush | `@x12i/countex/docs/guides/ingestion-and-flush` | `docs/guides/ingestion-and-flush.md` |
44
+ | Timeframes | `@x12i/countex/docs/guides/timeframes-and-bucketing` | `docs/guides/timeframes-and-bucketing.md` |
45
+ | Measures | `@x12i/countex/docs/guides/measures` | `docs/guides/measures.md` |
46
+ | Querying | `@x12i/countex/docs/guides/querying` | `docs/guides/querying.md` |
47
+ | Memory adapters | `@x12i/countex/docs/guides/adapter-memory` | `docs/guides/adapter-memory.md` |
48
+ | Mongo durable | `@x12i/countex/docs/guides/adapter-mongo` | `docs/guides/adapter-mongo.md` |
49
+ | Redis cache | `@x12i/countex/docs/guides/adapter-redis` | `docs/guides/adapter-redis.md` |
50
+ | Cardinality | `@x12i/countex/docs/guides/cardinality` | `docs/guides/cardinality.md` |
51
+ | Idempotency | `@x12i/countex/docs/guides/idempotency` | `docs/guides/idempotency.md` |
52
+ | Backup export | `@x12i/countex/docs/guides/backup-export` | `docs/guides/backup-export.md` |
53
+ | Client events | `@x12i/countex/docs/guides/client-events` | `docs/guides/client-events.md` |
54
+ | Insights overview | `@x12i/countex/docs/guides/insights-overview` | `docs/guides/insights-overview.md` |
55
+ | Insights ranking | `@x12i/countex/docs/guides/insights-ranking` | `docs/guides/insights-ranking.md` |
56
+ | Insights comparison & trends | `@x12i/countex/docs/guides/insights-comparison-and-trends` | `docs/guides/insights-comparison-and-trends.md` |
57
+ | Insights anomalies & rules | `@x12i/countex/docs/guides/insights-anomalies-and-rules` | `docs/guides/insights-anomalies-and-rules.md` |
58
+ | Insights forecasting & budget | `@x12i/countex/docs/guides/insights-forecasting-and-budget` | `docs/guides/insights-forecasting-and-budget.md` |
59
+ | Insights advisors | `@x12i/countex/docs/guides/insights-advisors-and-optimization` | `docs/guides/insights-advisors-and-optimization.md` |
60
+ | CLI | `@x12i/countex/docs/guides/cli` | `docs/guides/cli.md` |
61
+ | Simulation runtime (JS API) | `@x12i/countex/simulation` | `dist/simulation/` |
62
+ | Simulation overview | `@x12i/countex/docs/guides/simulation` | `docs/guides/simulation.md` |
63
+ | Simulation profiles | `@x12i/countex/docs/guides/simulation-profiles` | `docs/guides/simulation-profiles.md` |
64
+ | Simulation resource estimation | `@x12i/countex/docs/guides/simulation-resource-estimation` | `docs/guides/simulation-resource-estimation.md` |
65
+
66
+ **Use cases** (technical playbooks: contracts, fan-out math, exact `QuerySpec`s, production wiring, verification — see [`docs/use-cases/README.md`](docs/use-cases/README.md)):
67
+
68
+ | Topic | Package subpath | File |
69
+ |-------|-----------------|------|
70
+ | Use cases index | `@x12i/countex/docs/use-cases` | `docs/use-cases/README.md` |
71
+ | Audit & security logs (volume, situations, distinct entities, logical event totals) | `@x12i/countex/docs/use-cases/audit-security-log-counts` | `docs/use-cases/audit-security-log-counts.md` |
72
+ | Product & feature activity | `@x12i/countex/docs/use-cases/product-feature-usage` | `docs/use-cases/product-feature-usage.md` |
73
+ | LLM cost & token metering | `@x12i/countex/docs/use-cases/llm-cost-and-token-metering` | `docs/use-cases/llm-cost-and-token-metering.md` |
74
+ | Multi-tenant isolation | `@x12i/countex/docs/use-cases/multi-tenant-isolation` | `docs/use-cases/multi-tenant-isolation.md` |
75
+ | Idempotent webhooks & queues | `@x12i/countex/docs/use-cases/webhook-idempotent-ingestion` | `docs/use-cases/webhook-idempotent-ingestion.md` |
76
+ | Ops dashboards & rollups | `@x12i/countex/docs/use-cases/ops-dashboard-daily-rollups` | `docs/use-cases/ops-dashboard-daily-rollups.md` |
77
+ | Processing & workflow activity | `@x12i/countex/docs/use-cases/processing-workflow-activity` | `docs/use-cases/processing-workflow-activity.md` |
78
+
79
+ **Internals** (how the engine works — diagrams and traces) live under `docs/internals/` in the tarball; browse [`docs/internals/README.md`](docs/internals/README.md).
37
80
 
38
81
  After install: `node_modules/@x12i/countex/docs/`.
39
82
 
@@ -53,7 +96,7 @@ Each event can produce one or many cell increments. A counter increment is defin
53
96
 
54
97
  - **scope** — your tenant / org / account boundary
55
98
  - **counterId** — which counter family this is (e.g. `access_by_subject_metric`)
56
- - **timeframe** — `day` / `week` / `month` / `quarter` / `year` / `all`
99
+ - **timeframe** — `minute` / `hour` / `day` / `week` / `month` / `quarter` / `year` / `all`
57
100
  - **subject** — the thing being counted against (e.g. an actor or a target)
58
101
  - **metric** — the count category / label
59
102
  - **dimensions** — arbitrary additional breakdowns
@@ -61,6 +104,125 @@ Each event can produce one or many cell increments. A counter increment is defin
61
104
 
62
105
  Countex buffers increments locally, flushes atomic deltas to durable + cache, and serves queries from cache with durable fallback.
63
106
 
107
+ ### Measures and rates
108
+
109
+ Maps may declare optional **`measures`**: named numeric fields per event (cost, tokens, latency, …) with aggregations `sum`, `count`, `min`, and `max`. **`avg`** is computed at query time when both `sum` and `count` exist on the measure. Use **`scale`** on a measure for fixed-point storage (e.g. cents). Extracted values attach to each fan-out increment the same way as **`delta`** (see RFC-style docs for fan-out semantics).
110
+
111
+ Queries accept **`measures`** (explicit list or `"*"`), **`orderBy`** on a measure aggregation, and optional **`rate`** (count or a measure’s sum divided by elapsed time in the queried window; for `format: "timeseries"`, per bucket). **`rate`** is invalid for timeframe **`all`**.
112
+
113
+ **Redis cache** stores **sum** and **count** per measure only; **min** / **max** are durable-backed. If a query needs min/max (including `orderBy` on them, or requesting measures that maintain min/max when using `"*"`), the planner reads from **durable** first so cache cannot drift.
114
+
115
+ **`bucketRange`** caps at **10,000** buckets; at **`minute`** resolution that is about **6.94 days** — keep queries within that bound or narrow the range.
116
+
117
+ ---
118
+
119
+ ## What kinds of events Countex is for
120
+
121
+ Countex is not tied to one event source or domain. It is a **generic mapped-event counter**: any JSON-like input stream where useful aggregates can be produced from paths in the event.
122
+
123
+ Typical sources include:
124
+
125
+ | Source family | Examples | Common Countex projection |
126
+ |---|---|---|
127
+ | Audit and security logs | Microsoft 365 audit logs, Google Workspace logs, Okta logs, cloud audit logs | actor/resource/action/situation/severity |
128
+ | Product and user activity | Woopra, Segment, PostHog-style events, application activity logs | user/account/feature/event/page/funnel |
129
+ | Processing and workflow activity | ETL runs, background jobs, agent graphs, workflow engines, queue processors | job/task/node/status/error/runtime |
130
+ | LLM and AI service usage | Model gateway logs, OpenAI/Anthropic calls, internal LLM services | app/user/model/provider/tokens/cost/latency/result |
131
+ | Business/domain events | CRM, support tickets, payments, commerce, lifecycle events | customer/object/state/category/outcome |
132
+
133
+ Countex only needs a map. The map tells Countex where to find:
134
+
135
+ - the scope boundary
136
+ - the event time
137
+ - the subjects
138
+ - the metrics
139
+ - the dimensions
140
+ - the delta/count
141
+ - optional numeric measures such as cost, tokens, latency, or duration
142
+
143
+ The original event can come from a log, webhook, queue message, analytics event, system activity, processing trace, or generated test fixture. Countex does not care about the event source as long as the map can project it into generic counter primitives.
144
+
145
+ ### Audit-log style event
146
+
147
+ ```json
148
+ {
149
+ "tenant": { "id": "org_123" },
150
+ "event": {
151
+ "id": "audit_001",
152
+ "createdAt": "2026-05-08T14:33:00Z",
153
+ "operation": "FileAccessed",
154
+ "situation": "external"
155
+ },
156
+ "actor": { "id": "user_42", "type": "user" },
157
+ "resource": { "id": "file_99", "type": "document" },
158
+ "labels": ["PII", "Financial"]
159
+ }
160
+ ```
161
+
162
+ Counts:
163
+
164
+ ```text
165
+ actor/resource × label × operation/situation/resourceType × timeframe
166
+ ```
167
+
168
+ ### Product-activity style event
169
+
170
+ ```json
171
+ {
172
+ "account": { "id": "acct_123" },
173
+ "user": { "id": "user_42" },
174
+ "event": {
175
+ "name": "dashboard_viewed",
176
+ "createdAt": "2026-05-08T14:33:00Z"
177
+ },
178
+ "product": {
179
+ "feature": "risk_dashboard",
180
+ "plan": "enterprise"
181
+ }
182
+ }
183
+ ```
184
+
185
+ Counts:
186
+
187
+ ```text
188
+ user/account × activity metric × feature/plan × timeframe
189
+ ```
190
+
191
+ ### LLM-processing style event
192
+
193
+ ```json
194
+ {
195
+ "scope": { "id": "org_123" },
196
+ "request": {
197
+ "id": "llm_req_001",
198
+ "createdAt": "2026-05-08T14:33:00Z",
199
+ "status": "success"
200
+ },
201
+ "app": { "id": "graphs-studio" },
202
+ "model": {
203
+ "provider": "openai",
204
+ "name": "gpt-4.1"
205
+ },
206
+ "usage": {
207
+ "inputTokens": 1200,
208
+ "outputTokens": 350,
209
+ "costCents": 4,
210
+ "latencyMs": 1800
211
+ }
212
+ }
213
+ ```
214
+
215
+ Counts/measures:
216
+
217
+ ```text
218
+ app/model/provider/status × timeframe
219
+ sum inputTokens
220
+ sum outputTokens
221
+ sum costCents
222
+ avg latencyMs
223
+ count requests
224
+ ```
225
+
64
226
  ---
65
227
 
66
228
  ## Quick start
@@ -191,9 +353,10 @@ A `CounterMap` is the heart of the package. Everything Countex knows about your
191
353
  | `eventTime` | `{ path }` | Path to a Date / ISO string / epoch ms. Drives bucket selection. |
192
354
  | `subjects` | `SubjectMapping[]` | One or many. Each has `type` and `path`; multi-value paths fan out. |
193
355
  | `metrics` | `MetricMapping[]` | Same fanout semantics. `$.labels[*]` is common. |
356
+ | `measures` | `MeasureMapping[]` | Optional numeric fields per event (`sum` / `count` / `min` / `max`); see [Measures](./docs/guides/measures.md). |
194
357
  | `dimensions` | `DimensionMapping[]` | Named extra breakdowns. Optional by default. |
195
358
  | `delta` | `{ path?, default? }` | Numeric value at runtime. Default `1`. Negative deltas are fine. |
196
- | `timeframes` | `TimeframeType[]` | Subset of `day` / `week` / `month` / `quarter` / `year` / `all`. |
359
+ | `timeframes` | `TimeframeType[]` | Subset of `minute` / `hour` / `day` / `week` / `month` / `quarter` / `year` / `all`. |
197
360
  | `idempotency` | `IdempotencyPolicy` | Optional; needs a cache adapter that implements `markEventSeen`. |
198
361
  | `cardinality` | `CardinalityPolicy` | Optional; per-map override of engine-level defaults. |
199
362
  | `options` | `MappingOptions` | `skipMissingOptionalDimensions` (default true), `normalizeValues` (default true). |
@@ -351,11 +514,59 @@ Result:
351
514
  ```
352
515
 
353
516
  `groupBy` accepts:
354
- - `"subject"`, `"metric"`, `"timeframeKey"`
517
+ - `"subject"`, `"subjectType"`, `"metric"`, `"timeframeKey"`
355
518
  - `"dim:NAME"` — group by a dimension value
356
519
 
357
520
  ---
358
521
 
522
+ ## Insights and advisors
523
+
524
+ Countex can optionally analyze stored counters and measures to produce higher-level insights. The core engine answers “what happened?” by maintaining sparse aggregate cells. The insights layer answers “what matters?” by ranking, comparing periods, detecting anomalies, forecasting usage, and emitting evidence-backed recommendations.
525
+
526
+ Typical uses:
527
+
528
+ - Top / bottom N subjects, metrics, or dimensions; top/bottom percent of groups; Pareto and contribution views
529
+ - Period-over-period comparison and simple trends on timeseries
530
+ - Explainable anomaly detection (robust z-score, thresholds, missing activity)
531
+ - Rule evaluation with normalized recommendations
532
+ - Cost / budget / max-token style advisors (generic measures only — no domain lock-in)
533
+ - Map and cardinality health when you pass the counter map into `createCountexInsights`
534
+ - Resource projections from observed cells via `estimateResourcesFromActuals` (requires the durable adapter reference)
535
+
536
+ **Safety:** Insights honor `maxBuckets` (aligned with the core 10,000 bucket cap) and `maxGroups`. Grouped queries load all matching cells for the timeframe before aggregation, so narrow filters when possible.
537
+
538
+ **Sparse counters:** Bottom-N style rankings omit zero rows by default; Countex only stores cells that received increments.
539
+
540
+ ```ts
541
+ import { createCountexInsights } from "@x12i/countex/insights";
542
+
543
+ const insights = createCountexInsights({
544
+ countex,
545
+ durable, // optional; required for estimateResourcesFromActuals → streamCells
546
+ mapsByCounterId: new Map(maps.map((m) => [m.counterId, m])),
547
+ });
548
+
549
+ const topCostDrivers = await insights.topPercent({
550
+ scope: "org_123",
551
+ counterId: "llm_usage",
552
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
553
+ groupBy: ["subject"],
554
+ measure: "costMicros.sum",
555
+ percent: 20,
556
+ });
557
+ ```
558
+
559
+ Further reading: [docs/INSIGHTS.md](docs/INSIGHTS.md), [docs/INSIGHTS_ANOMALY_DETECTION.md](docs/INSIGHTS_ANOMALY_DETECTION.md), [docs/INSIGHTS_LLM_COST_AND_TOKENS.md](docs/INSIGHTS_LLM_COST_AND_TOKENS.md), [docs/INSIGHTS_RESOURCE_ADVISOR.md](docs/INSIGHTS_RESOURCE_ADVISOR.md).
560
+
561
+ CLI (after `npm run build` / install):
562
+
563
+ ```bash
564
+ npx countex insights:top ./path/to/insight-context.mjs --scope org_123 --counter my_counter
565
+ # TypeScript configs: node --import=tsx node_modules/@x12i/countex/dist/cli.js insights:pareto ./ctx.ts
566
+ ```
567
+
568
+ ---
569
+
359
570
  ## Events
360
571
 
361
572
  The Countex client is an `EventEmitter`. Subscribe to observe what's happening:
@@ -6,6 +6,8 @@
6
6
  *
7
7
  * Both are bounded by the (scope, counterId, timeframe) filter the caller
8
8
  * provides; we never iterate the entire collection.
9
+ *
10
+ * Streamed cells include optional `measures` when present on durable documents.
9
11
  */
10
12
  import type { CacheStorage, CounterCell, DurableStorage, QuerySpec } from "../types/index.js";
11
13
  export type ExportFilter = Pick<QuerySpec, "scope" | "counterId" | "timeframe">;
@@ -1 +1 @@
1
- {"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/backup/export.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC;AAEhF,wBAAgB,WAAW,CACzB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,WAAW,CAAC,CAE5B;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACzD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBlC"}
1
+ {"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/backup/export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC;AAEhF,wBAAgB,WAAW,CACzB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,WAAW,CAAC,CAE5B;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACzD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBlC"}
@@ -7,6 +7,8 @@
7
7
  *
8
8
  * Both are bounded by the (scope, counterId, timeframe) filter the caller
9
9
  * provides; we never iterate the entire collection.
10
+ *
11
+ * Streamed cells include optional `measures` when present on durable documents.
10
12
  */
11
13
  Object.defineProperty(exports, "__esModule", { value: true });
12
14
  exports.exportCells = exportCells;
@@ -1 +1 @@
1
- {"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/backup/export.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAWH,kCAMC;AAED,oCAyBC;AAjCD,SAAgB,WAAW,CACzB,OAAuB,EACvB,MAAoB,EACpB,MAAoB;IAEpB,OAAO,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC;AAEM,KAAK,UAAU,YAAY,CAChC,OAAuB,EACvB,KAAmB,EACnB,MAAoB,EACpB,UAAwD,EAAE;IAE1D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAkB,EAAE,CAAC;IAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAErE,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;QAC3D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC;YACvB,KAAK,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC"}
1
+ {"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/backup/export.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAWH,kCAMC;AAED,oCAyBC;AAjCD,SAAgB,WAAW,CACzB,OAAuB,EACvB,MAAoB,EACpB,MAAoB;IAEpB,OAAO,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC;AAEM,KAAK,UAAU,YAAY,CAChC,OAAuB,EACvB,KAAmB,EACnB,MAAoB,EACpB,UAAwD,EAAE;IAE1D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAkB,EAAE,CAAC;IAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAErE,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;QAC3D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC;YACvB,KAAK,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC"}
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Backup manifest, checksum verification, and snapshot restore orchestration.
3
+ */
4
+ import type { CounterCell, DurableStorage, QuerySpec } from "../types/index.js";
5
+ export declare const BACKUP_MANIFEST_VERSION: 1;
6
+ /** Logical schema marker for manifests; aligns with Mongo cell `schemaVersion` when using MongoDurable. */
7
+ export declare const COUNTEX_CELL_SCHEMA_VERSION = 1;
8
+ /** Document payload saved alongside an export (JSON). */
9
+ export interface BackupManifest {
10
+ manifestVersion: typeof BACKUP_MANIFEST_VERSION;
11
+ /** Engine cell schema marker (see Mongo `schemaVersion`). */
12
+ schemaVersion: number;
13
+ createdAtIso: string;
14
+ filter: Pick<QuerySpec, "scope" | "counterId" | "timeframe">;
15
+ cellCount: number;
16
+ /** SHA-256 of sorted canonical JSON lines (see `canonicalCellLine`). */
17
+ contentSha256: string;
18
+ }
19
+ export declare function canonicalCellLine(cell: CounterCell): string;
20
+ /**
21
+ * Stable fingerprint over an async cell stream (sorts canonical lines in memory).
22
+ * Suitable for bounded windows; for huge exports chunk by timeframe.
23
+ */
24
+ export declare function computeCellsFingerprint(cells: AsyncIterable<CounterCell>): Promise<{
25
+ cellCount: number;
26
+ contentSha256: string;
27
+ }>;
28
+ export declare function createBackupManifest(filter: Pick<QuerySpec, "scope" | "counterId" | "timeframe">, fp: {
29
+ cellCount: number;
30
+ contentSha256: string;
31
+ }, schemaVersion: number, createdAt?: Date): BackupManifest;
32
+ export declare function verifyBackupAgainstManifest(manifest: BackupManifest, cells: AsyncIterable<CounterCell>): Promise<{
33
+ ok: true;
34
+ } | {
35
+ ok: false;
36
+ detail: string;
37
+ }>;
38
+ /**
39
+ * Replace cells from an export stream. Requires adapter support (`importSnapshotCells`).
40
+ * `dryRun`: count cells only, no writes.
41
+ */
42
+ export declare function restoreSnapshotCells(durable: DurableStorage, cells: AsyncIterable<CounterCell>, options?: {
43
+ dryRun?: boolean;
44
+ batchSize?: number;
45
+ signal?: AbortSignal;
46
+ }): Promise<{
47
+ restored: number;
48
+ }>;
49
+ //# sourceMappingURL=manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/backup/manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGhF,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD,2GAA2G;AAC3G,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,OAAO,uBAAuB,CAAC;IAChD,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAc3D;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAYvD;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,EAC5D,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAChD,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,IAAiB,GAC3B,cAAc,CAShB;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAYvD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,EACjC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACvE,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B/B"}
@@ -0,0 +1,103 @@
1
+ "use strict";
2
+ /**
3
+ * Backup manifest, checksum verification, and snapshot restore orchestration.
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.COUNTEX_CELL_SCHEMA_VERSION = exports.BACKUP_MANIFEST_VERSION = void 0;
7
+ exports.canonicalCellLine = canonicalCellLine;
8
+ exports.computeCellsFingerprint = computeCellsFingerprint;
9
+ exports.createBackupManifest = createBackupManifest;
10
+ exports.verifyBackupAgainstManifest = verifyBackupAgainstManifest;
11
+ exports.restoreSnapshotCells = restoreSnapshotCells;
12
+ const node_crypto_1 = require("node:crypto");
13
+ const errors_js_1 = require("../utils/errors.js");
14
+ exports.BACKUP_MANIFEST_VERSION = 1;
15
+ /** Logical schema marker for manifests; aligns with Mongo cell `schemaVersion` when using MongoDurable. */
16
+ exports.COUNTEX_CELL_SCHEMA_VERSION = 1;
17
+ function canonicalCellLine(cell) {
18
+ return JSON.stringify({
19
+ scopeId: cell.scopeId,
20
+ counterId: cell.counterId,
21
+ timeframeType: cell.timeframeType,
22
+ timeframeKey: cell.timeframeKey,
23
+ subjectType: cell.subjectType,
24
+ subjectId: cell.subjectId,
25
+ metricId: cell.metricId,
26
+ dimensionsHash: cell.dimensionsHash,
27
+ dimensions: cell.dimensions,
28
+ count: cell.count,
29
+ measures: cell.measures,
30
+ });
31
+ }
32
+ /**
33
+ * Stable fingerprint over an async cell stream (sorts canonical lines in memory).
34
+ * Suitable for bounded windows; for huge exports chunk by timeframe.
35
+ */
36
+ async function computeCellsFingerprint(cells) {
37
+ const lines = [];
38
+ for await (const c of cells) {
39
+ lines.push(canonicalCellLine(c));
40
+ }
41
+ lines.sort();
42
+ const h = (0, node_crypto_1.createHash)("sha256");
43
+ for (const line of lines) {
44
+ h.update(line);
45
+ h.update("\n");
46
+ }
47
+ return { cellCount: lines.length, contentSha256: h.digest("hex") };
48
+ }
49
+ function createBackupManifest(filter, fp, schemaVersion, createdAt = new Date()) {
50
+ return {
51
+ manifestVersion: exports.BACKUP_MANIFEST_VERSION,
52
+ schemaVersion,
53
+ createdAtIso: createdAt.toISOString(),
54
+ filter,
55
+ cellCount: fp.cellCount,
56
+ contentSha256: fp.contentSha256,
57
+ };
58
+ }
59
+ async function verifyBackupAgainstManifest(manifest, cells) {
60
+ const fp = await computeCellsFingerprint(cells);
61
+ if (fp.cellCount !== manifest.cellCount) {
62
+ return {
63
+ ok: false,
64
+ detail: `cell count mismatch: stream has ${fp.cellCount}, manifest expects ${manifest.cellCount}`,
65
+ };
66
+ }
67
+ if (fp.contentSha256 !== manifest.contentSha256) {
68
+ return { ok: false, detail: "contentSha256 mismatch" };
69
+ }
70
+ return { ok: true };
71
+ }
72
+ /**
73
+ * Replace cells from an export stream. Requires adapter support (`importSnapshotCells`).
74
+ * `dryRun`: count cells only, no writes.
75
+ */
76
+ async function restoreSnapshotCells(durable, cells, options) {
77
+ if (!durable.importSnapshotCells) {
78
+ throw new errors_js_1.StorageError("Durable adapter does not implement importSnapshotCells", {});
79
+ }
80
+ const batchSize = options?.batchSize ?? 500;
81
+ let restored = 0;
82
+ let batch = [];
83
+ const flush = async () => {
84
+ if (batch.length === 0)
85
+ return;
86
+ if (!options?.dryRun) {
87
+ await durable.importSnapshotCells(batch, { signal: options?.signal });
88
+ }
89
+ restored += batch.length;
90
+ batch = [];
91
+ };
92
+ for await (const c of cells) {
93
+ if (options?.signal?.aborted) {
94
+ throw new errors_js_1.StorageError("restoreSnapshotCells aborted", {});
95
+ }
96
+ batch.push(c);
97
+ if (batch.length >= batchSize)
98
+ await flush();
99
+ }
100
+ await flush();
101
+ return { restored };
102
+ }
103
+ //# sourceMappingURL=manifest.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/backup/manifest.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Convert query/export-facing cells (presentation-valued measures) back into
3
+ * storage-layer cells (scaled integers) for snapshot import.
4
+ */
5
+ import type { CounterCell } from "../types/index.js";
6
+ /** Undo presentation rounding — use before writing Memory/Mongo storage state from exported cells. */
7
+ export declare function presentationToStorageCell(c: CounterCell): CounterCell;
8
+ //# sourceMappingURL=snapshot-encoding.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot-encoding.d.ts","sourceRoot":"","sources":["../../src/backup/snapshot-encoding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,mBAAmB,CAAC;AAYnE,sGAAsG;AACtG,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CAOrE"}
@@ -0,0 +1,27 @@
1
+ "use strict";
2
+ /**
3
+ * Convert query/export-facing cells (presentation-valued measures) back into
4
+ * storage-layer cells (scaled integers) for snapshot import.
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.presentationToStorageCell = presentationToStorageCell;
8
+ function scaleMeasureForStorage(mv) {
9
+ const scale = mv.scale !== undefined && mv.scale > 0 ? mv.scale : 1;
10
+ return {
11
+ ...mv,
12
+ sum: mv.sum !== undefined ? Math.trunc(mv.sum * scale) : undefined,
13
+ min: mv.min !== undefined ? Math.trunc(mv.min * scale) : undefined,
14
+ max: mv.max !== undefined ? Math.trunc(mv.max * scale) : undefined,
15
+ };
16
+ }
17
+ /** Undo presentation rounding — use before writing Memory/Mongo storage state from exported cells. */
18
+ function presentationToStorageCell(c) {
19
+ if (!c.measures)
20
+ return { ...c };
21
+ const measures = {};
22
+ for (const [name, mv] of Object.entries(c.measures)) {
23
+ measures[name] = scaleMeasureForStorage({ ...mv });
24
+ }
25
+ return { ...c, measures };
26
+ }
27
+ //# sourceMappingURL=snapshot-encoding.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot-encoding.js","sourceRoot":"","sources":["../../src/backup/snapshot-encoding.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAeH,8DAOC;AAlBD,SAAS,sBAAsB,CAAC,EAAgB;IAC9C,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO;QACL,GAAG,EAAE;QACL,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;QAClE,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;QAClE,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;KACnE,CAAC;AACJ,CAAC;AAED,sGAAsG;AACtG,SAAgB,yBAAyB,CAAC,CAAc;IACtD,IAAI,CAAC,CAAC,CAAC,QAAQ;QAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAyC,EAAE,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC"}
package/dist/cli.d.ts ADDED
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Minimal CLI for insights. Loads an ESM/CJS module that default-exports or exports `createContext`.
4
+ *
5
+ * Config module should export:
6
+ * `export async function createContext()` → `{ insights: CountexInsights }`
7
+ * or `export default { insights }`.
8
+ *
9
+ * For TypeScript configs run with: `node --import=tsx node_modules/@x12i/countex/dist/cli.js ...`
10
+ */
11
+ export {};
12
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}