npm - @jeffjassky/telemetry - Versions diffs - 0.5.0 → 0.6.1 - Mend

@jeffjassky/telemetry 0.5.0 → 0.6.1

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 (13) hide show

package/dist/index.cjs +172 -42
package/dist/index.cjs.map +1 -1
package/dist/index.js +172 -43
package/dist/index.js.map +1 -1
package/dist/mcp.cjs.map +1 -1
package/dist/mcp.js.map +1 -1
package/dist/ui/_assets/{index-kvwB9_3A.js → index-BVZYi-43.js} +8 -8
package/dist/ui/_assets/index-BVZYi-43.js.map +1 -0
package/dist/ui/index.html +1 -1
package/package.json +1 -1
package/types/index.d.ts +75 -1
package/types/test-d.ts +18 -0
package/dist/ui/_assets/index-kvwB9_3A.js.map +0 -1

package/dist/ui/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Telemetry</title>
     <!--telemetry-config-->
-    <script type="module" crossorigin src="./_assets/index-kvwB9_3A.js"></script>
+    <script type="module" crossorigin src="./_assets/index-BVZYi-43.js"></script>
     <link rel="stylesheet" crossorigin href="./_assets/index-COswHpSX.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jeffjassky/telemetry",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Unified telemetry — product events, errors, traces, state transitions, and billable usage in one Mongo envelope, with typed SDKs and a mountable dashboard.",
   "license": "MIT",
   "author": "Jeff Jassky <jeff@jeffjassky.com>",

package/types/index.d.ts CHANGED Viewed

@@ -696,6 +696,59 @@ export interface ForgetResult {
   views: number;
 }
+export interface RelinkOptions {
+  /**
+   * Restrict to these event names. Default: every stored record, whatever its
+   * name. A name the registry does not declare THROWS, before any I/O — a typo
+   * that silently relinks nothing looks exactly like a clean run.
+   */
+  names?: string[];
+  /** only records at/after this instant (`occurredAt`) */
+  since?: Date;
+  /**
+   * Stop after this many records are EXAMINED — not linked. A budget for the
+   * scan, so a huge collection can be probed cheaply. Default unbounded.
+   */
+  limit?: number;
+  /**
+   * Report what would change and write NOTHING. **Defaults to `true`**, because
+   * this rewrites historical aggregates and the short call has to be the safe
+   * one. A dry run still asks the host's linker, so the linking counters move;
+   * nothing on disk does.
+   */
+  dryRun?: boolean;
+  /** records fetched per batch, and the `onProgress` cadence. Default 500. */
+  batchSize?: number;
+  /** cumulative counts after each batch, for progress output. Guarded: a
+   *  printer that throws does not kill the backfill. */
+  onProgress?: (r: RelinkResult) => void;
+}
+export interface RelinkResult {
+  /** rows read */
+  examined: number;
+  /** rows that gained at least one subject */
+  linked: number;
+  /** subjects added in total — two links on one row count twice */
+  subjects: number;
+  /** rollup documents written, or under `dryRun` that would have been */
+  rollups: number;
+  /** rows where the linker answered `[]`. On a backfill this is the expected
+   *  answer for most rows, and it is not a failure. */
+  misses: number;
+  /** rows where the linker threw, rejected, timed out or answered garbage —
+   *  once per ROW however many ways it went wrong. `counters.subjectLinkErrors`
+   *  and `subjectLinkTimeouts` keep the finer split. */
+  errors: number;
+  /** rows the run declined to offer the linker (a stored name the registry no
+   *  longer declares, so its rollup families are unknowable), plus one standing
+   *  for a call with no `subjectLinker` configured, which reads nothing. */
+  skipped: number;
+}
+/** records fetched per batch by `relink()`, and how often `onProgress` fires */
+export declare const RELINK_BATCH_SIZE: 500;
 export interface Scoped {
   find(q?: Record<string, unknown>): Query<any[], any>;
   aggregate(stages: Record<string, unknown>[]): Aggregate<any[]>;
@@ -760,7 +813,9 @@ export interface SubjectLinker {
    * Runs once per record on the write path, so it must answer from a cache.
    * The package bounds it rather than trusting it: past `subjectLinkTimeoutMs`,
    * or on a throw, the record is written unlinked and counted. A linked subject
-   * whose `type` the event does not declare is refused, not written.
+   * whose `type` the event does not declare is written ANYWAY and counted in
+   * `counters.subjectLinkUndeclared` — refusing it could only ever be obeyed by
+   * losing rows, because `EventSpec.subjects` is a required list.
    */
   link(
     subjects: SubjectInput[],
@@ -802,6 +857,25 @@ export interface Telemetry<R extends Registry = Registry> {
    * platform-scoped saved views only when `globalSubjectRefs` is set.
    */
   forget(tenantId: string, ref: EntityRef): Promise<ForgetResult>;
+  /**
+   * Backfill for `subjectLinker`: re-ask it about records ALREADY on disk, and
+   * replay the rollups the new subjects reach.
+   *
+   * Linking happens at write time, so configuring the hook fixes the future and
+   * nothing else — a lifetime `by:['subject']` family is keyed on the subject
+   * the record was written with, permanently, and no read-time join can reach
+   * back into it. A host that adopts linking on a Tuesday therefore has a
+   * backlog whose rows carry only `machine:<installId>` and whose user-keyed
+   * families have no member for any of them. This is how it catches up.
+   *
+   * **Dry run by default.** It rewrites historical aggregates, so `t.relink()`
+   * reports and `t.relink({ dryRun: false })` writes. Idempotent by
+   * construction: a row that already carries the linked subject yields nothing
+   * new, so a second run writes nothing and replays nothing. Returns
+   * `{ skipped: 1 }` rather than throwing when no `subjectLinker` is
+   * configured.
+   */
+  relink(opts?: RelinkOptions): Promise<RelinkResult>;
   /**
    * Tenant scope is not optional — every read goes through here. Unconditional
    * on purpose: it does not understand PLATFORM_SCOPE, so `scoped('*')` scopes

package/types/test-d.ts CHANGED Viewed

@@ -33,6 +33,8 @@ import type {
   Logger,
   MetricsOf,
   Registry,
+  RelinkOptions,
+  RelinkResult,
   RollupSpec,
   LinkSubjects,
   Scoped,
@@ -60,6 +62,7 @@ import {
   LogLevel,
   Origin,
   PLATFORM_SCOPE,
+  RELINK_BATCH_SIZE,
   RETENTION_DAYS,
   SAMPLE_RATE,
   SCHEMA_VERSION,
@@ -196,6 +199,21 @@ async function reads() {
   const gone: ForgetResult = await t.forget('acc_9', 'user:u_1');
   void (gone.deleted + gone.redacted + gone.rollups + gone.aliases);
+  // relink() — the backfill for subjectLinker. Dry run by DEFAULT, so the
+  // no-argument call is the safe one and writing is opted into.
+  const preview: RelinkResult = await t.relink();
+  const opts: RelinkOptions = {
+    names: ['user.signed_up'],
+    since: new Date('2026-01-01T00:00:00Z'),
+    limit: 10_000,
+    dryRun: false,
+    batchSize: RELINK_BATCH_SIZE,
+    onProgress: (p) => void p.examined,
+  };
+  const done: RelinkResult = await t.relink(opts);
+  void (preview.examined + done.linked + done.subjects + done.rollups
+    + done.misses + done.errors + done.skipped);
   const cp: Checkpoint = t.checkpoint('mailery-bridge');
   const mark: Date | null = await cp.get();
   await cp.advance(mark ?? new Date());