@hestia-earth/data-validation 0.41.1 → 0.41.3

package/file-errors/public-api.d.mts

@@ -0,0 +1,237 @@
+import { NodeType, SchemaType } from '@hestia-earth/schema';
+
+/**
+ * A renderer abstracts every presentation primitive used to build an error message.
+ *
+ * The error catalog is a single source of truth; swapping the renderer changes only how
+ * the messages are presented:
+ *  - `htmlRenderer` reproduces the exact Bulma-classed HTML consumed by the Angular app.
+ *  - `textRenderer` produces framework-agnostic plain text (with lightweight markdown for
+ *    code spans, links and lists) suitable for any non-Angular consumer.
+ */
+interface IErrorRenderer {
+    code: (text: string | number | boolean) => string;
+    link: (href: string, text: string, newTab?: boolean) => string;
+    list: (values: (string | string[])[], style?: 'disc' | 'decimal') => string;
+    paragraph: (text: string) => string;
+    bold: (text: string) => string;
+    subscript: (text: string) => string;
+    underline: (text: string) => string;
+    /** Inline line break, e.g. `<br/>` or `\n`. */
+    lineBreak: string;
+    /** Separator used when joining inline code spans (`joinValues`). */
+    inlineSeparator: string;
+    /** Wraps the leading sentence of a default (non-catalog) message. */
+    capitalizeFirst: (text: string) => string;
+    /** Wraps the whole formatted message; receives a non-empty string. */
+    wrapMessage: (text: string) => string;
+}
+declare const htmlRenderer: IErrorRenderer;
+declare const textRenderer: IErrorRenderer;
+
+/**
+ * Provides the base URLs used to build links inside error messages.
+ *
+ * Functions (rather than plain strings) keep the lookups lazy: the Angular app reads them
+ * from `window.location` at call time, while a non-Angular consumer can pass static values.
+ */
+interface IUrlConfig {
+    baseUrl: () => string;
+    glossaryBaseUrl: () => string;
+    schemaBaseUrl: () => string;
+}
+/**
+ * Static, browser-free default configuration pointing at the public HESTIA platform.
+ */
+declare const defaultUrlConfig: IUrlConfig;
+/**
+ * Builds a configuration from a single base URL.
+ */
+declare const urlConfig: (baseUrl?: string) => IUrlConfig;
+
+/**
+ * Framework-agnostic validation types.
+ *
+ * These mirror the canonical definitions in `../schema/schema-validation.model` but are
+ * duplicated here so this entry point stays self-contained (no import from the Angular
+ * primary entry point). They are kept structurally compatible on purpose.
+ */
+type validationErrorLevel = 'error' | 'warning';
+type validationErrorParam = 'missingProperty' | 'type' | 'term' | 'termType' | 'termIds' | 'model' | 'product' | 'range' | 'node' | 'allowedValues' | 'allowedValue' | 'additionalProperty' | 'expected' | 'default' | 'current' | 'percentage' | 'keys' | 'threshold' | 'outliers' | 'country' | 'min' | 'max' | 'mu' | 'sd' | 'defaultSource' | 'source' | 'group' | 'message' | 'distance' | 'siteType' | 'products' | 'units' | 'duplicatedIndexes' | 'invalidCoordinates' | 'ids' | 'limit' | 'delta';
+type validationErrorKeyword = 'required' | 'type' | 'if' | 'then' | 'not';
+interface ICustomValidationRules {
+    const?: any;
+    required?: string[];
+    enum?: string[];
+    contains?: ICustomValidationRules;
+    properties?: {
+        [property: string]: ICustomValidationRules;
+    };
+    not?: ICustomValidationRules;
+    items?: ICustomValidationRules;
+    allOf?: ICustomValidationRules[];
+    anyOf?: ICustomValidationRules[];
+    oneOf?: ICustomValidationRules[];
+}
+interface IValidationError {
+    index?: number;
+    nodeIndex?: number;
+    level?: validationErrorLevel;
+    dataPath?: string;
+    schemaPath?: string;
+    keyword?: validationErrorKeyword;
+    message: string;
+    params?: {
+        [key in validationErrorParam]?: any;
+    };
+    schema?: ICustomValidationRules;
+}
+interface IValidationErrorWithIndex {
+    error: IValidationError[];
+    index: number;
+    changed?: boolean;
+}
+interface IDataPath {
+    path: string;
+    /**
+     * Human readable version of the path.
+     */
+    label: string;
+    nodeType?: NodeType;
+    schemaType?: SchemaType;
+}
+/**
+ * Structured, framework-agnostic representation of a formatted validation error.
+ */
+interface IFormattedError {
+    level: validationErrorLevel;
+    /**
+     * The rendered message. Plain text (or lightweight markdown) by default, HTML when
+     * formatted with the html renderer.
+     */
+    message: string;
+    /**
+     * Human readable location of the error within the document (derived from the dataPath).
+     */
+    location?: string;
+    dataPath?: string;
+    keyword?: validationErrorKeyword;
+}
+
+/**
+ * One failure inside a group, kept with the node it was raised on so a caller can show the offending
+ * entry rather than only the count.
+ */
+interface IErrorGroupEntry {
+    nodeIndex: number;
+    error: IValidationError;
+    node?: any;
+    /** The Term the failure is about, when the validator named one or the node carries one at that path. */
+    term?: any;
+}
+interface IErrorGroup {
+    level: validationErrorLevel;
+    /**
+     * The validator's own message, unformatted. It is the grouping key because it is also the key the error
+     * catalog and the validation list are addressed by — formatting first would group on presentation.
+     */
+    message: string;
+    /** Human-readable location, e.g. `Cycle › Practice`. */
+    path: string;
+    /** `@type` of the nodes in the group, when they are known. */
+    nodeType?: string;
+    count: number;
+    nodeIndexes: number[];
+    entries: IErrorGroupEntry[];
+    terms: any[];
+    /** Present only when a formatter was given. */
+    formattedMessage?: string;
+}
+/**
+ * The subset of `createErrorFormatter`'s result this module needs. Taking the functions rather than a
+ * renderer keeps the grouping independent of presentation: the same groups render as HTML in the platform
+ * UI and as plain text everywhere else.
+ */
+interface IErrorGroupFormatter {
+    dataPathLabel: (dataPath?: string) => string | undefined;
+    formatError: (error?: IValidationError, allErrors?: IValidationError[]) => IValidationError | undefined;
+}
+interface IGroupErrorsOptions {
+    /** The uploaded nodes, indexed as the errors are. Without them a group has no term and no node type. */
+    nodes?: any[];
+    formatter?: IErrorGroupFormatter;
+}
+/**
+ * Collapses a file's validation failures into one entry per distinct problem.
+ *
+ * An upload that fails one rule fails it on every row it applies to, so the raw list is mostly repetition:
+ * grouping on the message, the level and the location is what turns "247 failures" into the handful of
+ * things the uploader actually has to fix. Groups keep first-seen order — the order the file itself puts
+ * them in — and callers that want another order sort the result.
+ */
+declare const groupErrors: (errors?: IValidationErrorWithIndex[], { nodes, formatter }?: IGroupErrorsOptions) => IErrorGroup[];
+
+declare const validationGuidePrefix = "guide-data-validation";
+/**
+ * `guide-data-validation-cycle#validate_functionalUnit_not_1_ha`, and `undefined` for a message the
+ * validation list does not carry — a schema-level failure raises those too.
+ */
+declare const validationGuidePage: (nodeType: SchemaType | string, message: string) => string;
+
+declare enum Repository {
+    glossary = "hestia-glossary",
+    models = "hestia-engine-models",
+    aggregation = "hestia-aggregation-engine",
+    community = "hestia-community-edition",
+    schema = "hestia-schema",
+    frontend = "hestia-front-end"
+}
+declare enum Template {
+    bug = "bug",
+    feature = "feature"
+}
+interface IIssueParams {
+    title?: string;
+    description?: string;
+}
+declare const reportIssueUrl: (repository: Repository, template?: Template, issueParams?: IIssueParams) => string;
+
+declare const guidePageId: (nodeType: SchemaType, errorMessage: string) => string;
+declare const isMigrationError: ({ params }: IValidationError) => boolean;
+interface ICreateErrorFormatterOptions {
+    renderer: IErrorRenderer;
+    urls: IUrlConfig;
+}
+/**
+ * Builds the error formatting functions for a given presentation (`renderer`) and link
+ * configuration (`urls`). The error catalog below is the single source of truth; the
+ * renderer alone decides whether the output is HTML, plain text, etc.
+ */
+declare const createErrorFormatter: ({ renderer: r, urls }: ICreateErrorFormatterOptions) => {
+    parseDataPath: (dataPath?: string) => IDataPath[];
+    dataPathLabel: (dataPath?: string) => string;
+    migrationErrorMessage: ({ params }: IValidationError) => string;
+    formatCustomErrorMessage: (message?: string, error?: IValidationError, allErrors?: IValidationError[]) => string;
+    formatError: (error?: IValidationError, allErrors?: IValidationError[]) => IValidationError;
+    formatErrors: (errors?: IValidationError[]) => IFormattedError[];
+    locationLabel: (dataPath?: string) => string;
+};
+declare const errorHasError: (error?: IValidationError) => boolean;
+declare const errorHasWarning: (error?: IValidationError) => boolean;
+declare const isMissingPropertyError: ({ params }: IValidationError) => boolean;
+declare const isMissingOneOfError: ({ keyword, schemaPath }: IValidationError) => boolean;
+declare const filterError: (error: IValidationError) => boolean;
+declare const missingNodeErrors: (errors: IValidationError[]) => IValidationError[];
+
+interface IFormatErrorsOptions {
+    /** Presentation renderer. Defaults to `textRenderer` (plain text / lightweight markdown). */
+    renderer?: IErrorRenderer;
+    /** Base URLs used to build links. Defaults to the public HESTIA platform. */
+    urls?: IUrlConfig;
+}
+/**
+ * Formats a list of validation errors into structured, framework-agnostic objects.
+ */
+declare const formatErrors: (errors?: IValidationError[], options?: IFormatErrorsOptions) => IFormattedError[];
+
+export { type ICreateErrorFormatterOptions, type ICustomValidationRules, type IDataPath, type IErrorGroup, type IErrorGroupEntry, type IErrorGroupFormatter, type IErrorRenderer, type IFormatErrorsOptions, type IFormattedError, type IGroupErrorsOptions, type IUrlConfig, type IValidationError, type IValidationErrorWithIndex, Repository, Template, createErrorFormatter, defaultUrlConfig, errorHasError, errorHasWarning, filterError, formatErrors, groupErrors, guidePageId, htmlRenderer, isMigrationError, isMissingOneOfError, isMissingPropertyError, missingNodeErrors, reportIssueUrl, textRenderer, urlConfig, type validationErrorKeyword, type validationErrorLevel, type validationErrorParam, validationGuidePage, validationGuidePrefix };

package/file-errors/public-api.d.ts

@@ -0,0 +1,237 @@
+import { NodeType, SchemaType } from '@hestia-earth/schema';
+
+/**
+ * A renderer abstracts every presentation primitive used to build an error message.
+ *
+ * The error catalog is a single source of truth; swapping the renderer changes only how
+ * the messages are presented:
+ *  - `htmlRenderer` reproduces the exact Bulma-classed HTML consumed by the Angular app.
+ *  - `textRenderer` produces framework-agnostic plain text (with lightweight markdown for
+ *    code spans, links and lists) suitable for any non-Angular consumer.
+ */
+interface IErrorRenderer {
+    code: (text: string | number | boolean) => string;
+    link: (href: string, text: string, newTab?: boolean) => string;
+    list: (values: (string | string[])[], style?: 'disc' | 'decimal') => string;
+    paragraph: (text: string) => string;
+    bold: (text: string) => string;
+    subscript: (text: string) => string;
+    underline: (text: string) => string;
+    /** Inline line break, e.g. `<br/>` or `\n`. */
+    lineBreak: string;
+    /** Separator used when joining inline code spans (`joinValues`). */
+    inlineSeparator: string;
+    /** Wraps the leading sentence of a default (non-catalog) message. */
+    capitalizeFirst: (text: string) => string;
+    /** Wraps the whole formatted message; receives a non-empty string. */
+    wrapMessage: (text: string) => string;
+}
+declare const htmlRenderer: IErrorRenderer;
+declare const textRenderer: IErrorRenderer;
+
+/**
+ * Provides the base URLs used to build links inside error messages.
+ *
+ * Functions (rather than plain strings) keep the lookups lazy: the Angular app reads them
+ * from `window.location` at call time, while a non-Angular consumer can pass static values.
+ */
+interface IUrlConfig {
+    baseUrl: () => string;
+    glossaryBaseUrl: () => string;
+    schemaBaseUrl: () => string;
+}
+/**
+ * Static, browser-free default configuration pointing at the public HESTIA platform.
+ */
+declare const defaultUrlConfig: IUrlConfig;
+/**
+ * Builds a configuration from a single base URL.
+ */
+declare const urlConfig: (baseUrl?: string) => IUrlConfig;
+
+/**
+ * Framework-agnostic validation types.
+ *
+ * These mirror the canonical definitions in `../schema/schema-validation.model` but are
+ * duplicated here so this entry point stays self-contained (no import from the Angular
+ * primary entry point). They are kept structurally compatible on purpose.
+ */
+type validationErrorLevel = 'error' | 'warning';
+type validationErrorParam = 'missingProperty' | 'type' | 'term' | 'termType' | 'termIds' | 'model' | 'product' | 'range' | 'node' | 'allowedValues' | 'allowedValue' | 'additionalProperty' | 'expected' | 'default' | 'current' | 'percentage' | 'keys' | 'threshold' | 'outliers' | 'country' | 'min' | 'max' | 'mu' | 'sd' | 'defaultSource' | 'source' | 'group' | 'message' | 'distance' | 'siteType' | 'products' | 'units' | 'duplicatedIndexes' | 'invalidCoordinates' | 'ids' | 'limit' | 'delta';
+type validationErrorKeyword = 'required' | 'type' | 'if' | 'then' | 'not';
+interface ICustomValidationRules {
+    const?: any;
+    required?: string[];
+    enum?: string[];
+    contains?: ICustomValidationRules;
+    properties?: {
+        [property: string]: ICustomValidationRules;
+    };
+    not?: ICustomValidationRules;
+    items?: ICustomValidationRules;
+    allOf?: ICustomValidationRules[];
+    anyOf?: ICustomValidationRules[];
+    oneOf?: ICustomValidationRules[];
+}
+interface IValidationError {
+    index?: number;
+    nodeIndex?: number;
+    level?: validationErrorLevel;
+    dataPath?: string;
+    schemaPath?: string;
+    keyword?: validationErrorKeyword;
+    message: string;
+    params?: {
+        [key in validationErrorParam]?: any;
+    };
+    schema?: ICustomValidationRules;
+}
+interface IValidationErrorWithIndex {
+    error: IValidationError[];
+    index: number;
+    changed?: boolean;
+}
+interface IDataPath {
+    path: string;
+    /**
+     * Human readable version of the path.
+     */
+    label: string;
+    nodeType?: NodeType;
+    schemaType?: SchemaType;
+}
+/**
+ * Structured, framework-agnostic representation of a formatted validation error.
+ */
+interface IFormattedError {
+    level: validationErrorLevel;
+    /**
+     * The rendered message. Plain text (or lightweight markdown) by default, HTML when
+     * formatted with the html renderer.
+     */
+    message: string;
+    /**
+     * Human readable location of the error within the document (derived from the dataPath).
+     */
+    location?: string;
+    dataPath?: string;
+    keyword?: validationErrorKeyword;
+}
+
+/**
+ * One failure inside a group, kept with the node it was raised on so a caller can show the offending
+ * entry rather than only the count.
+ */
+interface IErrorGroupEntry {
+    nodeIndex: number;
+    error: IValidationError;
+    node?: any;
+    /** The Term the failure is about, when the validator named one or the node carries one at that path. */
+    term?: any;
+}
+interface IErrorGroup {
+    level: validationErrorLevel;
+    /**
+     * The validator's own message, unformatted. It is the grouping key because it is also the key the error
+     * catalog and the validation list are addressed by — formatting first would group on presentation.
+     */
+    message: string;
+    /** Human-readable location, e.g. `Cycle › Practice`. */
+    path: string;
+    /** `@type` of the nodes in the group, when they are known. */
+    nodeType?: string;
+    count: number;
+    nodeIndexes: number[];
+    entries: IErrorGroupEntry[];
+    terms: any[];
+    /** Present only when a formatter was given. */
+    formattedMessage?: string;
+}
+/**
+ * The subset of `createErrorFormatter`'s result this module needs. Taking the functions rather than a
+ * renderer keeps the grouping independent of presentation: the same groups render as HTML in the platform
+ * UI and as plain text everywhere else.
+ */
+interface IErrorGroupFormatter {
+    dataPathLabel: (dataPath?: string) => string | undefined;
+    formatError: (error?: IValidationError, allErrors?: IValidationError[]) => IValidationError | undefined;
+}
+interface IGroupErrorsOptions {
+    /** The uploaded nodes, indexed as the errors are. Without them a group has no term and no node type. */
+    nodes?: any[];
+    formatter?: IErrorGroupFormatter;
+}
+/**
+ * Collapses a file's validation failures into one entry per distinct problem.
+ *
+ * An upload that fails one rule fails it on every row it applies to, so the raw list is mostly repetition:
+ * grouping on the message, the level and the location is what turns "247 failures" into the handful of
+ * things the uploader actually has to fix. Groups keep first-seen order — the order the file itself puts
+ * them in — and callers that want another order sort the result.
+ */
+declare const groupErrors: (errors?: IValidationErrorWithIndex[], { nodes, formatter }?: IGroupErrorsOptions) => IErrorGroup[];
+
+declare const validationGuidePrefix = "guide-data-validation";
+/**
+ * `guide-data-validation-cycle#validate_functionalUnit_not_1_ha`, and `undefined` for a message the
+ * validation list does not carry — a schema-level failure raises those too.
+ */
+declare const validationGuidePage: (nodeType: SchemaType | string, message: string) => string;
+
+declare enum Repository {
+    glossary = "hestia-glossary",
+    models = "hestia-engine-models",
+    aggregation = "hestia-aggregation-engine",
+    community = "hestia-community-edition",
+    schema = "hestia-schema",
+    frontend = "hestia-front-end"
+}
+declare enum Template {
+    bug = "bug",
+    feature = "feature"
+}
+interface IIssueParams {
+    title?: string;
+    description?: string;
+}
+declare const reportIssueUrl: (repository: Repository, template?: Template, issueParams?: IIssueParams) => string;
+
+declare const guidePageId: (nodeType: SchemaType, errorMessage: string) => string;
+declare const isMigrationError: ({ params }: IValidationError) => boolean;
+interface ICreateErrorFormatterOptions {
+    renderer: IErrorRenderer;
+    urls: IUrlConfig;
+}
+/**
+ * Builds the error formatting functions for a given presentation (`renderer`) and link
+ * configuration (`urls`). The error catalog below is the single source of truth; the
+ * renderer alone decides whether the output is HTML, plain text, etc.
+ */
+declare const createErrorFormatter: ({ renderer: r, urls }: ICreateErrorFormatterOptions) => {
+    parseDataPath: (dataPath?: string) => IDataPath[];
+    dataPathLabel: (dataPath?: string) => string;
+    migrationErrorMessage: ({ params }: IValidationError) => string;
+    formatCustomErrorMessage: (message?: string, error?: IValidationError, allErrors?: IValidationError[]) => string;
+    formatError: (error?: IValidationError, allErrors?: IValidationError[]) => IValidationError;
+    formatErrors: (errors?: IValidationError[]) => IFormattedError[];
+    locationLabel: (dataPath?: string) => string;
+};
+declare const errorHasError: (error?: IValidationError) => boolean;
+declare const errorHasWarning: (error?: IValidationError) => boolean;
+declare const isMissingPropertyError: ({ params }: IValidationError) => boolean;
+declare const isMissingOneOfError: ({ keyword, schemaPath }: IValidationError) => boolean;
+declare const filterError: (error: IValidationError) => boolean;
+declare const missingNodeErrors: (errors: IValidationError[]) => IValidationError[];
+
+interface IFormatErrorsOptions {
+    /** Presentation renderer. Defaults to `textRenderer` (plain text / lightweight markdown). */
+    renderer?: IErrorRenderer;
+    /** Base URLs used to build links. Defaults to the public HESTIA platform. */
+    urls?: IUrlConfig;
+}
+/**
+ * Formats a list of validation errors into structured, framework-agnostic objects.
+ */
+declare const formatErrors: (errors?: IValidationError[], options?: IFormatErrorsOptions) => IFormattedError[];
+
+export { type ICreateErrorFormatterOptions, type ICustomValidationRules, type IDataPath, type IErrorGroup, type IErrorGroupEntry, type IErrorGroupFormatter, type IErrorRenderer, type IFormatErrorsOptions, type IFormattedError, type IGroupErrorsOptions, type IUrlConfig, type IValidationError, type IValidationErrorWithIndex, Repository, Template, createErrorFormatter, defaultUrlConfig, errorHasError, errorHasWarning, filterError, formatErrors, groupErrors, guidePageId, htmlRenderer, isMigrationError, isMissingOneOfError, isMissingPropertyError, missingNodeErrors, reportIssueUrl, textRenderer, urlConfig, type validationErrorKeyword, type validationErrorLevel, type validationErrorParam, validationGuidePage, validationGuidePrefix };