@x12i/countex 1.0.0 → 1.2.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 (256) hide show
  1. package/README.md +192 -3
  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/cli.d.ts +12 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +190 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/core/buffer.d.ts +4 -3
  11. package/dist/core/buffer.d.ts.map +1 -1
  12. package/dist/core/buffer.js +65 -9
  13. package/dist/core/buffer.js.map +1 -1
  14. package/dist/core/countex.d.ts.map +1 -1
  15. package/dist/core/countex.js +30 -3
  16. package/dist/core/countex.js.map +1 -1
  17. package/dist/core/extraction.d.ts +14 -2
  18. package/dist/core/extraction.d.ts.map +1 -1
  19. package/dist/core/extraction.js +117 -1
  20. package/dist/core/extraction.js.map +1 -1
  21. package/dist/core/mapping.d.ts.map +1 -1
  22. package/dist/core/mapping.js +44 -1
  23. package/dist/core/mapping.js.map +1 -1
  24. package/dist/core/timeframe.d.ts +7 -0
  25. package/dist/core/timeframe.d.ts.map +1 -1
  26. package/dist/core/timeframe.js +88 -0
  27. package/dist/core/timeframe.js.map +1 -1
  28. package/dist/index.d.ts +1 -1
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/insights/advisors/fanout-health.d.ts +3 -0
  31. package/dist/insights/advisors/fanout-health.d.ts.map +1 -0
  32. package/dist/insights/advisors/fanout-health.js +3 -0
  33. package/dist/insights/advisors/fanout-health.js.map +1 -0
  34. package/dist/insights/advisors/map-health.d.ts +6 -0
  35. package/dist/insights/advisors/map-health.d.ts.map +1 -0
  36. package/dist/insights/advisors/map-health.js +154 -0
  37. package/dist/insights/advisors/map-health.js.map +1 -0
  38. package/dist/insights/advisors/resource-advisor.d.ts +4 -0
  39. package/dist/insights/advisors/resource-advisor.d.ts.map +1 -0
  40. package/dist/insights/advisors/resource-advisor.js +102 -0
  41. package/dist/insights/advisors/resource-advisor.js.map +1 -0
  42. package/dist/insights/advisors/retention-advisor.d.ts +2 -0
  43. package/dist/insights/advisors/retention-advisor.d.ts.map +1 -0
  44. package/dist/insights/advisors/retention-advisor.js +6 -0
  45. package/dist/insights/advisors/retention-advisor.js.map +1 -0
  46. package/dist/insights/advisors-subpath.d.ts +4 -0
  47. package/dist/insights/advisors-subpath.d.ts.map +1 -0
  48. package/dist/insights/advisors-subpath.js +10 -0
  49. package/dist/insights/advisors-subpath.js.map +1 -0
  50. package/dist/insights/anomaly/baseline.d.ts +4 -0
  51. package/dist/insights/anomaly/baseline.d.ts.map +1 -0
  52. package/dist/insights/anomaly/baseline.js +54 -0
  53. package/dist/insights/anomaly/baseline.js.map +1 -0
  54. package/dist/insights/anomaly/detect-anomalies.d.ts +6 -0
  55. package/dist/insights/anomaly/detect-anomalies.d.ts.map +1 -0
  56. package/dist/insights/anomaly/detect-anomalies.js +245 -0
  57. package/dist/insights/anomaly/detect-anomalies.js.map +1 -0
  58. package/dist/insights/anomaly/ewma.d.ts +2 -0
  59. package/dist/insights/anomaly/ewma.d.ts.map +1 -0
  60. package/dist/insights/anomaly/ewma.js +15 -0
  61. package/dist/insights/anomaly/ewma.js.map +1 -0
  62. package/dist/insights/anomaly/missing-activity.d.ts +3 -0
  63. package/dist/insights/anomaly/missing-activity.d.ts.map +1 -0
  64. package/dist/insights/anomaly/missing-activity.js +8 -0
  65. package/dist/insights/anomaly/missing-activity.js.map +1 -0
  66. package/dist/insights/anomaly/robust-zscore.d.ts +2 -0
  67. package/dist/insights/anomaly/robust-zscore.d.ts.map +1 -0
  68. package/dist/insights/anomaly/robust-zscore.js +9 -0
  69. package/dist/insights/anomaly/robust-zscore.js.map +1 -0
  70. package/dist/insights/anomaly-subpath.d.ts +7 -0
  71. package/dist/insights/anomaly-subpath.d.ts.map +1 -0
  72. package/dist/insights/anomaly-subpath.js +20 -0
  73. package/dist/insights/anomaly-subpath.js.map +1 -0
  74. package/dist/insights/comparison/compare-periods.d.ts +5 -0
  75. package/dist/insights/comparison/compare-periods.d.ts.map +1 -0
  76. package/dist/insights/comparison/compare-periods.js +64 -0
  77. package/dist/insights/comparison/compare-periods.js.map +1 -0
  78. package/dist/insights/comparison/growth-rate.d.ts +3 -0
  79. package/dist/insights/comparison/growth-rate.d.ts.map +1 -0
  80. package/dist/insights/comparison/growth-rate.js +3 -0
  81. package/dist/insights/comparison/growth-rate.js.map +1 -0
  82. package/dist/insights/comparison/moving-average.d.ts +2 -0
  83. package/dist/insights/comparison/moving-average.d.ts.map +1 -0
  84. package/dist/insights/comparison/moving-average.js +6 -0
  85. package/dist/insights/comparison/moving-average.js.map +1 -0
  86. package/dist/insights/comparison/trend.d.ts +5 -0
  87. package/dist/insights/comparison/trend.d.ts.map +1 -0
  88. package/dist/insights/comparison/trend.js +84 -0
  89. package/dist/insights/comparison/trend.js.map +1 -0
  90. package/dist/insights/errors.d.ts +25 -0
  91. package/dist/insights/errors.d.ts.map +1 -0
  92. package/dist/insights/errors.js +54 -0
  93. package/dist/insights/errors.js.map +1 -0
  94. package/dist/insights/forecast/budget.d.ts +2 -0
  95. package/dist/insights/forecast/budget.d.ts.map +1 -0
  96. package/dist/insights/forecast/budget.js +6 -0
  97. package/dist/insights/forecast/budget.js.map +1 -0
  98. package/dist/insights/forecast/capacity.d.ts +2 -0
  99. package/dist/insights/forecast/capacity.d.ts.map +1 -0
  100. package/dist/insights/forecast/capacity.js +3 -0
  101. package/dist/insights/forecast/capacity.js.map +1 -0
  102. package/dist/insights/forecast/forecast.d.ts +5 -0
  103. package/dist/insights/forecast/forecast.d.ts.map +1 -0
  104. package/dist/insights/forecast/forecast.js +103 -0
  105. package/dist/insights/forecast/forecast.js.map +1 -0
  106. package/dist/insights/forecast/retention.d.ts +2 -0
  107. package/dist/insights/forecast/retention.d.ts.map +1 -0
  108. package/dist/insights/forecast/retention.js +3 -0
  109. package/dist/insights/forecast/retention.js.map +1 -0
  110. package/dist/insights/index.d.ts +4 -0
  111. package/dist/insights/index.d.ts.map +1 -0
  112. package/dist/insights/index.js +23 -0
  113. package/dist/insights/index.js.map +1 -0
  114. package/dist/insights/insights-client.d.ts +33 -0
  115. package/dist/insights/insights-client.d.ts.map +1 -0
  116. package/dist/insights/insights-client.js +344 -0
  117. package/dist/insights/insights-client.js.map +1 -0
  118. package/dist/insights/llm-subpath.d.ts +4 -0
  119. package/dist/insights/llm-subpath.d.ts.map +1 -0
  120. package/dist/insights/llm-subpath.js +10 -0
  121. package/dist/insights/llm-subpath.js.map +1 -0
  122. package/dist/insights/optimization/cost-optimizer.d.ts +6 -0
  123. package/dist/insights/optimization/cost-optimizer.d.ts.map +1 -0
  124. package/dist/insights/optimization/cost-optimizer.js +98 -0
  125. package/dist/insights/optimization/cost-optimizer.js.map +1 -0
  126. package/dist/insights/optimization/latency-optimizer.d.ts +3 -0
  127. package/dist/insights/optimization/latency-optimizer.d.ts.map +1 -0
  128. package/dist/insights/optimization/latency-optimizer.js +3 -0
  129. package/dist/insights/optimization/latency-optimizer.js.map +1 -0
  130. package/dist/insights/optimization/threshold-advisor.d.ts +2 -0
  131. package/dist/insights/optimization/threshold-advisor.d.ts.map +1 -0
  132. package/dist/insights/optimization/threshold-advisor.js +3 -0
  133. package/dist/insights/optimization/threshold-advisor.js.map +1 -0
  134. package/dist/insights/optimization/token-optimizer.d.ts +4 -0
  135. package/dist/insights/optimization/token-optimizer.d.ts.map +1 -0
  136. package/dist/insights/optimization/token-optimizer.js +133 -0
  137. package/dist/insights/optimization/token-optimizer.js.map +1 -0
  138. package/dist/insights/ranking/contribution.d.ts +2 -0
  139. package/dist/insights/ranking/contribution.d.ts.map +1 -0
  140. package/dist/insights/ranking/contribution.js +6 -0
  141. package/dist/insights/ranking/contribution.js.map +1 -0
  142. package/dist/insights/ranking/helpers.d.ts +22 -0
  143. package/dist/insights/ranking/helpers.d.ts.map +1 -0
  144. package/dist/insights/ranking/helpers.js +88 -0
  145. package/dist/insights/ranking/helpers.js.map +1 -0
  146. package/dist/insights/ranking/pareto.d.ts +2 -0
  147. package/dist/insights/ranking/pareto.d.ts.map +1 -0
  148. package/dist/insights/ranking/pareto.js +6 -0
  149. package/dist/insights/ranking/pareto.js.map +1 -0
  150. package/dist/insights/ranking/slices.d.ts +2 -0
  151. package/dist/insights/ranking/slices.d.ts.map +1 -0
  152. package/dist/insights/ranking/slices.js +6 -0
  153. package/dist/insights/ranking/slices.js.map +1 -0
  154. package/dist/insights/ranking/top-bottom.d.ts +2 -0
  155. package/dist/insights/ranking/top-bottom.d.ts.map +1 -0
  156. package/dist/insights/ranking/top-bottom.js +7 -0
  157. package/dist/insights/ranking/top-bottom.js.map +1 -0
  158. package/dist/insights/recommendations/evidence.d.ts +2 -0
  159. package/dist/insights/recommendations/evidence.d.ts.map +1 -0
  160. package/dist/insights/recommendations/evidence.js +3 -0
  161. package/dist/insights/recommendations/evidence.js.map +1 -0
  162. package/dist/insights/recommendations/recommendation.d.ts +6 -0
  163. package/dist/insights/recommendations/recommendation.d.ts.map +1 -0
  164. package/dist/insights/recommendations/recommendation.js +25 -0
  165. package/dist/insights/recommendations/recommendation.js.map +1 -0
  166. package/dist/insights/recommendations/severity.d.ts +2 -0
  167. package/dist/insights/recommendations/severity.d.ts.map +1 -0
  168. package/dist/insights/recommendations/severity.js +3 -0
  169. package/dist/insights/recommendations/severity.js.map +1 -0
  170. package/dist/insights/rules/evaluate-rules.d.ts +5 -0
  171. package/dist/insights/rules/evaluate-rules.d.ts.map +1 -0
  172. package/dist/insights/rules/evaluate-rules.js +156 -0
  173. package/dist/insights/rules/evaluate-rules.js.map +1 -0
  174. package/dist/insights/types.d.ts +405 -0
  175. package/dist/insights/types.d.ts.map +1 -0
  176. package/dist/insights/types.js +3 -0
  177. package/dist/insights/types.js.map +1 -0
  178. package/dist/insights/utils/formatting.d.ts +4 -0
  179. package/dist/insights/utils/formatting.d.ts.map +1 -0
  180. package/dist/insights/utils/formatting.js +21 -0
  181. package/dist/insights/utils/formatting.js.map +1 -0
  182. package/dist/insights/utils/grouping.d.ts +2 -0
  183. package/dist/insights/utils/grouping.d.ts.map +1 -0
  184. package/dist/insights/utils/grouping.js +8 -0
  185. package/dist/insights/utils/grouping.js.map +1 -0
  186. package/dist/insights/utils/query-builder.d.ts +21 -0
  187. package/dist/insights/utils/query-builder.d.ts.map +1 -0
  188. package/dist/insights/utils/query-builder.js +107 -0
  189. package/dist/insights/utils/query-builder.js.map +1 -0
  190. package/dist/insights/utils/row-value.d.ts +5 -0
  191. package/dist/insights/utils/row-value.d.ts.map +1 -0
  192. package/dist/insights/utils/row-value.js +36 -0
  193. package/dist/insights/utils/row-value.js.map +1 -0
  194. package/dist/insights/utils/stats.d.ts +28 -0
  195. package/dist/insights/utils/stats.d.ts.map +1 -0
  196. package/dist/insights/utils/stats.js +125 -0
  197. package/dist/insights/utils/stats.js.map +1 -0
  198. package/dist/query/formatter.d.ts.map +1 -1
  199. package/dist/query/formatter.js +202 -24
  200. package/dist/query/formatter.js.map +1 -1
  201. package/dist/query/planner.d.ts +10 -2
  202. package/dist/query/planner.d.ts.map +1 -1
  203. package/dist/query/planner.js +39 -2
  204. package/dist/query/planner.js.map +1 -1
  205. package/dist/storage/memory.d.ts.map +1 -1
  206. package/dist/storage/memory.js +78 -4
  207. package/dist/storage/memory.js.map +1 -1
  208. package/dist/storage/mongo.d.ts.map +1 -1
  209. package/dist/storage/mongo.js +61 -16
  210. package/dist/storage/mongo.js.map +1 -1
  211. package/dist/storage/redis.d.ts +6 -7
  212. package/dist/storage/redis.d.ts.map +1 -1
  213. package/dist/storage/redis.js +108 -39
  214. package/dist/storage/redis.js.map +1 -1
  215. package/dist/types/index.d.ts +88 -4
  216. package/dist/types/index.d.ts.map +1 -1
  217. package/docs/INSIGHTS.md +59 -0
  218. package/docs/INSIGHTS_ANOMALY_DETECTION.md +33 -0
  219. package/docs/INSIGHTS_LLM_COST_AND_TOKENS.md +26 -0
  220. package/docs/INSIGHTS_RESOURCE_ADVISOR.md +31 -0
  221. package/docs/guides/README.md +29 -0
  222. package/docs/guides/adapter-memory.md +48 -0
  223. package/docs/guides/adapter-mongo.md +50 -0
  224. package/docs/guides/adapter-redis.md +47 -0
  225. package/docs/guides/backup-export.md +39 -0
  226. package/docs/guides/cardinality.md +50 -0
  227. package/docs/guides/cli.md +45 -0
  228. package/docs/guides/client-events.md +49 -0
  229. package/docs/guides/counter-maps.md +116 -0
  230. package/docs/guides/idempotency.md +39 -0
  231. package/docs/guides/ingestion-and-flush.md +67 -0
  232. package/docs/guides/insights-advisors-and-optimization.md +39 -0
  233. package/docs/guides/insights-anomalies-and-rules.md +48 -0
  234. package/docs/guides/insights-comparison-and-trends.md +47 -0
  235. package/docs/guides/insights-forecasting-and-budget.md +61 -0
  236. package/docs/guides/insights-overview.md +76 -0
  237. package/docs/guides/insights-ranking.md +81 -0
  238. package/docs/guides/measures.md +67 -0
  239. package/docs/guides/querying.md +79 -0
  240. package/docs/guides/timeframes-and-bucketing.md +55 -0
  241. package/docs/internals/README.md +20 -0
  242. package/docs/internals/internal-architecture-overview.md +65 -0
  243. package/docs/internals/internal-backup-stream.md +23 -0
  244. package/docs/internals/internal-buffer-merge-and-flush.md +51 -0
  245. package/docs/internals/internal-cardinality.md +30 -0
  246. package/docs/internals/internal-idempotency.md +36 -0
  247. package/docs/internals/internal-ingest-pipeline.md +52 -0
  248. package/docs/internals/internal-insights-layer.md +36 -0
  249. package/docs/internals/internal-mapping-validation-and-extraction.md +59 -0
  250. package/docs/internals/internal-measures-and-scales.md +35 -0
  251. package/docs/internals/internal-query-path.md +46 -0
  252. package/docs/internals/internal-storage-memory.md +13 -0
  253. package/docs/internals/internal-storage-mongo.md +24 -0
  254. package/docs/internals/internal-storage-redis.md +31 -0
  255. package/docs/internals/internal-timeframe-bucketing.md +33 -0
  256. package/package.json +45 -2
@@ -0,0 +1,45 @@
1
+ # Guide: CLI (`countex`)
2
+
3
+ The package exposes a minimal **`countex`** binary for running selected insights against a **config module** you provide.
4
+
5
+ ## Step 1: Build or install
6
+
7
+ After install, the binary resolves to `dist/cli.js`. For local development:
8
+
9
+ ```bash
10
+ npm run build
11
+ npx countex insights:top ./my-context.mjs --scope org_1 --counter my_counter
12
+ ```
13
+
14
+ ## Step 2: Author a config module
15
+
16
+ Export one of:
17
+
18
+ - `export async function createContext()` returning `{ insights: CountexInsights }`
19
+ - `export default { insights }`
20
+ - `export const insights`
21
+
22
+ ## Step 3: Run a command
23
+
24
+ ```bash
25
+ countex insights:top ./ctx.mjs --scope org_1 --counter usage
26
+ countex insights:pareto ./ctx.mjs --format markdown
27
+ countex insights:anomalies ./ctx.mjs
28
+ countex insights:cost ./ctx.mjs
29
+ countex insights:tokens ./ctx.mjs
30
+ countex insights:map-health ./ctx.mjs
31
+ countex insights:resources ./ctx.mjs
32
+ ```
33
+
34
+ Use `--format json|markdown` for output shaping.
35
+
36
+ ## Step 4: TypeScript configs
37
+
38
+ ```bash
39
+ node --import=tsx node_modules/@x12i/countex/dist/cli.js insights:top ./ctx.ts --scope org_1
40
+ ```
41
+
42
+ ## See also
43
+
44
+ - [Insights overview](./insights-overview.md)
45
+ - `src/cli.ts` for the authoritative command list
@@ -0,0 +1,49 @@
1
+ # Guide: Client events (`Countex`)
2
+
3
+ `Countex` extends `EventEmitter`. Subscribe for operational visibility.
4
+
5
+ ## Step 1: Subscribe
6
+
7
+ ```ts
8
+ countex.on("flush", ({ cells, durationMs }) => {
9
+ console.log("flushed", cells, durationMs);
10
+ });
11
+
12
+ countex.on("flush_error", ({ error }) => {
13
+ console.error(error);
14
+ });
15
+
16
+ countex.on("cardinality_warning", (w) => {
17
+ console.warn("cardinality_warning", w);
18
+ });
19
+
20
+ countex.on("overflow", (o) => {
21
+ console.warn("overflow", o);
22
+ });
23
+
24
+ countex.on("dropped", (d) => {
25
+ console.warn("dropped", d);
26
+ });
27
+
28
+ countex.on("duplicate", ({ scopeId, eventId }) => {
29
+ console.info("duplicate", scopeId, eventId);
30
+ });
31
+
32
+ countex.on("measure_invalid", (m) => {
33
+ console.warn("measure_invalid", m);
34
+ });
35
+ ```
36
+
37
+ ## Step 2: Type payloads
38
+
39
+ Import `CountexEvents` from types if you want compile-time checks when wiring handlers.
40
+
41
+ ## Step 3: Unsubscribe
42
+
43
+ Use `off` with the same listener reference when tearing down tests.
44
+
45
+ ## See also
46
+
47
+ - [Ingestion and flush](./ingestion-and-flush.md)
48
+ - [Cardinality](./cardinality.md)
49
+ - [Measures](./measures.md)
@@ -0,0 +1,116 @@
1
+ # Guide: Counter maps
2
+
3
+ A **counter map** (`CounterMap`) tells Countex how to read one JSON event and turn it into sparse counter updates. This guide walks through defining a map from scratch.
4
+
5
+ ## What you will configure
6
+
7
+ - **scope** — tenant or isolation boundary (string id).
8
+ - **eventTime** — when the event happened (drives timeframe buckets).
9
+ - **subjects** — one or more “things” the count attaches to (fan-out supported).
10
+ - **metrics** — labels or categories being counted (fan-out supported).
11
+ - **dimensions** — optional breakdown fields stored on each cell.
12
+ - **delta** — how much to add (default `1`).
13
+ - **timeframes** — which bucket granularities to write (`minute` … `all`).
14
+ - Optional: **measures**, **idempotency**, **cardinality**, **options**.
15
+
16
+ ## Step 1: Choose a stable `counterId`
17
+
18
+ Use a string that identifies this projection family across deployments, for example `access_by_actor_label`.
19
+
20
+ ## Step 2: Point at scope and time
21
+
22
+ ```ts
23
+ const map = {
24
+ counterId: "access_by_actor_label",
25
+ scope: { path: "$.tenant.id" },
26
+ eventTime: { path: "$.event.createdAt" },
27
+ // ...
28
+ } as const;
29
+ ```
30
+
31
+ Rules:
32
+
33
+ - Both paths must resolve to usable values or the event is skipped for this map.
34
+ - `eventTime` accepts `Date`, ISO strings, or epoch numbers.
35
+
36
+ ## Step 3: Declare subjects
37
+
38
+ Each subject has a `type` (your label) and a `path`. Multi-value paths fan out.
39
+
40
+ ```ts
41
+ subjects: [
42
+ { type: "actor", path: "$.actor.id", required: true },
43
+ { type: "resource", path: "$.resource.id", required: false },
44
+ ],
45
+ ```
46
+
47
+ - **`required: true`** — if nothing matches, the whole event is skipped.
48
+ - **`required: false`** — missing values omit that subject type for this event.
49
+
50
+ ## Step 4: Declare metrics
51
+
52
+ ```ts
53
+ metrics: [
54
+ { path: "$.labels[*]", required: true },
55
+ ],
56
+ ```
57
+
58
+ Wildcards (`[*]`) expand to one increment per array element (or object values).
59
+
60
+ ## Step 5: Add dimensions (optional)
61
+
62
+ ```ts
63
+ dimensions: [
64
+ { name: "operation", path: "$.event.operation" },
65
+ { name: "situation", path: "$.event.situation", required: false },
66
+ ],
67
+ ```
68
+
69
+ ## Step 6: Delta and timeframes
70
+
71
+ ```ts
72
+ delta: { default: 1 },
73
+ timeframes: ["day", "week", "month"],
74
+ ```
75
+
76
+ Use `delta: { path: "$.weight" }` when counts are not always `1`.
77
+
78
+ ## Step 7: Pass maps into `createCountex`
79
+
80
+ ```ts
81
+ import { createCountex } from "@x12i/countex";
82
+ import { MemoryDurable, MemoryCache } from "@x12i/countex/adapters/memory";
83
+
84
+ const countex = createCountex({
85
+ maps: [map],
86
+ durable: new MemoryDurable(),
87
+ cache: new MemoryCache(),
88
+ });
89
+ ```
90
+
91
+ Maps are validated at construction time; invalid paths or duplicate `counterId` values throw immediately.
92
+
93
+ ## Path syntax (subset)
94
+
95
+ | Syntax | Meaning |
96
+ |--------|---------|
97
+ | `$` | Root |
98
+ | `.name` | Property |
99
+ | `['name']` | Bracket property |
100
+ | `[N]` | Array index |
101
+ | `[*]` | Fan-out wildcard |
102
+
103
+ ## Fan-out math
104
+
105
+ Total raw increments per event ≈
106
+
107
+ `(subjects) × (metrics) × (number of timeframes)`.
108
+
109
+ Plan capacity accordingly.
110
+
111
+ ## See also
112
+
113
+ - [Timeframes](./timeframes-and-bucketing.md)
114
+ - [Measures](./measures.md)
115
+ - [Cardinality](./cardinality.md)
116
+ - Internal: [Mapping validation & extraction](../internals/internal-mapping-validation-and-extraction.md)
@@ -0,0 +1,39 @@
1
+ # Guide: Idempotency
2
+
3
+ Idempotency prevents **duplicate events** from incrementing counters twice when retries or at-least-once delivery replay the same logical event.
4
+
5
+ ## Step 1: Enable on the map
6
+
7
+ ```ts
8
+ const map = {
9
+ counterId: "orders",
10
+ // ...
11
+ idempotency: {
12
+ enabled: true,
13
+ eventIdPath: "$.event.id",
14
+ ttlSeconds: 86_400,
15
+ },
16
+ } as const;
17
+ ```
18
+
19
+ If `enabled` is true, `eventIdPath` is required (validated at startup).
20
+
21
+ ## Step 2: Use a cache adapter that supports dedupe
22
+
23
+ Implement **`markEventSeen(scopeId, eventId, ttlSeconds): Promise<boolean>`** on your cache adapter. The built-in **`RedisCache`** provides this using Redis keys with TTL.
24
+
25
+ Countex namespaces ids as **`${counterId}:${eventId}`** per map so different counters do not collide.
26
+
27
+ ## Step 3: Ingest normally
28
+
29
+ When `markEventSeen` returns **false** (already seen), increments for that map/event are dropped and a **`duplicate`** event is emitted.
30
+
31
+ ## Step 4: Handle missing event ids
32
+
33
+ If the path resolves empty while idempotency is enabled, Countex records a warning and still processes unless your extraction logic skips the event — verify your producer always sets ids.
34
+
35
+ ## See also
36
+
37
+ - [Redis adapter](./adapter-redis.md)
38
+ - [Client events](./client-events.md)
39
+ - Internal: [Idempotency](../internals/internal-idempotency.md)
@@ -0,0 +1,67 @@
1
+ # Guide: Ingestion and flush
2
+
3
+ Countex keeps **deltas in memory**, then **flushes** them to durable storage and optionally a cache. This guide covers the write path from your application’s perspective.
4
+
5
+ ## Step 1: Ingest events
6
+
7
+ ```ts
8
+ await countex.ingest({
9
+ tenant: { id: "org_1" },
10
+ event: { createdAt: "2026-05-08T12:00:00.000Z", operation: "read" },
11
+ actor: { id: "user_a" },
12
+ labels: ["docs"],
13
+ });
14
+ ```
15
+
16
+ `ingest` accepts `unknown`. Each configured map runs extraction independently.
17
+
18
+ Use **`ingestBatch(events)`** when you already have an array; dictionary lookups are batched across the batch.
19
+
20
+ ## Step 2: Understand buffering
21
+
22
+ After ingestion:
23
+
24
+ - Raw increments are merged into an in-memory **`DeltaBuffer`** keyed by cell identity.
25
+ - Nothing hits Mongo/Redis until flush (except dictionary resolution during ingest, which uses durable `resolveIds`).
26
+
27
+ ## Step 3: Flush explicitly or on schedule
28
+
29
+ ```ts
30
+ await countex.flush();
31
+ ```
32
+
33
+ Flush behavior is controlled by `flush` in config:
34
+
35
+ | Option | Role |
36
+ |--------|------|
37
+ | `everyMs` | Periodic background flush (0 disables timer) |
38
+ | `maxBufferedCells` | Threshold on distinct buffered cells |
39
+ | `maxBufferedEvents` | Threshold on ingested events since last drain |
40
+ | `flushOnShutdown` | Drain on `shutdown()` |
41
+ | `onOverflow` | `"block"` awaits flush at threshold; `"drop"` fires flush without blocking |
42
+
43
+ ## Step 4: Shutdown cleanly
44
+
45
+ ```ts
46
+ await countex.shutdown();
47
+ ```
48
+
49
+ Typically clears the timer, optionally flushes, then closes adapters.
50
+
51
+ ## Step 5: Initialize adapters in production
52
+
53
+ ```ts
54
+ await countex.init(); // calls durable.init?.() and cache.init?.()
55
+ ```
56
+
57
+ Call once after constructing clients.
58
+
59
+ ## Observability
60
+
61
+ Subscribe to `flush`, `flush_error`, `dropped`, and related events — see [Client events](./client-events.md).
62
+
63
+ ## See also
64
+
65
+ - [Counter maps](./counter-maps.md)
66
+ - [Adapter guides](./adapter-mongo.md)
67
+ - Internal: [Ingest pipeline](../internals/internal-ingest-pipeline.md), [Buffer & flush](../internals/internal-buffer-merge-and-flush.md)
@@ -0,0 +1,39 @@
1
+ # Guide: Insights — advisors and resource estimation
2
+
3
+ Advisors inspect **map shape**, **fan-out health**, and optionally **stream durable cells** to estimate capacity-style metrics.
4
+
5
+ ## Step 1: Map health
6
+
7
+ Requires `mapsByCounterId` passed to `createCountexInsights`.
8
+
9
+ ```ts
10
+ const health = await insights.analyzeMapHealth({
11
+ scope: "org_1",
12
+ counterId: "usage",
13
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
14
+ });
15
+ ```
16
+
17
+ ## Step 2: Resource estimation from actuals
18
+
19
+ Requires the **`durable`** reference in `createCountexInsights`.
20
+
21
+ ```ts
22
+ const resources = await insights.estimateResourcesFromActuals({
23
+ scope: "org_1",
24
+ counterId: "usage",
25
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
26
+ });
27
+ ```
28
+
29
+ This path uses `durable.streamCells` — ensure your adapter implements streaming efficiently.
30
+
31
+ ## Events
32
+
33
+ Recommendations attach to `recommendation` emissions with severity for downstream routing (pager, ticket, etc.).
34
+
35
+ ## See also
36
+
37
+ - `docs/INSIGHTS_RESOURCE_ADVISOR.md`
38
+ - [Insights overview](./insights-overview.md)
39
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -0,0 +1,48 @@
1
+ # Guide: Insights — anomalies and rules
2
+
3
+ Detect unusual periods relative to a baseline and evaluate declarative **rules** over stored aggregates.
4
+
5
+ ## Step 1: Detect anomalies
6
+
7
+ ```ts
8
+ const { anomalies } = await insights.detectAnomalies({
9
+ scope: "org_1",
10
+ counterId: "usage",
11
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
12
+ groupBy: [],
13
+ measure: "count",
14
+ baseline: {
15
+ timeframe: { type: "day", from: "2026-04-01", to: "2026-04-30" },
16
+ minBuckets: 12,
17
+ },
18
+ });
19
+ ```
20
+
21
+ Notes:
22
+
23
+ - **`timeframe.type: "all"`** is not supported; you’ll receive an empty list and an `insufficient_data` event.
24
+ - Emits **`anomaly`** events with severity for each finding.
25
+
26
+ ## Step 2: Evaluate rules
27
+
28
+ ```ts
29
+ const rules = await insights.evaluateRules({
30
+ scope: "org_1",
31
+ counterId: "usage",
32
+ timeframe: { type: "week", from: "2026-W18", to: "2026-W19" },
33
+ rules: [
34
+ {
35
+ id: "spike_cost",
36
+ when: { measure: "cost.sum", op: "gt", value: 10_000 },
37
+ recommend: { title: "Investigate cost spike" },
38
+ },
39
+ ],
40
+ });
41
+ ```
42
+
43
+ Rule evaluation reuses the insights query helper so timeouts and group caps stay consistent.
44
+
45
+ ## See also
46
+
47
+ - `docs/INSIGHTS_ANOMALY_DETECTION.md`
48
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -0,0 +1,47 @@
1
+ # Guide: Insights — comparison and trends
2
+
3
+ Compare two time windows or derive simple **trend** statistics from a timeseries query.
4
+
5
+ ## Step 1: Compare periods
6
+
7
+ ```ts
8
+ const cmp = await insights.comparePeriods({
9
+ scope: "org_1",
10
+ counterId: "usage",
11
+ current: { type: "day", from: "2026-05-08", to: "2026-05-08" },
12
+ previous: { type: "day", from: "2026-05-07", to: "2026-05-07" },
13
+ groupBy: ["metric"],
14
+ measure: "count",
15
+ minPercentChange: 10,
16
+ minAbsoluteChange: 5,
17
+ });
18
+ ```
19
+
20
+ The helper issues **two** queries (current and previous) and merges rows by group keys.
21
+
22
+ ## Step 2: Trend from timeseries
23
+
24
+ ```ts
25
+ const trend = await insights.trend({
26
+ scope: "org_1",
27
+ counterId: "usage",
28
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
29
+ groupBy: [],
30
+ measure: "cost.sum",
31
+ method: "linear",
32
+ movingAverageWindow: 3,
33
+ });
34
+ ```
35
+
36
+ Underlying query uses `format: "timeseries"`; post-processing computes growth / smoothing per configuration.
37
+
38
+ ## Options shared with other insights
39
+
40
+ - `filters` — subject/metric/dimension filters compatible with core queries
41
+ - `bypassCache`, `signal`
42
+ - `maxBuckets`, `maxGroups`
43
+
44
+ ## See also
45
+
46
+ - [Timeframes](./timeframes-and-bucketing.md)
47
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -0,0 +1,61 @@
1
+ # Guide: Insights — forecasting and budget
2
+
3
+ Forecast simple forward curves and relate measures to **budgets**, **cost drivers**, and **token ceilings**.
4
+
5
+ ## Step 1: Forecast
6
+
7
+ ```ts
8
+ const fc = await insights.forecast({
9
+ scope: "org_1",
10
+ counterId: "usage",
11
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
12
+ measure: "count",
13
+ horizonBuckets: 7,
14
+ });
15
+ ```
16
+
17
+ Recommendations may emit `recommendation` events on the insights client.
18
+
19
+ ## Step 2: Budget projection
20
+
21
+ ```ts
22
+ const budget = await insights.budgetProjection({
23
+ scope: "org_1",
24
+ counterId: "usage",
25
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
26
+ measure: "cost.sum",
27
+ budget: 50_000,
28
+ });
29
+ ```
30
+
31
+ ## Step 3: Cost drivers
32
+
33
+ ```ts
34
+ const drivers = await insights.costDrivers({
35
+ scope: "org_1",
36
+ counterId: "usage",
37
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
38
+ groupBy: ["subject", "dim:model"],
39
+ measure: "cost.sum",
40
+ });
41
+ ```
42
+
43
+ ## Step 4: Token recommendations
44
+
45
+ ```ts
46
+ const tokens = await insights.recommendMaxTokens({
47
+ scope: "org_1",
48
+ counterId: "usage",
49
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
50
+ groupBy: ["dim:model"],
51
+ outputTokenMeasure: "outputTokens",
52
+ safetyFactor: 1.2,
53
+ });
54
+ ```
55
+
56
+ Measure names must exist on your map / cells.
57
+
58
+ ## See also
59
+
60
+ - `docs/INSIGHTS_LLM_COST_AND_TOKENS.md`
61
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -0,0 +1,76 @@
1
+ # Guide: Insights overview
2
+
3
+ The **`@x12i/countex/insights`** module layers ranking, comparison, anomaly detection, forecasting, and advisory helpers on top of ordinary `countex.query` results.
4
+
5
+ ## Step 1: Install / import
6
+
7
+ ```ts
8
+ import { createCountexInsights } from "@x12i/countex/insights";
9
+ ```
10
+
11
+ No extra peer dependencies beyond what your core Countex setup already uses.
12
+
13
+ ## Step 2: Construct insights with your Countex client
14
+
15
+ ```ts
16
+ const insights = createCountexInsights({
17
+ countex,
18
+ durable, // optional; required only for estimateResourcesFromActuals
19
+ mapsByCounterId: new Map(maps.map((m) => [m.counterId, m])),
20
+ defaults: {
21
+ maxGroups: 10_000,
22
+ maxBuckets: 10_000,
23
+ queryTimeoutMs: 10_000,
24
+ minBaselineBuckets: 12,
25
+ resultLimit: 1_000,
26
+ },
27
+ });
28
+ ```
29
+
30
+ Passing **`mapsByCounterId`** enables map-aware advisors (for example map health).
31
+
32
+ ## Step 3: Run an insight
33
+
34
+ Each method ultimately builds a `QuerySpec`, calls `client.query`, then post-processes rows.
35
+
36
+ ```ts
37
+ const top = await insights.topN({
38
+ scope: "org_1",
39
+ counterId: "llm_usage",
40
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
41
+ groupBy: ["subject"],
42
+ measure: "cost.sum",
43
+ n: 10,
44
+ });
45
+ ```
46
+
47
+ ## Step 4: Observe insight lifecycle events
48
+
49
+ `CountexInsights` emits:
50
+
51
+ - `insight_query` — timing per underlying query
52
+ - `anomaly`, `recommendation`, `insufficient_data` — depending on method
53
+
54
+ ```ts
55
+ insights.on("insight_query", (e) => console.log(e));
56
+ ```
57
+
58
+ ## Step 5: Respect limits
59
+
60
+ Insights honor **`maxBuckets`** (aligned with core query expansion) and **`maxGroups`**. Prefer narrower filters when grouping heavily.
61
+
62
+ ## Feature map
63
+
64
+ | Area | Methods |
65
+ |------|---------|
66
+ | Ranking | `topN`, `bottomN`, `topPercent`, `bottomPercent`, `pareto`, `contribution` |
67
+ | Comparison | `comparePeriods`, `trend` |
68
+ | Anomalies & rules | `detectAnomalies`, `evaluateRules` |
69
+ | Forecast & budget | `forecast`, `budgetProjection`, `costDrivers`, `recommendMaxTokens` |
70
+ | Advisors | `analyzeMapHealth`, `estimateResourcesFromActuals` |
71
+
72
+ ## See also
73
+
74
+ - Domain-focused narratives: `docs/INSIGHTS.md`, `docs/INSIGHTS_ANOMALY_DETECTION.md`, etc.
75
+ - [Ranking](./insights-ranking.md)
76
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -0,0 +1,81 @@
1
+ # Guide: Insights — ranking
2
+
3
+ Ranking helpers turn grouped query rows into **top/bottom lists**, **percent slices**, **Pareto** views, and **contribution** summaries.
4
+
5
+ ## Prerequisites
6
+
7
+ - A `CountexInsights` instance — see [Insights overview](./insights-overview.md).
8
+ - A measure selector string such as `"count"` or `"cost.sum"`.
9
+
10
+ ## Step 1: Top N
11
+
12
+ ```ts
13
+ const out = await insights.topN({
14
+ scope: "org_1",
15
+ counterId: "usage",
16
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-07" },
17
+ groupBy: ["metric"],
18
+ measure: "count",
19
+ n: 10,
20
+ includeTotal: true,
21
+ });
22
+ ```
23
+
24
+ ## Step 2: Bottom N
25
+
26
+ ```ts
27
+ const out = await insights.bottomN({
28
+ scope: "org_1",
29
+ counterId: "usage",
30
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-07" },
31
+ groupBy: ["dim:region"],
32
+ measure: "latencyMs.avg",
33
+ n: 5,
34
+ includeZeroes: false,
35
+ });
36
+ ```
37
+
38
+ Sparse counters omit zero rows unless you opt in.
39
+
40
+ ## Step 3: Top / bottom percent slices
41
+
42
+ ```ts
43
+ const slice = await insights.topPercent({
44
+ scope: "org_1",
45
+ counterId: "usage",
46
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
47
+ groupBy: ["subject"],
48
+ measure: "cost.sum",
49
+ percent: 20,
50
+ });
51
+ ```
52
+
53
+ ## Step 4: Pareto
54
+
55
+ ```ts
56
+ const pareto = await insights.pareto({
57
+ scope: "org_1",
58
+ counterId: "usage",
59
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
60
+ groupBy: ["subject"],
61
+ measure: "cost.sum",
62
+ targetShare: 0.8,
63
+ });
64
+ ```
65
+
66
+ ## Step 5: Contribution
67
+
68
+ ```ts
69
+ const contrib = await insights.contribution({
70
+ scope: "org_1",
71
+ counterId: "usage",
72
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
73
+ groupBy: ["dim:model"],
74
+ measure: "tokens.sum",
75
+ });
76
+ ```
77
+
78
+ ## See also
79
+
80
+ - [Querying](./querying.md)
81
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)