@dudousxd/nestjs-durable-store-mikro-orm 0.25.0 → 0.27.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as _mikro_orm_core from '@mikro-orm/core';
 import { EntityRepository, EntityRepositoryType, EntitySchema, MikroORM } from '@mikro-orm/core';
-import { StepKind, RunStatus, StateStore, WorkflowRun, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, SignalWaiter } from '@dudousxd/nestjs-durable-core';
+import { StepKind, RunStatus, StateStore, WorkflowRun, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, SignalWaiter } from '@dudousxd/nestjs-durable-core';
 
 /**
  * Custom repositories for the durable entities, so a host app can `@InjectRepository`/inject a
@@ -29,6 +29,8 @@ declare class BufferedSignalRepository extends EntityRepository<BufferedSignalEn
 }
 declare class BufferedEventRepository extends EntityRepository<BufferedEventEntity> {
 }
+declare class ScheduleRepository extends EntityRepository<ScheduleEntity> {
+}
 
 /**
  * How property names map to physical column names. The durable tables are adapter-agnostic: a run
@@ -121,6 +123,22 @@ declare class BufferedEventEntity {
     payload?: unknown;
     publishedAt: Date;
 }
+/** A persisted schedule (`engine.schedules`). `spec`/`state` are engine-owned JSON documents. */
+declare class ScheduleEntity {
+    [EntityRepositoryType]?: ScheduleRepository;
+    id: string;
+    namespace: string;
+    workflow: string;
+    paused: boolean;
+    /** Epoch ms as a `bigint` column — exact, so `updateSchedule`'s compare-and-set can't be defeated
+     *  by a DATETIME's truncated milliseconds. Drivers may hand it back as a string. */
+    nextFireAt?: number | string | bigint | null;
+    tags?: string[] | null;
+    spec: Record<string, unknown>;
+    state: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
 declare function durableEntities(options?: {
     naming?: DurableColumnNaming;
 }): EntitySchema[];
@@ -174,6 +192,7 @@ declare class MikroOrmStateStore implements StateStore {
     private reindexAttributes;
     getRun(runId: string): Promise<WorkflowRun | null>;
     deleteRun(runId: string): Promise<void>;
+    deleteRuns(runIds: string[]): Promise<void>;
     pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
@@ -199,26 +218,45 @@ declare class MikroOrmStateStore implements StateStore {
     /** `tags LIKE '%"etl"%'` — the quoted token, so `etl` doesn't match `etl-foo`. See the note in
      *  {@link listRuns} for why this is raw SQL rather than a MikroORM condition. */
     private tagLikeSql;
+    countRuns(query: Omit<RunQuery, 'limit' | 'offset'>): Promise<number>;
     /** `GROUP BY status, origin` over the same predicates {@link listRuns} pages — one aggregate, so a
      *  console can show whole-set counts next to a bounded page instead of downloading every run to
      *  count them in the browser. */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
-    /** Distinct values of one filter axis over the same predicates {@link listRuns} pages. A run-table
-     *  column is a `GROUP BY` like {@link runFacets}, exact over the whole matching set; the tag and
-     *  attribute axes live outside the row (json array / side table) and are counted from a bounded
-     *  page of runs instead — see {@link RunValueFacetOptions.scan}. */
-    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /**
-     * The axes whose values do not live in a column of the run row: `tag` (inside a JSON array) and the
-     * two search-attribute axes (a side table). Both read the newest `scan` matching runs.
+     * Distinct values of one filter axis over the same predicates {@link listRuns} pages, with counts —
+     * what a console's value pickers list.
+     *
+     * All three axis families are answered by ONE grouped query against the filtered run set, so the
+     * counts are exact over that whole set (not a sample), the ordering is stable, and a picker can
+     * page and search server-side. That last part is what makes a picker usable on the axis that needs
+     * it most: tag cardinality grows with the data, so the values an operator is looking for are
+     * routinely outside any top slice, and a search that only filtered the fetched page could never
+     * find them.
      *
-     * Neither reads a run's PAYLOAD. The obvious implementation — page `listRuns` and count in
-     * memory — pulls `input`, `output` and `error` for every run in the window, which on a control
-     * plane with real payloads is tens of megabytes fetched to produce a list of a hundred short
-     * strings, every time a picker opens. These project the one column each question needs instead:
-     * the tags column, or the run ids that then drive one grouped read of the side table.
+     * The predicates come from {@link runQueryBuilder} as a subquery rather than being rewritten here,
+     * so a picker and the list it filters can never disagree about which runs they are talking about.
+     */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
+    /** The filtered run set as a derived table, carrying only the columns the axis needs. One source
+     *  of truth with `listRuns`: the same builder, the same predicates. */
+    private runSubquery;
+    /** Where the values of an axis come from, and how to name one — a column of the filtered runs, an
+     *  element of their tags array, or a row of the attribute side table. */
+    private valueSource;
+    /**
+     * The dialect's way of turning a JSON array column into one row per element — the only portable
+     * thing about it being that all three have one. Without it a tag picker cannot be grouped in the
+     * database at all, and falls back to deduping a bounded page of runs in memory: counts that
+     * describe a sample, and an order that cannot be paged.
      */
-    private scannedValueFacets;
+    private jsonArrayJoin;
+    /** `lower(value) like '%needle%'` — the picker's search box, applied BEFORE the page is cut so a
+     *  match outside the top slice is still reachable. */
+    private searchCondition;
+    /** A grouped value as the string a picker shows. Drivers return a JSON element or a numeric
+     *  attribute as something other than a string; `null` stays null (the absent bucket). */
+    private text;
     /** One attribute predicate as a raw EXISTS subquery on the side-table, correlated to the outer run
      *  alias. `<>` (ne) also excludes runs where the attribute is absent (missing-key-never-matches):
      *  EXISTS already requires a present row, so EXISTS(... <> ...) is exactly ne-with-present. Numeric
@@ -239,6 +277,13 @@ declare class MikroOrmStateStore implements StateStore {
     private jsonAsText;
     /** Quote an identifier per the active SQL driver (MySQL/MariaDB backtick, others double-quote). */
     private idQuote;
+    saveSchedule(record: ScheduleRecord): Promise<void>;
+    getSchedule(id: string): Promise<ScheduleRecord | null>;
+    /** One conditional `nativeUpdate`: the compare-and-set on `next_fire_at` (an exact bigint) is a
+     *  single statement. */
+    updateSchedule(id: string, patch: Partial<Omit<ScheduleRecord, 'id' | 'createdAt'>>, expectedNextFireAt?: number | null): Promise<boolean>;
+    deleteSchedule(id: string): Promise<boolean>;
+    listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
@@ -309,4 +354,4 @@ declare function durableManagedTables(): string[];
  */
 declare function ensureMikroOrmDurableSchema(orm: MikroORM): Promise<void>;
 
-export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, type DurableColumnNaming, ENTITIES, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema };
+export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, type DurableColumnNaming, ENTITIES, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, ScheduleEntity, ScheduleRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _mikro_orm_core from '@mikro-orm/core';
 import { EntityRepository, EntityRepositoryType, EntitySchema, MikroORM } from '@mikro-orm/core';
-import { StepKind, RunStatus, StateStore, WorkflowRun, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, SignalWaiter } from '@dudousxd/nestjs-durable-core';
+import { StepKind, RunStatus, StateStore, WorkflowRun, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, SignalWaiter } from '@dudousxd/nestjs-durable-core';
 
 /**
  * Custom repositories for the durable entities, so a host app can `@InjectRepository`/inject a
@@ -29,6 +29,8 @@ declare class BufferedSignalRepository extends EntityRepository<BufferedSignalEn
 }
 declare class BufferedEventRepository extends EntityRepository<BufferedEventEntity> {
 }
+declare class ScheduleRepository extends EntityRepository<ScheduleEntity> {
+}
 
 /**
  * How property names map to physical column names. The durable tables are adapter-agnostic: a run
@@ -121,6 +123,22 @@ declare class BufferedEventEntity {
     payload?: unknown;
     publishedAt: Date;
 }
+/** A persisted schedule (`engine.schedules`). `spec`/`state` are engine-owned JSON documents. */
+declare class ScheduleEntity {
+    [EntityRepositoryType]?: ScheduleRepository;
+    id: string;
+    namespace: string;
+    workflow: string;
+    paused: boolean;
+    /** Epoch ms as a `bigint` column — exact, so `updateSchedule`'s compare-and-set can't be defeated
+     *  by a DATETIME's truncated milliseconds. Drivers may hand it back as a string. */
+    nextFireAt?: number | string | bigint | null;
+    tags?: string[] | null;
+    spec: Record<string, unknown>;
+    state: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
 declare function durableEntities(options?: {
     naming?: DurableColumnNaming;
 }): EntitySchema[];
@@ -174,6 +192,7 @@ declare class MikroOrmStateStore implements StateStore {
     private reindexAttributes;
     getRun(runId: string): Promise<WorkflowRun | null>;
     deleteRun(runId: string): Promise<void>;
+    deleteRuns(runIds: string[]): Promise<void>;
     pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
@@ -199,26 +218,45 @@ declare class MikroOrmStateStore implements StateStore {
     /** `tags LIKE '%"etl"%'` — the quoted token, so `etl` doesn't match `etl-foo`. See the note in
      *  {@link listRuns} for why this is raw SQL rather than a MikroORM condition. */
     private tagLikeSql;
+    countRuns(query: Omit<RunQuery, 'limit' | 'offset'>): Promise<number>;
     /** `GROUP BY status, origin` over the same predicates {@link listRuns} pages — one aggregate, so a
      *  console can show whole-set counts next to a bounded page instead of downloading every run to
      *  count them in the browser. */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
-    /** Distinct values of one filter axis over the same predicates {@link listRuns} pages. A run-table
-     *  column is a `GROUP BY` like {@link runFacets}, exact over the whole matching set; the tag and
-     *  attribute axes live outside the row (json array / side table) and are counted from a bounded
-     *  page of runs instead — see {@link RunValueFacetOptions.scan}. */
-    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /**
-     * The axes whose values do not live in a column of the run row: `tag` (inside a JSON array) and the
-     * two search-attribute axes (a side table). Both read the newest `scan` matching runs.
+     * Distinct values of one filter axis over the same predicates {@link listRuns} pages, with counts —
+     * what a console's value pickers list.
+     *
+     * All three axis families are answered by ONE grouped query against the filtered run set, so the
+     * counts are exact over that whole set (not a sample), the ordering is stable, and a picker can
+     * page and search server-side. That last part is what makes a picker usable on the axis that needs
+     * it most: tag cardinality grows with the data, so the values an operator is looking for are
+     * routinely outside any top slice, and a search that only filtered the fetched page could never
+     * find them.
      *
-     * Neither reads a run's PAYLOAD. The obvious implementation — page `listRuns` and count in
-     * memory — pulls `input`, `output` and `error` for every run in the window, which on a control
-     * plane with real payloads is tens of megabytes fetched to produce a list of a hundred short
-     * strings, every time a picker opens. These project the one column each question needs instead:
-     * the tags column, or the run ids that then drive one grouped read of the side table.
+     * The predicates come from {@link runQueryBuilder} as a subquery rather than being rewritten here,
+     * so a picker and the list it filters can never disagree about which runs they are talking about.
+     */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
+    /** The filtered run set as a derived table, carrying only the columns the axis needs. One source
+     *  of truth with `listRuns`: the same builder, the same predicates. */
+    private runSubquery;
+    /** Where the values of an axis come from, and how to name one — a column of the filtered runs, an
+     *  element of their tags array, or a row of the attribute side table. */
+    private valueSource;
+    /**
+     * The dialect's way of turning a JSON array column into one row per element — the only portable
+     * thing about it being that all three have one. Without it a tag picker cannot be grouped in the
+     * database at all, and falls back to deduping a bounded page of runs in memory: counts that
+     * describe a sample, and an order that cannot be paged.
      */
-    private scannedValueFacets;
+    private jsonArrayJoin;
+    /** `lower(value) like '%needle%'` — the picker's search box, applied BEFORE the page is cut so a
+     *  match outside the top slice is still reachable. */
+    private searchCondition;
+    /** A grouped value as the string a picker shows. Drivers return a JSON element or a numeric
+     *  attribute as something other than a string; `null` stays null (the absent bucket). */
+    private text;
     /** One attribute predicate as a raw EXISTS subquery on the side-table, correlated to the outer run
      *  alias. `<>` (ne) also excludes runs where the attribute is absent (missing-key-never-matches):
      *  EXISTS already requires a present row, so EXISTS(... <> ...) is exactly ne-with-present. Numeric
@@ -239,6 +277,13 @@ declare class MikroOrmStateStore implements StateStore {
     private jsonAsText;
     /** Quote an identifier per the active SQL driver (MySQL/MariaDB backtick, others double-quote). */
     private idQuote;
+    saveSchedule(record: ScheduleRecord): Promise<void>;
+    getSchedule(id: string): Promise<ScheduleRecord | null>;
+    /** One conditional `nativeUpdate`: the compare-and-set on `next_fire_at` (an exact bigint) is a
+     *  single statement. */
+    updateSchedule(id: string, patch: Partial<Omit<ScheduleRecord, 'id' | 'createdAt'>>, expectedNextFireAt?: number | null): Promise<boolean>;
+    deleteSchedule(id: string): Promise<boolean>;
+    listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
@@ -309,4 +354,4 @@ declare function durableManagedTables(): string[];
  */
 declare function ensureMikroOrmDurableSchema(orm: MikroORM): Promise<void>;
 
-export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, type DurableColumnNaming, ENTITIES, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema };
+export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, type DurableColumnNaming, ENTITIES, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, ScheduleEntity, ScheduleRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema };