@toa.io/extensions.exposition 1.0.0-alpha.28 → 1.0.0-alpha.283

package/transpiled/HTTP/messages.js

@@ -1,73 +1,144 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.read = exports.write = void 0;
-const node_stream_1 = require("node:stream");
-const consumers_1 = require("node:stream/consumers");
-const formats_1 = require("./formats");
-const exceptions_1 = require("./exceptions");
-function write(context, response, message) {
+import { readFileSync } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createHash } from 'node:crypto';
+import * as contentType from 'content-type';
+import { console } from 'openspan';
+import { decoders } from './formats/index.js';
+import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js';
+const server = `Exposition/${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
+    ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
+        (process.env.TOA_ENV === undefined ? '' : `/${process.env.TOA_ENV}`));
+const pending = new Map();
+export async function write(context, response, message) {
     for (const transform of context.pipelines.response)
-        transform(message);
+        await transform(message);
+    if (message?.status !== undefined)
+        response.statusCode = message.status;
+    response.setHeader('server', server);
     message.headers?.forEach((value, key) => response.setHeader(key, value));
     context.timing.append(response);
-    if (message.body instanceof node_stream_1.Readable)
+    if (response.destroyed) {
+        console.warn('Request destroyed prematurely', { path: context.url.pathname });
+        return;
+    }
+    response.on('error', (exception) => console.warn('HTTP response error', { path: context.url.pathname, exception }));
+    if (message.body instanceof Readable)
         stream(message, context, response);
     else
         send(message, context, response);
 }
-exports.write = write;
-async function read(context) {
-    const type = context.request.headers['content-type'];
-    if (type === undefined)
+export async function read(context) {
+    const header = context.request.headers['content-type'];
+    if (header === undefined)
         return undefined;
-    if (!(type in formats_1.formats))
-        throw new exceptions_1.UnsupportedMediaType();
-    const format = formats_1.formats[type];
-    const buf = await context.timing.capture('buffer', (0, consumers_1.buffer)(context.request));
+    const { type, parameters } = contentType.parse(header);
+    if (!(type in decoders))
+        throw new UnsupportedMediaType();
+    const format = decoders[type];
+    const buf = await context.buffer();
     try {
-        return format.decode(buf);
+        return format.decode(buf, parameters.charset);
     }
-    catch {
-        throw new exceptions_1.BadRequest();
+    catch (error) {
+        console.debug('Failed to decode message', {
+            path: context.url.pathname,
+            error: error?.toString?.()
+        });
+        throw new BadRequest();
     }
 }
-exports.read = read;
 function send(message, context, response) {
     if (message.body === undefined || message.body === null) {
+        // a HEAD reply carries no body but must still report the length a GET would
+        // have returned, so a length already set by a directive is left alone
+        if (!response.hasHeader('content-length'))
+            response.setHeader('content-length', '0');
         response.end();
         return;
     }
     if (context.encoder === null)
-        throw new exceptions_1.NotAcceptable();
+        throw new NotAcceptable();
     const buf = context.encoder.encode(message.body);
-    response
-        .setHeader('content-type', context.encoder.type)
-        .appendHeader('vary', 'accept')
-        .end(buf);
+    if (message.etag === true && conditional(context, response, buf))
+        return;
+    response.setHeader('content-type', context.encoder.type);
+    response.setHeader('content-length', buf.length.toString());
+    response.appendHeader('vary', 'accept');
+    response.end(buf);
+}
+/**
+ * Tags a reply that carries no version with a hash of the body being sent, and answers
+ * `304` when the client already has it. The tag is taken from the encoded body rather
+ * than from a serialization of its own, so it identifies the representation — which is
+ * what `vary` says.
+ */
+function conditional(context, response, buf) {
+    const etag = `"${createHash('sha256').update(buf).digest('hex')}"`;
+    response.setHeader('etag', etag);
+    if (context.request.headers['if-none-match'] !== etag)
+        return false;
+    response.setHeader('content-length', '0');
+    response.appendHeader('vary', 'accept');
+    response.statusCode = 304;
+    response.end();
+    return true;
 }
 function stream(message, context, response) {
     const encoded = message.headers !== undefined && message.headers.has('content-type');
-    if (encoded)
-        message.body.pipe(response);
-    else
-        multipart(message, context, response);
-    message.body.on('error', (e) => {
-        console.error(e);
-        response.end();
-    });
+    const source = encoded ? message.body : multipart(message, context, response);
+    // not awaited: a reply that streams is written long after the request is answered, and a
+    // realtime subscription outlives the span the reply was produced in
+    //
+    // `pipeline` carries an error to every stage and destroys them. `pipe` leaves the stages it
+    // built behind, and an `error` on a stream nobody listens to is an uncaught exception.
+    pipeline(source, response)
+        .catch((exception) => console.warn('Message stream error', { path: context.url.pathname, exception }));
+    if (context.debug)
+        debugStream(context, response);
 }
-function multipart(message, context, response) {
+/**
+ * Frames an object stream as `multipart/*`: an `ACK` part, the parts themselves, then `FIN`.
+ * The body is a `Readable`; `write` reached here by testing it.
+ */
+export function multipart(message, context, response) {
     if (context.encoder === null)
-        throw new exceptions_1.NotAcceptable();
+        throw new NotAcceptable();
     const encoder = context.encoder;
     response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`);
-    message.body
-        .map((part) => Buffer.concat([CUT, encoder.encode(part), CRLF]))
-        .on('end', () => response.end(FINALCUT))
-        .pipe(response);
+    return Readable.from(frames(message.body, encoder));
+}
+async function* frames(body, encoder) {
+    yield Buffer.concat([CUT, CRLF, encoder.encode('ACK'), CRLF, CUT]);
+    for await (const part of body)
+        yield Buffer.concat([
+            CRLF /* indicates no boundary headers */,
+            encoder.encode(part),
+            CRLF,
+            CUT
+        ]);
+    yield Buffer.concat([CRLF, encoder.encode('FIN'), CRLF, FINALCUT]);
 }
 const BOUNDARY = 'cut';
 const CUT = Buffer.from(`--${BOUNDARY}\r\n`);
 const CRLF = Buffer.from('\r\n');
 const FINALCUT = Buffer.from(`--${BOUNDARY}--`);
+const PENDING_DEBUG_INTERVAL = 30000;
+let pendingInterval = null;
+function debugStream(context, response) {
+    const ctx = { method: context.request.method, path: context.url.pathname };
+    console.debug('Stream opened', ctx);
+    pending.set(context.id, ctx);
+    response.on('close', () => {
+        console.debug('Stream closed', ctx);
+        pending.delete(context.id);
+        if (pending.size === 0) {
+            if (pendingInterval !== null)
+                clearInterval(pendingInterval);
+            pendingInterval = null;
+        }
+    });
+    if (pendingInterval === null)
+        pendingInterval = setInterval(() => console.debug('Pending streams', { size: pending.size }), PENDING_DEBUG_INTERVAL);
+}
 //# sourceMappingURL=messages.js.map

package/transpiled/HTTP/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../source/HTTP/messages.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../source/HTTP/messages.ts"],"names":[],"mappings":"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"}

package/transpiled/HTTP/types.d.ts

@@ -0,0 +1,37 @@
+import type { Readable, Writable } from 'node:stream';
+import type { OutgoingHttpHeaders } from 'node:http';
+import type { IncomingHttpHeaders } from 'node:http2';
+/**
+ * What Exposition requires of a request. Both `http.IncomingMessage` and
+ * `http2.Http2ServerRequest` satisfy it, so the pipeline is written once.
+ */
+export interface IncomingMessage extends Readable {
+    url: string;
+    method: string;
+    complete: boolean;
+    headers: IncomingHeaders;
+    socket: {
+        remoteAddress?: string | undefined;
+    };
+}
+/**
+ * What Exposition requires of a response.
+ *
+ * `setHeader` and `appendHeader` return `void` because `Http2ServerResponse` returns
+ * nothing from them, so neither can be chained.
+ */
+export interface ServerResponse extends Writable {
+    statusCode: number;
+    writableEnded: boolean;
+    setHeader: (name: string, value: number | string | string[]) => void;
+    appendHeader: (name: string, value: string | string[]) => void;
+    hasHeader: (name: string) => boolean;
+    writeHead: (status: number, headers?: OutgoingHttpHeaders) => ServerResponse;
+}
+/**
+ * HTTP/2's header map: HTTP/1.1's, plus the pseudo-headers. `:authority` is typed here
+ * so the authority can be read without narrowing at every call site.
+ */
+export type IncomingHeaders = IncomingHttpHeaders;
+/** `h2c` is cleartext HTTP/2: there is no in-process TLS to negotiate ALPN with. */
+export type Protocol = 'h1' | 'h2c';

package/transpiled/HTTP/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/transpiled/HTTP/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/HTTP/types.ts"],"names":[],"mappings":""}

package/transpiled/Interception.d.ts

@@ -1,9 +1,14 @@
-import type { Input, Output } from './io';
+import type * as http from './HTTP/index.js';
+import type { Input, Output } from './io.js';
 export declare class Interception implements Interceptor {
     private readonly interceptors;
-    constructor(interceptors: Interceptor[]);
+    constructor(interceptors: Interceptor[], options: http.Options);
     intercept(input: Input): Promise<Output>;
 }
 export interface Interceptor {
     intercept: (input: Input) => Output | Promise<Output>;
+    /** Discards whatever the interceptor accumulated while serving. */
+    reset?: () => void;
+    /** What the annotation says, for an interceptor that answers from it. */
+    mount?: (options: http.Options) => void;
 }

package/transpiled/Interception.js

@@ -1,10 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Interception = void 0;
-class Interception {
+export class Interception {
     interceptors;
-    constructor(interceptors) {
+    constructor(interceptors, options) {
         this.interceptors = interceptors;
+        // interceptors are module singletons, so a second gateway in one process —
+        // which is how the features run — would otherwise inherit the first one's state
+        for (const interceptor of interceptors) {
+            interceptor.reset?.();
+            interceptor.mount?.(options);
+        }
     }
     async intercept(input) {
         for (const interceptor of this.interceptors) {
@@ -15,5 +18,4 @@ class Interception {
         return null;
     }
 }
-exports.Interception = Interception;
 //# sourceMappingURL=Interception.js.map

package/transpiled/Interception.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interception.js","sourceRoot":"","sources":["../source/Interception.ts"],"names":[],"mappings":";;;AAEA,MAAa,YAAY;IACN,YAAY,CAAe;IAE5C,YAAoB,YAA2B;QAC7C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAEM,KAAK,CAAC,SAAS,CAAE,KAAY;QAClC,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YAEjD,IAAI,MAAM,KAAK,IAAI;gBACjB,OAAO,MAAM,CAAA;QACjB,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAjBD,oCAiBC"}
+{"version":3,"file":"Interception.js","sourceRoot":"","sources":["../source/Interception.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,YAAY;IACN,YAAY,CAAe;IAE5C,YAAoB,YAA2B,EAAE,OAAqB;QACpE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAEhC,2EAA2E;QAC3E,gFAAgF;QAChF,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,WAAW,CAAC,KAAK,EAAE,EAAE,CAAA;YACrB,WAAW,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAA;QAC9B,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,SAAS,CAAE,KAAY;QAClC,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YAEjD,IAAI,MAAM,KAAK,IAAI;gBACjB,OAAO,MAAM,CAAA;QACjB,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/transpiled/Introspection.d.ts

@@ -0,0 +1,9 @@
+import type { Remote } from '@toa.io/core';
+export interface Introspection {
+    route?: Record<string, Schema>;
+    query?: Record<string, Schema>;
+    input?: Schema;
+    output?: Schema;
+    errors?: string[];
+}
+export type Schema = Awaited<ReturnType<Remote['explain']>>['input'];

package/transpiled/Introspection.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Introspection.js.map

package/transpiled/Introspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Introspection.js","sourceRoot":"","sources":["../source/Introspection.ts"],"names":[],"mappings":""}

package/transpiled/Mapping.d.ts

@@ -1,8 +1,17 @@
-import { type Parameter } from './RTD';
-import type * as http from './HTTP';
-import type * as syntax from './RTD/syntax';
+import { type Parameter } from './RTD/index.js';
+import { Query } from './Query.js';
+import type { Introspection, Schema } from './Introspection.js';
+import type { QueryString } from './Query.js';
+import type * as http from './HTTP/index.js';
+import type * as syntax from './RTD/syntax/index.js';
 import type * as core from '@toa.io/core';
 export declare abstract class Mapping {
-    static create(query?: syntax.Query): Mapping;
-    abstract fit(input: any, qs: http.Query, parameters: Parameter[]): core.Request;
+    protected readonly query: Query;
+    abstract readonly queryable: boolean;
+    constructor(query: Query);
+    static create(query?: syntax.Query | null): Mapping;
+    explain(introspection: Introspection): Record<string, Schema> | null;
+    protected assign(input: any, qs: QueryString): void;
+    abstract fit(input: any, query: http.Query, parameters: Parameter[]): core.Request;
 }
+export declare function queryable(query?: syntax.Query | null): boolean;

package/transpiled/Mapping.js

@@ -1,41 +1,65 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Mapping = void 0;
-const Query_1 = require("./Query");
-class Mapping {
-    static create(query) {
-        if (query === undefined || query === null)
-            return new InputMapping();
-        const q = new Query_1.Query(query);
-        return new QueryableMapping(q);
-    }
-}
-exports.Mapping = Mapping;
-class QueryableMapping extends Mapping {
+import { Query } from './Query.js';
+export class Mapping {
     query;
     constructor(query) {
-        super();
         this.query = query;
     }
-    fit(input, qs, parameters) {
-        const query = this.query.fit(qs, parameters);
-        return {
-            input,
-            query
-        };
+    static create(query) {
+        const q = new Query(query);
+        return queryable(query)
+            ? new QueryableMapping(q)
+            : new InputMapping(q);
+    }
+    explain(introspection) {
+        return this.query.explain(introspection);
+    }
+    assign(input, qs) {
+        if (qs.parameters !== null) {
+            if (typeof input !== 'object' || input === null)
+                throw new Error('Input must be an object to embed query parameters');
+            Object.assign(input, qs.parameters);
+        }
+    }
+}
+class QueryableMapping extends Mapping {
+    queryable = true;
+    fit(input, query, parameters) {
+        const request = {};
+        const qs = this.query.fit(query, parameters);
+        if (input === undefined && qs.parameters !== null)
+            input = {};
+        this.assign(input, qs);
+        if (input !== undefined)
+            request.input = input;
+        if (qs.query !== null)
+            request.query = qs.query;
+        return request;
     }
 }
 class InputMapping extends Mapping {
-    fit(input, _, parameters) {
+    queryable = false;
+    fit(input, query, parameters) {
         const request = {};
-        if (input === undefined && parameters.length > 0)
+        const qs = this.query.fit(query, parameters);
+        if (input === undefined &&
+            (this.query.parameterized || parameters.length > 0 || qs.parameters !== null))
             input = {};
-        if (typeof input === 'object' && input !== null)
+        if (parameters.length > 0) {
+            if (typeof input !== 'object' || input === null)
+                throw new Error('Input must be an object to embed parameters');
             for (const parameter of parameters)
                 input[parameter.name] = parameter.value;
+        }
+        this.assign(input, qs);
         if (input !== undefined)
             request.input = input;
         return request;
     }
 }
+export function queryable(query) {
+    if (query === undefined || query === null)
+        return false;
+    const keys = Object.keys(query);
+    return !(keys.length === 1 && keys[0] === 'parameters');
+}
 //# sourceMappingURL=Mapping.js.map

package/transpiled/Mapping.js.map

@@ -1 +1 @@
-{"version":3,"file":"Mapping.js","sourceRoot":"","sources":["../source/Mapping.ts"],"names":[],"mappings":";;;AACA,mCAA+B;AAK/B,MAAsB,OAAO;IACpB,MAAM,CAAC,MAAM,CAAE,KAAoB;QACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YACvC,OAAO,IAAI,YAAY,EAAE,CAAA;QAE3B,MAAM,CAAC,GAAG,IAAI,aAAK,CAAC,KAAK,CAAC,CAAA;QAE1B,OAAO,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAA;IAChC,CAAC;CAGF;AAXD,0BAWC;AAED,MAAM,gBAAiB,SAAQ,OAAO;IACnB,KAAK,CAAO;IAE7B,YAAoB,KAAY;QAC9B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,GAAG,CAAE,KAAU,EAAE,EAAc,EAAE,UAAuB;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;QAE5C,OAAO;YACL,KAAK;YACL,KAAK;SACN,CAAA;IACH,CAAC;CACF;AAED,MAAM,YAAa,SAAQ,OAAO;IACzB,GAAG,CAAE,KAAU,EAAE,CAAU,EAAE,UAAuB;QACzD,MAAM,OAAO,GAAiB,EAAE,CAAA;QAEhC,IAAI,KAAK,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAC9C,KAAK,GAAG,EAAE,CAAA;QAEZ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAC7C,KAAK,MAAM,SAAS,IAAI,UAAU;gBAChC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAA;QAE3C,IAAI,KAAK,KAAK,SAAS;YACrB,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QAEvB,OAAO,OAAO,CAAA;IAChB,CAAC;CACF"}
+{"version":3,"file":"Mapping.js","sourceRoot":"","sources":["../source/Mapping.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAOlC,MAAM,OAAgB,OAAO;IACR,KAAK,CAAO;IAG/B,YAAoB,KAAY;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,MAAM,CAAC,MAAM,CAAE,KAA2B;QAC/C,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,KAAM,CAAC,CAAA;QAE3B,OAAO,SAAS,CAAC,KAAK,CAAC;YACrB,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC;YACzB,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;IACzB,CAAC;IAEM,OAAO,CAAE,aAA4B;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1C,CAAC;IAES,MAAM,CAAE,KAAU,EAAE,EAAe;QAC3C,IAAI,EAAE,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAC7C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;YAEtE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;CAGF;AAED,MAAM,gBAAiB,SAAQ,OAAO;IACX,SAAS,GAAG,IAAI,CAAA;IAElC,GAAG,CAAE,KAAU,EAAE,KAAiB,EAAE,UAAuB;QAChE,MAAM,OAAO,GAAiB,EAAE,CAAA;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QAE5C,IAAI,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,UAAU,KAAK,IAAI;YAC/C,KAAK,GAAG,EAAE,CAAA;QAEZ,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAEtB,IAAI,KAAK,KAAK,SAAS;YACrB,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QAEvB,IAAI,EAAE,CAAC,KAAK,KAAK,IAAI;YACnB,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAA;QAE1B,OAAO,OAAO,CAAA;IAChB,CAAC;CACF;AAED,MAAM,YAAa,SAAQ,OAAO;IACP,SAAS,GAAG,KAAK,CAAA;IAEnC,GAAG,CAAE,KAAU,EAAE,KAAiB,EAAE,UAAuB;QAChE,MAAM,OAAO,GAAiB,EAAE,CAAA;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QAE5C,IAAI,KAAK,KAAK,SAAS;YACrB,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,KAAK,IAAI,CAAC;YAC7E,KAAK,GAAG,EAAE,CAAA;QAEZ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAC7C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;YAEhE,KAAK,MAAM,SAAS,IAAI,UAAU;gBAChC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAA;QAC3C,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAEtB,IAAI,KAAK,KAAK,SAAS;YACrB,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QAEvB,OAAO,OAAO,CAAA;IAChB,CAAC;CACF;AAED,MAAM,UAAU,SAAS,CAAE,KAA2B;IACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QACvC,OAAO,KAAK,CAAA;IAEd,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAE/B,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,YAAY,CAAC,CAAA;AACzD,CAAC"}

package/transpiled/Query.d.ts

@@ -1,14 +1,24 @@
-import * as http from './HTTP';
-import { type Parameter } from './RTD';
-import type * as syntax from './RTD/syntax';
+import * as http from './HTTP/index.js';
+import { type Parameter } from './RTD/index.js';
+import type { Introspection, Schema } from './Introspection.js';
+import type * as syntax from './RTD/syntax/index.js';
 import type * as core from '@toa.io/core';
 export declare class Query {
+    readonly parameterized: boolean;
     private readonly query;
     private readonly closed;
     private readonly prepend;
+    private readonly queryable;
+    private readonly searchable;
     constructor(query: syntax.Query);
-    fit(query: http.Query, parameters: Parameter[]): core.Query;
+    fit(query: http.Query, parameters: Parameter[]): QueryString;
+    explain(introspection: Introspection): Record<string, Schema> | null;
+    private split;
     private fitCriteria;
     private fitRanges;
     private fitSort;
 }
+export interface QueryString {
+    query: core.Query | null;
+    parameters: Record<string, string> | null;
+}