@toa.io/extensions.exposition 1.0.0-alpha.14 → 1.0.0-alpha.143

package/transpiled/HTTP/messages.js

@@ -1,15 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.read = exports.write = void 0;
+exports.multipart = exports.read = exports.write = void 0;
 const node_stream_1 = require("node:stream");
 const consumers_1 = require("node:stream/consumers");
+const openspan_1 = require("openspan");
 const formats_1 = require("./formats");
 const exceptions_1 = require("./exceptions");
-function write(context, response, message) {
+const server = `Exposition/${require('../../package.json').version}` +
+    ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
+        (process.env.TOA_ENV === undefined ? '' : `/${process.env.TOA_ENV}`));
+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 (response.destroyed) {
+        openspan_1.console.warn('Request destroyed prematurely', { path: context.url.pathname });
+        return;
+    }
     if (message.body instanceof node_stream_1.Readable)
         stream(message, context, response);
     else
@@ -27,13 +38,15 @@ async function read(context) {
     try {
         return format.decode(buf);
     }
-    catch {
+    catch (error) {
+        openspan_1.console.debug('Failed to decode message', { path: context.url.pathname, error });
         throw new exceptions_1.BadRequest();
     }
 }
 exports.read = read;
 function send(message, context, response) {
     if (message.body === undefined || message.body === null) {
+        response.setHeader('content-length', '0');
         response.end();
         return;
     }
@@ -42,6 +55,7 @@ function send(message, context, response) {
     const buf = context.encoder.encode(message.body);
     response
         .setHeader('content-type', context.encoder.type)
+        .setHeader('content-length', buf.length.toString())
         .appendHeader('vary', 'accept')
         .end(buf);
 }
@@ -51,8 +65,8 @@ function stream(message, context, response) {
         message.body.pipe(response);
     else
         multipart(message, context, response);
-    message.body.on('error', (e) => {
-        console.error(e);
+    message.body.on('error', (exception) => {
+        openspan_1.console.error('Stream error', { path: context.url.pathname, exception });
         response.end();
     });
 }
@@ -61,11 +75,29 @@ function multipart(message, context, response) {
         throw new exceptions_1.NotAcceptable();
     const encoder = context.encoder;
     response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`);
+    response.write(Buffer.concat([
+        CUT,
+        CRLF,
+        encoder.encode('ACK'),
+        CRLF,
+        CUT
+    ]));
     message.body
-        .map((part) => Buffer.concat([CUT, encoder.encode(part), CRLF]))
-        .on('end', () => response.end(FINALCUT))
+        .map((part) => Buffer.concat([
+        CRLF /* indicates no boundary headers */,
+        encoder.encode(part),
+        CRLF,
+        CUT
+    ]))
+        .on('end', () => response.end(Buffer.concat([
+        CRLF,
+        encoder.encode('FIN'),
+        CRLF,
+        FINALCUT
+    ])))
         .pipe(response);
 }
+exports.multipart = multipart;
 const BOUNDARY = 'cut';
 const CUT = Buffer.from(`--${BOUNDARY}\r\n`);
 const CRLF = Buffer.from('\r\n');

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/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,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# 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 { Query } from './Query';
+import type { Introspection, Schema } from './Introspection';
+import type { QueryString } from './Query';
 import type * as http from './HTTP';
 import type * as syntax from './RTD/syntax';
 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,38 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Mapping = void 0;
+exports.queryable = exports.Mapping = void 0;
 const Query_1 = require("./Query");
 class Mapping {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
     static create(query) {
-        if (query === undefined || query === null)
-            return new InputMapping();
         const q = new Query_1.Query(query);
-        return new QueryableMapping(q);
+        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);
+        }
     }
 }
 exports.Mapping = Mapping;
 class QueryableMapping extends Mapping {
-    query;
-    constructor(query) {
-        super();
-        this.query = query;
-    }
-    fit(input, qs, parameters) {
-        const query = this.query.fit(qs, parameters);
-        return {
-            input,
-            query
-        };
+    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) {
-        if (input === undefined && parameters.length > 0)
+    queryable = false;
+    fit(input, query, parameters) {
+        const request = {};
+        const qs = this.query.fit(query, parameters);
+        if (input === undefined && (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 route parameters');
             for (const parameter of parameters)
                 input[parameter.name] = parameter.value;
-        return { input };
+        }
+        this.assign(input, qs);
+        if (input !== undefined)
+            request.input = input;
+        return request;
     }
 }
+function queryable(query) {
+    if (query === undefined || query === null)
+        return false;
+    const keys = Object.keys(query);
+    return !(keys.length === 1 && keys[0] === 'parameters');
+}
+exports.queryable = queryable;
 //# 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,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,OAAO,EAAE,KAAK,EAAE,CAAA;IAClB,CAAC;CACF"}
+{"version":3,"file":"Mapping.js","sourceRoot":"","sources":["../source/Mapping.ts"],"names":[],"mappings":"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"}

package/transpiled/Query.d.ts

@@ -1,13 +1,22 @@
 import * as http from './HTTP';
 import { type Parameter } from './RTD';
+import type { Introspection, Schema } from './Introspection';
 import type * as syntax from './RTD/syntax';
 import type * as core from '@toa.io/core';
 export declare class Query {
     private readonly query;
     private readonly closed;
+    private readonly prepend;
+    private readonly queryable;
     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;
+}

package/transpiled/Query.js

@@ -22,65 +22,121 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Query = void 0;
+const node_assert_1 = __importDefault(require("node:assert"));
 const http = __importStar(require("./HTTP"));
 const schemas = __importStar(require("./schemas"));
+const Mapping_1 = require("./Mapping");
 class Query {
     query;
     closed = false;
+    prepend = ';';
+    queryable;
     constructor(query) {
-        if (query.criteria !== undefined) {
-            const open = query.criteria[query.criteria.length - 1] === ';';
-            if (open)
-                query.criteria = query.criteria.slice(0, -1);
-            else
-                this.closed = true;
+        this.queryable = (0, Mapping_1.queryable)(query);
+        if (this.queryable) {
+            query.omit ??= { value: 0, range: [0, 1000] };
+            query.limit ??= { value: 10, range: [1, 100] };
+            if (query.criteria !== undefined) {
+                // eslint-disable-next-line max-depth
+                if (query.criteria.endsWith(';'))
+                    query.criteria = query.criteria.slice(0, -1);
+                else
+                    this.closed = true;
+                // eslint-disable-next-line max-depth
+                if (query.criteria.startsWith(',') || query.criteria.startsWith(';')) {
+                    this.prepend = query.criteria[0];
+                    query.criteria = query.criteria.slice(1);
+                }
+            }
         }
         this.query = query;
     }
     fit(query, parameters) {
-        const error = schemas.querystring.fit(query);
-        if (error !== null)
-            throw new http.BadRequest('Query ' + error.message);
-        this.fitCriteria(query, parameters);
-        this.fitRanges(query);
-        this.fitSort(query);
+        const qs = this.split(query);
+        if (qs.query !== null) {
+            const error = schemas.querystring.fit(qs.query);
+            if (error !== null)
+                throw new http.BadRequest('Query ' + error.message);
+            this.fitCriteria(qs.query, parameters);
+            this.fitRanges(qs.query);
+            this.fitSort(qs.query);
+        }
+        return {
+            query: qs.query,
+            parameters: qs.parameters
+        };
+    }
+    explain(introspection) {
+        if (this.query?.parameters === undefined || introspection.input?.type !== 'object')
+            return null;
+        let query = null;
+        for (const parameter of this.query.parameters) {
+            const schema = introspection.input.properties[parameter];
+            if (schema !== undefined) {
+                query ??= {};
+                query[parameter] = schema;
+            }
+            delete introspection.input.properties[parameter];
+        }
         return query;
     }
+    split(query) {
+        let parameters = null;
+        if (this.query?.parameters !== undefined)
+            for (const key in query)
+                // eslint-disable-next-line max-depth
+                if (this.query.parameters.includes(key)) {
+                    parameters ??= {};
+                    parameters[key] = query[key];
+                    delete query[key];
+                }
+        if (!this.queryable) {
+            const keys = Object.keys(query);
+            if (keys.length > 0)
+                throw new http.BadRequest(`Query parameter '${keys[0]}' is not allowed`);
+            query = null;
+        }
+        return {
+            query,
+            parameters
+        };
+    }
     fitCriteria(query, parameters) {
-        const criteria = [];
-        if (this.query.criteria !== undefined)
-            criteria.push(this.query.criteria);
+        const groups = [];
         const idx = parameters.findIndex((parameter) => parameter.name === 'id');
         if (idx !== -1) {
             query.id = parameters[idx].value;
             parameters.splice(idx, 1);
         }
         if (parameters.length > 0) {
-            const chunks = parameters
+            const criteria = parameters
                 .map(({ name, value }) => `${name}==${value}`)
                 .join(';');
-            criteria.push(chunks);
+            groups.push({ criteria, operator: this.prepend });
         }
+        if (this.query.criteria !== undefined)
+            groups.push({ criteria: this.query.criteria, operator: ';' });
         if (query.criteria !== undefined)
             if (this.closed)
-                throw new http.BadRequest('Query criteria is closed.');
+                throw new http.BadRequest('Query criteria is closed');
             else
-                criteria.push(query.criteria);
-        switch (criteria.length) {
-            case 0:
-                break;
-            case 1:
-                query.criteria = criteria[0];
-                break;
-            default:
-                query.criteria = '(' + criteria.join(');(') + ')';
-                break;
-        }
+                groups.push({ criteria: query.criteria, operator: WHATEVER });
+        if (groups.length > 0)
+            query.criteria = groups.reduce((acc, { criteria, operator }, i) => {
+                return i === groups.length - 1
+                    ? `${acc}(${criteria})`
+                    : `${acc}(${criteria})${operator}`;
+            }, '');
     }
     fitRanges(qs) {
         const query = qs;
+        node_assert_1.default.ok(this.query.limit !== undefined, 'Query limit must be defined');
+        node_assert_1.default.ok(this.query.omit !== undefined, 'Query limit range must be defined');
         if (qs.limit !== undefined)
             query.limit = fit(qs.limit, this.query.limit.range, 'limit');
         else
@@ -101,7 +157,8 @@ function fit(string, range, name) {
     const number = parseInt(string);
     if (number < range[0] || number > range[1])
         throw new http.BadRequest(`Query ${name} must be between ` +
-            `${range[0]} and ${range[1]} inclusive.`);
+            `${range[0]} and ${range[1]} inclusive`);
     return number;
 }
+const WHATEVER = ';';
 //# sourceMappingURL=Query.js.map

package/transpiled/Query.js.map

@@ -1 +1 @@
-{"version":3,"file":"Query.js","sourceRoot":"","sources":["../source/Query.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6CAA8B;AAE9B,mDAAoC;AAIpC,MAAa,KAAK;IACC,KAAK,CAAc;IACnB,MAAM,GAAY,KAAK,CAAA;IAExC,YAAoB,KAAmB;QACrC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,CAAA;YAE9D,IAAI,IAAI;gBAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;;gBACjD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QACzB,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,GAAG,CAAE,KAAiB,EAAE,UAAuB;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAE5C,IAAI,KAAK,KAAK,IAAI;YAChB,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAA;QAErD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QACnC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QACrB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAEnB,OAAO,KAAmB,CAAA;IAC5B,CAAC;IAEO,WAAW,CAAE,KAAiB,EAAE,UAAuB;QAC7D,MAAM,QAAQ,GAAa,EAAE,CAAA;QAE7B,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS;YACnC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QAEpC,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;QAExE,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,KAAK,CAAC,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAA;YAEhC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAC3B,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,UAAU;iBACtB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,KAAK,EAAE,CAAC;iBAC7C,IAAI,CAAC,GAAG,CAAC,CAAA;YAEZ,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACvB,CAAC;QAED,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;YAC9B,IAAI,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAA;;gBAClE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QAEpC,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxB,KAAK,CAAC;gBACJ,MAAK;YACP,KAAK,CAAC;gBACJ,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;gBAC5B,MAAK;YACP;gBACE,KAAK,CAAC,QAAQ,GAAG,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAA;gBACjD,MAAK;QACT,CAAC;IACH,CAAC;IAEO,SAAS,CAAE,EAAc;QAC/B,MAAM,KAAK,GAAG,EAAgB,CAAA;QAE9B,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;YACxB,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;;YAE5D,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAA;QAEtC,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS;YACvB,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC5D,CAAC;IAEO,OAAO,CAAE,EAAc;QAC7B,MAAM,KAAK,GAAG,EAAgB,CAAA;QAE9B,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS;YACxD,OAAM;QAER,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;QAEtD,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;CACF;AAxFD,sBAwFC;AAED,SAAS,GAAG,CAAE,MAAc,EAAE,KAAuB,EAAE,IAAY;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;IAE/B,IAAI,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;QACxC,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,IAAI,mBAAmB;YACxD,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAA;IAE7C,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"Query.js","sourceRoot":"","sources":["../source/Query.ts"],"names":[],"mappings":"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"}

package/transpiled/RTD/Context.d.ts

@@ -8,5 +8,5 @@ export interface Context<TExtension = any> {
         readonly factory: DirectiveFactory;
         stack: Directive[];
     };
-    readonly extension?: TExtension;
+    readonly extension: TExtension;
 }

package/transpiled/RTD/Endpoint.d.ts

@@ -4,6 +4,7 @@ import type * as syntax from './syntax';
 import type * as RTD from './index';
 export interface Endpoint {
     call: (context: http.Context, parameters: RTD.Parameter[]) => Promise<http.OutgoingMessage>;
+    explain: (parameters: RTD.Parameter[]) => Promise<unknown>;
     close: () => Promise<void>;
 }
 export interface EndpointsFactory {

package/transpiled/RTD/Method.d.ts

@@ -1,9 +1,13 @@
+import type { Parameter } from './Match';
 import type { Endpoint } from './Endpoint';
 import type { Directives } from './Directives';
 export declare class Method {
     readonly endpoint: Endpoint | null;
     readonly directives: Directives;
+    private introspection;
+    private introspecting;
     constructor(endpoint: Endpoint | null, directives: Directives);
+    explain(parameters: Parameter[]): Promise<unknown>;
     close(): Promise<void>;
 }
 export type Methods = Record<string, Method>;

package/transpiled/RTD/Method.js

@@ -4,10 +4,21 @@ exports.Method = void 0;
 class Method {
     endpoint;
     directives;
+    introspection = null;
+    introspecting = null;
     constructor(endpoint, directives) {
         this.endpoint = endpoint;
         this.directives = directives;
     }
+    async explain(parameters) {
+        if (this.introspection !== null)
+            return this.introspection;
+        if (this.introspecting === null)
+            // eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain
+            this.introspecting = this.endpoint?.explain(parameters);
+        this.introspection = await this.introspecting;
+        return this.introspection;
+    }
     async close() {
         await this.endpoint?.close();
     }

package/transpiled/RTD/Method.js.map

@@ -1 +1 @@
-{"version":3,"file":"Method.js","sourceRoot":"","sources":["../../source/RTD/Method.ts"],"names":[],"mappings":";;;AAGA,MAAa,MAAM;IACD,QAAQ,CAAiB;IACzB,UAAU,CAAY;IAEtC,YAAoB,QAAyB,EAAE,UAAsB;QACnE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,MAAM,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC9B,CAAC;CACF;AAZD,wBAYC"}
+{"version":3,"file":"Method.js","sourceRoot":"","sources":["../../source/RTD/Method.ts"],"names":[],"mappings":";;;AAIA,MAAa,MAAM;IACD,QAAQ,CAAiB;IACzB,UAAU,CAAY;IAC9B,aAAa,GAAmB,IAAI,CAAA;IACpC,aAAa,GAA4B,IAAI,CAAA;IAErD,YAAoB,QAAyB,EAAE,UAAsB;QACnE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;IAEM,KAAK,CAAC,OAAO,CAAE,UAAuB;QAC3C,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI;YAC7B,OAAO,IAAI,CAAC,aAAa,CAAA;QAE3B,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI;YAC7B,kFAAkF;YAClF,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAE,CAAA;QAE1D,IAAI,CAAC,aAAa,GAAG,MAAM,IAAI,CAAC,aAAa,CAAA;QAE7C,OAAO,IAAI,CAAC,aAAa,CAAA;IAC3B,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,MAAM,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC9B,CAAC;CACF;AA3BD,wBA2BC"}

package/transpiled/RTD/Node.d.ts

@@ -3,17 +3,20 @@ import { type Methods } from './Method';
 import { type Match, type Parameter } from './Match';
 export declare class Node {
     intermediate: boolean;
+    forward: string | null;
     methods: Methods;
     private readonly protected;
     private routes;
     constructor(routes: Route[], methods: Methods, properties: Properties);
     match(fragments: string[], parameters?: Parameter[]): Match | null;
     merge(node: Node): void;
+    explain(parameters: Parameter[]): Promise<Record<string, unknown>>;
     private replace;
     private append;
-    private mergeRoute;
+    private route;
     private sort;
 }
 export interface Properties {
     protected: boolean;
+    forward?: string;
 }

package/transpiled/RTD/Node.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Node = void 0;
 class Node {
     intermediate;
+    forward;
     methods;
     protected;
     routes;
@@ -10,12 +11,14 @@ class Node {
         this.routes = routes;
         this.methods = methods;
         this.protected = properties.protected;
+        this.forward = properties.forward ?? null;
         this.intermediate = this.routes.findIndex((route) => route.root) !== -1;
         this.sort();
     }
     match(fragments, parameters = []) {
         for (const route of this.routes) {
-            const match = route.match(fragments, parameters);
+            const params = parameters.slice();
+            const match = route.match(fragments, params);
             if (match !== null)
                 return match;
         }
@@ -23,30 +26,34 @@ class Node {
     }
     merge(node) {
         this.intermediate = node.intermediate;
-        if (!this.protected)
-            this.replace(node);
-        else
+        if (this.protected)
             this.append(node);
+        else
+            this.replace(node);
         this.sort();
     }
+    async explain(parameters) {
+        const methods = {};
+        const explained = Object.entries(this.methods)
+            .map(async ([verb, method]) => (methods[verb] = await method.explain(parameters)));
+        await Promise.all(explained);
+        return methods;
+    }
     replace(node) {
         const methods = Object.values(this.methods);
         this.routes = node.routes;
         this.methods = node.methods;
+        // race condition is really unlikely
         for (const method of methods)
             void method.close();
-        // race condition is really unlikely
     }
     append(node) {
         for (const route of node.routes)
-            this.mergeRoute(route);
+            this.route(route);
         for (const [verb, method] of Object.entries(node.methods))
-            if (verb in this.methods)
-                console.warn(`Overriding of the protected method ${verb} is not permitted.`);
-            else
-                this.methods[verb] = method;
+            this.methods[verb] = method;
     }
-    mergeRoute(candidate) {
+    route(candidate) {
         for (const route of this.routes)
             if (candidate.equals(route)) {
                 route.merge(candidate);
@@ -55,7 +62,11 @@ class Node {
         this.routes.push(candidate);
     }
     sort() {
-        this.routes.sort((a, b) => a.variables - b.variables);
+        this.routes.sort((a, b) => {
+            return a.variables === b.variables
+                ? b.segments.length - a.segments.length // routes with more segments should be matched first
+                : a.variables - b.variables; // routes with more variables should be matched last
+        });
     }
 }
 exports.Node = Node;