@mistriwork/engine 0.0.0 → 1.0.0-rc.10

package/dist/adapters/http/httpDescription.js

@@ -0,0 +1,246 @@
+export const DESCRIPTION_FORMAT = 'mistri.http/1';
+export function draftDescription(catalog, spec) {
+    return {
+        format: DESCRIPTION_FORMAT,
+        title: catalog.title,
+        version: catalog.version,
+        ...(spec ? { spec } : {}),
+        resources: catalog.resources,
+    };
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const TYPES = new Set(['string', 'integer', 'bigint', 'number', 'boolean', 'date', 'datetime', 'uuid', 'json']);
+const NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/* Refused rather than coerced, like the connection config beside it: a
+   description is edited by hand, and a typo that quietly became a different
+   API call is the mistake worth being loud about. */
+function strings(value) {
+    return Array.isArray(value) && value.every((each) => typeof each === 'string');
+}
+function readColumn(raw, at) {
+    if (!isObject(raw) || typeof raw.name !== 'string' || !NAME.test(raw.name))
+        throw new Error(`${at} needs a "name" (letters, digits, _ and -).`);
+    if (typeof raw.type !== 'string' || !TYPES.has(raw.type)) {
+        throw new Error(`${at} "${raw.name}" has "type": ${JSON.stringify(raw.type)}. Use one of ${[...TYPES].join(', ')}.`);
+    }
+    for (const flag of ['nullable', 'readOnly']) {
+        if (typeof raw[flag] !== 'boolean')
+            throw new Error(`${at} "${raw.name}" needs "${flag}": true or false, without quotes.`);
+    }
+    if (raw.allowed !== undefined && (!strings(raw.allowed) || !raw.allowed.length))
+        throw new Error(`${at} "${raw.name}" has "allowed" that is not a list of strings.`);
+    if (raw.comment !== undefined && typeof raw.comment !== 'string')
+        throw new Error(`${at} "${raw.name}" has a "comment" that is not text.`);
+    if (raw.references !== undefined && (typeof raw.references !== 'string' || !NAME.test(raw.references))) {
+        throw new Error(`${at} "${raw.name}" has "references" that is not a resource's name.`);
+    }
+    return {
+        name: raw.name,
+        type: raw.type,
+        nullable: raw.nullable,
+        readOnly: raw.readOnly,
+        ...(raw.allowed ? { allowed: raw.allowed } : {}),
+        ...(raw.references ? { references: raw.references } : {}),
+        ...(raw.comment ? { comment: raw.comment } : {}),
+    };
+}
+function readPaging(raw, at) {
+    if (!isObject(raw))
+        throw new Error(`${at} needs "paging".`);
+    const text = (key) => {
+        if (typeof raw[key] !== 'string' || !raw[key])
+            throw new Error(`${at} "paging" (${String(raw.kind)}) needs "${key}", the query parameter's name.`);
+        return raw[key];
+    };
+    switch (raw.kind) {
+        case 'none':
+            return { kind: 'none' };
+        case 'offset':
+            return { kind: 'offset', offset: text('offset'), limit: text('limit') };
+        case 'page':
+            return { kind: 'page', page: text('page'), size: text('size') };
+        case 'cursor': {
+            const next = text('next');
+            if (!next.startsWith('/'))
+                throw new Error(`${at} "paging" "next" is a JSON Pointer into the response, starting with "/".`);
+            return { kind: 'cursor', param: text('param'), next, ...(raw.limit === undefined ? {} : { limit: text('limit') }) };
+        }
+        default:
+            throw new Error(`${at} "paging" has "kind": ${JSON.stringify(raw.kind)}. Use none, offset, page or cursor.`);
+    }
+}
+function readResource(raw, at) {
+    if (!isObject(raw) || typeof raw.name !== 'string' || !NAME.test(raw.name))
+        throw new Error(`${at} needs a "name" (letters, digits, _ and -).`);
+    const here = `${at} "${raw.name}"`;
+    if (typeof raw.list !== 'string' || !raw.list.startsWith('/') || raw.list.includes('{'))
+        throw new Error(`${here} needs "list", a path like "/contacts".`);
+    if (typeof raw.key !== 'string' || !raw.key)
+        throw new Error(`${here} needs "key", the column its item path names.`);
+    if (raw.item !== `${raw.list}/{${raw.key}}`)
+        throw new Error(`${here} needs "item": "${raw.list}/{${raw.key}}", the list path and its key.`);
+    if (typeof raw.rows !== 'string' || (raw.rows !== '' && !raw.rows.startsWith('/')))
+        throw new Error(`${here} has "rows" that is not a JSON Pointer ("" or starting with "/").`);
+    if (!Array.isArray(raw.columns) || !raw.columns.length)
+        throw new Error(`${here} needs "columns".`);
+    const columns = raw.columns.map((column, index) => readColumn(column, `${here} column ${index + 1}`));
+    const names = new Set();
+    for (const column of columns) {
+        if (names.has(column.name))
+            throw new Error(`${here} has two columns called "${column.name}".`);
+        names.add(column.name);
+    }
+    const key = columns.find((column) => column.name === raw.key);
+    if (!key)
+        throw new Error(`${here} has "key": "${raw.key}", which is not one of its columns.`);
+    if (key.nullable || key.type === 'json')
+        throw new Error(`${here}: the key "${raw.key}" must be a value that is never null.`);
+    const filters = {};
+    if (raw.filters !== undefined) {
+        if (!isObject(raw.filters))
+            throw new Error(`${here} has "filters" that is not an object of column → parameter.`);
+        for (const [name, filter] of Object.entries(raw.filters)) {
+            const column = columns.find((each) => each.name === name);
+            if (!column || column.type === 'json')
+                throw new Error(`${here} filters "${name}", which is not a column that can be filtered.`);
+            if (!isObject(filter) || typeof filter.param !== 'string' || !filter.param)
+                throw new Error(`${here} filter "${name}" needs "param".`);
+            if (!strings(filter.ops) || !filter.ops.length || filter.ops.some((op) => op !== '=' && op !== 'in') || !filter.ops.includes('=')) {
+                throw new Error(`${here} filter "${name}" has "ops" other than ["="] or ["=", "in"].`);
+            }
+            if (filter.serialization !== undefined && filter.serialization !== 'csv')
+                throw new Error(`${here} filter "${name}" has unsupported serialization.`);
+            filters[name] = {
+                param: filter.param,
+                ops: [...new Set(filter.ops)],
+                ...(filter.serialization === 'csv' ? { serialization: 'csv' } : {}),
+            };
+        }
+    }
+    if (raw.search !== undefined && (typeof raw.search !== 'string' || !raw.search))
+        throw new Error(`${here} has "search" that is not a parameter name.`);
+    let sort;
+    if (raw.sort !== undefined) {
+        if (!isObject(raw.sort) || typeof raw.sort.param !== 'string' || !strings(raw.sort.values) || !raw.sort.values.length) {
+            throw new Error(`${here} has "sort" without a "param" and its documented "values".`);
+        }
+        sort = { param: raw.sort.param, values: raw.sort.values };
+    }
+    if (raw.guesses !== undefined && !strings(raw.guesses))
+        throw new Error(`${here} has "guesses" that is not a list of notes.`);
+    if (raw.comment !== undefined && typeof raw.comment !== 'string')
+        throw new Error(`${here} has a "comment" that is not text.`);
+    return {
+        name: raw.name,
+        list: raw.list,
+        item: raw.item,
+        key: raw.key,
+        rows: raw.rows,
+        columns,
+        filters,
+        ...(raw.search ? { search: raw.search } : {}),
+        ...(sort ? { sort } : {}),
+        paging: readPaging(raw.paging, here),
+        guesses: raw.guesses ?? [],
+        ...(raw.comment ? { comment: raw.comment } : {}),
+    };
+}
+/** A description as written in a file, checked field by field; `where` names the file in every message. */
+export function readDescription(raw, where) {
+    if (!isObject(raw))
+        throw new Error(`${where} is not a JSON object.`);
+    if (raw.format !== DESCRIPTION_FORMAT) {
+        throw new Error(`${where} has "format": ${JSON.stringify(raw.format)}; this build reads "${DESCRIPTION_FORMAT}". Draft one with --from-openapi.`);
+    }
+    if (!Array.isArray(raw.resources) || !raw.resources.length)
+        throw new Error(`${where} describes no "resources".`);
+    const resources = raw.resources.map((resource, index) => readResource(resource, `${where}: resource ${index + 1}`));
+    const names = new Set();
+    for (const resource of resources) {
+        if (names.has(resource.name))
+            throw new Error(`${where} describes two resources called "${resource.name}".`);
+        names.add(resource.name);
+    }
+    // A reference is followed by reading the target's item, so the target has to be here to read.
+    for (const resource of resources) {
+        for (const column of resource.columns) {
+            if (column.references && !names.has(column.references)) {
+                throw new Error(`${where}: "${resource.name}" column "${column.name}" references "${column.references}", which is not a resource in this description.`);
+            }
+            if (column.references && column.name === resource.key)
+                throw new Error(`${where}: "${resource.name}"'s key "${column.name}" cannot reference another resource.`);
+        }
+    }
+    let spec;
+    if (raw.spec !== undefined) {
+        if (!isObject(raw.spec) ||
+            typeof raw.spec.file !== 'string' ||
+            typeof raw.spec.sha256 !== 'string' ||
+            !/^[0-9a-f]{64}$/.test(raw.spec.sha256)) {
+            throw new Error(`${where} has "spec" without its "file" and a 64-character "sha256".`);
+        }
+        spec = { file: raw.spec.file, sha256: raw.spec.sha256 };
+    }
+    return {
+        format: DESCRIPTION_FORMAT,
+        title: typeof raw.title === 'string' ? raw.title : '',
+        version: typeof raw.version === 'string' ? raw.version : '',
+        ...(spec ? { spec } : {}),
+        resources,
+    };
+}
+/* The catalog words said as the type strings the rest of tablewalk already
+   reads — a grid right-aligns `numeric`, a record formats `timestamp`, and a
+   `json` value is laid out by its shape — so an API's row is drawn exactly
+   as a database's would be. */
+const SQL_TYPE = {
+    string: 'text',
+    integer: 'integer',
+    bigint: 'bigint',
+    number: 'numeric',
+    boolean: 'boolean',
+    date: 'date',
+    datetime: 'timestamp',
+    uuid: 'uuid',
+    json: 'json',
+};
+/** The description as the catalog every App, grant, type export and scaffold already reads. */
+export function describedSchema(description, label, readAt = new Date()) {
+    const keyOf = new Map(description.resources.map((resource) => [resource.name, resource.key]));
+    /* A reference is a foreign key to everything that reads the catalog: related
+       lists, label paths, the diagram. The adapter answers a path through one by
+       reading the target's items (httpAdapter.ts). */
+    const foreignKeys = description.resources.flatMap((resource) => resource.columns
+        .filter((column) => column.references && keyOf.has(column.references))
+        .map((column) => ({
+        name: `${resource.name}_${column.name}`,
+        from: { table: resource.name, columns: [column.name] },
+        to: { table: column.references, columns: [keyOf.get(column.references)] },
+    })));
+    const tables = description.resources.map((resource) => ({
+        name: resource.name,
+        schema: '',
+        id: resource.name,
+        isView: false,
+        columns: resource.columns.map((column) => ({
+            name: column.name,
+            type: SQL_TYPE[column.type],
+            nullable: column.nullable,
+            primaryKey: column.name === resource.key,
+            ...(column.allowed ? { allowed: column.allowed } : {}),
+            ...(column.comment ? { comment: column.comment } : {}),
+            ...(column.references && keyOf.has(column.references)
+                ? { references: { table: column.references, column: keyOf.get(column.references) } }
+                : {}),
+        })),
+        ...(resource.comment ? { comment: resource.comment } : {}),
+        // What the API documents a filter for; the explorer offers boxes for these alone.
+        filterable: Object.keys(resource.filters),
+        // The columns its documented sort values name ("-shipped_at" sorts by shipped_at), in the spellings the adapter reads.
+        sortable: [
+            ...new Set((resource.sort?.values ?? []).map((value) => value.replace(/^[-+]/, '').replace(/(?::| |_)(?:asc|desc)$/, ''))),
+        ].filter((name) => resource.columns.some((column) => column.name === name)),
+        countable: false,
+    }));
+    return { label, dialect: 'http', tables, foreignKeys, readAt: readAt.toISOString() };
+}

package/dist/adapters/http/openapi.d.ts

@@ -0,0 +1,98 @@
+/**
+ * An OpenAPI document read as a catalog of browsable resources.
+ *
+ * A resource is a collection an API lists (`GET /contacts`) together with the
+ * item it reads by key (`GET /contacts/{id}`), when both answer the same kind
+ * of row. For each one this says the columns a row carries and what the API
+ * can do with a list — filter, search, sort, page — as data, so tablewalk
+ * asks the API only what it can answer and refuses the rest by name.
+ *
+ * Pure: a parsed JSON document in, a catalog out. The spec is pinned locally
+ * and read at startup, as a database's catalog is read on connect, so there
+ * is no network here, no remote `$ref` and no YAML. Nothing outside the
+ * supported subset is guessed at: its operation is skipped with the reason,
+ * which `--check-openapi` prints. Paging is the one inference, and every
+ * inferred setting is listed under `guesses` for the author to confirm.
+ */
+/** What a column holds, in the catalog's words. `bigint` stays text, so a value past 2^53 keeps every digit. */
+export type HttpColumnType = 'string' | 'integer' | 'bigint' | 'number' | 'boolean' | 'date' | 'datetime' | 'uuid' | 'json';
+export interface HttpColumn {
+    name: string;
+    type: HttpColumnType;
+    /** Null or absent in a row: a property the schema does not require may be missing, and missing reads as null. */
+    nullable: boolean;
+    /** The API says so (`readOnly`), or the value is a nested document, which no editor offers. */
+    readOnly: boolean;
+    /** An `enum`: the values the API documents, not a promise that nothing else arrives. */
+    allowed?: string[];
+    /** The resource whose key this column holds; guessed from the name (`carrier_id` → `carriers`), for the author to confirm. */
+    references?: string;
+    comment?: string;
+}
+/** A list filter the API takes: one query parameter per column, `=` always, `in` when it takes a list. */
+export interface HttpFilter {
+    param: string;
+    ops: Array<'=' | 'in'>;
+    serialization?: 'csv';
+}
+export type HttpPaging = {
+    kind: 'offset';
+    offset: string;
+    limit: string;
+} | {
+    kind: 'page';
+    page: string;
+    size: string;
+} | {
+    kind: 'cursor';
+    param: string;
+    next: string;
+    limit?: string;
+} | {
+    kind: 'none';
+};
+export interface HttpResource {
+    /** The collection's own word (`contacts`), used as the table's name. */
+    name: string;
+    /** The list and item paths, as the document writes them. */
+    list: string;
+    item: string;
+    /** The column the item's path parameter names. */
+    key: string;
+    /** JSON Pointer (RFC 6901) to the rows in a list response; '' when the response is the array itself. */
+    rows: string;
+    columns: HttpColumn[];
+    filters: Record<string, HttpFilter>;
+    search?: string;
+    /** A sort the API takes only by the values it documents. */
+    sort?: {
+        param: string;
+        values: string[];
+    };
+    paging: HttpPaging;
+    /** Settings inferred rather than read, for the author to confirm. */
+    guesses: string[];
+    comment?: string;
+}
+/** An operation outside the supported subset, and why. */
+export interface HttpSkip {
+    operation: string;
+    reason: string;
+}
+export interface HttpCatalog {
+    title: string;
+    version: string;
+    resources: HttpResource[];
+    skipped: HttpSkip[];
+}
+/** The whole document is outside what tablewalk reads; the message names the fix. */
+export declare class OpenApiError extends Error {
+    readonly code = "openapi_unsupported";
+    constructor(message: string);
+}
+/**
+ * Reads a parsed OpenAPI 3.0 or 3.1 document. Throws `OpenApiError` only for
+ * a document tablewalk cannot read at all; everything else becomes either a
+ * resource or a skipped operation with its reason.
+ */
+export declare function readOpenApi(document: unknown): HttpCatalog;