@rtbnext/core 2.0.0-alpha.1

package/dist/core/Fetch.js

@@ -0,0 +1,172 @@
+import axios from 'axios';
+import { Config } from './Config.js';
+import { log } from './Logger.js';
+import { Utils } from './Utils.js';
+import { REGEX_NONUM, REGEX_SPACES } from '../lib/regex.js';
+import { Parser } from '../parser/Parser.js';
+export class Fetch {
+  static instance;
+  config;
+  wikiQuery = { format: 'json', formatversion: 2 };
+  lastRequest = 0;
+  httpClient;
+  constructor() {
+    this.config = Config.getInstance().fetch;
+    this.httpClient = this.setupHttpClient();
+  }
+  // --- set up axios ---
+  setupHttpClient() {
+    const {
+      headers,
+      rateLimit: { timeout }
+    } = this.config;
+    return axios.create({ headers, timeout });
+  }
+  // --- rate limit ---
+  getRandomDelay() {
+    const { max, min } = this.config.rateLimit.requestDelay;
+    const delay = Math.round(Math.random() * (max - min) + min);
+    return new Promise(resolve => setTimeout(resolve, delay));
+  }
+  async applyRateLimit(fn) {
+    if (Date.now() - this.lastRequest < this.config.rateLimit.idle) await this.getRandomDelay();
+    try {
+      return await fn();
+    } finally {
+      this.lastRequest = Date.now();
+    }
+  }
+  // --- headers ---
+  useApiUserAgent() {
+    return { 'User-Agent': this.config.apiAgent, 'Api-User-Agent': this.config.apiAgent };
+  }
+  useRandomUserAgent() {
+    return { 'User-Agent': this.config.agentPool[Math.floor(Math.random() * this.config.agentPool.length)] };
+  }
+  // --- helper ---
+  prepQuery(url, replacements) {
+    return Object.entries(replacements).reduce((acc, [key, value]) => {
+      return acc.replaceAll(`{${key.toUpperCase()}}`, String(value));
+    }, url);
+  }
+  retErr(res, msg, code) {
+    return {
+      success: false,
+      statusCode: code ?? res.statusCode ?? 500,
+      error: msg ?? res.error,
+      duration: res.duration,
+      retries: res.retries
+    };
+  }
+  async fetch(url, method = 'get', headers) {
+    log.debug(`Fetching URL: ${url} via ${method.toUpperCase()}`);
+    headers = { ...this.config.headers, ...headers };
+    const { result: res, ms } = await Utils.measure(async () => {
+      let res;
+      let retries = 0;
+      do {
+        res = await this.applyRateLimit(() => this.httpClient[method](url, { headers }));
+        if (res.status === 200 && res.data) break;
+        log.warn(`Request failed with status: ${res.status}. Retrying ...`);
+      } while (++retries < this.config.rateLimit.retries);
+      return { ...res, retries };
+    });
+    log.info(`Fetched URL: ${url} in ${ms} ms`);
+    return Object.assign(
+      { duration: ms, retries: res.retries },
+      res.status === 200 && res.data
+        ? { success: true, data: res.data }
+        : { success: false, error: `Invalid response status: ${res.status}`, statusCode: res.status }
+    );
+  }
+  // --- fetch methods ---
+  async single(url, method = 'get', header) {
+    return this.fetch(url, method, header);
+  }
+  async batch(urls, method = 'get', header) {
+    const results = [];
+    let url;
+    while ((url = urls.shift()) && results.length < this.config.rateLimit.batchSize)
+      results.push(await this.fetch(url, method, header));
+    if (urls.length) log.warn(`Batch limit reached: ${urls.length} URLs remaining`);
+    return results;
+  }
+  // --- special requests ---
+  async wayback(url, ts) {
+    const res = await this.single(
+      this.prepQuery(this.config.endpoints.wayback, {
+        url: encodeURIComponent(url),
+        ts: Parser.date(ts, 'ymd').replaceAll(REGEX_NONUM, '')
+      }),
+      'get',
+      this.useApiUserAgent()
+    );
+    if (!res?.success || !res.data?.archived_snapshots?.closest?.available)
+      return this.retErr(res, 'No archived snapshot found', 404);
+    return this.single(
+      res.data.archived_snapshots.closest.url.replace('/http', 'if_/http'),
+      'get',
+      this.useApiUserAgent()
+    );
+  }
+  async list(uriLike, year) {
+    const {
+      requests: {
+        list: { chunkSize, maxRequests }
+      }
+    } = this.config;
+    const uri = Utils.sanitize(uriLike),
+      entries = [];
+    let res,
+      count = 0,
+      start = 0,
+      requests = 0;
+    do {
+      res = await this.single(
+        this.prepQuery(this.config.endpoints.list, { uri, year, limit: chunkSize, start }),
+        'get',
+        this.useRandomUserAgent()
+      );
+      if (!res.success) return this.retErr(res);
+      if (!res.data?.personList.count) return this.retErr(res, 'Could not fetch list data', 404);
+      entries.push(...res.data.personList.personsLists);
+      ((count = res.data.personList.count), (start += chunkSize));
+    } while (++requests < maxRequests && start < count);
+    res.data.personList.personsLists = entries;
+    return res;
+  }
+  async profile(...uriLike) {
+    return this.batch(
+      uriLike.map(uri => this.prepQuery(this.config.endpoints.profile, { uri: Utils.sanitize(uri) })),
+      'get',
+      this.useRandomUserAgent()
+    );
+  }
+  async wikidata(sparql) {
+    return this.single(
+      this.prepQuery(this.config.endpoints.wikidata, {
+        sparql: encodeURIComponent(sparql.replace(REGEX_SPACES, ' ').trim())
+      }),
+      'get',
+      this.useApiUserAgent()
+    );
+  }
+  async wikipedia(query, lang = 'en') {
+    return this.single(
+      this.prepQuery(this.config.endpoints.wikipedia, { query: Utils.queryStr({ ...this.wikiQuery, ...query }), lang }),
+      'get',
+      this.useApiUserAgent()
+    );
+  }
+  async commons(query) {
+    return this.single(
+      this.prepQuery(this.config.endpoints.commons, { query: Utils.queryStr({ ...this.wikiQuery, ...query }) }),
+      'get',
+      this.useApiUserAgent()
+    );
+  }
+  // --- instantiate ---
+  static getInstance() {
+    return (Fetch.instance ??= new Fetch());
+  }
+}

package/dist/core/Logger.d.ts

@@ -0,0 +1,30 @@
+import type { ILogger } from '../interfaces/logger';
+import type { TLoggingLevel } from '../types/config';
+export declare class Logger implements ILogger {
+  private static instance;
+  private static readonly LEVEL;
+  private readonly config;
+  private readonly path;
+  private constructor();
+  private shouldLog;
+  private format;
+  private log2Console;
+  private log2File;
+  private log;
+  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): R | undefined;
+  catchAsync<F extends (...args: any[]) => Promise<any>, R = Awaited<ReturnType<F>>>(
+    fn: F,
+    msg: string,
+    level?: TLoggingLevel
+  ): Promise<R | undefined>;
+  getLogFile(date: string): string | undefined;
+  getCurrentLogFile(): string | undefined;
+  static getInstance(): ILogger;
+}
+export declare const log: ILogger;

package/dist/core/Logger.js

@@ -0,0 +1,92 @@
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { exit } from 'node:process';
+import { Config } from './Config.js';
+import { Utils } from './Utils.js';
+export class Logger {
+  static instance;
+  static LEVEL = { error: 0, warn: 1, info: 2, debug: 3 };
+  config;
+  path;
+  constructor() {
+    const { root, logging } = Config.getInstance();
+    this.config = logging;
+    this.path = join(root, 'logs');
+    mkdirSync(this.path, { recursive: true });
+  }
+  // --- helper ---
+  shouldLog(level) {
+    return Logger.LEVEL[level] <= Logger.LEVEL[this.config.level];
+  }
+  format(level, msg, meta) {
+    let entry = `[${Utils.date('iso')}] [${level.toUpperCase()}] ${msg}`;
+    if (meta instanceof Error) entry += `: ${meta.message}`;
+    else if (meta) entry += `: ${JSON.stringify(meta)}`;
+    return entry;
+  }
+  log2Console(level, entry) {
+    (console[level] ?? console.log)(entry);
+  }
+  log2File(entry) {
+    const path = join(this.path, `${Utils.date('ym')}.log`);
+    appendFileSync(path, entry + '\n', 'utf8');
+  }
+  log(level, msg, meta) {
+    if (!this.shouldLog(level)) return;
+    const entry = this.format(level, msg, meta);
+    if (this.config.console) this.log2Console(level, entry);
+    if (this.config.file) this.log2File(entry);
+  }
+  // --- logging methods ---
+  error(msg, err) {
+    this.log('error', msg, err);
+  }
+  errMsg(err, msg) {
+    const message = err instanceof Error ? err.message : String(err);
+    this.log('error', (msg ? `${msg}: ` : '') + message, err);
+  }
+  exit(msg, err) {
+    this.log('error', msg, err);
+    exit(1);
+  }
+  warn(msg, meta) {
+    this.log('warn', msg, meta);
+  }
+  info(msg, meta) {
+    this.log('info', msg, meta);
+  }
+  debug(msg, meta) {
+    this.log('debug', msg, meta);
+  }
+  // --- catch & log errors ---
+  catch(fn, msg, level = 'error') {
+    try {
+      return fn();
+    } catch (err) {
+      this.log(level, msg, err);
+    }
+  }
+  async catchAsync(fn, msg, level = 'error') {
+    try {
+      return await fn();
+    } catch (err) {
+      this.log(level, msg, err);
+    }
+  }
+  // --- get log file ---
+  getLogFile(date) {
+    return this.catch(
+      () => readFileSync(join(this.path, `${date}.log`), 'utf8'),
+      `Could not read log file for date ${date}`
+    );
+  }
+  getCurrentLogFile() {
+    return this.getLogFile(Utils.date('ym'));
+  }
+  // --- instantiate ---
+  static getInstance() {
+    return (Logger.instance ??= new Logger());
+  }
+}
+// --- singleton instance ---
+export const log = Logger.getInstance();

package/dist/core/Queue.d.ts

@@ -0,0 +1,37 @@
+import type { IQueue } from '../interfaces/queue';
+import type { TQueueConfig } from '../types/config';
+import type { TQueue, TQueueItem, TQueueOptions, TQueueType } from '../types/queue';
+export declare abstract class Queue implements IQueue {
+  protected static readonly storage: import('../interfaces/storage').IStorage;
+  protected readonly config: TQueueConfig;
+  protected readonly type: TQueueType;
+  protected readonly path: string;
+  protected queue: TQueue;
+  protected constructor(type: TQueueType);
+  protected loadQueue(): TQueue;
+  protected saveQueue(): void;
+  protected key(uri: string, args?: unknown): string;
+  get 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): boolean;
+  addMany(items: TQueueOptions[]): number;
+  removeByKey(key: string): boolean;
+  remove(...uriLike: string[]): number;
+  next(n?: number): TQueueItem[];
+  nextUri(n?: number): string[];
+}
+export declare class ProfileQueue extends Queue implements IQueue {
+  private static instance;
+  private constructor();
+  static getInstance(): ProfileQueue;
+}
+export declare class ListQueue extends Queue implements IQueue {
+  private static instance;
+  private constructor();
+  static getInstance(): ListQueue;
+}

package/dist/core/Queue.js

@@ -0,0 +1,136 @@
+import { sha256 } from 'js-sha256';
+import { Config } from './Config.js';
+import { log } from './Logger.js';
+import { Storage } from './Storage.js';
+import { Utils } from './Utils.js';
+export class Queue {
+  static storage = Storage.getInstance();
+  config;
+  type;
+  path;
+  queue;
+  constructor(type) {
+    this.config = Config.getInstance().queue;
+    this.type = type;
+    this.path = `queue/${this.type}.json`;
+    Queue.storage.ensurePath(this.path);
+    this.queue = this.loadQueue();
+  }
+  // --- helper ---
+  loadQueue() {
+    log.debug(`Load queue [${this.type}]`);
+    return new Map((Queue.storage.readJSON(this.path) || []).map(i => [i.key, i]));
+  }
+  saveQueue() {
+    const { defaultPrio = 0 } = this.config;
+    Queue.storage.writeJSON(
+      this.path,
+      [...this.queue.values()].sort(
+        (a, b) =>
+          (b.prio ?? defaultPrio) - (a.prio ?? defaultPrio) || new Date(a.ts).getTime() - new Date(b.ts).getTime()
+      )
+    );
+  }
+  key(uri, args) {
+    return sha256(uri + JSON.stringify(args));
+  }
+  // --- basic operations ---
+  get size() {
+    return this.queue.size;
+  }
+  getQueue() {
+    return [...this.queue.values()];
+  }
+  getByKey(key) {
+    return this.queue.get(key);
+  }
+  hasKey(key) {
+    return this.queue.has(key);
+  }
+  getByUri(uriLike) {
+    const uri = Utils.sanitize(uriLike);
+    return [...this.queue.values()].filter(i => i.uri === uri);
+  }
+  hasUri(uriLike) {
+    return this.getByUri(uriLike).length !== 0;
+  }
+  clear() {
+    log.debug(`Clear queue [${this.type}]`);
+    this.queue.clear();
+    this.saveQueue();
+  }
+  // --- add items ---
+  add(opt, save = true) {
+    const { uriLike, args, prio } = opt;
+    return (
+      log.catch(() => {
+        if (this.queue.size > this.config.maxSize) throw new Error(`Queue size limit reached for type: ${this.type}`);
+        const uri = Utils.sanitize(uriLike);
+        const key = this.key(uri, args);
+        const item = this.queue.get(key);
+        const ts = item?.ts ?? Utils.date('iso');
+        const data = { key, uri, ts, args, prio };
+        if (JSON.stringify(item) === JSON.stringify(data)) return false;
+        log.debug(`Add to queue [${this.type}]: ${uri}`, data);
+        this.queue.set(key, data);
+        if (save) this.saveQueue();
+        return true;
+      }, `Failed to add item to queue [${this.type}]: ${uriLike}`) ?? false
+    );
+  }
+  addMany(items) {
+    const added = items.reduce((acc, item) => acc + +this.add(item, false), 0);
+    this.saveQueue();
+    return added;
+  }
+  // --- remove items ---
+  removeByKey(key) {
+    return (
+      this.queue.delete(key) && (log.debug(`Remove from queue [${this.type}] by key: ${key}`), this.saveQueue(), true)
+    );
+  }
+  remove(...uriLike) {
+    const keys = [...new Set(uriLike.map(uri => this.getByUri(uri).map(i => i.key)).flat())];
+    if (keys && keys.length) {
+      keys.forEach(this.queue.delete.bind(this.queue));
+      log.debug(`Remove from queue [${this.type}] by URI(s): ${uriLike}`, keys);
+      this.saveQueue();
+    }
+    return keys.length;
+  }
+  // --- get items from queue (processing) ---
+  next(n = 1) {
+    const items = [];
+    for (const [k, item] of this.queue)
+      if (items.length < n) {
+        items.push(item);
+        this.queue.delete(k);
+      } else break;
+    this.saveQueue();
+    log.debug(`Process ${items.length} item(s) from queue [${this.type}]`, items);
+    return items;
+  }
+  nextUri(n = 1) {
+    return this.next(n)
+      .filter(Boolean)
+      .map(i => i.uri);
+  }
+}
+export class ProfileQueue extends Queue {
+  static instance;
+  constructor() {
+    super('profile');
+  }
+  static getInstance() {
+    return (this.instance ??= new ProfileQueue());
+  }
+}
+export class ListQueue extends Queue {
+  static instance;
+  constructor() {
+    super('list');
+  }
+  static getInstance() {
+    return (this.instance ??= new ListQueue());
+  }
+}

package/dist/core/Storage.d.ts

@@ -0,0 +1,28 @@
+import { type Stats } from 'node:fs';
+import type { IStorage } from '../interfaces/storage';
+export declare class Storage implements IStorage {
+  private static instance;
+  private readonly config;
+  private readonly path;
+  private constructor();
+  private initDB;
+  private resolvePath;
+  private fileExt;
+  private read;
+  private write;
+  get root(): string;
+  exists(path: string): boolean;
+  assertPath(path: string): void | never;
+  ensurePath(path: string, isDir?: boolean): void;
+  stat(path: string): Stats | false;
+  scanDir(path: string, ext?: string[]): 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): boolean;
+  datedCSV<T extends any[]>(path: string, content: T, force?: boolean): boolean;
+  remove(path: string, force?: boolean): boolean;
+  move(from: string, to: string, force?: boolean): boolean;
+  static getInstance(): IStorage;
+}

package/dist/core/Storage.js

@@ -0,0 +1,166 @@
+import { parse, stringify } from 'csv-string';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { Config } from './Config.js';
+import { log } from './Logger.js';
+import { Utils } from './Utils.js';
+export class Storage {
+  static instance;
+  config;
+  path;
+  constructor() {
+    const { root, storage } = Config.getInstance();
+    this.config = storage;
+    this.path = join(root, this.config.baseDir);
+    this.initDB();
+  }
+  initDB() {
+    log.debug(`Initializing storage at ${this.path}`);
+    this.ensurePath(this.path);
+    ['profile', 'list', 'filter', 'mover', 'stats', 'queue'].forEach(path => this.ensurePath(path, true));
+  }
+  // --- helper ---
+  resolvePath(path) {
+    return path.includes(this.path) ? path : join(this.path, path);
+  }
+  fileExt(path) {
+    return extname(this.resolvePath(path)).toLowerCase().slice(1);
+  }
+  read(path, type) {
+    return (
+      log.catch(() => {
+        this.assertPath((path = this.resolvePath(path)));
+        const content = readFileSync(path, 'utf8');
+        switch (type ?? this.fileExt(path)) {
+          case 'raw':
+            return content;
+          case 'json':
+            return JSON.parse(content);
+          case 'csv':
+            return parse(content);
+        }
+        throw new Error(`Unsupported file extension: ${extname(path)}`);
+      }, `Failed to read ${path}`) ?? false
+    );
+  }
+  write(path, content, type, options = { append: false, nl: true }) {
+    return (
+      log.catch(() => {
+        this.ensurePath((path = this.resolvePath(path)));
+        switch (type ?? this.fileExt(path)) {
+          case 'raw':
+            content = String(content);
+            break;
+          case 'json':
+            content = JSON.stringify(content, null, this.config.compression ? undefined : 2).trim();
+            break;
+          case 'csv':
+            content = stringify(content).trim();
+            break;
+          default:
+            throw new Error(`Unsupported file extension: ${extname(path)}`);
+        }
+        if (options.nl && !content.endsWith('\n')) content += '\n';
+        (options.append ? appendFileSync : writeFileSync)(path, content, 'utf8');
+        log.debug(`Wrote data to ${path}`, options);
+        return true;
+      }, `Failed to write ${path}`) ?? false
+    );
+  }
+  // --- path operations ---
+  get root() {
+    return this.path;
+  }
+  exists(path) {
+    return existsSync(this.resolvePath(path));
+  }
+  assertPath(path) {
+    if (!this.exists(path)) throw new Error(`Path ${path} does not exist`);
+  }
+  ensurePath(path, isDir = false) {
+    path = this.resolvePath(path);
+    mkdirSync(isDir ? path : dirname(path), { recursive: true });
+  }
+  stat(path) {
+    return (
+      log.catch(() => {
+        this.assertPath((path = this.resolvePath(path)));
+        return statSync(path);
+      }, `Failed to stat ${path}`) ?? false
+    );
+  }
+  // --- scan dir ---
+  scanDir(path, ext = ['json', 'csv']) {
+    return (
+      log.catch(() => {
+        this.assertPath((path = this.resolvePath(path)));
+        return readdirSync(path).filter(f => ext.includes(extname(f).slice(1).toLowerCase()));
+      }, `Failed to scan ${path}`) ?? []
+    );
+  }
+  // --- JSON files ---
+  readJSON(path) {
+    return this.read(path, 'json');
+  }
+  writeJSON(path, content) {
+    return this.write(path, Utils.sortKeysDeep(content), 'json');
+  }
+  // --- CSV files ---
+  readCSV(path) {
+    return this.read(path, 'csv');
+  }
+  writeCSV(path, content) {
+    return this.write(path, content, 'csv');
+  }
+  appendCSV(path, content, nl = true) {
+    return this.write(path, content, 'csv', { append: true, nl });
+  }
+  datedCSV(path, content, force = false) {
+    const raw = this.readCSV(path) || [];
+    const filtered = raw.filter(r => r[0] !== content[0]);
+    if (!force && raw.length !== filtered.length) return false;
+    return this.writeCSV(
+      path,
+      [...filtered, content].sort((a, b) => a[0].localeCompare(b[0]))
+    );
+  }
+  // --- file operations ---
+  remove(path, force = true) {
+    return (
+      log.catch(() => {
+        this.assertPath((path = this.resolvePath(path)));
+        rmSync(path, { recursive: true, force });
+        log.debug(`Removed ${path}`);
+        return true;
+      }, `Failed to remove ${path}`) ?? false
+    );
+  }
+  move(from, to, force = false) {
+    return (
+      log.catch(() => {
+        this.assertPath((from = this.resolvePath(from)));
+        if (this.exists((to = this.resolvePath(to)))) {
+          if (force) this.remove(to, true);
+          else throw new Error(`Destination path ${to} already exists`);
+        }
+        renameSync(from, to);
+        log.debug(`Moved ${from} to ${to}`);
+        return true;
+      }, `Failed to move ${from} to ${to}`) ?? false
+    );
+  }
+  // --- instantiate ---
+  static getInstance() {
+    return (Storage.instance ??= new Storage());
+  }
+}

package/dist/core/Utils.d.ts

@@ -0,0 +1,33 @@
+import { ArrayMode } from '@komed3/deepmerge';
+import type { TMetaData } from '@rtbnext/schema/src/base/generic';
+import type { ListLike } from 'devtypes/types/list';
+import type { TAggregator, TMeasuredResult, TObjOperator } from '../types/generic';
+import type { TParserDateType } from '../types/parser';
+export declare class Utils {
+  private static readonly mergeInstances;
+  static sanitize(value: unknown, delimiter?: string): string;
+  static hash(value: unknown): string;
+  static verifyHash(value: unknown, hash: string): boolean;
+  static measure<F extends (...args: any[]) => any, R = Awaited<ReturnType<F>>>(fn: F): Promise<TMeasuredResult<R>>;
+  static date(format?: TParserDateType): string;
+  static lastMonthDay(month: string | number, year?: string | number): Date;
+  static metaData<T extends Record<string, unknown>>(obj?: T): TMetaData<T>;
+  static aggregate<T extends Record<PropertyKey, unknown>, K extends keyof T = keyof T, R = unknown>(
+    arr: readonly T[],
+    key: K,
+    aggregator?: TAggregator
+  ): T[K] | T[K][] | number | R | undefined;
+  static update(operator: TObjOperator, obj: any, path: string, n?: any): void;
+  static sort<L extends ListLike>(
+    value: L,
+    compare?: (a: any, b: any) => number,
+    objCompare?: (a: any, b: any) => number
+  ): L;
+  static sortKeysDeep<T>(value: T, exclude?: ReadonlySet<string>): T;
+  static merge<T>(mode: ArrayMode, ...objects: any[]): T;
+  static unique<T = unknown>(arr: T[]): T[];
+  static mergeArray<T = unknown>(target: T[], source: T[], mode?: ArrayMode): T[];
+  static queryStr(query: Record<string, any>): string;
+  static buildSearchText(value: unknown, minLength?: number): string;
+  static tokenSearch(text: string, tokens: string[], looseMatch?: boolean): boolean;
+}