@rtbnext/core 2.0.0-alpha.1

package/dist/core/Utils.js

@@ -0,0 +1,167 @@
+import { Merger } from '@komed3/deepmerge';
+import { sha256 } from 'js-sha256';
+import { hrtime } from 'node:process';
+import { REGEX_DIACRITICS, REGEX_NOALNUM } from '../lib/regex.js';
+import { Parser } from '../parser/Parser.js';
+export class Utils {
+  static mergeInstances = {};
+  // --- sanitize IDs and URIs ---
+  static sanitize(value, delimiter = '-') {
+    return Parser.string(value)
+      .toLowerCase()
+      .replace(REGEX_NOALNUM, delimiter)
+      .replace(new RegExp(`[${delimiter}]{2,}`, 'g'), delimiter);
+  }
+  // --- hashing ---
+  static hash(value) {
+    return sha256(Parser.string(value).split('/').pop() ?? '');
+  }
+  static verifyHash(value, hash) {
+    return value === hash || Utils.hash(value) === hash;
+  }
+  // --- measurement ---
+  static async measure(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Parameter must be a function');
+    const now = hrtime.bigint();
+    const diff = () => Number(hrtime.bigint() - now) / 1e6;
+    try {
+      return { result: await fn(), ms: diff() };
+    } catch (err) {
+      throw Object.assign(err ?? {}, { ms: diff() });
+    }
+  }
+  // --- date ---
+  static date(format = 'ymd') {
+    return Parser.date(undefined, format);
+  }
+  static lastMonthDay(month, year) {
+    const date = new Date(Number(year ?? new Date().getFullYear()), Number(month), 0);
+    date.setHours(23, 59, 59, 999);
+    return date;
+  }
+  // --- meta data ---
+  static metaData(obj) {
+    return { $metadata: { schemaVersion: 2, lastModified: Utils.date('iso'), ...obj } };
+  }
+  // --- aggregate from object arrays ---
+  static aggregate(arr, key, aggregator = 'first') {
+    const values = arr.map(item => item[key]).filter(v => v !== undefined);
+    if (!values.length) return undefined;
+    if (typeof aggregator === 'function') return aggregator(values);
+    const isNum = v => typeof v === 'number' && !Number.isNaN(v);
+    const sum = (acc, val) => (acc === undefined || !isNum(val) ? undefined : acc + val);
+    switch (aggregator) {
+      case 'all':
+        return values;
+      case 'first':
+        return values[0];
+      case 'last':
+        return values.at(-1);
+      case 'sum':
+        return values.reduce(sum, 0);
+      case 'min':
+        return values.reduce((acc, val) => (acc === undefined || val < acc ? val : acc), Infinity);
+      case 'max':
+        return values.reduce((acc, val) => (acc === undefined || val > acc ? val : acc), -Infinity);
+      case 'mean':
+        const s = values.reduce(sum, 0);
+        return s === undefined ? undefined : s / values.length;
+    }
+  }
+  // --- deep object updates ---
+  static update(operator, obj, path, n) {
+    return path
+      .split('.')
+      .reduce(
+        (curr, p, i, arr) => (
+          i < arr.length - 1 && (curr[p] ??= {}),
+          i === arr.length - 1
+            ? operator === 'set'
+              ? (curr[p] = n)
+              : operator === 'inc'
+                ? (curr[p] = (curr[p] ?? 0) + (n ?? 1))
+                : operator === 'max'
+                  ? (curr[p] = Math.max(curr[p] ?? -Infinity, n))
+                  : operator === 'min'
+                    ? (curr[p] = Math.min(curr[p] ?? Infinity, n))
+                    : operator === 'append'
+                      ? (curr[p] = [...(curr[p] ?? []), n])
+                      : operator === 'prepend'
+                        ? (curr[p] = [n, ...(curr[p] ?? [])])
+                        : operator(curr[p], p)
+            : (curr = curr[p]),
+          curr
+        ),
+        obj
+      );
+  }
+  // --- sorting arrays and objects ---
+  static sort(value, compare, objCompare) {
+    compare ??= (a, b) => (a > b ? 1 : a < b ? -1 : 0);
+    objCompare ??= (a, b) => compare(a[0], b[0]);
+    return Array.isArray(value)
+      ? [...value].sort(compare)
+      : value instanceof Set
+        ? new Set([...value].sort(compare))
+        : value instanceof Map
+          ? new Map([...value.entries()].sort(objCompare))
+          : typeof value === 'object'
+            ? Object.fromEntries(Object.entries(value).sort(objCompare))
+            : [...value].sort(compare);
+  }
+  static sortKeysDeep(value, exclude = new Set()) {
+    if (value === null || typeof value !== 'object') return value;
+    if (Array.isArray(value)) return value.map(v => Utils.sortKeysDeep(v, exclude));
+    return Object.keys(value)
+      .sort((a, b) => (exclude.has(a) || exclude.has(b) ? 0 : a.localeCompare(b)))
+      .reduce((acc, k) => {
+        acc[k] = Utils.sortKeysDeep(value[k], exclude);
+        return acc;
+      }, {});
+  }
+  // --- merging ---
+  static merge(mode, ...objects) {
+    return (Utils.mergeInstances[mode] ??= new Merger({ arrayMode: mode })).merge(
+      objects[0] ?? {},
+      ...objects.slice(1)
+    );
+  }
+  static unique(arr) {
+    return [...new Set(arr.map(item => JSON.stringify(item)))].map(item => JSON.parse(item));
+  }
+  static mergeArray(target, source, mode = 'unique' /* ArrayMode.Unique */) {
+    switch (mode) {
+      case 'replace' /* ArrayMode.Replace */:
+        return source;
+      case 'keep' /* ArrayMode.Keep */:
+        return target;
+      case 'concat' /* ArrayMode.Concat */:
+        return [...target, ...source];
+      case 'unique' /* ArrayMode.Unique */:
+        return Utils.unique([...target, ...source]);
+    }
+  }
+  // --- queries ---
+  static queryStr(query) {
+    return new URLSearchParams(query).toString();
+  }
+  // --- search index ---
+  static buildSearchText(value, minLength = 4) {
+    return [
+      ...new Set(
+        String(value)
+          .normalize('NFD')
+          .replace(REGEX_DIACRITICS, '')
+          .toLowerCase()
+          .replace(REGEX_NOALNUM, ' ')
+          .split(' ')
+          .filter(w => w.length >= minLength)
+          .filter(Boolean)
+      )
+    ].join(' ');
+  }
+  static tokenSearch(text, tokens, looseMatch = false) {
+    if (!text || !tokens.length) return false;
+    return tokens[looseMatch ? 'some' : 'every'](t => text.includes(t));
+  }
+}

package/dist/interfaces/cache.d.ts

@@ -0,0 +1,6 @@
+export interface ICache {
+  readonly size: number;
+  get<T = any>(key: string): T | undefined;
+  has(key: string): boolean;
+  clear(): void;
+}

package/dist/interfaces/config.d.ts

@@ -0,0 +1,21 @@
+import type {
+  TConfigObject,
+  TCronConfig,
+  TFetchConfig,
+  TJobConfig,
+  TLoggingConfig,
+  TQueueConfig,
+  TStorageConfig
+} from '../types/config';
+
+export interface IConfig {
+  root: string;
+  environment: string;
+  config: TConfigObject;
+  logging: TLoggingConfig;
+  job: TJobConfig;
+  cron: TCronConfig;
+  storage: TStorageConfig;
+  fetch: TFetchConfig;
+  queue: TQueueConfig;
+}

package/dist/interfaces/cron.d.ts

@@ -0,0 +1,3 @@
+export interface ICron {
+  run(): Promise<void>;
+}

package/dist/interfaces/fetch.d.ts

@@ -0,0 +1,13 @@
+import type { TFetchMethod, THeader } from '../types/fetch';
+import type { TListResponse, TProfileResponse, TResponse } from '../types/response';
+
+export interface IFetch {
+  single<T>(url: string, method: TFetchMethod = 'get', header?: THeader): Promise<TResponse<T>>;
+  batch<T>(urls: string[], method: TFetchMethod = 'get', header?: THeader): Promise<TResponse<T>[]>;
+  wayback<T>(url: string, ts: unknown): Promise<TResponse<T>>;
+  list<T extends object>(uriLike: string, year: string): Promise<TResponse<TListResponse<T>>>;
+  profile(...uriLike: string[]): Promise<TResponse<TProfileResponse>[]>;
+  wikidata<T>(sparql: string): Promise<TResponse<T>>;
+  wikipedia<T>(query: Record<string, unknown>, lang: string = 'en'): Promise<TResponse<T>>;
+  commons<T>(query: Record<string, unknown>): Promise<TResponse<T>>;
+}

package/dist/interfaces/filter.d.ts

@@ -0,0 +1,12 @@
+import type { TFilterGroup, TFilterSpecial } from '@rtbnext/schema/src/base/const';
+import type { TFilter, TFilterList } from '@rtbnext/schema/src/model/filter';
+
+export interface IFilter {
+  resolvePath(path: string): string | false;
+  getFilter(group: TFilterGroup, key: string): TFilter | undefined;
+  getFilterByPath(path: string): TFilter | undefined;
+  getGroup(group: TFilterGroup): Record<string, TFilter> | undefined;
+  getSpecial(special: TFilterSpecial): TFilter | undefined;
+  has(path: string, uriLike: string): boolean;
+  save(collection: Partial<TFilterList>): void;
+}

package/dist/interfaces/index.d.ts

@@ -0,0 +1,30 @@
+import type { TIndex } from '@rtbnext/schema/src/base/generic';
+import type { TListIndex, TListIndexItem } from '@rtbnext/schema/src/model/list';
+import type { TProfileIndex, TProfileIndexItem } from '@rtbnext/schema/src/model/profile';
+
+export interface IIndex<I extends TIndex, T extends Map<string, I>> {
+  readonly size: number;
+  readonly values: IterableIterator<I>;
+  readonly keys: IterableIterator<string>;
+  getIndex(): T;
+  has(uriLike: string): boolean;
+  get(uriLike: string): I | undefined;
+  update(uriLike: string, data: Partial<I>, allowUpdate: boolean = true, save: boolean = true): I | false;
+  delta(items: Array<{ uriLike: string; data: Partial<I> }>, allowUpdate: boolean = true): number;
+  add(uriLike: string, data: I): I | false;
+  delete(uriLike: string): void;
+  search(query: string, looseMatch: boolean = false): T;
+}
+
+export interface IProfileIndex extends IIndex<TProfileIndexItem, TProfileIndex> {
+  find(uriLike: string): TProfileIndex;
+  move(from: string, to: string, makeAlias: boolean = true): TProfileIndexItem | false;
+  syncFromData(data: TProfileData): TProfileIndexItem | false;
+  hasAlias(aliasLike: string, uriLike?: string): string | false;
+  isAliasAvailable(aliasLike: string): boolean;
+  removeAlias(aliasLike: string): boolean;
+  addAliases(uriLike: string, ...aliases: string[]): TProfileIndexItem | false;
+  rmvAliases(uriLike: string, ...aliases: string[]): TProfileIndexItem | false;
+}
+
+export interface IListIndex extends IIndex<TListIndexItem, TListIndex> {}

package/dist/interfaces/job.d.ts

@@ -0,0 +1,9 @@
+import type { TJobClsOptions } from '../types/job';
+
+export interface IJob<T extends TJobClsOptions = TJobClsOptions> {
+  getJobName(): string;
+  getOptions(): T;
+  isSilent(): boolean;
+  isSafeMode(): boolean;
+  run(): void | Promise<void>;
+}

package/dist/interfaces/list.d.ts

@@ -0,0 +1,9 @@
+import type { TListSnapshot } from '@rtbnext/schema/src/model/list';
+
+import type { ISnapshot } from './snapshot';
+import type { TListSnapshotData } from '../types/generic';
+
+export interface IList extends ISnapshot<TListSnapshot> {
+  getUri(): string;
+  saveSnapshot(snapshot: TListSnapshotData, force: boolean = false): boolean;
+}

package/dist/interfaces/logger.d.ts

@@ -0,0 +1,20 @@
+export interface ILogger {
+  error(msg: string, err?: Error): void;
+  errMsg(err: unknown, msg?: string): void;
+  exit(msg: string, err?: Error): never;
+  warn(msg: string, meta?: unknown): void;
+  info(msg: string, meta?: unknown): void;
+  debug(msg: string, meta?: unknown): void;
+  catch<F extends (...args: any[]) => any, R = ReturnType<F>>(
+    fn: F,
+    msg: string,
+    level: TLoggingLevel = 'error'
+  ): R | undefined;
+  catchAsync<F extends (...args: any[]) => Promise<any>, R = Awaited<ReturnType<F>>>(
+    fn: F,
+    msg: string,
+    level: TLoggingLevel = 'error'
+  ): Promise<R | undefined>;
+  getLogFile(date: string): string | undefined;
+  getCurrentLogFile(): string | undefined;
+}

package/dist/interfaces/mover.d.ts

@@ -0,0 +1,7 @@
+import type { TMover } from '@rtbnext/schema/src/model/mover';
+
+import type { ISnapshot } from '@/interfaces/snapshot';
+
+export interface IMover extends ISnapshot<TMover> {
+  saveSnapshot(snapshot: TMoverData, force?: boolean): boolean;
+}

package/dist/interfaces/parser.d.ts

@@ -0,0 +1,68 @@
+import type { TAsset, TRealtime } from '@rtbnext/schema/src/base/assets';
+import type { TChangeFlag } from '@rtbnext/schema/src/base/const';
+import type {
+  TEducation,
+  TImage,
+  TLocation,
+  TOrganization,
+  TRelation,
+  TSelfMade
+} from '@rtbnext/schema/src/base/generic';
+import type { TProfileBio, TProfileFlags, TProfileInfo, TProfileName } from '@rtbnext/schema/src/model/profile';
+
+import type { ICache } from '@/type/cache';
+import type { TPersonListEntry, TProfileResponse } from '../types/response';
+
+export interface IProfileParser extends ICache {
+  rawData(): TProfileResponse['person'];
+  sortedLists(): TProfileResponse['person']['personLists'];
+  uri(): string;
+  id(): string;
+  aliases(): string[];
+  name(): { name: TProfileName; family: boolean };
+  flags(): TProfileFlags;
+  info(): TProfileInfo;
+  citizenship(): string | undefined;
+  residence(): TLocation | undefined;
+  birthPlace(): TLocation | undefined;
+  education(): TEducation[];
+  selfMade(): TSelfMade;
+  philanthropyScore(): number | undefined;
+  organization(): TOrganization | undefined;
+  bio(): TProfileBio;
+  cv(): string[];
+  facts(): string[];
+  quotes(): string[];
+  related(): TRelation[];
+  media(): TImage[];
+}
+
+export interface IListParser<T extends object> extends ICache {
+  rawData(): T;
+}
+
+export interface IPersonListParser extends IListParser<TPersonListEntry> {
+  uri(): string;
+  id(): string;
+  date(): string;
+  year(): number;
+  rank(): number | undefined;
+  networth(): number | undefined;
+  dropOff(): boolean | undefined;
+  name(): { name: TProfileName; family: boolean };
+  info(): Partial<TProfileInfo>;
+  residence(): TLocation | undefined;
+  selfMade(): TSelfMade | undefined;
+  philanthropyScore(): number | undefined;
+  organization(): TOrganization | undefined;
+  bio(): TProfileBio;
+  age(): number | undefined;
+}
+
+export interface IRTBListParser extends IPersonListParser {
+  assets(): TAsset[];
+  realtime(data?: Partial<TProfileData>, prev?: string, next?: string): TRealtime | undefined;
+  rankDiff(data?: Partial<TProfileData>): { flag: TChangeFlag; rankDiff?: number };
+}
+
+export interface IBillionairesListParser extends IPersonListParser {}

package/dist/interfaces/profile.d.ts

@@ -0,0 +1,30 @@
+import type { ArrayMode } from '@komed3/deepmerge';
+import type {
+  TProfileData,
+  TProfileHistory,
+  TProfileHistoryItem,
+  TProfileMetaData
+} from '@rtbnext/schema/src/model/profile';
+
+export interface IProfile {
+  getUri(): string;
+  getMeta(): TProfileMetaData['$metadata'];
+  schemaVersion(): number;
+  lastModified(): string;
+  lastModifiedTime(): number;
+  lastLookup(): string | undefined;
+  lastLookupTime(): number | undefined;
+  verify(id: string): boolean;
+  touch(): void;
+  touchLookup(): void;
+  needSave(): boolean;
+  save(syncIndex: boolean = true): void;
+  getData(): TProfileData;
+  setData(data: TProfileData): void;
+  updateData(data: Partial<TProfileData>, mode: ArrayMode = ArrayMode.Replace): void;
+  getHistory(): TProfileHistory;
+  setHistory(history: TProfileHistory): void;
+  addHistory(row: TProfileHistoryItem): void;
+  mergeHistory(history: TProfileHistory): void;
+  move(uriLike: string, makeAlias: boolean = true): boolean;
+}

package/dist/interfaces/queue.d.ts

@@ -0,0 +1,17 @@
+import type { TQueueItem, TQueueOptions } from '../types/queue';
+
+export interface IQueue {
+  readonly size: number;
+  getQueue(): TQueueItem[];
+  getByKey(key: string): TQueueItem | undefined;
+  hasKey(key: string): boolean;
+  getByUri(uriLike: string): TQueueItem[];
+  hasUri(uriLike: string): boolean;
+  clear(): void;
+  add(opt: TQueueOptions, save: boolean = true): boolean;
+  addMany(items: TQueueOptions[]): number;
+  removeByKey(key: string): boolean;
+  remove(...uriLike: string[]): number;
+  next(n: number = 1): TQueueItem[];
+  nextUri(n: number = 1): string[];
+}

package/dist/interfaces/snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { TSnapshot } from '@rtbnext/schema/src/base/generic';
+
+export interface ISnapshot<T extends TSnapshot> {
+  getDates(): string[];
+  hasDate(dateLike: string): boolean;
+  firstDate(): string | undefined;
+  latestDate(): string | undefined;
+  nearestDate(dateLike: string): string | undefined;
+  datesInRange(from: string, to: string): string[];
+  datesInYear(year: string | number): string[];
+  firstInYear(year: string | number): string | undefined;
+  latestInYear(year: string | number): string | undefined;
+  getSnapshot(dateLike: string, exactMatch: boolean = true): T | false;
+  getLatest(): T | false;
+  saveSnapshot(snapshot: T, force: boolean = false): boolean;
+}

package/dist/interfaces/stats.d.ts

@@ -0,0 +1,45 @@
+import type { TStatsGroup as TStatsGroupType } from '@rtbnext/schema/src/base/const';
+import type { TListSnapshot } from '@rtbnext/schema/src/model/list';
+import type {
+  TDBStats,
+  TDBStatsData,
+  TGlobalStats,
+  TGlobalStatsData,
+  THistory,
+  TProfileStats,
+  TProfileStatsData,
+  TScatter,
+  TScatterItem,
+  TStatsGroup,
+  TStatsGroupItem,
+  TTop10,
+  TTop10Data,
+  TTop10List,
+  TWealthStats,
+  TWealthStatsData
+} from '@rtbnext/schema/src/model/stats';
+
+export interface IStats {
+  getGlobalStats(): TGlobalStats;
+  getProfileStats(): TProfileStats;
+  getWealthStats(): TWealthStats;
+  getScatter(): TScatter;
+  getTop10(): TTop10;
+  getDBStats(): TDBStats;
+  getHistory(): THistory;
+  getGroupedStatsIndex(group: TStatsGroupType): TStatsGroup<string>['index'];
+  getGroupedStatsHistory(group: TStatsGroupType, key: string): THistory;
+  getGroupedStats(group: TStatsGroupType): TStatsGroup<string>;
+  setGlobalStats(data: TGlobalStatsData): boolean;
+  setProfileStats(data: TProfileStatsData): boolean;
+  setWealthStats(data: TWealthStatsData): boolean;
+  setScatter(data: TScatterItem[]): boolean;
+  setTop10(data: TTop10Data): boolean;
+  updateTop10(key: string, list: TTop10List): boolean;
+  setDBStats(data: TDBStatsData): boolean;
+  setGroupedStats<T extends string = string>(group: TStatsGroupType, raw: Record<T, TStatsGroupItem>): boolean;
+  updateHistory(data: Partial<TGlobalStats>): boolean;
+  generateWealthStats(scatter: TScatterItem[]): boolean;
+  generateTop10Entry(snapshot: TListSnapshot): boolean;
+  generateDBStats(): boolean;
+}

package/dist/interfaces/storage.d.ts

@@ -0,0 +1,16 @@
+export interface IStorage {
+  readonly root: string;
+  exists(path: string): boolean;
+  assertPath(path: string): void | never;
+  ensurePath(path: string, isDir: boolean = false): void;
+  stat(path: string): Stats | false;
+  scanDir(path: string, ext: string[] = ['json', 'csv']): string[];
+  readJSON<T extends object>(path: string): T | false;
+  writeJSON<T extends object>(path: string, content: T): boolean;
+  readCSV<T extends any[]>(path: string): T | false;
+  writeCSV<T extends any[]>(path: string, content: T): boolean;
+  appendCSV<T extends any[]>(path: string, content: T, nl: boolean = true): boolean;
+  datedCSV<T extends any[]>(path: string, content: T, force: boolean = false): boolean;
+  remove(path: string, force: boolean = true): boolean;
+  move(from: string, to: string, force: boolean = false): boolean;
+}

package/dist/job/Alias.d.ts

@@ -0,0 +1,8 @@
+import { Job } from '../abstract/Job.js';
+import type { TAliasJobOptions, TCommandJob } from '../types/job';
+export declare class AliasJob extends Job<TAliasJobOptions> {
+  private static readonly index;
+  constructor(options: TAliasJobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+}

package/dist/job/Alias.js

@@ -0,0 +1,42 @@
+import { Job } from '../abstract/Job.js';
+import { ProfileIndex } from '../model/ProfileIndex.js';
+import { Parser } from '../parser/Parser.js';
+export class AliasJob extends Job {
+  static index = ProfileIndex.getInstance();
+  constructor(options) {
+    super(options, 'alias');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      for (const a of this.options.removeGlobal ?? []) AliasJob.index.removeAlias(a);
+      if (this.options.profile) {
+        this.options.remove?.length && AliasJob.index.rmvAliases(this.options.profile, ...this.options.remove);
+        this.options.add?.length && AliasJob.index.addAliases(this.options.profile, ...this.options.add);
+      }
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'alias',
+    desc: 'Manage profile aliases',
+    options: [
+      { name: '-p, --profile <URI>', desc: 'The profile URI whose aliases will be edited' },
+      {
+        name: '--add <URIs>',
+        desc: 'Aliases to be added to the profile index item (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      },
+      {
+        name: '--remove <URIs>',
+        desc: 'Aliases to be removed from the profile index item (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      },
+      {
+        name: '-g, --remove-global <URIs>',
+        desc: 'Aliases to remove from any profile index item (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      }
+    ]
+  };
+}

package/dist/job/Annual.d.ts

@@ -0,0 +1,8 @@
+import { Job } from '../abstract/Job.js';
+import type { TAnnualJobOptions, TCommandJob, TCronJob } from '../types/job';
+export declare class AnnualJob extends Job<TAnnualJobOptions> {
+  constructor(options: TAnnualJobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+  static readonly cron: TCronJob<TAnnualJobOptions>;
+}

package/dist/job/Annual.js

@@ -0,0 +1,41 @@
+import { Job } from '../abstract/Job.js';
+import { Parser } from '../parser/Parser.js';
+import { Annual } from '../utils/Annual.js';
+export class AnnualJob extends Job {
+  constructor(options) {
+    super(options, 'annual');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      if (this.options.profiles?.length)
+        for (const uri of this.options.profiles) Annual.generate(uri, this.options.year);
+      else Annual.generateAll(this.options.year);
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'annual',
+    desc: 'Generate annual records for profiles',
+    options: [
+      {
+        name: '-y, --year <YEAR>',
+        desc: 'The year for which to generate annual records',
+        parser: v => Parser.number(v),
+        required: true
+      },
+      {
+        name: '-p, --profiles <URIs>',
+        desc: 'Process specific profiles by URI (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      }
+    ]
+  };
+  // --- cron job definition ---
+  static cron = [
+    {
+      cronexpr: '40 0 1 1 *', // run at 0:40 AM on January 1st every year
+      options: date => ({ year: date.getFullYear() - 1 })
+    }
+  ];
+}

package/dist/job/List.d.ts

@@ -0,0 +1,11 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TCronJob, TListJobOptions } from '../types/job';
+export declare class ListJob extends Job<TListJobOptions> {
+  private static readonly fetch;
+  private static readonly profileQueue;
+  private static readonly queue;
+  constructor(options?: TListJobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+  static readonly cron: TCronJob;
+}