@quanthea/plugin-kit 0.1.0

package/queries.d.ts

@@ -0,0 +1,151 @@
+/** The queries a connector executes: already bound, never a template with raw variables. */
+import type { QueryLanguage } from './languages.js';
+export type { QueryLanguage };
+/**
+ * The SQL dialects the core knows how to bind: how each writes its literals and its placeholders.
+ * A SQL connector kind declares one of them. `ansi` is standard SQL, for the sources the others do
+ * not fit; its kind also picks a placeholder style and a row-limit style.
+ */
+export declare const sqlDialects: readonly ["postgres", "mysql", "clickhouse", "trino", "influxdb", "ansi"];
+/** A SQL dialect name. */
+export type SqlDialect = (typeof sqlDialects)[number];
+/**
+ * How an `ansi` source writes a placeholder: `?` (JDBC, ODBC, SQLite, Snowflake), `$1` (numbered,
+ * as PostgreSQL), `:1` (numbered, as Oracle) or `@p1` (named, as SQL Server drivers).
+ */
+export declare const sqlPlaceholderStyles: readonly ["?", "$1", ":1", "@p1"];
+/** A placeholder style. */
+export type SqlPlaceholderStyle = (typeof sqlPlaceholderStyles)[number];
+/** How an `ansi` source limits rows: `FETCH FIRST n ROWS ONLY`, the standard, or `LIMIT n`. */
+export declare const sqlRowLimits: readonly ["fetch", "limit"];
+/** A row-limit style. */
+export type SqlRowLimit = (typeof sqlRowLimits)[number];
+/** A value bound to a SQL placeholder. */
+export type SqlParameter = string | number | boolean | Date | null;
+/**
+ * A SQL query with positional placeholders and their values. The placeholders are the dialect's:
+ * `$1`, `$2`… for `postgres`, `?` for `mysql` and `trino`, `{p1:Type}`, `{p2:Type}`… for
+ * `clickhouse`, `$p1`, `$p2`… for `influxdb`, and the kind's placeholder style for `ansi`, where `pN`
+ * is the Nth value. The core checked that it is a single read statement.
+ */
+export interface SqlQuery {
+    /** The query language. */
+    readonly language: 'sql';
+    /** The statement, with the dialect's placeholders. */
+    readonly text: string;
+    /** The placeholder values, in order. */
+    readonly parameters: readonly SqlParameter[];
+}
+/** A PromQL expression with every variable already substituted and escaped. */
+export interface PromqlQuery {
+    /** The query language. */
+    readonly language: 'promql';
+    /** The expression. */
+    readonly expr: string;
+    /** `true` evaluates once at the end of the time range; `false` over the range. */
+    readonly instant: boolean;
+    /** Seconds between points of a range query. */
+    readonly stepSeconds: number;
+}
+/**
+ * A search request in the Elasticsearch and OpenSearch query DSL, every variable already put in
+ * as a JSON value. The core checked that the body holds no script.
+ */
+export interface SearchQuery {
+    /** The query language. */
+    readonly language: 'search';
+    /** The index, index pattern or comma-separated list of them. */
+    readonly index: string;
+    /** The search body: `query`, `aggs`, `sort`, `size` and the like. */
+    readonly body: Readonly<Record<string, unknown>>;
+}
+/** A LogQL expression with every variable already substituted and escaped. */
+export interface LogqlQuery {
+    /** The query language. */
+    readonly language: 'logql';
+    /** The expression: a log query or a metric query. */
+    readonly expr: string;
+    /** `true` evaluates once at the end of the time range; `false` over the range. */
+    readonly instant: boolean;
+    /** Seconds between points of a metric range query. */
+    readonly stepSeconds: number;
+}
+/** How a column of an HTTP response is read. */
+export interface HttpField {
+    /** The column name. */
+    readonly name: string;
+    /** Where the value is in each row, as a JSON pointer from the row. */
+    readonly pointer: string;
+    /** The column type; inferred from the values when absent. */
+    readonly type?: 'time' | 'number' | 'string' | 'boolean' | undefined;
+    /** For a time given as a number: seconds or milliseconds since the epoch. */
+    readonly unit?: 's' | 'ms' | undefined;
+}
+/**
+ * An HTTP request with every variable already put in: the path encoded, each query parameter a
+ * separate value, the body's variables JSON values. The connector checks the method and the path
+ * against what its settings allow.
+ */
+export interface HttpQuery {
+    /** The query language. */
+    readonly language: 'http';
+    /** `GET` or `POST`. */
+    readonly method: 'GET' | 'POST';
+    /** The path under the connector's base URL, encoded, without a query string. */
+    readonly path: string;
+    /** The query parameters, in order; a name may repeat. */
+    readonly query: readonly (readonly [string, string])[];
+    /** The JSON body of a POST. */
+    readonly body?: Readonly<Record<string, unknown>> | undefined;
+    /** How the response becomes a table. */
+    readonly extract: {
+        /** The array of rows, as a JSON pointer. */
+        readonly rows: string;
+        /** The columns, or none to take every value of the rows. */
+        readonly fields?: readonly HttpField[] | undefined;
+    };
+}
+/** A Redis or Valkey read command, with every variable put in. The core checked it only reads. */
+export interface RedisQuery {
+    /** The query language. */
+    readonly language: 'redis';
+    /** The command, upper case. */
+    readonly command: string;
+    /** Its arguments, each sent as one argument whatever it holds. */
+    readonly args: readonly string[];
+}
+/**
+ * A MongoDB aggregation over one collection, every variable already put in as a JSON value. The
+ * stages are Extended JSON (`{"$date": …}` for a date), and the core checked that none writes or
+ * runs JavaScript.
+ */
+export interface MongodbQuery {
+    /** The query language. */
+    readonly language: 'mongodb';
+    /** The collection the pipeline starts from. */
+    readonly collection: string;
+    /** The stages, each an object with one `$` key. */
+    readonly pipeline: readonly Readonly<Record<string, unknown>>[];
+}
+/** A query ready to execute. Connectors receive nothing else. */
+export type BoundQuery = SqlQuery | PromqlQuery | SearchQuery | LogqlQuery | HttpQuery | RedisQuery | MongodbQuery;
+/** The time range a query covers. */
+export interface TimeRange {
+    /** The start, inclusive. */
+    readonly from: Date;
+    /** The end, inclusive. */
+    readonly to: Date;
+}
+/** What the core asks of one execution. Connectors must respect every field. */
+export interface ExecutionContext {
+    /** The name of the frames this query returns. */
+    readonly refId: string;
+    /** Aborted on timeout or when the caller gives up. Stop work and reject when it fires. */
+    readonly signal: AbortSignal;
+    /** The query timeout, for sources that enforce one themselves (a statement timeout). */
+    readonly timeoutMs: number;
+    /** Rows (or points) to return at most, per frame. Mark the frame truncated when there are more. */
+    readonly maxRows: number;
+    /** The time range of the query. */
+    readonly timeRange: TimeRange;
+}

package/schema.d.ts

@@ -0,0 +1,58 @@
+/** What a connector reports about its source: health, schema and sample values. */
+import type { FieldType } from './frames.js';
+/** The result of a connection test. */
+export interface HealthReport {
+    /** Whether the source answered and the credentials worked. */
+    readonly ok: boolean;
+    /** Round-trip time of the test, in milliseconds. */
+    readonly latencyMs: number;
+    /** A short sentence for the admin, such as the server version or why the test failed. */
+    readonly message: string;
+    /** Whether the credentials can only read: `true`, `false`, or `null` when the source cannot tell. */
+    readonly readOnly: boolean | null;
+}
+/** One field of a schema entity: a column, a label, a document field. */
+export interface SchemaField {
+    /** The field name as queries write it. */
+    readonly name: string;
+    /** The source's own type name, such as `timestamptz` or `keyword`. */
+    readonly nativeType: string;
+    /** The frame type the field maps to, when known. */
+    readonly type?: FieldType;
+    /** A description from the source, such as a column comment. */
+    readonly description?: string;
+    /** An estimate of the number of distinct values, when the source knows it cheaply. */
+    readonly distinctEstimate?: number;
+}
+/** A queryable thing in the source: a table, a view, a metric, an index. */
+export interface SchemaEntity {
+    /** The name as queries write it, qualified when the source needs it (`public.orders`). */
+    readonly name: string;
+    /** What kind of thing it is, for display. */
+    readonly kind: 'table' | 'view' | 'metric' | 'index' | 'endpoint' | 'collection';
+    /** A description from the source, such as a table comment or a metric's help text. */
+    readonly description?: string;
+    /** An estimate of the number of rows or series, when the source knows it cheaply. */
+    readonly rowEstimate?: number;
+    /** The fields. */
+    readonly fields: readonly SchemaField[];
+}
+/** The shape of a source: every entity and its fields, never their values. */
+export interface SchemaSnapshot {
+    /** The entities, in the order to show them. */
+    readonly entities: readonly SchemaEntity[];
+}
+/** Names one field of one entity. */
+export interface FieldReference {
+    /** The entity name, as in {@link SchemaEntity.name}. */
+    readonly entity: string;
+    /** The field name, as in {@link SchemaField.name}. */
+    readonly field: string;
+}
+/** Distinct values of a field. */
+export interface SampleResult {
+    /** At most the requested number of distinct values. */
+    readonly values: readonly string[];
+    /** `false` when the field has more distinct values than were requested. */
+    readonly complete: boolean;
+}

package/series-frames.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Turns labelled series, in the result format of the Prometheus HTTP API, into frames. Prometheus
+ * answers in it, and so do Loki's metric queries.
+ */
+import type { Frame } from './frames.js';
+import type { ExecutionContext } from './queries.js';
+/** One series of a range query. */
+interface MatrixSeries {
+    /** The series labels, including `__name__` when the query keeps it. */
+    readonly metric: Readonly<Record<string, string>>;
+    /** The points: Unix seconds and the value as a string. */
+    readonly values: readonly (readonly [number, string])[];
+}
+/** One sample of an instant query. */
+interface VectorSample {
+    /** The series labels. */
+    readonly metric: Readonly<Record<string, string>>;
+    /** The point: Unix seconds and the value as a string. */
+    readonly value: readonly [number, string];
+}
+/** The `data` of a query response: series over time, samples at one time, or one value. */
+export type SeriesData = {
+    readonly resultType: 'matrix';
+    readonly result: readonly MatrixSeries[];
+} | {
+    readonly resultType: 'vector';
+    readonly result: readonly VectorSample[];
+} | {
+    readonly resultType: 'scalar' | 'string';
+    readonly result: readonly [number, string];
+};
+/**
+ * Converts a sample value.
+ *
+ * @param value - The value as the API writes it, such as `"0.084"`, `"NaN"` or `"+Inf"`.
+ * @returns The number, or `null` when it is not finite.
+ */
+export declare function sampleValue(value: string): number | null;
+/**
+ * The display name of a series: its metric name and labels.
+ *
+ * @param metric - The series labels.
+ * @returns Such as `http_requests_total{service="checkout-svc"}`, or `{}` for no labels.
+ */
+export declare function seriesName(metric: Readonly<Record<string, string>>): string;
+/**
+ * Turns a series result into frames: one per series over time, one table of samples at one time.
+ *
+ * @param data - The `data` of the response.
+ * @param context - The execution context.
+ * @param durationMs - How long the query took.
+ * @returns The frames.
+ */
+export declare function seriesFrames(data: SeriesData, context: ExecutionContext, durationMs: number): Frame[];
+export {};

package/testing.d.ts

@@ -0,0 +1,36 @@
+import type { ConnectorKind } from './connector-kind.js';
+import type { ConnectorKit } from './kit.js';
+import type { BoundQuery, TimeRange } from './queries.js';
+import type { FieldReference } from './schema.js';
+/** What the suite needs to exercise a kind. */
+export interface ConformanceFixture {
+    /** A valid configuration, before parsing. */
+    readonly config: unknown;
+    /** Valid credentials, before parsing. */
+    readonly secret: unknown;
+    /** A query that returns at least two rows over {@link ConformanceFixture.timeRange}. */
+    readonly query: BoundQuery;
+    /** A query the source rejects, to check the error. */
+    readonly invalidQuery: BoundQuery;
+    /** A field with at least two distinct values. */
+    readonly sampleField: FieldReference;
+    /** The time range to query. */
+    readonly timeRange: TimeRange;
+    /** Whether a source is available. Without one, only the static checks run. */
+    readonly live: boolean;
+    /** Names the source in the test titles, when a kind runs against several. */
+    readonly label?: string;
+}
+/**
+ * The kit to call a plugin with in its tests: the same functions quanthea passes at load.
+ *
+ * @returns The kit.
+ */
+export declare function createTestKit(): ConnectorKit;
+/**
+ * Registers the conformance tests of a connector kind.
+ *
+ * @param kind - The connector kind under test.
+ * @param fixture - How to exercise it.
+ */
+export declare function testConnectorConformance(kind: ConnectorKind, fixture: ConformanceFixture): void;