@x12i/countex 1.0.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 (81) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +520 -0
  3. package/dist/backup/export.d.ts +19 -0
  4. package/dist/backup/export.d.ts.map +1 -0
  5. package/dist/backup/export.js +36 -0
  6. package/dist/backup/export.js.map +1 -0
  7. package/dist/core/buffer.d.ts +27 -0
  8. package/dist/core/buffer.d.ts.map +1 -0
  9. package/dist/core/buffer.js +63 -0
  10. package/dist/core/buffer.js.map +1 -0
  11. package/dist/core/cardinality.d.ts +43 -0
  12. package/dist/core/cardinality.d.ts.map +1 -0
  13. package/dist/core/cardinality.js +93 -0
  14. package/dist/core/cardinality.js.map +1 -0
  15. package/dist/core/countex.d.ts +49 -0
  16. package/dist/core/countex.d.ts.map +1 -0
  17. package/dist/core/countex.js +331 -0
  18. package/dist/core/countex.js.map +1 -0
  19. package/dist/core/extraction.d.ts +39 -0
  20. package/dist/core/extraction.d.ts.map +1 -0
  21. package/dist/core/extraction.js +176 -0
  22. package/dist/core/extraction.js.map +1 -0
  23. package/dist/core/mapping.d.ts +8 -0
  24. package/dist/core/mapping.d.ts.map +1 -0
  25. package/dist/core/mapping.js +90 -0
  26. package/dist/core/mapping.js.map +1 -0
  27. package/dist/core/normalization.d.ts +15 -0
  28. package/dist/core/normalization.d.ts.map +1 -0
  29. package/dist/core/normalization.js +43 -0
  30. package/dist/core/normalization.js.map +1 -0
  31. package/dist/core/timeframe.d.ts +30 -0
  32. package/dist/core/timeframe.d.ts.map +1 -0
  33. package/dist/core/timeframe.js +151 -0
  34. package/dist/core/timeframe.js.map +1 -0
  35. package/dist/index.d.ts +17 -0
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +28 -0
  38. package/dist/index.js.map +1 -0
  39. package/dist/query/formatter.d.ts +9 -0
  40. package/dist/query/formatter.d.ts.map +1 -0
  41. package/dist/query/formatter.js +119 -0
  42. package/dist/query/formatter.js.map +1 -0
  43. package/dist/query/planner.d.ts +14 -0
  44. package/dist/query/planner.d.ts.map +1 -0
  45. package/dist/query/planner.js +32 -0
  46. package/dist/query/planner.js.map +1 -0
  47. package/dist/storage/memory.d.ts +36 -0
  48. package/dist/storage/memory.d.ts.map +1 -0
  49. package/dist/storage/memory.js +150 -0
  50. package/dist/storage/memory.js.map +1 -0
  51. package/dist/storage/mongo.d.ts +56 -0
  52. package/dist/storage/mongo.d.ts.map +1 -0
  53. package/dist/storage/mongo.js +323 -0
  54. package/dist/storage/mongo.js.map +1 -0
  55. package/dist/storage/redis.d.ts +44 -0
  56. package/dist/storage/redis.d.ts.map +1 -0
  57. package/dist/storage/redis.js +193 -0
  58. package/dist/storage/redis.js.map +1 -0
  59. package/dist/types/index.d.ts +317 -0
  60. package/dist/types/index.d.ts.map +1 -0
  61. package/dist/types/index.js +9 -0
  62. package/dist/types/index.js.map +1 -0
  63. package/dist/utils/errors.d.ts +20 -0
  64. package/dist/utils/errors.d.ts.map +1 -0
  65. package/dist/utils/errors.js +44 -0
  66. package/dist/utils/errors.js.map +1 -0
  67. package/dist/utils/hash.d.ts +30 -0
  68. package/dist/utils/hash.d.ts.map +1 -0
  69. package/dist/utils/hash.js +61 -0
  70. package/dist/utils/hash.js.map +1 -0
  71. package/dist/utils/jsonpath.d.ts +40 -0
  72. package/dist/utils/jsonpath.d.ts.map +1 -0
  73. package/dist/utils/jsonpath.js +162 -0
  74. package/dist/utils/jsonpath.js.map +1 -0
  75. package/dist/utils/logger.d.ts +7 -0
  76. package/dist/utils/logger.d.ts.map +1 -0
  77. package/dist/utils/logger.js +24 -0
  78. package/dist/utils/logger.js.map +1 -0
  79. package/docs/DEPLOYMENT.md +244 -0
  80. package/docs/END_TO_END_EXAMPLE.md +316 -0
  81. package/package.json +91 -0
@@ -0,0 +1,162 @@
1
+ "use strict";
2
+ /**
3
+ * Minimal JSONPath subset.
4
+ *
5
+ * Supported syntax:
6
+ * $ root
7
+ * .name property
8
+ * ['name'] / ["name"] property (bracket form, allows arbitrary chars)
9
+ * [N] array index (N integer)
10
+ * [*] wildcard — fanout: returns all elements/values
11
+ *
12
+ * Path evaluation always returns an array of values.
13
+ * - Wildcards or fanout from arrays of arrays produce multiple values.
14
+ * - Missing paths return [].
15
+ * - For a single-value extraction, callers take result[0].
16
+ *
17
+ * Examples:
18
+ * "$.tenant.id" → [tenantId] or []
19
+ * "$.labels[*]" → ["PCI", "PII", "Financial"] or []
20
+ * "$.actor.id" → [actorId] or []
21
+ * "$['actor.with.dots']" → [...]
22
+ */
23
+ Object.defineProperty(exports, "__esModule", { value: true });
24
+ exports.parsePath = parsePath;
25
+ exports.evaluate = evaluate;
26
+ exports.extract = extract;
27
+ const errors_js_1 = require("./errors.js");
28
+ const cache = new Map();
29
+ function parsePath(expr) {
30
+ const cached = cache.get(expr);
31
+ if (cached)
32
+ return cached;
33
+ if (typeof expr !== "string" || expr.length === 0) {
34
+ throw new errors_js_1.ExtractionError("Path must be a non-empty string", { expr });
35
+ }
36
+ if (expr[0] !== "$") {
37
+ throw new errors_js_1.ExtractionError("Path must start with '$'", { expr });
38
+ }
39
+ const segs = [];
40
+ let i = 1;
41
+ while (i < expr.length) {
42
+ const ch = expr[i];
43
+ if (ch === ".") {
44
+ i++;
45
+ // Read property name up to next '.', '[', or end
46
+ const start = i;
47
+ while (i < expr.length && expr[i] !== "." && expr[i] !== "[")
48
+ i++;
49
+ if (i === start) {
50
+ throw new errors_js_1.ExtractionError("Empty property after '.'", { expr });
51
+ }
52
+ segs.push({ type: "prop", name: expr.slice(start, i) });
53
+ continue;
54
+ }
55
+ if (ch === "[") {
56
+ i++;
57
+ if (i >= expr.length)
58
+ throw new errors_js_1.ExtractionError("Unterminated '['", { expr });
59
+ // Wildcard
60
+ if (expr[i] === "*") {
61
+ i++;
62
+ if (expr[i] !== "]")
63
+ throw new errors_js_1.ExtractionError("Expected ']' after '*'", { expr });
64
+ i++;
65
+ segs.push({ type: "wildcard" });
66
+ continue;
67
+ }
68
+ // Quoted property
69
+ if (expr[i] === "'" || expr[i] === '"') {
70
+ const quote = expr[i];
71
+ i++;
72
+ const start = i;
73
+ while (i < expr.length && expr[i] !== quote) {
74
+ // Allow simple escaping
75
+ if (expr[i] === "\\" && i + 1 < expr.length)
76
+ i += 2;
77
+ else
78
+ i++;
79
+ }
80
+ if (expr[i] !== quote) {
81
+ throw new errors_js_1.ExtractionError("Unterminated quoted property", { expr });
82
+ }
83
+ const raw = expr.slice(start, i);
84
+ const name = raw.replace(/\\(.)/g, "$1");
85
+ i++;
86
+ if (expr[i] !== "]")
87
+ throw new errors_js_1.ExtractionError("Expected ']' after quoted property", { expr });
88
+ i++;
89
+ segs.push({ type: "prop", name });
90
+ continue;
91
+ }
92
+ // Numeric index
93
+ const start = i;
94
+ while (i < expr.length && expr[i] !== "]")
95
+ i++;
96
+ if (expr[i] !== "]")
97
+ throw new errors_js_1.ExtractionError("Unterminated '['", { expr });
98
+ const inner = expr.slice(start, i);
99
+ i++;
100
+ const n = Number(inner);
101
+ if (!Number.isInteger(n)) {
102
+ throw new errors_js_1.ExtractionError("Only integer indexes or '*' supported in [...]", {
103
+ expr,
104
+ inner,
105
+ });
106
+ }
107
+ segs.push({ type: "index", index: n });
108
+ continue;
109
+ }
110
+ throw new errors_js_1.ExtractionError(`Unexpected character '${ch}' in path`, { expr, position: i });
111
+ }
112
+ cache.set(expr, segs);
113
+ return segs;
114
+ }
115
+ /**
116
+ * Evaluate a parsed path against a JSON value. Always returns an array.
117
+ * Short-circuits to [] when an intermediate access fails.
118
+ */
119
+ function evaluate(segments, root) {
120
+ let frontier = [root];
121
+ for (const seg of segments) {
122
+ const next = [];
123
+ for (const v of frontier) {
124
+ if (v === null || v === undefined)
125
+ continue;
126
+ if (seg.type === "prop") {
127
+ if (typeof v === "object" && !Array.isArray(v)) {
128
+ const val = v[seg.name];
129
+ if (val !== undefined)
130
+ next.push(val);
131
+ }
132
+ // Property access on an array yields nothing in this subset.
133
+ continue;
134
+ }
135
+ if (seg.type === "index") {
136
+ if (Array.isArray(v)) {
137
+ const idx = seg.index < 0 ? v.length + seg.index : seg.index;
138
+ if (idx >= 0 && idx < v.length)
139
+ next.push(v[idx]);
140
+ }
141
+ continue;
142
+ }
143
+ // wildcard
144
+ if (Array.isArray(v)) {
145
+ for (const elem of v)
146
+ next.push(elem);
147
+ }
148
+ else if (typeof v === "object") {
149
+ for (const key of Object.keys(v)) {
150
+ next.push(v[key]);
151
+ }
152
+ }
153
+ }
154
+ frontier = next;
155
+ }
156
+ return frontier;
157
+ }
158
+ /** Convenience: parse + evaluate. */
159
+ function extract(expr, root) {
160
+ return evaluate(parsePath(expr), root);
161
+ }
162
+ //# sourceMappingURL=jsonpath.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"jsonpath.js","sourceRoot":"","sources":["../../src/utils/jsonpath.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,7 @@
1
+ import type { CountexLogger } from "../types/index.js";
2
+ /**
3
+ * Default no-op logger. We never log unless the user opts in by passing one.
4
+ */
5
+ export declare const noopLogger: Required<CountexLogger>;
6
+ export declare function resolveLogger(logger?: CountexLogger): Required<CountexLogger>;
7
+ //# sourceMappingURL=logger.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,aAAa,CAK9C,CAAC;AAEF,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC,aAAa,CAAC,CAQ7E"}
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.noopLogger = void 0;
4
+ exports.resolveLogger = resolveLogger;
5
+ /**
6
+ * Default no-op logger. We never log unless the user opts in by passing one.
7
+ */
8
+ exports.noopLogger = {
9
+ debug: () => { },
10
+ info: () => { },
11
+ warn: () => { },
12
+ error: () => { },
13
+ };
14
+ function resolveLogger(logger) {
15
+ if (!logger)
16
+ return exports.noopLogger;
17
+ return {
18
+ debug: logger.debug ?? exports.noopLogger.debug,
19
+ info: logger.info ?? exports.noopLogger.info,
20
+ warn: logger.warn ?? exports.noopLogger.warn,
21
+ error: logger.error ?? exports.noopLogger.error,
22
+ };
23
+ }
24
+ //# sourceMappingURL=logger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";;;AAYA,sCAQC;AAlBD;;GAEG;AACU,QAAA,UAAU,GAA4B;IACjD,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC;AAEF,SAAgB,aAAa,CAAC,MAAsB;IAClD,IAAI,CAAC,MAAM;QAAE,OAAO,kBAAU,CAAC;IAC/B,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,kBAAU,CAAC,KAAK;QACvC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,kBAAU,CAAC,IAAI;QACpC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,kBAAU,CAAC,IAAI;QACpC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,kBAAU,CAAC,KAAK;KACxC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,244 @@
1
+ # Deploying and releasing `@x12i/countex`
2
+
3
+ This guide has two parts:
4
+
5
+ 1. **Publishing the library** to the public npm registry (`@x12i/countex`).
6
+ 2. **Running it in production** in your own service (MongoDB durable store, Redis cache, process lifecycle, configuration).
7
+
8
+ After `npm install @x12i/countex`, these files ship inside the package (see **Finding this document** at the end).
9
+
10
+ ---
11
+
12
+ ## Part 1 — Publish the package to npm
13
+
14
+ ### 1. Prerequisites
15
+
16
+ - **Node.js** 18 or newer (matches `engines` in `package.json`).
17
+ - An **npm account** with permission to publish under the **`@x12i` scope**. If the scope is new, create an npm organization (or user scope) and add trusted publishers.
18
+ - **Git** remote aligned with `repository` in `package.json` (for tags and optional CI).
19
+
20
+ ### 2. Machine setup
21
+
22
+ 1. Log in locally (interactive):
23
+
24
+ ```bash
25
+ npm login
26
+ ```
27
+
28
+ Or configure a **granular access token** in **`~/.npmrc`** on the machine or in CI secrets — never commit tokens into the repository. The repo’s `.gitignore` excludes `.npmrc` for that reason.
29
+
30
+ 2. Confirm who you are:
31
+
32
+ ```bash
33
+ npm whoami
34
+ ```
35
+
36
+ ### 3. Pre-release checklist
37
+
38
+ Run from the package root (the folder that contains `package.json`):
39
+
40
+ | Step | Command / action |
41
+ |------|------------------|
42
+ | Install dev deps | `npm install` |
43
+ | Tests | `npm test` |
44
+ | Optional integration | `npm run test:integration` |
45
+ | Clean build | `npm run build` (or rely on publish hook below) |
46
+ | Dry-run tarball | `npm publish --dry-run` |
47
+
48
+ `package.json` includes **`prepublishOnly`**: `npm run clean && npm run build`. That means every **`npm publish`** rebuilds `dist/` so the published tarball always matches source.
49
+
50
+ `publishConfig` is set to **`access: "public"`** so the scoped name `@x12i/countex` is published as a **public** package.
51
+
52
+ ### 4. Versioning
53
+
54
+ Follow **semver**:
55
+
56
+ - **`0.x`** — API still stabilizing; breaking changes are expected until `1.0.0`.
57
+ - Bump **`version`** in `package.json` (or use `npm version patch|minor|major`), commit, and tag if your workflow uses tags.
58
+
59
+ Example:
60
+
61
+ ```bash
62
+ npm version patch
63
+ git push origin main --follow-tags
64
+ ```
65
+
66
+ ### 5. Publish
67
+
68
+ ```bash
69
+ npm publish
70
+ ```
71
+
72
+ First-time scoped publish: if anything blocks you, confirm **`publishConfig.access`** is `"public"` (already set in this repo).
73
+
74
+ ### 6. Verify on the registry
75
+
76
+ ```bash
77
+ npm view @x12i/countex version
78
+ npm view @x12i/countex dist.tarball
79
+ ```
80
+
81
+ Smoke-test in an empty directory:
82
+
83
+ ```bash
84
+ mkdir /tmp/countex-smoke && cd /tmp/countex-smoke
85
+ npm init -y
86
+ npm install @x12i/countex
87
+ node -e "console.log(require('@x12i/countex/package.json').version)"
88
+ ```
89
+
90
+ ### 7. Optional — CI publishing (outline)
91
+
92
+ Typical pattern:
93
+
94
+ 1. On release tag or `release` workflow, check out the repo.
95
+ 2. Use a **trusted publishing** / **OIDC** setup with npm (recommended) or a **scoped automation token** stored as a secret.
96
+ 3. Run `npm ci`, `npm test`, then `npm publish`.
97
+
98
+ Exact YAML depends on your host (GitHub Actions, GitLab CI, etc.). Keep tokens out of logs.
99
+
100
+ ---
101
+
102
+ ## Part 2 — Deploy an application that uses Countex
103
+
104
+ Countex is a **library**, not a standalone server. You embed it in a long-running worker, API, or stream consumer.
105
+
106
+ ### 1. Install in your app
107
+
108
+ ```bash
109
+ npm install @x12i/countex
110
+ ```
111
+
112
+ If you use **MongoDB** and/or **Redis** adapters:
113
+
114
+ ```bash
115
+ npm install mongodb ioredis
116
+ ```
117
+
118
+ Those are **peer dependencies**: they must be installed in **your** application; they are not bundled inside `@x12i/countex`.
119
+
120
+ ### 2. Imports
121
+
122
+ | Need | Import |
123
+ |------|--------|
124
+ | Engine factory | `import { createCountex } from "@x12i/countex"` |
125
+ | In-memory adapters | `import { MemoryDurable, MemoryCache } from "@x12i/countex/adapters/memory"` |
126
+ | Mongo durable | `import { MongoDurable } from "@x12i/countex/adapters/mongo"` |
127
+ | Redis cache | `import { RedisCache } from "@x12i/countex/adapters/redis"` |
128
+
129
+ ### 3. MongoDB (durable storage)
130
+
131
+ **Role:** Source of truth for counter cells and dictionary ids (`resolveIds`). Writes use atomic **`$inc`**-style upserts per cell.
132
+
133
+ **Setup:**
134
+
135
+ 1. Provide a **`MongoClient`** from the `mongodb` driver (you own the client lifecycle — connect before `createCountex`, disconnect after shutdown).
136
+ 2. Choose how databases map to **scopes**:
137
+ - **Single DB:** omit `dbResolver` and set `defaultDb` (default name `countex`).
138
+ - **DB per tenant:** use `dbResolver: ({ scope }) => \`countex_${scope}\`` (sanitize names for Mongo rules).
139
+
140
+ **Collections** (defaults):
141
+
142
+ - **`countex_cells`** — aggregate counts.
143
+ - **`countex_dict`** — maps `(scope, kind, qualifier, sourceKey)` → numeric ids for subjects/metrics.
144
+ - **`countex_seq`** — sequence for allocating ids.
145
+
146
+ On **`init()`**, the adapter **ensures indexes** on each DB it touches (unless **`skipIndexInit: true`** for externally managed migrations).
147
+
148
+ **Operations:**
149
+
150
+ - Call **`await countex.init()`** once after construction so default DB indexes exist (when not using only lazy per-scope DBs before first flush — lazy paths still ensure indexes on first write).
151
+ - Under load, Mongo must be reachable with latency suitable for your flush interval; durable flush failures cause buffered deltas to be **re-merged** into memory.
152
+
153
+ ### 4. Redis (cache)
154
+
155
+ **Role:** Hot reads and optional **idempotency** (`markEventSeen`). Cache apply failures during flush are **non-fatal**; durable remains authoritative.
156
+
157
+ **Setup:**
158
+
159
+ 1. Provide an **`ioredis`** client instance.
160
+ 2. Set **`keyPrefix`** to avoid collisions with other apps on shared Redis.
161
+ 3. Set **`ttlSeconds`** for cache eviction consistent with your retention (example code uses ~3 months).
162
+
163
+ **Idempotency:** If your map defines `idempotency` with `eventIdPath`, Countex calls **`cache.markEventSeen`** before buffering. Ensure Redis is available for dedupe semantics you rely on.
164
+
165
+ ### 5. Environment variables (recommended)
166
+
167
+ Define explicitly in your deployment (Kubernetes secrets, systemd `Environment=`, etc.):
168
+
169
+ | Variable | Used by | Purpose |
170
+ |----------|---------|---------|
171
+ | `MONGO_URI` | Your app | Mongo connection string |
172
+ | `REDIS_URL` | Your app | Redis connection string |
173
+
174
+ Example pattern:
175
+
176
+ ```ts
177
+ const mongo = new MongoClient(process.env.MONGO_URI ?? "mongodb://localhost:27017");
178
+ const redis = new IORedis(process.env.REDIS_URL ?? "redis://localhost:6379");
179
+ ```
180
+
181
+ Never commit real URIs or tokens.
182
+
183
+ ### 6. Process lifecycle
184
+
185
+ Recommended order:
186
+
187
+ 1. Construct **`MongoClient`** / **`IORedis`** and connect.
188
+ 2. **`createCountex({ ... })`** with `MongoDurable` / `RedisCache`.
189
+ 3. **`await countex.init()`** — storage initialization.
190
+ 4. **Ingest loop** — `await countex.ingest(event)` or **`ingestBatch`** from Kafka/NATS/HTTP/etc.
191
+ 5. **Flush** — periodic timer may already run via `flush.everyMs`; also call **`await countex.flush()`** before exit or on graceful shutdown.
192
+ 6. **`await countex.shutdown()`** — stops flush timer, optional final flush (`flushOnShutdown`), then **`close`** hooks on adapters (Mongo client is **not** closed by `MongoDurable`; you close it after shutdown).
193
+
194
+ Handle **`SIGTERM` / `SIGINT`** in servers so shutdown flushes buffered counts.
195
+
196
+ ### 7. Flush and backpressure
197
+
198
+ Configure under **`flush`**:
199
+
200
+ - **`everyMs`** — background flush interval (`0` disables timer; you flush manually).
201
+ - **`maxBufferedCells` / `maxBufferedEvents`** — thresholds triggering flush.
202
+ - **`onOverflow`** — `"block"` (await flush) vs `"drop"` (fire-and-forget flush under pressure — understand data risk).
203
+
204
+ Tune for **peak event rate**, **Mongo write throughput**, and **acceptable latency** before counts appear in storage.
205
+
206
+ ### 8. Observability
207
+
208
+ Subscribe to **`Countex`** events (`countex.on(...)`) for:
209
+
210
+ - **`flush`** — cells flushed, duration.
211
+ - **`flush_error`** — durable failure (buffer re-merged).
212
+ - **`duplicate`** — idempotent skip.
213
+ - **`cardinality_warning`**, **`overflow`**, **`dropped`** — mapping/cardinality/dictionary issues.
214
+
215
+ Wire these to your logger/metrics stack.
216
+
217
+ ### 9. Failure modes (short)
218
+
219
+ | Situation | Behavior |
220
+ |-----------|----------|
221
+ | Redis down during flush | Warning; durable OK; reads may hit Mongo |
222
+ | Mongo down during flush | Error; deltas **returned to buffer** |
223
+ | Duplicate event id | Increments skipped for that map/event |
224
+
225
+ ---
226
+
227
+ ## Finding this document after install
228
+
229
+ From a project that depends on `@x12i/countex`:
230
+
231
+ - **On disk:** `node_modules/@x12i/countex/docs/DEPLOYMENT.md`
232
+ - **Stable package subpaths** (for tooling that resolves `exports`):
233
+
234
+ - `@x12i/countex/docs/deployment`
235
+ - `@x12i/countex/docs/end-to-end-example`
236
+
237
+ Your bundler or runtime may not import `.md` as code; open the resolved file path or read it from disk.
238
+
239
+ ---
240
+
241
+ ## Related
242
+
243
+ - **`END_TO_END_EXAMPLE.md`** — tutorial-style walkthrough from install to query.
244
+ - Repository **README** — API overview and quick start.