@tablecraft/engine 0.1.0-beta.1

package/dist/src/define.js

@@ -0,0 +1,690 @@
+import { getTableName, } from 'drizzle-orm';
+import { introspectTable, getSensitiveColumnNames, detectSensitiveColumns, } from './utils/introspect';
+function emptyExtensions() {
+    return {
+        computedExpressions: new Map(),
+        transforms: new Map(),
+        rawSelects: new Map(),
+        rawWheres: [],
+        rawJoins: [],
+        rawOrderBys: [],
+        ctes: new Map(),
+        sqlJoinConditions: new Map(),
+    };
+}
+// ── Builder ──
+export class TableDefinitionBuilder {
+    _config;
+    _table;
+    _ext;
+    constructor(table, config) {
+        this._table = table;
+        this._config = config;
+        this._ext = emptyExtensions();
+    }
+    // ──── Column Format / Metadata ────
+    /** Set display format for a column */
+    format(column, fmt) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.format = fmt;
+        return this;
+    }
+    /** Set column alignment */
+    align(column, alignment) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.align = alignment;
+        return this;
+    }
+    /** Set column width (px) */
+    width(column, w, options) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col) {
+            col.width = w;
+            if (options?.min)
+                col.minWidth = options.min;
+            if (options?.max)
+                col.maxWidth = options.max;
+        }
+        return this;
+    }
+    // ──── Enum Options ────
+    /**
+     * Declare the valid values for a column.
+     * Used by frontend to render dropdown filters.
+     * @example
+     * .options('status', [
+     *   { value: 'active', label: 'Active', color: 'green' },
+     *   { value: 'inactive', label: 'Inactive', color: 'gray' },
+     *   { value: 'banned', label: 'Banned', color: 'red' },
+     * ])
+     */
+    options(column, opts) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.options = opts;
+        return this;
+    }
+    // ──── Date Presets ────
+    /**
+     * Set which date presets are available for filtering.
+     * @example
+     * .datePresets('createdAt', ['today', 'last7days', 'thisMonth', 'custom'])
+     */
+    datePresets(column, presets) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.datePresets = presets;
+        return this;
+    }
+    // ──── Role-Based Column Visibility ────
+    /**
+     * Restrict column visibility to specific roles.
+     * Columns without visibleTo are visible to everyone.
+     * @example
+     * .visibleTo('salary', ['admin', 'hr'])
+     * .visibleTo('internalNotes', ['admin'])
+     */
+    visibleTo(column, roles) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.visibleTo = roles;
+        return this;
+    }
+    // ──── Column Visibility ────
+    hide(...columns) {
+        for (const name of columns) {
+            const col = this._config.columns.find((c) => c.name === name);
+            if (col)
+                col.hidden = true;
+        }
+        return this;
+    }
+    show(...columns) {
+        for (const name of columns) {
+            const col = this._config.columns.find((c) => c.name === name);
+            if (col)
+                col.hidden = false;
+        }
+        return this;
+    }
+    only(...columns) {
+        const keep = new Set(columns);
+        for (const col of this._config.columns) {
+            col.hidden = !keep.has(col.name);
+        }
+        return this;
+    }
+    autoHide() {
+        const sensitive = getSensitiveColumnNames();
+        for (const col of this._config.columns) {
+            if (sensitive.has(col.name))
+                col.hidden = true;
+        }
+        return this;
+    }
+    inspectSensitive() {
+        return detectSensitiveColumns(this._table);
+    }
+    // ──── Labels ────
+    label(column, lbl) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.label = lbl;
+        return this;
+    }
+    labels(map) {
+        for (const [name, lbl] of Object.entries(map)) {
+            if (lbl)
+                this.label(name, lbl);
+        }
+        return this;
+    }
+    // ──── Search ────
+    search(...columns) {
+        // Cast to unknown first to avoid tuple/array type mismatch in strict mode
+        this._config.search = { fields: columns, enabled: true };
+        return this;
+    }
+    searchAll() {
+        const textCols = this._config.columns
+            .filter((c) => c.type === 'string' && !c.hidden)
+            .map((c) => c.name);
+        this._config.search = { fields: textCols, enabled: true };
+        return this;
+    }
+    noSearch() {
+        this._config.search = { fields: [], enabled: false };
+        return this;
+    }
+    // ──── Filtering ────
+    filter(...columns) {
+        const filterSet = new Set(columns);
+        for (const col of this._config.columns) {
+            col.filterable = filterSet.has(col.name);
+        }
+        return this;
+    }
+    staticFilter(field, operator, value) {
+        if (!this._config.filters)
+            this._config.filters = [];
+        this._config.filters.push({ field: field, operator, value, type: 'static' });
+        return this;
+    }
+    noFilter() {
+        for (const col of this._config.columns)
+            col.filterable = false;
+        return this;
+    }
+    // ──── OR Logic / Filter Groups ────
+    /**
+     * Add an OR group of conditions.
+     * @example .whereOr(
+     *   { field: 'status', op: 'eq', value: 'active' },
+     *   { field: 'priority', op: 'eq', value: 'high' },
+     * )
+     * → WHERE ... AND (status = 'active' OR priority = 'high')
+     */
+    whereOr(...conditions) {
+        if (!this._config.filterGroups)
+            this._config.filterGroups = [];
+        this._config.filterGroups.push({
+            type: 'or',
+            conditions: conditions.map((c) => ({
+                field: c.field,
+                operator: c.op,
+                value: c.value,
+            })),
+        });
+        return this;
+    }
+    /**
+     * Add a filter group with explicit AND/OR type.
+     * Supports nested groups for complex logic.
+     * @example .whereGroup('or', [
+     *   { field: 'status', operator: 'eq', value: 'active' },
+     *   { type: 'and', conditions: [
+     *     { field: 'priority', operator: 'eq', value: 'high' },
+     *     { field: 'total', operator: 'gt', value: 1000 },
+     *   ]},
+     * ])
+     */
+    whereGroup(type, conditions) {
+        if (!this._config.filterGroups)
+            this._config.filterGroups = [];
+        this._config.filterGroups.push({ type, conditions });
+        return this;
+    }
+    // ──── Sorting ────
+    sort(...specs) {
+        this._config.defaultSort = specs.map(parseSortSpec);
+        return this;
+    }
+    sortable(...columns) {
+        const sortSet = new Set(columns);
+        for (const col of this._config.columns) {
+            col.sortable = sortSet.has(col.name);
+        }
+        return this;
+    }
+    noSort() {
+        for (const col of this._config.columns)
+            col.sortable = false;
+        this._config.defaultSort = undefined;
+        return this;
+    }
+    // ──── Pagination ────
+    pageSize(size, options) {
+        this._config.pagination = {
+            ...this._config.pagination,
+            defaultPageSize: size,
+            maxPageSize: options?.max ?? this._config.pagination?.maxPageSize ?? 100,
+            enabled: true,
+        };
+        return this;
+    }
+    noPagination() {
+        this._config.pagination = { defaultPageSize: 10, maxPageSize: 100, enabled: false };
+        return this;
+    }
+    // ──── Joins (accepts string OR SQL) ────
+    join(table, options) {
+        if (!this._config.joins)
+            this._config.joins = [];
+        const joinedName = getTableName(table);
+        const baseName = this._config.base;
+        const key = options?.alias ?? joinedName;
+        let onString = '';
+        if (options?.on) {
+            if (typeof options.on === 'string') {
+                // Shorthand: "customerId" → "base.customerId = joined.id"
+                if (!options.on.includes('=') && !options.on.includes('.')) {
+                    onString = `${baseName}.${options.on} = ${joinedName}.id`;
+                }
+                else {
+                    onString = options.on;
+                }
+            }
+            else {
+                // It's a SQL object. Store it in extensions map.
+                // We use a placeholder string for the config.
+                onString = `__SQL__:${key}`;
+                this._ext.sqlJoinConditions.set(key, options.on);
+            }
+        }
+        else {
+            // Default guess
+            onString = `${baseName}.${joinedName}Id = ${joinedName}.id`;
+        }
+        const joinConfig = {
+            table: joinedName,
+            type: options?.type ?? 'left',
+            on: onString,
+            ...(options?.alias && { alias: options.alias }),
+            ...(options?.columns && {
+                columns: options.columns.map((name) => ({
+                    name,
+                    type: 'string',
+                    hidden: false,
+                    sortable: true,
+                    filterable: true,
+                })),
+            }),
+        };
+        this._config.joins.push(joinConfig);
+        return this;
+    }
+    // ──── Computed Columns ────
+    computed(name, expression, options) {
+        this._config.columns.push({
+            name,
+            type: options?.type ?? 'string',
+            label: options?.label ?? name,
+            hidden: false,
+            sortable: true,
+            filterable: false,
+            computed: true,
+        });
+        this._ext.computedExpressions.set(name, expression);
+        return this;
+    }
+    // ──── Backend Conditions ────
+    where(condition) {
+        if (!this._config.backendConditions)
+            this._config.backendConditions = [];
+        this._config.backendConditions.push({
+            field: condition.field,
+            operator: condition.op,
+            value: condition.value,
+        });
+        return this;
+    }
+    // ──── Transforms ────
+    dbTransform(column, ...transforms) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.dbTransform = transforms;
+        return this;
+    }
+    jsTransform(column, ...transforms) {
+        const col = this._config.columns.find((c) => c.name === column);
+        if (col)
+            col.jsTransform = transforms;
+        return this;
+    }
+    transform(column, fn) {
+        this._ext.transforms.set(column, fn);
+        return this;
+    }
+    // ──── GROUP BY & HAVING ────
+    groupBy(...fields) {
+        if (!this._config.groupBy)
+            this._config.groupBy = { fields: [] };
+        this._config.groupBy.fields = fields;
+        return this;
+    }
+    having(alias, operator, value) {
+        if (!this._config.groupBy)
+            this._config.groupBy = { fields: [] };
+        if (!this._config.groupBy.having)
+            this._config.groupBy.having = [];
+        this._config.groupBy.having.push({ alias, operator, value });
+        return this;
+    }
+    // ──── Aggregations ────
+    aggregate(alias, type, field) {
+        if (!this._config.aggregations)
+            this._config.aggregations = [];
+        this._config.aggregations.push({ alias, type, field: field });
+        return this;
+    }
+    // ──── Nested Relations (Includes) ────
+    include(table, options) {
+        if (!this._config.include)
+            this._config.include = [];
+        const includeConfig = {
+            table: getTableName(table),
+            foreignKey: options.foreignKey,
+            localKey: options.localKey ?? 'id',
+            as: options.as,
+            columns: options.columns,
+            limit: options.limit,
+            where: options.where?.map((w) => ({
+                field: w.field,
+                operator: w.op,
+                value: w.value,
+            })),
+            orderBy: options.orderBy?.map(parseSortSpec),
+        };
+        this._config.include.push(includeConfig);
+        return this;
+    }
+    // ──── Recursive Queries (CTE) ────
+    recursive(options) {
+        this._config.recursive = {
+            parentKey: options.parentKey,
+            childKey: options.childKey ?? 'id',
+            maxDepth: options.maxDepth ?? 10,
+            depthAlias: options.depthAlias ?? 'depth',
+            pathAlias: options.pathAlias,
+            startWith: options.startWith
+                ? {
+                    field: options.startWith.field,
+                    operator: options.startWith.op,
+                    value: options.startWith.value,
+                }
+                : undefined,
+        };
+        return this;
+    }
+    // ──── Column Metadata (universal) ────
+    /**
+     * Enrich any column's metadata — works on base columns, join columns,
+     * computed columns, rawSelect columns, or any column by name.
+     *
+     * Use this to describe raw SQL columns to the frontend, or override
+     * any auto-detected metadata.
+     *
+     * @example
+     * .rawSelect('revenue', sql`SUM(orders.total)`)
+     * .columnMeta('revenue', {
+     *   type: 'number',
+     *   label: 'Total Revenue',
+     *   format: 'currency',
+     *   align: 'right',
+     *   filterable: true,
+     *   sortable: true,
+     *   options: [
+     *     { value: 'high', label: 'High (>$1000)', color: 'green' },
+     *   ],
+     * })
+     */
+    columnMeta(column, meta) {
+        // Find in base columns first
+        let col = this._config.columns.find((c) => c.name === column);
+        // Then search join columns
+        if (!col && this._config.joins) {
+            col = this._findJoinColumn(this._config.joins, column);
+        }
+        if (!col) {
+            // Column doesn't exist yet — this is fine for rawSelect/computed that
+            // haven't been registered yet. Create a placeholder.
+            col = {
+                name: column,
+                type: meta.type ?? 'string',
+                hidden: false,
+                computed: true,
+            };
+            this._config.columns.push(col);
+        }
+        // Apply all provided metadata
+        if (meta.type !== undefined)
+            col.type = meta.type;
+        if (meta.label !== undefined)
+            col.label = meta.label;
+        if (meta.sortable !== undefined)
+            col.sortable = meta.sortable;
+        if (meta.filterable !== undefined)
+            col.filterable = meta.filterable;
+        if (meta.hidden !== undefined)
+            col.hidden = meta.hidden;
+        if (meta.format !== undefined)
+            col.format = meta.format;
+        if (meta.align !== undefined)
+            col.align = meta.align;
+        if (meta.width !== undefined)
+            col.width = meta.width;
+        if (meta.minWidth !== undefined)
+            col.minWidth = meta.minWidth;
+        if (meta.maxWidth !== undefined)
+            col.maxWidth = meta.maxWidth;
+        if (meta.options !== undefined)
+            col.options = meta.options;
+        if (meta.datePresets !== undefined)
+            col.datePresets = meta.datePresets;
+        if (meta.visibleTo !== undefined)
+            col.visibleTo = meta.visibleTo;
+        return this;
+    }
+    /** Find a column inside the join tree by name */
+    _findJoinColumn(joins, name) {
+        for (const join of joins) {
+            if (join.columns) {
+                const col = join.columns.find((c) => c.name === name);
+                if (col)
+                    return col;
+            }
+            if (join.joins) {
+                const found = this._findJoinColumn(join.joins, name);
+                if (found)
+                    return found;
+            }
+        }
+        return undefined;
+    }
+    // ──── Raw SQL Escape Hatches ────
+    /**
+     * Add a raw SQL expression as a select column.
+     * By default typed as 'string'. Use the options parameter or
+     * chain `.columnMeta()` to set the correct type, label, format, etc.
+     *
+     * @example
+     * // Basic
+     * .rawSelect('revenue', sql`SUM(orders.total)`)
+     *
+     * // With inline metadata
+     * .rawSelect('revenue', sql`SUM(orders.total)`, {
+     *   type: 'number', label: 'Revenue', format: 'currency',
+     * })
+     *
+     * // Or chain .columnMeta() for full control
+     * .rawSelect('revenue', sql`SUM(orders.total)`)
+     * .columnMeta('revenue', { type: 'number', label: 'Revenue', format: 'currency' })
+     */
+    rawSelect(alias, sqlExpr, options) {
+        this._ext.rawSelects.set(alias, sqlExpr);
+        // Register as a computed column with metadata
+        this._config.columns.push({
+            name: alias,
+            type: options?.type ?? 'string',
+            label: options?.label,
+            hidden: options?.hidden ?? false,
+            sortable: options?.sortable ?? true,
+            filterable: options?.filterable ?? false,
+            computed: true,
+            ...(options?.format && { format: options.format }),
+            ...(options?.align && { align: options.align }),
+            ...(options?.width && { width: options.width }),
+            ...(options?.options && { options: options.options }),
+            ...(options?.visibleTo && { visibleTo: options.visibleTo }),
+        });
+        return this;
+    }
+    rawWhere(sqlExpr) {
+        this._ext.rawWheres.push(sqlExpr);
+        return this;
+    }
+    rawJoin(sqlExpr) {
+        this._ext.rawJoins.push(sqlExpr);
+        return this;
+    }
+    rawOrderBy(sqlExpr) {
+        this._ext.rawOrderBys.push(sqlExpr);
+        return this;
+    }
+    cte(name, sqlExpr) {
+        this._ext.ctes.set(name, sqlExpr);
+        return this;
+    }
+    // ──── Subqueries ────
+    subquery(alias, table, type, filter) {
+        if (!this._config.subqueries)
+            this._config.subqueries = [];
+        this._config.subqueries.push({
+            alias,
+            table: getTableName(table),
+            type,
+            filter,
+        });
+        return this;
+    }
+    // ──── Platform Features ────
+    softDelete(field) {
+        this._config.softDelete = {
+            field: field ?? this._config.softDelete?.field ?? 'deletedAt',
+            enabled: true,
+        };
+        return this;
+    }
+    tenant(field) {
+        this._config.tenant = {
+            field: field ?? this._config.tenant?.field ?? 'tenantId',
+            enabled: true,
+        };
+        return this;
+    }
+    exportable(...formats) {
+        this._config.export = {
+            formats: formats.length > 0 ? formats : ['csv', 'json'],
+            enabled: true,
+        };
+        return this;
+    }
+    access(options) {
+        this._config.access = options;
+        return this;
+    }
+    // ──── Name Override ────
+    as(name) {
+        this._config.name = name;
+        return this;
+    }
+    // ──── Count Mode ────
+    /**
+     * Control how row counting works.
+     * 'exact' = SELECT COUNT(*) — accurate but slow on large tables
+     * 'estimated' = PostgreSQL's reltuples — fast but approximate
+     * 'none' = skip counting entirely — fastest
+     */
+    countMode(mode) {
+        if (!this._config._countMode) {
+            this._config._countMode = mode;
+        }
+        this._config._countMode = mode;
+        return this;
+    }
+    // ──── DISTINCT ────
+    /** Enable DISTINCT on queries */
+    distinct() {
+        this._config._distinct = true;
+        return this;
+    }
+    // ──── Hooks ────
+    /** Add a hook that runs before every query */
+    beforeQuery(fn) {
+        this._ext.hooks = this._ext.hooks ?? {};
+        this._ext.hooks.beforeQuery = fn;
+        return this;
+    }
+    /** Add a hook that runs after every query */
+    afterQuery(fn) {
+        this._ext.hooks = this._ext.hooks ?? {};
+        this._ext.hooks.afterQuery = fn;
+        return this;
+    }
+    /** Add an error handler */
+    onError(fn) {
+        this._ext.hooks = this._ext.hooks ?? {};
+        this._ext.hooks.onError = fn;
+        return this;
+    }
+    // ──── Output ────
+    toConfig() {
+        return { ...this._config };
+    }
+}
+// ── Main Entry ──
+export function defineTable(table, options) {
+    if (options && 'columns' in options && Array.isArray(options.columns)) {
+        return new TableDefinitionBuilder(table, options);
+    }
+    const config = introspectTable(table);
+    if (options) {
+        applyQuickOptions(config, options);
+    }
+    return new TableDefinitionBuilder(table, config);
+}
+// ── Helpers ──
+function applyQuickOptions(config, options) {
+    if (options.hide) {
+        for (const name of options.hide) {
+            const col = config.columns.find((c) => c.name === name);
+            if (col)
+                col.hidden = true;
+        }
+    }
+    if (options.search) {
+        config.search = { fields: options.search, enabled: true };
+    }
+    if (options.filter) {
+        const filterSet = new Set(options.filter);
+        for (const col of config.columns) {
+            col.filterable = filterSet.has(col.name);
+        }
+    }
+    if (options.sort) {
+        const specs = options.sort.split(',').map((s) => s.trim()).filter(Boolean);
+        config.defaultSort = specs.map(parseSortSpec);
+    }
+    if (options.pageSize !== undefined) {
+        config.pagination = {
+            ...config.pagination,
+            defaultPageSize: options.pageSize,
+            maxPageSize: options.maxPageSize ?? config.pagination?.maxPageSize ?? 100,
+            enabled: true,
+        };
+    }
+    if (options.maxPageSize !== undefined && config.pagination) {
+        config.pagination.maxPageSize = options.maxPageSize;
+    }
+    if (options.labels) {
+        for (const [name, label] of Object.entries(options.labels)) {
+            if (!label)
+                continue;
+            const col = config.columns.find((c) => c.name === name);
+            if (col)
+                col.label = label;
+        }
+    }
+}
+function parseSortSpec(spec) {
+    if (spec.startsWith('-')) {
+        return { field: String(spec.slice(1)), order: 'desc' };
+    }
+    if (spec.startsWith('+')) {
+        return { field: String(spec.slice(1)), order: 'asc' };
+    }
+    return { field: String(spec), order: 'asc' };
+}
+//# sourceMappingURL=define.js.map