pivotkit-report 0.0.0-stage → 0.2.0

package/types/operations.d.ts

@@ -0,0 +1,362 @@
+import { describeSource } from "pivotkit-core";
+/** The codes of OperationError, each with the HTTP status a REST front end answers with. */
+export declare const OPERATION_ERRORS: Readonly<{
+    INVALID_INPUT: 400;
+    FILES_NOT_ALLOWED: 403;
+    NOT_ALLOWED: 403;
+    SOURCE_NOT_FOUND: 404;
+    FILE_NOT_AVAILABLE: 404;
+    NO_OUTPUT: 409;
+    NO_LINK: 409;
+    NOT_SCHEDULABLE: 409;
+    LIMIT_EXCEEDED: 413;
+    UNSUPPORTED_FORMAT: 415;
+    INVALID_FILE: 422;
+    NOT_REGULAR_FILE: 422;
+    HARD_LINK: 422;
+    INVALID_TEMPLATE: 422;
+    BUSY: 503;
+    NOT_READY: 503;
+    TIMEOUT: 504;
+    INTERNAL: 500;
+}>;
+/** An error of an operation a front end shows as it is: a stable code and a message without file content. */
+export declare class OperationError extends Error {
+    code: "BUSY" | "FILES_NOT_ALLOWED" | "FILE_NOT_AVAILABLE" | "HARD_LINK" | "INTERNAL" | "INVALID_FILE" | "INVALID_INPUT" | "INVALID_TEMPLATE" | "LIMIT_EXCEEDED" | "NOT_ALLOWED" | "NOT_READY" | "NOT_REGULAR_FILE" | "NOT_SCHEDULABLE" | "NO_LINK" | "NO_OUTPUT" | "SOURCE_NOT_FOUND" | "TIMEOUT" | "UNSUPPORTED_FORMAT";
+    status: 400 | 403 | 404 | 409 | 413 | 415 | 422 | 500 | 503 | 504;
+    /**
+     * @param {keyof typeof OPERATION_ERRORS} code
+     * @param {string} message
+     */
+    constructor(code: keyof typeof OPERATION_ERRORS, message: string);
+}
+export type Finding = {
+    severity: "error" | "warning" | "info";
+    code: string;
+    path: string;
+    message: string;
+    /**
+     * the name or item meant ("did you mean")
+     */
+    suggestion?: string;
+};
+/**
+ * @typedef {object} Finding
+ * @property {"error" | "warning" | "info"} severity
+ * @property {string} code
+ * @property {string} path
+ * @property {string} message
+ * @property {string} [suggestion]  the name or item meant ("did you mean")
+ */
+/** The most characters of a name, path or message from outside an operation puts into a finding. */
+export declare const FINDING_TEXT = 200;
+/** Text from a view or the data, as a finding carries it: no control or direction characters, capped. */
+export declare function findingText(text: any): string;
+/**
+ * An issue of pivotkit-core (or a reader's note) as a finding.
+ * @param {{ severity?: string, code?: string, path?: string, message?: string, params?: { suggestion?: string } }} issue
+ * @returns {Finding}
+ */
+export declare function findingOf(issue: {
+    severity?: string;
+    code?: string;
+    path?: string;
+    message?: string;
+    params?: {
+        suggestion?: string;
+    };
+}): Finding;
+export type OperationEnv = {
+    /**
+     * the data of a source (encoded, or only its fields)
+     */
+    data?: (source: string) => Promise<SourceData>;
+    /**
+     * the sources this caller may use
+     */
+    sources?: () => Promise<SourceInfo[]>;
+    /**
+     * where a link to the source's report goes
+     */
+    link?: (source: string) => Promise<{
+        url: string;
+        key?: string | null;
+    } | null>;
+    /**
+     * the print template of a source (the operator's, never the caller's)
+     */
+    template?: (source: string) => Promise<string | undefined>;
+    /**
+     * the ECharts module, for svg and a report with its chart
+     */
+    echarts?: {
+        init: Function;
+    };
+    limits?: Partial<import("pivotkit-core").Limits>;
+    locale?: string;
+    timeZone?: string;
+    now?: Date | number | string;
+    /**
+     * a front end's own render options (the CLI's template, bom, size)
+     */
+    renderOptions?: Record<string, unknown>;
+};
+export type SourceData = {
+    /**
+     * encoded data, or only the fields (a view file's source.fields)
+     */
+    data: import("pivotkit-core").Encoded | Array<{
+        name: string;
+        type: string;
+    }>;
+    /**
+     * how a report names the data (a file's base name, a source's title)
+     */
+    name: string;
+    /**
+     * what reading it noticed
+     */
+    notes?: Finding[];
+    /**
+     * a schedule may run over it (false for a file a person handed in)
+     */
+    schedulable?: boolean;
+};
+export type SourceInfo = {
+    id: string;
+    title: string;
+    description?: string;
+    kind: "source" | "file";
+    /**
+     * create_link works for it
+     */
+    link: boolean;
+    schedulable: boolean;
+};
+export type OperationOutcome = {
+    /**
+     * what the output schema describes
+     */
+    result: Record<string, any>;
+    /**
+     * a file the front end writes, sends or shows
+     */
+    file?: {
+        bytes: Uint8Array;
+        mediaType: string;
+        extension: string;
+        name: string;
+    };
+};
+export type Operation = {
+    name: string;
+    title: string;
+    /**
+     * one paragraph: an MCP tool's description, an OpenAPI operation's, a CLI command's help line
+     */
+    description: string;
+    /**
+     * the CLI command it is, or null
+     */
+    cli: string | null;
+    http: {
+        method: "GET" | "POST";
+        path: string;
+    };
+    needs: Array<keyof OperationEnv>;
+    annotations: {
+        readOnly: boolean;
+        idempotent: boolean;
+        writesFile: boolean;
+    };
+    /**
+     * JSON Schema of the input (draft 2020-12)
+     */
+    input: Record<string, unknown>;
+    /**
+     * JSON Schema of `result`
+     */
+    output: Record<string, unknown>;
+    run: (input: any, env: OperationEnv) => Promise<OperationOutcome>;
+};
+/** How a note of viewFromLayout or suggestLayout counts as a finding. */
+export declare const LAYOUT_NOTE_SEVERITY: Readonly<{
+    noSuggestion: "error";
+    dateGrouped: "info";
+    unusedGroup: "warning";
+    unusedMap: "warning";
+}>;
+/**
+ * A view from field names, the one way the operations and pivotkit-cli make one: pivotkit-core's
+ * viewFromLayout over the source's field description. With `suggest`, suggestLayout's picks come
+ * first and the layout's parts replace them (a suggested grouping stays only while its field stays
+ * where the suggestion put it); nothing to group by (noSuggestion) counts only while the layout places
+ * no field itself. A layout of another shape is INVALID_INPUT, one too large LIMIT_EXCEEDED.
+ * @param {ReturnType<typeof describeSource>} description
+ * @param {import("pivotkit-core").Layout} layout
+ * @param {{ suggest?: boolean, locale?: string }} [options]
+ * @returns {{ view: Record<string, any>, name: string, picks: import("pivotkit-core").LayoutPick[], notes: import("pivotkit-core").LayoutNote[] }}
+ */
+export declare function viewOfLayout(description: ReturnType<typeof describeSource>, layout?: import("pivotkit-core").Layout, options?: {
+    suggest?: boolean;
+    locale?: string;
+}): {
+    view: Record<string, any>;
+    name: string;
+    picks: import("pivotkit-core").LayoutPick[];
+    notes: import("pivotkit-core").LayoutNote[];
+};
+/**
+ * Two or three views built from a data set's own fields, for a model or a person to start from: a
+ * measure is a number field that is no identifier.
+ * @param {Array<{ name: string, type: string }>} fields
+ */
+export declare function exampleViews(fields: Array<{
+    name: string;
+    type: string;
+}>): any[];
+/** The view guide: the format of a view in short, its vocabulary from pivotkit-core's CATALOG, and examples. */
+export declare const VIEW_GUIDE: Readonly<{
+    text: string;
+    catalog: Readonly<{
+        aggregators: readonly string[];
+        deriveUnits: readonly string[];
+        filterTypes: readonly string[];
+        filterFields: Readonly<{
+            [k: string]: readonly string[];
+        }>;
+        textOps: readonly string[];
+        compareOps: readonly string[];
+        relativeUnits: readonly string[];
+        relativeDirections: readonly string[];
+        relativeAnchors: readonly string[];
+        filterBlanks: readonly string[];
+        showAs: readonly string[];
+        formats: readonly string[];
+        chartTypes: readonly string[];
+        displayModes: readonly string[];
+    }>;
+    examples: readonly ({
+        title: string;
+        view: {
+            version: number;
+            rows: string[];
+            values: {
+                field: string;
+                agg: string;
+            }[];
+            cols?: undefined;
+            filters?: undefined;
+            derived?: undefined;
+            display?: undefined;
+            chart?: undefined;
+        };
+    } | {
+        title: string;
+        view: {
+            version: number;
+            rows: string[];
+            cols: string[];
+            derived: {
+                name: string;
+                field: string;
+                by: string;
+            }[];
+            values: {
+                field: string;
+                agg: string;
+            }[];
+            filters?: undefined;
+            display?: undefined;
+            chart?: undefined;
+        };
+    } | {
+        title: string;
+        view: {
+            cols?: undefined;
+            version: number;
+            rows: string[];
+            values: {
+                field: string;
+                agg: string;
+            }[];
+            filters: ({
+                field: string;
+                type: string;
+                direction: string;
+                count: number;
+                unit: string;
+                anchor: string;
+                blanks: string;
+                by?: undefined;
+            } | {
+                direction?: undefined;
+                unit?: undefined;
+                anchor?: undefined;
+                blanks?: undefined;
+                field: string;
+                type: string;
+                count: number;
+                by: {
+                    field: string;
+                    agg: string;
+                };
+            })[];
+            derived?: undefined;
+            display?: undefined;
+            chart?: undefined;
+        };
+    } | {
+        title: string;
+        view: {
+            cols?: undefined;
+            filters?: undefined;
+            version: number;
+            rows: string[];
+            derived: {
+                name: string;
+                field: string;
+                by: string;
+            }[];
+            values: {
+                agg: string;
+            }[];
+            display: string;
+            chart: {
+                type: string;
+            };
+        };
+    } | {
+        title: string;
+        view: {
+            cols?: undefined;
+            filters?: undefined;
+            derived?: undefined;
+            display?: undefined;
+            chart?: undefined;
+            version: number;
+            rows: string[];
+            values: {
+                field: string;
+                agg: string;
+                showAs: {
+                    type: string;
+                };
+            }[];
+        };
+    })[];
+}>;
+/**
+ * Checks an input against an operation's input schema, for the JSON Schema keywords the table uses
+ * (type, enum, required, properties, additionalProperties: false, items, min/max length, items and
+ * value, pattern, uniqueItems, maxProperties, additionalProperties as a schema). Every `run` calls it first, so a front end without a validator of its
+ * own (a REST service, a script) gets INVALID_INPUT naming the place, never a TypeError.
+ * @param {Record<string, unknown>} schema
+ * @param {unknown} value
+ * @param {string} [path]
+ */
+export declare function checkInput(schema: Record<string, unknown>, value: unknown, path?: string): void;
+/** @type {Readonly<Record<string, Operation>>} */
+export declare const OPERATIONS: Readonly<Record<string, Operation>>;
+/** The operations' names, in the table's order. */
+export declare const OPERATION_NAMES: readonly string[];

package/types/render.d.ts

@@ -0,0 +1,177 @@
+/** The formats: media type, file extension, and whether the body is text (`text` is set). */
+export declare const RENDER_FORMATS: Readonly<{
+    json: Readonly<{
+        mediaType: "application/json";
+        extension: "json";
+        text: true;
+    }>;
+    csv: Readonly<{
+        mediaType: "text/csv;charset=utf-8";
+        extension: "csv";
+        text: true;
+    }>;
+    xlsx: Readonly<{
+        mediaType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+        extension: "xlsx";
+        text: false;
+    }>;
+    svg: Readonly<{
+        mediaType: "image/svg+xml";
+        extension: "svg";
+        text: true;
+    }>;
+    html: Readonly<{
+        mediaType: "text/html;charset=utf-8";
+        extension: "html";
+        text: true;
+    }>;
+}>;
+/**
+ * What a report allows at most, besides pivotkit-core's LIMITS: the characters of a template, the size
+ * of a chart in px, the cells of a report's table (a larger table is cut after the last whole row, and
+ * says so), the categories of a chart (the first ones, as on the screen).
+ */
+export declare const REPORT_LIMITS: Readonly<{
+    template: 262144;
+    chartWidth: 8000;
+    chartHeight: 8000;
+    tableCells: 200000;
+    categories: 50;
+}>;
+/** The default size of a chart in px. */
+export declare const CHART_SIZE: Readonly<{
+    width: 800;
+    height: 480;
+}>;
+/** Issues of a report itself (warnings), besides a view's (VIEW_ISSUES). */
+export declare const REPORT_ISSUE_CODES: readonly string[];
+export type RenderOptions = {
+    /**
+     * default "html"
+     */
+    format?: "json" | "csv" | "xlsx" | "svg" | "html";
+    /**
+     * used when the view names none; default "en-US"
+     */
+    locale?: string;
+    /**
+     * of rows that are not encoded yet (encode()), and of the "generated" time; default "UTC"
+     */
+    timeZone?: string;
+    /**
+     * "today" of relative date filters and the "generated" time; fix it for output that is the same on every run
+     */
+    now?: Date | number | string;
+    /**
+     * pivotkit-core's limits
+     */
+    limits?: Partial<import("pivotkit-core").Limits>;
+    /**
+     * the view is the host's own: the host's limits instead of outsideLimits() (default false)
+     */
+    trusted?: boolean;
+    /**
+     * no body when the view has an error (default false: the normalized view is rendered)
+     */
+    strict?: boolean;
+    /**
+     * pivotkit-core's texts (totals, value names)
+     */
+    labels?: Partial<import("pivotkit-core").Labels>;
+    /**
+     * the report's words around the table
+     */
+    texts?: Partial<import("./texts.js").ReportTexts>;
+    /**
+     * --pk-* colours over the light ones (the chart and the report)
+     */
+    tokens?: Record<string, string>;
+    /**
+     * the report's title; default the view file's name, the chart's title, "Report"
+     */
+    title?: string;
+    /**
+     * default the view file's description
+     */
+    description?: string;
+    /**
+     * where the data comes from, for the report's details (a file name)
+     */
+    source?: string;
+    /**
+     * html: a print template (parseTemplate), default DEFAULT_TEMPLATE
+     */
+    template?: string;
+    /**
+     * html: with the chart; "auto" (default) when the view shows the chart
+     */
+    chart?: boolean | "auto";
+    /**
+     * html: the chart as a data: image (default) or as inline SVG
+     */
+    chartEmbed?: "image" | "inline";
+    /**
+     * the ECharts module (with its SVG renderer): svg, and html with a chart
+     */
+    echarts?: {
+        init: Function;
+    };
+    /**
+     * of the chart in px, default 800 x 480
+     */
+    size?: {
+        width?: number;
+        height?: number;
+    };
+    /**
+     * html: cells of the table at most, default REPORT_LIMITS.tableCells
+     */
+    tableCells?: number;
+    /**
+     * csv: start with a byte order mark, so Excel reads it as UTF-8 (default true)
+     */
+    bom?: boolean;
+};
+export type RenderResult = {
+    format: string;
+    mediaType: string;
+    extension: string;
+    /**
+     * the file; null when `strict` and the view has an error
+     */
+    body: Uint8Array | null;
+    /**
+     * the body as text, for json, csv, svg and html
+     */
+    text?: string;
+    /**
+     * the view's issues, then the report's (REPORT_ISSUE_CODES)
+     */
+    issues: import("pivotkit-core").Issue[];
+    /**
+     * no issue of severity "error"
+     */
+    ok: boolean;
+    /**
+     * the table's body rows and columns, the data's rows, the rows its filters keep, whether a part was cut
+     */
+    summary: {
+        rows: number;
+        columns: number;
+        sourceRows: number;
+        keptRows: number;
+        truncated: boolean;
+    } | null;
+    /**
+     * the normalized view that was rendered
+     */
+    view: import("pivotkit-core").View | null;
+};
+/**
+ * Renders a view over data as a file.
+ * @param {unknown} view  a view, a view file or a template { name, view }, as an object or JSON text
+ * @param {unknown} data  rows, columnar data ({ columns, types, data }) or encode()'s result
+ * @param {RenderOptions} [options]
+ * @returns {Promise<RenderResult>}
+ */
+export declare function render(view: unknown, data: unknown, options?: RenderOptions): Promise<RenderResult>;

package/types/report-css.d.ts

@@ -0,0 +1,14 @@
+/** Columns from which a printed table is turned to landscape, and from which its font gets smaller. */
+export declare const PRINT_WIDE: Readonly<{
+    landscape: 8;
+    small: 16;
+}>;
+/**
+ * @param {{ columns: number, tokens?: Record<string, string>, extra?: string }} options
+ *   columns: the table's; tokens: the host's (cleaned), over the light ones; extra: the cells' colour rules
+ */
+export declare function reportCss({ columns, tokens, extra }: {
+    columns: number;
+    tokens?: Record<string, string>;
+    extra?: string;
+}): string;

package/types/svg.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Checks an SVG string and makes it safe to open and to show under a strict Content-Security-Policy:
+ * only the elements an ECharts chart draws, no event handler attribute, no link but to a fragment or
+ * a data: image, no attribute name but a plain one, no namespace but SVG's and xlink's, no text that is not escaped; every `style` attribute becomes presentation attributes
+ * (a policy without 'unsafe-inline' blocks style attributes, not those) and a <style> element (ECharts'
+ * hover states) and characters XML does not allow, also as numeric references, are left out. Throws INVALID_ARGUMENT
+ * (`details.reason`) for anything else.
+ * @param {string} svg
+ * @returns {string}
+ */
+export declare function cleanSvg(svg: string): string;
+/**
+ * The chart of a pivot as SVG, as pivotkit-react draws it: chartPlan's type (the view's, or what
+ * "auto" picks; rows and columns swapped for the chart where it says so), the theme's colours from
+ * `style`, the axis labels laid out for the size, at most `maxCategories` categories.
+ * @param {import("pivotkit-core").PivotResult} result
+ * @param {{ echarts: { init: Function }, style: { getPropertyValue(name: string): string }, width: number, height: number,
+ *   locale: string, labels?: object, limits?: object, now?: any, maxCategories: number }} options
+ * @returns {{ svg: string, categories: number, of: number }}
+ */
+export declare function chartSvg(result: import("pivotkit-core").PivotResult, { echarts, style, width, height, locale, labels, limits, now, maxCategories }: {
+    echarts: {
+        init: Function;
+    };
+    style: {
+        getPropertyValue(name: string): string;
+    };
+    width: number;
+    height: number;
+    locale: string;
+    labels?: object;
+    limits?: object;
+    now?: any;
+    maxCategories: number;
+}): {
+    svg: string;
+    categories: number;
+    of: number;
+};

package/types/template.d.ts

@@ -0,0 +1,37 @@
+/** Characters a template may have. */
+export declare const TEMPLATE_LIMIT = 262144;
+/**
+ * The placeholders: text (escaped) and markup (built by pivotkit from escaped parts).
+ * @type {Readonly<Record<string, "text" | "markup">>}
+ */
+export declare const PLACEHOLDERS: Readonly<Record<string, "text" | "markup">>;
+/** Attributes whose quoted value may hold a text placeholder. */
+export declare const ATTRIBUTES: readonly string[];
+export type Slot = {
+    name: string;
+    kind: "text" | "markup";
+};
+export type Template = {
+    parts: Array<string | Slot>;
+    names: string[];
+};
+/**
+ * @typedef {{ name: string, kind: "text" | "markup" }} Slot
+ * @typedef {{ parts: Array<string | Slot>, names: string[] }} Template  the template's text cut at its placeholders
+ */
+/** Escapes text for HTML text content and quoted attribute values; bidi controls are left out. */
+export declare function escapeHtml(text: any): string;
+/**
+ * Checks a template and cuts it at its placeholders. Throws INVALID_TEMPLATE (see above).
+ * @param {string} source
+ * @returns {Template}
+ */
+export declare function parseTemplate(source: string): Template;
+/**
+ * The template with its placeholders filled: text values escaped, markup values as given (built by
+ * pivotkit). A placeholder without a value is empty.
+ * @param {Template} template  from parseTemplate()
+ * @param {Partial<Record<string, string>>} values
+ * @returns {string}
+ */
+export declare function fillTemplate(template: Template, values: Partial<Record<string, string>>): string;

package/types/texts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The characters that change the direction of text, as pivotkit-core's import leaves them out: a report
+ * writes none of them (HTML, SVG), so no name reads as another one ("invoice\u202Etxt.exe").
+ */
+export declare const BIDI_CONTROLS: RegExp;
+export declare const REPORT_TEXTS: Readonly<{
+    en: Readonly<{
+        untitled: "Report";
+        source: "Source";
+        rows: "Rows";
+        rowsCount: "{count} rows";
+        generated: "Generated";
+        filters: "Filters";
+        noFilters: "None";
+        chart: "Chart";
+        tableCut: "The table shows the first {shown} of {count} rows. Export it as Excel or CSV for all of them.";
+        chartCut: "The chart shows the first {shown} of {count} categories.";
+        chartUnavailable: "The chart is left out: ECharts is not available.";
+    }>;
+    de: Readonly<{
+        untitled: "Bericht";
+        source: "Quelle";
+        rows: "Zeilen";
+        rowsCount: "{count} Zeilen";
+        generated: "Erstellt";
+        filters: "Filter";
+        noFilters: "Keine";
+        chart: "Diagramm";
+        tableCut: "Die Tabelle zeigt die ersten {shown} von {count} Zeilen. Für alle als Excel oder CSV exportieren.";
+        chartCut: "Das Diagramm zeigt die ersten {shown} von {count} Kategorien.";
+        chartUnavailable: "Das Diagramm fehlt: ECharts ist nicht verfügbar.";
+    }>;
+}>;
+export type ReportTexts = typeof REPORT_TEXTS.en;
+/** @typedef {typeof REPORT_TEXTS.en} ReportTexts */
+/**
+ * The texts for a locale, the host's over them.
+ * @param {string} locale
+ * @param {Partial<ReportTexts>} [own]
+ * @returns {ReportTexts}
+ */
+export declare function textsFor(locale: string, own?: Partial<ReportTexts>): ReportTexts;
+/** "{count} rows" with its values. */
+export declare const fill: (text: any, values: any) => any;