@x12i/countex 1.2.0 → 1.6.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 (112) hide show
  1. package/README.md +80 -18
  2. package/dist/backup/manifest.d.ts +70 -0
  3. package/dist/backup/manifest.d.ts.map +1 -0
  4. package/dist/backup/manifest.js +131 -0
  5. package/dist/backup/manifest.js.map +1 -0
  6. package/dist/backup/snapshot-encoding.d.ts +8 -0
  7. package/dist/backup/snapshot-encoding.d.ts.map +1 -0
  8. package/dist/backup/snapshot-encoding.js +27 -0
  9. package/dist/backup/snapshot-encoding.js.map +1 -0
  10. package/dist/cli.js +16 -0
  11. package/dist/cli.js.map +1 -1
  12. package/dist/core/countex.d.ts +79 -1
  13. package/dist/core/countex.d.ts.map +1 -1
  14. package/dist/core/countex.js +254 -49
  15. package/dist/core/countex.js.map +1 -1
  16. package/dist/core/extraction.d.ts +1 -5
  17. package/dist/core/extraction.d.ts.map +1 -1
  18. package/dist/core/extraction.js.map +1 -1
  19. package/dist/core/mapping.d.ts +5 -0
  20. package/dist/core/mapping.d.ts.map +1 -1
  21. package/dist/core/mapping.js +27 -0
  22. package/dist/core/mapping.js.map +1 -1
  23. package/dist/index.d.ts +5 -2
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +15 -1
  26. package/dist/index.js.map +1 -1
  27. package/dist/query/formatter.d.ts +2 -2
  28. package/dist/query/formatter.d.ts.map +1 -1
  29. package/dist/query/formatter.js +9 -6
  30. package/dist/query/formatter.js.map +1 -1
  31. package/dist/query/planner.d.ts +15 -1
  32. package/dist/query/planner.d.ts.map +1 -1
  33. package/dist/query/planner.js +152 -3
  34. package/dist/query/planner.js.map +1 -1
  35. package/dist/simulation/context.d.ts +5 -0
  36. package/dist/simulation/context.d.ts.map +1 -0
  37. package/dist/simulation/context.js +56 -0
  38. package/dist/simulation/context.js.map +1 -0
  39. package/dist/simulation/events.d.ts +3 -0
  40. package/dist/simulation/events.d.ts.map +1 -0
  41. package/dist/simulation/events.js +67 -0
  42. package/dist/simulation/events.js.map +1 -0
  43. package/dist/simulation/index.d.ts +7 -0
  44. package/dist/simulation/index.d.ts.map +1 -0
  45. package/dist/simulation/index.js +16 -0
  46. package/dist/simulation/index.js.map +1 -0
  47. package/dist/simulation/prng.d.ts +4 -0
  48. package/dist/simulation/prng.d.ts.map +1 -0
  49. package/dist/simulation/prng.js +18 -0
  50. package/dist/simulation/prng.js.map +1 -0
  51. package/dist/simulation/resource-estimate.d.ts +6 -0
  52. package/dist/simulation/resource-estimate.d.ts.map +1 -0
  53. package/dist/simulation/resource-estimate.js +11 -0
  54. package/dist/simulation/resource-estimate.js.map +1 -0
  55. package/dist/simulation/simulator.d.ts +15 -0
  56. package/dist/simulation/simulator.d.ts.map +1 -0
  57. package/dist/simulation/simulator.js +67 -0
  58. package/dist/simulation/simulator.js.map +1 -0
  59. package/dist/simulation/tracker.d.ts +8 -0
  60. package/dist/simulation/tracker.d.ts.map +1 -0
  61. package/dist/simulation/tracker.js +18 -0
  62. package/dist/simulation/tracker.js.map +1 -0
  63. package/dist/simulation/types.d.ts +49 -0
  64. package/dist/simulation/types.d.ts.map +1 -0
  65. package/dist/simulation/types.js +21 -0
  66. package/dist/simulation/types.js.map +1 -0
  67. package/dist/storage/coverage.d.ts +13 -0
  68. package/dist/storage/coverage.d.ts.map +1 -0
  69. package/dist/storage/coverage.js +37 -0
  70. package/dist/storage/coverage.js.map +1 -0
  71. package/dist/storage/memory.d.ts +23 -5
  72. package/dist/storage/memory.d.ts.map +1 -1
  73. package/dist/storage/memory.js +162 -3
  74. package/dist/storage/memory.js.map +1 -1
  75. package/dist/storage/mongo.d.ts +5 -0
  76. package/dist/storage/mongo.d.ts.map +1 -1
  77. package/dist/storage/mongo.js +68 -1
  78. package/dist/storage/mongo.js.map +1 -1
  79. package/dist/storage/redis.d.ts +40 -11
  80. package/dist/storage/redis.d.ts.map +1 -1
  81. package/dist/storage/redis.js +202 -44
  82. package/dist/storage/redis.js.map +1 -1
  83. package/dist/types/index.d.ts +165 -7
  84. package/dist/types/index.d.ts.map +1 -1
  85. package/docs/DEPLOYMENT.md +125 -3
  86. package/docs/countex_gap_analysis_complete_checklist.md +1340 -0
  87. package/docs/guides/README.md +5 -0
  88. package/docs/guides/adapter-mongo.md +12 -0
  89. package/docs/guides/adapter-redis.md +46 -4
  90. package/docs/guides/backup-export.md +106 -10
  91. package/docs/guides/cli.md +8 -0
  92. package/docs/guides/counter-maps.md +14 -0
  93. package/docs/guides/insights-overview.md +6 -0
  94. package/docs/guides/measures.md +4 -0
  95. package/docs/guides/preview.md +92 -0
  96. package/docs/guides/querying.md +70 -0
  97. package/docs/guides/simulation-profiles.md +33 -0
  98. package/docs/guides/simulation-resource-estimation.md +30 -0
  99. package/docs/guides/simulation.md +36 -0
  100. package/docs/internals/README.md +1 -0
  101. package/docs/internals/internal-dimension-hash.md +34 -0
  102. package/docs/internals/internal-storage-mongo.md +24 -4
  103. package/docs/internals/internal-storage-redis.md +41 -9
  104. package/docs/use-cases/README.md +56 -0
  105. package/docs/use-cases/audit-security-log-counts.md +550 -0
  106. package/docs/use-cases/llm-cost-and-token-metering.md +255 -0
  107. package/docs/use-cases/multi-tenant-isolation.md +203 -0
  108. package/docs/use-cases/ops-dashboard-daily-rollups.md +255 -0
  109. package/docs/use-cases/processing-workflow-activity.md +165 -0
  110. package/docs/use-cases/product-feature-usage.md +240 -0
  111. package/docs/use-cases/webhook-idempotent-ingestion.md +188 -0
  112. package/package.json +18 -2
package/README.md CHANGED
@@ -7,6 +7,10 @@
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)
@@ -36,6 +40,7 @@ These guides are included in the published tarball under `docs/` and exposed as
36
40
  | Tutorial — install → map → ingest → query | `@x12i/countex/docs/end-to-end-example` | `docs/END_TO_END_EXAMPLE.md` |
37
41
  | Feature guides index | `@x12i/countex/docs/guides` | `docs/guides/README.md` |
38
42
  | Counter maps | `@x12i/countex/docs/guides/counter-maps` | `docs/guides/counter-maps.md` |
43
+ | Preview a map (dry-run) | `@x12i/countex/docs/guides/preview` | `docs/guides/preview.md` |
39
44
  | Ingestion & flush | `@x12i/countex/docs/guides/ingestion-and-flush` | `docs/guides/ingestion-and-flush.md` |
40
45
  | Timeframes | `@x12i/countex/docs/guides/timeframes-and-bucketing` | `docs/guides/timeframes-and-bucketing.md` |
41
46
  | Measures | `@x12i/countex/docs/guides/measures` | `docs/guides/measures.md` |
@@ -54,6 +59,23 @@ These guides are included in the published tarball under `docs/` and exposed as
54
59
  | Insights forecasting & budget | `@x12i/countex/docs/guides/insights-forecasting-and-budget` | `docs/guides/insights-forecasting-and-budget.md` |
55
60
  | Insights advisors | `@x12i/countex/docs/guides/insights-advisors-and-optimization` | `docs/guides/insights-advisors-and-optimization.md` |
56
61
  | CLI | `@x12i/countex/docs/guides/cli` | `docs/guides/cli.md` |
62
+ | Simulation runtime (JS API) | `@x12i/countex/simulation` | `dist/simulation/` |
63
+ | Simulation overview | `@x12i/countex/docs/guides/simulation` | `docs/guides/simulation.md` |
64
+ | Simulation profiles | `@x12i/countex/docs/guides/simulation-profiles` | `docs/guides/simulation-profiles.md` |
65
+ | Simulation resource estimation | `@x12i/countex/docs/guides/simulation-resource-estimation` | `docs/guides/simulation-resource-estimation.md` |
66
+
67
+ **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)):
68
+
69
+ | Topic | Package subpath | File |
70
+ |-------|-----------------|------|
71
+ | Use cases index | `@x12i/countex/docs/use-cases` | `docs/use-cases/README.md` |
72
+ | 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` |
73
+ | Product & feature activity | `@x12i/countex/docs/use-cases/product-feature-usage` | `docs/use-cases/product-feature-usage.md` |
74
+ | LLM cost & token metering | `@x12i/countex/docs/use-cases/llm-cost-and-token-metering` | `docs/use-cases/llm-cost-and-token-metering.md` |
75
+ | Multi-tenant isolation | `@x12i/countex/docs/use-cases/multi-tenant-isolation` | `docs/use-cases/multi-tenant-isolation.md` |
76
+ | Idempotent webhooks & queues | `@x12i/countex/docs/use-cases/webhook-idempotent-ingestion` | `docs/use-cases/webhook-idempotent-ingestion.md` |
77
+ | Ops dashboards & rollups | `@x12i/countex/docs/use-cases/ops-dashboard-daily-rollups` | `docs/use-cases/ops-dashboard-daily-rollups.md` |
78
+ | Processing & workflow activity | `@x12i/countex/docs/use-cases/processing-workflow-activity` | `docs/use-cases/processing-workflow-activity.md` |
57
79
 
58
80
  **Internals** (how the engine works — diagrams and traces) live under `docs/internals/` in the tarball; browse [`docs/internals/README.md`](docs/internals/README.md).
59
81
 
@@ -93,6 +115,10 @@ Queries accept **`measures`** (explicit list or `"*"`), **`orderBy`** on a measu
93
115
 
94
116
  **`bucketRange`** caps at **10,000** buckets; at **`minute`** resolution that is about **6.94 days** — keep queries within that bound or narrow the range.
95
117
 
118
+ ### Percentiles & histograms
119
+
120
+ Core cells store **additive** measure aggregates (`sum / count / min / max`) per sparse cell. They do **not** store distributions, so percentile-style answers (p50/p90/p95/p99) can only come from min/max approximation or from histogram/sketch storage you add yourself. Insights advisors that mention percentile-shaped recommendations are heuristic; see [`docs/guides/insights-overview.md`](docs/guides/insights-overview.md) §"Distributions" and [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) "Architecture decisions".
121
+
96
122
  ---
97
123
 
98
124
  ## What kinds of events Countex is for
@@ -275,6 +301,10 @@ That single ingest produces:
275
301
 
276
302
  Each cell uses an atomic `$inc` on durable and `HINCRBY` on the cache, so 20 ingest workers can safely run in parallel.
277
303
 
304
+ ### Preview a map (dry-run)
305
+
306
+ Use `countex.preview(event, { counterId? })` to inspect what one event would produce without any I/O — no dictionary allocation, no buffering, no writes. Returns one `MapPreviewResult` per matching map, each with `cells: PreviewIncrementCell[]` (subjects, metrics, dimensions, dimensionsHash, timeframe keys, deltas, measures), `extractionWarnings`, and `droppedAfterCardinality`. See [docs/guides/preview.md](docs/guides/preview.md).
307
+
278
308
  ---
279
309
 
280
310
  ## Production setup (Mongo + Redis)
@@ -332,9 +362,10 @@ A `CounterMap` is the heart of the package. Everything Countex knows about your
332
362
  | `eventTime` | `{ path }` | Path to a Date / ISO string / epoch ms. Drives bucket selection. |
333
363
  | `subjects` | `SubjectMapping[]` | One or many. Each has `type` and `path`; multi-value paths fan out. |
334
364
  | `metrics` | `MetricMapping[]` | Same fanout semantics. `$.labels[*]` is common. |
365
+ | `measures` | `MeasureMapping[]` | Optional numeric fields per event (`sum` / `count` / `min` / `max`); see [Measures](./docs/guides/measures.md). |
335
366
  | `dimensions` | `DimensionMapping[]` | Named extra breakdowns. Optional by default. |
336
367
  | `delta` | `{ path?, default? }` | Numeric value at runtime. Default `1`. Negative deltas are fine. |
337
- | `timeframes` | `TimeframeType[]` | Subset of `day` / `week` / `month` / `quarter` / `year` / `all`. |
368
+ | `timeframes` | `TimeframeType[]` | Subset of `minute` / `hour` / `day` / `week` / `month` / `quarter` / `year` / `all`. |
338
369
  | `idempotency` | `IdempotencyPolicy` | Optional; needs a cache adapter that implements `markEventSeen`. |
339
370
  | `cardinality` | `CardinalityPolicy` | Optional; per-map override of engine-level defaults. |
340
371
  | `options` | `MappingOptions` | `skipMissingOptionalDimensions` (default true), `normalizeValues` (default true). |
@@ -429,7 +460,9 @@ Indexes (created automatically on first write):
429
460
  - `by_subject` — for subject filters
430
461
  - `by_metric` — for metric filters
431
462
 
432
- `countex_dict` — the per-scope subject/metric dictionary, with monotonic ids allocated via `countex_seq`.
463
+ `countex_dict` — the per-scope subject/metric dictionary, with monotonic ids allocated via `countex_seq`. Allocation is **concurrency-safe by construction**: read existing → atomic sequence `$inc` → `insertMany({ ordered: false })` → on duplicate-key, re-read. See [`docs/guides/adapter-mongo.md`](docs/guides/adapter-mongo.md) §"Dictionary allocation (`resolveIds`) and concurrency" and [`docs/internals/internal-storage-mongo.md`](docs/internals/internal-storage-mongo.md).
464
+
465
+ `dimensionsHash` is canonicalized so any two workers produce the same hash for the same logical dimension tuple: keys sorted lexicographically, values type-tagged (`n: / b: / i: / s:`), serialized, hashed (SHA-1, truncated to 12 hex). See [`docs/internals/internal-dimension-hash.md`](docs/internals/internal-dimension-hash.md).
433
466
 
434
467
  ### Redis layout
435
468
 
@@ -621,28 +654,52 @@ All writes are atomic per cell:
621
654
 
622
655
  20+ Countex workers can safely run in parallel against the same scope. Reads are eventually consistent across the two stores; if Redis is behind durable, the planner will detect partial coverage and read durable.
623
656
 
624
- ### Backup / rebuild
657
+ ### Backup / verify / restore / rebuild
625
658
 
626
- ```ts
627
- import { exportCells, rebuildCache } from "@x12i/countex";
659
+ Top-level free functions and a `countex.backup` namespace bound to your engine:
628
660
 
629
- // Stream all cells in a window — bounded async iteration.
630
- for await (const cell of exportCells(durable, {
661
+ ```ts
662
+ import {
663
+ exportCells,
664
+ computeCellsFingerprint,
665
+ createBackupManifest,
666
+ verifyBackupAgainstManifest,
667
+ restoreSnapshotCells,
668
+ rebuildCache,
669
+ COUNTEX_CELL_SCHEMA_VERSION,
670
+ } from "@x12i/countex";
671
+
672
+ const filter = {
631
673
  scope: "org_123",
632
674
  counterId: "access_by_subject_metric",
633
675
  timeframe: { type: "day", from: "2026-02-01", to: "2026-05-08" },
634
- })) {
676
+ };
677
+
678
+ // Stream all cells in a window — bounded async iteration.
679
+ for await (const cell of exportCells(durable, filter)) {
635
680
  // ndjson, S3, whatever you want
636
681
  }
637
682
 
638
- // Re-warm cache from durable.
639
- await rebuildCache(durable, cache, {
640
- scope: "org_123",
641
- counterId: "access_by_subject_metric",
642
- timeframe: { type: "day", from: "2026-02-01", to: "2026-05-08" },
643
- });
683
+ // Fingerprint + manifest for cold-storage verification.
684
+ const fp = await countex.backup.fingerprint(filter); // { cellCount, contentSha256, countSum }
685
+ const manifest = countex.backup.createManifest(filter, fp); // { manifestVersion, schemaVersion, filter, … }
686
+
687
+ // Verify a manifest against the live durable adapter.
688
+ const ok = await countex.backup.verify(manifest);
689
+ if (!ok.ok) throw new Error(ok.detail);
690
+
691
+ // Restore. Modes: "validate-only" | "replace-window" (default) | "merge-deltas" (reserved).
692
+ const { restored, mode } = await countex.backup.restore(
693
+ countex.backup.export(filter),
694
+ { mode: "replace-window" },
695
+ );
696
+
697
+ // Re-warm cache from durable. Each warmed bucket's :cov flips to status=complete.
698
+ await countex.backup.rebuildCache(filter);
644
699
  ```
645
700
 
701
+ See [`docs/guides/backup-export.md`](docs/guides/backup-export.md) for the full recipe and manifest layout.
702
+
646
703
  ---
647
704
 
648
705
  ## Errors
@@ -660,6 +717,8 @@ All errors thrown by Countex extend `CountexError`:
660
717
 
661
718
  ## Versioning & scope
662
719
 
720
+ > **Additive counts are not distinct counts.** If `user_42` appears in 100 events, `count = 100`, not 1 unique user. Counter cells store sums of deltas, so a query result of `count = 100` from a subject-grouped view means "100 increments hit this subject", not "100 distinct subjects". For exact distinct subject counts, group by `["subjectType", "subject"]` and use `rows.length` after retrieving every matching cell — see [`docs/guides/querying.md`](docs/guides/querying.md) §"Distinct subjects / metrics as row cardinality". Approximate distinct counts (HLL/sets) are a planned opt-in extension, not core.
721
+
663
722
  `v0.x` is for stabilizing the public API. Once it's hardened:
664
723
 
665
724
  - exact unique counts (HLL / sets) are an opt-in extension, not core
@@ -674,12 +733,15 @@ All errors thrown by Countex extend `CountexError`:
674
733
  |------|------|
675
734
  | `src/index.ts` | Public exports (`createCountex`, types, errors). |
676
735
  | `src/core/` | Engine: ingest pipeline, buffer, extraction, mapping validation, time buckets, cardinality. |
677
- | `src/query/` | Query planner and result formatting. |
678
- | `src/storage/` | Adapters: `memory` (in-process), `mongo` (durable), `redis` (cache). |
736
+ | `src/query/` | Query planner (`planQuery` + `executeQuery`) and result formatting. |
737
+ | `src/storage/` | Adapters: `memory` (in-process), `mongo` (durable), `redis` (cache); shared coverage helpers. |
679
738
  | `src/utils/` | JSONPath subset, hashing, logging. |
680
- | `src/backup/` | Export / cache rebuild helpers. |
739
+ | `src/backup/` | Export, fingerprint, manifest, verify, restore, cache rebuild helpers. |
740
+ | `src/simulation/` | Simulation engine, profiles, expected aggregates, resource reports. |
741
+ | `src/insights/` | Ranking, comparison, anomaly detection, advisors, recommendations. |
742
+ | `src/cli.ts` | CLI commands for simulation, insights, export, and operational helpers. |
681
743
  | `examples/` | Runnable demos (`npx tsx examples/basic.ts`). |
682
- | `docs/` | Deployment guide and end-to-end tutorial (published in the npm package). |
744
+ | `docs/` | Deployment guide, tutorial, guides, internals, and use cases (published in the npm package). |
683
745
  | `tests/unit/` | Fast Node test runner tests (`npm test`). |
684
746
  | `tests/integration/` | Opt-in live tests against real services (`npm run test:integration`). |
685
747
 
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Backup manifest, checksum verification, and snapshot restore orchestration.
3
+ */
4
+ import type { CounterCell, DurableStorage, QuerySpec } from "../types/index.js";
5
+ import { CountexError } from "../utils/errors.js";
6
+ export declare const BACKUP_MANIFEST_VERSION: 1;
7
+ /** Logical schema marker for manifests; aligns with Mongo cell `schemaVersion` when using MongoDurable. */
8
+ export declare const COUNTEX_CELL_SCHEMA_VERSION = 1;
9
+ /** Restore semantics. `merge-deltas` is reserved for a future release. */
10
+ export type RestoreMode = "validate-only" | "replace-window" | "merge-deltas";
11
+ /** Thrown when a restore mode is not yet implemented. */
12
+ export declare class NotImplementedError extends CountexError {
13
+ constructor(message: string);
14
+ }
15
+ /** Document payload saved alongside an export (JSON). */
16
+ export interface BackupManifest {
17
+ manifestVersion: typeof BACKUP_MANIFEST_VERSION;
18
+ /** Engine cell schema marker (see Mongo `schemaVersion`). */
19
+ schemaVersion: number;
20
+ createdAtIso: string;
21
+ filter: Pick<QuerySpec, "scope" | "counterId" | "timeframe">;
22
+ cellCount: number;
23
+ /** SHA-256 of sorted canonical JSON lines (see `canonicalCellLine`). */
24
+ contentSha256: string;
25
+ /** Sum of `count` across all cells in the export (optional, set when computed). */
26
+ countSum?: number;
27
+ }
28
+ export declare function canonicalCellLine(cell: CounterCell): string;
29
+ /**
30
+ * Stable fingerprint over an async cell stream (sorts canonical lines in memory).
31
+ * Suitable for bounded windows; for huge exports chunk by timeframe.
32
+ *
33
+ * Returns the standard `cellCount` + `contentSha256` plus a `countSum` of all
34
+ * cells' `count` field, suitable for an optional manifest sanity check.
35
+ */
36
+ export declare function computeCellsFingerprint(cells: AsyncIterable<CounterCell>): Promise<{
37
+ cellCount: number;
38
+ contentSha256: string;
39
+ countSum: number;
40
+ }>;
41
+ export declare function createBackupManifest(filter: Pick<QuerySpec, "scope" | "counterId" | "timeframe">, fp: {
42
+ cellCount: number;
43
+ contentSha256: string;
44
+ countSum?: number;
45
+ }, schemaVersion: number, createdAt?: Date): BackupManifest;
46
+ export declare function verifyBackupAgainstManifest(manifest: BackupManifest, cells: AsyncIterable<CounterCell>): Promise<{
47
+ ok: true;
48
+ } | {
49
+ ok: false;
50
+ detail: string;
51
+ }>;
52
+ /**
53
+ * Replace cells from an export stream. Requires adapter support (`importSnapshotCells`).
54
+ *
55
+ * Modes:
56
+ * - `validate-only` — count cells without writing (also accepts `dryRun: true`).
57
+ * - `replace-window` — replace each cell identity in the stream (default).
58
+ * - `merge-deltas` — reserved; throws `NotImplementedError` today.
59
+ */
60
+ export declare function restoreSnapshotCells(durable: DurableStorage, cells: AsyncIterable<CounterCell>, options?: {
61
+ /** @deprecated use `mode: "validate-only"`. */
62
+ dryRun?: boolean;
63
+ mode?: RestoreMode;
64
+ batchSize?: number;
65
+ signal?: AbortSignal;
66
+ }): Promise<{
67
+ restored: number;
68
+ mode: RestoreMode;
69
+ }>;
70
+ //# 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;AAChF,OAAO,EAAE,YAAY,EAAgB,MAAM,oBAAoB,CAAC;AAEhE,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD,2GAA2G;AAC3G,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAE9E,yDAAyD;AACzD,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED,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;IACtB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAc3D;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAczE;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,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACnE,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,IAAiB,GAC3B,cAAc,CAUhB;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,CAkBvD;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,EACjC,OAAO,CAAC,EAAE;IACR,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAoClD"}
@@ -0,0 +1,131 @@
1
+ "use strict";
2
+ /**
3
+ * Backup manifest, checksum verification, and snapshot restore orchestration.
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.NotImplementedError = 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
+ /** Thrown when a restore mode is not yet implemented. */
18
+ class NotImplementedError extends errors_js_1.CountexError {
19
+ constructor(message) {
20
+ super(message);
21
+ this.name = "NotImplementedError";
22
+ }
23
+ }
24
+ exports.NotImplementedError = NotImplementedError;
25
+ function canonicalCellLine(cell) {
26
+ return JSON.stringify({
27
+ scopeId: cell.scopeId,
28
+ counterId: cell.counterId,
29
+ timeframeType: cell.timeframeType,
30
+ timeframeKey: cell.timeframeKey,
31
+ subjectType: cell.subjectType,
32
+ subjectId: cell.subjectId,
33
+ metricId: cell.metricId,
34
+ dimensionsHash: cell.dimensionsHash,
35
+ dimensions: cell.dimensions,
36
+ count: cell.count,
37
+ measures: cell.measures,
38
+ });
39
+ }
40
+ /**
41
+ * Stable fingerprint over an async cell stream (sorts canonical lines in memory).
42
+ * Suitable for bounded windows; for huge exports chunk by timeframe.
43
+ *
44
+ * Returns the standard `cellCount` + `contentSha256` plus a `countSum` of all
45
+ * cells' `count` field, suitable for an optional manifest sanity check.
46
+ */
47
+ async function computeCellsFingerprint(cells) {
48
+ const lines = [];
49
+ let countSum = 0;
50
+ for await (const c of cells) {
51
+ lines.push(canonicalCellLine(c));
52
+ countSum += c.count;
53
+ }
54
+ lines.sort();
55
+ const h = (0, node_crypto_1.createHash)("sha256");
56
+ for (const line of lines) {
57
+ h.update(line);
58
+ h.update("\n");
59
+ }
60
+ return { cellCount: lines.length, contentSha256: h.digest("hex"), countSum };
61
+ }
62
+ function createBackupManifest(filter, fp, schemaVersion, createdAt = new Date()) {
63
+ return {
64
+ manifestVersion: exports.BACKUP_MANIFEST_VERSION,
65
+ schemaVersion,
66
+ createdAtIso: createdAt.toISOString(),
67
+ filter,
68
+ cellCount: fp.cellCount,
69
+ contentSha256: fp.contentSha256,
70
+ ...(fp.countSum !== undefined ? { countSum: fp.countSum } : {}),
71
+ };
72
+ }
73
+ async function verifyBackupAgainstManifest(manifest, cells) {
74
+ const fp = await computeCellsFingerprint(cells);
75
+ if (fp.cellCount !== manifest.cellCount) {
76
+ return {
77
+ ok: false,
78
+ detail: `cell count mismatch: stream has ${fp.cellCount}, manifest expects ${manifest.cellCount}`,
79
+ };
80
+ }
81
+ if (fp.contentSha256 !== manifest.contentSha256) {
82
+ return { ok: false, detail: "contentSha256 mismatch" };
83
+ }
84
+ if (manifest.countSum !== undefined && fp.countSum !== manifest.countSum) {
85
+ return {
86
+ ok: false,
87
+ detail: `countSum mismatch: stream sums ${fp.countSum}, manifest expects ${manifest.countSum}`,
88
+ };
89
+ }
90
+ return { ok: true };
91
+ }
92
+ /**
93
+ * Replace cells from an export stream. Requires adapter support (`importSnapshotCells`).
94
+ *
95
+ * Modes:
96
+ * - `validate-only` — count cells without writing (also accepts `dryRun: true`).
97
+ * - `replace-window` — replace each cell identity in the stream (default).
98
+ * - `merge-deltas` — reserved; throws `NotImplementedError` today.
99
+ */
100
+ async function restoreSnapshotCells(durable, cells, options) {
101
+ const mode = options?.mode ?? (options?.dryRun ? "validate-only" : "replace-window");
102
+ if (mode === "merge-deltas") {
103
+ throw new NotImplementedError("restoreSnapshotCells: 'merge-deltas' mode is not implemented in this release");
104
+ }
105
+ if (mode === "replace-window" && !durable.importSnapshotCells) {
106
+ throw new errors_js_1.StorageError("Durable adapter does not implement importSnapshotCells", {});
107
+ }
108
+ const batchSize = options?.batchSize ?? 500;
109
+ let restored = 0;
110
+ let batch = [];
111
+ const flush = async () => {
112
+ if (batch.length === 0)
113
+ return;
114
+ if (mode === "replace-window") {
115
+ await durable.importSnapshotCells(batch, { signal: options?.signal });
116
+ }
117
+ restored += batch.length;
118
+ batch = [];
119
+ };
120
+ for await (const c of cells) {
121
+ if (options?.signal?.aborted) {
122
+ throw new errors_js_1.StorageError("restoreSnapshotCells aborted", {});
123
+ }
124
+ batch.push(c);
125
+ if (batch.length >= batchSize)
126
+ await flush();
127
+ }
128
+ await flush();
129
+ return { restored, mode };
130
+ }
131
+ //# 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.js CHANGED
@@ -86,8 +86,24 @@ async function main() {
86
86
  }
87
87
  }
88
88
  const [cmd, configPath, ...rest] = filtered;
89
+ if (cmd === "simulate:demo") {
90
+ let events = 100;
91
+ let seed = 42;
92
+ for (let i = 1; i < filtered.length; i++) {
93
+ if (filtered[i] === "--events" && filtered[i + 1])
94
+ events = Number(filtered[++i]);
95
+ else if (filtered[i] === "--seed" && filtered[i + 1])
96
+ seed = Number(filtered[++i]);
97
+ }
98
+ const { createCountexSimulator, DEMO_SIMULATION_MAP } = await Promise.resolve().then(() => __importStar(require("./simulation/index.js")));
99
+ const sim = createCountexSimulator({ profile: { id: "audit-log" }, seed });
100
+ const report = sim.estimateFanout(DEMO_SIMULATION_MAP, events);
101
+ console.log(JSON.stringify(report, null, 2));
102
+ return;
103
+ }
89
104
  if (!cmd || !configPath) {
90
105
  console.error(`Usage: countex insights:<command> <configfile> [--format json|markdown]
106
+ countex simulate:demo [--events N] [--seed S]
91
107
 
92
108
  Commands:
93
109
  insights:top insights:pareto insights:anomalies insights:cost insights:tokens
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -15,7 +15,10 @@
15
15
  * - At most one flush runs at a time (guarded by a promise lock). New deltas
16
16
  * accumulate while a flush is in flight.
17
17
  */
18
- import type { CountexConfig, CountexEvents, QueryResult, QuerySpec } from "../types/index.js";
18
+ import type { CountexConfig, CountexEvents, MapPreviewResult, QueryPlan, QueryResult, QuerySpec, RetentionDuration } from "../types/index.js";
19
+ import { type ExportFilter } from "../backup/export.js";
20
+ import { type BackupManifest, type RestoreMode } from "../backup/manifest.js";
21
+ import type { CounterCell } from "../types/index.js";
19
22
  export declare class Countex {
20
23
  private readonly cfg;
21
24
  private readonly buffer;
@@ -33,17 +36,92 @@ export declare class Countex {
33
36
  private emit;
34
37
  ingest(event: unknown): Promise<void>;
35
38
  ingestBatch(events: unknown[]): Promise<void>;
39
+ /**
40
+ * Dry-run mapping for one event: extraction + cardinality, no dictionary I/O and no buffer.
41
+ * Does not emit lifecycle events (`dropped`, `overflow`, etc.).
42
+ */
43
+ preview(event: unknown, options?: {
44
+ counterId?: string;
45
+ }): MapPreviewResult[];
46
+ /**
47
+ * Cardinality pass shared by ingest and preview. When `silent`, no events are emitted
48
+ * and cardinality counters still update (preview affects in-process guard state — use a
49
+ * dedicated Countex instance for isolated dry-runs).
50
+ */
51
+ private applyCardinalityPass;
36
52
  /**
37
53
  * Flush buffered deltas. At most one flush runs at a time; overlapping
38
54
  * callers get the same in-flight promise.
39
55
  */
40
56
  flush(): Promise<void>;
41
57
  query(spec: QuerySpec): Promise<QueryResult>;
58
+ /**
59
+ * Explain a query without executing it. Returns a {@link QueryPlan} with
60
+ * bucket expansion, cache eligibility, predicted durable fallback, and a
61
+ * cost classification. Probes per-bucket cache coverage when the cache
62
+ * adapter supports `probeBucketCoverage`.
63
+ */
64
+ explainQuery(spec: QuerySpec): Promise<QueryPlan>;
65
+ private buildPlannerCtx;
42
66
  diag(): {
43
67
  bufferCells: number;
44
68
  bufferEvents: number;
45
69
  };
70
+ /**
71
+ * Backup helpers bound to this Countex instance's durable + cache. Mirrors
72
+ * the free-function exports (`exportCells`, `verifyBackupAgainstManifest`,
73
+ * `restoreSnapshotCells`, `rebuildCache`) for ergonomic use:
74
+ *
75
+ * await countex.backup.verify(manifest);
76
+ * await countex.backup.restore(stream, { mode: "validate-only" });
77
+ */
78
+ readonly backup: {
79
+ export: (filter: ExportFilter, signal?: AbortSignal) => AsyncIterable<CounterCell>;
80
+ fingerprint: (filter: ExportFilter, signal?: AbortSignal) => Promise<{
81
+ cellCount: number;
82
+ contentSha256: string;
83
+ countSum: number;
84
+ }>;
85
+ createManifest: (filter: ExportFilter, fp: {
86
+ cellCount: number;
87
+ contentSha256: string;
88
+ countSum?: number;
89
+ }, schemaVersion?: number) => BackupManifest;
90
+ verify: (manifest: BackupManifest, signal?: AbortSignal) => Promise<{
91
+ ok: true;
92
+ } | {
93
+ ok: false;
94
+ detail: string;
95
+ }>;
96
+ restore: (cells: AsyncIterable<CounterCell>, options?: {
97
+ mode?: RestoreMode;
98
+ batchSize?: number;
99
+ signal?: AbortSignal;
100
+ }) => Promise<{
101
+ restored: number;
102
+ mode: RestoreMode;
103
+ }>;
104
+ rebuildCache: (filter: ExportFilter, options?: {
105
+ batchSize?: number;
106
+ signal?: AbortSignal;
107
+ }) => Promise<{
108
+ cellsWarmed: number;
109
+ }>;
110
+ };
46
111
  }
112
+ /**
113
+ * Parse a {@link RetentionDuration} into seconds. Accepts numbers (already
114
+ * seconds), `"forever"` (returns `Infinity`), or `<n><unit>` strings:
115
+ * `s` second (default unit when only digits are given)
116
+ * `m` minute
117
+ * `h` hour
118
+ * `d` day
119
+ * `w` week
120
+ * `mo` month (30d)
121
+ * `q` quarter (90d)
122
+ * `y` year (365d)
123
+ */
124
+ export declare function parseRetentionDuration(d: RetentionDuration): number;
47
125
  /** Factory matching the spec's public API. */
48
126
  export declare function createCountex(config: CountexConfig): Countex;
49
127
  //# sourceMappingURL=countex.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"countex.d.ts","sourceRoot":"","sources":["../../src/core/countex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAIV,aAAa,EACb,aAAa,EAKb,WAAW,EACX,SAAS,EACV,MAAM,mBAAmB,CAAC;AA+B3B,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAE9C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,aAAa;IAqC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB/B,EAAE,CAAC,CAAC,SAAS,MAAM,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAKhG,GAAG,CAAC,CAAC,SAAS,MAAM,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAKjG,OAAO,CAAC,IAAI;IAMN,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuOnD;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2ChB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAUlD,IAAI,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;CAMtD;AAUD,8CAA8C;AAC9C,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE5D"}
1
+ {"version":3,"file":"countex.d.ts","sourceRoot":"","sources":["../../src/core/countex.ts"],"names":[],"mappings":"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"}