@rotorsoft/act-pg 0.22.0 → 0.24.0

package/dist/@types/postgres-store.d.ts

@@ -1,4 +1,4 @@
-import type { BlockedLease, Committed, EventMeta, Lease, Message, NotifyDisposer, PrioritizeFilter, Query, QueryStreams, QueryStreamsResult, Schema, Schemas, Store, StoreNotification, StreamPosition } from "@rotorsoft/act";
+import type { BlockedLease, Committed, EventMeta, Lease, Message, NotifyDisposer, Query, QueryStatsOptions, QueryStreams, QueryStreamsResult, Schema, Schemas, Store, StoreNotification, StreamFilter, StreamPosition, StreamStats } from "@rotorsoft/act";
 import pg from "pg";
 type Config = Readonly<{
     schema: string;
@@ -275,7 +275,30 @@ export declare class PostgresStore implements Store {
      * @param streams - Stream names to reset.
      * @returns Count of streams that were actually reset.
      */
-    reset(streams: string[]): Promise<number>;
+    /**
+     * Translate a {@link StreamFilter} to a `WHERE` clause fragment and
+     * the corresponding parameter values. The fragment never starts with
+     * `WHERE` — callers compose it with any other predicates they need.
+     * Returns an always-true clause (`true`) when the filter is empty.
+     */
+    private _filterClause;
+    reset(input: string[] | StreamFilter): Promise<number>;
+    /**
+     * Clear blocked flag (and retry / error / lease state) on streams
+     * without touching the `at` watermark. `blocked = true` is always
+     * applied, so the return count reflects only streams that were
+     * actually flipped — already-unblocked rows, unknown streams, and
+     * filter matches that aren't blocked are silently skipped.
+     *
+     * `retry = -1` matches the InMemoryStore convention: claim() bumps
+     * retry on every acquisition, so storing -1 means the first claim
+     * after unblock returns retry=0 ("first attempt"). Storing 0 would
+     * mis-report the post-recovery attempt as a continuation of the
+     * failed sequence. See {@link Store.unblock}.
+     *
+     * @returns Count of streams that were actually flipped (were blocked).
+     */
+    unblock(input: string[] | StreamFilter): Promise<number>;
     /**
      * Bulk-update priority of streams matching `filter` (ACT-102).
      *
@@ -290,7 +313,7 @@ export declare class PostgresStore implements Store {
      *
      * @returns Count of streams whose priority changed.
      */
-    prioritize(filter: PrioritizeFilter, priority: number): Promise<number>;
+    prioritize(filter: StreamFilter, priority: number): Promise<number>;
     /**
      * Streams subscription positions to a callback, ordered by stream name,
      * along with the highest event id in the store.
@@ -302,6 +325,46 @@ export declare class PostgresStore implements Store {
      * @returns `maxEventId` and the `count` of positions emitted.
      */
     query_streams(callback: (position: StreamPosition) => void, query?: QueryStreams): Promise<QueryStreamsResult>;
+    /**
+     * Per-stream aggregated stats — see {@link Store.query_stats}.
+     *
+     * Two code paths chosen by the requested stats:
+     *
+     * - **Heads-only path** (no `count`, no `names`): one or two
+     *   `SELECT DISTINCT ON (stream) ... ORDER BY stream, version DESC|ASC`
+     *   queries, executed in parallel when `tail: true`. The
+     *   `(stream, version)` unique index gives index-only access — K rows
+     *   touched per query (K = matched streams), not N (events).
+     *   Ordering by `version` (not `id`) is equivalent within a stream
+     *   (versions are monotonic per stream and events are committed
+     *   sequentially) and is the column actually indexed.
+     *
+     * - **Full-scan path** (`count` or `names` set): one CTE materializes
+     *   the filtered events, then `GROUP BY stream, name` →
+     *   `jsonb_object_agg(name, n)` for the `names` map plus per-stream
+     *   `COUNT(*)` for `count`. Heads (and `tails` when requested) come
+     *   from `DISTINCT ON` over the same CTE — they ride free on the
+     *   already-paid scan.
+     *
+     * The stream universe is derived from the events table: filter form
+     * matches event-bearing streams (not subscription rows). When the
+     * filter sets `source` or `blocked`, the events table is joined
+     * against the streams subscription table since those concepts only
+     * exist for subscribed streams.
+     */
+    query_stats<E extends Schemas>(input: string[] | Pick<StreamFilter, "stream" | "stream_exact">, options?: QueryStatsOptions<E>): Promise<Map<string, StreamStats<E>>>;
+    /**
+     * Cheap path: index-only DISTINCT ON for the head per stream, plus an
+     * optional second query (in parallel) for the tail. K rows touched
+     * per query, not N events.
+     */
+    private _queryStatsHeadsOnly;
+    /**
+     * Full-scan path: one CTE-based query computes the per-stream
+     * `COUNT(*)` and `jsonb_object_agg(name, n)` map alongside the head
+     * (and tail when requested). All extras share the single events scan.
+     */
+    private _queryStatsFullScan;
     /**
      * Implementation of the optional `Store.notify` hook. Bound onto
      * `this.notify` in the constructor when `config.notify === true`,

package/dist/@types/postgres-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/postgres-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,KAAK,EAEL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAAkB,EAClB,MAAM,EACN,OAAO,EACP,KAAK,EACL,iBAAiB,EACjB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAUpB,KAAK,MAAM,GAAG,QAAQ,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC,GACA,EAAE,CAAC,UAAU,CAAC;AAsChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,qBAAa,aAAc,YAAW,KAAK;IACzC,OAAO,CAAC,KAAK,CAAC;IACd,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAC5C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAA4B;IACjD;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAA+C;IACrE;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CACP,OAAO,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,KAC/C,OAAO,CAAC,cAAc,CAAC,CAAC;IAE7B;;;OAGG;gBACS,MAAM,GAAE,OAAO,CAAC,MAAM,CAAM;IAiBxC;;;;OAIG;IACG,OAAO;IAKb;;;;;;OAMG;YACW,eAAe;IAe7B;;;;OAIG;IACG,IAAI;IA2FV;;;OAGG;IACG,IAAI;IAoBV;;;;;;;;;OASG;IACG,KAAK,CAAC,CAAC,SAAS,OAAO,EAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,EAChD,KAAK,CAAC,EAAE,KAAK;IAyEf;;;;;;;;;OASG;IACG,MAAM,CAAC,CAAC,SAAS,OAAO,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAC3B,IAAI,EAAE,SAAS,EACf,eAAe,CAAC,EAAE,MAAM;IAkF1B;;;;;;;;;;;;;OAaG;IACG,KAAK,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,EAAE,CAAC;IA8EnB;;;;;;OAMG;IACG,SAAS,CACb,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACrE,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAkDrD;;;;;OAKG;IACG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAgD5C;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA8C5D;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAY/C;;;;;;;;;;;;;OAaG;IACG,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC;IA8BlB;;;;;;;;;OASG;IACG,aAAa,CACjB,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,EAC5C,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,kBAAkB,CAAC;IA4E9B;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,uBAAuB;IAuFrC;;;;OAIG;IACG,QAAQ,CACZ,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,SAAS,CAAC;KAClB,CAAC,GACD,OAAO,CACR,GAAG,CACD,MAAM,EACN;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAA;KAAE,CAClE,CACF;CA2CF"}
+{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/postgres-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,KAAK,EAEL,OAAO,EACP,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,MAAM,EACN,OAAO,EACP,KAAK,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAUpB,KAAK,MAAM,GAAG,QAAQ,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC,GACA,EAAE,CAAC,UAAU,CAAC;AAsChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,qBAAa,aAAc,YAAW,KAAK;IACzC,OAAO,CAAC,KAAK,CAAC;IACd,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAC5C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAA4B;IACjD;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAA+C;IACrE;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CACP,OAAO,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,KAC/C,OAAO,CAAC,cAAc,CAAC,CAAC;IAE7B;;;OAGG;gBACS,MAAM,GAAE,OAAO,CAAC,MAAM,CAAM;IAiBxC;;;;OAIG;IACG,OAAO;IAKb;;;;;;OAMG;YACW,eAAe;IAe7B;;;;OAIG;IACG,IAAI;IA2FV;;;OAGG;IACG,IAAI;IAoBV;;;;;;;;;OASG;IACG,KAAK,CAAC,CAAC,SAAS,OAAO,EAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,EAChD,KAAK,CAAC,EAAE,KAAK;IAyEf;;;;;;;;;OASG;IACG,MAAM,CAAC,CAAC,SAAS,OAAO,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAC3B,IAAI,EAAE,SAAS,EACf,eAAe,CAAC,EAAE,MAAM;IAkF1B;;;;;;;;;;;;;OAaG;IACG,KAAK,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,EAAE,CAAC;IA8EnB;;;;;;OAMG;IACG,SAAS,CACb,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACrE,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAkDrD;;;;;OAKG;IACG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAgD5C;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA8C5D;;;;;OAKG;IACH;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAiCf,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB5D;;;;;;;;;;;;;;OAcG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA0B9D;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzE;;;;;;;;;OASG;IACG,aAAa,CACjB,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,EAC5C,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,kBAAkB,CAAC;IA4E9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,WAAW,CAAC,CAAC,SAAS,OAAO,EACjC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,cAAc,CAAC,EAC/D,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IA2DvC;;;;OAIG;YACW,oBAAoB;IAsClC;;;;OAIG;YACW,mBAAmB;IAsGjC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,uBAAuB;IAuFrC;;;;OAIG;IACG,QAAQ,CACZ,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,SAAS,CAAC;KAClB,CAAC,GACD,OAAO,CACR,GAAG,CACD,MAAM,EACN;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAA;KAAE,CAClE,CACF;CA2CF"}

package/dist/index.cjs

@@ -632,14 +632,89 @@ var PostgresStore = class {
    * @param streams - Stream names to reset.
    * @returns Count of streams that were actually reset.
    */
-  async reset(streams) {
-    if (!streams.length) return 0;
+  /**
+   * Translate a {@link StreamFilter} to a `WHERE` clause fragment and
+   * the corresponding parameter values. The fragment never starts with
+   * `WHERE` — callers compose it with any other predicates they need.
+   * Returns an always-true clause (`true`) when the filter is empty.
+   */
+  _filterClause(filter, start) {
+    const conditions = [];
+    const values = [];
+    if (filter.stream !== void 0) {
+      values.push(filter.stream);
+      conditions.push(
+        filter.stream_exact ? `stream = $${start + values.length - 1}` : `stream ~ $${start + values.length - 1}`
+      );
+    }
+    if (filter.source !== void 0) {
+      conditions.push(`source IS NOT NULL`);
+      values.push(filter.source);
+      conditions.push(
+        filter.source_exact ? `source = $${start + values.length - 1}` : `source ~ $${start + values.length - 1}`
+      );
+    }
+    if (filter.blocked !== void 0) {
+      values.push(filter.blocked);
+      conditions.push(`blocked = $${start + values.length - 1}`);
+    }
+    return {
+      clause: conditions.length ? conditions.join(" AND ") : "TRUE",
+      values
+    };
+  }
+  async reset(input) {
+    const setClause = `SET at = -1, retry = 0, blocked = false, error = NULL,
+                          leased_by = NULL, leased_until = NULL`;
+    if (Array.isArray(input)) {
+      if (!input.length) return 0;
+      const { rowCount: rowCount2 } = await this._pool.query(
+        `UPDATE ${this._fqs} ${setClause} WHERE stream = ANY($1)`,
+        [input]
+      );
+      return rowCount2 ?? 0;
+    }
+    const { clause, values } = this._filterClause(input, 1);
+    const { rowCount } = await this._pool.query(
+      `UPDATE ${this._fqs} ${setClause} WHERE ${clause}`,
+      values
+    );
+    return rowCount ?? 0;
+  }
+  /**
+   * Clear blocked flag (and retry / error / lease state) on streams
+   * without touching the `at` watermark. `blocked = true` is always
+   * applied, so the return count reflects only streams that were
+   * actually flipped — already-unblocked rows, unknown streams, and
+   * filter matches that aren't blocked are silently skipped.
+   *
+   * `retry = -1` matches the InMemoryStore convention: claim() bumps
+   * retry on every acquisition, so storing -1 means the first claim
+   * after unblock returns retry=0 ("first attempt"). Storing 0 would
+   * mis-report the post-recovery attempt as a continuation of the
+   * failed sequence. See {@link Store.unblock}.
+   *
+   * @returns Count of streams that were actually flipped (were blocked).
+   */
+  async unblock(input) {
+    const setClause = `SET retry = -1, blocked = false, error = NULL,
+                          leased_by = NULL, leased_until = NULL`;
+    if (Array.isArray(input)) {
+      if (!input.length) return 0;
+      const { rowCount: rowCount2 } = await this._pool.query(
+        `UPDATE ${this._fqs} ${setClause}
+         WHERE stream = ANY($1) AND blocked = true`,
+        [input]
+      );
+      return rowCount2 ?? 0;
+    }
+    const { clause, values } = this._filterClause(
+      { ...input, blocked: true },
+      1
+    );
     const { rowCount } = await this._pool.query(
-      `UPDATE ${this._fqs}
-       SET at = -1, retry = 0, blocked = false, error = NULL,
-           leased_by = NULL, leased_until = NULL
-       WHERE stream = ANY($1)`,
-      [streams]
+      `UPDATE ${this._fqs} ${setClause} WHERE ${clause}`,
+      values
     );
     return rowCount ?? 0;
   }
@@ -658,27 +733,10 @@ var PostgresStore = class {
    * @returns Count of streams whose priority changed.
    */
   async prioritize(filter, priority) {
-    const conditions = ["priority <> $1"];
-    const values = [priority];
-    if (filter.stream !== void 0) {
-      values.push(filter.stream);
-      conditions.push(
-        filter.stream_exact ? `stream = $${values.length}` : `stream ~ $${values.length}`
-      );
-    }
-    if (filter.source !== void 0) {
-      conditions.push(`source IS NOT NULL`);
-      values.push(filter.source);
-      conditions.push(
-        filter.source_exact ? `source = $${values.length}` : `source ~ $${values.length}`
-      );
-    }
-    if (filter.blocked !== void 0) {
-      values.push(filter.blocked);
-      conditions.push(`blocked = $${values.length}`);
-    }
-    const sql = `UPDATE ${this._fqs} SET priority = $1 WHERE ${conditions.join(" AND ")}`;
-    const { rowCount } = await this._pool.query(sql, values);
+    const { clause, values } = this._filterClause(filter, 2);
+    const sql = `UPDATE ${this._fqs} SET priority = $1
+                 WHERE priority <> $1 AND ${clause}`;
+    const { rowCount } = await this._pool.query(sql, [priority, ...values]);
     return rowCount ?? 0;
   }
   /**
@@ -748,6 +806,168 @@ var PostgresStore = class {
       client.release();
     }
   }
+  /**
+   * Per-stream aggregated stats — see {@link Store.query_stats}.
+   *
+   * Two code paths chosen by the requested stats:
+   *
+   * - **Heads-only path** (no `count`, no `names`): one or two
+   *   `SELECT DISTINCT ON (stream) ... ORDER BY stream, version DESC|ASC`
+   *   queries, executed in parallel when `tail: true`. The
+   *   `(stream, version)` unique index gives index-only access — K rows
+   *   touched per query (K = matched streams), not N (events).
+   *   Ordering by `version` (not `id`) is equivalent within a stream
+   *   (versions are monotonic per stream and events are committed
+   *   sequentially) and is the column actually indexed.
+   *
+   * - **Full-scan path** (`count` or `names` set): one CTE materializes
+   *   the filtered events, then `GROUP BY stream, name` →
+   *   `jsonb_object_agg(name, n)` for the `names` map plus per-stream
+   *   `COUNT(*)` for `count`. Heads (and `tails` when requested) come
+   *   from `DISTINCT ON` over the same CTE — they ride free on the
+   *   already-paid scan.
+   *
+   * The stream universe is derived from the events table: filter form
+   * matches event-bearing streams (not subscription rows). When the
+   * filter sets `source` or `blocked`, the events table is joined
+   * against the streams subscription table since those concepts only
+   * exist for subscribed streams.
+   */
+  async query_stats(input, options) {
+    const exclude = options?.exclude ?? [];
+    const wantTail = options?.tail ?? false;
+    const wantCount = options?.count ?? false;
+    const wantNames = options?.names ?? false;
+    const before = options?.before;
+    const fullScan = wantCount || wantNames;
+    if (Array.isArray(input) && input.length === 0) {
+      return /* @__PURE__ */ new Map();
+    }
+    const where = [];
+    const params = [];
+    if (Array.isArray(input)) {
+      params.push(input);
+      where.push(`e.stream = ANY($${params.length})`);
+    } else if (input.stream !== void 0) {
+      params.push(input.stream);
+      where.push(
+        input.stream_exact ? `e.stream = $${params.length}` : `e.stream ~ $${params.length}`
+      );
+    }
+    if (exclude.length) {
+      params.push(exclude);
+      where.push(`e.name <> ALL($${params.length})`);
+    }
+    if (before !== void 0) {
+      params.push(before);
+      where.push(`e.id < $${params.length}`);
+    }
+    const fromClause = `${this._fqt} e`;
+    const whereClause = `WHERE ${where.length ? where.join(" AND ") : "TRUE"}`;
+    return fullScan ? this._queryStatsFullScan(
+      fromClause,
+      whereClause,
+      params,
+      wantTail,
+      wantCount,
+      wantNames
+    ) : this._queryStatsHeadsOnly(fromClause, whereClause, params, wantTail);
+  }
+  /**
+   * Cheap path: index-only DISTINCT ON for the head per stream, plus an
+   * optional second query (in parallel) for the tail. K rows touched
+   * per query, not N events.
+   */
+  async _queryStatsHeadsOnly(fromClause, whereClause, params, wantTail) {
+    const cols = `e.id, e.stream, e.version, e.name, e.data, e.created, e.meta`;
+    const headSql = `SELECT DISTINCT ON (e.stream) ${cols} FROM ${fromClause} ${whereClause} ORDER BY e.stream, e.version DESC`;
+    const tailSql = wantTail ? `SELECT DISTINCT ON (e.stream) ${cols} FROM ${fromClause} ${whereClause} ORDER BY e.stream, e.version ASC` : null;
+    const [headRes, tailRes] = await Promise.all([
+      this._pool.query(headSql, params),
+      tailSql ? this._pool.query(tailSql, params) : Promise.resolve(null)
+    ]);
+    const out = /* @__PURE__ */ new Map();
+    for (const row of headRes.rows) {
+      out.set(row.stream, { head: row });
+    }
+    if (tailRes) {
+      for (const row of tailRes.rows) {
+        out.get(row.stream).tail = row;
+      }
+    }
+    return out;
+  }
+  /**
+   * Full-scan path: one CTE-based query computes the per-stream
+   * `COUNT(*)` and `jsonb_object_agg(name, n)` map alongside the head
+   * (and tail when requested). All extras share the single events scan.
+   */
+  async _queryStatsFullScan(fromClause, whereClause, params, wantTail, wantCount, wantNames) {
+    const tailCte = wantTail ? `, tails AS (SELECT DISTINCT ON (stream) * FROM ef ORDER BY stream, version ASC)` : "";
+    const tailJoin = wantTail ? `LEFT JOIN tails t ON t.stream = h.stream` : "";
+    const tailCols = wantTail ? `, t.id AS t_id, t.stream AS t_stream, t.version AS t_version,
+           t.name AS t_name, t.data AS t_data, t.created AS t_created, t.meta AS t_meta` : "";
+    const sql = `
+      WITH ef AS (
+        SELECT e.id, e.stream, e.version, e.name, e.data, e.created, e.meta
+        FROM ${fromClause}
+        ${whereClause}
+      ),
+      agg AS (
+        SELECT stream,
+               SUM(n)::int AS cnt,
+               jsonb_object_agg(name, n) AS names
+        FROM (
+          SELECT stream, name, COUNT(*)::int AS n
+          FROM ef
+          GROUP BY stream, name
+        ) t
+        GROUP BY stream
+      ),
+      heads AS (
+        SELECT DISTINCT ON (stream) * FROM ef ORDER BY stream, version DESC
+      )
+      ${tailCte}
+      SELECT
+        h.id, h.stream, h.version, h.name, h.data, h.created, h.meta,
+        a.cnt AS agg_count,
+        a.names AS agg_names
+        ${tailCols}
+      FROM heads h
+      LEFT JOIN agg a ON a.stream = h.stream
+      ${tailJoin}
+    `;
+    const res = await this._pool.query(sql, params);
+    const out = /* @__PURE__ */ new Map();
+    for (const row of res.rows) {
+      const stats = {
+        head: {
+          id: row.id,
+          stream: row.stream,
+          version: row.version,
+          name: row.name,
+          data: row.data,
+          created: row.created,
+          meta: row.meta
+        }
+      };
+      if (wantTail && row.t_id !== void 0 && row.t_id !== null) {
+        stats.tail = {
+          id: row.t_id,
+          stream: row.t_stream,
+          version: row.t_version,
+          name: row.t_name,
+          data: row.t_data,
+          created: row.t_created,
+          meta: row.t_meta
+        };
+      }
+      if (wantCount) stats.count = row.agg_count;
+      if (wantNames) stats.names = row.agg_names;
+      out.set(row.stream, stats);
+    }
+    return out;
+  }
   /**
    * Implementation of the optional `Store.notify` hook. Bound onto
    * `this.notify` in the constructor when `config.notify === true`,