@x12i/countex 1.5.0 → 1.6.5
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.
- package/README.md +138 -21
- package/dist/backup/manifest.d.ts +22 -1
- package/dist/backup/manifest.d.ts.map +1 -1
- package/dist/backup/manifest.js +34 -6
- package/dist/backup/manifest.js.map +1 -1
- package/dist/core/countex.d.ts +66 -1
- package/dist/core/countex.d.ts.map +1 -1
- package/dist/core/countex.js +113 -4
- package/dist/core/countex.js.map +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/query/planner.d.ts +15 -1
- package/dist/query/planner.d.ts.map +1 -1
- package/dist/query/planner.js +136 -1
- package/dist/query/planner.js.map +1 -1
- package/dist/storage/coverage.d.ts +13 -0
- package/dist/storage/coverage.d.ts.map +1 -0
- package/dist/storage/coverage.js +37 -0
- package/dist/storage/coverage.js.map +1 -0
- package/dist/storage/memory.d.ts +20 -5
- package/dist/storage/memory.d.ts.map +1 -1
- package/dist/storage/memory.js +127 -3
- package/dist/storage/memory.js.map +1 -1
- package/dist/storage/redis.d.ts +36 -11
- package/dist/storage/redis.d.ts.map +1 -1
- package/dist/storage/redis.js +189 -41
- package/dist/storage/redis.js.map +1 -1
- package/dist/types/index.d.ts +114 -7
- package/dist/types/index.d.ts.map +1 -1
- package/docs/DEPLOYMENT.md +87 -3
- package/docs/guides/adapter-redis.md +40 -4
- package/docs/guides/backup-export.md +84 -32
- package/docs/guides/counter-maps.md +8 -0
- package/docs/guides/preview.md +92 -0
- package/docs/guides/querying.md +30 -0
- package/docs/internals/internal-storage-mongo.md +24 -4
- package/docs/internals/internal-storage-redis.md +41 -9
- package/package.json +14 -2
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,17 +301,28 @@ 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)
|
|
302
311
|
|
|
312
|
+
Do **not** derive Mongo database names directly from raw tenant strings (length, `$`, `/`, and Unicode can break DB naming rules or leak structure). Hash or normalize first:
|
|
313
|
+
|
|
303
314
|
```ts
|
|
315
|
+
import { createHash } from "node:crypto";
|
|
304
316
|
import { MongoClient } from "mongodb";
|
|
305
317
|
import IORedis from "ioredis";
|
|
306
318
|
import { createCountex } from "@x12i/countex";
|
|
307
319
|
import { MongoDurable } from "@x12i/countex/adapters/mongo";
|
|
308
320
|
import { RedisCache } from "@x12i/countex/adapters/redis";
|
|
309
321
|
|
|
322
|
+
function hashScopeId(scope: string): string {
|
|
323
|
+
return createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 16);
|
|
324
|
+
}
|
|
325
|
+
|
|
310
326
|
const mongo = new MongoClient(process.env.MONGO_URI!);
|
|
311
327
|
await mongo.connect();
|
|
312
328
|
const redis = new IORedis(process.env.REDIS_URL!);
|
|
@@ -315,13 +331,30 @@ const countex = createCountex({
|
|
|
315
331
|
maps: [accessMap],
|
|
316
332
|
durable: new MongoDurable({
|
|
317
333
|
client: mongo,
|
|
318
|
-
dbResolver: ({ scope }) => `countex_${scope}`,
|
|
334
|
+
dbResolver: ({ scope }) => `countex_${hashScopeId(scope)}`,
|
|
319
335
|
}),
|
|
320
336
|
cache: new RedisCache({
|
|
321
337
|
client: redis,
|
|
322
338
|
keyPrefix: "countex",
|
|
323
|
-
|
|
339
|
+
// Optional adapter default TTLs; when `retention.redis` is set below, the
|
|
340
|
+
// engine resolves those strings to seconds and forwards them via
|
|
341
|
+
// `setRetentionPolicy`, overriding adapter defaults for matching timeframes.
|
|
324
342
|
}),
|
|
343
|
+
retention: {
|
|
344
|
+
redis: {
|
|
345
|
+
minute: "48h",
|
|
346
|
+
hour: "14d",
|
|
347
|
+
day: "92d",
|
|
348
|
+
week: "52w",
|
|
349
|
+
month: "24mo",
|
|
350
|
+
quarter: "24mo",
|
|
351
|
+
year: "forever",
|
|
352
|
+
all: "forever",
|
|
353
|
+
},
|
|
354
|
+
// Durable TTL / prune is not enforced by the engine — operators apply Mongo
|
|
355
|
+
// TTL indexes or scheduled jobs. `retention.mongo` is optional per-timeframe
|
|
356
|
+
// documentation (same duration grammar as redis); see types / DEPLOYMENT.
|
|
357
|
+
},
|
|
325
358
|
flush: {
|
|
326
359
|
everyMs: 60_000,
|
|
327
360
|
maxBufferedCells: 100_000,
|
|
@@ -451,7 +484,9 @@ Indexes (created automatically on first write):
|
|
|
451
484
|
- `by_subject` — for subject filters
|
|
452
485
|
- `by_metric` — for metric filters
|
|
453
486
|
|
|
454
|
-
`countex_dict` — the per-scope subject/metric dictionary, with monotonic ids allocated via `countex_seq`.
|
|
487
|
+
`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).
|
|
488
|
+
|
|
489
|
+
`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
490
|
|
|
456
491
|
### Redis layout
|
|
457
492
|
|
|
@@ -460,12 +495,19 @@ countex:{scope}:{counterId}:{timeframeType}:{timeframeKey} → HASH
|
|
|
460
495
|
field = "{subjectType}|{subjectId}|{metricId}|{dimensionsHash}"
|
|
461
496
|
value = count
|
|
462
497
|
|
|
498
|
+
countex:{scope}:{counterId}:{timeframeType}:{timeframeKey}:cov → HASH (coverage meta)
|
|
499
|
+
status = complete | partial | rebuilding (see BucketCoverageMeta; reads may infer missing)
|
|
500
|
+
lastWarmAt = epoch ms (string)
|
|
501
|
+
mapVersion = optional opaque integer (string)
|
|
502
|
+
schemaVersion = cache layout version (string)
|
|
503
|
+
cellCount = cells last warmed into this bucket (string, when known)
|
|
504
|
+
|
|
463
505
|
countex:{scope}:{counterId}:...:{timeframeKey}:meta:{field} → JSON of dimensions
|
|
464
506
|
|
|
465
507
|
countex:{scope}:dedupe:{eventId} → "1" with TTL
|
|
466
508
|
```
|
|
467
509
|
|
|
468
|
-
One hash per `(scope, counterId, bucket)` keeps Redis key counts small and per-bucket reads to a single `HGETALL`.
|
|
510
|
+
One hash per `(scope, counterId, bucket)` keeps Redis key counts small and per-bucket reads to a single `HGETALL`. **Do not** treat “cell hash is non-empty” as full cache coverage — use the **`:cov`** hash (`status === complete` after `warm`, `partial` after incremental `applyDeltas`, `rebuilding` during cache rebuild). See [`docs/guides/adapter-redis.md`](docs/guides/adapter-redis.md) and [`docs/internals/internal-storage-redis.md`](docs/internals/internal-storage-redis.md).
|
|
469
511
|
|
|
470
512
|
---
|
|
471
513
|
|
|
@@ -499,6 +541,18 @@ const result = await countex.query({
|
|
|
499
541
|
});
|
|
500
542
|
```
|
|
501
543
|
|
|
544
|
+
`explainQuery` runs the planner **without** materializing cells. It returns a **`QueryPlan`**: expanded `bucketsRequested`, `cacheEligible` / `cacheReason`, predicted `durableFallbackPredicted`, `cacheBucketsExpectedHit` (when the cache adapter supports `probeBucketCoverage`), heuristic `plannedCellsEstimate`, and cost hints (`expensive`, `groupByCost`). Use it to preflight dashboards and expensive `groupBy` shapes.
|
|
545
|
+
|
|
546
|
+
```ts
|
|
547
|
+
const plan = await countex.explainQuery({
|
|
548
|
+
scope: "org_123",
|
|
549
|
+
counterId: "access_by_subject_metric",
|
|
550
|
+
timeframe: { type: "day", from: "2026-05-01", to: "2026-05-08" },
|
|
551
|
+
groupBy: ["subject", "metric"],
|
|
552
|
+
format: "table",
|
|
553
|
+
});
|
|
554
|
+
```
|
|
555
|
+
|
|
502
556
|
Result:
|
|
503
557
|
|
|
504
558
|
```ts
|
|
@@ -556,7 +610,7 @@ const topCostDrivers = await insights.topPercent({
|
|
|
556
610
|
});
|
|
557
611
|
```
|
|
558
612
|
|
|
559
|
-
Further reading: [docs/
|
|
613
|
+
Further reading: [`docs/guides/insights-overview.md`](docs/guides/insights-overview.md), [`docs/guides/insights-ranking.md`](docs/guides/insights-ranking.md), [`docs/guides/insights-comparison-and-trends.md`](docs/guides/insights-comparison-and-trends.md), [`docs/guides/insights-anomalies-and-rules.md`](docs/guides/insights-anomalies-and-rules.md), [`docs/guides/insights-forecasting-and-budget.md`](docs/guides/insights-forecasting-and-budget.md), [`docs/guides/insights-advisors-and-optimization.md`](docs/guides/insights-advisors-and-optimization.md). Deeper topic notes also live under `docs/INSIGHTS*.md` for maintainers.
|
|
560
614
|
|
|
561
615
|
CLI (after `npm run build` / install):
|
|
562
616
|
|
|
@@ -643,28 +697,86 @@ All writes are atomic per cell:
|
|
|
643
697
|
|
|
644
698
|
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
699
|
|
|
646
|
-
### Backup / rebuild
|
|
700
|
+
### Backup / verify / restore / rebuild
|
|
647
701
|
|
|
648
|
-
|
|
649
|
-
import { exportCells, rebuildCache } from "@x12i/countex";
|
|
702
|
+
Top-level free functions and a `countex.backup` namespace bound to your engine:
|
|
650
703
|
|
|
651
|
-
|
|
652
|
-
|
|
704
|
+
```ts
|
|
705
|
+
import {
|
|
706
|
+
exportCells,
|
|
707
|
+
computeCellsFingerprint,
|
|
708
|
+
createBackupManifest,
|
|
709
|
+
verifyBackupAgainstManifest,
|
|
710
|
+
restoreSnapshotCells,
|
|
711
|
+
rebuildCache,
|
|
712
|
+
COUNTEX_CELL_SCHEMA_VERSION,
|
|
713
|
+
} from "@x12i/countex";
|
|
714
|
+
|
|
715
|
+
const filter = {
|
|
653
716
|
scope: "org_123",
|
|
654
717
|
counterId: "access_by_subject_metric",
|
|
655
718
|
timeframe: { type: "day", from: "2026-02-01", to: "2026-05-08" },
|
|
656
|
-
}
|
|
719
|
+
};
|
|
720
|
+
|
|
721
|
+
// Stream all cells in a window — bounded async iteration.
|
|
722
|
+
for await (const cell of exportCells(durable, filter)) {
|
|
657
723
|
// ndjson, S3, whatever you want
|
|
658
724
|
}
|
|
659
725
|
|
|
660
|
-
//
|
|
661
|
-
await
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
726
|
+
// Fingerprint + manifest for cold-storage verification.
|
|
727
|
+
const fp = await countex.backup.fingerprint(filter); // { cellCount, contentSha256, countSum }
|
|
728
|
+
const manifest = countex.backup.createManifest(filter, fp); // { manifestVersion, schemaVersion, filter, … }
|
|
729
|
+
|
|
730
|
+
// Verify a manifest against the live durable adapter.
|
|
731
|
+
const ok = await countex.backup.verify(manifest);
|
|
732
|
+
if (!ok.ok) throw new Error(ok.detail);
|
|
733
|
+
|
|
734
|
+
// Restore. Modes: "validate-only" | "replace-window" (default) | "merge-deltas" (reserved).
|
|
735
|
+
const { restored, mode } = await countex.backup.restore(
|
|
736
|
+
countex.backup.export(filter),
|
|
737
|
+
{ mode: "replace-window" },
|
|
738
|
+
);
|
|
739
|
+
|
|
740
|
+
// Re-warm cache from durable. Each warmed bucket's :cov flips to status=complete.
|
|
741
|
+
await countex.backup.rebuildCache(filter);
|
|
742
|
+
```
|
|
743
|
+
|
|
744
|
+
See [`docs/guides/backup-export.md`](docs/guides/backup-export.md) for the full recipe and manifest layout.
|
|
745
|
+
|
|
746
|
+
---
|
|
747
|
+
|
|
748
|
+
## Docker integration testing
|
|
749
|
+
|
|
750
|
+
Countex ships a Docker-based stack (MongoDB, Redis, MinIO) and integration tests under `tests/integration/docker/` that exercise real adapters: dictionary allocation under concurrency, multi-worker ingestion, Redis cache coverage and durable fallback, `rebuildCache`, simulation fingerprints against a memory reference, and backup / manifest / verify / restore to S3-compatible storage (via the AWS SDK in devDependencies).
|
|
751
|
+
|
|
752
|
+
**One-shot local run** (starts services, runs tests with default localhost URLs, tears volumes down):
|
|
753
|
+
|
|
754
|
+
```bash
|
|
755
|
+
npm run test:e2e
|
|
756
|
+
```
|
|
757
|
+
|
|
758
|
+
**Host-runner** (services in Docker, tests on the host):
|
|
759
|
+
|
|
760
|
+
```bash
|
|
761
|
+
npm run docker:up
|
|
762
|
+
export COUNTEX_MONGO_URI='mongodb://countex:countex@127.0.0.1:27017/admin'
|
|
763
|
+
export COUNTEX_REDIS_URL='redis://127.0.0.1:6379'
|
|
764
|
+
export COUNTEX_S3_ENDPOINT='http://127.0.0.1:9000'
|
|
765
|
+
export COUNTEX_S3_REGION='us-east-1'
|
|
766
|
+
export COUNTEX_S3_ACCESS_KEY_ID='countex'
|
|
767
|
+
export COUNTEX_S3_SECRET_ACCESS_KEY='countex-password'
|
|
768
|
+
export COUNTEX_S3_BUCKET='countex-backups'
|
|
769
|
+
export COUNTEX_INTEGRATION=1
|
|
770
|
+
npm run test:integration
|
|
771
|
+
npm run docker:down
|
|
666
772
|
```
|
|
667
773
|
|
|
774
|
+
Optional tuning: `COUNTEX_TEST_PROFILE`, `COUNTEX_TEST_EVENTS`, `COUNTEX_TEST_WORKERS`. Stress-style full pipeline (larger simulation + S3 round-trip): set `COUNTEX_TEST_FULL=1` (requires S3 env as above).
|
|
775
|
+
|
|
776
|
+
**Container-runner** (CI parity): `npm run test:integration:docker` builds `docker/test-runner.Dockerfile` and runs `npm run test:integration:exec` with service hostnames injected by Compose.
|
|
777
|
+
|
|
778
|
+
Reports are written to `artifacts/integration/report.json` and `artifacts/integration/report.md` after `npm run test:integration`.
|
|
779
|
+
|
|
668
780
|
---
|
|
669
781
|
|
|
670
782
|
## Errors
|
|
@@ -682,6 +794,8 @@ All errors thrown by Countex extend `CountexError`:
|
|
|
682
794
|
|
|
683
795
|
## Versioning & scope
|
|
684
796
|
|
|
797
|
+
> **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.
|
|
798
|
+
|
|
685
799
|
`v0.x` is for stabilizing the public API. Once it's hardened:
|
|
686
800
|
|
|
687
801
|
- exact unique counts (HLL / sets) are an opt-in extension, not core
|
|
@@ -696,12 +810,15 @@ All errors thrown by Countex extend `CountexError`:
|
|
|
696
810
|
|------|------|
|
|
697
811
|
| `src/index.ts` | Public exports (`createCountex`, types, errors). |
|
|
698
812
|
| `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). |
|
|
813
|
+
| `src/query/` | Query planner (`planQuery` + `executeQuery`) and result formatting. |
|
|
814
|
+
| `src/storage/` | Adapters: `memory` (in-process), `mongo` (durable), `redis` (cache); shared coverage helpers. |
|
|
701
815
|
| `src/utils/` | JSONPath subset, hashing, logging. |
|
|
702
|
-
| `src/backup/` | Export
|
|
816
|
+
| `src/backup/` | Export, fingerprint, manifest, verify, restore, cache rebuild helpers. |
|
|
817
|
+
| `src/simulation/` | Simulation engine, profiles, expected aggregates, resource reports. |
|
|
818
|
+
| `src/insights/` | Ranking, comparison, anomaly detection, advisors, recommendations. |
|
|
819
|
+
| `src/cli.ts` | CLI commands for simulation, insights, export, and operational helpers. |
|
|
703
820
|
| `examples/` | Runnable demos (`npx tsx examples/basic.ts`). |
|
|
704
|
-
| `docs/` | Deployment guide and
|
|
821
|
+
| `docs/` | Deployment guide, tutorial, guides, internals, and use cases (published in the npm package). |
|
|
705
822
|
| `tests/unit/` | Fast Node test runner tests (`npm test`). |
|
|
706
823
|
| `tests/integration/` | Opt-in live tests against real services (`npm run test:integration`). |
|
|
707
824
|
|
|
@@ -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
|
-
*
|
|
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;
|
|
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"}
|
package/dist/backup/manifest.js
CHANGED
|
@@ -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
|
-
*
|
|
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
|
-
|
|
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 (
|
|
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;;;
|
|
1
|
+
{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/backup/manifest.ts"],"names":[],"mappings":"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"}
|
package/dist/core/countex.d.ts
CHANGED
|
@@ -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,
|
|
1
|
+
{"version":3,"file":"countex.d.ts","sourceRoot":"","sources":["../../src/core/countex.ts"],"names":[],"mappings":"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"}
|