@nest-batch/core 0.2.0

package/src/repository/in-memory/in-memory-job-repository.ts

@@ -0,0 +1,334 @@
+import { Injectable } from '@nestjs/common';
+import { JobRepository } from '@nest-batch/core';
+import type {
+  JobInstance,
+  JobExecution,
+  JobExecutionPatch,
+  JobParameters,
+  StepExecution,
+  StepExecutionPatch,
+  ExecutionContext,
+  ExecutionScope,
+  JobInstanceFilter,
+  JobExecutionFilter,
+} from '@nest-batch/core';
+import { JobStatus, StepStatus } from '@nest-batch/core';
+import { JobExecutionAlreadyRunningError } from '@nest-batch/core';
+import { assertJsonSerializable } from '@nest-batch/core';
+import type { IdGenerator } from '../id-generator';
+import { UuidIdGenerator } from '../id-generator';
+
+function deepClone<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Date) return new Date(value.getTime()) as unknown as T;
+  if (Array.isArray(value)) return value.map((v) => deepClone(v)) as unknown as T;
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(value as Record<string, unknown>)) {
+    out[k] = deepClone((value as Record<string, unknown>)[k]);
+  }
+  return out as T;
+}
+
+interface InMemoryState {
+  instances: Map<string, JobInstance>; // key: instanceId
+  instancesByKey: Map<string, JobInstance>; // key: `${name}::${jobKey}`
+  executions: Map<string, JobExecution>;
+  stepExecutions: Map<string, StepExecution>;
+  contexts: Map<string, ExecutionContext>; // key: serialized ExecutionScope
+}
+
+function scopeKey(scope: ExecutionScope): string {
+  if ('jobExecutionId' in scope) return `job::${scope.jobExecutionId}`;
+  return `step::${scope.stepExecutionId}`;
+}
+
+/**
+ * In-memory JobRepository with real-repo semantics:
+ * - deterministic IDs (configurable via IdGenerator)
+ * - deep clone on reads/writes to prevent mutation leaks
+ * - async signatures
+ * - uniqueness on (jobName, jobKey)
+ * - getOrCreateJobInstance / createJobExecution / getRunningJobExecution
+ *   share a single promise-chain lock, so the check-then-create sequence
+ *   used by JobLauncher is race-safe
+ *
+ * restartable: false by default (per Metis directive: in-memory repo is non-restartable
+ * because contexts are lost on process restart).
+ */
+@Injectable()
+export class InMemoryJobRepository extends JobRepository {
+  private readonly state: InMemoryState = {
+    instances: new Map(),
+    instancesByKey: new Map(),
+    executions: new Map(),
+    stepExecutions: new Map(),
+    contexts: new Map(),
+  };
+  /** Promise-chain lock to serialize getOrCreateJobInstance calls. */
+  private lock: Promise<unknown> = Promise.resolve();
+
+  constructor(private readonly idGen: IdGenerator = new UuidIdGenerator()) {
+    super();
+  }
+
+  private async withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const prev = this.lock;
+    let release!: () => void;
+    this.lock = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    try {
+      await prev;
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  async getOrCreateJobInstance(name: string, jobKey: string): Promise<JobInstance> {
+    return this.withLock(async () => {
+      const key = `${name}::${jobKey}`;
+      const existing = this.state.instancesByKey.get(key);
+      if (existing) return deepClone(existing);
+      const inst: JobInstance = {
+        id: this.idGen.next(),
+        jobName: name,
+        jobKey,
+        createdAt: new Date(),
+      };
+      this.state.instances.set(inst.id, inst);
+      this.state.instancesByKey.set(key, inst);
+      return deepClone(inst);
+    });
+  }
+
+  async createJobExecution(jobInstanceId: string, params: JobParameters): Promise<JobExecution> {
+    return this.withLock(async () => {
+      const exec: JobExecution = {
+        id: this.idGen.next(),
+        jobInstanceId,
+        status: JobStatus.STARTING,
+        startTime: null,
+        endTime: null,
+        exitCode: '',
+        exitMessage: '',
+        params: deepClone(params),
+      };
+      this.state.executions.set(exec.id, exec);
+      return deepClone(exec);
+    });
+  }
+
+  async createExecutionAtomic(
+    name: string,
+    jobKey: string,
+    params: JobParameters,
+  ): Promise<JobExecution> {
+    return this.withLock(async () => {
+      const key = `${name}::${jobKey}`;
+      let instance = this.state.instancesByKey.get(key);
+      if (!instance) {
+        instance = {
+          id: this.idGen.next(),
+          jobName: name,
+          jobKey,
+          createdAt: new Date(),
+        };
+        this.state.instances.set(instance.id, instance);
+        this.state.instancesByKey.set(key, instance);
+      }
+      for (const exec of this.state.executions.values()) {
+        if (
+          exec.jobInstanceId === instance.id &&
+          (exec.status === JobStatus.STARTING || exec.status === JobStatus.STARTED)
+        ) {
+          throw new JobExecutionAlreadyRunningError(exec.id);
+        }
+      }
+      const exec: JobExecution = {
+        id: this.idGen.next(),
+        jobInstanceId: instance.id,
+        status: JobStatus.STARTING,
+        startTime: null,
+        endTime: null,
+        exitCode: '',
+        exitMessage: '',
+        params: deepClone(params),
+      };
+      this.state.executions.set(exec.id, exec);
+      return deepClone(exec);
+    });
+  }
+
+  async getRunningJobExecution(jobInstanceId: string): Promise<JobExecution | null> {
+    return this.withLock(async () => {
+      for (const exec of this.state.executions.values()) {
+        if (
+          exec.jobInstanceId === jobInstanceId &&
+          (exec.status === JobStatus.STARTING || exec.status === JobStatus.STARTED)
+        ) {
+          return deepClone(exec);
+        }
+      }
+      return null;
+    });
+  }
+
+  async updateJobExecution(executionId: string, patch: JobExecutionPatch): Promise<void> {
+    const cur = this.state.executions.get(executionId);
+    if (!cur) throw new Error(`JobExecution not found: ${executionId}`);
+    const next: JobExecution = {
+      ...cur,
+      ...patch,
+      startTime: patch.startTime === undefined ? cur.startTime : patch.startTime,
+      endTime: patch.endTime === undefined ? cur.endTime : patch.endTime,
+    };
+    this.state.executions.set(executionId, next);
+  }
+
+  async getJobExecution(executionId: string): Promise<JobExecution | null> {
+    const e = this.state.executions.get(executionId);
+    return e ? deepClone(e) : null;
+  }
+
+  override async getJobInstance(jobInstanceId: string): Promise<JobInstance | null> {
+    const instance = this.state.instances.get(jobInstanceId);
+    return instance ? deepClone(instance) : null;
+  }
+
+  override async findJobInstances(filter: JobInstanceFilter = {}): Promise<JobInstance[]> {
+    const rows: JobInstance[] = [];
+    for (const instance of this.state.instances.values()) {
+      if (filter.jobName !== undefined && instance.jobName !== filter.jobName) continue;
+      if (filter.jobKey !== undefined && instance.jobKey !== filter.jobKey) continue;
+      rows.push(deepClone(instance));
+    }
+    return rows;
+  }
+
+  override async findJobExecutions(filter: JobExecutionFilter = {}): Promise<JobExecution[]> {
+    let statuses: Set<JobStatus> | undefined;
+    if (filter.status !== undefined) {
+      const statusFilter = filter.status;
+      const statusList: readonly JobStatus[] = Array.isArray(statusFilter)
+        ? statusFilter
+        : [statusFilter];
+      statuses = new Set<JobStatus>(statusList);
+    }
+
+    const rows: JobExecution[] = [];
+    for (const execution of this.state.executions.values()) {
+      if (
+        filter.jobInstanceId !== undefined &&
+        execution.jobInstanceId !== filter.jobInstanceId
+      ) {
+        continue;
+      }
+      if (statuses !== undefined && !statuses.has(execution.status)) continue;
+      if (
+        filter.startedAfter !== undefined &&
+        (execution.startTime === null || execution.startTime < filter.startedAfter)
+      ) {
+        continue;
+      }
+      if (
+        filter.startedBefore !== undefined &&
+        (execution.startTime === null || execution.startTime > filter.startedBefore)
+      ) {
+        continue;
+      }
+      rows.push(deepClone(execution));
+    }
+    return rows;
+  }
+
+  async createStepExecution(jobExecutionId: string, stepName: string): Promise<StepExecution> {
+    const step: StepExecution = {
+      id: this.idGen.next(),
+      jobExecutionId,
+      stepName,
+      status: StepStatus.STARTING,
+      readCount: 0,
+      writeCount: 0,
+      skipCount: 0,
+      rollbackCount: 0,
+      commitCount: 0,
+      startTime: null,
+      endTime: null,
+      exitCode: '',
+      exitMessage: '',
+    };
+    this.state.stepExecutions.set(step.id, step);
+    return deepClone(step);
+  }
+
+  async updateStepExecution(stepExecutionId: string, patch: StepExecutionPatch): Promise<void> {
+    const cur = this.state.stepExecutions.get(stepExecutionId);
+    if (!cur) throw new Error(`StepExecution not found: ${stepExecutionId}`);
+    const next: StepExecution = { ...cur, ...patch };
+    this.state.stepExecutions.set(stepExecutionId, next);
+  }
+
+  async getStepExecution(stepExecutionId: string): Promise<StepExecution | null> {
+    const s = this.state.stepExecutions.get(stepExecutionId);
+    return s ? deepClone(s) : null;
+  }
+
+  override async findStepExecutions(jobExecutionId: string): Promise<StepExecution[]> {
+    const rows: StepExecution[] = [];
+    for (const step of this.state.stepExecutions.values()) {
+      if (step.jobExecutionId === jobExecutionId) {
+        rows.push(deepClone(step));
+      }
+    }
+    return rows;
+  }
+
+  async getExecutionContext(scope: ExecutionScope): Promise<ExecutionContext> {
+    const ctx = this.state.contexts.get(scopeKey(scope));
+    if (ctx) return { data: deepClone(ctx.data), version: ctx.version };
+    return { data: null, version: 0 };
+  }
+
+  async saveExecutionContext(
+    scope: ExecutionScope,
+    ctx: ExecutionContext,
+    version?: number,
+  ): Promise<void> {
+    // Validate JSON-serializability (per ExecutionContext contract)
+    assertJsonSerializable(ctx.data);
+    const current = this.state.contexts.get(scopeKey(scope));
+    const nextVersion = version !== undefined ? version : (current?.version ?? 0) + 1;
+    this.state.contexts.set(scopeKey(scope), {
+      data: deepClone(ctx.data),
+      version: nextVersion,
+    });
+  }
+
+  /**
+   * Returns the most recently created StepExecution for the given
+   * (jobExecutionId, stepName) pair, or `null` if none exists. Insertion
+   * order over `Map` is stable (ES2015+), so a reverse scan picks the
+   * latest entry that matches the filter. The restart path filters the
+   * result further by status (FAILED) at the call site.
+   */
+  async findLatestStepExecution(
+    jobExecutionId: string,
+    stepName: string,
+  ): Promise<StepExecution | null> {
+    let latest: StepExecution | null = null;
+    for (const step of this.state.stepExecutions.values()) {
+      if (step.jobExecutionId === jobExecutionId && step.stepName === stepName) {
+        if (!latest) {
+          latest = step;
+        }
+        // No monotonic timestamp on StepExecution itself; rely on Map
+        // insertion order: later-created entries override earlier ones.
+        latest = step;
+      }
+    }
+    return latest ? deepClone(latest) : null;
+  }
+}
+
+export const RESTARTABLE_DEFAULT_INMEMORY = false;

package/src/repository/in-memory/index.ts

@@ -0,0 +1 @@
+export * from './in-memory-job-repository';

package/src/repository/index.ts

@@ -0,0 +1,3 @@
+export * from './id-generator';
+export * from './uuid-v7';
+export * from './in-memory';

package/src/repository/uuid-v7.ts

@@ -0,0 +1,40 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * UUID v7 generator — time-sortable IDs (first 48 bits are unix time ms).
+ *
+ * Suitable for execution IDs (JobExecution, StepExecution) where
+ * chronological ordering is useful — e.g., grouping recent runs in a
+ * log dashboard or in a B-tree keyed persistence layer.
+ *
+ * Layout per RFC 9562 §5.7:
+ *   xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
+ *     ^ts hi   ^ts lo  ^rand  ^rand   ^rand
+ * where:
+ *   - positions 0-11  = 48-bit unix-ms timestamp (sortable)
+ *   - position 14     = version nibble '7'
+ *   - position 19     = variant nibble ∈ {8, 9, a, b} (top 2 bits = 10)
+ *   - remaining 62    = random bits from `crypto.randomBytes(10)`
+ */
+export class UuidV7IdGenerator {
+  next(): string {
+    // 48-bit timestamp in hex (12 chars) — Date.now() is bounded to ~2^41
+    // today, so padStart keeps it stable-width for predictable sorting.
+    const ts = Date.now().toString(16).padStart(12, '0');
+
+    // 80 random bits (10 bytes). We use byte 0's top nibble as the
+    // variant and place it explicitly in group 4; the remaining 9
+    // bytes (18 hex chars) fill the rest of the random slots.
+    const rand = randomBytes(10);
+
+    // RFC 9562 §4.1 variant: top 2 bits of the variant nibble must be `10`.
+    // `& 0x3f` clears the top 2 bits, then `| 0x80` sets them to `10`,
+    // yielding a value in [0x80, 0xbf] whose hex first digit ∈ {8,9,a,b}.
+    const variantNibble = ((((rand[0] ?? 0) & 0x3f) | 0x80).toString(16) as string)[0];
+
+    // 18 hex chars of pure random from the remaining 9 bytes.
+    const rest = rand.subarray(1).toString('hex');
+
+    return `${ts.slice(0, 8)}-${ts.slice(8, 12)}-7${rest.slice(0, 3)}-${variantNibble}${rest.slice(3, 6)}-${rest.slice(6, 18)}`;
+  }
+}

package/src/scheduling/batch-scheduled.ts

@@ -0,0 +1,257 @@
+import 'reflect-metadata';
+import { SetMetadata } from '@nestjs/common';
+
+import { BATCH_SCHEDULED_OPTIONS as SCHEDULED_KEY } from '../decorators/constants';
+
+export const BATCH_SCHEDULED_OPTIONS = SCHEDULED_KEY;
+
+/**
+ * Overlap policies for cron-scheduled jobs:
+ *
+ * - `'skip'`     — drop the new tick if the previous run is still in flight.
+ * - `'queue'`    — buffer the new tick and start it after the current one ends.
+ * - `'parallel'` — start the new tick alongside the current one.
+ *
+ * The runtime scheduler (the future `@nest-batch/bullmq` cron strategy)
+ * reads this value off the stored metadata and applies the policy at
+ * dispatch time. The decorator itself MUST NOT silently default the
+ * policy to `'skip'` on the user's behalf — leaving it `undefined` here
+ * is the contract: the runtime applies the default.
+ */
+export type BatchOverlapPolicy = 'skip' | 'queue' | 'parallel';
+
+/**
+ * Decorator-facing options for `@BatchScheduled`.
+ *
+ * - `name`     — required, unique per job (used as the scheduling key).
+ * - `timezone` — required, IANA zone (e.g. `'UTC'`, `'Asia/Seoul'`).
+ * - `overlap`  — optional, see `BatchOverlapPolicy`. Default applied at
+ *                runtime, never silently here.
+ * - `startAt`  — optional, absolute lower bound. Preserved by reference.
+ * - `endAt`    — optional, absolute upper bound. Preserved by reference.
+ * - `inert`    — optional, hints the runtime scheduler to skip actual
+ *                registration. The decorator stamps this by reading
+ *                `process.env.BATCH_SCHEDULED_DISABLE` at decoration time
+ *                so the runtime never has to re-evaluate the env.
+ */
+export interface BatchScheduledOptions {
+  name: string;
+  timezone: string;
+  overlap?: BatchOverlapPolicy;
+  startAt?: Date;
+  endAt?: Date;
+  inert?: boolean;
+}
+
+/**
+ * The shape stored under the `BATCH_SCHEDULED_OPTIONS` metadata key on
+ * the decorated method function. The runtime scheduler (the future
+ * `@nest-batch/bullmq` cron strategy) reads this verbatim to register
+ * the job with the underlying scheduler.
+ *
+ * Note: `inert` lives at the top level (not inside `options`) on
+ * purpose. It is a *runtime* flag captured at decoration time from
+ * `process.env.BATCH_SCHEDULED_DISABLE`; it is not a user-facing
+ * knob in `BatchScheduledOptions`. (The `inert?: boolean` slot on
+ * `BatchScheduledOptions` is the user-facing counterpart — see the
+ * GREEN half of Task 13 to wire it up.)
+ */
+export interface BatchScheduledMetadata {
+  cron: string;
+  options: BatchScheduledOptions;
+  inert: boolean;
+}
+
+/**
+ * `@BatchScheduled` — cron decorator.
+ *
+ * Stamps `BATCH_SCHEDULED_OPTIONS` metadata onto the decorated method's
+ * function reference (via `@nestjs/common`'s `SetMetadata`, which writes
+ * to `descriptor.value`), so `Reflect.getMetadata(KEY, Job.prototype.run)`
+ * returns the stored shape.
+ *
+ * This is the TDD-RED half of Task 13. It deliberately implements only
+ * the metadata-storing contract — i.e. the 10 happy-path assertions in
+ * `tests/scheduling/batch-scheduled.test.ts` (sections A + B). The
+ * 7 negative-path assertions in sections C + D are the GREEN half
+ * of the contract and land in the next task:
+ *
+ *   1. Cron expression shape validation (5/6 fields, no literal words).
+ *   2. IANA timezone validation (rejects unknown / empty / whitespace).
+ *
+ * The inert-mode flag (section E) is wired up here because it is also
+ * a pure metadata capture — `process.env.BATCH_SCHEDULED_DISABLE` is
+ * read at decoration time and stamped onto the stored shape. The
+ * decorator does NOT install any timer, interval, or scheduler
+ * registration at decoration time; `inert` is a hint the future
+ * runtime scheduler honors when it later walks the class.
+ *
+ * The decorator is metadata-only by design — it does NOT depend on
+ * `cron` (the boundary test from Task 2 still passes — no `cron`
+ * import appears in core).
+ */
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum + maximum number of whitespace-separated fields a valid
+ * cron expression can have. `cronstrue` / Linux
+ * `crontab(5)` all agree on 5 (minute, hour, day-of-month, month,
+ * day-of-week); Quartz-style extensions add a leading seconds field
+ * for 6.
+ */
+const CRON_MIN_FIELDS = 5;
+const CRON_MAX_FIELDS = 6;
+
+/**
+ * Cron-shape check.
+ *
+ * Accepts:
+ *   - 5 fields: `minute hour dom month dow` (Linux crontab style)
+ *   - 6 fields: `second minute hour dom month dow` (extended cron style)
+ *
+ * Each field is `\S+` (one or more non-whitespace tokens, no empty
+ * fields). The trailing `\S+$` is the final field; the leading
+ * `(\S+\s+){4,5}` captures the preceding 4 or 5 fields separated by
+ * a single whitespace run.
+ *
+ * This is a shape check, not a semantic one — `99 99 99 99 99` still
+ * passes the regex. The runtime scheduler (in `@nest-batch/bullmq`)
+ * is the layer that handles semantic validation via `cron-parser`.
+ * The shape check exists so the decorator fails fast on
+ * unambiguously-wrong input (empty string, too few / too many
+ * fields, literal English words).
+ */
+const CRON_SHAPE = /^(\S+\s+){4,5}\S+$/;
+
+/**
+ * IANA timezone validation.
+ *
+ * The platform's `Intl.DateTimeFormat` is the canonical, no-dep
+ * source of truth for valid IANA zone identifiers: it throws a
+ * `RangeError` for unknown zones. We use it inside a `try/catch` and
+ * normalise the result to a boolean so the decorator's failure mode
+ * is a deterministic `Error` (not a `RangeError` leaking out).
+ *
+ * Reference: https://tc39.es/ecma402/#sec-intl-datetimeformat-constructor
+ */
+function isValidIanaTimezone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a cron expression. Throws a deterministic
+ * `InvalidBatchScheduledCronError` whose `.message` embeds the
+ * invalid value verbatim so log lines and test assertions can pin
+ * the error to a specific input.
+ */
+function assertValidCron(cronExpression: string): void {
+  // Type guard: a non-string value would have already broken
+  // SetMetadata, but checking here keeps the helper standalone.
+  if (typeof cronExpression !== 'string' || cronExpression.length === 0) {
+    throw new InvalidBatchScheduledCronError(cronExpression, 'empty');
+  }
+  if (!CRON_SHAPE.test(cronExpression.trim())) {
+    const fieldCount = cronExpression.trim().split(/\s+/).length;
+    const reason =
+      fieldCount < CRON_MIN_FIELDS
+        ? `fewer than ${CRON_MIN_FIELDS} fields`
+        : fieldCount > CRON_MAX_FIELDS
+          ? `more than ${CRON_MAX_FIELDS} fields`
+          : 'not a valid cron expression';
+    throw new InvalidBatchScheduledCronError(cronExpression, reason);
+  }
+}
+
+/**
+ * Validate a timezone string. Throws a deterministic
+ * `InvalidBatchScheduledTimezoneError` whose `.message` embeds the
+ * invalid value verbatim.
+ */
+function assertValidTimezone(tz: string): void {
+  if (typeof tz !== 'string' || tz.trim().length === 0) {
+    throw new InvalidBatchScheduledTimezoneError(tz, 'empty');
+  }
+  if (!isValidIanaTimezone(tz)) {
+    throw new InvalidBatchScheduledTimezoneError(tz, 'not a valid IANA timezone');
+  }
+}
+
+/**
+ * Thrown by `@BatchScheduled` when the cron expression fails the
+ * shape check (5/6 fields, non-whitespace tokens). The `.message`
+ * includes the invalid value and the failure reason so the error
+ * is greppable in logs and pinned in test assertions.
+ *
+ * Exported from the module barrel so adapter packages (e.g. the
+ * BullMQ runtime) can `instanceof`-check it without reaching into
+ * the decorator's internal helper.
+ */
+export class InvalidBatchScheduledCronError extends Error {
+  readonly cron: string;
+  readonly reason: string;
+
+  constructor(cron: string, reason: string) {
+    super(
+      `[BatchScheduled] invalid cron expression "${cron}": ${reason}. ` +
+        `Expected ${CRON_MIN_FIELDS} (Linux crontab) or ${CRON_MAX_FIELDS} (extended cron) ` +
+        `whitespace-separated fields.`,
+    );
+    this.name = 'InvalidBatchScheduledCronError';
+    this.cron = cron;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Thrown by `@BatchScheduled` when the IANA timezone fails the
+ * platform check. The `.message` embeds the invalid value and the
+ * failure reason.
+ *
+ * Exported from the module barrel so adapter packages can
+ * `instanceof`-check it without reaching into the decorator's
+ * internal helper.
+ */
+export class InvalidBatchScheduledTimezoneError extends Error {
+  readonly timezone: string;
+  readonly reason: string;
+
+  constructor(timezone: string, reason: string) {
+    super(
+      `[BatchScheduled] invalid timezone "${timezone}": ${reason}. ` +
+        `Expected a valid IANA zone identifier (e.g. "UTC", "Asia/Seoul", "America/New_York").`,
+    );
+    this.name = 'InvalidBatchScheduledTimezoneError';
+    this.timezone = timezone;
+    this.reason = reason;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Decorator
+// ---------------------------------------------------------------------------
+
+export function BatchScheduled(
+  cronExpression: string,
+  options: BatchScheduledOptions,
+): MethodDecorator {
+  // 1. Validate inputs at decoration time. The decorator is
+  //    synchronous and metadata-only; the validation runs BEFORE
+  //    `SetMetadata(...)` is called so a bad input never reaches
+  //    the registry.
+  assertValidCron(cronExpression);
+  assertValidTimezone(options.timezone);
+
+  const meta: BatchScheduledMetadata = {
+    cron: cronExpression,
+    options,
+    inert: process.env.BATCH_SCHEDULED_DISABLE === '1',
+  };
+  return SetMetadata(BATCH_SCHEDULED_OPTIONS, meta);
+}

package/src/transaction/in-memory-transaction-manager.ts

@@ -0,0 +1,23 @@
+import { Injectable } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { TransactionContext, TransactionManager } from '../core/transaction/transaction-manager';
+
+export interface InMemoryTransactionContext extends TransactionContext {
+  readonly isActive: true;
+  readonly id: string;
+}
+
+/**
+ * No-op TransactionManager for the in-memory adapter and for tests.
+ * Calls `fn(ctx)` directly without any real transactional semantics.
+ *
+ * For real DB transactions, use a MikroORM/SQL adapter implementation
+ * (e.g., `MikroORMTransactionManager`).
+ */
+@Injectable()
+export class InMemoryTransactionManager extends TransactionManager {
+  async withTransaction<T>(fn: (ctx: InMemoryTransactionContext) => Promise<T>): Promise<T> {
+    const ctx: InMemoryTransactionContext = { isActive: true, id: randomUUID() };
+    return fn(ctx);
+  }
+}

package/src/transaction/index.ts

@@ -0,0 +1 @@
+export * from './in-memory-transaction-manager';