@adonis-agora/telescope 0.23.0 → 0.25.0

package/dist/src/sampling/sampling_store.js

@@ -1,3 +1,4 @@
+import { forwardOptionalReads } from '../store.js';
 import { passesSampling } from './sampling.js';
 /**
  * A {@link TelescopeStore} decorator that applies tail-sampling on the WRITE
@@ -24,6 +25,7 @@ export class SamplingTelescopeStore {
         this.inner = inner;
         this.sampling = sampling;
         this.random = random;
+        forwardOptionalReads(this, inner);
     }
     async record(input) {
         if (!passesSampling(this.sampling, input, this.random)) {
@@ -52,7 +54,10 @@ function droppedEntry(input) {
     return {
         id: '',
         type: input.type,
-        familyHash: input.familyHash ?? null,
+        // A getter, so a lazily computed key is not computed for an entry that is dropped.
+        get familyHash() {
+            return input.familyHash ?? null;
+        },
         content: input.content,
         tags: input.tags ?? [],
         sequence: -1,

package/dist/src/sampling/sampling_store.js.map

@@ -1 +1 @@
-{"version":3,"file":"sampling_store.js","sourceRoot":"","sources":["../../../src/sampling/sampling_store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAuB,MAAM,eAAe,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAsB;IAEd,KAAK;IACL,QAAQ;IACR,MAAM;IAHzB,YACmB,KAAqB,EACrB,QAAwB,EACxB,MAAM,GAAiB,IAAI,CAAC,MAAM;qBAFlC,KAAK;wBACL,QAAQ;sBACR,MAAM;IACtB,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAW,KAA4B;QACjD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,KAAkB;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAe,EAAE,QAAiB;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,6EAA6E;AAC7E,SAAS,YAAY,CAAW,KAA4B;IAC1D,OAAO;QACL,EAAE,EAAE,EAAE;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,QAAQ,EAAE,CAAC,CAAC;QACZ,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,QAAQ;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,SAAS,EAAE,IAAI,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sampling_store.js","sourceRoot":"","sources":["../../../src/sampling/sampling_store.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,oBAAoB,EAAuB,MAAM,aAAa,CAAC;AACzF,OAAO,EAAE,cAAc,EAAuB,MAAM,eAAe,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAsB;IAEd,KAAK;IACL,QAAQ;IACR,MAAM;IAHzB,YACmB,KAAqB,EACrB,QAAwB,EACxB,MAAM,GAAiB,IAAI,CAAC,MAAM;qBAFlC,KAAK;wBACL,QAAQ;sBACR,MAAM;QAEvB,oBAAoB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,MAAM,CAAW,KAA4B;QACjD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,KAAkB;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAe,EAAE,QAAiB;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,6EAA6E;AAC7E,SAAS,YAAY,CAAW,KAA4B;IAC1D,OAAO;QACL,EAAE,EAAE,EAAE;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,mFAAmF;QACnF,IAAI,UAAU;YACZ,OAAO,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC;QAClC,CAAC;QACD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,QAAQ,EAAE,CAAC,CAAC;QACZ,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,QAAQ;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,SAAS,EAAE,IAAI,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC"}

package/dist/src/self_scope.d.ts

@@ -0,0 +1,5 @@
+/** Run `fn` as telescope's own work: nothing it causes is recorded. */
+export declare function runAsTelescopeWork<T>(fn: () => T): T;
+/** Whether the caller is inside {@link runAsTelescopeWork}. */
+export declare function isTelescopeWork(): boolean;
+//# sourceMappingURL=self_scope.d.ts.map

package/dist/src/self_scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self_scope.d.ts","sourceRoot":"","sources":["../../src/self_scope.ts"],"names":[],"mappings":"AAwBA,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpD;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}

package/dist/src/self_scope.js

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Marks work telescope does on its own behalf — the lucid store's INSERTs, reads and
+ * prunes — so the watchers can tell it apart from the app's.
+ *
+ * The query watcher records every `db:query` Lucid emits, and when the store shares
+ * the app's connection its own INSERT is one of them: recorded through the store, it
+ * becomes another INSERT, another `db:query`, and the loop never ends. Every
+ * ingestion point that goes through `safeRecord` drops entries raised inside this
+ * scope.
+ *
+ * Kept on a `Symbol.for()` global slot like the origin scope, so a store built by
+ * one copy of this package and a watcher loaded from another still agree.
+ */
+const SELF_SCOPE_KEY = Symbol.for('@agora/telescope:self-scope');
+const globalSlot = globalThis;
+const storage = globalSlot[SELF_SCOPE_KEY] ??
+    new AsyncLocalStorage();
+globalSlot[SELF_SCOPE_KEY] = storage;
+/** Run `fn` as telescope's own work: nothing it causes is recorded. */
+export function runAsTelescopeWork(fn) {
+    return storage.run(true, fn);
+}
+/** Whether the caller is inside {@link runAsTelescopeWork}. */
+export function isTelescopeWork() {
+    return storage.getStore() === true;
+}
+//# sourceMappingURL=self_scope.js.map

package/dist/src/self_scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self_scope.js","sourceRoot":"","sources":["../../src/self_scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAEjE,MAAM,UAAU,GAAG,UAAqC,CAAC;AAEzD,MAAM,OAAO,GACV,UAAU,CAAC,cAAc,CAAyC;IACnE,IAAI,iBAAiB,EAAQ,CAAC;AAChC,UAAU,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC;AAErC,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAI,EAAW;IAC/C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC;AACrC,CAAC"}

package/dist/src/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY;IAN/B,mFAAmF;IACnF,OAAO,CAAC,YAAY,CAA6B;IAEjD,YACmB,KAAK,EAAE,cAAc;IACtC,8EAA8E;IAC7D,YAAY,GAAE,mBAAwB,EACrD;IAEJ,gFAAgF;IAChF,IAAI,cAAc,IAAI,cAAc,CAEnC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAGnD;IAED,mDAAmD;IACnD,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzC;IAED,wCAAwC;IACxC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAEtC;IAED,iEAAiE;IACjE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzC;IAED,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAEvB;IAED;;;;OAIG;IACG,WAAW,CAAC,KAAK,SAAK,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAOnE;IAED,0EAA0E;IACpE,OAAO,CAAC,KAAK,SAAK,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CASjE;CACF"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY;IAN/B,mFAAmF;IACnF,OAAO,CAAC,YAAY,CAA6B;IAEjD,YACmB,KAAK,EAAE,cAAc;IACtC,8EAA8E;IAC7D,YAAY,GAAE,mBAAwB,EACrD;IAEJ,gFAAgF;IAChF,IAAI,cAAc,IAAI,cAAc,CAEnC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAGnD;IAED,mDAAmD;IACnD,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzC;IAED,wCAAwC;IACxC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAEtC;IAED,iEAAiE;IACjE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzC;IAED,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAEvB;IAED;;;;OAIG;IACG,WAAW,CAAC,KAAK,SAAK,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAWnE;IAED,0EAA0E;IACpE,OAAO,CAAC,KAAK,SAAK,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAYjE;CACF"}

package/dist/src/service.js

@@ -53,8 +53,12 @@ export class TelescopeService {
      * the store's newest-first ordering.
      */
     async topFamilies(limit = 10, type) {
+        if (typeof this.store.countFamilies === 'function') {
+            return this.store.countFamilies(type !== undefined ? { limit, type } : { limit });
+        }
         const counts = new Map();
-        for (const entry of await this.store.list(type !== undefined ? { type } : {})) {
+        const query = { omitContent: true, ...(type !== undefined ? { type } : {}) };
+        for (const entry of await this.store.list(query)) {
             if (!entry.familyHash)
                 continue;
             counts.set(entry.familyHash, (counts.get(entry.familyHash) ?? 0) + 1);
@@ -63,8 +67,11 @@ export class TelescopeService {
     }
     /** Top-N most common tags across stored entries, optionally by prefix. */
     async topTags(limit = 10, prefix) {
+        if (typeof this.store.countTags === 'function') {
+            return this.store.countTags(prefix !== undefined ? { limit, prefix } : { limit });
+        }
         const counts = new Map();
-        for (const entry of await this.store.list()) {
+        for (const entry of await this.store.list({ omitContent: true })) {
             for (const tag of entry.tags) {
                 if (prefix !== undefined && !tag.startsWith(prefix))
                     continue;

package/dist/src/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}

package/dist/src/store.d.ts

@@ -44,6 +44,14 @@ export interface EntryQuery {
      * `@adonis-agora/filter`'s `FilterInput.size` (see {@link EntryQuery.page}).
      */
     size?: number;
+    /**
+     * The caller reads everything but `content`, so a store MAY return `content: null`
+     * instead of loading and parsing it. A hint, not a filter: a store that ignores it
+     * still answers correctly, and callers must not depend on content being absent.
+     * Aggregations over a whole window set it and fetch the content of the few entries
+     * they display afterwards.
+     */
+    omitContent?: boolean;
 }
 /** One row of {@link TelescopeStore.listTraceIds} — a trace and when it was last seen. */
 export interface TraceIdRow {
@@ -69,6 +77,25 @@ export interface BucketCountQuery {
     /** Only entries of this type. */
     type?: string;
 }
+/** A grouping key and how many stored entries carry it. */
+export interface KeyCountRow {
+    key: string;
+    count: number;
+}
+/** What {@link TelescopeStore.countFamilies} counts. */
+export interface FamilyCountQuery {
+    /** How many families to return, busiest first. */
+    limit: number;
+    /** Only entries of this type. */
+    type?: string;
+}
+/** What {@link TelescopeStore.countTags} counts. */
+export interface TagCountQuery {
+    /** How many tags to return, most common first. */
+    limit: number;
+    /** Only tags starting with this prefix. */
+    prefix?: string;
+}
 /** The window + page for {@link TelescopeStore.listTraceIds}. */
 export interface TraceIdQuery {
     /**
@@ -141,5 +168,24 @@ export interface TelescopeStore {
      * scan-and-bucket, which is what this always used to do.
      */
     countByBucket?(query: BucketCountQuery): Promise<BucketCountRow[]>;
+    /**
+     * OPTIONAL fast path for `TelescopeService.topFamilies`: the busiest `familyHash`
+     * values across every stored entry, most entries first, ties going to the family
+     * seen most recently. Without it the service lists the whole table and counts in JS.
+     */
+    countFamilies?(query: FamilyCountQuery): Promise<KeyCountRow[]>;
+    /**
+     * OPTIONAL fast path for `TelescopeService.topTags`: the most common tags across
+     * every stored entry, ties going to the tag seen most recently. Without it the
+     * service lists the whole table and counts in JS.
+     */
+    countTags?(query: TagCountQuery): Promise<KeyCountRow[]>;
 }
+/**
+ * Give a decorating store the optional read methods its inner store has, and only
+ * those: callers detect a capability by the method being there, so a decorator that
+ * always declared them would claim fast paths the store underneath cannot serve, and
+ * one that never did would hide them.
+ */
+export declare function forwardOptionalReads(target: TelescopeStore, inner: TelescopeStore): void;
 //# sourceMappingURL=store.d.ts.map

package/dist/src/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,4CAA4C;IAC5C,KAAK,CAAC,EAAE,IAAI,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,MAAM,EAAE,IAAI,CAAC;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,KAAK,EAAE,IAAI,CAAC;IACZ,8BAA8B;IAC9B,MAAM,EAAE,IAAI,CAAC;IACb,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEzE,yDAAyD;IACzD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAEvC,mDAAmD;IACnD,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE3C,sCAAsC;IACtC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE3D,iCAAiC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAE1D;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CACpE"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"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"}

package/dist/src/store.js

@@ -1,2 +1,17 @@
-export {};
+/** The optional read methods a store may implement on top of the required contract. */
+const OPTIONAL_READS = ['listTraceIds', 'countByBucket', 'countFamilies', 'countTags'];
+/**
+ * Give a decorating store the optional read methods its inner store has, and only
+ * those: callers detect a capability by the method being there, so a decorator that
+ * always declared them would claim fast paths the store underneath cannot serve, and
+ * one that never did would hide them.
+ */
+export function forwardOptionalReads(target, inner) {
+    const writable = target;
+    for (const name of OPTIONAL_READS) {
+        const method = inner[name];
+        if (typeof method === 'function')
+            writable[name] = method.bind(inner);
+    }
+}
 //# sourceMappingURL=store.js.map

package/dist/src/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":""}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AA0MA,uFAAuF;AACvF,MAAM,cAAc,GAAG,CAAC,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,WAAW,CAAU,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB,EAAE,KAAqB;IAChF,MAAM,QAAQ,GAAG,MAA4C,CAAC;IAC9D,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,OAAO,MAAM,KAAK,UAAU;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxE,CAAC;AACH,CAAC"}

package/dist/src/stores/lucid.d.ts

@@ -1,5 +1,5 @@
 import { type Entry, type RecordInput } from '../entry.js';
-import type { BucketCountQuery, BucketCountRow, EntryQuery, TelescopeStore, TraceIdQuery, TraceIdRow } from '../store.js';
+import type { BucketCountQuery, BucketCountRow, EntryQuery, FamilyCountQuery, KeyCountRow, TagCountQuery, TelescopeStore, TraceIdQuery, TraceIdRow } from '../store.js';
 /**
  * The table {@link LucidTelescopeStore} reads and writes. Override via
  * {@link LucidStoreOptions.tableName} when `telescope_entries` collides with an
@@ -33,12 +33,13 @@ export interface TelescopeColumns {
  * indexes `list` / `prune` / `topFamilies` lean on, as one statement per array
  * element so each can be issued through Lucid's `rawQuery`.
  *
- * Portable across sqlite / Postgres / MySQL (quoted identifiers, no dialect-only
- * column types). A real deployment should still prefer the bundled migration stub
+ * Identifiers are double-quoted (sqlite / Postgres) unless `dialect` is a Lucid
+ * MySQL dialect name (`mysql` / `mysql2`), which gets backticks and plain
+ * `CREATE INDEX`; the column types are portable. A real deployment should still prefer the bundled migration stub
  * so the schema is versioned, but this lets a store stand itself up in tests and
  * scripts without a migration runner.
  */
-export declare function createTableStatements(tableName?: string): string[];
+export declare function createTableStatements(tableName?: string, dialect?: string): string[];
 /**
  * The marker table backing the fingerprint gate. One row PER owned entries table
  * (keyed by that table's name, so two telescope tables in one database never
@@ -60,6 +61,16 @@ export interface LucidDatabaseLike {
     table(table: string): LucidInsertBuilderLike;
     /** Run a raw SQL statement (DDL, `MAX(sequence)` seed). */
     rawQuery(sql: string, bindings?: unknown[]): Promise<unknown>;
+    /** The dialect, when this is a single connection client. Picks the DDL's identifier quoting. */
+    dialect?: {
+        name: string;
+    };
+    /** The default connection, when this is the `Database` facade. */
+    connection?(): {
+        dialect?: {
+            name: string;
+        };
+    };
 }
 /** The structural query-builder surface the store leans on (Knex-shaped). */
 export interface LucidQueryBuilderLike {
@@ -70,6 +81,8 @@ export interface LucidQueryBuilderLike {
     whereNotNull(column: string): this;
     orderBy(column: string, direction: 'asc' | 'desc'): this;
     groupBy(...columns: string[]): this;
+    /** Group by an expression. Optional: without it, `countByBucket` buckets rows in JS. */
+    groupByRaw?(sql: string, bindings?: unknown[]): this;
     limit(value: number): this;
     offset(value: number): this;
     /** Aggregate MAX with an alias, e.g. `max('created_at as last_at')`. Chainable so it
@@ -81,7 +94,8 @@ export interface LucidQueryBuilderLike {
     first(): Promise<Record<string, unknown> | null>;
 }
 export interface LucidInsertBuilderLike {
-    insert(row: Record<string, unknown>): Promise<unknown>;
+    /** Insert one row, or several in one statement. */
+    insert(row: Record<string, unknown> | Record<string, unknown>[]): Promise<unknown>;
 }
 /** Options for {@link LucidTelescopeStore} (and the `storage.lucid` factory). */
 export interface LucidStoreOptions {
@@ -110,6 +124,15 @@ export interface LucidStoreOptions {
  * `sequence` is seeded from `MAX(sequence)` on first use so it keeps climbing
  * across process restarts.
  *
+ * Writes are buffered: every entry recorded during one tick of the event loop goes
+ * out in one multi-row INSERT (split to stay under each dialect's bind limit), one
+ * statement at a time, so the store never holds more than one pooled connection
+ * for writing and a burst of watcher events costs a handful of round trips instead
+ * of one each. `record()` still resolves once its entry is persisted.
+ *
+ * Every query the store runs is marked as telescope's own work (see
+ * `self_scope.ts`), so the query watcher never records them.
+ *
  * Usually you don't construct this directly: `config/telescope.ts` selects it via
  * `storage.lucid({ ... })` and the provider builds it for you, lazily importing
  * `@adonisjs/lucid` only when the `lucid` driver is the active one.
@@ -122,16 +145,17 @@ export declare class LucidTelescopeStore implements TelescopeStore {
     /** Lazily-resolved init (table creation + sequence seed), run at most once. */
     private ready;
     private sequence;
-    /**
-     * Single-flight write chain: every `record()` insert is queued behind the previous one so the
-     * store holds at most ONE pooled connection at a time. A burst of watcher events can therefore
-     * never exhaust the host app's connection pool (which telescope may share). Reads
-     * (`get`/`list`/`prune`) are user-initiated and low-frequency, so they are intentionally NOT
-     * serialized.
-     */
-    private writeTail;
+    private pending;
+    /** The running drain, while one is scheduled or writing. */
+    private draining;
+    private dropped;
+    private warnedDrop;
     constructor(db: LucidDatabaseLike, options?: LucidStoreOptions);
     record<TContent>(input: RecordInput<TContent>): Promise<Entry<TContent>>;
+    /** Entries dropped because the write buffer was full. */
+    get droppedCount(): number;
+    /** Resolves once every entry recorded so far has been written (or has failed). */
+    flush(): Promise<void>;
     get(id: string): Promise<Entry | null>;
     list(query?: EntryQuery): Promise<Entry[]>;
     /**
@@ -145,29 +169,50 @@ export declare class LucidTelescopeStore implements TelescopeStore {
      */
     listTraceIds(query: TraceIdQuery): Promise<TraceIdRow[]>;
     /**
-     * Per-bucket, per-type counts for the throughput chart.
+     * Per-bucket, per-type counts for the throughput chart, grouped in SQL so one row
+     * per `(bucket, type)` leaves the database instead of one per entry.
      *
-     * The win here is the PROJECTION, not the grouping: the chart needs `created_at`
-     * and `type` and nothing else, but the only way to get them was `list()`, which
-     * does `select('*')` — shipping every row's `content` JSON blob out of the database
-     * and running it through `hydrate()`, to then discard all of it except a timestamp
-     * and a string. Two scalar columns instead of a blob is orders of magnitude less
-     * bytes on the wire and no per-row JSON parse.
-     *
-     * The bucketing itself stays in JS, deliberately. Doing it in SQL needs a raw
-     * select expression (`(created_at - ?) / ?`), and Lucid exposes `groupByRaw` but no
-     * `selectRaw` — the alternative is `rawQuery`, whose result shape differs per driver
-     * (`{ rows }` on Postgres, an array on SQLite). Trading a portability bug for the
-     * second-order win is a bad deal; the row count is what would justify it, and after
-     * the redis-watcher filter that count drops by roughly an order of magnitude. If
-     * this is still hot with a clean table, THAT is when it earns the raw query.
+     * The bucket is `(created_at - start) - ((created_at - start) % bucketMs)`: integer
+     * arithmetic every dialect evaluates the same way, where `/` would be integer
+     * division on some and decimal on MySQL. Each group reports its newest
+     * `created_at`, and the bucket index is computed from that in JS. A builder
+     * without `groupByRaw` gets the per-row projection, bucketed here.
      */
     countByBucket(query: BucketCountQuery): Promise<BucketCountRow[]>;
+    /**
+     * The busiest families, counted by `GROUP BY family_hash` — see
+     * {@link TelescopeStore.countFamilies}.
+     */
+    countFamilies(query: FamilyCountQuery): Promise<KeyCountRow[]>;
+    /**
+     * The most common tags — see {@link TelescopeStore.countTags}. Tags are JSON text,
+     * so they are counted here, reading only the `tags` column a page at a time in
+     * primary-key order.
+     */
+    countTags(query: TagCountQuery): Promise<KeyCountRow[]>;
     count(): Promise<number>;
+    /**
+     * Deletes oldest-first, {@link PRUNE_BATCH_ROWS} rows per statement, each batch
+     * addressed by its newest row's position rather than by id: a backlog of any size
+     * is pruned in bounded statements that never approach a bind limit.
+     */
     prune(olderThan: Date, keepLast?: number): Promise<number>;
     clear(): Promise<void>;
     /** Cap enforcement helper for callers running a scheduled trim. */
     get capacity(): number | null;
+    /** The first row of an ordered query, as a position. */
+    private position;
+    /** Start a drain on the next tick unless one is already running. */
+    private scheduleDrain;
+    /** Write the buffer out, batch by batch, until it is empty. */
+    private drain;
+    /** The oldest pending writes that fit one INSERT. */
+    private takeBatch;
+    /**
+     * One multi-row INSERT. When it fails, its rows are retried one at a time, so a
+     * row the database rejects fails only its own `record()`.
+     */
+    private writeBatch;
     /** Run table creation (optional) + sequence seeding exactly once. */
     private init;
     private doInit;

package/dist/src/stores/lucid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lucid.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lucid.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid.ts"],"names":[],"mappings":"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"}