@navette-js/tables 0.0.0-stage → 1.0.0-beta.2

package/lib/query-builder.d.ts

@@ -0,0 +1,302 @@
+import type { ListQuery } from '@navette-js/database';
+import { Block, Builder } from '@navette-js/forms/builder';
+import { Component } from '@navette-js/schemas';
+import type { FilterIndicator, FilterState, TableFilter, TableHost } from './index.ts';
+/** Limits applied to the rule tree received from the browser. */
+export declare const MAX_RULES = 100;
+export declare const MAX_NESTING_DEPTH = 3;
+/** Maximum number of values in a multiple select. */
+export declare const MAX_LIST_VALUES = 100;
+type Comparison = '=' | '!=' | '<' | '<=' | '>' | '>=';
+type Key = string | number;
+export type Condition = {
+    kind: 'like';
+    column: string;
+    pattern: string;
+    negate: boolean;
+} | {
+    kind: 'compare';
+    column: string;
+    operator: Comparison;
+    value: string | number;
+} | {
+    kind: 'boolean';
+    column: string;
+    value: boolean;
+} | {
+    kind: 'date' | 'month' | 'year';
+    column: string;
+    operator: Comparison;
+    value: string | number;
+}
+/** Value is filled (neither null nor an empty string), or the opposite. */
+ | {
+    kind: 'filled';
+    column: string;
+    negate: boolean;
+} | {
+    kind: 'in';
+    column: string;
+    values: Key[];
+    negate: boolean;
+}
+/** Number of related records compared to a value. */
+ | {
+    kind: 'relationCount';
+    relationship: string;
+    operator: Comparison;
+    value: number;
+    modify?: RelationshipQueryModifier;
+}
+/** At least one related record (among `keys` when given), or none (`negate`). */
+ | {
+    kind: 'related';
+    relationship: string;
+    keys: Key[] | null;
+    negate: boolean;
+    modify?: RelationshipQueryModifier;
+};
+/** `{ relationship, nodes }`: the nodes apply to the related records (`whereExists` subquery). */
+export type ConditionNode = Condition | {
+    or: ConditionNode[][];
+} | {
+    relationship: string;
+    nodes: ConditionNode[];
+    modify?: RelationshipQueryModifier;
+};
+type Settings = Record<string, unknown>;
+type Resolved = {
+    condition: Condition;
+    summary: string;
+};
+/** Constraint operator: its settings form and how it turns into a condition. */
+type Operator = {
+    name: string;
+    label: (inverse: boolean) => string;
+    /** Default settings (null: the operator has no form). */
+    defaults: () => Settings | null;
+    fields: () => Component[];
+    /** Null when the settings fail the form's validation: the rule then has no effect. */
+    resolve: (settings: Settings, inverse: boolean, constraint: Constraint) => Resolved | null;
+    /** Condition applied to the base query even when the constraint targets a relationship (RelationshipConstraint operators). */
+    onBaseQuery?: boolean;
+};
+/** Date (or date-time, with `hasTime`) targeted by an "after / before" operator's settings. */
+export declare function resolveRuleDate(settings: Settings, now?: Date, hasTime?: boolean): string | null;
+declare const OPERATORS: Record<'text' | 'number' | 'boolean' | 'date', Operator[]>;
+type ConstraintType = keyof typeof OPERATORS | 'select' | 'relationship';
+/** Application-defined modifier of the related records query (knex / objection). */
+export type RelationshipQueryModifier = (query: any) => void;
+/**
+ * Attribute the query builder can filter on. The queried column and relationship are the ones declared here, never browser values:
+ * the browser only picks a constraint (by name) and one of its operators.
+ */
+export declare class Constraint {
+    readonly name: string;
+    readonly type: ConstraintType;
+    private _label;
+    private _attributeLabel;
+    private _icon;
+    private _column;
+    protected _relationship: string | null;
+    protected _modifyRelationshipQuery: RelationshipQueryModifier | null;
+    protected _nullable: boolean;
+    /** Objection model of the table's records, used to list related records. */
+    protected _model: any;
+    constructor(name: string, type: ConstraintType, icon: string);
+    label(label: string): this;
+    /** Attribute name used in rule summaries (defaults to the label). */
+    attributeLabel(label: string | null): this;
+    icon(name: string): this;
+    /** Queried column (or query alias) when it differs from the name. */
+    attribute(column: string): this;
+    /**
+     * Filters on an attribute of related records: `relationship('author', 'name')` filters on the author's name.
+     * The relationship must be declared by the Objection model (`relationMappings`).
+     */
+    relationship(name: string, titleAttribute: string, modifyQueryUsing?: RelationshipQueryModifier | null): this;
+    modifyRelationshipQueryUsing(callback: RelationshipQueryModifier | null): this;
+    /** Adds the "Is filled" / "Is blank" operator. */
+    nullable(condition?: boolean): this;
+    isNullable(): boolean;
+    model(model: any): this;
+    getModel(): any;
+    getLabel(): string;
+    getAttributeLabel(): string;
+    getIcon(): string;
+    getColumn(): string;
+    /** Relationship whose records hold the attribute, or `null` for a column of the table. */
+    getRelationshipName(): string | null;
+    getModifyRelationshipQueryUsing(): RelationshipQueryModifier | null;
+    getOperators(): Operator[];
+    /** `contains` or `contains.inverse` → operator and direction; null if the constraint does not declare it. */
+    parseOperator(value: unknown): {
+        operator: Operator;
+        inverse: boolean;
+    } | null;
+    getOperatorOptions(): [string, string][];
+    /** Setting names known to the constraint across all operators (switching operator keeps the previous settings). */
+    getSettingNames(): string[];
+    /** Settings whose value is a list (multiple select). */
+    getListSettingNames(): string[];
+    getDefaultData(): Record<string, unknown>;
+}
+export declare class TextConstraint extends Constraint {
+    static make(name: string): TextConstraint;
+}
+export declare class NumberConstraint extends Constraint {
+    static make(name: string): NumberConstraint;
+}
+export declare class BooleanConstraint extends Constraint {
+    static make(name: string): BooleanConstraint;
+}
+/** Date constraint; with `time()`, date and time (date-time picker, minute and hour presets and units). */
+export declare class DateConstraint extends Constraint {
+    private _time;
+    static make(name: string): DateConstraint;
+    time(condition?: boolean): this;
+    hasTime(): boolean;
+    getOperators(): Operator[];
+}
+/** Value picked from a fixed list; with `multiple()`, any of the picked values. */
+export declare class SelectConstraint extends Constraint {
+    private _options;
+    private _multiple;
+    private _searchable;
+    static make(name: string): SelectConstraint;
+    /** Options as `[value, label]` pairs or `{ value: label }`; only these values can filter. */
+    options(options: [string | number, string][] | Record<string, string>): this;
+    getOptions(): [string, string][];
+    multiple(condition?: boolean): this;
+    isMultiple(): boolean;
+    searchable(condition?: boolean): this;
+    getOperators(): Operator[];
+}
+/**
+ * "Is" / "Contains" operator of a RelationshipConstraint: related records are picked by key from a list loaded from the related model;
+ * `titleAttribute` is the displayed column.
+ */
+export declare class IsRelatedToOperator {
+    private _titleAttribute;
+    private _multiple;
+    private _searchable;
+    private _preload;
+    private _optionsLimit;
+    private _modifyQuery;
+    static make(): IsRelatedToOperator;
+    titleAttribute(attribute: string | null): this;
+    getTitleAttribute(): string | null;
+    multiple(condition?: boolean): this;
+    isMultiple(): boolean;
+    searchable(condition?: boolean): this;
+    preload(condition?: boolean): this;
+    optionsLimit(limit: number): this;
+    modifyRelationshipQueryUsing(callback: RelationshipQueryModifier | null): this;
+    getModifyRelationshipQueryUsing(): RelationshipQueryModifier | null;
+    /** Builds the query builder operator for the given constraint. */
+    toOperator(constraint: RelationshipConstraint): Operator;
+    getOptionsLimit(): number;
+}
+/**
+ * Related records: minimum, maximum or exact count (`multiple()`), empty relationship (`emptyable()`, on by default with `multiple()`),
+ * or related to picked records (`selectable(IsRelatedToOperator.make()…)`).
+ */
+export declare class RelationshipConstraint extends Constraint {
+    private _multiple;
+    private _emptyable;
+    private _selectable;
+    /** Labels of the related records cited by rules, loaded before indicators are computed. */
+    private _relatedLabels;
+    static make(name: string): RelationshipConstraint;
+    multiple(condition?: boolean): this;
+    isMultiple(): boolean;
+    emptyable(condition?: boolean | null): this;
+    canBeEmpty(): boolean;
+    selectable(operator: IsRelatedToOperator): this;
+    getSelectableOperator(): IsRelatedToOperator | null;
+    /** Queried relationship: from `relationship()`, else `attribute()`, else the constraint name. */
+    getRelationshipName(): string;
+    getOperators(): Operator[];
+    getRelatedLabel(key: Key): string | null;
+    /** Related model, found through the table model's relationship (declared, or the host's Objection adapter model). */
+    private relatedModel;
+    private relatedQuery;
+    /** Select options: records of the related model, sorted by title. */
+    loadRelatedOptions(operator: IsRelatedToOperator, host: unknown): Promise<[string, string][]>;
+    /** Loads labels of the keys cited by rules (for indicators such as "Author is Ada or Linus"). */
+    loadRelatedLabels(keys: Key[], host: unknown): Promise<void>;
+}
+type Rule = {
+    type: string;
+    data: Record<string, any>;
+};
+type Rules = Record<string, Rule>;
+/**
+ * Reduces the browser's rule tree to what the filter declares: known block types, the constraint's operators, scalar settings with
+ * known names, bounded depth and rule count. An unknown operator is reset to null (the rule has no effect).
+ */
+export declare function sanitizeRules(constraints: Constraint[], raw: unknown, depth?: number, budget?: {
+    rules: number;
+}): Rules;
+/** Sanitized rules → conditions and indicator labels (one entry per effective top-level rule). */
+export declare function compileRules(constraints: Constraint[], rules: Rules, iteration?: number): {
+    nodes: ConditionNode[];
+    summaries: Record<string, string>;
+};
+/** SQL dialect of the query's knex connection. */
+export type SqlDialect = 'sqlite' | 'mysql' | 'pg' | 'mssql';
+/** Dialect read from the knex client (`query.client.config.client`, or the Objection model's connection); SQLite by default. */
+export declare function sqlDialectOf(query: any): SqlDialect;
+/**
+ * Applies conditions to a knex / objection query. Columns are bound as identifiers and values as parameters; comparison operators
+ * come from a closed list. Date and search SQL follows the connection's dialect.
+ */
+export declare function applyConditions(query: any, nodes: ConditionNode[], dialect?: SqlDialect): void;
+/** Rule builder: a Builder whose blocks are the filter's constraints, plus the "OR" block. */
+export declare class RuleBuilder extends Builder {
+    readonly filter: QueryBuilder;
+    readonly depth: number;
+    constructor(name: string, filter: QueryBuilder, depth?: number);
+    /** The "OR" block is neither offered nor accepted beyond the maximum depth; nothing is offered once the rule limit is reached. */
+    getBlockPickerBlocks(): Block[];
+    getBlock(name: unknown): Block | undefined;
+    protected canAdd(): boolean;
+    /** Counts rules across the whole tree ("OR" blocks excluded), read from the host's deferred filter state. */
+    isAtRuleLimit(): boolean;
+    /** Component action without modal (also used by "OR" groups). */
+    makeAction(name: string, handler: (args: Record<string, unknown>) => void): any;
+}
+/** Query builder table filter. */
+export declare class QueryBuilder implements TableFilter {
+    readonly name = "queryBuilder";
+    private _constraints;
+    private _pickerColumns;
+    private _model;
+    static make(): QueryBuilder;
+    constraints(constraints: Constraint[]): this;
+    /** Objection model of the table, passed to relationship constraints (related record lists). */
+    model(model: any): this;
+    /** Before indicators: loads labels of the related records cited by rules (`RelationshipConstraint.selectable`). */
+    loadIndicatorData(state: FilterState, host: TableHost): Promise<void>;
+    constraintPickerColumns(columns?: number | null): this;
+    getConstraints(): Constraint[];
+    getConstraintPickerColumns(): number | null;
+    getLabel(): string;
+    getDefaultState(): FilterState;
+    getFormDefinition(): {
+        placeholder: string;
+        options: [string, string][];
+    };
+    /** The filter spans the full width of the filters form. */
+    getColumnSpan(): Record<string, number | string>;
+    getFormComponents(): Component[];
+    sanitizeState(state: unknown): FilterState;
+    countRules(state: unknown): number;
+    private compile;
+    isActive(state: FilterState): boolean;
+    getIndicators(state: FilterState): FilterIndicator[];
+    /** Removing an indicator removes the matching top-level rule. */
+    removeIndicator(state: FilterState, field: string): FilterState;
+    apply(query: Omit<ListQuery, 'page' | 'perPage'>, state: FilterState): void;
+}
+export {};