@dudousxd/nestjs-durable-dashboard 0.43.1 → 0.44.0

package/dist/server/index.d.cts

@@ -1,8 +1,10 @@
 import * as _dudousxd_nestjs_durable_core from '@dudousxd/nestjs-durable-core';
-import { RunGateway, StateStore, WorkflowEngine, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, DurableTopology, GroupHealth, RunDetail, RunResult, UpdateResult, EngineEvent, RunStatus } from '@dudousxd/nestjs-durable-core';
+import { RunGateway, StateStore, WorkflowEngine, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, DurableTopology, GroupHealth, RunDetail, RunResult, UpdateResult, EngineEvent, AttributeFilter } from '@dudousxd/nestjs-durable-core';
 export { RunDetail } from '@dudousxd/nestjs-durable-core';
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
+import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
+import { FilterRunner } from '@dudousxd/nestjs-filter';
 import { DynamicModule, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, ExecutionContext, StreamableFile } from '@nestjs/common';
 
 /** The session user the host `login` hook returns to mint a cookie. */
@@ -137,6 +139,10 @@ declare class DashboardService {
     /** `(status, origin)` counts over the same predicates {@link listRuns} pages — what keeps the
      *  console's chips exact while its list is bounded to a page. */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /** The distinct values of one filter axis over the same predicates — what fills the console's
+     *  tenant/tag/attribute pickers, so an operator picks a value that exists instead of typing one
+     *  blind. `[]` when the store cannot enumerate them; the pickers then fall back to free text. */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /** This deployment's durable role (control plane vs tenant) + tenant name — for the dashboard header
      *  badge. Routes through the gateway, which knows its own topology (store-backed = operator, proxy =
      *  tenant). Works on both topologies (no store/engine needed). */
@@ -210,28 +216,68 @@ declare class DashboardService {
  */
 type RunListRow = Omit<RunListItem, 'input' | 'output' | 'error'>;
 
+/**
+ * What this adapter hands the filter runner in place of a query builder: a {@link RunQuery} under
+ * construction.
+ *
+ * The runner never inspects it — it only passes it back to the adapter's own methods — so the shape
+ * is ours to choose, and a plain predicate bag is the honest one. There is no SQL to append to here;
+ * a run query is a fixed set of named predicates that the gateway resolves, so "building" it is
+ * filling fields in, and everything the filter lib can express but `RunQuery` cannot is rejected at
+ * the point of translation rather than accumulated and silently dropped.
+ */
+declare class RunQueryDraft {
+    readonly query: RunQuery;
+    /** Narrow by one or more predicates. Later calls overwrite the same field — the runner applies one
+     *  clause per field, so the last one wins, exactly as a repeated `where` on a builder would. */
+    narrow(patch: RunQuery): void;
+    /** Add one search-attribute predicate. These ACCUMULATE (unlike {@link narrow}) because
+     *  `RunQuery.attributes` is an ANDed list — two predicates on different keys are both meant. */
+    attribute(filter: AttributeFilter): void;
+    /** The predicates minus the page window and the axes a facet count reports on — what
+     *  `runFacets`/`runValueFacets` are taken over. */
+    facetQuery(): RunFacetQuery;
+}
+
 /** JSON API consumed by the control-plane SPA. Mounted at `apiBasePath` (set by RouterModule). */
 declare class DurableApiController {
     private readonly dashboard;
-    constructor(dashboard: DashboardService);
+    private readonly runner;
+    constructor(dashboard: DashboardService, runner: FilterRunner);
     /**
-     * The run list, filtered by whatever the operator asked for. Every predicate is OPTIONAL and an
-     * omitted one means "don't narrow on this axis" — in particular `namespace`, whose absence keeps
-     * the historical, deliberate behaviour that read paths are NOT namespace-scoped (core,
-     * `WorkflowRun.namespace`): the console shows every tenant's runs until an operator chooses one.
-     * A blank param (`?namespace=`, from a cleared filter box) is the same as an absent one; passing
-     * `''` through would be an exact match on a tenant nobody has, i.e. a silently empty console.
+     * The run list, filtered by whatever the operator asked for.
+     *
+     * The predicates are parsed, validated and translated by `@dudousxd/nestjs-filter` (see
+     * `RunFilter` for the two spellings it accepts, and `RunQueryAdapter` for how they become a
+     * `RunQuery`). Every predicate is OPTIONAL and an omitted one means "don't narrow on this axis" —
+     * in particular `namespace`, whose absence keeps the historical, deliberate behaviour that read
+     * paths are NOT namespace-scoped (core, `WorkflowRun.namespace`): the console shows every tenant's
+     * runs until an operator chooses one.
      */
-    runs(status?: RunStatus | RunStatus[], workflow?: string, tag?: string, attr?: string | string[], namespace?: string, origin?: string, unattributed?: string, limit?: string, offset?: string): Promise<RunListRow[]>;
+    runs(draft: RunQueryDraft): Promise<RunListRow[]>;
     /**
      * `(status, origin)` counts for the runs matching the same tag/tenant/attribute predicates as
      * `GET runs`. This is what lets that listing be PAGED at all: the page bounds what the console
      * renders, this bounds nothing and keeps its status and origin chips exact.
      *
-     * `status`, `origin` and the page bounds are deliberately NOT accepted — they are the axes being
-     * counted, so narrowing by them would report the answer back to itself.
+     * `status`, `origin` and the page bounds are accepted (the route takes the same filter) but
+     * deliberately DROPPED before counting — they are the axes being counted, so narrowing by them
+     * would report the answer back to itself.
      */
-    facets(workflow?: string, tag?: string, attr?: string | string[], namespace?: string): Promise<_dudousxd_nestjs_durable_core.RunFacetRow[]>;
+    facets(draft: RunQueryDraft): Promise<_dudousxd_nestjs_durable_core.RunFacetRow[]>;
+    /**
+     * The distinct values one filter field takes across the runs matching every OTHER active
+     * predicate, with counts — what the console's tenant/tag/attribute pickers list.
+     *
+     * `?groupByCount[field]=tag&groupByCount[limit]=20`, with the filters in the structured
+     * `filter[where][...]` form (what `filterQuery()` builds). Scoping the values to the active
+     * filters is the point: picking a tenant leaves the tag picker offering only that tenant's tags,
+     * so a picker never offers a value whose result set is empty.
+     *
+     * `limit` matters rather than being a nicety — tag and attribute cardinality grows with the data
+     * (a `singleton:<key>` tag is minted per key), so the unbounded answer is a listing.
+     */
+    values(query: Record<string, unknown>): Promise<_dudousxd_nestjs_filter.GroupByCountResult>;
     /** Prometheus-text metrics (runs/steps by outcome, per-workflow counts) for a scrape. */
     metrics(): Promise<string>;
     /** Per-group worker health (queue backlog + live worker heartbeats) for the Workers panel. */
@@ -256,7 +302,7 @@ declare class DurableApiController {
      * The filter takes the SAME params as `GET runs` and is parsed identically, so "retry all" acts on
      * exactly the set the operator was looking at rather than a wider one.
      */
-    bulk(action: 'retry' | 'cancel', status?: RunStatus, tag?: string, workflow?: string, attr?: string | string[], compensate?: string, namespace?: string, origin?: string, unattributed?: string): Promise<{
+    bulk(action: 'retry' | 'cancel', draft: RunQueryDraft, compensate?: string): Promise<{
         matched: number;
         applied: number;
     }>;
@@ -402,6 +448,24 @@ interface DurableDashboardOptions {
      * (e.g. an `EntityManager` to look up an admin user).
      */
     dashboardAuth?: DashboardAuthOptions;
+    /**
+     * Who registers `@dudousxd/nestjs-filter`'s core — the console's run filters are written with it.
+     *
+     * - `'bootstrap'` (default): this module calls `FilterModule.forRoot()` itself, so the console
+     *   works in an app that has never heard of the filter library.
+     * - `'host'`: your app already calls `FilterModule.forRoot(...)`; this module registers only its
+     *   own filter and adapter.
+     *
+     * It has to be YOUR call rather than something detected, because `forRoot` is a GLOBAL
+     * registration: called twice, the second one's module options (validation policy, input format,
+     * page-size ceiling) shadow the first's, and the app-wide interceptor is registered twice. There
+     * is no moment at module-definition time when this module could see whether you have called it.
+     *
+     * Only the core is shared. The console's adapter never is: `RunFilter` names its own via
+     * `@Filterable({ adapter })`, so your global adapter (your ORM's) keeps answering for your filters
+     * and the run gateway answers for the console's, in the same process.
+     */
+    filterModule?: 'bootstrap' | 'host';
 }
 /**
  * Async variant of {@link DurableDashboardOptions}. The mount paths and `guards` stay static (the
@@ -416,6 +480,8 @@ interface DurableDashboardAsyncOptions {
     apiBasePath?: string;
     guards?: Type<CanActivate>[];
     imports?: DynamicModule['imports'];
+    /** See {@link DurableDashboardOptions.filterModule}. */
+    filterModule?: 'bootstrap' | 'host';
     /** Providers injected into `useDashboardAuth`, in order. Shared with a `guards` class's own deps. */
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
     /** Build the `dashboardAuth` config from injected deps (or `undefined` to leave the console open). */
@@ -439,6 +505,8 @@ declare class DurableApiModule {
          *  (true whenever `dashboardAuth` was set, or unconditionally for `forRootAsync`, where it's
          *  resolved at runtime and is a no-op if it ends up unconfigured). */
         authMayBeConfigured: boolean;
+        /** See {@link DurableDashboardOptions.filterModule}. */
+        filterModule?: 'bootstrap' | 'host';
     }): DynamicModule;
 }
 /**

package/dist/server/index.d.ts

@@ -1,8 +1,10 @@
 import * as _dudousxd_nestjs_durable_core from '@dudousxd/nestjs-durable-core';
-import { RunGateway, StateStore, WorkflowEngine, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, DurableTopology, GroupHealth, RunDetail, RunResult, UpdateResult, EngineEvent, RunStatus } from '@dudousxd/nestjs-durable-core';
+import { RunGateway, StateStore, WorkflowEngine, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, DurableTopology, GroupHealth, RunDetail, RunResult, UpdateResult, EngineEvent, AttributeFilter } from '@dudousxd/nestjs-durable-core';
 export { RunDetail } from '@dudousxd/nestjs-durable-core';
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
+import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
+import { FilterRunner } from '@dudousxd/nestjs-filter';
 import { DynamicModule, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, ExecutionContext, StreamableFile } from '@nestjs/common';
 
 /** The session user the host `login` hook returns to mint a cookie. */
@@ -137,6 +139,10 @@ declare class DashboardService {
     /** `(status, origin)` counts over the same predicates {@link listRuns} pages — what keeps the
      *  console's chips exact while its list is bounded to a page. */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /** The distinct values of one filter axis over the same predicates — what fills the console's
+     *  tenant/tag/attribute pickers, so an operator picks a value that exists instead of typing one
+     *  blind. `[]` when the store cannot enumerate them; the pickers then fall back to free text. */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /** This deployment's durable role (control plane vs tenant) + tenant name — for the dashboard header
      *  badge. Routes through the gateway, which knows its own topology (store-backed = operator, proxy =
      *  tenant). Works on both topologies (no store/engine needed). */
@@ -210,28 +216,68 @@ declare class DashboardService {
  */
 type RunListRow = Omit<RunListItem, 'input' | 'output' | 'error'>;
 
+/**
+ * What this adapter hands the filter runner in place of a query builder: a {@link RunQuery} under
+ * construction.
+ *
+ * The runner never inspects it — it only passes it back to the adapter's own methods — so the shape
+ * is ours to choose, and a plain predicate bag is the honest one. There is no SQL to append to here;
+ * a run query is a fixed set of named predicates that the gateway resolves, so "building" it is
+ * filling fields in, and everything the filter lib can express but `RunQuery` cannot is rejected at
+ * the point of translation rather than accumulated and silently dropped.
+ */
+declare class RunQueryDraft {
+    readonly query: RunQuery;
+    /** Narrow by one or more predicates. Later calls overwrite the same field — the runner applies one
+     *  clause per field, so the last one wins, exactly as a repeated `where` on a builder would. */
+    narrow(patch: RunQuery): void;
+    /** Add one search-attribute predicate. These ACCUMULATE (unlike {@link narrow}) because
+     *  `RunQuery.attributes` is an ANDed list — two predicates on different keys are both meant. */
+    attribute(filter: AttributeFilter): void;
+    /** The predicates minus the page window and the axes a facet count reports on — what
+     *  `runFacets`/`runValueFacets` are taken over. */
+    facetQuery(): RunFacetQuery;
+}
+
 /** JSON API consumed by the control-plane SPA. Mounted at `apiBasePath` (set by RouterModule). */
 declare class DurableApiController {
     private readonly dashboard;
-    constructor(dashboard: DashboardService);
+    private readonly runner;
+    constructor(dashboard: DashboardService, runner: FilterRunner);
     /**
-     * The run list, filtered by whatever the operator asked for. Every predicate is OPTIONAL and an
-     * omitted one means "don't narrow on this axis" — in particular `namespace`, whose absence keeps
-     * the historical, deliberate behaviour that read paths are NOT namespace-scoped (core,
-     * `WorkflowRun.namespace`): the console shows every tenant's runs until an operator chooses one.
-     * A blank param (`?namespace=`, from a cleared filter box) is the same as an absent one; passing
-     * `''` through would be an exact match on a tenant nobody has, i.e. a silently empty console.
+     * The run list, filtered by whatever the operator asked for.
+     *
+     * The predicates are parsed, validated and translated by `@dudousxd/nestjs-filter` (see
+     * `RunFilter` for the two spellings it accepts, and `RunQueryAdapter` for how they become a
+     * `RunQuery`). Every predicate is OPTIONAL and an omitted one means "don't narrow on this axis" —
+     * in particular `namespace`, whose absence keeps the historical, deliberate behaviour that read
+     * paths are NOT namespace-scoped (core, `WorkflowRun.namespace`): the console shows every tenant's
+     * runs until an operator chooses one.
      */
-    runs(status?: RunStatus | RunStatus[], workflow?: string, tag?: string, attr?: string | string[], namespace?: string, origin?: string, unattributed?: string, limit?: string, offset?: string): Promise<RunListRow[]>;
+    runs(draft: RunQueryDraft): Promise<RunListRow[]>;
     /**
      * `(status, origin)` counts for the runs matching the same tag/tenant/attribute predicates as
      * `GET runs`. This is what lets that listing be PAGED at all: the page bounds what the console
      * renders, this bounds nothing and keeps its status and origin chips exact.
      *
-     * `status`, `origin` and the page bounds are deliberately NOT accepted — they are the axes being
-     * counted, so narrowing by them would report the answer back to itself.
+     * `status`, `origin` and the page bounds are accepted (the route takes the same filter) but
+     * deliberately DROPPED before counting — they are the axes being counted, so narrowing by them
+     * would report the answer back to itself.
      */
-    facets(workflow?: string, tag?: string, attr?: string | string[], namespace?: string): Promise<_dudousxd_nestjs_durable_core.RunFacetRow[]>;
+    facets(draft: RunQueryDraft): Promise<_dudousxd_nestjs_durable_core.RunFacetRow[]>;
+    /**
+     * The distinct values one filter field takes across the runs matching every OTHER active
+     * predicate, with counts — what the console's tenant/tag/attribute pickers list.
+     *
+     * `?groupByCount[field]=tag&groupByCount[limit]=20`, with the filters in the structured
+     * `filter[where][...]` form (what `filterQuery()` builds). Scoping the values to the active
+     * filters is the point: picking a tenant leaves the tag picker offering only that tenant's tags,
+     * so a picker never offers a value whose result set is empty.
+     *
+     * `limit` matters rather than being a nicety — tag and attribute cardinality grows with the data
+     * (a `singleton:<key>` tag is minted per key), so the unbounded answer is a listing.
+     */
+    values(query: Record<string, unknown>): Promise<_dudousxd_nestjs_filter.GroupByCountResult>;
     /** Prometheus-text metrics (runs/steps by outcome, per-workflow counts) for a scrape. */
     metrics(): Promise<string>;
     /** Per-group worker health (queue backlog + live worker heartbeats) for the Workers panel. */
@@ -256,7 +302,7 @@ declare class DurableApiController {
      * The filter takes the SAME params as `GET runs` and is parsed identically, so "retry all" acts on
      * exactly the set the operator was looking at rather than a wider one.
      */
-    bulk(action: 'retry' | 'cancel', status?: RunStatus, tag?: string, workflow?: string, attr?: string | string[], compensate?: string, namespace?: string, origin?: string, unattributed?: string): Promise<{
+    bulk(action: 'retry' | 'cancel', draft: RunQueryDraft, compensate?: string): Promise<{
         matched: number;
         applied: number;
     }>;
@@ -402,6 +448,24 @@ interface DurableDashboardOptions {
      * (e.g. an `EntityManager` to look up an admin user).
      */
     dashboardAuth?: DashboardAuthOptions;
+    /**
+     * Who registers `@dudousxd/nestjs-filter`'s core — the console's run filters are written with it.
+     *
+     * - `'bootstrap'` (default): this module calls `FilterModule.forRoot()` itself, so the console
+     *   works in an app that has never heard of the filter library.
+     * - `'host'`: your app already calls `FilterModule.forRoot(...)`; this module registers only its
+     *   own filter and adapter.
+     *
+     * It has to be YOUR call rather than something detected, because `forRoot` is a GLOBAL
+     * registration: called twice, the second one's module options (validation policy, input format,
+     * page-size ceiling) shadow the first's, and the app-wide interceptor is registered twice. There
+     * is no moment at module-definition time when this module could see whether you have called it.
+     *
+     * Only the core is shared. The console's adapter never is: `RunFilter` names its own via
+     * `@Filterable({ adapter })`, so your global adapter (your ORM's) keeps answering for your filters
+     * and the run gateway answers for the console's, in the same process.
+     */
+    filterModule?: 'bootstrap' | 'host';
 }
 /**
  * Async variant of {@link DurableDashboardOptions}. The mount paths and `guards` stay static (the
@@ -416,6 +480,8 @@ interface DurableDashboardAsyncOptions {
     apiBasePath?: string;
     guards?: Type<CanActivate>[];
     imports?: DynamicModule['imports'];
+    /** See {@link DurableDashboardOptions.filterModule}. */
+    filterModule?: 'bootstrap' | 'host';
     /** Providers injected into `useDashboardAuth`, in order. Shared with a `guards` class's own deps. */
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
     /** Build the `dashboardAuth` config from injected deps (or `undefined` to leave the console open). */
@@ -439,6 +505,8 @@ declare class DurableApiModule {
          *  (true whenever `dashboardAuth` was set, or unconditionally for `forRootAsync`, where it's
          *  resolved at runtime and is a no-op if it ends up unconfigured). */
         authMayBeConfigured: boolean;
+        /** See {@link DurableDashboardOptions.filterModule}. */
+        filterModule?: 'bootstrap' | 'host';
     }): DynamicModule;
 }
 /**