@okf/ootils 1.39.3 → 1.40.0

package/dist/node.d.mts

@@ -3,6 +3,7 @@ import * as mongoose from 'mongoose';
 import mongoose__default, { Document, Types, Schema } from 'mongoose';
 import * as bullmq from 'bullmq';
 import { Queue } from 'bullmq/dist/esm/classes/queue';
+import { FlowProducer } from 'bullmq/dist/esm/classes/flow-producer';
 import { Worker } from 'bullmq/dist/esm/classes/worker';
 
 declare const deleteVal: (data: any, valuePath: string) => any;
@@ -2592,6 +2593,100 @@ declare class BaseProducer {
     stop(): Promise<void>;
 }
 
+/**
+ * BaseFlowProducer — the flow-equivalent of BaseProducer.
+ *
+ * A BullMQ Flow adds its parent + children jobs straight into each queue's
+ * Redis keys WITHOUT going through a Queue instance. That means flow nodes do
+ * NOT inherit their queue's `defaultJobOptions` the way `BaseProducer` jobs do
+ * (BaseProducer gets them for free via `new Queue(id, queueConfig)`). Left
+ * unhandled, options like removeOnComplete/removeOnFail are never applied and
+ * completed/failed jobs accumulate unbounded.
+ *
+ * This base centralises the one thing that must happen for every flow: each
+ * node's `opts` is layered as `{ ...queueDefaultJobOptions, ...nodeOpts }`,
+ * mirroring exactly how BullMQ layers defaultJobOptions under per-`add` opts
+ * for normal queues. So subclasses declare ONLY structure + job-specific opts
+ * (e.g. failParentOnFailure); retention and other defaults flow from the same
+ * GLOBAL_BULLMQ_CONFIG that the queues/workers already read — single source of
+ * truth, no per-call-site restatement.
+ *
+ * Construction takes the SAME config objects (entries of GET_GLOBAL_BULLMQ_CONFIG)
+ * that BaseProducer/BaseWorker consume, so a flow is configured declaratively
+ * alongside its queues.
+ *
+ * @param {Object} params
+ * @param {Object} params.parentConfig
+ * The GLOBAL_BULLMQ_CONFIG entry for the parent queue (has .id, .queueConfig).
+ * @param {Object} params.childConfigs
+ * Map keyed by an arbitrary childKey →
+ * the GLOBAL_BULLMQ_CONFIG entry for that
+ * child queue. Subclasses reference a child
+ * node's queue by this key, never by id.
+ */
+declare class BaseFlowProducer {
+    constructor({ parentConfig, childConfigs }: {
+        parentConfig: any;
+        childConfigs?: {} | undefined;
+    });
+    parentConfig: any;
+    childConfigs: {};
+    flow: FlowProducer;
+    /**
+     * Build & enqueue a flow declaratively.
+     *
+     * @param {Object} params
+     * @param {string} [params.name]        Parent job name.
+     * @param {Object} params.parentData    Parent job data.
+     * @param {Object} [params.parentOpts]  Per-node opts for the parent, layered
+     *                                       over the parent queue's defaults.
+     * @param {Array}  params.children      One entry per child node:
+     *   @param {string} children[].childKey  Key into childConfigs (which queue).
+     *   @param {string} [children[].name]    Child job name.
+     *   @param {Object} children[].data      Child job data.
+     *   @param {Object} [children[].opts]    Job-specific opts (e.g.
+     *                                        failParentOnFailure); layered over
+     *                                        that child queue's defaults.
+     * @returns {Promise<{ parentJobId, childJobIds }>}
+     */
+    addFlow({ name, parentData, parentOpts, children }: {
+        name?: string | undefined;
+        parentData: Object;
+        parentOpts?: Object | undefined;
+        children: any[];
+    }): Promise<{
+        parentJobId: any;
+        childJobIds: any;
+    }>;
+    /**
+     * Find the FIRST parent job in the given states whose data matches the
+     * predicate — e.g. an in-flight lock check ("is a run already pending for
+     * this tenant?"). Opens a short-lived Queue on the parent queue and closes
+     * it before returning, so callers don't have to reach into config internals
+     * to construct one themselves.
+     *
+     * Returns the first match or null. BullMQ can't filter by job.data
+     * server-side, so this still fetches the in-flight set and scans in JS; the
+     * contract is intentionally first-match (not a list) because that's the only
+     * thing the lock-check use case needs.
+     *
+     * @param {Object} params
+     * @param {string[]} params.states
+     *   Job states to scan, e.g. ["waiting", "active", "delayed"].
+     * @param {(data: any, job: any) => boolean} params.matchData
+     *   Required function; receives job.data (and the job). Without it there's
+     *   no meaningful "match", so this throws — returning an arbitrary in-flight
+     *   job would be a silent caller bug.
+     * @returns {Promise<Object|null>} The first matching parent job, or null.
+     */
+    findParentJob({ states, matchData }: {
+        states: string[];
+        matchData: (data: any, job: any) => boolean;
+    }): Promise<Object | null>;
+    stop(): Promise<void>;
+    #private;
+}
+
 declare class BaseWorker {
     constructor(config: any);
     config: any;
@@ -2648,4 +2743,4 @@ declare function GET_GLOBAL_BULLMQ_CONFIG({ env, redisCredentials }: {
     };
 }): Object;
 
-export { AIChatSchema, AnnosElasticSyncProducer, AnnotationSchema, BASE_BULLMQ_CONFIG, BaseProducer, BaseWorker, type BlockCapabilities, type BlockDef, BlockRegistry, CHUNKING_PRESETS, ChunksElasticSyncProducer, ELASTIC_MAPPING_PRESETS, ElasticSearchConnector, FILTER_IDS, GET_GLOBAL_BULLMQ_CONFIG, GeneratedEntitiesSchema, GeneratedTopicsSchema, MONGO_SCHEMA_PRESETS, MongoConnector, PlatformConfigsSchema, ProducerManager, RedisCacheConnector, SecretManagerConnector, TEMP_removeDuplicateFilters, TplSchema, UI_CONTENT, WorkerManager, _self_managed_buildAnnoHierarchyConfig, _self_managed_buildDocHierarchyConfig, _self_managed_getFixedAnnoRollupBlocks, _self_managed_getFixedAnnoTagBlock, autoGenFilterConfigsFromTpl, blockRegistry, buildFilterConfigurations, collectMarkIdsInOrder, compareAndGroupBlocks, deleteVal, extractAllBlocksFromTpl, extractAndOrganizeBlocks, genCleanCamelCaseId, genTagId, generateFilterKey, getAIChatModelByTenant, getAnnoFilterBucketKey, getAnnotationsModelByTenant, getDbByTenant, getFilterKeyForBlock, getGeneratedEntitiesModelByTenant, getGeneratedTopicsModelByTenant, getModelByTenant, getPlatformConfigsModelByTenant, getPlatformContextContent, getRollupPossibilities, getRoutePathToContentTypeLanding, getRoutePathToEditContent, getRoutePathToModerateContent, getRoutePathToMyContent, getRoutePathToPublishedContent, getRoutePathToReviewDashboard, getRoutePathToTCI, getRoutePathToTagCategoryLanding, getTplModelByTenant, getVal, isTplAnnotationEnabled, mergeAnnoDataIntoAnnotationsTags, parseSpecialConfigSyntax, plainTextToLexical, processAuthorAndCommonFilters, _recursExtractBlocks as recursivelyExtractBlocks, segrigateDocs, setVal, toArray };
+export { AIChatSchema, AnnosElasticSyncProducer, AnnotationSchema, BASE_BULLMQ_CONFIG, BaseFlowProducer, BaseProducer, BaseWorker, type BlockCapabilities, type BlockDef, BlockRegistry, CHUNKING_PRESETS, ChunksElasticSyncProducer, ELASTIC_MAPPING_PRESETS, ElasticSearchConnector, FILTER_IDS, GET_GLOBAL_BULLMQ_CONFIG, GeneratedEntitiesSchema, GeneratedTopicsSchema, MONGO_SCHEMA_PRESETS, MongoConnector, PlatformConfigsSchema, ProducerManager, RedisCacheConnector, SecretManagerConnector, TEMP_removeDuplicateFilters, TplSchema, UI_CONTENT, WorkerManager, _self_managed_buildAnnoHierarchyConfig, _self_managed_buildDocHierarchyConfig, _self_managed_getFixedAnnoRollupBlocks, _self_managed_getFixedAnnoTagBlock, autoGenFilterConfigsFromTpl, blockRegistry, buildFilterConfigurations, collectMarkIdsInOrder, compareAndGroupBlocks, deleteVal, extractAllBlocksFromTpl, extractAndOrganizeBlocks, genCleanCamelCaseId, genTagId, generateFilterKey, getAIChatModelByTenant, getAnnoFilterBucketKey, getAnnotationsModelByTenant, getDbByTenant, getFilterKeyForBlock, getGeneratedEntitiesModelByTenant, getGeneratedTopicsModelByTenant, getModelByTenant, getPlatformConfigsModelByTenant, getPlatformContextContent, getRollupPossibilities, getRoutePathToContentTypeLanding, getRoutePathToEditContent, getRoutePathToModerateContent, getRoutePathToMyContent, getRoutePathToPublishedContent, getRoutePathToReviewDashboard, getRoutePathToTCI, getRoutePathToTagCategoryLanding, getTplModelByTenant, getVal, isTplAnnotationEnabled, mergeAnnoDataIntoAnnotationsTags, parseSpecialConfigSyntax, plainTextToLexical, processAuthorAndCommonFilters, _recursExtractBlocks as recursivelyExtractBlocks, segrigateDocs, setVal, toArray };

package/dist/node.d.ts

@@ -3,6 +3,7 @@ import * as mongoose from 'mongoose';
 import mongoose__default, { Document, Types, Schema } from 'mongoose';
 import * as bullmq from 'bullmq';
 import { Queue } from 'bullmq/dist/esm/classes/queue';
+import { FlowProducer } from 'bullmq/dist/esm/classes/flow-producer';
 import { Worker } from 'bullmq/dist/esm/classes/worker';
 
 declare const deleteVal: (data: any, valuePath: string) => any;
@@ -2592,6 +2593,100 @@ declare class BaseProducer {
     stop(): Promise<void>;
 }
 
+/**
+ * BaseFlowProducer — the flow-equivalent of BaseProducer.
+ *
+ * A BullMQ Flow adds its parent + children jobs straight into each queue's
+ * Redis keys WITHOUT going through a Queue instance. That means flow nodes do
+ * NOT inherit their queue's `defaultJobOptions` the way `BaseProducer` jobs do
+ * (BaseProducer gets them for free via `new Queue(id, queueConfig)`). Left
+ * unhandled, options like removeOnComplete/removeOnFail are never applied and
+ * completed/failed jobs accumulate unbounded.
+ *
+ * This base centralises the one thing that must happen for every flow: each
+ * node's `opts` is layered as `{ ...queueDefaultJobOptions, ...nodeOpts }`,
+ * mirroring exactly how BullMQ layers defaultJobOptions under per-`add` opts
+ * for normal queues. So subclasses declare ONLY structure + job-specific opts
+ * (e.g. failParentOnFailure); retention and other defaults flow from the same
+ * GLOBAL_BULLMQ_CONFIG that the queues/workers already read — single source of
+ * truth, no per-call-site restatement.
+ *
+ * Construction takes the SAME config objects (entries of GET_GLOBAL_BULLMQ_CONFIG)
+ * that BaseProducer/BaseWorker consume, so a flow is configured declaratively
+ * alongside its queues.
+ *
+ * @param {Object} params
+ * @param {Object} params.parentConfig
+ * The GLOBAL_BULLMQ_CONFIG entry for the parent queue (has .id, .queueConfig).
+ * @param {Object} params.childConfigs
+ * Map keyed by an arbitrary childKey →
+ * the GLOBAL_BULLMQ_CONFIG entry for that
+ * child queue. Subclasses reference a child
+ * node's queue by this key, never by id.
+ */
+declare class BaseFlowProducer {
+    constructor({ parentConfig, childConfigs }: {
+        parentConfig: any;
+        childConfigs?: {} | undefined;
+    });
+    parentConfig: any;
+    childConfigs: {};
+    flow: FlowProducer;
+    /**
+     * Build & enqueue a flow declaratively.
+     *
+     * @param {Object} params
+     * @param {string} [params.name]        Parent job name.
+     * @param {Object} params.parentData    Parent job data.
+     * @param {Object} [params.parentOpts]  Per-node opts for the parent, layered
+     *                                       over the parent queue's defaults.
+     * @param {Array}  params.children      One entry per child node:
+     *   @param {string} children[].childKey  Key into childConfigs (which queue).
+     *   @param {string} [children[].name]    Child job name.
+     *   @param {Object} children[].data      Child job data.
+     *   @param {Object} [children[].opts]    Job-specific opts (e.g.
+     *                                        failParentOnFailure); layered over
+     *                                        that child queue's defaults.
+     * @returns {Promise<{ parentJobId, childJobIds }>}
+     */
+    addFlow({ name, parentData, parentOpts, children }: {
+        name?: string | undefined;
+        parentData: Object;
+        parentOpts?: Object | undefined;
+        children: any[];
+    }): Promise<{
+        parentJobId: any;
+        childJobIds: any;
+    }>;
+    /**
+     * Find the FIRST parent job in the given states whose data matches the
+     * predicate — e.g. an in-flight lock check ("is a run already pending for
+     * this tenant?"). Opens a short-lived Queue on the parent queue and closes
+     * it before returning, so callers don't have to reach into config internals
+     * to construct one themselves.
+     *
+     * Returns the first match or null. BullMQ can't filter by job.data
+     * server-side, so this still fetches the in-flight set and scans in JS; the
+     * contract is intentionally first-match (not a list) because that's the only
+     * thing the lock-check use case needs.
+     *
+     * @param {Object} params
+     * @param {string[]} params.states
+     *   Job states to scan, e.g. ["waiting", "active", "delayed"].
+     * @param {(data: any, job: any) => boolean} params.matchData
+     *   Required function; receives job.data (and the job). Without it there's
+     *   no meaningful "match", so this throws — returning an arbitrary in-flight
+     *   job would be a silent caller bug.
+     * @returns {Promise<Object|null>} The first matching parent job, or null.
+     */
+    findParentJob({ states, matchData }: {
+        states: string[];
+        matchData: (data: any, job: any) => boolean;
+    }): Promise<Object | null>;
+    stop(): Promise<void>;
+    #private;
+}
+
 declare class BaseWorker {
     constructor(config: any);
     config: any;
@@ -2648,4 +2743,4 @@ declare function GET_GLOBAL_BULLMQ_CONFIG({ env, redisCredentials }: {
     };
 }): Object;
 
-export { AIChatSchema, AnnosElasticSyncProducer, AnnotationSchema, BASE_BULLMQ_CONFIG, BaseProducer, BaseWorker, type BlockCapabilities, type BlockDef, BlockRegistry, CHUNKING_PRESETS, ChunksElasticSyncProducer, ELASTIC_MAPPING_PRESETS, ElasticSearchConnector, FILTER_IDS, GET_GLOBAL_BULLMQ_CONFIG, GeneratedEntitiesSchema, GeneratedTopicsSchema, MONGO_SCHEMA_PRESETS, MongoConnector, PlatformConfigsSchema, ProducerManager, RedisCacheConnector, SecretManagerConnector, TEMP_removeDuplicateFilters, TplSchema, UI_CONTENT, WorkerManager, _self_managed_buildAnnoHierarchyConfig, _self_managed_buildDocHierarchyConfig, _self_managed_getFixedAnnoRollupBlocks, _self_managed_getFixedAnnoTagBlock, autoGenFilterConfigsFromTpl, blockRegistry, buildFilterConfigurations, collectMarkIdsInOrder, compareAndGroupBlocks, deleteVal, extractAllBlocksFromTpl, extractAndOrganizeBlocks, genCleanCamelCaseId, genTagId, generateFilterKey, getAIChatModelByTenant, getAnnoFilterBucketKey, getAnnotationsModelByTenant, getDbByTenant, getFilterKeyForBlock, getGeneratedEntitiesModelByTenant, getGeneratedTopicsModelByTenant, getModelByTenant, getPlatformConfigsModelByTenant, getPlatformContextContent, getRollupPossibilities, getRoutePathToContentTypeLanding, getRoutePathToEditContent, getRoutePathToModerateContent, getRoutePathToMyContent, getRoutePathToPublishedContent, getRoutePathToReviewDashboard, getRoutePathToTCI, getRoutePathToTagCategoryLanding, getTplModelByTenant, getVal, isTplAnnotationEnabled, mergeAnnoDataIntoAnnotationsTags, parseSpecialConfigSyntax, plainTextToLexical, processAuthorAndCommonFilters, _recursExtractBlocks as recursivelyExtractBlocks, segrigateDocs, setVal, toArray };
+export { AIChatSchema, AnnosElasticSyncProducer, AnnotationSchema, BASE_BULLMQ_CONFIG, BaseFlowProducer, BaseProducer, BaseWorker, type BlockCapabilities, type BlockDef, BlockRegistry, CHUNKING_PRESETS, ChunksElasticSyncProducer, ELASTIC_MAPPING_PRESETS, ElasticSearchConnector, FILTER_IDS, GET_GLOBAL_BULLMQ_CONFIG, GeneratedEntitiesSchema, GeneratedTopicsSchema, MONGO_SCHEMA_PRESETS, MongoConnector, PlatformConfigsSchema, ProducerManager, RedisCacheConnector, SecretManagerConnector, TEMP_removeDuplicateFilters, TplSchema, UI_CONTENT, WorkerManager, _self_managed_buildAnnoHierarchyConfig, _self_managed_buildDocHierarchyConfig, _self_managed_getFixedAnnoRollupBlocks, _self_managed_getFixedAnnoTagBlock, autoGenFilterConfigsFromTpl, blockRegistry, buildFilterConfigurations, collectMarkIdsInOrder, compareAndGroupBlocks, deleteVal, extractAllBlocksFromTpl, extractAndOrganizeBlocks, genCleanCamelCaseId, genTagId, generateFilterKey, getAIChatModelByTenant, getAnnoFilterBucketKey, getAnnotationsModelByTenant, getDbByTenant, getFilterKeyForBlock, getGeneratedEntitiesModelByTenant, getGeneratedTopicsModelByTenant, getModelByTenant, getPlatformConfigsModelByTenant, getPlatformContextContent, getRollupPossibilities, getRoutePathToContentTypeLanding, getRoutePathToEditContent, getRoutePathToModerateContent, getRoutePathToMyContent, getRoutePathToPublishedContent, getRoutePathToReviewDashboard, getRoutePathToTCI, getRoutePathToTagCategoryLanding, getTplModelByTenant, getVal, isTplAnnotationEnabled, mergeAnnoDataIntoAnnotationsTags, parseSpecialConfigSyntax, plainTextToLexical, processAuthorAndCommonFilters, _recursExtractBlocks as recursivelyExtractBlocks, segrigateDocs, setVal, toArray };

package/dist/node.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
@@ -34,6 +37,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 // src/bullmq/GLOBAL_BULLMQ_CONFIG.js
 var GLOBAL_BULLMQ_CONFIG_exports = {};
@@ -1912,6 +1918,133 @@ var require_BaseProducer = __commonJS({
   }
 });
 
+// src/bullmq/BaseFlowProducer.js
+var require_BaseFlowProducer = __commonJS({
+  "src/bullmq/BaseFlowProducer.js"(exports2, module2) {
+    "use strict";
+    var { FlowProducer, Queue } = require("bullmq");
+    var _BaseFlowProducer_instances, mergeOpts_fn, childConfig_fn;
+    var BaseFlowProducer2 = class {
+      constructor({ parentConfig, childConfigs = {} }) {
+        __privateAdd(this, _BaseFlowProducer_instances);
+        if (!parentConfig) {
+          throw new Error("BaseFlowProducer requires a parentConfig");
+        }
+        this.parentConfig = parentConfig;
+        this.childConfigs = childConfigs;
+        this.flow = new FlowProducer({
+          connection: parentConfig.queueConfig.connection
+        });
+      }
+      /**
+       * Build & enqueue a flow declaratively.
+       *
+       * @param {Object} params
+       * @param {string} [params.name]        Parent job name.
+       * @param {Object} params.parentData    Parent job data.
+       * @param {Object} [params.parentOpts]  Per-node opts for the parent, layered
+       *                                       over the parent queue's defaults.
+       * @param {Array}  params.children      One entry per child node:
+       *   @param {string} children[].childKey  Key into childConfigs (which queue).
+       *   @param {string} [children[].name]    Child job name.
+       *   @param {Object} children[].data      Child job data.
+       *   @param {Object} [children[].opts]    Job-specific opts (e.g.
+       *                                        failParentOnFailure); layered over
+       *                                        that child queue's defaults.
+       * @returns {Promise<{ parentJobId, childJobIds }>}
+       */
+      async addFlow({ name, parentData, parentOpts = {}, children = [] }) {
+        const flowJob = await this.flow.add({
+          name,
+          queueName: this.parentConfig.id,
+          data: parentData,
+          opts: __privateMethod(this, _BaseFlowProducer_instances, mergeOpts_fn).call(this, this.parentConfig, parentOpts),
+          children: children.map((child) => {
+            const childCfg = __privateMethod(this, _BaseFlowProducer_instances, childConfig_fn).call(this, child.childKey);
+            return {
+              name: child.name,
+              queueName: childCfg.id,
+              data: child.data,
+              opts: __privateMethod(this, _BaseFlowProducer_instances, mergeOpts_fn).call(this, childCfg, child.opts)
+            };
+          })
+        });
+        const parentJobId = flowJob?.job?.id;
+        const childJobIds = (flowJob?.children || []).map((c) => c?.job?.id).filter(Boolean);
+        return { parentJobId, childJobIds };
+      }
+      /**
+       * Find the FIRST parent job in the given states whose data matches the
+       * predicate — e.g. an in-flight lock check ("is a run already pending for
+       * this tenant?"). Opens a short-lived Queue on the parent queue and closes
+       * it before returning, so callers don't have to reach into config internals
+       * to construct one themselves.
+       *
+       * Returns the first match or null. BullMQ can't filter by job.data
+       * server-side, so this still fetches the in-flight set and scans in JS; the
+       * contract is intentionally first-match (not a list) because that's the only
+       * thing the lock-check use case needs.
+       *
+       * @param {Object} params
+       * @param {string[]} params.states
+       *   Job states to scan, e.g. ["waiting", "active", "delayed"].
+       * @param {(data: any, job: any) => boolean} params.matchData
+       *   Required function; receives job.data (and the job). Without it there's
+       *   no meaningful "match", so this throws — returning an arbitrary in-flight
+       *   job would be a silent caller bug.
+       * @returns {Promise<Object|null>} The first matching parent job, or null.
+       */
+      async findParentJob({ states, matchData }) {
+        if (typeof matchData !== "function") {
+          throw new Error("BaseFlowProducer.findParentJob requires a matchData function");
+        }
+        const parentQueue = new Queue(
+          this.parentConfig.id,
+          this.parentConfig.queueConfig
+        );
+        try {
+          const jobs = await parentQueue.getJobs(states, 0, -1);
+          return jobs.find((job) => matchData(job?.data, job)) || null;
+        } finally {
+          await parentQueue.close();
+        }
+      }
+      async stop() {
+        if (this.flow) {
+          try {
+            await this.flow.close();
+          } catch (err) {
+            console.warn(`[${this.constructor.name}] flow close failed: ${err.message}`);
+          }
+        }
+      }
+    };
+    _BaseFlowProducer_instances = new WeakSet();
+    /**
+     * Layer a queue config's defaultJobOptions under per-node opts — identical
+     * to how BullMQ merges defaultJobOptions under per-`add` opts for a Queue.
+     * Config is the base; anything the node explicitly sets wins.
+     */
+    mergeOpts_fn = function(queueConfig, nodeOpts = {}) {
+      const defaults = queueConfig?.queueConfig?.defaultJobOptions || {};
+      return { ...defaults, ...nodeOpts };
+    };
+    /**
+     * Resolve the GLOBAL_BULLMQ_CONFIG entry for a declared child key.
+     */
+    childConfig_fn = function(childKey) {
+      const cfg = this.childConfigs[childKey];
+      if (!cfg) {
+        throw new Error(
+          `BaseFlowProducer: no child queue declared under key "${childKey}". Declared keys: [${Object.keys(this.childConfigs).join(", ")}]`
+        );
+      }
+      return cfg;
+    };
+    module2.exports = { BaseFlowProducer: BaseFlowProducer2 };
+  }
+});
+
 // src/bullmq/BaseWorker.js
 var require_BaseWorker = __commonJS({
   "src/bullmq/BaseWorker.js"(exports2, module2) {
@@ -2102,6 +2235,7 @@ __export(node_exports, {
   AnnosElasticSyncProducer: () => import_AnnosElasticSyncProducer.AnnosElasticSyncProducer,
   AnnotationSchema: () => Annotations_default,
   BASE_BULLMQ_CONFIG: () => BASE_BULLMQ_CONFIG,
+  BaseFlowProducer: () => import_BaseFlowProducer.BaseFlowProducer,
   BaseProducer: () => import_BaseProducer.BaseProducer,
   BaseWorker: () => import_BaseWorker.BaseWorker,
   BlockRegistry: () => BlockRegistry,
@@ -4767,6 +4901,7 @@ init_models();
 var import_WorkerManager = __toESM(require_WorkerManager());
 var import_ProducerManager = __toESM(require_ProducerManager());
 var import_BaseProducer = __toESM(require_BaseProducer());
+var import_BaseFlowProducer = __toESM(require_BaseFlowProducer());
 var import_BaseWorker = __toESM(require_BaseWorker());
 var import_ChunksElasticSyncProducer = __toESM(require_ChunksElasticSyncProducer());
 var import_AnnosElasticSyncProducer = __toESM(require_AnnosElasticSyncProducer());
@@ -4777,6 +4912,7 @@ var import_GET_GLOBAL_BULLMQ_CONFIG = __toESM(require_GET_GLOBAL_BULLMQ_CONFIG()
   AnnosElasticSyncProducer,
   AnnotationSchema,
   BASE_BULLMQ_CONFIG,
+  BaseFlowProducer,
   BaseProducer,
   BaseWorker,
   BlockRegistry,

package/dist/node.mjs

@@ -4,6 +4,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -39,6 +42,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 // src/bullmq/GLOBAL_BULLMQ_CONFIG.js
 var GLOBAL_BULLMQ_CONFIG_exports = {};
@@ -1917,6 +1923,133 @@ var require_BaseProducer = __commonJS({
   }
 });
 
+// src/bullmq/BaseFlowProducer.js
+var require_BaseFlowProducer = __commonJS({
+  "src/bullmq/BaseFlowProducer.js"(exports, module) {
+    "use strict";
+    var { FlowProducer, Queue } = __require("bullmq");
+    var _BaseFlowProducer_instances, mergeOpts_fn, childConfig_fn;
+    var BaseFlowProducer2 = class {
+      constructor({ parentConfig, childConfigs = {} }) {
+        __privateAdd(this, _BaseFlowProducer_instances);
+        if (!parentConfig) {
+          throw new Error("BaseFlowProducer requires a parentConfig");
+        }
+        this.parentConfig = parentConfig;
+        this.childConfigs = childConfigs;
+        this.flow = new FlowProducer({
+          connection: parentConfig.queueConfig.connection
+        });
+      }
+      /**
+       * Build & enqueue a flow declaratively.
+       *
+       * @param {Object} params
+       * @param {string} [params.name]        Parent job name.
+       * @param {Object} params.parentData    Parent job data.
+       * @param {Object} [params.parentOpts]  Per-node opts for the parent, layered
+       *                                       over the parent queue's defaults.
+       * @param {Array}  params.children      One entry per child node:
+       *   @param {string} children[].childKey  Key into childConfigs (which queue).
+       *   @param {string} [children[].name]    Child job name.
+       *   @param {Object} children[].data      Child job data.
+       *   @param {Object} [children[].opts]    Job-specific opts (e.g.
+       *                                        failParentOnFailure); layered over
+       *                                        that child queue's defaults.
+       * @returns {Promise<{ parentJobId, childJobIds }>}
+       */
+      async addFlow({ name, parentData, parentOpts = {}, children = [] }) {
+        const flowJob = await this.flow.add({
+          name,
+          queueName: this.parentConfig.id,
+          data: parentData,
+          opts: __privateMethod(this, _BaseFlowProducer_instances, mergeOpts_fn).call(this, this.parentConfig, parentOpts),
+          children: children.map((child) => {
+            const childCfg = __privateMethod(this, _BaseFlowProducer_instances, childConfig_fn).call(this, child.childKey);
+            return {
+              name: child.name,
+              queueName: childCfg.id,
+              data: child.data,
+              opts: __privateMethod(this, _BaseFlowProducer_instances, mergeOpts_fn).call(this, childCfg, child.opts)
+            };
+          })
+        });
+        const parentJobId = flowJob?.job?.id;
+        const childJobIds = (flowJob?.children || []).map((c) => c?.job?.id).filter(Boolean);
+        return { parentJobId, childJobIds };
+      }
+      /**
+       * Find the FIRST parent job in the given states whose data matches the
+       * predicate — e.g. an in-flight lock check ("is a run already pending for
+       * this tenant?"). Opens a short-lived Queue on the parent queue and closes
+       * it before returning, so callers don't have to reach into config internals
+       * to construct one themselves.
+       *
+       * Returns the first match or null. BullMQ can't filter by job.data
+       * server-side, so this still fetches the in-flight set and scans in JS; the
+       * contract is intentionally first-match (not a list) because that's the only
+       * thing the lock-check use case needs.
+       *
+       * @param {Object} params
+       * @param {string[]} params.states
+       *   Job states to scan, e.g. ["waiting", "active", "delayed"].
+       * @param {(data: any, job: any) => boolean} params.matchData
+       *   Required function; receives job.data (and the job). Without it there's
+       *   no meaningful "match", so this throws — returning an arbitrary in-flight
+       *   job would be a silent caller bug.
+       * @returns {Promise<Object|null>} The first matching parent job, or null.
+       */
+      async findParentJob({ states, matchData }) {
+        if (typeof matchData !== "function") {
+          throw new Error("BaseFlowProducer.findParentJob requires a matchData function");
+        }
+        const parentQueue = new Queue(
+          this.parentConfig.id,
+          this.parentConfig.queueConfig
+        );
+        try {
+          const jobs = await parentQueue.getJobs(states, 0, -1);
+          return jobs.find((job) => matchData(job?.data, job)) || null;
+        } finally {
+          await parentQueue.close();
+        }
+      }
+      async stop() {
+        if (this.flow) {
+          try {
+            await this.flow.close();
+          } catch (err) {
+            console.warn(`[${this.constructor.name}] flow close failed: ${err.message}`);
+          }
+        }
+      }
+    };
+    _BaseFlowProducer_instances = new WeakSet();
+    /**
+     * Layer a queue config's defaultJobOptions under per-node opts — identical
+     * to how BullMQ merges defaultJobOptions under per-`add` opts for a Queue.
+     * Config is the base; anything the node explicitly sets wins.
+     */
+    mergeOpts_fn = function(queueConfig, nodeOpts = {}) {
+      const defaults = queueConfig?.queueConfig?.defaultJobOptions || {};
+      return { ...defaults, ...nodeOpts };
+    };
+    /**
+     * Resolve the GLOBAL_BULLMQ_CONFIG entry for a declared child key.
+     */
+    childConfig_fn = function(childKey) {
+      const cfg = this.childConfigs[childKey];
+      if (!cfg) {
+        throw new Error(
+          `BaseFlowProducer: no child queue declared under key "${childKey}". Declared keys: [${Object.keys(this.childConfigs).join(", ")}]`
+        );
+      }
+      return cfg;
+    };
+    module.exports = { BaseFlowProducer: BaseFlowProducer2 };
+  }
+});
+
 // src/bullmq/BaseWorker.js
 var require_BaseWorker = __commonJS({
   "src/bullmq/BaseWorker.js"(exports, module) {
@@ -4696,11 +4829,13 @@ init_models();
 var import_WorkerManager = __toESM(require_WorkerManager());
 var import_ProducerManager = __toESM(require_ProducerManager());
 var import_BaseProducer = __toESM(require_BaseProducer());
+var import_BaseFlowProducer = __toESM(require_BaseFlowProducer());
 var import_BaseWorker = __toESM(require_BaseWorker());
 var import_ChunksElasticSyncProducer = __toESM(require_ChunksElasticSyncProducer());
 var import_AnnosElasticSyncProducer = __toESM(require_AnnosElasticSyncProducer());
 var import_GET_GLOBAL_BULLMQ_CONFIG = __toESM(require_GET_GLOBAL_BULLMQ_CONFIG());
 var export_AnnosElasticSyncProducer = import_AnnosElasticSyncProducer.AnnosElasticSyncProducer;
+var export_BaseFlowProducer = import_BaseFlowProducer.BaseFlowProducer;
 var export_BaseProducer = import_BaseProducer.BaseProducer;
 var export_BaseWorker = import_BaseWorker.BaseWorker;
 var export_ChunksElasticSyncProducer = import_ChunksElasticSyncProducer.ChunksElasticSyncProducer;
@@ -4721,6 +4856,7 @@ export {
   export_AnnosElasticSyncProducer as AnnosElasticSyncProducer,
   Annotations_default as AnnotationSchema,
   BASE_BULLMQ_CONFIG,
+  export_BaseFlowProducer as BaseFlowProducer,
   export_BaseProducer as BaseProducer,
   export_BaseWorker as BaseWorker,
   BlockRegistry,

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.39.3",
+  "version": "1.40.0",
   "description": "Utility functions for both browser and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",