@tailglow/cli 0.6.5 → 0.8.1

package/src/import.generated.d.ts

@@ -0,0 +1,155 @@
+import type { Transferable } from "node:worker_threads";
+
+export type ImportFormat = "xml" | "jsonl" | "json" | "csv" | "tsv";
+export interface ImportSource {
+  name: string;
+  size: number;
+  open(): AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>;
+  /**
+   * Optional random access to the same immutable bytes: exactly `end - start` bytes from `start`.
+   * Parallel XML reads need it, so they never load a whole file.
+   */
+  read?(start: number, end: number): Promise<Uint8Array>;
+}
+export interface ImportRow {
+  index: number;
+  record: Record<string, unknown>;
+}
+export interface ImportProgress {
+  bytes_read: number;
+  total_bytes: number;
+  rows: number;
+}
+/** A dedicated `Worker`, or a worker_threads adapter from `createNodeImportWorker`. */
+export interface ImportWorker {
+  postMessage(message: unknown, transfer: Transferable[]): void;
+  addEventListener(
+    type: "message" | "messageerror" | "error",
+    listener: (event: any) => void
+  ): void;
+  terminate(): unknown;
+}
+/**
+ * Execution diagnostics for one read or scan. Never part of an ImportReport: results are identical
+ * with any worker count.
+ */
+export interface ImportWorkerStatus {
+  /** Workers chosen before startup; 0 reads on the calling thread. */
+  requested: number;
+  /** Workers that completed the readiness handshake; 0 reads on the calling thread. */
+  actual: number;
+  /** Why the read is sequential, or why fewer workers started than requested. */
+  reason?: string;
+  /** Sent in a second status when workers stopped and the rest was read on the calling thread. */
+  fallback?: string;
+}
+export interface ImportOptions {
+  format?: ImportFormat | "auto";
+  /** Optional XML filter; omitted imports all direct root children plus bounded root context. */
+  record_path?: string;
+  signal?: AbortSignal;
+  onprogress?: (progress: ImportProgress) => void;
+  /**
+   * XML worker count for complete reads (readImportRows and full scans) of sources with `read`.
+   * Default "auto": two workers for 32 MiB or more on four or more logical processors. 0 reads on
+   * the calling thread; 1 to 16 skips the size and processor checks. Other values reject.
+   */
+  workers?: "auto" | number;
+  /** Starts one worker running this package's worker entry. Without it reads are sequential. */
+  create_worker?: () => ImportWorker;
+  /** Called when the execution mode is known, and again if workers fall back. */
+  onworkers?: (status: ImportWorkerStatus) => void;
+}
+export interface Detection {
+  format: ImportFormat;
+  is_sampled: boolean;
+  bytes_read: number;
+  xml?: {
+    root_name: string | null;
+    record_paths: Array<{ path: string; count: number }>;
+    recommended_path: string | null;
+  };
+  warnings: string[];
+}
+export interface FieldProfile {
+  path: string;
+  label: string;
+  types: string[];
+  present: number;
+  missing: number;
+}
+export interface TimestampCandidate {
+  path: string;
+  label: string;
+  valid: number;
+  invalid: number;
+  missing: number;
+  ambiguous: number;
+  min: string | null;
+  max: string | null;
+}
+export interface ImportReport {
+  format: ImportFormat;
+  is_sampled: boolean;
+  is_complete: boolean;
+  bytes_read: number;
+  total_bytes: number;
+  row_count: number;
+  preview: ImportRow[];
+  fields: FieldProfile[];
+  timestamp_candidates: TimestampCandidate[];
+  xml?: NonNullable<Detection["xml"]> & { record_path?: string };
+  warnings: string[];
+  max_row_bytes: number;
+}
+export interface ImportScanOptions extends ImportOptions {
+  is_full?: boolean;
+  /** Selected timestamps must be valid, explicit-zone values between the Unix epoch and now. */
+  timestamp_field?: string;
+}
+export interface ImportBatchOptions {
+  /** Selected timestamps must be valid, explicit-zone values between the Unix epoch and now. */
+  timestamp_field?: string;
+  max_bytes?: number;
+  max_rows?: number;
+}
+export interface ImportBatch {
+  index: number;
+  body: string;
+  bytes: number;
+  rows: ImportRow[];
+  timestamp: string | null;
+}
+export const IMPORT_BATCH_BYTES: number;
+export const IMPORT_BATCH_ROWS: number;
+export const IMPORT_JSON_BYTES: number;
+export const IMPORT_MAX_WORKERS: number;
+export function createBlobSource(blob: Blob, name?: string): ImportSource;
+export function detectImport(source: ImportSource, options?: ImportOptions): Promise<Detection>;
+export function readImportRows(
+  source: ImportSource,
+  options?: ImportOptions
+): AsyncGenerator<ImportRow>;
+export function scanImport(
+  source: ImportSource,
+  options?: ImportScanOptions
+): Promise<ImportReport>;
+/** JSON pointer, or an exact top-level key. Never traverses inherited properties. */
+export function getImportField(record: Record<string, unknown>, path: string): unknown;
+/** Explicit-zone ISO/Apple dates, ten-digit epoch seconds or thirteen-digit epoch milliseconds. */
+export function parseImportTimestamp(value: unknown): string | null;
+/** The line excludes its trailing newline; bytes includes that newline. */
+export function serializeImportRow(row: ImportRow): { row: ImportRow; line: string; bytes: number };
+export function createImportBatches(
+  rows: AsyncIterable<ImportRow> | Iterable<ImportRow>,
+  options?: ImportBatchOptions
+): AsyncGenerator<ImportBatch>;
+
+/** HTTP statuses treated as explicit batch rejection by import delivery clients. */
+export const IMPORT_REJECTED_STATUSES: readonly number[];
+
+/**
+ * Start a worker_threads worker for parallel XML reads. Pass `() => createNodeImportWorker()` as
+ * `create_worker`; bundled callers pass the URL of their bundled `src/worker.node.js`.
+ */
+export function createNodeImportWorker(entry?: URL | string): ImportWorker;