@futdevpro/nts-dynamo 1.15.157 → 1.15.163

package/src/_modules/scheduler/scheduler.service.spec.ts

@@ -1,141 +0,0 @@
-import { DyNTS_Scheduler_Service } from './scheduler.service';
-
-describe('| DyNTS_Scheduler_Service', (): void => {
-  let svc: DyNTS_Scheduler_Service;
-
-  beforeEach((): void => {
-    svc = DyNTS_Scheduler_Service.getInstance();
-    svc._resetForTesting();
-  });
-
-  afterEach((): void => {
-    svc._resetForTesting();
-  });
-
-  describe('| singleton', (): void => {
-    it('| returns the same instance', (): void => {
-      const a: DyNTS_Scheduler_Service = DyNTS_Scheduler_Service.getInstance();
-      const b: DyNTS_Scheduler_Service = DyNTS_Scheduler_Service.getInstance();
-      expect(a).toBe(b);
-      expect(a).toBeInstanceOf(DyNTS_Scheduler_Service);
-    });
-  });
-
-  describe('| registerJob', (): void => {
-    it('| registers a job by key', (): void => {
-      svc.registerJob({ key: 'a', intervalMs: 1000, handler: (): void => {} });
-      expect(svc.getJobKeys()).toEqual(['a']);
-    });
-
-    it('| throws on duplicate key', (): void => {
-      svc.registerJob({ key: 'dup', intervalMs: 1000, handler: (): void => {} });
-      expect((): void => svc.registerJob({ key: 'dup', intervalMs: 1000, handler: (): void => {} })).toThrow();
-    });
-
-    it('| throws on missing key', (): void => {
-      expect((): void => svc.registerJob({ key: '', intervalMs: 1000, handler: (): void => {} })).toThrow();
-    });
-
-    it('| throws on non-positive intervalMs', (): void => {
-      expect((): void => svc.registerJob({ key: 'x', intervalMs: 0, handler: (): void => {} })).toThrow();
-    });
-  });
-
-  describe('| unregisterJob', (): void => {
-    it('| removes a registered job', (): void => {
-      svc.registerJob({ key: 'a', intervalMs: 1000, handler: (): void => {} });
-      svc.unregisterJob('a');
-      expect(svc.getJobKeys()).toEqual([]);
-    });
-
-    it('| is a no-op for unknown key', (): void => {
-      expect((): void => svc.unregisterJob('nope')).not.toThrow();
-    });
-  });
-
-  describe('| start / stop', (): void => {
-    it('| start marks the scheduler started', (): void => {
-      expect(svc.isStarted()).toBe(false);
-      svc.start();
-      expect(svc.isStarted()).toBe(true);
-    });
-
-    it('| stop marks the scheduler stopped', (): void => {
-      svc.start();
-      svc.stop();
-      expect(svc.isStarted()).toBe(false);
-    });
-
-    it('| start is idempotent', (): void => {
-      svc.start();
-      svc.start();
-      expect(svc.isStarted()).toBe(true);
-    });
-  });
-
-  describe('| runNow', (): void => {
-    it('| executes the handler and records a success run', async (): Promise<void> => {
-      let calls: number = 0;
-      svc.registerJob({ key: 'ok', intervalMs: 1000, handler: (): void => { calls++; } });
-
-      await svc.runNow('ok');
-
-      expect(calls).toBe(1);
-      const runs: ReturnType<DyNTS_Scheduler_Service['getRuns']> = svc.getRuns();
-      expect(runs.length).toBe(1);
-      expect(runs[0].jobKey).toBe('ok');
-      expect(runs[0].status).toBe('success');
-      expect(runs[0].finishedAt).toBeDefined();
-    });
-
-    it('| records a failed run with a rich error message', async (): Promise<void> => {
-      svc.registerJob({ key: 'bad', intervalMs: 1000, handler: (): void => { throw new Error('boom'); } });
-
-      await svc.runNow('bad');
-
-      const runs: ReturnType<DyNTS_Scheduler_Service['getRuns']> = svc.getRuns();
-      expect(runs[0].status).toBe('failed');
-      expect(runs[0].error).toContain('boom');
-    });
-
-    it('| throws for an unknown job key', async (): Promise<void> => {
-      let thrown: unknown = null;
-      try { await svc.runNow('nope'); } catch (error: unknown) { thrown = error; }
-      expect(thrown).not.toBeNull();
-    });
-
-    it('| skip-if-running prevents overlapping executions', async (): Promise<void> => {
-      let active: number = 0;
-      let maxActive: number = 0;
-      svc.registerJob({
-        key: 'lock',
-        intervalMs: 1000,
-        handler: async (): Promise<void> => {
-          active++;
-          maxActive = Math.max(maxActive, active);
-          await new Promise<void>((resolve: () => void): void => { setTimeout(resolve, 20); });
-          active--;
-        },
-      });
-
-      await Promise.all([svc.runNow('lock'), svc.runNow('lock')]);
-
-      expect(maxActive).toBe(1);
-    });
-  });
-
-  describe('| getRuns', (): void => {
-    it('| returns the most recent run first', async (): Promise<void> => {
-      svc.registerJob({ key: 'first', intervalMs: 1000, handler: (): void => {} });
-      svc.registerJob({ key: 'second', intervalMs: 1000, handler: (): void => {} });
-
-      await svc.runNow('first');
-      await svc.runNow('second');
-
-      const runs: ReturnType<DyNTS_Scheduler_Service['getRuns']> = svc.getRuns();
-      expect(runs.length).toBe(2);
-      expect(runs[0].jobKey).toBe('second');
-      expect(runs[1].jobKey).toBe('first');
-    });
-  });
-});

package/src/_modules/scheduler/scheduler.service.ts

@@ -1,176 +0,0 @@
-import { Subscription, timer } from 'rxjs';
-
-import { DyNTS_SingletonServiceBase } from '../../_services/base/singleton.service-base';
-import {
-  DyNTS_ScheduledJob,
-  DyNTS_ScheduledJobRun,
-} from './_models/scheduler-job.interface';
-
-/** Belso reprezentacio egy regisztralt job-rol + aktiv timer-rol. */
-interface DyNTS_RegisteredJob {
-  job: DyNTS_ScheduledJob;
-  subscription?: Subscription;
-  running: boolean;
-}
-
-/**
- * Altalanos, idozitett-job utemzo a DyNTS szerverekhez.
- *
- * - **Regisztralhato**: `registerJob({ key, intervalMs, handler })`.
- * - **Idempotens / skip-if-running**: egy job-bol egyszerre csak egy futas megy
- *   (a lassu futas nem torlodik fel).
- * - **Restart-biztos**: a scheduler NEM perzisztal futasi allapotot — a helyesseget
- *   a handler igazsagforras-timestampjei adjak (lasd DyNTS_ScheduledJob doc).
- * - **Naplo**: az utolso N futas in-memory ring bufferben (`getRuns()`), hiba eseten
- *   rich hibauzenettel (sosem `[object Object]`).
- *
- * Hasznalat (szerver indulasakor):
- *   const scheduler = DyNTS_Scheduler_Service.getInstance();
- *   scheduler.registerJob({ key: 'sp-auto-accept', intervalMs: 24 * 60 * 60 * 1000, handler });
- *   scheduler.start();
- */
-export class DyNTS_Scheduler_Service extends DyNTS_SingletonServiceBase {
-
-  static getInstance(): DyNTS_Scheduler_Service {
-    return DyNTS_Scheduler_Service.getSingletonInstance() as DyNTS_Scheduler_Service;
-  }
-
-  private readonly jobs: Map<string, DyNTS_RegisteredJob> = new Map<string, DyNTS_RegisteredJob>();
-  private readonly runs: DyNTS_ScheduledJobRun[] = [];
-  private readonly maxRuns: number = 500;
-  private started: boolean = false;
-
-  /**
-   * Job regisztralasa. Ha a scheduler mar el (`start()` lefutott), a job timer-e
-   * azonnal elindul. Duplikalt kulcs / hibas intervalMs eseten hibat dob.
-   */
-  registerJob(job: DyNTS_ScheduledJob): void {
-    if (!job || !job.key) {
-      throw new Error('DyNTS_Scheduler_Service.registerJob: job.key kotelezo');
-    }
-    if (this.jobs.has(job.key)) {
-      throw new Error(`DyNTS_Scheduler_Service.registerJob: a(z) "${job.key}" job mar regisztralva van`);
-    }
-    if (typeof job.intervalMs !== 'number' || job.intervalMs <= 0) {
-      throw new Error(`DyNTS_Scheduler_Service.registerJob: a(z) "${job.key}" job-hoz pozitiv intervalMs kell`);
-    }
-
-    const registered: DyNTS_RegisteredJob = { job: job, running: false };
-    this.jobs.set(job.key, registered);
-
-    if (this.started) {
-      this.startJob(registered);
-    }
-  }
-
-  /** Job leiratkoztatasa + eltavolitasa. Ismeretlen kulcs eseten no-op. */
-  unregisterJob(key: string): void {
-    const registered: DyNTS_RegisteredJob | undefined = this.jobs.get(key);
-    if (!registered) { return; }
-    registered.subscription?.unsubscribe();
-    this.jobs.delete(key);
-  }
-
-  /** Minden regisztralt job timer-enek inditasa. Idempotens. */
-  start(): void {
-    if (this.started) { return; }
-    this.started = true;
-    this.jobs.forEach((registered: DyNTS_RegisteredJob) => this.startJob(registered));
-  }
-
-  /** Minden job timer-enek leallitasa (a regisztraciok megmaradnak). */
-  stop(): void {
-    this.jobs.forEach((registered: DyNTS_RegisteredJob) => {
-      registered.subscription?.unsubscribe();
-      registered.subscription = undefined;
-    });
-    this.started = false;
-  }
-
-  /** Egy job azonnali, kezi futtatasa (a skip-if-running lock-ot tiszteletben tartva). */
-  async runNow(key: string): Promise<void> {
-    const registered: DyNTS_RegisteredJob | undefined = this.jobs.get(key);
-    if (!registered) {
-      throw new Error(`DyNTS_Scheduler_Service.runNow: a(z) "${key}" job nincs regisztralva`);
-    }
-    await this.executeJob(registered);
-  }
-
-  /** El van-e inditva a scheduler. */
-  isStarted(): boolean {
-    return this.started;
-  }
-
-  /** Eppen fut-e az adott job. */
-  isRunning(key: string): boolean {
-    return this.jobs.get(key)?.running ?? false;
-  }
-
-  /** A regisztralt job-kulcsok. */
-  getJobKeys(): string[] {
-    return Array.from(this.jobs.keys());
-  }
-
-  /** Az utolso N futas, legujabb elol. */
-  getRuns(limit: number = 100): DyNTS_ScheduledJobRun[] {
-    const safeLimit: number = Math.max(0, Math.min(limit, this.runs.length));
-    return this.runs.slice(this.runs.length - safeLimit).reverse();
-  }
-
-  /** Teszt-segedlet: minden timer leall + minden regisztracio/naplo torlodik. */
-  _resetForTesting(): void {
-    this.stop();
-    this.jobs.clear();
-    this.runs.length = 0;
-  }
-
-  private startJob(registered: DyNTS_RegisteredJob): void {
-    if (registered.subscription) { return; }
-    const initialDelay: number = registered.job.initialDelayMs ?? registered.job.intervalMs;
-    registered.subscription = timer(initialDelay, registered.job.intervalMs)
-      .subscribe(() => { void this.executeJob(registered); });
-  }
-
-  private async executeJob(registered: DyNTS_RegisteredJob): Promise<void> {
-    if (registered.running) { return; }
-    registered.running = true;
-
-    const run: DyNTS_ScheduledJobRun = {
-      jobKey: registered.job.key,
-      startedAt: new Date().toISOString(),
-      status: 'running',
-    };
-    this.pushRun(run);
-
-    try {
-      await registered.job.handler();
-      run.status = 'success';
-    } catch (error: unknown) {
-      run.status = 'failed';
-      run.error = this.toErrorMessage(error);
-      this.logError(registered.job.key, error);
-    } finally {
-      run.finishedAt = new Date().toISOString();
-      registered.running = false;
-    }
-  }
-
-  private pushRun(run: DyNTS_ScheduledJobRun): void {
-    this.runs.push(run);
-    if (this.runs.length > this.maxRuns) {
-      this.runs.shift();
-    }
-  }
-
-  private toErrorMessage(error: unknown): string {
-    if (error instanceof Error) { return error.message; }
-    try { return JSON.stringify(error); } catch { return String(error); }
-  }
-
-  private logError(jobKey: string, error: unknown): void {
-    // A console.error-t a DyNTS_Logs_Service (ha telepitve van) automatikusan bufferli.
-    // TODO (kovetkezo iteracio): bekotni a DyNTS_GlobalService.globalErrorHandler-be.
-    // eslint-disable-next-line no-console
-    console.error(` ! Scheduler job "${jobKey}" failed:`, error);
-  }
-}

package/src/_modules/scoped-config/_enums/dynts-scoped-config-level.enum.ts

@@ -1,22 +0,0 @@
-
-/**
- * `DyNTS_ScopedConfig_Level` — a DB-backed scoped config feloldási-szintjei (BFR-AM-004).
- *
- * A precedencia: **scope (leaf→root) > table > global > builtin-default**. Egy `DyNTS_ScopedConfig`
- * dokumentum mindig pontosan EGY szinten él; a `level` + `tableScope` + `scopeId` hármas adja a
- * feloldási-kulcsot (a `key`-vel együtt a logikai unique-constraint).
- *
- * **Domain-agnosztikus:** a konkrét table-/scope-nevek a fogyasztó dolga; a bedrock csak a generikus
- * precedencia-engine + a tárolás szintjeit definiálja (a katalógus/kulcsok NEM ide tartoznak).
- */
-export enum DyNTS_ScopedConfig_Level {
-
-  /** Rendszer-szintű default (a legalacsonyabb precedencia a builtin felett). */
-  global = 'global',
-
-  /** Egy adott logikai tár/táblázat szintje (`tableScope` kötelező). */
-  table = 'table',
-
-  /** A legspecifikusabb szint: egy konkrét scope-entitás (`tableScope` + `scopeId` kötelező). */
-  scope = 'scope',
-}

package/src/_modules/scoped-config/_models/data-models/dynts-scoped-config.data-model.ts

@@ -1,82 +0,0 @@
-
-import { DyFM_DataModel_Params, DyFM_Metadata, DyFM_Object } from '@futdevpro/fsm-dynamo';
-
-import { DyNTS_ScopedConfig_Level } from '../../_enums/dynts-scoped-config-level.enum';
-
-/**
- * `DyNTS_ScopedConfig` entitás (BFR-AM-004) — egy dokumentum = **egy setting-érték egy adott szinten**.
- * A `level` + `tableScope` + `scopeId` hármas adja a feloldási-kulcsot (a `key`-vel együtt a logikai
- * unique-constraint); a precedencia: **scope (leaf→root) > table > global > builtin-default**.
- *
- * `extends DyFM_Metadata`: az identitás/metadata (`_id`, `__created`, `__lastModified`, `_deleted`)
- * az ősből jön; a `_deleted` soft-delete marker (Date), amit a `DyNTS_ArchiveDataService` kezel — ez
- * a felülírás-history alapja (egy `set` a régi aktív rekordot archiválja, az újat aktívan írja).
- *
- * **Domain-agnosztikus:** a `key` `string`, a `value` `unknown` (Mongoose `Mixed`, séma-szinten
- * `type:'object'`). A bedrock NEM validál séma-szinten — a típushelyesség / katalógus a FOGYASZTÓ
- * dolga. A `value` írása **`$set`-tel atomikus** (Mongoose Mixed silent-drop ellen — lásd
- * `DyNTS_ScopedConfig_DataService.setValue`).
- */
-export class DyNTS_ScopedConfig extends DyFM_Metadata {
-
-  // --- a feloldási kulcs ---
-
-  /** A feloldási-szint (`global`|`table`|`scope`). */
-  level?: DyNTS_ScopedConfig_Level;
-
-  /** `level='table'|'scope'` esetén kötelező: melyik logikai tár. */
-  tableScope?: string;
-
-  /** `level='scope'` esetén kötelező: a scope-entitás logikai azonosítója. */
-  scopeId?: string;
-
-  // --- a setting maga ---
-
-  /** A config-kulcs (a fogyasztó katalógusából; string-ként perzistált). */
-  key?: string;
-
-  /** A setting-érték; típusa a fogyasztó katalógusa szerint. Mongoose `Mixed`. */
-  value?: unknown;
-
-  // --- audit ---
-
-  /** Ki/mi állította be (audit). */
-  setBy?: string;
-
-  /** Beállítás-részlet (pl. preset-név, CLI-user). */
-  setByDetail?: string;
-
-  /** Opcionális indoklás. */
-  note?: string;
-
-  constructor(set?: Partial<DyNTS_ScopedConfig>) {
-    super(set);
-
-    if (set) {
-      DyFM_Object.cleanAssign(this, set);
-    }
-  }
-}
-
-/**
- * MongoDB data-params a `dynts_scoped_config` collection-höz (BFR-AM-004). `addArchive: true` → a
- * felülírt (régi) értékek soft-delete-elve megőrződnek (audit-trail / history).
- *
- * A `value` `type:'object'` (Mongoose `Mixed`) — a séma NEM validál; a típushelyesség a fogyasztó
- * katalógusának + set-kori validációjának dolga.
- */
-export const DyNTS_scopedConfig_dataParams: DyFM_DataModel_Params<DyNTS_ScopedConfig> =
-  new DyFM_DataModel_Params<DyNTS_ScopedConfig>({
-    dataName: 'dynts_scoped_config',
-    addArchive: true,
-    properties: {
-      level: { type: 'string', index: true, required: true },
-      tableScope: { type: 'string', index: true },
-      scopeId: { type: 'string', index: true },
-      key: { type: 'string', index: true, required: true },
-      value: { type: 'object' },
-      setBy: { type: 'string', index: true },
-      setByDetail: { type: 'string' },
-      note: { type: 'string' },
-    },
-  });

package/src/_modules/scoped-config/_models/interfaces/dynts-scoped-config.interface.ts

@@ -1,107 +0,0 @@
-
-/**
- * Scoped-config shared vokabulár (BFR-AM-004). Egy fájlban a szorosan összetartozó típusok
- * (a `*.interface.ts` az egy-export-per-file konvenció ismert kivétele — mint a FAM `fam-config.interface.ts`).
- *
- * **Domain-agnosztikus:** a bedrock CSAK a generikus resolve-precedencia engine-t + a tárolást adja;
- * a konkrét kulcs-katalógus, a kulcs-típusok és a default-ok a fogyasztó projekté (pl. FAM
- * `CONFIG_CATALOG`). Ezért a `value` itt `unknown`, a `key` `string`, és a `builtinDefault`-ot a
- * hívó adja át (nincs beépített katalógus).
- */
-
-/**
- * Egy scoped-config érték generikus típusa. A típushelyesség a FOGYASZTÓ felelőssége (a bedrock nem
- * validál séma-szinten — a `value` Mongoose `Mixed`). A `null` megengedett (pl. "nincs plafon").
- */
-export type DyNTS_ScopedConfigValue =
-  number | string | boolean | string[] | null | { [key: string]: unknown };
-
-/**
- * A precedencia-feloldás forrás-szintje. A `resolve` ezt adja vissza, hogy a fogyasztó átlátható módon
- * tudja, **honnan** jön egy érték (`builtin` = a hívó által átadott `builtinDefault`).
- */
-export type DyNTS_ScopedConfigResolvedFrom = 'scope' | 'table' | 'global' | 'builtin';
-
-/**
- * Egy canonical scope-referencia a `scopePath`-ban (BFR-AM-004). A `scopeId` a logikai scope-azonosító
- * (a fogyasztó adja, pl. egy `FAM_Scope._id`); a feloldás a path **levéből** (utolsó elem) indul a
- * gyökér (első elem) felé — a legmélyebb találat nyer.
- */
-export interface DyNTS_ScopedConfigScopeRef {
-  /** A scope logikai azonosítója (a `DyNTS_ScopedConfig.scopeId`-vel egyezik). */
-  scopeId: string;
-}
-
-/**
- * A `resolve(key, ctx)` / `resolveAll(ctx)` kontextusa (BFR-AM-004). A `table` + `scopePath` nélkül
- * csak a global + builtin szint értelmezett. A `scopePath` canonical formában érkezik (a fogyasztó
- * read/write-path-ja oldotta fel) — a config-engine nyers stringgel NEM dolgozik.
- */
-export interface DyNTS_ScopedConfigResolveContext {
-  /** Melyik logikai tár szintjén oldjuk fel (a table + scope ág; nélküle csak global+builtin). */
-  table?: string;
-
-  /** Canonical scope-lánc (gyökér→levél); a feloldás a **levéből** indul a gyökér felé. */
-  scopePath?: DyNTS_ScopedConfigScopeRef[];
-}
-
-/**
- * Egy feloldott config-érték a forrás-szinttel (BFR-AM-004). Átlátható: jelzi, melyik szintről jött
- * az effektív érték + ki állította be (audit). A `builtin` esetén csak a `value` + `resolvedFrom` van.
- */
-export interface DyNTS_ScopedConfigResolvedValue<T = DyNTS_ScopedConfigValue> {
-  /** A feloldott effektív érték. */
-  value: T;
-
-  /** A forrás-szint (`scope`/`table`/`global`/`builtin`). */
-  resolvedFrom: DyNTS_ScopedConfigResolvedFrom;
-
-  /** Ha `resolvedFrom='scope'`, melyik scope-entitásról (a legmélyebb találat). */
-  scopeId?: string;
-
-  /** Ki/mi állította be (a forrás-rekordról; `builtin` esetén nincs). */
-  setBy?: string;
-
-  /** Beállítás-részlet (pl. preset-név / CLI-user), ha van. */
-  setByDetail?: string;
-}
-
-/**
- * A `resolve(key, opts)` opciói (BFR-AM-004). A `builtinDefault` a hívó által átadott fallback —
- * ha egyik DB-szinten sincs érték, ezt adja vissza `resolvedFrom='builtin'`-nal (a bedrock nem
- * tart beépített katalógust). Ha nincs `builtinDefault` és nincs DB-érték, az érték `undefined`.
- */
-export interface DyNTS_ScopedConfigResolveOptions<T = DyNTS_ScopedConfigValue> {
-  /** Melyik logikai tár szintjén oldjuk fel (a table + scope ág). */
-  table?: string;
-
-  /** Canonical scope-lánc (gyökér→levél); a feloldás a **levéből** indul a gyökér felé. */
-  scopePath?: DyNTS_ScopedConfigScopeRef[];
-
-  /** A hívó által átadott builtin fallback (a katalógus a fogyasztóé). */
-  builtinDefault?: T;
-}
-
-/**
- * A `set(level, key, value, opts)` opció-objektuma (BFR-AM-004). A `level`+`tableScope`+`scopeId` adja
- * a feloldási-kulcsot; az audit-mezők (`setBy`/`setByDetail`/`note`) a felülírás-history-hez.
- */
-export interface DyNTS_ScopedConfigSetOptions {
-  /** `level='table'|'scope'` esetén kötelező: melyik logikai tár. */
-  tableScope?: string;
-
-  /** `level='scope'` esetén kötelező: a scope-entitás logikai azonosítója. */
-  scopeId?: string;
-
-  /** Ki/mi állította be (audit; default `'system'`). */
-  setBy?: string;
-
-  /** Beállítás-részlet (pl. preset-név / CLI-user). */
-  setByDetail?: string;
-
-  /** Opcionális indoklás. */
-  note?: string;
-
-  /** A hibák / write-ok `issuer`-e. */
-  issuer?: string;
-}