linkgress-orm 0.4.35 → 0.4.37

package/dist/query/cte-root-query.d.ts

@@ -0,0 +1,164 @@
+import type { DatabaseClient } from '../database/database-client.interface';
+import { QueryExecutor } from '../entity/db-context';
+import type { OrderDirection } from '../entity/db-context';
+import { Condition, UnwrapSelection } from './conditions';
+import { DbCte } from './cte-builder';
+/**
+ * Join types supported when a CTE is the FROM root.
+ *
+ * Unlike the entity-anchored {@link JoinQueryBuilder} (which only models
+ * `INNER`/`LEFT`), a CTE-rooted query can express the full set of SQL join
+ * flavours — including `FULL OUTER` and `CROSS` — because both sides are
+ * already materialized, independent relations (the CTE bodies). This is what
+ * makes a `spend FULL OUTER JOIN current_tier ON TRUE` shape expressible.
+ */
+export type CteJoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL OUTER' | 'CROSS';
+/**
+ * A constant `TRUE` join predicate, for cross-product joins written as
+ * `… JOIN … ON TRUE`. Equivalent to a `CROSS JOIN` but keeps the `ON`
+ * keyword, which Postgres requires for `FULL OUTER JOIN` (a bare
+ * `FULL OUTER JOIN` with no `ON`/`USING` is a syntax error).
+ *
+ * @example
+ * cteBuilder
+ *   .selectFromCte(spendCte)
+ *   .fullOuterJoin(currentTierCte, onTrue(), (s, t) => ({ ... }))
+ */
+export declare function onTrue(): Condition;
+/**
+ * A single joined CTE step (the right-hand relation + how it is attached).
+ */
+interface CteJoinStep {
+    type: CteJoinType;
+    cte: DbCte<any>;
+    /** ON predicate. Always undefined for `CROSS` joins. */
+    condition?: Condition;
+}
+/**
+ * A query whose FROM root is a {@link DbCte} (rather than an entity table),
+ * joined to one or more further CTEs with any SQL join flavour.
+ *
+ * This complements the entity-anchored `db.<table>.with(...).leftJoin(cte, …)`
+ * path: there the FROM root must be a real table and joins are `INNER`/`LEFT`
+ * only. Here the FROM root is itself a CTE and `FULL OUTER` / `RIGHT` / `CROSS`
+ * joins (and `ON TRUE` predicates) are available — exactly what a
+ * `WITH a AS (…), b AS (…) SELECT … FROM a FULL OUTER JOIN b ON TRUE` shape
+ * needs.
+ *
+ * Parameter ordering: every CTE body's parameters are emitted first, in `WITH`
+ * declaration order (root CTE, then each joined CTE), followed by any `ON`
+ * predicate parameters — so the whole statement keeps a single, sequential
+ * `$1..$n` numbering, matching how the entity-rooted CTE path orders params.
+ *
+ * @typeParam TRootColumns - the column shape of the root CTE
+ * @typeParam TSelection - the projected output row shape (after `.select(...)`)
+ */
+export declare class CteRootQueryBuilder<TRootColumns extends Record<string, any>, TSelection = TRootColumns> {
+    protected rootCte: DbCte<TRootColumns>;
+    protected client: DatabaseClient;
+    protected executor?: QueryExecutor | undefined;
+    private joinSteps;
+    private selector?;
+    private orderByFields;
+    private limitValue?;
+    private offsetValue?;
+    constructor(rootCte: DbCte<TRootColumns>, client: DatabaseClient, executor?: QueryExecutor | undefined);
+    /** Override the per-query timeout (ms). Pass `0` to disable. */
+    withTimeout(timeoutMs: number): this;
+    /** Flag this query as expected to finish within `expectedMs` (ms). */
+    expectedExecutionTime(expectedMs: number): this;
+    /**
+     * `INNER JOIN` another CTE.
+     */
+    innerJoin<TRight extends Record<string, any>>(cte: DbCte<TRight>, condition: Condition): CteJoinedQueryBuilder<TRootColumns, TRight>;
+    /**
+     * `LEFT JOIN` another CTE.
+     */
+    leftJoin<TRight extends Record<string, any>>(cte: DbCte<TRight>, condition: Condition): CteJoinedQueryBuilder<TRootColumns, TRight>;
+    /**
+     * `RIGHT JOIN` another CTE.
+     */
+    rightJoin<TRight extends Record<string, any>>(cte: DbCte<TRight>, condition: Condition): CteJoinedQueryBuilder<TRootColumns, TRight>;
+    /**
+     * `FULL OUTER JOIN` another CTE.
+     *
+     * Postgres requires an `ON`/`USING` clause on a `FULL OUTER JOIN`, so pass a
+     * predicate — use {@link onTrue} for the cross-product (`ON TRUE`) form that
+     * keeps every row of both sides while pairing them up.
+     */
+    fullOuterJoin<TRight extends Record<string, any>>(cte: DbCte<TRight>, condition: Condition): CteJoinedQueryBuilder<TRootColumns, TRight>;
+    /**
+     * `CROSS JOIN` another CTE (cartesian product, no `ON`).
+     */
+    crossJoin<TRight extends Record<string, any>>(cte: DbCte<TRight>): CteJoinedQueryBuilder<TRootColumns, TRight>;
+    /**
+     * Project the root CTE's columns directly (no join).
+     */
+    select<TNewSelection>(selector: (root: TRootColumns) => TNewSelection): CteRootQueryBuilder<TRootColumns, UnwrapSelection<TNewSelection>>;
+    /**
+     * Order the result. Selector returns one or more projected columns (by their
+     * output alias) — `ORDER BY "alias"` — supporting the same shapes as the
+     * other builders (`r => r.col`, `r => [a, b]`, `r => [[a, 'DESC']]`).
+     */
+    orderBy<T>(selector: (row: TSelection) => T): this;
+    orderBy<T>(selector: (row: TSelection) => T[]): this;
+    orderBy<T>(selector: (row: TSelection) => Array<[T, OrderDirection]>): this;
+    /** Limit the result set. */
+    limit(count: number): this;
+    /** Offset the result set. */
+    offset(count: number): this;
+    private addJoin;
+    /** @internal — used by the joined builder to share the build machinery. */
+    _getRootCte(): DbCte<TRootColumns>;
+    /** @internal */
+    _setState(joinSteps: CteJoinStep[], selector: ((...sources: any[]) => any) | undefined, orderByFields: Array<{
+        table: string;
+        field: string;
+        direction: 'ASC' | 'DESC';
+    }>, limitValue: number | undefined, offsetValue: number | undefined): void;
+    /**
+     * Build the SQL + ordered parameter array for this CTE-rooted query.
+     * @internal
+     */
+    buildQuery(): {
+        sql: string;
+        params: any[];
+    };
+    /** Generate the SQL string (for debugging / assertions). */
+    toSql(): string;
+    /** Execute and return all rows. */
+    toList(): Promise<TSelection[]>;
+    /** Execute and return the first row, or null. */
+    first(): Promise<TSelection | null>;
+    /** Evaluate the user selector against fresh CTE FieldRef proxies. */
+    protected evaluateSelection(): Record<string, any>;
+}
+/**
+ * The result of joining a CTE onto a CTE-rooted query. Carries the same build
+ * machinery as {@link CteRootQueryBuilder} but its `.select(...)` selector
+ * receives a FieldRef proxy per source (root first, then each joined CTE in
+ * order), and further joins can still be chained.
+ */
+export declare class CteJoinedQueryBuilder<TRootColumns extends Record<string, any>, TRight extends Record<string, any>, TSelection = TRootColumns & TRight> extends CteRootQueryBuilder<TRootColumns, TSelection> {
+    private _joinSteps;
+    /** @internal */
+    _inheritJoins(steps: CteJoinStep[]): void;
+    /**
+     * Project columns from the root CTE plus every joined CTE. The selector is
+     * called with `(root, ...joined)` FieldRef proxies in FROM declaration order.
+     *
+     * The common single-join case is fully typed: `(root, right)` where `right`
+     * is the joined CTE ({@link TRight}). For 3+ way joins, the additional joined
+     * sources arrive (in FROM order) as loosely-typed rest arguments.
+     */
+    select<TNewSelection>(selector: (root: TRootColumns, right: TRight) => TNewSelection): CteRootQueryBuilder<TRootColumns, UnwrapSelection<TNewSelection>>;
+    select<TNewSelection>(selector: (root: TRootColumns, ...joined: any[]) => TNewSelection): CteRootQueryBuilder<TRootColumns, UnwrapSelection<TNewSelection>>;
+    /**
+     * Typed `fullOuterJoin` that exposes both already-joined sources (root +
+     * first right) to the predicate. (Re-declared so the chained right side keeps
+     * a useful element type rather than collapsing to the base signature.)
+     */
+    fullOuterJoin<TThird extends Record<string, any>>(cte: DbCte<TThird>, condition: Condition): CteJoinedQueryBuilder<TRootColumns, TThird>;
+}
+export {};
+//# sourceMappingURL=cte-root-query.d.ts.map

package/dist/query/cte-root-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cte-root-query.d.ts","sourceRoot":"","sources":["../../src/query/cte-root-query.ts"],"names":[],"mappings":"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"}

package/dist/query/cte-root-query.js

@@ -0,0 +1,398 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CteJoinedQueryBuilder = exports.CteRootQueryBuilder = void 0;
+exports.onTrue = onTrue;
+const db_context_1 = require("../entity/db-context");
+const conditions_1 = require("./conditions");
+const query_utils_1 = require("./query-utils");
+/** SQL keyword emitted for each {@link CteJoinType}. */
+const CTE_JOIN_SQL = {
+    INNER: 'INNER JOIN',
+    LEFT: 'LEFT JOIN',
+    RIGHT: 'RIGHT JOIN',
+    'FULL OUTER': 'FULL OUTER JOIN',
+    CROSS: 'CROSS JOIN',
+};
+/**
+ * A constant `TRUE` join predicate, for cross-product joins written as
+ * `… JOIN … ON TRUE`. Equivalent to a `CROSS JOIN` but keeps the `ON`
+ * keyword, which Postgres requires for `FULL OUTER JOIN` (a bare
+ * `FULL OUTER JOIN` with no `ON`/`USING` is a syntax error).
+ *
+ * @example
+ * cteBuilder
+ *   .selectFromCte(spendCte)
+ *   .fullOuterJoin(currentTierCte, onTrue(), (s, t) => ({ ... }))
+ */
+function onTrue() {
+    return (0, conditions_1.sql) `TRUE`;
+}
+/**
+ * Build a mock row that yields {@link FieldRef}s for a CTE's columns, qualified
+ * with the CTE's own name as the table alias. Mirrors
+ * `SelectQueryBuilder.createMockRowForCte` so column mappers / aggregation-array
+ * markers carried on the CTE's `selectionMetadata` survive into the projection.
+ */
+function createCteFieldRefProxy(cte) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop === 'symbol') {
+                return undefined;
+            }
+            if (cte.selectionMetadata && prop in cte.selectionMetadata) {
+                const value = cte.selectionMetadata[prop];
+                // SqlFragment / column with a fromDriver mapper — preserve it so the
+                // projection re-applies the mapper to the joined column.
+                if (typeof value === 'object' && value !== null && typeof value.getMapper === 'function') {
+                    return {
+                        __fieldName: prop,
+                        __dbColumnName: prop,
+                        __tableAlias: cte.name,
+                        getMapper: () => value.getMapper(),
+                    };
+                }
+                // CTE aggregation-array marker (json_agg column) — preserve the inner
+                // metadata so nested items can be mapped.
+                if (typeof value === 'object' && value !== null && '__isAggregationArray' in value && value.__isAggregationArray) {
+                    return {
+                        __fieldName: prop,
+                        __dbColumnName: prop,
+                        __tableAlias: cte.name,
+                        __isAggregationArray: true,
+                        __innerSelectionMetadata: value.__innerSelectionMetadata,
+                    };
+                }
+            }
+            return {
+                __fieldName: prop,
+                __dbColumnName: prop,
+                __tableAlias: cte.name,
+            };
+        },
+        has() {
+            return true;
+        },
+        ownKeys() {
+            return cte.columnDefs ? Object.keys(cte.columnDefs) : [];
+        },
+        getOwnPropertyDescriptor() {
+            return { enumerable: true, configurable: true };
+        },
+    });
+}
+const NUMERIC_REGEX = /^-?\d+(\.\d+)?$/;
+/**
+ * A query whose FROM root is a {@link DbCte} (rather than an entity table),
+ * joined to one or more further CTEs with any SQL join flavour.
+ *
+ * This complements the entity-anchored `db.<table>.with(...).leftJoin(cte, …)`
+ * path: there the FROM root must be a real table and joins are `INNER`/`LEFT`
+ * only. Here the FROM root is itself a CTE and `FULL OUTER` / `RIGHT` / `CROSS`
+ * joins (and `ON TRUE` predicates) are available — exactly what a
+ * `WITH a AS (…), b AS (…) SELECT … FROM a FULL OUTER JOIN b ON TRUE` shape
+ * needs.
+ *
+ * Parameter ordering: every CTE body's parameters are emitted first, in `WITH`
+ * declaration order (root CTE, then each joined CTE), followed by any `ON`
+ * predicate parameters — so the whole statement keeps a single, sequential
+ * `$1..$n` numbering, matching how the entity-rooted CTE path orders params.
+ *
+ * @typeParam TRootColumns - the column shape of the root CTE
+ * @typeParam TSelection - the projected output row shape (after `.select(...)`)
+ */
+class CteRootQueryBuilder {
+    constructor(rootCte, client, executor) {
+        this.rootCte = rootCte;
+        this.client = client;
+        this.executor = executor;
+        this.joinSteps = [];
+        this.orderByFields = [];
+    }
+    /** Override the per-query timeout (ms). Pass `0` to disable. */
+    withTimeout(timeoutMs) {
+        this.executor = this.executor
+            ? this.executor.withTimeout(timeoutMs)
+            : new db_context_1.QueryExecutor(this.client, undefined, timeoutMs);
+        return this;
+    }
+    /** Flag this query as expected to finish within `expectedMs` (ms). */
+    expectedExecutionTime(expectedMs) {
+        this.executor = this.executor
+            ? this.executor.withExpectedExecutionTime(expectedMs)
+            : new db_context_1.QueryExecutor(this.client, undefined, undefined, expectedMs);
+        return this;
+    }
+    /**
+     * `INNER JOIN` another CTE.
+     */
+    innerJoin(cte, condition) {
+        return this.addJoin('INNER', cte, condition);
+    }
+    /**
+     * `LEFT JOIN` another CTE.
+     */
+    leftJoin(cte, condition) {
+        return this.addJoin('LEFT', cte, condition);
+    }
+    /**
+     * `RIGHT JOIN` another CTE.
+     */
+    rightJoin(cte, condition) {
+        return this.addJoin('RIGHT', cte, condition);
+    }
+    /**
+     * `FULL OUTER JOIN` another CTE.
+     *
+     * Postgres requires an `ON`/`USING` clause on a `FULL OUTER JOIN`, so pass a
+     * predicate — use {@link onTrue} for the cross-product (`ON TRUE`) form that
+     * keeps every row of both sides while pairing them up.
+     */
+    fullOuterJoin(cte, condition) {
+        return this.addJoin('FULL OUTER', cte, condition);
+    }
+    /**
+     * `CROSS JOIN` another CTE (cartesian product, no `ON`).
+     */
+    crossJoin(cte) {
+        return this.addJoin('CROSS', cte, undefined);
+    }
+    /**
+     * Project the root CTE's columns directly (no join).
+     */
+    select(selector) {
+        const next = new CteRootQueryBuilder(this.rootCte, this.client, this.executor);
+        next.joinSteps = this.joinSteps;
+        next.selector = selector;
+        next.orderByFields = this.orderByFields;
+        next.limitValue = this.limitValue;
+        next.offsetValue = this.offsetValue;
+        return next;
+    }
+    orderBy(selector) {
+        const mockRow = new Proxy({}, {
+            get: (_t, prop) => {
+                if (typeof prop === 'symbol') {
+                    return undefined;
+                }
+                return { __fieldName: prop, __dbColumnName: prop };
+            },
+            has: () => true,
+        });
+        const result = selector(mockRow);
+        this.orderByFields = [];
+        (0, query_utils_1.parseOrderBy)(result, this.orderByFields, undefined, () => '');
+        return this;
+    }
+    /** Limit the result set. */
+    limit(count) {
+        this.limitValue = count;
+        return this;
+    }
+    /** Offset the result set. */
+    offset(count) {
+        this.offsetValue = count;
+        return this;
+    }
+    addJoin(type, cte, condition) {
+        const next = new CteJoinedQueryBuilder(this.rootCte, this.client, this.executor);
+        next._inheritJoins([...this.joinSteps, { type, cte, condition }]);
+        return next;
+    }
+    /** @internal — used by the joined builder to share the build machinery. */
+    _getRootCte() {
+        return this.rootCte;
+    }
+    /** @internal */
+    _setState(joinSteps, selector, orderByFields, limitValue, offsetValue) {
+        this.joinSteps = joinSteps;
+        this.selector = selector;
+        this.orderByFields = orderByFields;
+        this.limitValue = limitValue;
+        this.offsetValue = offsetValue;
+    }
+    /**
+     * Build the SQL + ordered parameter array for this CTE-rooted query.
+     * @internal
+     */
+    buildQuery() {
+        if (!this.selector) {
+            throw new Error('A selection is required. Call .select(...) before executing a CTE-rooted query.');
+        }
+        const params = [];
+        // Parameters of every CTE body come first, in WITH declaration order
+        // (root, then each join). The bodies already carry sequential `$N`
+        // placeholders assigned by DbCteBuilder, so just concatenate their params.
+        params.push(...this.rootCte.params);
+        for (const step of this.joinSteps) {
+            params.push(...step.cte.params);
+        }
+        // The ON predicates are appended after all CTE-body params. Their next free
+        // placeholder index is therefore (paramsSoFar + 1).
+        const ctx = {
+            paramCounter: params.length + 1,
+            params,
+        };
+        // FROM root
+        let fromClause = `FROM "${this.rootCte.name}"`;
+        for (const step of this.joinSteps) {
+            const keyword = CTE_JOIN_SQL[step.type];
+            if (step.type === 'CROSS') {
+                fromClause += `\n${keyword} "${step.cte.name}"`;
+            }
+            else {
+                const condBuilder = new conditions_1.ConditionBuilder();
+                const { sql: condSql, params: condParams, paramCounter } = condBuilder.build(step.condition, ctx.paramCounter);
+                ctx.paramCounter = paramCounter;
+                ctx.params.push(...condParams);
+                fromClause += `\n${keyword} "${step.cte.name}" ON ${condSql}`;
+            }
+        }
+        // Build the WITH clause from every referenced CTE, in declaration order.
+        const cteDecls = [`"${this.rootCte.name}" AS (${this.rootCte.query})`];
+        for (const step of this.joinSteps) {
+            cteDecls.push(`"${step.cte.name}" AS (${step.cte.query})`);
+        }
+        // Build SELECT from the projection (root + joined CTE FieldRefs).
+        const selection = this.evaluateSelection();
+        const selectParts = buildSelectParts(selection, ctx, this.rootCte.name);
+        let orderByClause = '';
+        if (this.orderByFields.length > 0) {
+            const orderParts = this.orderByFields.map(({ field, direction }) => `"${field}" ${direction}`);
+            orderByClause = `\nORDER BY ${orderParts.join(', ')}`;
+        }
+        let limitClause = '';
+        if (this.limitValue !== undefined) {
+            limitClause = `\nLIMIT ${this.limitValue}`;
+        }
+        if (this.offsetValue !== undefined) {
+            limitClause += `\nOFFSET ${this.offsetValue}`;
+        }
+        const sqlText = `WITH ${cteDecls.join(', ')}\n` +
+            `SELECT ${selectParts.join(', ')}\n${fromClause}${orderByClause}${limitClause}`;
+        return { sql: sqlText, params: ctx.params };
+    }
+    /** Generate the SQL string (for debugging / assertions). */
+    toSql() {
+        return this.buildQuery().sql;
+    }
+    /** Execute and return all rows. */
+    async toList() {
+        const { sql: sqlText, params } = this.buildQuery();
+        const result = this.executor
+            ? await this.executor.query(sqlText, params)
+            : await this.client.query(sqlText, params);
+        const selection = this.evaluateSelection();
+        return transformRows(result.rows, selection);
+    }
+    /** Execute and return the first row, or null. */
+    async first() {
+        const results = await this.limit(1).toList();
+        return results.length > 0 ? results[0] : null;
+    }
+    /** Evaluate the user selector against fresh CTE FieldRef proxies. */
+    evaluateSelection() {
+        const rootMock = createCteFieldRefProxy(this.rootCte);
+        const joinMocks = this.joinSteps.map(step => createCteFieldRefProxy(step.cte));
+        return this.selector(rootMock, ...joinMocks);
+    }
+}
+exports.CteRootQueryBuilder = CteRootQueryBuilder;
+/**
+ * The result of joining a CTE onto a CTE-rooted query. Carries the same build
+ * machinery as {@link CteRootQueryBuilder} but its `.select(...)` selector
+ * receives a FieldRef proxy per source (root first, then each joined CTE in
+ * order), and further joins can still be chained.
+ */
+class CteJoinedQueryBuilder extends CteRootQueryBuilder {
+    constructor() {
+        super(...arguments);
+        this._joinSteps = [];
+    }
+    /** @internal */
+    _inheritJoins(steps) {
+        this._joinSteps = steps;
+        this._setState(steps, undefined, [], undefined, undefined);
+    }
+    select(selector) {
+        const next = new CteRootQueryBuilder(this._getRootCte(), this.client, this.executor);
+        next._setState(this._joinSteps, selector, [], undefined, undefined);
+        return next;
+    }
+    /**
+     * Typed `fullOuterJoin` that exposes both already-joined sources (root +
+     * first right) to the predicate. (Re-declared so the chained right side keeps
+     * a useful element type rather than collapsing to the base signature.)
+     */
+    fullOuterJoin(cte, condition) {
+        return super.fullOuterJoin(cte, condition);
+    }
+}
+exports.CteJoinedQueryBuilder = CteJoinedQueryBuilder;
+/**
+ * Build SELECT list fragments from a projection object whose leaves are
+ * FieldRefs (qualified with their CTE/table alias), SqlFragments, or literals.
+ */
+function buildSelectParts(selection, ctx, defaultAlias) {
+    const parts = [];
+    for (const [key, value] of Object.entries(selection)) {
+        if (value instanceof conditions_1.SqlFragment) {
+            const fragmentSql = value.buildSql(ctx);
+            parts.push(`${fragmentSql} as "${key}"`);
+        }
+        else if (typeof value === 'object' && value !== null && '__dbColumnName' in value) {
+            const alias = value.__tableAlias || defaultAlias;
+            parts.push(`"${alias}"."${value.__dbColumnName}" as "${key}"`);
+        }
+        else if (typeof value === 'string') {
+            // Bare column name string — qualify with the root alias.
+            parts.push(`"${defaultAlias}"."${value}" as "${key}"`);
+        }
+        else {
+            // Literal value
+            ctx.params.push(value);
+            parts.push(`$${ctx.paramCounter++} as "${key}"`);
+        }
+    }
+    return parts;
+}
+/**
+ * Transform driver rows into the projected shape, re-applying any column /
+ * SqlFragment fromDriver mappers and coercing Postgres numeric strings to
+ * numbers. NULLs are preserved as `null` (faithful to the SQL — a CTE-rooted
+ * projection mirrors raw column output, unlike the entity path which maps
+ * absent columns to `undefined`).
+ */
+function transformRows(rows, selection) {
+    // Pre-analyze each selected field once.
+    const fields = [];
+    for (const [key, value] of Object.entries(selection)) {
+        let mapper;
+        if (value && typeof value === 'object' && typeof value.getMapper === 'function') {
+            let m = value.getMapper();
+            if (m && typeof m.getType === 'function') {
+                m = m.getType();
+            }
+            if (m && typeof m.fromDriver === 'function') {
+                mapper = m;
+            }
+        }
+        fields.push({ key, mapper });
+    }
+    return rows.map(row => {
+        const out = {};
+        for (const { key, mapper } of fields) {
+            const raw = row[key];
+            if (mapper) {
+                out[key] = mapper.fromDriver(raw);
+            }
+            else if (typeof raw === 'string' && NUMERIC_REGEX.test(raw)) {
+                out[key] = +raw;
+            }
+            else {
+                out[key] = raw;
+            }
+        }
+        return out;
+    });
+}
+//# sourceMappingURL=cte-root-query.js.map

package/dist/query/cte-root-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cte-root-query.js","sourceRoot":"","sources":["../../src/query/cte-root-query.ts"],"names":[],"mappings":";;;AA8CA,wBAEC;AA/CD,qDAAqD;AAErD,6CAQsB;AAEtB,+CAA6C;AAa7C,wDAAwD;AACxD,MAAM,YAAY,GAAgC;IAChD,KAAK,EAAE,YAAY;IACnB,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,YAAY,EAAE,iBAAiB;IAC/B,KAAK,EAAE,YAAY;CACpB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,SAAgB,MAAM;IACpB,OAAO,IAAA,gBAAG,EAAS,MAAM,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAAuC,GAAoB;IACxF,OAAO,IAAI,KAAK,CAAC,EAAS,EAAE;QAC1B,GAAG,CAAC,OAAO,EAAE,IAAqB;YAChC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,GAAG,CAAC,iBAAiB,IAAI,IAAI,IAAI,GAAG,CAAC,iBAAiB,EAAE,CAAC;gBAC3D,MAAM,KAAK,GAAG,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAE1C,qEAAqE;gBACrE,yDAAyD;gBACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAAa,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;oBAClG,OAAO;wBACL,WAAW,EAAE,IAAI;wBACjB,cAAc,EAAE,IAAI;wBACpB,YAAY,EAAE,GAAG,CAAC,IAAI;wBACtB,SAAS,EAAE,GAAG,EAAE,CAAE,KAAa,CAAC,SAAS,EAAE;qBAC5C,CAAC;gBACJ,CAAC;gBAED,sEAAsE;gBACtE,0CAA0C;gBAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,sBAAsB,IAAI,KAAK,IAAK,KAAa,CAAC,oBAAoB,EAAE,CAAC;oBAC1H,OAAO;wBACL,WAAW,EAAE,IAAI;wBACjB,cAAc,EAAE,IAAI;wBACpB,YAAY,EAAE,GAAG,CAAC,IAAI;wBACtB,oBAAoB,EAAE,IAAI;wBAC1B,wBAAwB,EAAG,KAAa,CAAC,wBAAwB;qBAClE,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,OAAO;gBACL,WAAW,EAAE,IAAI;gBACjB,cAAc,EAAE,IAAI;gBACpB,YAAY,EAAE,GAAG,CAAC,IAAI;aACX,CAAC;QAChB,CAAC;QACD,GAAG;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAoB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,CAAC;QACD,wBAAwB;YACtB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAClD,CAAC;KACF,CAAa,CAAC;AACjB,CAAC;AAED,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAYxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,mBAAmB;IAO9B,YACY,OAA4B,EAC5B,MAAsB,EACtB,QAAwB;QAFxB,YAAO,GAAP,OAAO,CAAqB;QAC5B,WAAM,GAAN,MAAM,CAAgB;QACtB,aAAQ,GAAR,QAAQ,CAAgB;QAT5B,cAAS,GAAkB,EAAE,CAAC;QAE9B,kBAAa,GAAuE,EAAE,CAAC;IAQ5F,CAAC;IAEJ,gEAAgE;IAChE,WAAW,CAAC,SAAiB;QAC3B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ;YAC3B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC;YACtC,CAAC,CAAC,IAAI,0BAAa,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sEAAsE;IACtE,qBAAqB,CAAC,UAAkB;QACtC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ;YAC3B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,yBAAyB,CAAC,UAAU,CAAC;YACrD,CAAC,CAAC,IAAI,0BAAa,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CACP,GAAkB,EAClB,SAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,QAAQ,CACN,GAAkB,EAClB,SAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,SAAS,CACP,GAAkB,EAClB,SAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CACX,GAAkB,EAClB,SAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,SAAS,CACP,GAAkB;QAElB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,MAAM,CACJ,QAA+C;QAE/C,MAAM,IAAI,GAAG,IAAI,mBAAmB,CAClC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,QAAQ,CACd,CAAC;QACF,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,QAAe,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAUD,OAAO,CAAI,QAAmE;QAC5E,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,EAAS,EAAE;YACnC,GAAG,EAAE,CAAC,EAAE,EAAE,IAAqB,EAAE,EAAE;gBACjC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC7B,OAAO,SAAS,CAAC;gBACnB,CAAC;gBACD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAc,CAAC;YACjE,CAAC;YACD,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI;SAChB,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAqB,CAAC,CAAC;QAC/C,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,IAAA,0BAAY,EAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,KAAa;QACjB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6BAA6B;IAC7B,MAAM,CAAC,KAAa;QAClB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,OAAO,CACb,IAAiB,EACjB,GAAkB,EAClB,SAAqB;QAErB,MAAM,IAAI,GAAG,IAAI,qBAAqB,CACpC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,QAAQ,CACd,CAAC;QACF,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2EAA2E;IAC3E,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,gBAAgB;IAChB,SAAS,CACP,SAAwB,EACxB,QAAkD,EAClD,aAAiF,EACjF,UAA8B,EAC9B,WAA+B;QAE/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAC;QACrG,CAAC;QAED,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,qEAAqE;QACrE,mEAAmE;QACnE,2EAA2E;QAC3E,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,4EAA4E;QAC5E,oDAAoD;QACpD,MAAM,GAAG,GAAoB;YAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC;YAC/B,MAAM;SACP,CAAC;QAEF,YAAY;QACZ,IAAI,UAAU,GAAG,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;QAC/C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAC1B,UAAU,IAAI,KAAK,OAAO,KAAK,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,MAAM,WAAW,GAAG,IAAI,6BAAgB,EAAE,CAAC;gBAC3C,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,KAAK,CAC1E,IAAI,CAAC,SAAU,EACf,GAAG,CAAC,YAAY,CACjB,CAAC;gBACF,GAAG,CAAC,YAAY,GAAG,YAAY,CAAC;gBAChC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;gBAC/B,UAAU,IAAI,KAAK,OAAO,KAAK,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,OAAO,EAAE,CAAC;YAChE,CAAC;QACH,CAAC;QAED,yEAAyE;QACzE,MAAM,QAAQ,GAAa,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,SAAS,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC;QACjF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;QAC7D,CAAC;QAED,kEAAkE;QAClE,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3C,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAExE,IAAI,aAAa,GAAG,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC,CAAC;YAC/F,aAAa,GAAG,cAAc,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxD,CAAC;QAED,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,WAAW,GAAG,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC;QAC7C,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnC,WAAW,IAAI,YAAY,IAAI,CAAC,WAAW,EAAE,CAAC;QAChD,CAAC;QAED,MAAM,OAAO,GACX,QAAQ,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC/B,UAAU,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,UAAU,GAAG,aAAa,GAAG,WAAW,EAAE,CAAC;QAElF,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAC9C,CAAC;IAED,4DAA4D;IAC5D,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC;IAC/B,CAAC;IAED,mCAAmC;IACnC,KAAK,CAAC,MAAM;QACV,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ;YAC1B,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC;YAC5C,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAE7C,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3C,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAiB,CAAC;IAC/D,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IAED,qEAAqE;IAC3D,iBAAiB;QACzB,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC,QAAS,CAAC,QAAQ,EAAE,GAAG,SAAS,CAAC,CAAC;IAChD,CAAC;CACF;AAjRD,kDAiRC;AAED;;;;;GAKG;AACH,MAAa,qBAIX,SAAQ,mBAA6C;IAJvD;;QAKU,eAAU,GAAkB,EAAE,CAAC;IA6CzC,CAAC;IA3CC,gBAAgB;IAChB,aAAa,CAAC,KAAoB;QAChC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAC7D,CAAC;IAgBD,MAAM,CACJ,QAAiE;QAEjE,MAAM,IAAI,GAAG,IAAI,mBAAmB,CAClC,IAAI,CAAC,WAAW,EAAE,EAClB,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,QAAQ,CACd,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,QAAe,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,aAAa,CACX,GAAkB,EAClB,SAAoB;QAEpB,OAAO,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAQ,CAAC;IACpD,CAAC;CACF;AAlDD,sDAkDC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CACvB,SAA8B,EAC9B,GAAoB,EACpB,YAAoB;IAEpB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,KAAK,YAAY,wBAAW,EAAE,CAAC;YACjC,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,QAAQ,GAAG,GAAG,CAAC,CAAC;QAC3C,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,gBAAgB,IAAI,KAAK,EAAE,CAAC;YACpF,MAAM,KAAK,GAAI,KAAa,CAAC,YAAY,IAAI,YAAY,CAAC;YAC1D,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,MAAO,KAAa,CAAC,cAAc,SAAS,GAAG,GAAG,CAAC,CAAC;QAC1E,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,yDAAyD;YACzD,KAAK,CAAC,IAAI,CAAC,IAAI,YAAY,MAAM,KAAK,SAAS,GAAG,GAAG,CAAC,CAAC;QACzD,CAAC;aAAM,CAAC;YACN,gBAAgB;YAChB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,QAAQ,GAAG,GAAG,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,IAAW,EAAE,SAA8B;IAChE,wCAAwC;IACxC,MAAM,MAAM,GAAqE,EAAE,CAAC;IACpF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,MAAmD,CAAC;QACxD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAAa,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;YACzF,IAAI,CAAC,GAAI,KAAa,CAAC,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBACzC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;YAClB,CAAC;YACD,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;gBAC5C,MAAM,GAAG,CAAC,CAAC;YACb,CAAC;QACH,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;QACpB,MAAM,GAAG,GAAQ,EAAE,CAAC;QACpB,KAAK,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACrC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YACpC,CAAC;iBAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9D,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YACjB,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/schema/table-builder.d.ts

@@ -49,6 +49,37 @@ export interface IndexDefinition {
      */
     requiresSearchNormalize?: boolean;
 }
+/**
+ * PostgreSQL declarative-partitioning strategy.
+ * - `'range'` — partition by ranges of the key (e.g. dates).
+ * - `'list'`  — partition by an explicit list of key values.
+ * - `'hash'`  — partition by hash of the key (even distribution).
+ */
+export type PartitionStrategy = 'range' | 'list' | 'hash';
+/**
+ * Declarative table-partitioning configuration — describes the parent table's
+ * `PARTITION BY <strategy> (<key>)` clause. Child partitions (`PARTITION OF ...
+ * FOR VALUES ...`) are managed separately (they are typically created/rotated at
+ * runtime), so they are not part of this declaration.
+ *
+ * PostgreSQL requires every partition-key column to be included in the table's
+ * PRIMARY KEY / UNIQUE constraints.
+ */
+export interface PartitioningConfig {
+    /** Partitioning strategy: RANGE, LIST, or HASH. */
+    strategy: PartitionStrategy;
+    /**
+     * Partition-key columns (database column names). Mutually exclusive with
+     * {@link expression}.
+     */
+    columns?: string[];
+    /**
+     * Raw partition-key expression — the contents of the `PARTITION BY <strategy>
+     * (...)` parentheses, e.g. `date_trunc('month', created_at)`. Mutually
+     * exclusive with {@link columns}.
+     */
+    expression?: string;
+}
 /**
  * Foreign key action type
  */
@@ -87,6 +118,8 @@ export interface TableSchema<TColumns extends Record<string, ColumnBuilder> = an
     relations: Record<string, RelationConfig>;
     indexes: IndexDefinition[];
     foreignKeys: ForeignKeyConstraint[];
+    /** Declarative partitioning config for this table (parent `PARTITION BY`). */
+    partitioning?: PartitioningConfig;
     /**
      * Performance optimization: Pre-computed map of property names to database column names
      * Avoids repeated .build().name calls during query building
@@ -146,8 +179,15 @@ export declare class TableBuilder<TSchema extends SchemaDefinition = any> {
     private relationDefs;
     private indexDefs;
     private foreignKeyDefs;
+    private partitioningDef?;
     constructor(name: string, schema: TSchema, indexes?: IndexDefinition[], foreignKeys?: ForeignKeyConstraint[], schemaName?: string);
     private _cachedSchema?;
+    /**
+     * Configure declarative table partitioning (the parent `PARTITION BY` clause).
+     * @example
+     * builder.partitionBy({ strategy: 'range', columns: ['created_at'] });
+     */
+    partitionBy(config: PartitioningConfig): this;
     /**
      * Build the final table schema
      */