@zintrust/core 3.0.4 → 3.0.6

package/README.md

@@ -80,7 +80,7 @@ ZinTrust is a **minimal-core** backend framework built on:
 
 ### 🛡️ Secure by Default
 
-- No raw SQL - QueryBuilder enforces parameterized queries
+- No free-form SQL - QueryBuilder enforces safe identifiers + parameterized values (see [Query Builder](./query-builder.md) for exists, joins, groupBy, latestPer)
 - Automatic CSRF protection
 - JWT token management
 - XSS vulnerability prevention

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "3.0.4",
+  "version": "3.0.6",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/http/Kernel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../../src/http/Kernel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,KAAK,EAAE,OAAO,EAAc,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK7E,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAgBpE,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/C,wBAAwB,CAAC,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC5D,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACpE,SAAS,IAAI,OAAO,CAAC;IACrB,YAAY,IAAI,iBAAiB,CAAC;IAClC,kBAAkB,IAAI,gBAAgB,CAAC;IAGvC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,cAAc,IAAI,IAAI,CAAC;IACvB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AA4XD,eAAO,MAAM,MAAM;qBAvEK,OAAO,aAAa,iBAAiB,KAAG,OAAO;EAyErE,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../../src/http/Kernel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,KAAK,EAAE,OAAO,EAAc,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK7E,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAgBpE,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/C,wBAAwB,CAAC,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC5D,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACpE,SAAS,IAAI,OAAO,CAAC;IACrB,YAAY,IAAI,iBAAiB,CAAC;IAClC,kBAAkB,IAAI,gBAAgB,CAAC;IAGvC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,cAAc,IAAI,IAAI,CAAC;IACvB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AA8ZD,eAAO,MAAM,MAAM;qBAvEK,OAAO,aAAa,iBAAiB,KAAG,OAAO;EAyErE,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/src/http/Kernel.js

@@ -111,41 +111,39 @@ const maybeSetKernelTraceRoute = (traceSpan, method, routeLabel) => {
         return;
     OpenTelemetry.setHttpRoute(traceSpan.span, method, routeLabel);
 };
-const runKernelPipeline = async (router, globalMiddleware, routeMiddleware, req, res, context, traceSpan) => {
-    const route = resolveRouteWithPreflightFallback(router, req.getMethod(), req.getPath());
-    if (route === null) {
-        const routeLabel = 'not_found';
-        maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
-        const handleNotFound = ErrorRouting.handleNotFound;
-        await handleNotFound(req, res, context.requestId);
-        return routeLabel;
-    }
-    // Safe type guard to ensure route.routePath is a non-empty string before calling .trim()
-    const hasNonEmptyRoutePath = (r) => {
-        if (typeof r !== 'object' || r === null)
-            return false;
-        const rp = r.routePath;
-        return typeof rp === 'string' && rp.trim() !== '';
+const runMiddlewareChain = async (middleware, req, res, terminal) => {
+    let index = 0;
+    const next = async () => {
+        if (index < middleware.length) {
+            const mw = middleware[index++];
+            await mw(req, res, next);
+            return;
+        }
+        await terminal();
     };
-    const routeLabel = hasNonEmptyRoutePath(route) ? route.routePath : req.getPath();
-    maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
-    // Use a typed view of the matched route to avoid unsafe member access
-    const matchedRoute = route;
-    // Coerce route params (which may be undefined or non-string) into the
-    // expected Record<string, string> shape required by Request.setParams.
+    await next();
+};
+// Safe type guard to ensure route.routePath is a non-empty string before calling .trim()
+const hasNonEmptyRoutePath = (r) => {
+    if (typeof r !== 'object' || r === null)
+        return false;
+    const rp = r.routePath;
+    return typeof rp === 'string' && rp.trim() !== '';
+};
+const coerceRouteParams = (params) => {
     const safeParams = {};
-    if (typeof matchedRoute.params === 'object' && matchedRoute.params !== null) {
-        for (const [k, v] of Object.entries(matchedRoute.params)) {
-            if (v === undefined || v === null)
-                continue;
-            safeParams[k] = typeof v === 'string' ? v : String(v);
-        }
+    if (typeof params !== 'object' || params === null)
+        return safeParams;
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        safeParams[k] = typeof v === 'string' ? v : String(v);
     }
-    req.setParams(safeParams);
-    const routeMiddlewareNames = getRouteMiddlewareNames(matchedRoute);
-    req.context['traceRouteMiddleware'] = routeMiddlewareNames;
+    return safeParams;
+};
+const resolveWrappedRouteMiddleware = (routeMiddlewareNames, routeMiddleware) => {
     const traceMiddlewareEmitter = getTraceMiddlewareEmitter();
-    const resolvedRouteMiddleware = routeMiddlewareNames
+    return routeMiddlewareNames
         .map((name) => ({ name, middleware: routeMiddleware[name] }))
         .filter((entry) => typeof entry.middleware === 'function')
         .map(({ name, middleware }) => {
@@ -163,17 +161,37 @@ const runKernelPipeline = async (router, globalMiddleware, routeMiddleware, req,
         };
         return wrapped;
     });
-    const middlewareToRun = [...globalMiddleware, ...resolvedRouteMiddleware];
-    let index = 0;
-    const next = async () => {
-        if (index < middlewareToRun.length) {
-            const mw = middlewareToRun[index++];
-            await mw(req, res, next);
-            return;
-        }
+};
+const runNotFoundPipeline = async (globalMiddleware, req, res, context, traceSpan) => {
+    // Run global middleware (including HttpWatcher) so routing 404s are still observed.
+    // Route middleware is intentionally skipped — there is no matched route.
+    const routeLabel = 'not_found';
+    maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
+    req.context['traceRouteMiddleware'] = [];
+    const handleNotFound = ErrorRouting.handleNotFound;
+    await runMiddlewareChain(globalMiddleware, req, res, async () => {
+        await handleNotFound(req, res, context.requestId);
+    });
+    return routeLabel;
+};
+const runKernelPipeline = async (router, globalMiddleware, routeMiddleware, req, res, context, traceSpan) => {
+    const route = resolveRouteWithPreflightFallback(router, req.getMethod(), req.getPath());
+    if (route === null) {
+        return runNotFoundPipeline(globalMiddleware, req, res, context, traceSpan);
+    }
+    const matchedRoute = route;
+    const routeLabel = hasNonEmptyRoutePath(matchedRoute) ? matchedRoute.routePath : req.getPath();
+    maybeSetKernelTraceRoute(traceSpan, context.method, routeLabel);
+    req.setParams(coerceRouteParams(matchedRoute.params));
+    const routeMiddlewareNames = getRouteMiddlewareNames(matchedRoute);
+    req.context['traceRouteMiddleware'] = routeMiddlewareNames;
+    const middlewareToRun = [
+        ...globalMiddleware,
+        ...resolveWrappedRouteMiddleware(routeMiddlewareNames, routeMiddleware),
+    ];
+    await runMiddlewareChain(middlewareToRun, req, res, async () => {
         await matchedRoute.handler(req, res);
-    };
-    await next();
+    });
     return routeLabel;
 };
 const finalizeKernelObservability = (context, res, routeLabel, thrown, traceSpan) => {

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v3.0.4
+ * @zintrust/core v3.0.6
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-07-14T19:37:30.278Z
+ *   Built: 2026-07-17T06:17:14.731Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-07-14T19:37:30.239Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-07-17T06:17:14.680Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';

package/src/orm/QueryBuilder.d.ts

@@ -17,6 +17,14 @@ export interface NormalizedTextOptions {
     trim?: boolean;
     lowercase?: boolean;
 }
+export interface IJoinOnBuilder {
+    on(left: string, operator: string, right: string): IJoinOnBuilder;
+}
+export type LatestPerOptions = {
+    orderBy: Array<[string, 'ASC' | 'DESC']>;
+    alias?: string;
+};
+export type JoinOnInput = string | ((on: IJoinOnBuilder) => unknown);
 /**
  * Result returned from INSERT operations
  * Provides access to the created record ID, affected rows count, and the full record if available
@@ -34,6 +42,11 @@ export interface QueryBuilderOptions {
 export interface PaginationOptions {
     baseUrl?: string;
     query?: PaginationQuery;
+    /**
+     * When joins are present, paginate totals use COUNT(DISTINCT …).
+     * Defaults to `<table>.id`. Pass an explicit safe identifier path when the primary key differs.
+     */
+    countDistinct?: string;
 }
 export type EagerLoadConstraint = (builder: IQueryBuilder) => IQueryBuilder;
 export type EagerLoadConstraints = Record<string, EagerLoadConstraint>;
@@ -49,13 +62,20 @@ export interface IQueryBuilder {
     whereNormalized(column: string, value: unknown, options?: NormalizedTextOptions): IQueryBuilder;
     orWhereNormalized(column: string, value: unknown, options?: NormalizedTextOptions): IQueryBuilder;
     whereNull(column: string): IQueryBuilder;
+    whereNotNull(column: string): IQueryBuilder;
     whereIn(column: string, values: unknown[]): IQueryBuilder;
     whereNotIn(column: string, values: unknown[]): IQueryBuilder;
+    whereColumn(left: string, operator: string, right: string): IQueryBuilder;
+    whereExists(callback: (builder: IQueryBuilder) => unknown): IQueryBuilder;
+    whereNotExists(callback: (builder: IQueryBuilder) => unknown): IQueryBuilder;
+    from(table: string): IQueryBuilder;
     withTrashed(): IQueryBuilder;
     onlyTrashed(): IQueryBuilder;
     withoutTrashed(): IQueryBuilder;
-    join(table: string, on: string): IQueryBuilder;
-    leftJoin(table: string, on: string): IQueryBuilder;
+    join(table: string, on: JoinOnInput): IQueryBuilder;
+    leftJoin(table: string, on: JoinOnInput): IQueryBuilder;
+    groupBy(...columns: string[]): IQueryBuilder;
+    latestPer(partitionBy: string | string[], options: LatestPerOptions): IQueryBuilder;
     orderBy(column: string, direction?: 'ASC' | 'DESC'): IQueryBuilder;
     inRandomOrder(): IQueryBuilder;
     limit(count: number): IQueryBuilder;
@@ -72,6 +92,7 @@ export interface IQueryBuilder {
     getJoins(): Array<{
         table: string;
         on: string;
+        type: 'INNER' | 'LEFT';
     }>;
     isReadOperation(): boolean;
     toSQL(): string;

package/src/orm/QueryBuilder.d.ts.map

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

package/src/orm/QueryBuilder.js

@@ -110,7 +110,17 @@ const buildNormalizedColumnSql = (column, dialect, options) => {
     return sql;
 };
 const isWhereGroupClause = (value) => 'kind' in value && value.kind === 'group';
+const isWhereExistsClause = (value) => 'kind' in value && value.kind === 'exists';
+const isWhereColumnCompareClause = (value) => 'kind' in value && value.kind === 'column-compare';
 const normalizeOperator = (operator) => operator.trim().toUpperCase();
+const ALLOWED_COLUMN_COMPARE_OPERATORS = new Set(['=', '!=', '<>', '<', '<=', '>', '>=']);
+const assertSafeColumnCompareOperator = (operator) => {
+    const normalized = operator.trim();
+    if (!ALLOWED_COLUMN_COMPARE_OPERATORS.has(normalized)) {
+        throw ErrorFactory.createDatabaseError('Unsafe SQL column comparison operator');
+    }
+    return normalized;
+};
 const ALLOWED_OPERATORS = new Set([
     '=',
     '==',
@@ -289,19 +299,49 @@ const compileSingleWhereClause = (clause, dialect) => {
         return nullClause;
     return compileComparisonWhereClause(columnSql, operator, clause.value, clause.expression, clause.normalization);
 };
+const compileColumnCompareClause = (clause, dialect) => {
+    assertSafeIdentifierPath(clause.left, 'where column left');
+    assertSafeIdentifierPath(clause.right, 'where column right');
+    const operator = assertSafeColumnCompareOperator(clause.operator);
+    return {
+        sql: `${escapeIdentifier(clause.left, dialect)} ${operator} ${escapeIdentifier(clause.right, dialect)}`,
+        parameters: [],
+    };
+};
+const compileExistsClause = (clause, dialect) => {
+    assertSafeIdentifierPath(clause.table, 'exists table');
+    const inner = compileWhereFragments(clause.conditions, dialect);
+    const whereSql = inner.sql.length > 0 ? ` WHERE ${inner.sql}` : '';
+    const keyword = clause.not ? 'NOT EXISTS' : 'EXISTS';
+    return {
+        sql: `${keyword} (SELECT 1 FROM ${escapeIdentifier(clause.table, dialect)}${whereSql})`,
+        parameters: inner.parameters,
+    };
+};
+const compileWherePredicate = (condition, dialect) => {
+    if (isWhereGroupClause(condition)) {
+        const compiled = compileWhereFragments(condition.conditions, dialect);
+        return { ...compiled, grouped: true };
+    }
+    if (isWhereExistsClause(condition)) {
+        return { ...compileExistsClause(condition, dialect), grouped: false };
+    }
+    if (isWhereColumnCompareClause(condition)) {
+        return { ...compileColumnCompareClause(condition, dialect), grouped: false };
+    }
+    return { ...compileSingleWhereClause(condition, dialect), grouped: false };
+};
 const compileWhereFragments = (conditions, dialect) => {
     if (conditions.length === 0)
         return { sql: '', parameters: [] };
     const parameters = [];
     const fragments = [];
     for (const condition of conditions) {
-        const compiled = isWhereGroupClause(condition)
-            ? compileWhereFragments(condition.conditions, dialect)
-            : compileSingleWhereClause(condition, dialect);
+        const compiled = compileWherePredicate(condition, dialect);
         if (compiled.sql.length === 0)
             continue;
         parameters.push(...compiled.parameters);
-        const fragment = isWhereGroupClause(condition) ? `(${compiled.sql})` : compiled.sql;
+        const fragment = compiled.grouped ? `(${compiled.sql})` : compiled.sql;
         const boolean = normalizeClauseBoolean(condition.boolean);
         fragments.push(fragments.length === 0 ? fragment : `${boolean} ${fragment}`);
     }
@@ -386,35 +426,171 @@ const buildLimitOffsetClause = (limit, offset) => {
 // `users.id = profiles.user_id`). Operator alternation lists the two-char
 // operators before their single-char prefixes so `<=`/`>=`/`<>` win the match.
 const JOIN_CONDITION = /^([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)\s*(=|!=|<>|<=|>=|<|>)\s*([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)$/;
+const parseJoinOnTerms = (on) => {
+    const parts = on
+        .split(/\s+AND\s+/i)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        throw ErrorFactory.createDatabaseError('Unsafe SQL join condition');
+    }
+    return parts.map((part) => {
+        const match = JOIN_CONDITION.exec(part);
+        if (!match) {
+            throw ErrorFactory.createDatabaseError('Unsafe SQL join condition');
+        }
+        const [, left, op, right] = match;
+        return { left: left ?? '', op: op ?? '=', right: right ?? '' };
+    });
+};
+const resolveJoinOnInput = (on) => {
+    if (typeof on === 'string') {
+        // Validate early so bad ON strings fail at builder time, not only at compile.
+        const terms = parseJoinOnTerms(on);
+        return terms.map((term) => `${term.left} ${term.op} ${term.right}`).join(' AND ');
+    }
+    const terms = [];
+    const joinOnBuilder = Object.freeze({
+        on(left, operator, right) {
+            assertSafeIdentifierPath(left, 'join on left');
+            assertSafeIdentifierPath(right, 'join on right');
+            const op = assertSafeColumnCompareOperator(operator);
+            terms.push({ left: left.trim(), op, right: right.trim() });
+            return joinOnBuilder;
+        },
+    });
+    on(joinOnBuilder);
+    if (terms.length === 0) {
+        throw ErrorFactory.createDatabaseError('Join ON builder requires at least one on() term');
+    }
+    return terms.map((term) => `${term.left} ${term.op} ${term.right}`).join(' AND ');
+};
+const buildJoinOnSql = (on, dialect) => {
+    const terms = parseJoinOnTerms(on);
+    return terms
+        .map((term) => `${escapeIdentifier(term.left, dialect)} ${term.op} ${escapeIdentifier(term.right, dialect)}`)
+        .join(' AND ');
+};
 const buildJoinClause = (joins, dialect) => joins
     .map(({ table, on, type }) => {
     assertSafeIdentifierPath(table, 'join table');
-    const match = JOIN_CONDITION.exec(on.trim());
-    if (!match) {
-        throw ErrorFactory.createDatabaseError('Unsafe SQL join condition');
-    }
-    const [, left, op, right] = match;
-    return ` ${type} JOIN ${escapeIdentifier(table, dialect)} ON ${escapeIdentifier(left, dialect)} ${op} ${escapeIdentifier(right, dialect)}`;
+    return ` ${type} JOIN ${escapeIdentifier(table, dialect)} ON ${buildJoinOnSql(on, dialect)}`;
 })
     .join('');
-const buildSelectQuery = (state) => {
+const buildGroupByClause = (columns, dialect) => {
+    if (columns.length === 0)
+        return '';
+    const parts = columns.map((column) => {
+        const col = column.trim();
+        assertSafeIdentifierPath(col, 'group by column');
+        return escapeIdentifier(col, dialect);
+    });
+    return ` GROUP BY ${parts.join(', ')}`;
+};
+const buildWindowOrderBySql = (orderBy, dialect) => {
+    if (orderBy.length === 0) {
+        throw ErrorFactory.createDatabaseError('latestPer requires at least one orderBy column');
+    }
+    return orderBy
+        .map((clause) => {
+        assertSafeIdentifierPath(clause.column, 'window order by column');
+        return `${escapeIdentifier(clause.column, dialect)} ${clause.direction}`;
+    })
+        .join(', ');
+};
+const buildWindowPartitionSql = (partitionBy, dialect) => {
+    if (partitionBy.length === 0) {
+        throw ErrorFactory.createDatabaseError('latestPer requires at least one partition column');
+    }
+    return partitionBy
+        .map((column) => {
+        assertSafeIdentifierPath(column, 'window partition column');
+        return escapeIdentifier(column, dialect);
+    })
+        .join(', ');
+};
+const buildBaseSelectBody = (state, columnsSql, options) => {
     if (state.tableName.length > 0) {
         assertSafeIdentifierPath(state.tableName, 'table name');
     }
-    const columns = buildSelectClause(state.selectColumns, state.dialect);
     const fromClause = state.tableName.length > 0 ? ` FROM ${escapeIdentifier(state.tableName, state.dialect)}` : '';
     const joinClause = buildJoinClause(state.joins, state.dialect);
     const where = compileWhere(getEffectiveWhereConditions(state), state.dialect);
-    const sql = `SELECT ${columns}${fromClause}${joinClause}${where.sql}${buildOrderByClause(state.orderByClauses, state.randomOrder, state.dialect)}${buildLimitOffsetClause(state.limitValue, state.offsetValue)}`;
+    const groupByClause = options.includeGroupBy
+        ? buildGroupByClause(state.groupByColumns, state.dialect)
+        : '';
+    const orderLimit = options.includeOrderLimit
+        ? `${buildOrderByClause(state.orderByClauses, state.randomOrder, state.dialect)}${buildLimitOffsetClause(state.limitValue, state.offsetValue)}`
+        : '';
+    const sql = `SELECT ${columnsSql}${fromClause}${joinClause}${where.sql}${groupByClause}${orderLimit}`;
     return { sql, parameters: where.parameters };
 };
-const buildCountQuery = (state) => {
+const buildLatestPerQuery = (state) => {
+    const latest = state.latestPer;
+    if (latest === undefined) {
+        throw ErrorFactory.createDatabaseError('latestPer state is missing');
+    }
+    const baseColumns = buildSelectClause(state.selectColumns, state.dialect);
+    const partitionSql = buildWindowPartitionSql(latest.partitionBy, state.dialect);
+    const orderSql = buildWindowOrderBySql(latest.orderBy, state.dialect);
+    const aliasSql = escapeIdentifier(latest.alias, state.dialect);
+    const windowSql = `ROW_NUMBER() OVER (PARTITION BY ${partitionSql} ORDER BY ${orderSql}) AS ${aliasSql}`;
+    const innerColumns = baseColumns === '*' || baseColumns.trim().length === 0
+        ? `*, ${windowSql}`
+        : `${baseColumns}, ${windowSql}`;
+    // Window wrap owns outer ORDER/LIMIT; inner keeps filters/joins only.
+    const inner = buildBaseSelectBody(state, innerColumns, {
+        includeOrderLimit: false,
+        includeGroupBy: false,
+    });
+    const outerOrderLimit = `${buildOrderByClause(state.orderByClauses, state.randomOrder, state.dialect)}${buildLimitOffsetClause(state.limitValue, state.offsetValue)}`;
+    const sql = `SELECT * FROM (${inner.sql}) AS ${escapeIdentifier('_zt_window', state.dialect)} WHERE ${aliasSql} = 1${outerOrderLimit}`;
+    return { sql, parameters: inner.parameters };
+};
+const buildSelectQuery = (state) => {
+    if (state.latestPer !== undefined) {
+        return buildLatestPerQuery(state);
+    }
+    const columns = buildSelectClause(state.selectColumns, state.dialect);
+    return buildBaseSelectBody(state, columns, {
+        includeOrderLimit: true,
+        includeGroupBy: true,
+    });
+};
+const buildCountQuery = (state, options) => {
     if (state.tableName.length > 0) {
         assertSafeIdentifierPath(state.tableName, 'table name');
     }
+    // GROUP BY / window queries: count rows of the unconstrained result set via subquery.
+    if (state.groupByColumns.length > 0 || state.latestPer !== undefined) {
+        const prevLimit = state.limitValue;
+        const prevOffset = state.offsetValue;
+        const prevOrder = state.orderByClauses;
+        const prevRandom = state.randomOrder;
+        state.limitValue = undefined;
+        state.offsetValue = undefined;
+        state.orderByClauses = [];
+        state.randomOrder = false;
+        const inner = buildSelectQuery(state);
+        state.limitValue = prevLimit;
+        state.offsetValue = prevOffset;
+        state.orderByClauses = prevOrder;
+        state.randomOrder = prevRandom;
+        const sql = `SELECT COUNT(*) AS total FROM (${inner.sql}) AS ${escapeIdentifier('_zt_count', state.dialect)}`;
+        return { sql, parameters: inner.parameters };
+    }
     const fromClause = state.tableName.length > 0 ? ` FROM ${escapeIdentifier(state.tableName, state.dialect)}` : '';
+    const joinClause = buildJoinClause(state.joins, state.dialect);
     const where = compileWhere(getEffectiveWhereConditions(state), state.dialect);
-    const sql = `SELECT COUNT(*) AS total${fromClause}${where.sql}`;
+    let countExpr = 'COUNT(*)';
+    if (state.joins.length > 0) {
+        const distinctCol = typeof options?.countDistinct === 'string' && options.countDistinct.trim().length > 0
+            ? options.countDistinct.trim()
+            : `${state.tableName}.id`;
+        assertSafeIdentifierPath(distinctCol, 'count distinct column');
+        countExpr = `COUNT(DISTINCT ${escapeIdentifier(distinctCol, state.dialect)})`;
+    }
+    const sql = `SELECT ${countExpr} AS total${fromClause}${joinClause}${where.sql}`;
     return { sql, parameters: where.parameters };
 };
 const applyWhereCondition = (state, column, operator, value, boolean = 'AND', extra = {}) => {
@@ -449,11 +625,81 @@ const createPredicateState = (dialect) => ({
     orderByClauses: [],
     randomOrder: false,
     joins: [],
+    groupByColumns: [],
     eagerLoads: [],
     eagerLoadConstraints: {},
     eagerLoadCounts: [],
     dialect,
 });
+const applyWhereColumnCompare = (state, left, operator, right, boolean = 'AND') => {
+    assertSafeIdentifierPath(left, 'where column left');
+    assertSafeIdentifierPath(right, 'where column right');
+    const op = assertSafeColumnCompareOperator(operator);
+    state.whereConditions.push({
+        kind: 'column-compare',
+        boolean,
+        left: left.trim(),
+        operator: op,
+        right: right.trim(),
+    });
+};
+const applyWhereExists = (state, callback, not, boolean = 'AND') => {
+    const subState = createPredicateState(state.dialect);
+    const subBuilder = createBuilder(subState);
+    callback(subBuilder);
+    const table = subState.tableName.trim();
+    if (table.length === 0) {
+        throw ErrorFactory.createDatabaseError('EXISTS subquery requires from(table)');
+    }
+    assertSafeIdentifierPath(table, 'exists table');
+    state.whereConditions.push({
+        kind: 'exists',
+        not,
+        boolean,
+        table,
+        conditions: subState.whereConditions,
+    });
+};
+const applyJoin = (state, table, on, type) => {
+    assertSafeIdentifierPath(table, 'join table');
+    const onSql = resolveJoinOnInput(on);
+    state.joins.push({ table: table.trim(), on: onSql, type });
+};
+const applyGroupBy = (state, columns) => {
+    for (const column of columns) {
+        const col = String(column).trim();
+        assertSafeIdentifierPath(col, 'group by column');
+        state.groupByColumns.push(col);
+    }
+};
+const applyLatestPer = (state, partitionBy, options) => {
+    const partitions = (Array.isArray(partitionBy) ? partitionBy : [partitionBy])
+        .map((column) => String(column).trim())
+        .filter((column) => column.length > 0);
+    if (partitions.length === 0) {
+        throw ErrorFactory.createDatabaseError('latestPer requires at least one partition column');
+    }
+    for (const column of partitions) {
+        assertSafeIdentifierPath(column, 'window partition column');
+    }
+    if (!Array.isArray(options.orderBy) || options.orderBy.length === 0) {
+        throw ErrorFactory.createDatabaseError('latestPer requires at least one orderBy column');
+    }
+    const orderBy = options.orderBy.map(([column, direction]) => {
+        const col = String(column).trim();
+        assertSafeIdentifierPath(col, 'window order by column');
+        return { column: col, direction: normalizeOrderDirection(direction) };
+    });
+    const aliasRaw = typeof options.alias === 'string' && options.alias.trim().length > 0
+        ? options.alias.trim()
+        : 'rn';
+    assertSafeIdentifier(aliasRaw, 'window alias');
+    state.latestPer = {
+        partitionBy: partitions,
+        orderBy,
+        alias: aliasRaw,
+    };
+};
 const applyWhereGroup = (state, callback, boolean) => {
     const groupState = createPredicateState(state.dialect);
     const groupBuilder = createBuilder(groupState);
@@ -474,6 +720,10 @@ const flattenWherePredicates = (conditions) => {
             flattened.push(...flattenWherePredicates(condition.conditions));
             continue;
         }
+        // Exists / column-compare predicates are not simple column clauses.
+        if (isWhereExistsClause(condition) || isWhereColumnCompareClause(condition)) {
+            continue;
+        }
         flattened.push(condition);
     }
     return flattened;
@@ -596,7 +846,9 @@ async function executePaginate(builder, state, db, page, perPage, options) {
         throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
     const safePage = normalizePaginationValue(page, 'page');
     const safePerPage = normalizePaginationValue(perPage, 'perPage');
-    const countQuery = buildCountQuery(state);
+    const countQuery = buildCountQuery(state, {
+        countDistinct: options?.countDistinct,
+    });
     const countRows = (await db.query(countQuery.sql, countQuery.parameters, true));
     const rawTotal = countRows.at(0)?.['total'];
     const total = typeof rawTotal === 'bigint' ? Number(rawTotal) : Number(rawTotal ?? 0);
@@ -682,6 +934,7 @@ function attachWhereMethods(builder, state) {
         return builder;
     };
     builder.whereNull = (column) => builder.where(column, 'IS', null);
+    builder.whereNotNull = (column) => builder.where(column, 'IS NOT', null);
     builder.whereIn = (column, values) => {
         builder.where(column, 'IN', values);
         return builder;
@@ -690,6 +943,24 @@ function attachWhereMethods(builder, state) {
         builder.where(column, 'NOT IN', values);
         return builder;
     };
+    builder.whereColumn = (left, operator, right) => {
+        applyWhereColumnCompare(state, left, operator, right, 'AND');
+        return builder;
+    };
+    builder.whereExists = (callback) => {
+        applyWhereExists(state, callback, false, 'AND');
+        return builder;
+    };
+    builder.whereNotExists = (callback) => {
+        applyWhereExists(state, callback, true, 'AND');
+        return builder;
+    };
+    builder.from = (table) => {
+        const name = String(table).trim();
+        assertSafeIdentifierPath(name, 'table name');
+        state.tableName = name;
+        return builder;
+    };
 }
 function attachSoftDeleteMethods(builder, state) {
     builder.withTrashed = () => {
@@ -722,11 +993,19 @@ function attachSoftDeleteMethods(builder, state) {
 }
 function attachJoinOrderPagingMethods(builder, state) {
     builder.join = (tableJoin, on) => {
-        state.joins.push({ table: tableJoin, on, type: 'INNER' });
+        applyJoin(state, tableJoin, on, 'INNER');
         return builder;
     };
     builder.leftJoin = (tableJoin, on) => {
-        state.joins.push({ table: tableJoin, on, type: 'LEFT' });
+        applyJoin(state, tableJoin, on, 'LEFT');
+        return builder;
+    };
+    builder.groupBy = (...columns) => {
+        applyGroupBy(state, columns);
+        return builder;
+    };
+    builder.latestPer = (partitionBy, options) => {
+        applyLatestPer(state, partitionBy, options);
         return builder;
     };
     builder.orderBy = (column, direction = 'ASC') => {
@@ -1312,6 +1591,7 @@ export const QueryBuilder = Object.freeze({
             orderByClauses: [],
             randomOrder: false,
             joins: [],
+            groupByColumns: [],
             eagerLoads: [],
             eagerLoadConstraints: {},
             eagerLoadCounts: [],

package/src/worker-runtime/rpc-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-client.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/rpc-client.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAWF,eAAO,MAAM,oBAAoB,QAAO,OAAkC,CAAC;AAE3E,eAAO,MAAM,4BAA4B,QAAO,MAI/C,CAAC;AAOF,eAAO,MAAM,8BAA8B,QAAO,OAC0B,CAAC;AAiO7E,wFAAwF;AACxF,eAAO,MAAM,OAAO,GAClB,WAAW,MAAM,EACjB,qBAAqB,MAAM,KAC1B,OAAO,CAAC,SAAS,GAAG,SAAS,CAkB/B,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,MAAM,GACjB,WAAW,MAAM,EACjB,OAAO,MAAM,EACb,cAAc,OAAO,KACpB,OAAO,CAAC,IAAI,CAOd,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,OAAO,GAAU,WAAW,MAAM,EAAE,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAW5F,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,WAAW,QAAa,OAAO,CAAC,gBAAgB,EAAE,CAO9D,CAAC"}
+{"version":3,"file":"rpc-client.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/rpc-client.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAWF,eAAO,MAAM,oBAAoB,QAAO,OAAkC,CAAC;AAE3E,eAAO,MAAM,4BAA4B,QAAO,MAI/C,CAAC;AAOF,eAAO,MAAM,8BAA8B,QAAO,OAC0B,CAAC;AAkO7E,wFAAwF;AACxF,eAAO,MAAM,OAAO,GAClB,WAAW,MAAM,EACjB,qBAAqB,MAAM,KAC1B,OAAO,CAAC,SAAS,GAAG,SAAS,CAkB/B,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,MAAM,GACjB,WAAW,MAAM,EACjB,OAAO,MAAM,EACb,cAAc,OAAO,KACpB,OAAO,CAAC,IAAI,CAOd,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,OAAO,GAAU,WAAW,MAAM,EAAE,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAW5F,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,WAAW,QAAa,OAAO,CAAC,gBAAgB,EAAE,CAO9D,CAAC"}

package/src/worker-runtime/rpc-client.js

@@ -44,6 +44,8 @@ const queuePayload = (extra) => {
     return db === undefined ? extra : { db, ...extra };
 };
 const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const isPullJobId = (value) => (typeof value === 'string' && value.trim() !== '') ||
+    (typeof value === 'number' && Number.isFinite(value));
 const parseHeaderEnv = (key) => {
     const raw = Env.get(key, '').trim();
     if (raw === '')
@@ -145,6 +147,24 @@ const call = async (service, method, payload = {}) => {
     }
     return parsed.result;
 };
+const resolvePulledJobPayload = (record) => {
+    if (hasOwn(record, 'payload'))
+        return record['payload'];
+    if (hasOwn(record, 'data'))
+        return record['data'];
+    throw ErrorFactory.createConfigError('Worker queue pull returned a job without payload/data');
+};
+const resolvePulledJobAttempts = (record) => {
+    const rawAttempts = hasOwn(record, 'attempts') ? record['attempts'] : record['attemptsMade'];
+    return typeof rawAttempts === 'number' && Number.isFinite(rawAttempts)
+        ? Math.max(0, Math.floor(rawAttempts))
+        : 0;
+};
+const resolvePulledJobName = (record) => {
+    return typeof record['name'] === 'string' && record['name'].trim() !== ''
+        ? record['name'].trim()
+        : 'default';
+};
 const normalizePulledJob = (raw) => {
     if (raw === null || raw === undefined)
         return undefined;
@@ -153,27 +173,14 @@ const normalizePulledJob = (raw) => {
     }
     const record = raw;
     const rawId = record['id'];
-    if (!((typeof rawId === 'string' && rawId.trim() !== '') ||
-        (typeof rawId === 'number' && Number.isFinite(rawId)))) {
+    if (!isPullJobId(rawId)) {
         throw ErrorFactory.createConfigError('Worker queue pull returned a job without an id');
     }
-    const hasPayload = hasOwn(record, 'payload');
-    const hasData = hasOwn(record, 'data');
-    if (!hasPayload && !hasData) {
-        throw ErrorFactory.createConfigError('Worker queue pull returned a job without payload/data');
-    }
-    const rawAttempts = hasOwn(record, 'attempts') ? record['attempts'] : record['attemptsMade'];
-    const attempts = typeof rawAttempts === 'number' && Number.isFinite(rawAttempts)
-        ? Math.max(0, Math.floor(rawAttempts))
-        : 0;
-    const name = typeof record['name'] === 'string' && record['name'].trim() !== ''
-        ? record['name'].trim()
-        : 'default';
     return {
         id: String(rawId),
-        name,
-        payload: hasPayload ? record['payload'] : record['data'],
-        attempts,
+        name: resolvePulledJobName(record),
+        payload: resolvePulledJobPayload(record),
+        attempts: resolvePulledJobAttempts(record),
     };
 };
 const createZedgiBullMqError = (method, error) => {