@quanthea/plugin-kit 0.1.0 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ kit to the plugin when it loads it, so the bundle carries none of the kit's code
 ## Write a plugin
 
 The plugin is one bundled ES module. It exports the kit version it is built for and, as default, a
-function that receives the kit and returns its kinds:
+function that receives the kit and returns what the plugin adds, its connector kinds:
 
 ```ts
 import type { ConnectorKit } from '@quanthea/plugin-kit';
@@ -25,7 +25,9 @@ import type { ConnectorKit } from '@quanthea/plugin-kit';
 export const kitVersion = 0;
 
 export default function plugin(kit: ConnectorKit) {
-  return [kit.defineConnector({ kind: 'example', configSchema: kit.z.object({ … }), … })];
+  return {
+    connectors: [kit.defineConnector({ kind: 'example', configSchema: kit.z.object({ … }), … })],
+  };
 }
 ```
 

package/{chunk-3ayrhcmg.js → chunk-9jgedrqw.js}

@@ -1,5 +1,5 @@
 // @bun
-// packages/plugin-kit/src/kit.ts
+// src/kit.ts
 var kitVersion2 = 0;
 
 export { kitVersion2 };

package/dialects.d.ts

@@ -0,0 +1,20 @@
+/** The SQL dialects the core binds, and the styles an `ansi` source picks. */
+/**
+ * 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];

package/host.d.ts

@@ -6,6 +6,7 @@ export { type AnyConnectorKind, type ConnectorIcon, type ConnectorInstance, type
 export { ConnectorError, type ConnectorErrorCode } from './errors.js';
 export { createFrameBuilder } from './frame-builder.js';
 export { createHttpClient, type HttpClient, type HttpResponse } from './http.js';
+export { isMetadataAddress } from './http-address.js';
 export { kitVersion } from './kit.js';
 export { type BoundQuery, type ExecutionContext, type HttpField, type HttpQuery, type LogqlQuery, type MongodbQuery, type PromqlQuery, type QueryLanguage, type RedisQuery, type SearchQuery, type SqlDialect, type SqlParameter, type SqlPlaceholderStyle, type SqlQuery, type SqlRowLimit, sqlDialects, type TimeRange, } from './queries.js';
 export type { FieldReference, HealthReport, SampleResult, SchemaEntity, SchemaField, SchemaSnapshot, } from './schema.js';

package/index.d.ts

@@ -6,7 +6,7 @@
  * import type { ConnectorKit } from '@quanthea/plugin-kit';
  * export const kitVersion = 0;
  * export default function plugin(kit: ConnectorKit) {
- *   return [kit.defineConnector({ kind: 'example', … })];
+ *   return { connectors: [kit.defineConnector({ kind: 'example', … })] };
  * }
  * ```
  */
@@ -15,7 +15,7 @@ export type { ConnectorError, ConnectorErrorCode } from './errors.js';
 export type { FrameBuilder, FrameBuilderOptions } from './frame-builder.js';
 export type { Field, FieldType, Frame } from './frames.js';
 export type { HttpClient, HttpClientOptions, HttpRequest, HttpResponse } from './http.js';
-export { type ConnectorKit, type ConnectorPlugin, kitVersion } from './kit.js';
+export { type ConnectorKit, kitVersion, type Plugin, type PluginContributions } from './kit.js';
 export type { BoundQuery, ExecutionContext, HttpField, HttpQuery, LogqlQuery, MongodbQuery, PromqlQuery, QueryLanguage, RedisQuery, SearchQuery, SqlDialect, SqlParameter, SqlPlaceholderStyle, SqlQuery, SqlRowLimit, TimeRange, } from './queries.js';
 export type { FieldReference, HealthReport, SampleResult, SchemaEntity, SchemaField, SchemaSnapshot, } from './schema.js';
 export type { SeriesData } from './series-frames.js';

package/index.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   kitVersion2
-} from "./chunk-3ayrhcmg.js";
+} from "./chunk-9jgedrqw.js";
 export {
   kitVersion2 as kitVersion
 };

package/kit.d.ts

@@ -1,5 +1,5 @@
 /**
- * The kit quanthea hands a plugin when it loads it, and the shape of a plugin. The kit is the live
+ * The kit quanthea hands a plugin when it loads it, and the shape of a plugin and what it adds. The kit is the live
  * one: its Zod, its error class and its helpers are the server's own, so a plugin's schemas and
  * errors are the ones the core checks.
  */
@@ -29,9 +29,17 @@ export interface ConnectorKit {
     readonly seriesFrames: typeof seriesFrames;
 }
 /**
- * A plugin's default export: given the kit, the connector kinds it adds.
+ * What a plugin adds to quanthea, by kind of contribution. Connector kinds are the one kind today;
+ * others will be added beside them, so a plugin written now keeps loading.
+ */
+export interface PluginContributions {
+    /** The connector kinds the plugin adds. */
+    readonly connectors: readonly ConnectorKind[];
+}
+/**
+ * A plugin's default export: given the kit, what the plugin adds.
  *
  * @param kit - The kit.
- * @returns The kinds.
+ * @returns The contributions.
  */
-export type ConnectorPlugin = (kit: ConnectorKit) => readonly ConnectorKind[];
+export type Plugin = (kit: ConnectorKit) => PluginContributions;

package/naming.d.ts

@@ -0,0 +1,5 @@
+/** How plugins and connector kinds are named, as the loader and the static checks read them. */
+/** A plugin's npm package name: `quanthea-plugin-<name>` or `@scope/quanthea-plugin-<name>`. */
+export declare const pluginNamePattern: RegExp;
+/** A connector kind identifier: lowercase letters, digits and dashes, up to 40 characters. */
+export declare const kindPattern: RegExp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quanthea/plugin-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The connector kit: the types a quanthea connector plugin is written against, a test kit and the conformance suite.",
   "keywords": [
     "quanthea",

package/queries.d.ts

@@ -1,25 +1,7 @@
 /** The queries a connector executes: already bound, never a template with raw variables. */
 import type { QueryLanguage } from './languages.js';
+export { type SqlDialect, type SqlPlaceholderStyle, type SqlRowLimit, sqlDialects, sqlPlaceholderStyles, sqlRowLimits, } from './dialects.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;
 /**

package/testing.js

@@ -1,15 +1,27 @@
 // @bun
 import {
   kitVersion2
-} from "./chunk-3ayrhcmg.js";
+} from "./chunk-9jgedrqw.js";
 
-// packages/plugin-kit/src/testing.ts
+// src/testing.ts
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 
-// packages/plugin-kit/src/checks.ts
+// src/checks.ts
 import { z as z2 } from "zod";
 
-// packages/plugin-kit/src/languages.ts
+// src/dialects.ts
+var sqlDialects = [
+  "postgres",
+  "mysql",
+  "clickhouse",
+  "trino",
+  "influxdb",
+  "ansi"
+];
+var sqlPlaceholderStyles = ["?", "$1", ":1", "@p1"];
+var sqlRowLimits = ["fetch", "limit"];
+
+// src/languages.ts
 import { z } from "zod";
 var queryLanguages = [
   "sql",
@@ -22,20 +34,10 @@ var queryLanguages = [
 ];
 var queryLanguageSchema = z.enum(queryLanguages);
 
-// packages/plugin-kit/src/queries.ts
-var sqlDialects = [
-  "postgres",
-  "mysql",
-  "clickhouse",
-  "trino",
-  "influxdb",
-  "ansi"
-];
-var sqlPlaceholderStyles = ["?", "$1", ":1", "@p1"];
-var sqlRowLimits = ["fetch", "limit"];
-
-// packages/plugin-kit/src/checks.ts
+// src/naming.ts
 var kindPattern = /^[a-z][a-z0-9-]{0,39}$/;
+
+// src/checks.ts
 var pathPattern = /^[MmZzLlHhVvCcSsQqTtAa0-9eE.,\s+-]+$/;
 var colorPattern = /^#[0-9a-fA-F]{6}$/;
 var maxGuideLength = 8192;
@@ -133,7 +135,7 @@ function kindProblems(kind) {
   return [...failed, ...schemaProblems(candidate)];
 }
 
-// packages/plugin-kit/src/errors.ts
+// src/errors.ts
 var connectorErrorCodes = [
   "unreachable",
   "authentication",
@@ -165,7 +167,7 @@ class ConnectorError extends Error {
 }
 Object.defineProperty(ConnectorError.prototype, brand, { value: true });
 
-// packages/plugin-kit/src/frames.ts
+// src/frames.ts
 import { z as z3 } from "zod";
 var fieldTypes = ["time", "number", "string", "boolean"];
 var fieldSchema = z3.object({
@@ -213,11 +215,9 @@ function frameProblems(frame) {
   });
 }
 
-// packages/plugin-kit/src/host.ts
+// src/host.ts
 import { z as z4 } from "zod";
-
-// packages/plugin-kit/src/connector-kind.ts
-var kindPattern2 = /^[a-z][a-z0-9-]*$/;
+// src/connector-kind.ts
 var pathPattern2 = /^[MmZzLlHhVvCcSsQqTtAa0-9eE.,\s+-]+$/;
 var colorPattern2 = /^#[0-9a-fA-F]{6}$/;
 function checkIcon(kind, icon) {
@@ -236,8 +236,8 @@ function checkAnsiStyles(definition) {
     throw new Error(`Connector kind "${kind}" has rowLimit "${rowLimit}": use fetch or limit.`);
 }
 function defineConnector(definition) {
-  if (!kindPattern2.test(definition.kind)) {
-    throw new Error(`Connector kind "${definition.kind}" must be lowercase letters, digits and dashes.`);
+  if (!kindPattern.test(definition.kind)) {
+    throw new Error(`Connector kind "${definition.kind}" must be lowercase letters, digits and dashes, up to 40.`);
   }
   if (definition.language === "sql" && definition.dialect === undefined)
     throw new Error(`Connector kind "${definition.kind}" runs SQL and must declare its dialect.`);
@@ -246,7 +246,7 @@ function defineConnector(definition) {
   return definition;
 }
 
-// packages/plugin-kit/src/frame-builder.ts
+// src/frame-builder.ts
 function createFrameBuilder(options) {
   const columns = options.fields.map(() => []);
   let rowCount = 0;
@@ -275,7 +275,7 @@ function createFrameBuilder(options) {
   };
 }
 
-// packages/plugin-kit/src/http-address.ts
+// src/http-address.ts
 var metadataIpv4 = [/^169\.254\./, /^100\.100\.100\.200$/];
 var metadataIpv6 = [/^fe[89ab][0-9a-f]:/, /^fd00:ec2::254$/];
 var dottedIpv4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
@@ -311,7 +311,7 @@ async function checkDestination(url, sourceName) {
     throw refused;
 }
 
-// packages/plugin-kit/src/http.ts
+// src/http.ts
 var maxRedirects = 5;
 function transportError(error, signal, sourceName) {
   if (error instanceof ConnectorError)
@@ -458,7 +458,7 @@ function createHttpClient(options) {
   };
 }
 
-// packages/plugin-kit/src/series-frames.ts
+// src/series-frames.ts
 var maxSeries = 1000;
 function sampleValue(value) {
   const number = Number(value);
@@ -532,7 +532,7 @@ function seriesFrames(data, context, durationMs) {
   return [builder.build(durationMs)];
 }
 
-// packages/plugin-kit/src/host.ts
+// src/host.ts
 var hostKit = Object.freeze({
   version: kitVersion2,
   z: z4,
@@ -543,7 +543,7 @@ var hostKit = Object.freeze({
   seriesFrames
 });
 
-// packages/plugin-kit/src/testing.ts
+// src/testing.ts
 function createTestKit() {
   return hostKit;
 }