@x12i/countex 1.8.5 → 1.10.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 (105) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +867 -860
  3. package/dist/cli.js +6 -6
  4. package/dist/core/countex.d.ts +61 -1
  5. package/dist/core/countex.d.ts.map +1 -1
  6. package/dist/core/countex.js +241 -0
  7. package/dist/core/countex.js.map +1 -1
  8. package/dist/core/managed.d.ts +200 -0
  9. package/dist/core/managed.d.ts.map +1 -0
  10. package/dist/core/managed.js +431 -0
  11. package/dist/core/managed.js.map +1 -0
  12. package/dist/core/timeframe.d.ts +5 -0
  13. package/dist/core/timeframe.d.ts.map +1 -1
  14. package/dist/core/timeframe.js +36 -0
  15. package/dist/core/timeframe.js.map +1 -1
  16. package/dist/index.d.ts +6 -2
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +9 -1
  19. package/dist/index.js.map +1 -1
  20. package/dist/insights/advisors/resource-advisor.d.ts.map +1 -1
  21. package/dist/insights/advisors/resource-advisor.js +5 -1
  22. package/dist/insights/advisors/resource-advisor.js.map +1 -1
  23. package/dist/insights/types.d.ts +4 -0
  24. package/dist/insights/types.d.ts.map +1 -1
  25. package/dist/storage/managed-memory.d.ts +33 -0
  26. package/dist/storage/managed-memory.d.ts.map +1 -0
  27. package/dist/storage/managed-memory.js +211 -0
  28. package/dist/storage/managed-memory.js.map +1 -0
  29. package/dist/storage/memory.d.ts +7 -4
  30. package/dist/storage/memory.d.ts.map +1 -1
  31. package/dist/storage/memory.js.map +1 -1
  32. package/dist/storage/postgres.d.ts +123 -0
  33. package/dist/storage/postgres.d.ts.map +1 -0
  34. package/dist/storage/postgres.js +1325 -0
  35. package/dist/storage/postgres.js.map +1 -0
  36. package/dist/storage/redis.d.ts +6 -0
  37. package/dist/storage/redis.d.ts.map +1 -1
  38. package/dist/storage/redis.js +21 -0
  39. package/dist/storage/redis.js.map +1 -1
  40. package/dist/types/index.d.ts +63 -5
  41. package/dist/types/index.d.ts.map +1 -1
  42. package/dist/utils/errors.d.ts +12 -0
  43. package/dist/utils/errors.d.ts.map +1 -1
  44. package/dist/utils/errors.js +22 -1
  45. package/dist/utils/errors.js.map +1 -1
  46. package/docs/DEPLOYMENT.md +399 -375
  47. package/docs/END_TO_END_EXAMPLE.md +316 -316
  48. package/docs/INSIGHTS.md +59 -59
  49. package/docs/INSIGHTS_ANOMALY_DETECTION.md +33 -33
  50. package/docs/INSIGHTS_LLM_COST_AND_TOKENS.md +26 -26
  51. package/docs/INSIGHTS_RESOURCE_ADVISOR.md +33 -31
  52. package/docs/countex_gap_analysis_complete_checklist.md +1340 -1340
  53. package/docs/guides/README.md +37 -34
  54. package/docs/guides/adapter-memory.md +60 -60
  55. package/docs/guides/adapter-mongo.md +64 -62
  56. package/docs/guides/adapter-postgres.md +92 -0
  57. package/docs/guides/adapter-redis.md +89 -89
  58. package/docs/guides/backup-export.md +135 -135
  59. package/docs/guides/cardinality.md +50 -50
  60. package/docs/guides/cli.md +53 -53
  61. package/docs/guides/client-events.md +65 -65
  62. package/docs/guides/counter-maps.md +160 -160
  63. package/docs/guides/idempotency.md +39 -39
  64. package/docs/guides/ingestion-and-flush.md +67 -67
  65. package/docs/guides/insights-advisors-and-optimization.md +39 -39
  66. package/docs/guides/insights-anomalies-and-rules.md +48 -48
  67. package/docs/guides/insights-comparison-and-trends.md +47 -47
  68. package/docs/guides/insights-forecasting-and-budget.md +61 -61
  69. package/docs/guides/insights-overview.md +82 -82
  70. package/docs/guides/insights-ranking.md +81 -81
  71. package/docs/guides/managed-commit.md +119 -0
  72. package/docs/guides/measures.md +72 -71
  73. package/docs/guides/migrating-mongo-to-postgres.md +127 -0
  74. package/docs/guides/preview.md +92 -92
  75. package/docs/guides/querying.md +178 -178
  76. package/docs/guides/simulation-profiles.md +33 -33
  77. package/docs/guides/simulation-resource-estimation.md +31 -30
  78. package/docs/guides/simulation.md +36 -36
  79. package/docs/guides/timeframes-and-bucketing.md +55 -55
  80. package/docs/internals/README.md +21 -21
  81. package/docs/internals/internal-architecture-overview.md +65 -65
  82. package/docs/internals/internal-backup-stream.md +23 -23
  83. package/docs/internals/internal-buffer-merge-and-flush.md +51 -51
  84. package/docs/internals/internal-cardinality.md +30 -30
  85. package/docs/internals/internal-dimension-hash.md +34 -34
  86. package/docs/internals/internal-idempotency.md +36 -36
  87. package/docs/internals/internal-ingest-pipeline.md +52 -52
  88. package/docs/internals/internal-insights-layer.md +36 -36
  89. package/docs/internals/internal-mapping-validation-and-extraction.md +59 -59
  90. package/docs/internals/internal-measures-and-scales.md +35 -35
  91. package/docs/internals/internal-query-path.md +46 -46
  92. package/docs/internals/internal-storage-memory.md +13 -13
  93. package/docs/internals/internal-storage-mongo.md +44 -44
  94. package/docs/internals/internal-storage-postgres.md +32 -0
  95. package/docs/internals/internal-storage-redis.md +63 -63
  96. package/docs/internals/internal-timeframe-bucketing.md +33 -33
  97. package/docs/use-cases/README.md +56 -56
  98. package/docs/use-cases/audit-security-log-counts.md +550 -550
  99. package/docs/use-cases/llm-cost-and-token-metering.md +255 -255
  100. package/docs/use-cases/multi-tenant-isolation.md +203 -203
  101. package/docs/use-cases/ops-dashboard-daily-rollups.md +255 -255
  102. package/docs/use-cases/processing-workflow-activity.md +165 -165
  103. package/docs/use-cases/product-feature-usage.md +240 -240
  104. package/docs/use-cases/webhook-idempotent-ingestion.md +188 -188
  105. package/package.json +190 -170
@@ -1,316 +1,316 @@
1
- # End-to-end example — access-style counters with `@x12i/countex`
2
-
3
- This tutorial walks through one complete use case: **counting labeled “access” activity per tenant**, broken down by **actor/target**, **labels**, **event type**, and **time**.
4
-
5
- You will:
6
-
7
- 1. Install the package (and optional adapters).
8
- 2. Declare a **counter map** that describes how JSON events become increments.
9
- 3. Run **in-memory** adapters (no external services).
10
- 4. **Ingest** events, **flush**, and **query** aggregated results.
11
- 5. See how the same map plugs into **MongoDB + Redis** in production.
12
-
13
- After `npm install @x12i/countex`, this file is available at `node_modules/@x12i/countex/docs/END_TO_END_EXAMPLE.md` (see **Stable paths** below).
14
-
15
- ---
16
-
17
- ## Domain scenario
18
-
19
- Imagine your product emits JSON events like:
20
-
21
- ```json
22
- {
23
- "tenant": { "id": "org_123" },
24
- "event": {
25
- "id": "evt_001",
26
- "type": "share",
27
- "situation": "external",
28
- "createdAt": "2026-05-08T14:33:00Z"
29
- },
30
- "actor": { "id": "user_42" },
31
- "target": { "id": "doc_99", "type": "document" },
32
- "labels": ["PCI", "PII"]
33
- }
34
- ```
35
-
36
- You want to answer:
37
-
38
- - How many **label hits** (`PCI`, `PII`, …) per **day**, per **actor** or **target**?
39
- - How does **event type** (`share` vs `download`) break down over time?
40
-
41
- Countex does not know “tenant” or “document” — only **scope**, **subjects**, **metrics**, **dimensions**, **timeframes**, and **delta**. You map your JSON into those primitives once.
42
-
43
- ---
44
-
45
- ## Step 1 — Install
46
-
47
- ```bash
48
- npm install @x12i/countex
49
- ```
50
-
51
- For the **production** section later:
52
-
53
- ```bash
54
- npm install mongodb ioredis
55
- ```
56
-
57
- ---
58
-
59
- ## Step 2 — Define the counter map
60
-
61
- A **`CounterMap`** tells Countex how to read each field from an event:
62
-
63
- | Map field | Meaning in this example |
64
- |-----------|-------------------------|
65
- | `counterId` | Logical name for this matrix (e.g. `access_by_subject_metric`). |
66
- | `scope` | Tenant boundary — JSONPath to `$.tenant.id`. |
67
- | `eventTime` | Bucketing time — `$.event.createdAt` (ISO string or `Date`). |
68
- | `subjects` | Two extractors: **actor** (`$.actor.id`) required, **target** (`$.target.id`) optional. Each produces separate cells. |
69
- | `metrics` | Fan-out over **labels** — `$.labels[*]` (each label is one metric value). |
70
- | `dimensions` | Breakdown fields: event type, situation, target type. |
71
- | `delta` | How much to add (default `1`, or a path like `$.change`). |
72
- | `timeframes` | Which buckets to maintain (`day`, `week`, …). |
73
-
74
- Example map (TypeScript):
75
-
76
- ```ts
77
- import type { CounterMap } from "@x12i/countex";
78
-
79
- export const accessMap: CounterMap = {
80
- counterId: "access_by_subject_metric",
81
-
82
- scope: { path: "$.tenant.id" },
83
- eventTime: { path: "$.event.createdAt" },
84
-
85
- subjects: [
86
- { type: "actor", path: "$.actor.id", required: true },
87
- { type: "target", path: "$.target.id", required: false },
88
- ],
89
-
90
- metrics: [{ path: "$.labels[*]", required: true }],
91
-
92
- dimensions: [
93
- { name: "eventType", path: "$.event.type" },
94
- { name: "situation", path: "$.event.situation" },
95
- { name: "targetType", path: "$.target.type" },
96
- ],
97
-
98
- delta: { default: 1 },
99
- timeframes: ["day", "week", "month", "quarter", "year"],
100
- };
101
- ```
102
-
103
- **Cardinality:** each distinct actor id, label string, and dimension value participates in dictionary or dimension hashing. For high-cardinality streams, configure **`cardinality`** on `createCountex` (see README).
104
-
105
- ---
106
-
107
- ## Step 3 — Full in-memory program
108
-
109
- No Mongo or Redis — ideal for tests and local demos.
110
-
111
- ```ts
112
- import { createCountex } from "@x12i/countex";
113
- import { MemoryDurable, MemoryCache } from "@x12i/countex/adapters/memory";
114
- import type { CounterMap } from "@x12i/countex";
115
-
116
- const accessMap: CounterMap = {
117
- counterId: "access_by_subject_metric",
118
- scope: { path: "$.tenant.id" },
119
- eventTime: { path: "$.event.createdAt" },
120
- subjects: [
121
- { type: "actor", path: "$.actor.id", required: true },
122
- { type: "target", path: "$.target.id", required: false },
123
- ],
124
- metrics: [{ path: "$.labels[*]", required: true }],
125
- dimensions: [
126
- { name: "eventType", path: "$.event.type" },
127
- { name: "situation", path: "$.event.situation" },
128
- { name: "targetType", path: "$.target.type" },
129
- ],
130
- delta: { default: 1 },
131
- timeframes: ["day", "week", "month"],
132
- };
133
-
134
- async function main() {
135
- const countex = createCountex({
136
- maps: [accessMap],
137
- durable: new MemoryDurable(),
138
- cache: new MemoryCache(),
139
- flush: { everyMs: 0 }, // manual flush for clarity
140
- });
141
-
142
- await countex.ingest({
143
- tenant: { id: "org_123" },
144
- event: {
145
- type: "share",
146
- situation: "external",
147
- createdAt: "2026-05-08T14:33:00Z",
148
- },
149
- actor: { id: "user_42" },
150
- target: { id: "doc_99", type: "document" },
151
- labels: ["PCI", "PII"],
152
- });
153
-
154
- await countex.flush();
155
-
156
- const table = await countex.query({
157
- scope: "org_123",
158
- counterId: "access_by_subject_metric",
159
- timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
160
- groupBy: ["metric"],
161
- format: "table",
162
- orderBy: "-count",
163
- });
164
-
165
- console.log(table.rows);
166
- await countex.shutdown();
167
- }
168
-
169
- main();
170
- ```
171
-
172
- ---
173
-
174
- ## Step 4 — What happened?
175
-
176
- For that single event:
177
-
178
- - **Subjects:** actor + target ⇒ **2** subject lines (if target present).
179
- - **Metrics:** two labels ⇒ **2** metrics.
180
- - **Timeframes:** `day`, `week`, `month` ⇒ **3** buckets per combination.
181
-
182
- So you get **2 × 2 × 3 = 12** buffered cell deltas from one ingest (before merging duplicate cells). Exact merged cell count depends on shared identities.
183
-
184
- After **`flush`**, those cells exist in **`MemoryDurable`** and are mirrored to **`MemoryCache`** for reads.
185
-
186
- ---
187
-
188
- ## Step 5 — Queries you can run
189
-
190
- **Table — top metrics for one day:**
191
-
192
- ```ts
193
- await countex.query({
194
- scope: "org_123",
195
- counterId: "access_by_subject_metric",
196
- timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
197
- groupBy: ["metric"],
198
- format: "table",
199
- orderBy: "-count",
200
- limit: 50,
201
- });
202
- ```
203
-
204
- **Timeseries — counts by day and event type:**
205
-
206
- ```ts
207
- await countex.query({
208
- scope: "org_123",
209
- counterId: "access_by_subject_metric",
210
- timeframe: { type: "day", from: "2026-05-01", to: "2026-05-08" },
211
- groupBy: ["dim:eventType"],
212
- format: "timeseries",
213
- });
214
- ```
215
-
216
- **Pivot dimensions** using `groupBy: ["subject", "metric", "dim:eventType"]` etc. See README for full query options.
217
-
218
- ---
219
-
220
- ## Step 6 — Production shape (Mongo + Redis)
221
-
222
- Swap adapters only; the **same map** stays.
223
-
224
- Conceptually:
225
-
226
- ```ts
227
- import { MongoClient } from "mongodb";
228
- import IORedis from "ioredis";
229
- import { createCountex } from "@x12i/countex";
230
- import { MongoDurable } from "@x12i/countex/adapters/mongo";
231
- import { RedisCache } from "@x12i/countex/adapters/redis";
232
-
233
- const mongo = new MongoClient(process.env.MONGO_URI!);
234
- await mongo.connect();
235
- const redis = new IORedis(process.env.REDIS_URL!);
236
-
237
- const countex = createCountex({
238
- maps: [accessMap],
239
- durable: new MongoDurable({
240
- client: mongo,
241
- dbResolver: ({ scope }) => `countex_${scope}`,
242
- }),
243
- cache: new RedisCache({
244
- client: redis,
245
- keyPrefix: "countex",
246
- ttlSeconds: 92 * 24 * 3600,
247
- }),
248
- flush: {
249
- everyMs: 60_000,
250
- maxBufferedCells: 100_000,
251
- maxBufferedEvents: 50_000,
252
- flushOnShutdown: true,
253
- },
254
- });
255
-
256
- await countex.init();
257
- // … ingest from your queue / API …
258
- ```
259
-
260
- Operational checklist (indexes, URIs, shutdown) is in **`DEPLOYMENT.md`**.
261
-
262
- ---
263
-
264
- ## Step 7 — Idempotency (optional)
265
-
266
- To skip duplicate **logical events**, enable **`idempotency`** on the map and ensure **`RedisCache`** implements **`markEventSeen`**:
267
-
268
- ```ts
269
- const accessMapWithDedupe: CounterMap = {
270
- ...accessMap,
271
- idempotency: {
272
- enabled: true,
273
- eventIdPath: "$.event.id",
274
- ttlSeconds: 86_400,
275
- },
276
- };
277
- ```
278
-
279
- Second ingest with the same `event.id` for that scope produces **no new increments** (and emits a **`duplicate`** event).
280
-
281
- ---
282
-
283
- ## Runnable scripts in the Git repository
284
-
285
- The npm tarball includes **`dist/`**, **`README.md`**, **`LICENSE`**, and **`docs/`** — not the repo’s **`examples/`** folder. To run the maintained scripts that mirror this tutorial:
286
-
287
- 1. Clone **https://github.com/x12i/countex**.
288
- 2. **`npm install`**
289
- 3. **`npx tsx examples/basic.ts`** — in-memory path.
290
- 4. **`MONGO_URI=... REDIS_URL=... npx tsx examples/access-counter.ts`** — Mongo + Redis path.
291
-
292
- ---
293
-
294
- ## Stable paths inside the published package
295
-
296
- | Document | Subpath (package exports) | File on disk |
297
- |----------|---------------------------|--------------|
298
- | Deployment guide | `@x12i/countex/docs/deployment` | `docs/DEPLOYMENT.md` |
299
- | This tutorial | `@x12i/countex/docs/end-to-end-example` | `docs/END_TO_END_EXAMPLE.md` |
300
-
301
- Resolve from Node if needed:
302
-
303
- ```js
304
- import { createRequire } from "node:module";
305
- import path from "node:path";
306
- const require = createRequire(import.meta.url);
307
- const root = path.dirname(require.resolve("@x12i/countex/package.json"));
308
- // path.join(root, "docs", "END_TO_END_EXAMPLE.md")
309
- ```
310
-
311
- ---
312
-
313
- ## Related
314
-
315
- - **`DEPLOYMENT.md`** — npm release and production deployment steps.
316
- - **README** — API reference, mental model, and additional examples.
1
+ # End-to-end example — access-style counters with `@x12i/countex`
2
+
3
+ This tutorial walks through one complete use case: **counting labeled “access” activity per tenant**, broken down by **actor/target**, **labels**, **event type**, and **time**.
4
+
5
+ You will:
6
+
7
+ 1. Install the package (and optional adapters).
8
+ 2. Declare a **counter map** that describes how JSON events become increments.
9
+ 3. Run **in-memory** adapters (no external services).
10
+ 4. **Ingest** events, **flush**, and **query** aggregated results.
11
+ 5. See how the same map plugs into **MongoDB + Redis** in production.
12
+
13
+ After `npm install @x12i/countex`, this file is available at `node_modules/@x12i/countex/docs/END_TO_END_EXAMPLE.md` (see **Stable paths** below).
14
+
15
+ ---
16
+
17
+ ## Domain scenario
18
+
19
+ Imagine your product emits JSON events like:
20
+
21
+ ```json
22
+ {
23
+ "tenant": { "id": "org_123" },
24
+ "event": {
25
+ "id": "evt_001",
26
+ "type": "share",
27
+ "situation": "external",
28
+ "createdAt": "2026-05-08T14:33:00Z"
29
+ },
30
+ "actor": { "id": "user_42" },
31
+ "target": { "id": "doc_99", "type": "document" },
32
+ "labels": ["PCI", "PII"]
33
+ }
34
+ ```
35
+
36
+ You want to answer:
37
+
38
+ - How many **label hits** (`PCI`, `PII`, …) per **day**, per **actor** or **target**?
39
+ - How does **event type** (`share` vs `download`) break down over time?
40
+
41
+ Countex does not know “tenant” or “document” — only **scope**, **subjects**, **metrics**, **dimensions**, **timeframes**, and **delta**. You map your JSON into those primitives once.
42
+
43
+ ---
44
+
45
+ ## Step 1 — Install
46
+
47
+ ```bash
48
+ npm install @x12i/countex
49
+ ```
50
+
51
+ For the **production** section later:
52
+
53
+ ```bash
54
+ npm install mongodb ioredis
55
+ ```
56
+
57
+ ---
58
+
59
+ ## Step 2 — Define the counter map
60
+
61
+ A **`CounterMap`** tells Countex how to read each field from an event:
62
+
63
+ | Map field | Meaning in this example |
64
+ |-----------|-------------------------|
65
+ | `counterId` | Logical name for this matrix (e.g. `access_by_subject_metric`). |
66
+ | `scope` | Tenant boundary — JSONPath to `$.tenant.id`. |
67
+ | `eventTime` | Bucketing time — `$.event.createdAt` (ISO string or `Date`). |
68
+ | `subjects` | Two extractors: **actor** (`$.actor.id`) required, **target** (`$.target.id`) optional. Each produces separate cells. |
69
+ | `metrics` | Fan-out over **labels** — `$.labels[*]` (each label is one metric value). |
70
+ | `dimensions` | Breakdown fields: event type, situation, target type. |
71
+ | `delta` | How much to add (default `1`, or a path like `$.change`). |
72
+ | `timeframes` | Which buckets to maintain (`day`, `week`, …). |
73
+
74
+ Example map (TypeScript):
75
+
76
+ ```ts
77
+ import type { CounterMap } from "@x12i/countex";
78
+
79
+ export const accessMap: CounterMap = {
80
+ counterId: "access_by_subject_metric",
81
+
82
+ scope: { path: "$.tenant.id" },
83
+ eventTime: { path: "$.event.createdAt" },
84
+
85
+ subjects: [
86
+ { type: "actor", path: "$.actor.id", required: true },
87
+ { type: "target", path: "$.target.id", required: false },
88
+ ],
89
+
90
+ metrics: [{ path: "$.labels[*]", required: true }],
91
+
92
+ dimensions: [
93
+ { name: "eventType", path: "$.event.type" },
94
+ { name: "situation", path: "$.event.situation" },
95
+ { name: "targetType", path: "$.target.type" },
96
+ ],
97
+
98
+ delta: { default: 1 },
99
+ timeframes: ["day", "week", "month", "quarter", "year"],
100
+ };
101
+ ```
102
+
103
+ **Cardinality:** each distinct actor id, label string, and dimension value participates in dictionary or dimension hashing. For high-cardinality streams, configure **`cardinality`** on `createCountex` (see README).
104
+
105
+ ---
106
+
107
+ ## Step 3 — Full in-memory program
108
+
109
+ No Mongo or Redis — ideal for tests and local demos.
110
+
111
+ ```ts
112
+ import { createCountex } from "@x12i/countex";
113
+ import { MemoryDurable, MemoryCache } from "@x12i/countex/adapters/memory";
114
+ import type { CounterMap } from "@x12i/countex";
115
+
116
+ const accessMap: CounterMap = {
117
+ counterId: "access_by_subject_metric",
118
+ scope: { path: "$.tenant.id" },
119
+ eventTime: { path: "$.event.createdAt" },
120
+ subjects: [
121
+ { type: "actor", path: "$.actor.id", required: true },
122
+ { type: "target", path: "$.target.id", required: false },
123
+ ],
124
+ metrics: [{ path: "$.labels[*]", required: true }],
125
+ dimensions: [
126
+ { name: "eventType", path: "$.event.type" },
127
+ { name: "situation", path: "$.event.situation" },
128
+ { name: "targetType", path: "$.target.type" },
129
+ ],
130
+ delta: { default: 1 },
131
+ timeframes: ["day", "week", "month"],
132
+ };
133
+
134
+ async function main() {
135
+ const countex = createCountex({
136
+ maps: [accessMap],
137
+ durable: new MemoryDurable(),
138
+ cache: new MemoryCache(),
139
+ flush: { everyMs: 0 }, // manual flush for clarity
140
+ });
141
+
142
+ await countex.ingest({
143
+ tenant: { id: "org_123" },
144
+ event: {
145
+ type: "share",
146
+ situation: "external",
147
+ createdAt: "2026-05-08T14:33:00Z",
148
+ },
149
+ actor: { id: "user_42" },
150
+ target: { id: "doc_99", type: "document" },
151
+ labels: ["PCI", "PII"],
152
+ });
153
+
154
+ await countex.flush();
155
+
156
+ const table = await countex.query({
157
+ scope: "org_123",
158
+ counterId: "access_by_subject_metric",
159
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
160
+ groupBy: ["metric"],
161
+ format: "table",
162
+ orderBy: "-count",
163
+ });
164
+
165
+ console.log(table.rows);
166
+ await countex.shutdown();
167
+ }
168
+
169
+ main();
170
+ ```
171
+
172
+ ---
173
+
174
+ ## Step 4 — What happened?
175
+
176
+ For that single event:
177
+
178
+ - **Subjects:** actor + target ⇒ **2** subject lines (if target present).
179
+ - **Metrics:** two labels ⇒ **2** metrics.
180
+ - **Timeframes:** `day`, `week`, `month` ⇒ **3** buckets per combination.
181
+
182
+ So you get **2 × 2 × 3 = 12** buffered cell deltas from one ingest (before merging duplicate cells). Exact merged cell count depends on shared identities.
183
+
184
+ After **`flush`**, those cells exist in **`MemoryDurable`** and are mirrored to **`MemoryCache`** for reads.
185
+
186
+ ---
187
+
188
+ ## Step 5 — Queries you can run
189
+
190
+ **Table — top metrics for one day:**
191
+
192
+ ```ts
193
+ await countex.query({
194
+ scope: "org_123",
195
+ counterId: "access_by_subject_metric",
196
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
197
+ groupBy: ["metric"],
198
+ format: "table",
199
+ orderBy: "-count",
200
+ limit: 50,
201
+ });
202
+ ```
203
+
204
+ **Timeseries — counts by day and event type:**
205
+
206
+ ```ts
207
+ await countex.query({
208
+ scope: "org_123",
209
+ counterId: "access_by_subject_metric",
210
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-08" },
211
+ groupBy: ["dim:eventType"],
212
+ format: "timeseries",
213
+ });
214
+ ```
215
+
216
+ **Pivot dimensions** using `groupBy: ["subject", "metric", "dim:eventType"]` etc. See README for full query options.
217
+
218
+ ---
219
+
220
+ ## Step 6 — Production shape (Mongo + Redis)
221
+
222
+ Swap adapters only; the **same map** stays.
223
+
224
+ Conceptually:
225
+
226
+ ```ts
227
+ import { MongoClient } from "mongodb";
228
+ import IORedis from "ioredis";
229
+ import { createCountex } from "@x12i/countex";
230
+ import { MongoDurable } from "@x12i/countex/adapters/mongo";
231
+ import { RedisCache } from "@x12i/countex/adapters/redis";
232
+
233
+ const mongo = new MongoClient(process.env.MONGO_URI!);
234
+ await mongo.connect();
235
+ const redis = new IORedis(process.env.REDIS_URL!);
236
+
237
+ const countex = createCountex({
238
+ maps: [accessMap],
239
+ durable: new MongoDurable({
240
+ client: mongo,
241
+ dbResolver: ({ scope }) => `countex_${scope}`,
242
+ }),
243
+ cache: new RedisCache({
244
+ client: redis,
245
+ keyPrefix: "countex",
246
+ ttlSeconds: 92 * 24 * 3600,
247
+ }),
248
+ flush: {
249
+ everyMs: 60_000,
250
+ maxBufferedCells: 100_000,
251
+ maxBufferedEvents: 50_000,
252
+ flushOnShutdown: true,
253
+ },
254
+ });
255
+
256
+ await countex.init();
257
+ // … ingest from your queue / API …
258
+ ```
259
+
260
+ Operational checklist (indexes, URIs, shutdown) is in **`DEPLOYMENT.md`**.
261
+
262
+ ---
263
+
264
+ ## Step 7 — Idempotency (optional)
265
+
266
+ To skip duplicate **logical events**, enable **`idempotency`** on the map and ensure **`RedisCache`** implements **`markEventSeen`**:
267
+
268
+ ```ts
269
+ const accessMapWithDedupe: CounterMap = {
270
+ ...accessMap,
271
+ idempotency: {
272
+ enabled: true,
273
+ eventIdPath: "$.event.id",
274
+ ttlSeconds: 86_400,
275
+ },
276
+ };
277
+ ```
278
+
279
+ Second ingest with the same `event.id` for that scope produces **no new increments** (and emits a **`duplicate`** event).
280
+
281
+ ---
282
+
283
+ ## Runnable scripts in the Git repository
284
+
285
+ The npm tarball includes **`dist/`**, **`README.md`**, **`LICENSE`**, and **`docs/`** — not the repo’s **`examples/`** folder. To run the maintained scripts that mirror this tutorial:
286
+
287
+ 1. Clone **https://github.com/x12i/countex**.
288
+ 2. **`npm install`**
289
+ 3. **`npx tsx examples/basic.ts`** — in-memory path.
290
+ 4. **`MONGO_URI=... REDIS_URL=... npx tsx examples/access-counter.ts`** — Mongo + Redis path.
291
+
292
+ ---
293
+
294
+ ## Stable paths inside the published package
295
+
296
+ | Document | Subpath (package exports) | File on disk |
297
+ |----------|---------------------------|--------------|
298
+ | Deployment guide | `@x12i/countex/docs/deployment` | `docs/DEPLOYMENT.md` |
299
+ | This tutorial | `@x12i/countex/docs/end-to-end-example` | `docs/END_TO_END_EXAMPLE.md` |
300
+
301
+ Resolve from Node if needed:
302
+
303
+ ```js
304
+ import { createRequire } from "node:module";
305
+ import path from "node:path";
306
+ const require = createRequire(import.meta.url);
307
+ const root = path.dirname(require.resolve("@x12i/countex/package.json"));
308
+ // path.join(root, "docs", "END_TO_END_EXAMPLE.md")
309
+ ```
310
+
311
+ ---
312
+
313
+ ## Related
314
+
315
+ - **`DEPLOYMENT.md`** — npm release and production deployment steps.
316
+ - **README** — API reference, mental model, and additional examples.