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

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';
+/** Plafonds appliqués à l'arbre de règles reçu du navigateur. */
+export declare const MAX_RULES = 100;
+export declare const MAX_NESTING_DEPTH = 3;
+/** Nombre maximal de valeurs d'une sélection multiple. */
+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;
+}
+/** Valeur renseignée (ni nulle, ni chaîne vide), ou l'inverse. */
+ | {
+    kind: 'filled';
+    column: string;
+    negate: boolean;
+} | {
+    kind: 'in';
+    column: string;
+    values: Key[];
+    negate: boolean;
+}
+/** Nombre d'enregistrements liés comparé à une valeur. */
+ | {
+    kind: 'relationCount';
+    relationship: string;
+    operator: Comparison;
+    value: number;
+    modify?: RelationshipQueryModifier;
+}
+/** Au moins un enregistrement lié (parmi `keys` si la liste est donnée), ou aucun (`negate`). */
+ | {
+    kind: 'related';
+    relationship: string;
+    keys: Key[] | null;
+    negate: boolean;
+    modify?: RelationshipQueryModifier;
+};
+/** `whereHas` : les conditions s'appliquent aux enregistrements liés par la relation. */
+export type ConditionNode = Condition | {
+    or: ConditionNode[][];
+} | {
+    relationship: string;
+    nodes: ConditionNode[];
+    modify?: RelationshipQueryModifier;
+};
+type Settings = Record<string, unknown>;
+type Resolved = {
+    condition: Condition;
+    summary: string;
+};
+/** Opérateur d'une contrainte : son formulaire de réglages et sa traduction en condition. */
+type Operator = {
+    name: string;
+    label: (inverse: boolean) => string;
+    /** Réglages par défaut (null : l'opérateur n'a pas de formulaire). */
+    defaults: () => Settings | null;
+    fields: () => Component[];
+    /** Null quand les réglages ne passent pas la validation du formulaire : la règle est alors sans effet, comme dans Filament. */
+    resolve: (settings: Settings, inverse: boolean, constraint: Constraint) => Resolved | null;
+    /** Condition posée sur la requête principale, même quand la contrainte vise une relation (opérateurs de RelationshipConstraint). */
+    onBaseQuery?: boolean;
+};
+/** Date (ou date et heure, avec `hasTime`) visée par les réglages d'un opérateur « après / avant ». */
+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';
+/** Modification de la requête des enregistrements liés (knex / objection), posée par l'application. */
+export type RelationshipQueryModifier = (query: any) => void;
+/**
+ * Attribut filtrable par le constructeur de requêtes (port de Constraint). La colonne et la relation interrogées sont celles déclarées
+ * ici, jamais des valeurs du navigateur : celui-ci ne choisit qu'une contrainte (par son nom) et un opérateur de sa liste.
+ */
+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;
+    /** Modèle Objection interrogé (enregistrements de la table), pour les listes d'enregistrements liés. */
+    protected _model: any;
+    constructor(name: string, type: ConstraintType, icon: string);
+    label(label: string): this;
+    /** Nom de l'attribut dans les résumés des règles (par défaut, le libellé). */
+    attributeLabel(label: string | null): this;
+    icon(name: string): this;
+    /** Colonne (ou alias de la requête) interrogée quand elle diffère du nom. */
+    attribute(column: string): this;
+    /**
+     * La contrainte porte sur un attribut d'enregistrements liés (`whereHas`) : `relationship('author', 'name')` filtre sur le nom de
+     * l'auteur. La relation doit être déclarée par le modèle Objection (`relationMappings`).
+     */
+    relationship(name: string, titleAttribute: string, modifyQueryUsing?: RelationshipQueryModifier | null): this;
+    modifyRelationshipQueryUsing(callback: RelationshipQueryModifier | null): this;
+    /** Ajoute l'opérateur « Is filled » / « Is blank » (port de `nullable()`). */
+    nullable(condition?: boolean): this;
+    isNullable(): boolean;
+    model(model: any): this;
+    getModel(): any;
+    getLabel(): string;
+    getAttributeLabel(): string;
+    getIcon(): string;
+    getColumn(): string;
+    /** Relation dont les enregistrements portent l'attribut, ou `null` pour une colonne de la table. */
+    getRelationshipName(): string | null;
+    getModifyRelationshipQueryUsing(): RelationshipQueryModifier | null;
+    getOperators(): Operator[];
+    /** `contains` ou `contains.inverse` → opérateur et sens ; null si la contrainte ne le déclare pas. */
+    parseOperator(value: unknown): {
+        operator: Operator;
+        inverse: boolean;
+    } | null;
+    getOperatorOptions(): [string, string][];
+    /** Noms de réglages connus de la contrainte, tous opérateurs confondus (un changement d'opérateur conserve les anciens, comme Filament). */
+    getSettingNames(): string[];
+    /** Réglages dont la valeur est une liste (sélection multiple). */
+    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 ; avec `time()`, la date et l'heure (sélecteur date-heure, préréglages et unités à la minute ou à l'heure). */
+export declare class DateConstraint extends Constraint {
+    private _time;
+    static make(name: string): DateConstraint;
+    time(condition?: boolean): this;
+    hasTime(): boolean;
+    getOperators(): Operator[];
+}
+/** Valeur choisie dans une liste fixe (port de SelectConstraint) ; `multiple()` : l'une des valeurs choisies. */
+export declare class SelectConstraint extends Constraint {
+    private _options;
+    private _multiple;
+    private _searchable;
+    static make(name: string): SelectConstraint;
+    /** Options `[valeur, libellé]` ou `{ valeur: libellé }` ; seules ces valeurs filtrent. */
+    options(options: [string | number, string][] | Record<string, string>): this;
+    getOptions(): [string, string][];
+    multiple(condition?: boolean): this;
+    isMultiple(): boolean;
+    searchable(condition?: boolean): this;
+    getOperators(): Operator[];
+}
+/**
+ * Opérateur « Is » / « Contains » d'une RelationshipConstraint (port de IsRelatedToOperator) : les enregistrements liés sont choisis dans
+ * une liste tirée du modèle lié, par leur clé ; `titleAttribute` est la colonne affichée.
+ */
+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;
+    /** Opérateur du constructeur pour la contrainte donnée. */
+    toOperator(constraint: RelationshipConstraint): Operator;
+    getOptionsLimit(): number;
+}
+/**
+ * Enregistrements liés (port de RelationshipConstraint) : nombre minimal, maximal ou exact (`multiple()`), relation vide (`emptyable()`,
+ * par défaut avec `multiple()`), ou liés à des enregistrements choisis (`selectable(IsRelatedToOperator.make()…)`).
+ */
+export declare class RelationshipConstraint extends Constraint {
+    private _multiple;
+    private _emptyable;
+    private _selectable;
+    /** Libellés des enregistrements liés cités par les règles, chargés avant le calcul des indicateurs. */
+    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;
+    /** Relation interrogée : celle de `relationship()`, sinon `attribute()`, sinon le nom de la contrainte. */
+    getRelationshipName(): string;
+    getOperators(): Operator[];
+    getRelatedLabel(key: Key): string | null;
+    /** Modèle lié, retrouvé par la relation du modèle de la table (déclaré, ou celui de l'adaptateur Objection de l'hôte). */
+    private relatedModel;
+    private relatedQuery;
+    /** Options de la liste : enregistrements du modèle lié, triés par leur titre. */
+    loadRelatedOptions(operator: IsRelatedToOperator, host: unknown): Promise<[string, string][]>;
+    /** Charge les libellés des clés citées par des règles (indicateurs « 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>;
+/**
+ * Arbre de règles reçu du navigateur → arbre ne contenant que ce que le filtre déclare : types de blocs connus, opérateurs de la contrainte,
+ * réglages scalaires aux noms connus, profondeur et nombre de règles bornés. Un opérateur inconnu est remis à vide (règle sans effet).
+ */
+export declare function sanitizeRules(constraints: Constraint[], raw: unknown, depth?: number, budget?: {
+    rules: number;
+}): Rules;
+/** Règles nettoyées → conditions et libellés d'indicateurs (une entrée par règle de premier niveau qui a un effet). */
+export declare function compileRules(constraints: Constraint[], rules: Rules, iteration?: number): {
+    nodes: ConditionNode[];
+    summaries: Record<string, string>;
+};
+/** Famille de SQL de la connexion knex de la requête. */
+export type SqlDialect = 'sqlite' | 'mysql' | 'pg' | 'mssql';
+/** Dialecte lu dans le client knex (`query.client.config.client`, ou celui de la connexion du modèle Objection) ; SQLite par défaut. */
+export declare function sqlDialectOf(query: any): SqlDialect;
+/**
+ * Applique des conditions à une requête knex / objection. Colonnes passées en identifiants, valeurs en paramètres liés ; les opérateurs
+ * de comparaison viennent d'une liste fermée. Le SQL de date et de recherche suit le dialecte de la connexion.
+ */
+export declare function applyConditions(query: any, nodes: ConditionNode[], dialect?: SqlDialect): void;
+/** Constructeur de règles (port de RuleBuilder) : un Builder dont les blocs sont les contraintes du filtre, plus le bloc « OR ». */
+export declare class RuleBuilder extends Builder {
+    readonly filter: QueryBuilder;
+    readonly depth: number;
+    constructor(name: string, filter: QueryBuilder, depth?: number);
+    /** Le bloc « OR » n'est plus proposé (ni accepté) quand il dépasserait la profondeur autorisée ; rien ne l'est une fois le plafond de règles atteint. */
+    getBlockPickerBlocks(): Block[];
+    getBlock(name: unknown): Block | undefined;
+    protected canAdd(): boolean;
+    /** Nombre de règles de l'arbre entier (les blocs « OR » ne comptent pas), lu dans l'état différé de l'hôte. */
+    isAtRuleLimit(): boolean;
+    /** Action de composant sans modale (utilisée aussi par les groupes « OR »). */
+    makeAction(name: string, handler: (args: Record<string, unknown>) => void): any;
+}
+/** Filtre « constructeur de requêtes » d'une table. */
+export declare class QueryBuilder implements TableFilter {
+    readonly name = "queryBuilder";
+    private _constraints;
+    private _pickerColumns;
+    private _model;
+    static make(): QueryBuilder;
+    constraints(constraints: Constraint[]): this;
+    /** Modèle Objection de la table, transmis aux contraintes de relation (listes d'enregistrements liés). */
+    model(model: any): this;
+    /** Avant les indicateurs : charge les libellés des enregistrements liés que citent les règles (`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][];
+    };
+    /** Le filtre occupe toute la largeur du formulaire des filtres. */
+    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[];
+    /** Retrait d'un indicateur : la règle de premier niveau correspondante disparaît. */
+    removeIndicator(state: FilterState, field: string): FilterState;
+    apply(query: Omit<ListQuery, 'page' | 'perPage'>, state: FilterState): void;
+}
+export {};