@venizia/ignis-connectors 0.2.0-0

package/dist/cjs/relational/core/repositories/dialect/filter.d.ts

@@ -0,0 +1,199 @@
+import type { TDrizzleQueryOptions, TFields, TFilter, TInclusion, TQueryOperatorHandlers, TWhere } from '@venizia/ignis-kernel';
+import { Sorts } from '@venizia/ignis-kernel';
+import type { TTableObject, TTableSchemaWithId } from '../../../../relational/core/models/common';
+import { MetadataRegistry } from '@venizia/ignis-kernel';
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import { type SQL } from 'drizzle-orm';
+import type { TRelationConfig, TTableColumns } from '../common';
+/** Operators whose scalar operand determines the JSON numeric-cast need in jsonNeedsNumericCast. */
+/** What one registry lookup yields - named so the three setting readers can accept an already-resolved entry instead of each repeating the lookup. */
+type TResolvedModelEntry = ReturnType<MetadataRegistry['getModelEntry']>;
+/**
+ * Converts filter objects into Drizzle query options (where, order, columns, relations). The
+ * operator table and both JSON extractions are abstract rather than defaulted, so this tier
+ * emits no engine-specific SQL.
+ */
+export declare abstract class FilterBuilder extends BaseHelper {
+    /**
+     * Per-schema memo of resolved relations. `@model` settings are
+     * immutable after boot, so the lookup and resolver run once per schema.
+     */
+    private readonly _relationsCache;
+    constructor();
+    /** Handler table for `where` translation. Abstract so this class names no engine. */
+    protected abstract get operators(): TQueryOperatorHandlers;
+    /**
+     * Merges default and user filters. `where` merges at the TOP KEY LEVEL, never index-wise - that
+     * corrupts operator arrays. Operator-object collisions AND-compose, so a default scope can only
+     * be narrowed, and a user `undefined` never overrides a defined default. Other parts user-wins.
+     */
+    mergeFilter<T = any>(opts: {
+        defaultFilter?: TFilter<T>;
+        userFilter?: TFilter<T>;
+    }): TFilter<T>;
+    /**
+     * Top-key merge: operator-object collisions AND-compose under the reserved `and` key, merging
+     * with an existing `and` rather than clobbering it. Every other collision is user-wins.
+     */
+    private mergeWhere;
+    /**
+     * Registry lookup shared by the resolvers below. A failure degrades to no settings rather than
+     * failing the query, and is never silent - a degraded `resolveHiddenProperties` would stop
+     * hidden columns being omitted.
+     */
+    private resolveModelEntry;
+    /**
+     * Resolves hidden properties by SQL table name, not class - `toInclude` has a relation's
+     * `schema` and no class reference. Diverges from the class-keyed lookup elsewhere when
+     * `@model({ tableName })` differs from the table name.
+     */
+    resolveHiddenProperties(opts: {
+        schema: TTableSchemaWithId;
+        modelEntry?: TResolvedModelEntry;
+    }): Set<string>;
+    /** Resolves default filter for a schema from MetadataRegistry. */
+    resolveDefaultFilter(opts: {
+        schema: TTableSchemaWithId;
+        modelEntry?: TResolvedModelEntry;
+    }): TFilter | undefined;
+    /** Resolves default row limit for a schema from MetadataRegistry. */
+    resolveDefaultLimit(opts: {
+        schema: TTableSchemaWithId;
+        modelEntry?: TResolvedModelEntry;
+    }): number | undefined;
+    /** Resolves relation configurations for a schema from MetadataRegistry. Memoized per schema. */
+    resolveRelations(opts: {
+        schema: TTableSchemaWithId;
+    }): Record<string, TRelationConfig>;
+    private resolveRelationsUncached;
+    /** Builds Drizzle query options from a filter object. */
+    build<Schema extends TTableSchemaWithId>(opts: {
+        tableName: string;
+        schema: Schema;
+        filter: TFilter<TTableObject<Schema>>;
+    }): TDrizzleQueryOptions;
+    /** Converts fields selection to Drizzle columns format. */
+    toColumns(opts: {
+        fields: TFields;
+    }): Record<string, boolean>;
+    /**
+     * Converts a where clause to a Drizzle SQL condition (supports operators, JSON paths, AND/OR).
+     */
+    toWhere<Schema extends TTableSchemaWithId>(opts: {
+        tableName: string;
+        schema: Schema;
+        where: TWhere<TTableObject<Schema>>;
+    }): SQL | undefined;
+    /**
+     * Conditions contributed by a single where key: a logical
+     * group, a JSON path, a bare value or an operator object.
+     */
+    private buildWhereKeyConditions;
+    /** Converts order strings to Drizzle SQL order expressions (supports JSON paths). */
+    toOrderBy<Schema extends TTableSchemaWithId>(opts: {
+        tableName: string;
+        schema: Schema;
+        order: string[];
+    }): SQL[];
+    /**
+     * Converts include clause to Drizzle 'with' options
+     * with nested filtering and hidden prop exclusion.
+     */
+    toInclude(opts: {
+        include: TInclusion[];
+        relations: {
+            [relationName: string]: TRelationConfig;
+        };
+    }): Record<string, true | TDrizzleQueryOptions>;
+    /**
+     * Column selection with hidden properties removed;
+     * a nullish `columns` means "every schema column".
+     */
+    private omitHiddenColumns;
+    private getColumns;
+    private isPrimitiveValue;
+    /**
+     * Protected, not private: an engine overriding `buildJsonWhereCondition` must tell an operator
+     * object from a bare value, and cannot reach the base's own walk to do it.
+     */
+    protected isOperatorObject(opts: {
+        value: any;
+    }): boolean;
+    /**
+     * Builds a SQL condition for a simple value (null, array, or
+     * equality). Protected for the same reason as `isOperatorObject`: an
+     * overridden `buildJsonWhereCondition` needs the bare-value branch.
+     */
+    protected buildValueCondition(opts: {
+        column: any;
+        value: any;
+    }): SQL;
+    protected buildOperatorConditions(opts: {
+        column: any;
+        value: Record<string, any>;
+    }): SQL[];
+    /**
+     * Negates a nested condition: `not: <operatorObject>` recurses into the
+     * operators, `not: <bareValue>` negates that value equality/array/null condition.
+     */
+    private buildNotCondition;
+    /** Builds SQL conditions for logical groups (AND/OR). */
+    private buildLogicalGroupCondition;
+    protected validateJsonColumn(opts: {
+        key: string;
+        columns: TTableColumns;
+        tableName: string;
+        methodName: string;
+    }): {
+        column: TTableColumns[string];
+        path: string[];
+    };
+    /**
+     * Whether a JSON operand needs the engine's numeric extraction: numeric comparisons, eq/ne/neq
+     * with a number, in/inq/nin with an all-number array. Only picks between the two fragments the
+     * engine passed in, so an engine with already-typed extraction returns false.
+     */
+    protected jsonNeedsNumericCast(opts: {
+        operators: Record<string, any>;
+    }): boolean;
+    /**
+     * Emits the engine JSON extraction for one where key. Abstract because the syntax is
+     * engine-owned: a default would hand the next engine one branch's SQL with no compile error.
+     */
+    protected abstract buildJsonWhereCondition(opts: {
+        key: string;
+        value: any;
+        columns: TTableColumns;
+        tableName: string;
+    }): SQL[];
+    /**
+     * A bare JSON operand IS its operator equivalent - `isOperatorObject` counts an array
+     * as primitive, so `[10, 20]` must take the same cast `{ inq: [10, 20] }` does.
+     */
+    protected toBareJsonOperators(opts: {
+        value: any;
+    }): Record<string, any>;
+    /**
+     * The cast belongs to each OPERATOR, not the object: one object-wide cast misses the operand in
+     * `{ not: { gt: 50 } }` (-> `text > integer`) and over-casts the extraction `like` shares in
+     * `{ gte: 1, like: '%a%' }` (-> `numeric ~~ text`).
+     */
+    protected buildJsonOperatorConditions(opts: {
+        jsonPath: string;
+        safeNumericCast: string;
+        operators: Record<string, any>;
+    }): SQL[];
+    /**
+     * Emits the engine's JSON extraction for one order key.
+     * Abstract for the same reason as `buildJsonWhereCondition`.
+     */
+    protected abstract buildJsonOrderBy(opts: {
+        key: string;
+        direction: TConstValue<typeof Sorts>;
+        columns: TTableColumns;
+        tableName: string;
+    }): SQL;
+}
+export {};
+//# sourceMappingURL=filter.d.ts.map

package/dist/cjs/relational/core/repositories/dialect/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../../../../src/relational/core/repositories/dialect/filter.ts"],"names":[],"mappings":"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"}