types/t3.d.ts - master - t3/cli

types/t3.d.ts
152 строки6 KB
Ivan
fix TUI metrics
09 июл 2026, 15:21
09 июл 2026, 15:21f8d1b63
export interface Counter {
  add(n: number, tags?: Record<string, string>): void;
  value(): number;
}

export interface Gauge {
  set(v: number): void;
  value(): number;
}

export interface HistogramOptions {
  quantiles?: number[];
}

export interface Histogram {
  record(v: number): void;
}

export function Counter(name: string): Counter;
export function Gauge(name: string): Gauge;
export function Histogram(name: string, opts?: HistogramOptions): Histogram;

// --- S3 Bridge ---

/** Конфигурация S3-совместимого хранилища */
export interface S3Config {
  endpoint: string;
  accessKey: string;
  secretKey: string;
  region: string;
  useSSL: boolean;
}

/**
 * Универсальный файл, скачанный с S3.
 * API по аналогии с fetch Response:
 *  - file.text()          — содержимое как строка (zero-copy)
 *  - file.json()          — содержимое, распарсенное как JSON (deep-copy)
 *  - file.arrayBuffer() — содержимое как ArrayBuffer
 */
export interface File {
  /** Имя файла, извлечённое из URL */
  name: string;
  /** Размер содержимого в байтах */
  size: number;
  /** MIME-тип, если известен из S3-метаданных; иначе пустая строка */
  mimeType: string;
  /** Возвращает содержимое как строку (аналог Response.text()) */
  text(): string;
  /** Возвращает содержимое, распарсенное как JSON (аналог Response.json()) */
  json(): any;
  /** Возвращает содержимое как ArrayBuffer (аналог Response.arrayBuffer()) */
  arrayBuffer(): ArrayBuffer;
}

/** S3-функции */
export interface S3 {
  /**
   * Скачивает файл с S3 (или достает из кэша).
   * Должна быть вызвана в init_agent() для предзагрузки файла.
   * В default()/init() файл должен быть уже предзагружен — иначе будет ошибка.
   */
  download(url: string, config: S3Config): File;

  /** Разбивает содержимое File на массив строк */
  lines(file: File): string[];
  /** Количество строк в файле */
  lineCount(file: File): number;
  /** Строка №n (1-based) */
  readLine(file: File, n: number): string;
}

// --- HTTP Bridge ---

/** Тайминги HTTP-ответа */
export interface ResponseTime {
  /** Время до первого байта (TTFB) в миллисекундах */
  ttfb: number;
  /** Общее время запроса (включая чтение всего тела) в миллисекундах */
  total: number;
}

/** HTTP-ответ (по аналогии с fetch Response) */
export interface HttpResponse {
  /** HTTP статус-код (200, 404, 500 и т.д.) */
  status: number;
  /** Статус-текст (например, "200 OK") */
  statusText: string;
  /** Заголовки ответа (все ключи в lowercase) */
  headers: Record<string, string>;
  /** Тайминги запроса */
  responseTime: ResponseTime;
  /** Возвращает тело ответа как строку */
  text(): string;
  /** Возвращает тело ответа, распарсенное как JSON */
  json(): any;
  /** Возвращает тело ответа как ArrayBuffer */
  arrayBuffer(): ArrayBuffer;
}

/** Опции HTTP-запроса */
export interface RequestOptions {
  /** HTTP-метод: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS (по умолчанию GET) */
  method?: string;
  /** Тело запроса (строка) */
  body?: string;
  /** Заголовки запроса (дополняют/перезаписывают общие заголовки клиента) */
  headers?: Record<string, string>;
}

/** Конфигурация HTTP-клиента */
export interface HttpClientConfig {
  /** Базовый URL для относительных путей */
  baseURL?: string;
  /** Общие заголовки для всех запросов клиента */
  headers?: Record<string, string>;
  /** Отключить проверку TLS-сертификатов */
  insecureSkipVerify?: boolean;
  /** Клиентский TLS-сертификат в PEM-формате (строка или File из S3) */
  tlsCert?: string | File;
  /** Приватный ключ клиентского TLS-сертификата в PEM-формате (строка или File из S3) */
  tlsKey?: string | File;
  /** Таймаут запроса в миллисекундах (0 = без таймаута) */
  timeoutMs?: number;
}

/** HTTP-клиент для нагрузочных сценариев */
export interface HttpClient {
  /**
   * Выполняет HTTP-запрос.
   * url может быть абсолютным ("https://...") или относительным (резолвится через baseURL клиента).
   */
  fetch(url: string, options?: RequestOptions): HttpResponse;
}

// --- HTTP функции в t3 ---

export interface HttpBridge {
  /** Создаёт новый HTTP-клиент с заданной конфигурацией */
  newClient(config: HttpClientConfig): HttpClient;
}

export interface T3 {
  Counter: typeof Counter;
  Gauge: typeof Gauge;
  Histogram: typeof Histogram;
  s3: S3;
  http: HttpBridge;
}

/** Глобальный объект t3 */
export const t3: T3;