@x12i/countex 1.5.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 (40) hide show
  1. package/README.md +57 -17
  2. package/dist/backup/manifest.d.ts +22 -1
  3. package/dist/backup/manifest.d.ts.map +1 -1
  4. package/dist/backup/manifest.js +34 -6
  5. package/dist/backup/manifest.js.map +1 -1
  6. package/dist/core/countex.d.ts +66 -1
  7. package/dist/core/countex.d.ts.map +1 -1
  8. package/dist/core/countex.js +113 -4
  9. package/dist/core/countex.js.map +1 -1
  10. package/dist/index.d.ts +4 -4
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +3 -1
  13. package/dist/index.js.map +1 -1
  14. package/dist/query/planner.d.ts +15 -1
  15. package/dist/query/planner.d.ts.map +1 -1
  16. package/dist/query/planner.js +136 -1
  17. package/dist/query/planner.js.map +1 -1
  18. package/dist/storage/coverage.d.ts +13 -0
  19. package/dist/storage/coverage.d.ts.map +1 -0
  20. package/dist/storage/coverage.js +37 -0
  21. package/dist/storage/coverage.js.map +1 -0
  22. package/dist/storage/memory.d.ts +20 -5
  23. package/dist/storage/memory.d.ts.map +1 -1
  24. package/dist/storage/memory.js +127 -3
  25. package/dist/storage/memory.js.map +1 -1
  26. package/dist/storage/redis.d.ts +36 -11
  27. package/dist/storage/redis.d.ts.map +1 -1
  28. package/dist/storage/redis.js +189 -41
  29. package/dist/storage/redis.js.map +1 -1
  30. package/dist/types/index.d.ts +114 -7
  31. package/dist/types/index.d.ts.map +1 -1
  32. package/docs/DEPLOYMENT.md +87 -3
  33. package/docs/guides/adapter-redis.md +40 -4
  34. package/docs/guides/backup-export.md +84 -32
  35. package/docs/guides/counter-maps.md +8 -0
  36. package/docs/guides/preview.md +92 -0
  37. package/docs/guides/querying.md +30 -0
  38. package/docs/internals/internal-storage-mongo.md +24 -4
  39. package/docs/internals/internal-storage-redis.md +41 -9
  40. package/package.json +1 -1
package/README.md CHANGED
@@ -40,6 +40,7 @@ These guides are included in the published tarball under `docs/` and exposed as
40
40
  | Tutorial — install → map → ingest → query | `@x12i/countex/docs/end-to-end-example` | `docs/END_TO_END_EXAMPLE.md` |
41
41
  | Feature guides index | `@x12i/countex/docs/guides` | `docs/guides/README.md` |
42
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` |
43
44
  | Ingestion & flush | `@x12i/countex/docs/guides/ingestion-and-flush` | `docs/guides/ingestion-and-flush.md` |
44
45
  | Timeframes | `@x12i/countex/docs/guides/timeframes-and-bucketing` | `docs/guides/timeframes-and-bucketing.md` |
45
46
  | Measures | `@x12i/countex/docs/guides/measures` | `docs/guides/measures.md` |
@@ -114,6 +115,10 @@ Queries accept **`measures`** (explicit list or `"*"`), **`orderBy`** on a measu
114
115
 
115
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.
116
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
+
117
122
  ---
118
123
 
119
124
  ## What kinds of events Countex is for
@@ -296,6 +301,10 @@ That single ingest produces:
296
301
 
297
302
  Each cell uses an atomic `$inc` on durable and `HINCRBY` on the cache, so 20 ingest workers can safely run in parallel.
298
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
+
299
308
  ---
300
309
 
301
310
  ## Production setup (Mongo + Redis)
@@ -451,7 +460,9 @@ Indexes (created automatically on first write):
451
460
  - `by_subject` — for subject filters
452
461
  - `by_metric` — for metric filters
453
462
 
454
- `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).
455
466
 
456
467
  ### Redis layout
457
468
 
@@ -643,28 +654,52 @@ All writes are atomic per cell:
643
654
 
644
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.
645
656
 
646
- ### Backup / rebuild
657
+ ### Backup / verify / restore / rebuild
647
658
 
648
- ```ts
649
- import { exportCells, rebuildCache } from "@x12i/countex";
659
+ Top-level free functions and a `countex.backup` namespace bound to your engine:
650
660
 
651
- // Stream all cells in a window — bounded async iteration.
652
- 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 = {
653
673
  scope: "org_123",
654
674
  counterId: "access_by_subject_metric",
655
675
  timeframe: { type: "day", from: "2026-02-01", to: "2026-05-08" },
656
- })) {
676
+ };
677
+
678
+ // Stream all cells in a window — bounded async iteration.
679
+ for await (const cell of exportCells(durable, filter)) {
657
680
  // ndjson, S3, whatever you want
658
681
  }
659
682
 
660
- // Re-warm cache from durable.
661
- await rebuildCache(durable, cache, {
662
- scope: "org_123",
663
- counterId: "access_by_subject_metric",
664
- timeframe: { type: "day", from: "2026-02-01", to: "2026-05-08" },
665
- });
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);
666
699
  ```
667
700
 
701
+ See [`docs/guides/backup-export.md`](docs/guides/backup-export.md) for the full recipe and manifest layout.
702
+
668
703
  ---
669
704
 
670
705
  ## Errors
@@ -682,6 +717,8 @@ All errors thrown by Countex extend `CountexError`:
682
717
 
683
718
  ## Versioning & scope
684
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
+
685
722
  `v0.x` is for stabilizing the public API. Once it's hardened:
686
723
 
687
724
  - exact unique counts (HLL / sets) are an opt-in extension, not core
@@ -696,12 +733,15 @@ All errors thrown by Countex extend `CountexError`:
696
733
  |------|------|
697
734
  | `src/index.ts` | Public exports (`createCountex`, types, errors). |
698
735
  | `src/core/` | Engine: ingest pipeline, buffer, extraction, mapping validation, time buckets, cardinality. |
699
- | `src/query/` | Query planner and result formatting. |
700
- | `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. |
701
738
  | `src/utils/` | JSONPath subset, hashing, logging. |
702
- | `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. |
703
743
  | `examples/` | Runnable demos (`npx tsx examples/basic.ts`). |
704
- | `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). |
705
745
  | `tests/unit/` | Fast Node test runner tests (`npm test`). |
706
746
  | `tests/integration/` | Opt-in live tests against real services (`npm run test:integration`). |
707
747
 
@@ -2,9 +2,16 @@
2
2
  * Backup manifest, checksum verification, and snapshot restore orchestration.
3
3
  */
4
4
  import type { CounterCell, DurableStorage, QuerySpec } from "../types/index.js";
5
+ import { CountexError } from "../utils/errors.js";
5
6
  export declare const BACKUP_MANIFEST_VERSION: 1;
6
7
  /** Logical schema marker for manifests; aligns with Mongo cell `schemaVersion` when using MongoDurable. */
7
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
+ }
8
15
  /** Document payload saved alongside an export (JSON). */
9
16
  export interface BackupManifest {
10
17
  manifestVersion: typeof BACKUP_MANIFEST_VERSION;
@@ -15,19 +22,26 @@ export interface BackupManifest {
15
22
  cellCount: number;
16
23
  /** SHA-256 of sorted canonical JSON lines (see `canonicalCellLine`). */
17
24
  contentSha256: string;
25
+ /** Sum of `count` across all cells in the export (optional, set when computed). */
26
+ countSum?: number;
18
27
  }
19
28
  export declare function canonicalCellLine(cell: CounterCell): string;
20
29
  /**
21
30
  * Stable fingerprint over an async cell stream (sorts canonical lines in memory).
22
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.
23
35
  */
24
36
  export declare function computeCellsFingerprint(cells: AsyncIterable<CounterCell>): Promise<{
25
37
  cellCount: number;
26
38
  contentSha256: string;
39
+ countSum: number;
27
40
  }>;
28
41
  export declare function createBackupManifest(filter: Pick<QuerySpec, "scope" | "counterId" | "timeframe">, fp: {
29
42
  cellCount: number;
30
43
  contentSha256: string;
44
+ countSum?: number;
31
45
  }, schemaVersion: number, createdAt?: Date): BackupManifest;
32
46
  export declare function verifyBackupAgainstManifest(manifest: BackupManifest, cells: AsyncIterable<CounterCell>): Promise<{
33
47
  ok: true;
@@ -37,13 +51,20 @@ export declare function verifyBackupAgainstManifest(manifest: BackupManifest, ce
37
51
  }>;
38
52
  /**
39
53
  * Replace cells from an export stream. Requires adapter support (`importSnapshotCells`).
40
- * `dryRun`: count cells only, no writes.
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.
41
59
  */
42
60
  export declare function restoreSnapshotCells(durable: DurableStorage, cells: AsyncIterable<CounterCell>, options?: {
61
+ /** @deprecated use `mode: "validate-only"`. */
43
62
  dryRun?: boolean;
63
+ mode?: RestoreMode;
44
64
  batchSize?: number;
45
65
  signal?: AbortSignal;
46
66
  }): Promise<{
47
67
  restored: number;
68
+ mode: RestoreMode;
48
69
  }>;
49
70
  //# sourceMappingURL=manifest.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/backup/manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGhF,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD,2GAA2G;AAC3G,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,OAAO,uBAAuB,CAAC;IAChD,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAc3D;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAYvD;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,EAC5D,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAChD,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,IAAiB,GAC3B,cAAc,CAShB;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAYvD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,EACjC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACvE,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B/B"}
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"}
@@ -3,7 +3,7 @@
3
3
  * Backup manifest, checksum verification, and snapshot restore orchestration.
4
4
  */
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.COUNTEX_CELL_SCHEMA_VERSION = exports.BACKUP_MANIFEST_VERSION = void 0;
6
+ exports.NotImplementedError = exports.COUNTEX_CELL_SCHEMA_VERSION = exports.BACKUP_MANIFEST_VERSION = void 0;
7
7
  exports.canonicalCellLine = canonicalCellLine;
8
8
  exports.computeCellsFingerprint = computeCellsFingerprint;
9
9
  exports.createBackupManifest = createBackupManifest;
@@ -14,6 +14,14 @@ const errors_js_1 = require("../utils/errors.js");
14
14
  exports.BACKUP_MANIFEST_VERSION = 1;
15
15
  /** Logical schema marker for manifests; aligns with Mongo cell `schemaVersion` when using MongoDurable. */
16
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;
17
25
  function canonicalCellLine(cell) {
18
26
  return JSON.stringify({
19
27
  scopeId: cell.scopeId,
@@ -32,11 +40,16 @@ function canonicalCellLine(cell) {
32
40
  /**
33
41
  * Stable fingerprint over an async cell stream (sorts canonical lines in memory).
34
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.
35
46
  */
36
47
  async function computeCellsFingerprint(cells) {
37
48
  const lines = [];
49
+ let countSum = 0;
38
50
  for await (const c of cells) {
39
51
  lines.push(canonicalCellLine(c));
52
+ countSum += c.count;
40
53
  }
41
54
  lines.sort();
42
55
  const h = (0, node_crypto_1.createHash)("sha256");
@@ -44,7 +57,7 @@ async function computeCellsFingerprint(cells) {
44
57
  h.update(line);
45
58
  h.update("\n");
46
59
  }
47
- return { cellCount: lines.length, contentSha256: h.digest("hex") };
60
+ return { cellCount: lines.length, contentSha256: h.digest("hex"), countSum };
48
61
  }
49
62
  function createBackupManifest(filter, fp, schemaVersion, createdAt = new Date()) {
50
63
  return {
@@ -54,6 +67,7 @@ function createBackupManifest(filter, fp, schemaVersion, createdAt = new Date())
54
67
  filter,
55
68
  cellCount: fp.cellCount,
56
69
  contentSha256: fp.contentSha256,
70
+ ...(fp.countSum !== undefined ? { countSum: fp.countSum } : {}),
57
71
  };
58
72
  }
59
73
  async function verifyBackupAgainstManifest(manifest, cells) {
@@ -67,14 +81,28 @@ async function verifyBackupAgainstManifest(manifest, cells) {
67
81
  if (fp.contentSha256 !== manifest.contentSha256) {
68
82
  return { ok: false, detail: "contentSha256 mismatch" };
69
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
+ }
70
90
  return { ok: true };
71
91
  }
72
92
  /**
73
93
  * Replace cells from an export stream. Requires adapter support (`importSnapshotCells`).
74
- * `dryRun`: count cells only, no writes.
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.
75
99
  */
76
100
  async function restoreSnapshotCells(durable, cells, options) {
77
- if (!durable.importSnapshotCells) {
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) {
78
106
  throw new errors_js_1.StorageError("Durable adapter does not implement importSnapshotCells", {});
79
107
  }
80
108
  const batchSize = options?.batchSize ?? 500;
@@ -83,7 +111,7 @@ async function restoreSnapshotCells(durable, cells, options) {
83
111
  const flush = async () => {
84
112
  if (batch.length === 0)
85
113
  return;
86
- if (!options?.dryRun) {
114
+ if (mode === "replace-window") {
87
115
  await durable.importSnapshotCells(batch, { signal: options?.signal });
88
116
  }
89
117
  restored += batch.length;
@@ -98,6 +126,6 @@ async function restoreSnapshotCells(durable, cells, options) {
98
126
  await flush();
99
127
  }
100
128
  await flush();
101
- return { restored };
129
+ return { restored, mode };
102
130
  }
103
131
  //# sourceMappingURL=manifest.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/backup/manifest.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAuBH,8CAcC;AAMD,0DAcC;AAED,oDAcC;AAED,kEAeC;AAMD,oDAgCC;AA9HD,6CAAyC;AAEzC,kDAAkD;AAErC,QAAA,uBAAuB,GAAG,CAAU,CAAC;AAElD,2GAA2G;AAC9F,QAAA,2BAA2B,GAAG,CAAC,CAAC;AAc7C,SAAgB,iBAAiB,CAAC,IAAiB;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,uBAAuB,CAC3C,KAAiC;IAEjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,KAAK,CAAC,IAAI,EAAE,CAAC;IACb,MAAM,CAAC,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,SAAgB,oBAAoB,CAClC,MAA4D,EAC5D,EAAgD,EAChD,aAAqB,EACrB,YAAkB,IAAI,IAAI,EAAE;IAE5B,OAAO;QACL,eAAe,EAAE,+BAAuB;QACxC,aAAa;QACb,YAAY,EAAE,SAAS,CAAC,WAAW,EAAE;QACrC,MAAM;QACN,SAAS,EAAE,EAAE,CAAC,SAAS;QACvB,aAAa,EAAE,EAAE,CAAC,aAAa;KAChC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,2BAA2B,CAC/C,QAAwB,EACxB,KAAiC;IAEjC,MAAM,EAAE,GAAG,MAAM,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,EAAE,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS,EAAE,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,mCAAmC,EAAE,CAAC,SAAS,sBAAsB,QAAQ,CAAC,SAAS,EAAE;SAClG,CAAC;IACJ,CAAC;IACD,IAAI,EAAE,CAAC,aAAa,KAAK,QAAQ,CAAC,aAAa,EAAE,CAAC;QAChD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,oBAAoB,CACxC,OAAuB,EACvB,KAAiC,EACjC,OAAwE;IAExE,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC;QACjC,MAAM,IAAI,wBAAY,CAAC,wDAAwD,EAAE,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,GAAG,CAAC;IAC5C,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAAkB,EAAE,CAAC;IAE9B,MAAM,KAAK,GAAG,KAAK,IAAI,EAAE;QACvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACrB,MAAM,OAAO,CAAC,mBAAoB,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC;QACzB,KAAK,GAAG,EAAE,CAAC;IACb,CAAC,CAAC;IAEF,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QAC5B,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAC7B,MAAM,IAAI,wBAAY,CAAC,8BAA8B,EAAE,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACd,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS;YAAE,MAAM,KAAK,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,KAAK,EAAE,CAAC;IAEd,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC"}
1
+ {"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/backup/manifest.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAoCH,8CAcC;AASD,0DAgBC;AAED,oDAeC;AAED,kEAqBC;AAUD,oDA8CC;AAzKD,6CAAyC;AAEzC,kDAAgE;AAEnD,QAAA,uBAAuB,GAAG,CAAU,CAAC;AAElD,2GAA2G;AAC9F,QAAA,2BAA2B,GAAG,CAAC,CAAC;AAK7C,yDAAyD;AACzD,MAAa,mBAAoB,SAAQ,wBAAY;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AALD,kDAKC;AAgBD,SAAgB,iBAAiB,CAAC,IAAiB;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,uBAAuB,CAC3C,KAAiC;IAEjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,IAAI,EAAE,CAAC;IACb,MAAM,CAAC,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC/E,CAAC;AAED,SAAgB,oBAAoB,CAClC,MAA4D,EAC5D,EAAmE,EACnE,aAAqB,EACrB,YAAkB,IAAI,IAAI,EAAE;IAE5B,OAAO;QACL,eAAe,EAAE,+BAAuB;QACxC,aAAa;QACb,YAAY,EAAE,SAAS,CAAC,WAAW,EAAE;QACrC,MAAM;QACN,SAAS,EAAE,EAAE,CAAC,SAAS;QACvB,aAAa,EAAE,EAAE,CAAC,aAAa;QAC/B,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,2BAA2B,CAC/C,QAAwB,EACxB,KAAiC;IAEjC,MAAM,EAAE,GAAG,MAAM,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,EAAE,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS,EAAE,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,mCAAmC,EAAE,CAAC,SAAS,sBAAsB,QAAQ,CAAC,SAAS,EAAE;SAClG,CAAC;IACJ,CAAC;IACD,IAAI,EAAE,CAAC,aAAa,KAAK,QAAQ,CAAC,aAAa,EAAE,CAAC;QAChD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACzE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,kCAAkC,EAAE,CAAC,QAAQ,sBAAsB,QAAQ,CAAC,QAAQ,EAAE;SAC/F,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,oBAAoB,CACxC,OAAuB,EACvB,KAAiC,EACjC,OAMC;IAED,MAAM,IAAI,GAAgB,OAAO,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAElG,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;QAC5B,MAAM,IAAI,mBAAmB,CAC3B,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,gBAAgB,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC;QAC9D,MAAM,IAAI,wBAAY,CAAC,wDAAwD,EAAE,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,GAAG,CAAC;IAC5C,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAAkB,EAAE,CAAC;IAE9B,MAAM,KAAK,GAAG,KAAK,IAAI,EAAE;QACvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;YAC9B,MAAM,OAAO,CAAC,mBAAoB,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC;QACzB,KAAK,GAAG,EAAE,CAAC;IACb,CAAC,CAAC;IAEF,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QAC5B,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAC7B,MAAM,IAAI,wBAAY,CAAC,8BAA8B,EAAE,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACd,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS;YAAE,MAAM,KAAK,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,KAAK,EAAE,CAAC;IAEd,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}
@@ -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, MapPreviewResult, 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;
@@ -52,11 +55,73 @@ export declare class Countex {
52
55
  */
53
56
  flush(): Promise<void>;
54
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;
55
66
  diag(): {
56
67
  bufferCells: number;
57
68
  bufferEvents: number;
58
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
+ };
59
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;
60
125
  /** Factory matching the spec's public API. */
61
126
  export declare function createCountex(config: CountexConfig): Countex;
62
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,EAIb,gBAAgB,EAGhB,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;IAkKnD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,EAAE;IAwE7E;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAkE5B;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2DhB,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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"}
@@ -18,6 +18,7 @@
18
18
  */
19
19
  Object.defineProperty(exports, "__esModule", { value: true });
20
20
  exports.Countex = void 0;
21
+ exports.parseRetentionDuration = parseRetentionDuration;
21
22
  exports.createCountex = createCountex;
22
23
  const node_events_1 = require("node:events");
23
24
  const extraction_js_1 = require("./extraction.js");
@@ -28,6 +29,8 @@ const timeframe_js_1 = require("./timeframe.js");
28
29
  const hash_js_1 = require("../utils/hash.js");
29
30
  const logger_js_1 = require("../utils/logger.js");
30
31
  const planner_js_1 = require("../query/planner.js");
32
+ const export_js_1 = require("../backup/export.js");
33
+ const manifest_js_1 = require("../backup/manifest.js");
31
34
  class Countex {
32
35
  cfg;
33
36
  buffer = new buffer_js_1.DeltaBuffer();
@@ -42,6 +45,7 @@ class Countex {
42
45
  const mapsByCounterId = new Map();
43
46
  for (const m of config.maps)
44
47
  mapsByCounterId.set(m.counterId, m);
48
+ const resolvedRedisRetentionSeconds = resolveRetentionSeconds(config.retention?.redis ?? config.cachePolicy?.hotTimeframes);
45
49
  this.cfg = {
46
50
  maps: mapsByCounterId,
47
51
  durable: config.durable,
@@ -53,12 +57,20 @@ class Countex {
53
57
  flushOnShutdown: config.flush?.flushOnShutdown ?? true,
54
58
  onOverflow: config.flush?.onOverflow ?? "block",
55
59
  },
60
+ retention: config.retention,
61
+ resolvedRedisRetentionSeconds,
56
62
  defaultIdempotency: config.idempotency,
57
63
  defaultCardinality: config.cardinality,
58
64
  now: config.now ?? (() => new Date()),
59
65
  };
60
66
  this.cardinality = new cardinality_js_1.CardinalityGuard(config.cardinality);
61
67
  this.logger = (0, logger_js_1.resolveLogger)(config.logger);
68
+ // Forward unified retention to the cache adapter (engine policy wins).
69
+ if (this.cfg.cache?.setRetentionPolicy &&
70
+ resolvedRedisRetentionSeconds &&
71
+ Object.keys(resolvedRedisRetentionSeconds).length > 0) {
72
+ this.cfg.cache.setRetentionPolicy(resolvedRedisRetentionSeconds);
73
+ }
62
74
  if (this.cfg.flush.everyMs > 0) {
63
75
  this.flushTimer = setInterval(() => {
64
76
  this.flush().catch((err) => {
@@ -424,12 +436,27 @@ class Countex {
424
436
  }
425
437
  // ── Query ─────────────────────────────────────────────────────────────────
426
438
  async query(spec) {
427
- const counterMap = this.cfg.maps.get(spec.counterId);
428
- const plannerCtx = counterMap
429
- ? { measureAggByName: (0, planner_js_1.buildMeasureAggIndex)(counterMap) }
430
- : undefined;
439
+ const plannerCtx = this.buildPlannerCtx(spec);
431
440
  return (0, planner_js_1.executeQuery)(spec, this.cfg.durable, this.cfg.cache, plannerCtx);
432
441
  }
442
+ /**
443
+ * Explain a query without executing it. Returns a {@link QueryPlan} with
444
+ * bucket expansion, cache eligibility, predicted durable fallback, and a
445
+ * cost classification. Probes per-bucket cache coverage when the cache
446
+ * adapter supports `probeBucketCoverage`.
447
+ */
448
+ async explainQuery(spec) {
449
+ const plannerCtx = this.buildPlannerCtx(spec);
450
+ return (0, planner_js_1.planQuery)(spec, this.cfg.durable, this.cfg.cache, plannerCtx);
451
+ }
452
+ buildPlannerCtx(spec) {
453
+ const counterMap = this.cfg.maps.get(spec.counterId);
454
+ if (!counterMap)
455
+ return undefined;
456
+ return {
457
+ measureAggByName: (0, planner_js_1.buildMeasureAggIndex)(counterMap),
458
+ };
459
+ }
433
460
  // ── Diagnostics ───────────────────────────────────────────────────────────
434
461
  diag() {
435
462
  return {
@@ -437,6 +464,28 @@ class Countex {
437
464
  bufferEvents: this.buffer.eventCount(),
438
465
  };
439
466
  }
467
+ // ── Backup namespace ──────────────────────────────────────────────────────
468
+ /**
469
+ * Backup helpers bound to this Countex instance's durable + cache. Mirrors
470
+ * the free-function exports (`exportCells`, `verifyBackupAgainstManifest`,
471
+ * `restoreSnapshotCells`, `rebuildCache`) for ergonomic use:
472
+ *
473
+ * await countex.backup.verify(manifest);
474
+ * await countex.backup.restore(stream, { mode: "validate-only" });
475
+ */
476
+ backup = {
477
+ export: (filter, signal) => (0, export_js_1.exportCells)(this.cfg.durable, filter, signal),
478
+ fingerprint: (filter, signal) => (0, manifest_js_1.computeCellsFingerprint)((0, export_js_1.exportCells)(this.cfg.durable, filter, signal)),
479
+ createManifest: (filter, fp, schemaVersion = manifest_js_1.COUNTEX_CELL_SCHEMA_VERSION) => (0, manifest_js_1.createBackupManifest)(filter, fp, schemaVersion),
480
+ verify: (manifest, signal) => (0, manifest_js_1.verifyBackupAgainstManifest)(manifest, (0, export_js_1.exportCells)(this.cfg.durable, manifest.filter, signal)),
481
+ restore: (cells, options) => (0, manifest_js_1.restoreSnapshotCells)(this.cfg.durable, cells, options),
482
+ rebuildCache: (filter, options) => {
483
+ if (!this.cfg.cache) {
484
+ return Promise.resolve({ cellsWarmed: 0 });
485
+ }
486
+ return (0, export_js_1.rebuildCache)(this.cfg.durable, this.cfg.cache, filter, options);
487
+ },
488
+ };
440
489
  }
441
490
  exports.Countex = Countex;
442
491
  function measureScalesFromMap(map) {
@@ -447,6 +496,66 @@ function measureScalesFromMap(map) {
447
496
  }
448
497
  return Object.keys(out).length ? out : undefined;
449
498
  }
499
+ /**
500
+ * Parse a {@link RetentionDuration} into seconds. Accepts numbers (already
501
+ * seconds), `"forever"` (returns `Infinity`), or `<n><unit>` strings:
502
+ * `s` second (default unit when only digits are given)
503
+ * `m` minute
504
+ * `h` hour
505
+ * `d` day
506
+ * `w` week
507
+ * `mo` month (30d)
508
+ * `q` quarter (90d)
509
+ * `y` year (365d)
510
+ */
511
+ function parseRetentionDuration(d) {
512
+ if (typeof d === "number") {
513
+ if (!Number.isFinite(d) || d < 0)
514
+ throw new Error(`invalid retention duration: ${d}`);
515
+ return d;
516
+ }
517
+ const s = d.trim().toLowerCase();
518
+ if (s === "forever")
519
+ return Number.POSITIVE_INFINITY;
520
+ const m = s.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d|w|mo|q|y)?$/);
521
+ if (!m)
522
+ throw new Error(`invalid retention duration: ${d}`);
523
+ const n = Number(m[1]);
524
+ const unit = m[2] ?? "s";
525
+ switch (unit) {
526
+ case "s":
527
+ return n;
528
+ case "m":
529
+ return n * 60;
530
+ case "h":
531
+ return n * 3600;
532
+ case "d":
533
+ return n * 86_400;
534
+ case "w":
535
+ return n * 604_800;
536
+ case "mo":
537
+ return n * 30 * 86_400;
538
+ case "q":
539
+ return n * 90 * 86_400;
540
+ case "y":
541
+ return n * 365 * 86_400;
542
+ default:
543
+ throw new Error(`invalid retention unit: ${unit}`);
544
+ }
545
+ }
546
+ function resolveRetentionSeconds(policy) {
547
+ if (!policy)
548
+ return undefined;
549
+ const out = {};
550
+ for (const [tf, d] of Object.entries(policy)) {
551
+ if (d === undefined)
552
+ continue;
553
+ const sec = parseRetentionDuration(d);
554
+ // Adapters interpret `0` as "no TTL". Map Infinity (`forever`) to 0.
555
+ out[tf] = Number.isFinite(sec) ? Math.floor(sec) : 0;
556
+ }
557
+ return out;
558
+ }
450
559
  /** Factory matching the spec's public API. */
451
560
  function createCountex(config) {
452
561
  return new Countex(config);