@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.300

package/transpiled/MCP/tools.js

@@ -0,0 +1,109 @@
+import * as http from '../HTTP/index.js';
+import { fork } from '../RPC/Context.js';
+import { address, name, split } from '../RPC/names.js';
+import { METHOD_NOT_FOUND, failure, refusal, response } from './errors.js';
+import { annotations, input, output } from './schema.js';
+import { FAMILY, MCP } from '../directives/mcp/index.js';
+import { describing } from '../Introspection.js';
+import { variables } from '../RTD/segment.js';
+/**
+ * Every method this caller may reach that is published as a tool, named as the procedure
+ * it is.
+ *
+ * A method is a tool where it says so with `mcp:tool`, and a default denies: a tree holds
+ * what an application serves, and most of it is machinery a model has no business reading.
+ * What a caller may then do with one is what `auth` says. The tree is walked once and each
+ * method describes itself, which is where that is decided and where `io` and `map` say what
+ * may be sent.
+ *
+ * Sorted, because the revision asks for an order a client can cache on.
+ */
+export async function list(tree, request) {
+    const tools = [];
+    /*
+     * A description, not the request asking. What refuses a credentialed request at an
+     * `anonymous` route does not refuse the call a tool makes, and a list that says otherwise
+     * disagrees with what `tools/call` then does.
+     */
+    const context = describing(request);
+    for (const { segments, verb, method } of tree.walk()) {
+        if (!MCP.published(method.directives.declared(FAMILY)))
+            continue;
+        const named = name(segments, verb);
+        // a route a name cannot spell is a route nothing addresses, here or at `/.rpc`
+        if (named === null)
+            continue;
+        const params = variables(segments);
+        const introspection = await method.explain(context, params);
+        if (introspection === null)
+            continue;
+        const described = introspection.description;
+        const schema = output(introspection);
+        const hints = annotations(verb);
+        // in the order the revision documents one, which is the order it is read in
+        const tool = {
+            name: named,
+            ...(introspection.title === undefined ? {} : { title: introspection.title }),
+            ...(described === undefined ? {} : { description: described }),
+            inputSchema: input(introspection, params.map((param) => param.name), method.endpoint?.selection() ?? null),
+            ...(schema === undefined ? {} : { outputSchema: schema }),
+            ...(hints === undefined ? {} : { annotations: hints })
+        };
+        tools.push(tool);
+    }
+    return tools.sort((one, other) => (one.name < other.name ? -1 : 1));
+}
+/**
+ * The call the tool is. Its arguments are the procedure's parameters, taken apart the way a
+ * request carries them, and what answers is the same `route` an ordinary request goes to.
+ *
+ * A name that is not a published tool is answered as no tool at all, whether or not a route
+ * would have taken it: what an application did not publish is not reachable here by guessing
+ * its name. What the caller may then do with one that is published is still `auth`'s to say.
+ */
+export async function call(scope, named, args) {
+    if (!published(scope.tree, named))
+        throw new http.NotFound(response(null, failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)));
+    const { path, verb, variables } = address(named, args);
+    const { query, input: body } = split(args, variables);
+    const clone = fork(scope.context, path, verb, query, body);
+    try {
+        const message = await scope.route(clone);
+        // what `io:output` restricts, over this call's reply rather than the envelope
+        await http.shape(clone, message);
+        return result(message.body);
+    }
+    catch (exception) {
+        /*
+         * What the route made of this call is a value a model reads and may correct itself by:
+         * an operation that refused, an argument `io:input` would not take, a record that is
+         * not there, an identity `auth` would not let it act on. A credential is none of those
+         * — that is the client's to fix and not the model's, so it is answered as it is — and
+         * neither is a fault of this server, which is a protocol error and stays one.
+         */
+        if (exception instanceof http.ClientError &&
+            !(exception instanceof http.Unauthorized))
+            return { content: [{ type: 'text', text: refusal(exception) }], isError: true };
+        throw exception;
+    }
+}
+/**
+ * Whether the tree publishes this name as a tool. What `auth` makes of the caller is not
+ * asked here — the declaration is the route's and does not vary by who is calling, and the
+ * call that follows is authorized as any request to that route is.
+ */
+function published(tree, named) {
+    for (const { segments, verb, method } of tree.walk())
+        if (name(segments, verb) === named)
+            return MCP.published(method.directives.declared(FAMILY));
+    return false;
+}
+function result(body) {
+    if (body === undefined || body === null)
+        return { content: [] };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(body) }],
+        structuredContent: body
+    };
+}
+//# sourceMappingURL=tools.js.map

package/transpiled/MCP/tools.js.map

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

package/transpiled/MCP/types.d.ts

@@ -0,0 +1,66 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export declare const MODERN = "2026-07-28";
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export declare const LEGACY = "2025-11-25";
+export declare const VERSIONS: string[];
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export declare const JSONRPC = "2.0";
+/** The prefix the revision reserves for itself in `_meta`. */
+export declare const RESERVED = "io.modelcontextprotocol/";
+export declare const PROTOCOL_VERSION: string;
+export declare const CLIENT_CAPABILITIES: string;
+export declare const SERVER_INFO: string;
+export type Params = Record<string, unknown>;
+export interface Message {
+    jsonrpc: string;
+    method: string;
+    params?: Params;
+    /** Absent makes this a notification, which is answered by not answering. */
+    id?: string | number;
+}
+export interface Failure {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface Response {
+    jsonrpc: string;
+    id: string | number | null;
+    result?: unknown;
+    error?: Failure;
+}
+/**
+ * How long a complete result may be held, and by whom. `private` is a result that is the
+ * caller's alone — a list `auth` filtered for their identity is not another caller's list.
+ */
+export interface Cache {
+    ttlMs: number;
+    cacheScope: 'public' | 'private';
+}
+/** What a tool answers with: what a model reads, and the reply itself. */
+export interface Result {
+    content: Content[];
+    structuredContent?: unknown;
+    /** The operation refused, which is something a model can read and correct. */
+    isError?: boolean;
+}
+export interface Content {
+    type: 'text';
+    text: string;
+}
+export interface Tool {
+    name: string;
+    /** what a person is shown where a client lists this tool; a name is an address */
+    title?: string;
+    /** what the route states this method is */
+    description?: string;
+    inputSchema: object;
+    outputSchema?: object;
+    annotations?: Annotations;
+}
+/** What the verb says about the call, which the revision asks a client to treat as a hint. */
+export interface Annotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+}

package/transpiled/MCP/types.js

@@ -0,0 +1,13 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export const MODERN = '2026-07-28';
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export const LEGACY = '2025-11-25';
+export const VERSIONS = [MODERN, LEGACY];
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export const JSONRPC = '2.0';
+/** The prefix the revision reserves for itself in `_meta`. */
+export const RESERVED = 'io.modelcontextprotocol/';
+export const PROTOCOL_VERSION = RESERVED + 'protocolVersion';
+export const CLIENT_CAPABILITIES = RESERVED + 'clientCapabilities';
+export const SERVER_INFO = RESERVED + 'serverInfo';
+//# sourceMappingURL=types.js.map

package/transpiled/MCP/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/MCP/types.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAA;AAElC,kGAAkG;AAClG,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAA;AAElC,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,CAAA;AAE5B,8DAA8D;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAG,0BAA0B,CAAA;AAElD,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,GAAG,iBAAiB,CAAA;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,GAAG,oBAAoB,CAAA;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAA"}

package/transpiled/Mapping.d.ts

@@ -1,8 +1,19 @@
-import { type Parameter } from './RTD';
-import type * as http from './HTTP';
-import type * as syntax from './RTD/syntax';
-import type * as core from '@toa.io/core';
+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/types';
 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, paged?: boolean): Mapping;
+    explain(introspection: Introspection): Record<string, Schema> | null;
+    /** What picks the records a call is about; see `Query.selection`. */
+    selection(): 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,67 @@
-"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, paged) {
+        const q = new Query(query, paged);
+        return queryable(query) ? new QueryableMapping(q) : new InputMapping(q);
+    }
+    explain(introspection) {
+        return this.query.explain(introspection);
+    }
+    /** What picks the records a call is about; see `Query.selection`. */
+    selection() {
+        return this.query.selection();
+    }
+    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 InputMapping extends Mapping {
-    fit(input, _, parameters) {
-        if (input === undefined && parameters.length > 0)
+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 = {};
-        if (typeof input === 'object')
-            this.assign(input, parameters);
-        return { input };
+        this.assign(input, qs);
+        if (input !== undefined)
+            request.input = input;
+        if (qs.query !== null)
+            request.query = qs.query;
+        return request;
     }
-    assign(input, parameters) {
-        for (const parameter of parameters)
-            input[parameter.name] = parameter.value;
+}
+class InputMapping extends Mapping {
+    queryable = false;
+    fit(input, query, parameters) {
+        const request = {};
+        const qs = this.query.fit(query, parameters);
+        if (input === undefined &&
+            (this.query.parameterized || parameters.length > 0 || qs.parameters !== null))
+            input = {};
+        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,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;IACzB,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;YAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QAEhC,OAAO,EAAE,KAAK,EAAE,CAAA;IAClB,CAAC;IAEO,MAAM,CAAE,KAA0B,EAAE,UAAuB;QACjE,KAAK,MAAM,SAAS,IAAI,UAAU;YAChC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAA;IAC3C,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,37 @@
-import * as http from './HTTP';
-import { type Parameter } from './RTD';
-import type * as syntax from './RTD/syntax';
-import type * as core from '@toa.io/core';
+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/types';
 export declare class Query {
+    readonly parameterized: boolean;
     private readonly query;
     private readonly closed;
-    constructor(query: syntax.Query);
-    fit(query: http.Query, parameters: Parameter[]): core.Query;
+    private readonly prepend;
+    private readonly queryable;
+    private readonly searchable;
+    /** whether a page is taken of what this answers, and so whether `omit` and `limit` apply */
+    private readonly paged;
+    constructor(query: syntax.Query, paged?: boolean);
+    fit(query: http.Query, parameters: Parameter[]): QueryString;
+    /**
+     * The querystring parameters this resource declares, which are properties of its own
+     * taken out of the input. What selects records is not among them: that is `selection`.
+     */
+    explain(introspection: Introspection): Record<string, Schema> | null;
+    /**
+     * What picks the records a call is about, which is the querystring the gateway reads
+     * rather than anything the resource declares.
+     */
+    selection(): Record<string, Schema> | null;
+    private split;
     private fitCriteria;
+    /** A route that answers one object is not paged, so a request that pages it is a mistake. */
+    private refuseRanges;
     private fitRanges;
     private fitSort;
 }
+export interface QueryString {
+    query: core.Query | null;
+    parameters: Record<string, string> | null;
+}

package/transpiled/Query.js

@@ -1,86 +1,161 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Query = void 0;
-const http = __importStar(require("./HTTP"));
-const schemas = __importStar(require("./schemas"));
-class Query {
+import { quote } from '@toa.io/generic';
+import * as http from './HTTP/index.js';
+import { schemas } from '@toa.io/definitions/extensions.exposition';
+import { queryable } from './Mapping.js';
+import { take } from './Introspection.js';
+export class Query {
+    parameterized;
     query;
     closed = false;
-    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;
+    prepend = ';';
+    queryable;
+    searchable;
+    /** whether a page is taken of what this answers, and so whether `omit` and `limit` apply */
+    paged;
+    constructor(query, paged = true) {
+        this.parameterized = query?.parameters !== undefined;
+        this.queryable = queryable(query);
+        this.searchable = query?.search === true;
+        this.paged = paged;
+        if (this.queryable) {
+            if (this.paged) {
+                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);
+            if (this.paged)
+                this.fitRanges(qs.query);
+            else
+                this.refuseRanges(qs.query);
+            this.fitSort(qs.query);
+            if (this.query.deleted !== undefined)
+                qs.query.deleted = this.query.deleted;
+        }
+        return {
+            query: qs.query,
+            parameters: qs.parameters
+        };
+    }
+    /**
+     * The querystring parameters this resource declares, which are properties of its own
+     * taken out of the input. What selects records is not among them: that is `selection`.
+     */
+    explain(introspection) {
+        let query = null;
+        if (this.query?.parameters !== undefined)
+            for (const parameter of this.query.parameters) {
+                const schema = take(introspection, parameter);
+                // eslint-disable-next-line max-depth
+                if (schema === undefined)
+                    continue;
+                query ??= {};
+                query[parameter] = schema;
+            }
+        return query;
+    }
+    /**
+     * What picks the records a call is about, which is the querystring the gateway reads
+     * rather than anything the resource declares.
+     */
+    selection() {
+        if (!this.queryable)
+            return null;
+        const query = {};
+        if (!this.closed)
+            query.criteria = keyword('string', 'What to match, in RSQL: `state==hot`, `rank=gt=5;name==*tea*`.');
+        query.sort = keyword('string', 'What to order by: `rank:desc`, or `rank` for ascending.');
+        if (this.paged) {
+            query.limit = bounded('How many at once.', this.query.limit);
+            query.omit = bounded('How many to skip.', this.query.omit);
+        }
+        if (this.searchable)
+            query.search = keyword('string', 'What to search the text index for.');
         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;
+        }
+        if (query?.search !== undefined && !this.searchable)
+            throw new http.BadRequest('Query search is not allowed');
+        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
-                .map(({ name, value }) => `${name}==${value}`)
+            // a segment may carry `,` `;` `(` `)` `=`, which is criteria grammar when unquoted
+            const criteria = parameters
+                .map(({ name, value }) => `${name}==${quote(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}`;
+            }, '');
+    }
+    /** A route that answers one object is not paged, so a request that pages it is a mistake. */
+    refuseRanges(qs) {
+        for (const name of ['omit', 'limit'])
+            if (qs[name] !== undefined)
+                throw new http.BadRequest(`Query ${name} is not allowed`);
     }
     fitRanges(qs) {
         const query = qs;
+        if (this.query.limit === undefined)
+            throw new Error('Query limit must be defined');
+        if (this.query.omit === undefined)
+            throw new Error('Query limit range must be defined');
         if (qs.limit !== undefined)
             query.limit = fit(qs.limit, this.query.limit.range, 'limit');
         else
@@ -96,12 +171,25 @@ class Query {
         query.sort = sort.split(';');
     }
 }
-exports.Query = Query;
 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.`);
+        throw new http.BadRequest(`Query ${name} must be between ${range[0]} and ${range[1]} inclusive`);
     return number;
 }
+const WHATEVER = ';';
+function keyword(type, description) {
+    return { type, description };
+}
+function bounded(description, bounds) {
+    const schema = {
+        type: 'integer',
+        description,
+        minimum: bounds.range[0],
+        maximum: bounds.range[1]
+    };
+    if (bounds.value !== undefined)
+        schema.default = bounds.value;
+    return schema;
+}
 //# sourceMappingURL=Query.js.map