signalk-questdb 2.0.0 → 2.1.0

package/dist/migration.d.ts

@@ -0,0 +1,147 @@
+import type { ILPWriter } from "./ilp-writer.js";
+import type { MigrationBucket, MigrationMeasurement, MigrationProgress, MigrationRunState } from "./api-contract.js";
+/**
+ * How much time one read covers. Small enough that a dense measurement does
+ * not return a result set too large to hold, large enough that a sparse one
+ * does not need thousands of round trips. A day is the natural unit for boat
+ * data: it bounds a busy passage to a few hundred thousand points.
+ */
+export declare const DEFAULT_WINDOW_MS: number;
+export interface InfluxAuth {
+    /** 2.x API token, or 1.x password when `username` is set. */
+    token?: string;
+    username?: string;
+    password?: string;
+    /** 2.x organisation, required by the Flux API. */
+    org?: string;
+}
+export interface MigrationRequest {
+    url: string;
+    /** "influxdb1" or "influxdb2" — decides the query dialect. */
+    type: string;
+    /** Bucket (2.x) or database (1.x). */
+    bucket: string;
+    auth?: InfluxAuth;
+    /** ISO instants bounding the import. */
+    from: string;
+    to: string;
+    /** Signal K context to write rows under. */
+    context: string;
+    /** Restrict to these measurements; empty/absent means all of them. */
+    measurements?: string[];
+    /** `source` tag written on every imported row, so it is distinguishable. */
+    sourceLabel?: string;
+    windowMs?: number;
+}
+/** Buckets (2.x) or databases (1.x) available to import from. */
+export declare function listBuckets(req: {
+    url: string;
+    type: string;
+    auth?: InfluxAuth;
+}, fetchImpl?: typeof fetch): Promise<MigrationBucket[]>;
+/** Measurements in a bucket/database, with the field keys each carries. */
+export declare function listMeasurements(req: {
+    url: string;
+    type: string;
+    bucket: string;
+    auth?: InfluxAuth;
+}, fetchImpl?: typeof fetch): Promise<MigrationMeasurement[]>;
+/**
+ * Minimal annotated-CSV reader for Flux responses.
+ *
+ * Flux emits one or more *tables*, each preceded by annotation lines starting
+ * with `#` and then a header row. A response can therefore change its column
+ * layout partway through, which is why the header is tracked per block rather
+ * than read once at the top.
+ */
+export declare function parseAnnotatedCsv(text: string): AnnotatedRecord[];
+/** One Flux CSV record plus the `#datatype` of each of its columns. */
+export interface AnnotatedRecord {
+    values: Record<string, string>;
+    types: Record<string, string>;
+}
+/**
+ * Parse an RFC3339 instant into nanoseconds since the epoch, preserving digits
+ * below the millisecond.
+ *
+ * `Date.parse` truncates to milliseconds. InfluxDB stores nanoseconds, and the
+ * QuestDB tables dedup on (ts, path, context, source) — so two points 200µs
+ * apart would collide and one would be lost. The fractional part is therefore
+ * read from the string directly.
+ */
+export declare function rfc3339ToNanos(value: string): bigint | null;
+/**
+ * The Signal K path a measurement+field pair represents.
+ *
+ * signalk-to-influxdb writes the path as the measurement name and the value in
+ * a field called `value`. Anything else (a measurement with several named
+ * fields) is a non-Signal K schema, so the field name is appended to keep the
+ * two apart instead of overwriting one with the other.
+ */
+export declare function toSignalKPath(measurement: string, field: string): string;
+/** Coerce an InfluxDB field value (always text over CSV) to a JS value. */
+export declare function coerceValue(raw: string, dataType?: string): unknown;
+export interface MigrationRunHandle {
+    id: string;
+    state: MigrationRunState;
+    url: string;
+    bucket: string;
+    startedAt: string;
+    finishedAt?: string;
+    progress: MigrationProgress;
+    error?: string;
+    cancel(): void;
+}
+/**
+ * A single import run. Holds its own cancellation flag and counters so the
+ * HTTP layer can poll it without the importer knowing about Express.
+ */
+export declare class MigrationRun implements MigrationRunHandle {
+    readonly id: string;
+    readonly url: string;
+    readonly bucket: string;
+    state: MigrationRunState;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+    progress: MigrationProgress;
+    private cancelled;
+    constructor(id: string, url: string, bucket: string);
+    cancel(): void;
+    get isCancelled(): boolean;
+}
+/**
+ * Copy history from InfluxDB into QuestDB.
+ *
+ * Rows are written through the plugin's own ILP writer, so imported history is
+ * subject to exactly the same schema, dedup and retention rules as live data —
+ * and re-running an import is idempotent, because a row with the same
+ * (ts, path, context, source) upserts rather than duplicating.
+ */
+export declare function runMigration(req: MigrationRequest, writer: Pick<ILPWriter, "writeAtNanos" | "writeStringAtNanos" | "writePositionAtNanos" | "pendingLines"> & {
+    readonly droppedLineCount?: number;
+}, run: MigrationRun, deps?: {
+    fetchImpl?: typeof fetch;
+    debug?: (msg: string) => void;
+    /** Injected so tests don't wait on real backpressure sleeps. */
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
+/** One point read out of InfluxDB, normalised across the two dialects. */
+export interface SourceRow {
+    tsNanos: bigint;
+    field: string;
+    value: unknown;
+}
+/**
+ * Recombine latitude/longitude fields of a position measurement into one
+ * object value at the same instant.
+ *
+ * The Signal K InfluxDB plugins store navigation.position as two fields
+ * (`latitude`/`longitude`, or `lat`/`lon`). Left as-is they would import as
+ * two numeric paths and the position history would be unusable — QuestDB keeps
+ * positions in their own table.
+ */
+export declare function mergePositionRows(measurement: string, rows: SourceRow[]): {
+    rows: SourceRow[];
+    dropped: number;
+};