@tablecraft/engine 0.1.0-beta.1

package/dist/src/core/filterGroupBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filterGroupBuilder.js","sourceRoot":"","sources":["../../../src/core/filterGroupBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,eAAe,EACf,GAAG,EACH,EAAE,GACH,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,MAAM,OAAO,kBAAkB;IACT;IAApB,YAAoB,MAA+B;QAA/B,WAAM,GAAN,MAAM,CAAyB;IAAG,CAAC;IAEvD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,UAA4B,EAAE,MAAmB;QACrD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAU,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,WAA+B,EAAE,MAAmB;QAC3D,IAAI,CAAC,WAAW,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAE1C,MAAM,KAAK,GAAU,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACrC,IAAI,GAAG;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IACvB,CAAC;IAEO,OAAO,CAAC,IAAsB,EAAE,OAA+B;QACrE,gCAAgC;QAChC,IAAI,OAAO,IAAI,IAAI,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAuB,EAAE,OAAO,CAAC,CAAC;QACjE,CAAC;QAED,4BAA4B;QAC5B,MAAM,KAAK,GAAG,IAA8D,CAAC;QAC7E,MAAM,KAAK,GAAU,EAAE,CAAC;QAExB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC9C,IAAI,QAAQ;gBAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAExC,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC5D,CAAC;IAEO,gBAAgB,CACtB,SAA0B,EAC1B,OAA+B;QAE/B,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO,aAAa,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACjE,CAAC;CACF"}

package/dist/src/core/groupByBuilder.d.ts

@@ -0,0 +1,23 @@
+import { Column, SQL } from 'drizzle-orm';
+import { TableConfig } from '../types/table';
+export declare class GroupByBuilder {
+    private schema;
+    constructor(schema: Record<string, unknown>);
+    /**
+     * Returns the columns to GROUP BY.
+     */
+    buildGroupByColumns(config: TableConfig): Column[] | undefined;
+    /**
+     * Builds the SELECT for a grouped query:
+     * group-by fields + aggregation expressions.
+     */
+    buildGroupedSelect(config: TableConfig): Record<string, SQL | Column> | undefined;
+    /**
+     * Builds the HAVING clause.
+     * HAVING references aggregation expressions, not aliases.
+     */
+    buildHaving(config: TableConfig): SQL | undefined;
+    private buildAggExpression;
+    private buildComparison;
+}
+//# sourceMappingURL=groupByBuilder.d.ts.map

package/dist/src/core/groupByBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupByBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/groupByBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EACN,GAAG,EASJ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,qBAAa,cAAc;IACb,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEnD;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,GAAG,SAAS;IAiB9D;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,CAAC,GAAG,SAAS;IAkCjF;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,GAAG,SAAS;IA+BjD,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,eAAe;CAWxB"}

package/dist/src/core/groupByBuilder.js

@@ -0,0 +1,127 @@
+import { sql, getTableColumns, and, count, sum, avg, min, max, } from 'drizzle-orm';
+export class GroupByBuilder {
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+    }
+    /**
+     * Returns the columns to GROUP BY.
+     */
+    buildGroupByColumns(config) {
+        if (!config.groupBy?.fields?.length)
+            return undefined;
+        const table = this.schema[config.base];
+        if (!table)
+            return undefined;
+        const columns = getTableColumns(table);
+        const result = [];
+        for (const field of config.groupBy.fields) {
+            const col = columns[field];
+            if (col)
+                result.push(col);
+        }
+        return result.length > 0 ? result : undefined;
+    }
+    /**
+     * Builds the SELECT for a grouped query:
+     * group-by fields + aggregation expressions.
+     */
+    buildGroupedSelect(config) {
+        if (!config.groupBy?.fields?.length)
+            return undefined;
+        const table = this.schema[config.base];
+        if (!table)
+            return undefined;
+        const columns = getTableColumns(table);
+        const selection = {};
+        // Add grouped fields
+        for (const field of config.groupBy.fields) {
+            const col = columns[field];
+            if (col)
+                selection[field] = col;
+        }
+        // Add aggregations
+        if (config.aggregations) {
+            for (const agg of config.aggregations) {
+                const col = columns[agg.field];
+                if (!col)
+                    continue;
+                switch (agg.type) {
+                    case 'count':
+                        selection[agg.alias] = count(col);
+                        break;
+                    case 'sum':
+                        selection[agg.alias] = sum(col);
+                        break;
+                    case 'avg':
+                        selection[agg.alias] = avg(col);
+                        break;
+                    case 'min':
+                        selection[agg.alias] = min(col);
+                        break;
+                    case 'max':
+                        selection[agg.alias] = max(col);
+                        break;
+                }
+            }
+        }
+        return Object.keys(selection).length > 0 ? selection : undefined;
+    }
+    /**
+     * Builds the HAVING clause.
+     * HAVING references aggregation expressions, not aliases.
+     */
+    buildHaving(config) {
+        if (!config.groupBy?.having?.length)
+            return undefined;
+        if (!config.aggregations?.length)
+            return undefined;
+        const table = this.schema[config.base];
+        if (!table)
+            return undefined;
+        const columns = getTableColumns(table);
+        const parts = [];
+        for (const having of config.groupBy.having) {
+            // Find the aggregation config by alias
+            const agg = config.aggregations.find((a) => a.alias === having.alias);
+            if (!agg)
+                continue;
+            const col = columns[agg.field];
+            if (!col)
+                continue;
+            // Build the aggregation expression
+            const aggExpr = this.buildAggExpression(agg.type, col);
+            if (!aggExpr)
+                continue;
+            // Build the comparison
+            const comparison = this.buildComparison(aggExpr, having.operator, having.value);
+            if (comparison)
+                parts.push(comparison);
+        }
+        if (parts.length === 0)
+            return undefined;
+        return and(...parts);
+    }
+    buildAggExpression(type, col) {
+        switch (type) {
+            case 'count': return sql `count(${col})`;
+            case 'sum': return sql `sum(${col})`;
+            case 'avg': return sql `avg(${col})`;
+            case 'min': return sql `min(${col})`;
+            case 'max': return sql `max(${col})`;
+            default: return undefined;
+        }
+    }
+    buildComparison(expr, operator, value) {
+        switch (operator) {
+            case 'eq': return sql `${expr} = ${value}`;
+            case 'neq': return sql `${expr} != ${value}`;
+            case 'gt': return sql `${expr} > ${value}`;
+            case 'gte': return sql `${expr} >= ${value}`;
+            case 'lt': return sql `${expr} < ${value}`;
+            case 'lte': return sql `${expr} <= ${value}`;
+            default: return undefined;
+        }
+    }
+}
+//# sourceMappingURL=groupByBuilder.js.map

package/dist/src/core/groupByBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupByBuilder.js","sourceRoot":"","sources":["../../../src/core/groupByBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,GAAG,EACH,eAAe,EACf,GAAG,EACH,KAAK,EACL,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,GACJ,MAAM,aAAa,CAAC;AAGrB,MAAM,OAAO,cAAc;IACL;IAApB,YAAoB,MAA+B;QAA/B,WAAM,GAAN,MAAM,CAAyB;IAAG,CAAC;IAEvD;;OAEG;IACH,mBAAmB,CAAC,MAAmB;QACrC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM;YAAE,OAAO,SAAS,CAAC;QAEtD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAU,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,GAAG;gBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,CAAC;IAED;;;OAGG;IACH,kBAAkB,CAAC,MAAmB;QACpC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM;YAAE,OAAO,SAAS,CAAC;QAEtD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAU,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,SAAS,GAAiC,EAAE,CAAC;QAEnD,qBAAqB;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,GAAG;gBAAE,SAAS,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;QAClC,CAAC;QAED,mBAAmB;QACnB,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;gBACtC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAC/B,IAAI,CAAC,GAAG;oBAAE,SAAS;gBAEnB,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;oBACjB,KAAK,OAAO;wBAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;wBAAC,MAAM;oBACvD,KAAK,KAAK;wBAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;wBAAC,MAAM;oBACnD,KAAK,KAAK;wBAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;wBAAC,MAAM;oBACnD,KAAK,KAAK;wBAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;wBAAC,MAAM;oBACnD,KAAK,KAAK;wBAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;wBAAC,MAAM;gBACrD,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,MAAmB;QAC7B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM;YAAE,OAAO,SAAS,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM;YAAE,OAAO,SAAS,CAAC;QAEnD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAU,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,KAAK,GAAU,EAAE,CAAC;QAExB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC3C,uCAAuC;YACvC,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;YACtE,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,mCAAmC;YACnC,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACvD,IAAI,CAAC,OAAO;gBAAE,SAAS;YAEvB,uBAAuB;YACvB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YAChF,IAAI,UAAU;gBAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzC,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACzC,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IACvB,CAAC;IAEO,kBAAkB,CAAC,IAAY,EAAE,GAAW;QAClD,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,OAAO,CAAC,CAAC,OAAO,GAAG,CAAA,SAAS,GAAG,GAAG,CAAC;YACxC,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,OAAO,GAAG,GAAG,CAAC;YACpC,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,OAAO,GAAG,GAAG,CAAC;YACpC,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,OAAO,GAAG,GAAG,CAAC;YACpC,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,OAAO,GAAG,GAAG,CAAC;YACpC,OAAO,CAAC,CAAC,OAAO,SAAS,CAAC;QAC5B,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,IAAS,EAAE,QAAgB,EAAE,KAAc;QACjE,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,IAAI,CAAC,CAAC,OAAO,GAAG,CAAA,GAAG,IAAI,MAAM,KAAK,EAAE,CAAC;YAC1C,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,GAAG,IAAI,OAAO,KAAK,EAAE,CAAC;YAC5C,KAAK,IAAI,CAAC,CAAC,OAAO,GAAG,CAAA,GAAG,IAAI,MAAM,KAAK,EAAE,CAAC;YAC1C,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,GAAG,IAAI,OAAO,KAAK,EAAE,CAAC;YAC5C,KAAK,IAAI,CAAC,CAAC,OAAO,GAAG,CAAA,GAAG,IAAI,MAAM,KAAK,EAAE,CAAC;YAC1C,KAAK,KAAK,CAAC,CAAC,OAAO,GAAG,CAAA,GAAG,IAAI,OAAO,KAAK,EAAE,CAAC;YAC5C,OAAO,CAAC,CAAC,OAAO,SAAS,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/src/core/inputValidator.d.ts

@@ -0,0 +1,8 @@
+import { TableConfig } from '../types/table';
+import { EngineParams } from '../types/engine';
+/**
+ * Validates request params against the table config BEFORE hitting the database.
+ * Catches type mismatches, invalid fields, and bad values early.
+ */
+export declare function validateInput(params: EngineParams, config: TableConfig): void;
+//# sourceMappingURL=inputValidator.d.ts.map

package/dist/src/core/inputValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputValidator.d.ts","sourceRoot":"","sources":["../../../src/core/inputValidator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAG5D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAI7E"}

package/dist/src/core/inputValidator.js

@@ -0,0 +1,117 @@
+import { ValidationError, FieldError } from '../errors';
+/**
+ * Validates request params against the table config BEFORE hitting the database.
+ * Catches type mismatches, invalid fields, and bad values early.
+ */
+export function validateInput(params, config) {
+    validateSelectFields(params, config);
+    validateFilterValues(params, config);
+    validateSortFields(params, config);
+}
+function validateSelectFields(params, config) {
+    if (!params.select?.length)
+        return;
+    const validNames = new Set(config.columns.map((c) => c.name));
+    for (const field of params.select) {
+        if (!validNames.has(field)) {
+            throw new FieldError(field, 'does not exist. Available: ' + [...validNames].join(', '));
+        }
+        const col = config.columns.find((c) => c.name === field);
+        if (col?.hidden) {
+            throw new FieldError(field, 'is not accessible');
+        }
+    }
+}
+function validateFilterValues(params, config) {
+    if (!params.filters)
+        return;
+    const columnMap = new Map();
+    for (const col of config.columns) {
+        columnMap.set(col.name, col);
+    }
+    for (const [field, filter] of Object.entries(params.filters)) {
+        const col = columnMap.get(field);
+        if (!col) {
+            if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'test') {
+                console.warn(`[TableCraft] Filter field '${field}' does not exist in table '${config.name}', skipping`);
+            }
+            continue;
+        }
+        if (!col.filterable) {
+            throw new FieldError(field, 'is not filterable');
+        }
+        if (filter.operator === 'isNull' || filter.operator === 'isNotNull')
+            continue;
+        validateValueType(field, col.type, filter);
+    }
+}
+function validateValueType(field, colType, filter) {
+    const value = filter.value;
+    if (value === null || value === undefined)
+        return;
+    // For array operators, validate each element
+    if (filter.operator === 'in' || filter.operator === 'notIn') {
+        if (!Array.isArray(value)) {
+            throw new ValidationError(field, 'array', value);
+        }
+        for (const item of value) {
+            validateSingleValue(field, colType, item);
+        }
+        return;
+    }
+    // For between, validate both bounds
+    if (filter.operator === 'between') {
+        if (!Array.isArray(value) || value.length !== 2) {
+            throw new ValidationError(field, 'array of [min, max]', value);
+        }
+        validateSingleValue(field, colType, value[0]);
+        validateSingleValue(field, colType, value[1]);
+        return;
+    }
+    validateSingleValue(field, colType, value);
+}
+function validateSingleValue(field, colType, value) {
+    switch (colType) {
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new ValidationError(field, 'number', value);
+            }
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                throw new ValidationError(field, 'boolean', value);
+            }
+            break;
+        case 'uuid':
+            if (typeof value !== 'string' || !isValidUUID(value)) {
+                throw new ValidationError(field, 'valid UUID', value);
+            }
+            break;
+        case 'date':
+            if (typeof value === 'string') {
+                const d = new Date(value);
+                if (isNaN(d.getTime())) {
+                    throw new ValidationError(field, 'valid date string', value);
+                }
+            }
+            else if (!(value instanceof Date)) {
+                throw new ValidationError(field, 'date', value);
+            }
+            break;
+        // string, json — accept anything
+    }
+}
+function validateSortFields(params, config) {
+    if (!params.sort?.length)
+        return;
+    const sortable = new Set(config.columns.filter((c) => c.sortable).map((c) => c.name));
+    for (const s of params.sort) {
+        if (!sortable.has(s.field)) {
+            throw new FieldError(s.field, 'is not sortable. Sortable: ' + [...sortable].join(', '));
+        }
+    }
+}
+function isValidUUID(str) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(str);
+}
+//# sourceMappingURL=inputValidator.js.map

package/dist/src/core/inputValidator.js.map

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

package/dist/src/core/metadataBuilder.d.ts

@@ -0,0 +1,91 @@
+import { TableConfig } from '../types/table';
+import { EngineContext } from '../types/engine';
+/**
+ * The metadata response that describes a table's schema to the frontend.
+ * Everything the frontend needs to auto-build a data table.
+ */
+export interface TableMetadata {
+    name: string;
+    dateRangeColumn?: string | null;
+    dateColumns: string[];
+    columns: ColumnMetadata[];
+    capabilities: {
+        search: boolean;
+        searchFields: string[];
+        export: boolean;
+        exportFormats: string[];
+        pagination: {
+            enabled: boolean;
+            defaultPageSize: number;
+            maxPageSize: number;
+            cursor: boolean;
+        };
+        sort: {
+            enabled: boolean;
+            defaultSort: {
+                field: string;
+                order: string;
+            }[];
+        };
+        groupBy: boolean;
+        groupByFields: string[];
+        recursive: boolean;
+    };
+    filters: FilterMetadata[];
+    aggregations: AggregationMetadata[];
+    includes: IncludeMetadata[];
+    staticFilters: string[];
+}
+export interface ColumnMetadata {
+    name: string;
+    type: string;
+    label: string;
+    hidden: boolean;
+    sortable: boolean;
+    filterable: boolean;
+    computed?: boolean;
+    source?: 'base' | 'join' | 'computed' | 'subquery';
+    joinTable?: string;
+    format?: string;
+    align?: string;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    options?: {
+        value: string | number | boolean;
+        label: string;
+        color?: string;
+    }[];
+    datePresets?: string[];
+    operators: string[];
+}
+export interface FilterMetadata {
+    field: string;
+    type: string;
+    label: string;
+    operators: string[];
+    options?: {
+        value: string | number | boolean;
+        label: string;
+        color?: string;
+    }[];
+    datePresets?: string[];
+}
+export interface AggregationMetadata {
+    alias: string;
+    type: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    field: string;
+}
+export interface IncludeMetadata {
+    as: string;
+    table: string;
+    columns?: string[];
+    nested?: IncludeMetadata[];
+}
+/**
+ * Builds metadata from a TableConfig, filtered by the requesting user's roles.
+ * Handles: base columns, join columns, computed columns, subqueries,
+ * aggregations, includes, groupBy, recursive, and static filters.
+ */
+export declare function buildMetadata(config: TableConfig, context?: EngineContext): TableMetadata;
+//# sourceMappingURL=metadataBuilder.d.ts.map

package/dist/src/core/metadataBuilder.d.ts.map

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

package/dist/src/core/metadataBuilder.js

@@ -0,0 +1,220 @@
+/**
+ * Builds metadata from a TableConfig, filtered by the requesting user's roles.
+ * Handles: base columns, join columns, computed columns, subqueries,
+ * aggregations, includes, groupBy, recursive, and static filters.
+ */
+export function buildMetadata(config, context) {
+    const userRoles = context?.user?.roles ?? [];
+    // ── Collect ALL columns from every source ──
+    const allColumns = [];
+    // 1. Base table columns (includes computed columns added via .computed())
+    for (const col of config.columns) {
+        allColumns.push({
+            ...col,
+            _source: col.computed ? 'computed' : 'base',
+        });
+    }
+    // 2. Join columns — walk the join tree recursively
+    if (config.joins) {
+        collectJoinColumnsRecursive(config.joins, allColumns);
+    }
+    // 3. Subquery virtual columns
+    if (config.subqueries) {
+        for (const sub of config.subqueries) {
+            // Subqueries produce a virtual column with the alias name
+            // Only add if not already in allColumns (engine may have pushed it)
+            if (!allColumns.some(c => c.name === sub.alias)) {
+                allColumns.push({
+                    name: sub.alias,
+                    type: sub.type === 'exists' ? 'boolean' : sub.type === 'count' ? 'number' : 'string',
+                    label: sub.alias,
+                    hidden: false,
+                    sortable: true,
+                    filterable: true,
+                    computed: true,
+                    _source: 'subquery',
+                });
+            }
+        }
+    }
+    // ── Filter by role-based visibility ──
+    const visibleColumns = allColumns.filter((col) => {
+        if (col.hidden)
+            return false;
+        const visibleTo = col.visibleTo;
+        if (!visibleTo || visibleTo.length === 0)
+            return true;
+        if (userRoles.length === 0)
+            return false;
+        return visibleTo.some((role) => userRoles.includes(role));
+    });
+    // ── Build column metadata ──
+    const columns = visibleColumns.map((col) => {
+        const source = col._source;
+        const joinTable = col._joinTable;
+        return {
+            name: col.name,
+            type: col.type,
+            label: col.label ?? col.name,
+            hidden: false,
+            sortable: col.sortable ?? true,
+            filterable: col.filterable ?? true,
+            computed: col.computed ?? false,
+            source: (source ?? 'base'),
+            ...(joinTable && { joinTable }),
+            format: col.format,
+            align: col.align,
+            width: col.width,
+            minWidth: col.minWidth,
+            maxWidth: col.maxWidth,
+            options: col.options,
+            datePresets: col.datePresets,
+            operators: getOperatorsForType(col.type),
+        };
+    });
+    // ── Build filter metadata (only filterable visible columns) ──
+    const filters = visibleColumns
+        .filter((col) => col.filterable)
+        .map((col) => ({
+        field: col.name,
+        type: col.type,
+        label: col.label ?? col.name,
+        operators: getOperatorsForType(col.type),
+        options: col.options,
+        datePresets: col.datePresets,
+    }));
+    // ── Build aggregation metadata ──
+    const aggregations = (config.aggregations ?? []).map(agg => ({
+        alias: agg.alias,
+        type: agg.type,
+        field: agg.field,
+    }));
+    // ── Build include metadata (nested relations) ──
+    const includes = (config.include ?? []).map(buildIncludeMetadata);
+    // ── Build static filters list (inform frontend about pre-applied filters) ──
+    const staticFilters = [];
+    if (config.filters) {
+        for (const f of config.filters) {
+            if (f.type === 'static')
+                staticFilters.push(f.field);
+        }
+    }
+    if (config.backendConditions) {
+        for (const bc of config.backendConditions) {
+            staticFilters.push(bc.field);
+        }
+    }
+    // ── Auto-detect date range column if not explicit ──
+    const dateColumns = allColumns
+        .filter(c => c.type === 'date' && !c.computed && !c.hidden)
+        .map(c => c.name);
+    let dateRangeColumn = null;
+    if (config.dateRangeColumn) {
+        const colDef = allColumns.find(c => c.name === config.dateRangeColumn);
+        if (colDef && colDef.type === 'date' && !colDef.computed && !colDef.hidden) {
+            dateRangeColumn = config.dateRangeColumn;
+        }
+    }
+    if (!dateRangeColumn && dateColumns.length > 0) {
+        const hasCreatedAt = dateColumns.includes('createdAt') || dateColumns.includes('created_at');
+        if (hasCreatedAt) {
+            dateRangeColumn = dateColumns.find(c => c === 'createdAt' || c === 'created_at') ?? null;
+        }
+        else {
+            dateRangeColumn = dateColumns[0];
+        }
+    }
+    return {
+        name: config.name,
+        dateRangeColumn,
+        dateColumns,
+        columns,
+        capabilities: {
+            search: config.search?.enabled ?? false,
+            searchFields: config.search?.fields ?? [],
+            export: config.export?.enabled ?? true,
+            exportFormats: config.export?.formats ?? ['csv', 'json'],
+            pagination: {
+                enabled: config.pagination?.enabled ?? true,
+                defaultPageSize: config.pagination?.defaultPageSize ?? 10,
+                maxPageSize: config.pagination?.maxPageSize ?? 100,
+                cursor: true,
+            },
+            sort: {
+                enabled: visibleColumns.some((c) => c.sortable),
+                defaultSort: (config.defaultSort ?? []).map(s => ({
+                    field: s.field,
+                    order: s.order ?? 'asc'
+                })),
+            },
+            groupBy: !!(config.groupBy?.fields?.length),
+            groupByFields: config.groupBy?.fields ?? [],
+            recursive: !!config.recursive,
+        },
+        filters,
+        aggregations,
+        includes,
+        staticFilters,
+    };
+}
+/**
+ * Recursively collects columns from join configs.
+ */
+function collectJoinColumnsRecursive(joins, out) {
+    for (const join of joins) {
+        if (join.columns) {
+            for (const col of join.columns) {
+                // Skip if a column with the same name already exists (base takes priority)
+                if (!out.some(c => c.name === col.name)) {
+                    out.push({
+                        ...col,
+                        _source: 'join',
+                        _joinTable: join.alias ?? join.table,
+                    });
+                }
+            }
+        }
+        // Recurse into nested joins
+        if (join.joins) {
+            collectJoinColumnsRecursive(join.joins, out);
+        }
+    }
+}
+/**
+ * Builds metadata for an include config, recursing into nested includes.
+ */
+function buildIncludeMetadata(inc) {
+    const meta = {
+        as: inc.as,
+        table: inc.table,
+    };
+    if (inc.columns?.length)
+        meta.columns = inc.columns;
+    if (inc.include?.length) {
+        meta.nested = inc.include.map(buildIncludeMetadata);
+    }
+    return meta;
+}
+/**
+ * Returns the valid filter operators for a column type.
+ */
+function getOperatorsForType(type) {
+    const common = ['eq', 'neq', 'isNull', 'isNotNull'];
+    switch (type) {
+        case 'string':
+            return [...common, 'contains', 'startsWith', 'endsWith', 'like', 'ilike', 'in', 'notIn'];
+        case 'number':
+            return [...common, 'gt', 'gte', 'lt', 'lte', 'between', 'in', 'notIn'];
+        case 'date':
+            return [...common, 'gt', 'gte', 'lt', 'lte', 'between'];
+        case 'boolean':
+            return ['eq', 'neq'];
+        case 'uuid':
+            return [...common, 'in', 'notIn'];
+        case 'json':
+            return ['eq', 'neq', 'isNull', 'isNotNull'];
+        default:
+            return common;
+    }
+}
+//# sourceMappingURL=metadataBuilder.js.map

package/dist/src/core/metadataBuilder.js.map

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

package/dist/src/core/paginationBuilder.d.ts

@@ -0,0 +1,20 @@
+import { TableConfig } from '../types/table';
+import { EngineMeta } from '../types/engine';
+export interface PaginationResult {
+    limit: number;
+    offset: number;
+    page: number;
+    pageSize: number;
+}
+export declare class PaginationBuilder {
+    /**
+     * Computes LIMIT and OFFSET from page/pageSize params.
+     * Enforces min/max boundaries from the config.
+     */
+    buildPagination(config: TableConfig, page?: number, pageSize?: number): PaginationResult;
+    /**
+     * Produces pagination metadata from the total row count.
+     */
+    buildMeta(total: number, pagination: PaginationResult): EngineMeta;
+}
+//# sourceMappingURL=paginationBuilder.d.ts.map