jsql-neo 1.1.0 → 1.2.0

package/lib/query.js

@@ -0,0 +1,435 @@
+// © Vexify 2026 All Rights Reserved.
+/**
+ * JSQL Query — 链式查询构建器
+ * 支持 JOIN、DISTINCT、HAVING、UNION、多字段排序、高级操作符、分页、EXPLAIN
+ */
+
+class Query {
+    constructor(table, conditions = {}) {
+        this._table = table;
+        this._conditions = conditions;
+        this._orderBy = [];
+        this._limitCount = null;
+        this._offsetCount = 0;
+        this._selectFields = null;
+        this._groupBy = null;
+        this._having = null;
+        this._distinct = false;
+        this._distinctField = null;
+        this._joins = [];
+        this._union = null;
+        this._explain = false;
+    }
+
+    // ============================================================
+    // 条件
+    // ============================================================
+
+    where(conditions) {
+        Object.assign(this._conditions, conditions);
+        return this;
+    }
+
+    // ============================================================
+    // 排序
+    // ============================================================
+
+    orderBy(field, dir = 'asc') {
+        this._orderBy.push({ field, dir: dir.toLowerCase() });
+        return this;
+    }
+
+    orderByDesc(field) {
+        return this.orderBy(field, 'desc');
+    }
+
+    // ============================================================
+    // 分页
+    // ============================================================
+
+    limit(n) {
+        this._limitCount = n;
+        return this;
+    }
+
+    offset(n) {
+        this._offsetCount = n;
+        return this;
+    }
+
+    /**
+     * 便捷分页
+     * @param {number} page - 页码（从 1 开始）
+     * @param {number} perPage - 每页数量
+     * @returns {{ rows, total, page, perPage, totalPages }}
+     */
+    paginate(page = 1, perPage = 20) {
+        this._limitCount = perPage;
+        this._offsetCount = (page - 1) * perPage;
+        const total = this._countRaw();
+        const rows = this.get();
+        return {
+            rows,
+            total,
+            page,
+            perPage,
+            totalPages: Math.ceil(total / perPage)
+        };
+    }
+
+    // ============================================================
+    // 字段选择
+    // ============================================================
+
+    select(fields) {
+        this._selectFields = Array.isArray(fields) ? fields : [fields];
+        return this;
+    }
+
+    distinct(field) {
+        this._distinct = true;
+        this._distinctField = field;
+        return this;
+    }
+
+    // ============================================================
+    // 分组 & 聚合后过滤
+    // ============================================================
+
+    groupBy(field) {
+        this._groupBy = field;
+        return this;
+    }
+
+    having(conditions) {
+        this._having = conditions;
+        return this;
+    }
+
+    // ============================================================
+    // JOIN
+    // ============================================================
+
+    /**
+     * INNER JOIN
+     * @param {Table} otherTable - 要 JOIN 的表
+     * @param {string} localField - 本地字段
+     * @param {string} foreignField - 对方字段
+     * @param {string} as - 别名
+     */
+    join(otherTable, localField, foreignField, as) {
+        this._joins.push({ type: 'inner', table: otherTable, localField, foreignField, as });
+        return this;
+    }
+
+    leftJoin(otherTable, localField, foreignField, as) {
+        this._joins.push({ type: 'left', table: otherTable, localField, foreignField, as });
+        return this;
+    }
+
+    rightJoin(otherTable, localField, foreignField, as) {
+        this._joins.push({ type: 'right', table: otherTable, localField, foreignField, as });
+        return this;
+    }
+
+    // ============================================================
+    // UNION
+    // ============================================================
+
+    union(query) {
+        this._union = query;
+        return this;
+    }
+
+    // ============================================================
+    // EXPLAIN
+    // ============================================================
+
+    explain() {
+        this._explain = true;
+        return this;
+    }
+
+    // ============================================================
+    // 执行
+    // ============================================================
+
+    get() {
+        if (this._explain) return this._getExplain();
+
+        let rows = this._table._applyFilter(this._table._rows, this._conditions);
+
+        // JOIN
+        for (const join of this._joins) {
+            rows = this._applyJoin(rows, join);
+        }
+
+        // UNION
+        if (this._union) {
+            const unionRows = this._union.get();
+            rows = [...rows, ...unionRows];
+        }
+
+        // GROUP BY
+        if (this._groupBy) {
+            rows = this._applyGroupBy(rows);
+        }
+
+        // HAVING
+        if (this._having) {
+            rows = this._table._applyFilter(rows, this._having);
+        }
+
+        // DISTINCT
+        if (this._distinct && this._distinctField) {
+            const seen = new Set();
+            rows = rows.filter(r => {
+                const val = r[this._distinctField];
+                if (val === undefined) return false; // 跳过 undefined
+                const key = String(val);
+                if (seen.has(key)) return false;
+                seen.add(key);
+                return true;
+            });
+        }
+
+        // 排序
+        if (this._orderBy.length > 0) {
+            rows = this._applyOrderBy(rows);
+        }
+
+        // 分页
+        if (this._offsetCount > 0) {
+            rows = rows.slice(this._offsetCount);
+        }
+        if (this._limitCount !== null) {
+            rows = rows.slice(0, this._limitCount);
+        }
+
+        // 字段选择
+        rows = rows.map(r => ({ ...r }));
+        if (this._selectFields) {
+            rows = rows.map(r => {
+                const obj = {};
+                for (const f of this._selectFields) {
+                    obj[f] = r[f];
+                }
+                return obj;
+            });
+        }
+
+        return rows;
+    }
+
+    first() {
+        const rows = this.limit(1).get();
+        return rows.length > 0 ? rows[0] : null;
+    }
+
+    count() {
+        return this._countRaw();
+    }
+
+    sum(field) {
+        const rows = this._getFilteredRows();
+        return rows.reduce((acc, r) => acc + (Number(r[field]) || 0), 0);
+    }
+
+    avg(field) {
+        const rows = this._getFilteredRows();
+        if (rows.length === 0) return 0;
+        return this.sum(field) / rows.length;
+    }
+
+    min(field) {
+        const rows = this._getFilteredRows();
+        if (rows.length === 0) return null;
+        return rows.reduce((min, r) => {
+            const v = Number(r[field]);
+            return (min === null || v < min) ? v : min;
+        }, null);
+    }
+
+    max(field) {
+        const rows = this._getFilteredRows();
+        if (rows.length === 0) return null;
+        return rows.reduce((max, r) => {
+            const v = Number(r[field]);
+            return (max === null || v > max) ? v : max;
+        }, null);
+    }
+
+    groupStats(field) {
+        if (!this._groupBy) throw new Error('groupStats() requires groupBy() to be called first');
+        const rows = this._table._applyFilter(this._table._rows, this._conditions);
+        const groups = {};
+
+        for (const row of rows) {
+            const key = String(row[this._groupBy] ?? '__null__');
+            if (!groups[key]) {
+                groups[key] = { _group: row[this._groupBy], _count: 0, _sum: 0, _min: null, _max: null, _rows: [] };
+            }
+            const g = groups[key];
+            g._count++;
+            const v = Number(row[field]) || 0;
+            g._sum += v;
+            g._min = g._min === null ? v : Math.min(g._min, v);
+            g._max = g._max === null ? v : Math.max(g._max, v);
+            g._rows.push(row);
+        }
+
+        const result = Object.values(groups);
+        result.forEach(g => {
+            g._avg = g._count > 0 ? g._sum / g._count : 0;
+            delete g._rows;
+        });
+
+        return result;
+    }
+
+    update(updates) {
+        return this._table.update(this._conditions, updates);
+    }
+
+    remove() {
+        return this._table.remove(this._conditions);
+    }
+
+    // ============================================================
+    // 内部
+    // ============================================================
+
+    _getFilteredRows() {
+        return this._table._applyFilter(this._table._rows, this._conditions);
+    }
+
+    _countRaw() {
+        return this._table._applyFilter(this._table._rows, this._conditions).length;
+    }
+
+    _applyOrderBy(rows) {
+        return [...rows].sort((a, b) => {
+            for (const { field, dir } of this._orderBy) {
+                const va = a[field];
+                const vb = b[field];
+                if (va < vb) return dir === 'asc' ? -1 : 1;
+                if (va > vb) return dir === 'asc' ? 1 : -1;
+            }
+            return 0;
+        });
+    }
+
+    _applyJoin(localRows, join) {
+        const result = [];
+        const foreignRows = join.table._rows;
+
+        if (join.type === 'left') {
+            for (const lr of localRows) {
+                const matches = foreignRows.filter(fr => fr[join.foreignField] === lr[join.localField]);
+                if (matches.length === 0) {
+                    result.push({ ...lr, ...this._nullRow(join.table) });
+                } else {
+                    for (const fr of matches) {
+                        result.push(this._mergeJoinRow(lr, fr, join));
+                    }
+                }
+            }
+        } else if (join.type === 'right') {
+            for (const fr of foreignRows) {
+                const matches = localRows.filter(lr => lr[join.localField] === fr[join.foreignField]);
+                if (matches.length === 0) {
+                    result.push({ ...fr, ...this._nullRow(join.table, true) });
+                } else {
+                    for (const lr of matches) {
+                        result.push(this._mergeJoinRow(lr, fr, join));
+                    }
+                }
+            }
+        } else {
+            // inner join
+            for (const lr of localRows) {
+                for (const fr of foreignRows) {
+                    if (fr[join.foreignField] === lr[join.localField]) {
+                        result.push(this._mergeJoinRow(lr, fr, join));
+                    }
+                }
+            }
+        }
+        return result;
+    }
+
+    _mergeJoinRow(lr, fr, join) {
+        const merged = { ...lr };
+        const prefix = join.as ? join.as + '_' : '';
+        for (const [key, value] of Object.entries(fr)) {
+            merged[prefix + key] = value;
+        }
+        return merged;
+    }
+
+    _nullRow(table, isLocal) {
+        const nulls = {};
+        const schema = table._schema;
+        for (const field of Object.keys(schema)) {
+            nulls[field] = null;
+        }
+        return nulls;
+    }
+
+    _applyGroupBy(rows) {
+        const groups = {};
+        for (const row of rows) {
+            const key = String(row[this._groupBy] ?? '__null__');
+            if (!groups[key]) {
+                groups[key] = { _group: row[this._groupBy], _rows: [], _count: 0 };
+            }
+            groups[key]._rows.push(row);
+            groups[key]._count++;
+        }
+
+        const result = [];
+        for (const g of Object.values(groups)) {
+            // 使用第一行作为基础，并添加 _group 和 _count
+            const base = { ...g._rows[0] };
+            base._group = g._group;
+            base._count = g._count;
+            result.push(base);
+        }
+        return result;
+    }
+
+    _getExplain() {
+        const totalRows = this._table._rows.length;
+        const filtered = this._table._applyFilter(this._table._rows, this._conditions);
+        const plan = {
+            table: this._table._name,
+            totalRows,
+            conditions: this._conditions,
+            filteredRows: filtered.length,
+            selectivity: totalRows > 0 ? (filtered.length / totalRows * 100).toFixed(1) + '%' : '0%',
+            hasIndex: false,
+            indexUsed: null,
+            joins: this._joins.length,
+            groupBy: this._groupBy,
+            having: this._having,
+            orderBy: this._orderBy.map(o => `${o.field} ${o.dir}`),
+            limit: this._limitCount,
+            offset: this._offsetCount,
+            estimatedCost: filtered.length * (1 + this._joins.length)
+        };
+
+        // 检查索引命中
+        for (const [field] of Object.entries(this._conditions)) {
+            if (this._table._indexes[field]) {
+                plan.hasIndex = true;
+                plan.indexUsed = field;
+                plan.estimatedCost = Math.floor(plan.estimatedCost * 0.1);
+                break;
+            }
+        }
+
+        return plan;
+    }
+}
+
+module.exports = Query;