@nest-batch/core 0.2.0

package/dist/src/module/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public surface for the `module/` package directory.
+ *
+ * Exports the `NestBatchModule` (the dynamic Nest module), the
+ * `BatchScheduleRegistry` provider, the canonical injection tokens,
+ * and the `BatchAdapter` / `BatchAdaptersConfig` types sibling
+ * packages implement to plug into core.
+ */
+export * from './tokens';
+export * from './adapter-options';
+export * from './adapter';
+export * from './batch-schedule-registry';
+export * from './nest-batch.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/module/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/module/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC"}

package/dist/src/module/index.js

@@ -0,0 +1,31 @@
+/**
+ * Public surface for the `module/` package directory.
+ *
+ * Exports the `NestBatchModule` (the dynamic Nest module), the
+ * `BatchScheduleRegistry` provider, the canonical injection tokens,
+ * and the `BatchAdapter` / `BatchAdaptersConfig` types sibling
+ * packages implement to plug into core.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./tokens"), exports);
+_export_star(require("./adapter-options"), exports);
+_export_star(require("./adapter"), exports);
+_export_star(require("./batch-schedule-registry"), exports);
+_export_star(require("./nest-batch.module"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+
+//# sourceMappingURL=index.js.map

package/dist/src/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/module/index.ts"],"sourcesContent":["/**\n * Public surface for the `module/` package directory.\n *\n * Exports the `NestBatchModule` (the dynamic Nest module), the\n * `BatchScheduleRegistry` provider, the canonical injection tokens,\n * and the `BatchAdapter` / `BatchAdaptersConfig` types sibling\n * packages implement to plug into core.\n */\nexport * from './tokens';\nexport * from './adapter-options';\nexport * from './adapter';\nexport * from './batch-schedule-registry';\nexport * from './nest-batch.module';\n"],"names":[],"mappings":"AAAA;;;;;;;CAOC;;;;qBACa;qBACA;qBACA;qBACA;qBACA"}

package/dist/src/module/nest-batch.module.d.ts

@@ -0,0 +1,236 @@
+import { DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
+import type { BatchAdaptersConfig } from './adapter';
+import { DefinitionCompiler } from '../compiler/definition-compiler';
+import { BatchExplorer } from '../explorer/batch-explorer';
+import { JobRegistry } from '../registry/job-registry';
+import { InProcessExecutionStrategy, IN_PROCESS_EXECUTION_STRATEGY_PROVIDER } from '../execution/in-process-execution-strategy';
+import { BatchScheduleRegistry } from './batch-schedule-registry';
+/**
+ * Re-export the default in-process strategy and its token binding so
+ * the host app can wire them up alongside the rest of the batch
+ * engine. The strategy is *not* auto-registered by
+ * `NestBatchModule.forRoot()` because its constructor requires
+ * `JobRepository` and `JobExecutor` — runtime deps the host
+ * supplies. The T4 `InProcessAdapter` factory does the wiring through
+ * the adapter's own `DynamicModule.exports` so the runtime
+ * resolution chain works without the core module having to know which
+ * adapter is active.
+ *
+ * ```ts
+ * import { InProcessAdapter, MikroOrmAdapter, NestBatchModule } from '@nest-batch/core';
+ *
+ * @Module({
+ *   imports: [
+ *     NestBatchModule.forRoot({
+ *       adapters: {
+ *         persistence: MikroOrmAdapter,
+ *         transport: InProcessAdapter,
+ *       },
+ *     }),
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ */
+export { InProcessExecutionStrategy, IN_PROCESS_EXECUTION_STRATEGY_PROVIDER };
+/**
+ * Options for `NestBatchModule.forRoot()`.
+ *
+ * The whole configuration is the pair of adapters (persistence +
+ * transport) the host picked. Both are required — the compiler
+ * will reject an `adapters` bag that is missing one — and each
+ * adapter is a self-contained `DynamicModule` core will import.
+ * Sibling packages can no longer extend the options shape via
+ * interface merging: the old `AdapterOptions` extension point is
+ * gone because every adapter now owns its own `DynamicModule`
+ * (and therefore its own config). Adapter authors that want
+ * type-safe factory arguments should expose them on their own
+ * adapter factory (e.g. `MikroOrmAdapter.forRoot({ ... })`).
+ *
+ *   - `adapters.persistence` — the adapter that owns the
+ *     `JobRepository` + `TransactionManager` bindings (e.g.
+ *     `MikroOrmAdapter`, `TypeOrmAdapter`).
+ *   - `adapters.transport`   — the adapter that owns the
+ *     `IExecutionStrategy` binding (e.g. `InProcessAdapter`,
+ *     `BullmqAdapter`).
+ */
+export interface NestBatchModuleOptions {
+    readonly adapters: BatchAdaptersConfig;
+}
+/**
+ * Options for `NestBatchModule.forRootAsync()`.
+ *
+ * `imports` + `inject` + `useFactory` mirror the standard
+ * `ConfigurableModuleBuilder` shape. The factory is registered as a
+ * sentinel provider under `OPTIONS_FACTORY` (a `Symbol.for` token
+ * stable across module boundaries), and `MODULE_OPTIONS_TOKEN` is
+ * bound to its resolved `BatchAdaptersConfig` via a follow-up
+ * `useFactory` provider.
+ *
+ * **Note on adapter module merging.** NestJS cannot dynamically
+ * import a `DynamicModule` at module-build time, so the
+ * `forRootAsync` path does NOT auto-merge the adapter modules'
+ * `globalProviders` into the core module's `providers` list the way
+ * `forRoot` does. Two consequences for the async path:
+ *
+ *   1. The adapter `DynamicModule`s must be passed in the caller's
+ *      `imports` array directly (e.g.
+ *      `imports: [MikroOrmAdapter.module, InProcessAdapter.module]`)
+ *      so Nest sees them in the module graph.
+ *   2. The factory's return value is used only for the
+ *      `MODULE_OPTIONS_TOKEN` binding (adapters introspection);
+ *      sibling packages and the host can read the resolved config
+ *      via `@Inject(MODULE_OPTIONS_TOKEN)`.
+ *
+ * For the full auto-merge (adapter modules + `globalProviders`
+ * registered into core's own DI scope), prefer `forRoot` with a
+ * pre-resolved `BatchAdaptersConfig`. The async path is for
+ * adapters whose factory needs to consult a config service or
+ * another async provider to decide which adapter to plug in.
+ */
+export interface NestBatchModuleAsyncOptions {
+    imports?: DynamicModule['imports'];
+    useFactory: (...args: unknown[]) => Promise<BatchAdaptersConfig> | BatchAdaptersConfig;
+    inject?: readonly unknown[];
+}
+/**
+ * Hook that runs on `OnApplicationBootstrap` to wire together the
+ * discovery → compile → register pipeline.
+ *
+ * Why a separate provider and not a method on `JobRegistry` or
+ * `DefinitionCompiler`?
+ *   - `BatchExplorer.onModuleInit` populates the discovered
+ *     list once the DI container is ready. Compilation needs every
+ *     `@Jobable` provider to be instantiated, so it must run *after*
+ *     `onModuleInit`.
+ *   - `OnApplicationBootstrap` is the latest point in Nest's lifecycle
+ *     before the app actually starts handling requests, so all of:
+ *     `forRoot` / `forRootAsync` providers, custom `useFactory` results,
+ *     and user-supplied job classes, are guaranteed to be live.
+ *   - Keeping the wire-up in a dedicated `BatchBootstrapper` means the
+ *     explorer/compiler/registry stay pure (no `onApplicationBootstrap`
+ *     coupling) and are independently testable.
+ *
+ * The bootstrapper also walks every discovered job for
+ * `@BatchScheduled` metadata and registers the corresponding entries
+ * into the `BatchScheduleRegistry` so the (future) runtime scheduler
+ * has a single, stable place to read them from. Today, the registry is
+ * metadata-only — no timers are installed.
+ */
+export declare class BatchBootstrapper implements OnApplicationBootstrap {
+    private readonly explorer;
+    private readonly compiler;
+    private readonly registry;
+    private readonly scheduleRegistry;
+    private readonly logger;
+    constructor(explorer: BatchExplorer, compiler: DefinitionCompiler, registry: JobRegistry, scheduleRegistry: BatchScheduleRegistry);
+    onApplicationBootstrap(): void;
+    /**
+     * Walk the prototype chain and return every own method name
+     * (excluding `constructor`) up to (but not including)
+     * `Object.prototype`. Same shape as `BatchExplorer.allMethodNames` —
+     * we duplicate the walker here so the bootstrapper remains
+     * independent of the explorer's internals.
+     */
+    private allMethodNames;
+}
+/**
+ * Public Nest module that wires up the @nest-batch/core library.
+ *
+ * The module is a `global: true` `DynamicModule` whose `imports`,
+ * `providers`, and `exports` are assembled at the call site by
+ * `forRoot` (synchronous) or `forRootAsync` (sentinel-factory
+ * pattern). In both paths the core providers and the executor
+ * subgraph are auto-registered so the host does not have to wire
+ * them by hand; adapter modules are imported as part of the same
+ * `DynamicModule` so Nest's discovery phase sees every job class.
+ *
+ * @see {@link NestBatchModuleOptions} for the synchronous options shape
+ * @see {@link NestBatchModuleAsyncOptions} for the async options shape
+ * @see {@link BatchAdaptersConfig} for the adapter contract
+ */
+export declare class NestBatchModule {
+    /**
+     * Build a provider list from an adapter's `globalProviders`,
+     * automatically aliasing the abstract `JobRepository` class to
+     * `JOB_REPOSITORY_TOKEN` when the symbol is present but the class
+     * itself is not directly provided.
+     *
+     * This fixes the NestJS DI resolution gap: `JobExecutor`,
+     * `JobLauncher`, and `InProcessExecutionStrategy` all inject the
+     * abstract `JobRepository`, but adapters typically bind their
+     * concrete implementation to `JOB_REPOSITORY_TOKEN`. NestJS cannot
+     * resolve abstract class → concrete subclass automatically, so we
+     * inject the alias here.
+     *
+     * Idempotent: if `JobRepository` is already directly provided (e.g.
+     * `{ provide: JobRepository, useClass: MyRepo }`), no extra alias is
+     * added.
+     */
+    private static buildProviders;
+    /**
+     * Best-effort resolution of `inject` tokens by reading the
+     * `providers` metadata of modules listed in `imports`. This lets
+     * `forRootAsync` evaluate a synchronous `useFactory` even when it
+     * declares `inject` deps, provided those deps are `useValue`
+     * providers exported by an imported module.
+     *
+     * Only `useValue` providers can be resolved this way — `useClass`
+     * and `useFactory` providers need Nest's DI container and are
+     * skipped.
+     */
+    private static resolveInjectValues;
+    /**
+     * Static (synchronous) configuration.
+     *
+     * Takes the resolved `BatchAdaptersConfig` and builds a
+     * `global: true` `DynamicModule` that:
+     *
+     *   1. imports each adapter's `DynamicModule`
+     *      (`adapters.persistence.module` and `adapters.transport.module`);
+     *   2. imports `DiscoveryModule` from `@nestjs/core` so the explorer
+     *      can use Nest's `DiscoveryService`;
+     *   3. registers core's own providers — `JobRegistry`,
+     *      `DefinitionCompiler`, `BatchExplorer`, `FlowEvaluator`,
+     *      `BatchScheduleRegistry`, `BatchBootstrapper` — and the
+     *      executor subgraph (`JobExecutor`, `ChunkStepExecutor`,
+     *      `TaskletStepExecutor`, `ListenerInvoker`) so the host
+     *      does not have to wire them by hand;
+     *   4. registers each adapter's `globalProviders` (e.g. the
+     *      `JobRepository` / `TransactionManager` implementations
+     *      from a persistence adapter) so the host can inject them
+     *      too;
+     *   5. binds the `BatchAdaptersConfig` to `MODULE_OPTIONS_TOKEN`
+     *      via a value provider for adapter introspection.
+     */
+    static forRoot(options: NestBatchModuleOptions): DynamicModule;
+    /**
+     * Async configuration — useful when the adapter set comes from a
+     * config service or another async source.
+     *
+     * Mirrors the `BullmqBatchModule.forRootAsync` pattern: the user's
+     * `useFactory` is registered as a sentinel provider under
+     * `OPTIONS_FACTORY`, and `MODULE_OPTIONS_TOKEN` is bound to its
+     * resolved `BatchAdaptersConfig` via a follow-up `useFactory`
+     * provider. The user's `imports` + `inject` are forwarded as-is
+     * so the factory can pull from `ConfigService` or any other
+     * DI-bound dependency.
+     *
+     * See the `NestBatchModuleAsyncOptions` JSDoc for the adapter
+     * module merging caveat — the async path does not auto-merge
+     * the adapter modules' `globalProviders`. The adapter
+     * `DynamicModule`s must be passed in the caller's `imports`
+     * array so Nest sees them in the module graph; the factory's
+     * return value is used only for `MODULE_OPTIONS_TOKEN`.
+     */
+    static forRootAsync(options: NestBatchModuleAsyncOptions): DynamicModule | Promise<DynamicModule>;
+    /**
+     * Shared module builder used by both the sync and async branches
+     * of `forRootAsync`. When the factory result is available
+     * synchronously we merge adapter `globalProviders` (plus the
+     * `JobRepository` alias) into core's own provider list, exactly
+     * like `forRoot` does.
+     */
+    private static buildAsyncModule;
+}
+//# sourceMappingURL=nest-batch.module.d.ts.map

package/dist/src/module/nest-batch.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-batch.module.d.ts","sourceRoot":"","sources":["../../../src/module/nest-batch.module.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAIb,sBAAsB,EAEvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AASvD,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACvC,MAAM,4CAA4C,CAAC;AAIpD,OAAO,EACL,qBAAqB,EAEtB,MAAM,2BAA2B,CAAC;AAUnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,0BAA0B,EAAE,sCAAsC,EAAE,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,UAAU,EAAE,CACV,GAAG,IAAI,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IACxD,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B;AAgBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,iBAAkB,YAAW,sBAAsB;IAI5D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IANnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;gBAG1C,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,WAAW,EACrB,gBAAgB,EAAE,qBAAqB;IAG1D,sBAAsB,IAAI,IAAI;IA6D9B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAYvB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBACa,eAAe;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAsD7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAmDlC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa;IAsF9D;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,YAAY,CACjB,OAAO,EAAE,2BAA2B,GACnC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBzC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAoGhC"}