@baasix/baasix 0.1.0

package/dist/utils/orderUtils.js

@@ -0,0 +1,249 @@
+/**
+ * Order/Sort Utilities Module for Drizzle ORM
+ *
+ * This module provides sorting utilities that convert Sequelize-style
+ * sort objects into Drizzle ORM orderBy clauses.
+ *
+ * Features:
+ * - Convert sort objects to Drizzle orderBy
+ * - Support ascending/descending sort
+ * - Handle nested relation sorting
+ * - Support special fields (aggregate functions, computed columns)
+ * - Full-text search relevance ranking
+ */
+import { sql, asc, desc } from 'drizzle-orm';
+/**
+ * Process a single sort field
+ * Handles both simple fields and complex nested relation paths
+ */
+function processSortField(fieldPath, direction, ctx) {
+    const normalizedDirection = direction.toUpperCase();
+    // Handle nested relation paths
+    if (fieldPath.includes('.')) {
+        const parts = fieldPath.split('.');
+        // For nested relation paths (e.g., "userRoles.role.name" or "author.name"),
+        // the table alias is the SECOND-TO-LAST part (the immediate parent relation),
+        // and the column is the LAST part.
+        //
+        // Example: "userRoles.role.name"
+        //   - userRoles is aliased as "userRoles" (HasMany JOIN)
+        //   - role is aliased as "role" (BelongsTo nested JOIN under userRoles)
+        //   - We ORDER BY "role"."name"
+        //
+        // Example: "author.name"
+        //   - author is aliased as "author"
+        //   - We ORDER BY "author"."name"
+        const relationName = parts[parts.length - 2]; // Second-to-last part is the table alias
+        const columnName = parts[parts.length - 1]; // Last part is the column
+        const sqlColumn = sql.raw(`"${relationName}"."${columnName}"`);
+        return normalizedDirection === 'ASC' ? asc(sqlColumn) : desc(sqlColumn);
+    }
+    // Direct field - check if it exists in schema
+    if (ctx.schema && ctx.schema[fieldPath]) {
+        const column = ctx.schema[fieldPath];
+        return normalizedDirection === 'ASC' ? asc(column) : desc(column);
+    }
+    // Fallback to raw SQL for computed/aggregate fields
+    const sqlColumn = ctx.tableName
+        ? sql.raw(`"${ctx.tableName}"."${fieldPath}"`)
+        : sql.raw(`"${fieldPath}"`);
+    return normalizedDirection === 'ASC' ? asc(sqlColumn) : desc(sqlColumn);
+}
+/**
+ * Convert Sequelize-style sort object to Drizzle orderBy array
+ *
+ * @param sort - Sort object or JSON string
+ * @param ctx - Sort context with table schema
+ * @returns Array of Drizzle orderBy SQL expressions
+ *
+ * @example
+ * ```typescript
+ * const sort = { name: 'ASC', createdAt: 'DESC' };
+ *
+ * const orderBy = drizzleOrder(sort, {
+ *   table: usersTable,
+ *   tableName: 'users',
+ *   schema: usersTable
+ * });
+ *
+ * // Use in query:
+ * const results = await db.select().from(usersTable).orderBy(...orderBy);
+ * ```
+ */
+export function drizzleOrder(sort, ctx) {
+    if (!sort)
+        return [];
+    // Parse JSON string if needed
+    let sortObject;
+    if (typeof sort === 'string') {
+        try {
+            sortObject = JSON.parse(sort);
+        }
+        catch (e) {
+            console.warn('Failed to parse sort string:', e);
+            return [];
+        }
+    }
+    else {
+        sortObject = sort;
+    }
+    // Convert each sort field to Drizzle orderBy
+    return Object.entries(sortObject).map(([field, direction]) => {
+        // Handle special _distance sorting
+        if (field === '_distance' && typeof direction === 'object') {
+            const distanceConfig = direction;
+            const { target, column, direction: sortDir } = distanceConfig;
+            // Build qualified field name
+            let fieldRef;
+            if (column.startsWith('"')) {
+                fieldRef = column;
+            }
+            else if (column.includes('.')) {
+                const [table, col] = column.split('.');
+                fieldRef = `"${table}"."${col}"`;
+            }
+            else if (ctx.tableName) {
+                fieldRef = `"${ctx.tableName}"."${column}"`;
+            }
+            else {
+                fieldRef = `"${column}"`;
+            }
+            return sortByDistance(fieldRef, { type: 'Point', coordinates: target }, sortDir);
+        }
+        return processSortField(field, direction, ctx);
+    });
+}
+/**
+ * Apply full-text search ranking to sort
+ * Used for relevance-based sorting when searching
+ *
+ * @param searchFields - Fields to search in
+ * @param searchQuery - Search query string
+ * @param ctx - Sort context
+ * @returns SQL for ts_rank ordering
+ */
+export function applyFullTextSearchRanking(searchFields, searchQuery, ctx) {
+    const tableName = ctx.tableName || 'table';
+    // Create concatenated string of all searchable fields using sql template
+    const fieldParts = searchFields.map(field => sql `COALESCE(${sql.raw(`"${tableName}"."${field}"`)}::text, '')`);
+    const concatFields = sql.join(fieldParts, sql ` || ' ' || `);
+    // Prepare the full-text search query (escape single quotes)
+    const tsQuery = searchQuery.trim().replace(/\s+/g, ":* & ") + ":*";
+    const escapedTsQuery = tsQuery.replace(/'/g, "''");
+    // Build ts_rank expression using sql template
+    const rankSQL = sql `ts_rank(to_tsvector('english', ${concatFields}), to_tsquery('english', ${escapedTsQuery}))`;
+    return desc(rankSQL);
+}
+/**
+ * Sort by aggregate function result
+ * Example: Sort by count of related records
+ */
+export function sortByAggregate(aggregateExpression, direction = 'DESC') {
+    const normalizedDirection = direction.toUpperCase();
+    return normalizedDirection === 'ASC' ? asc(aggregateExpression) : desc(aggregateExpression);
+}
+/**
+ * Sort by distance (for geo queries)
+ *
+ * @param fieldName - The geometry/geography field name
+ * @param referencePoint - GeoJSON point to measure distance from
+ * @param direction - Sort direction (usually ASC for nearest first)
+ */
+export function sortByDistance(fieldName, referencePoint, direction = 'ASC') {
+    const geoJSON = JSON.stringify(referencePoint);
+    // Use ST_DistanceSpheroid for accurate earth-surface distance calculations in meters
+    // This is more reliable than ::geography casting across different PostGIS versions
+    const spheroid = `SPHEROID["WGS 84",6378137,298.257223563]`;
+    const distanceSQL = sql `ST_DistanceSpheroid(${sql.raw(fieldName)}, ST_SetSRID(ST_GeomFromGeoJSON(${geoJSON}), 4326), ${spheroid})`;
+    const normalizedDirection = direction.toUpperCase();
+    return normalizedDirection === 'ASC' ? asc(distanceSQL) : desc(distanceSQL);
+}
+/**
+ * Sort by CASE expression (conditional sorting)
+ * Useful for custom sort orders
+ *
+ * @example
+ * ```typescript
+ * // Sort by status: active first, then pending, then inactive
+ * const sortExpr = sortByCase({
+ *   field: 'status',
+ *   cases: [
+ *     { when: 'active', then: 1 },
+ *     { when: 'pending', then: 2 },
+ *     { when: 'inactive', then: 3 }
+ *   ],
+ *   direction: 'ASC'
+ * });
+ * ```
+ */
+export function sortByCase(options) {
+    const { field, cases, direction = 'ASC', defaultValue = 999 } = options;
+    // Build CASE expression using sql template with parameterized values
+    const caseParts = cases.map(c => sql `WHEN ${sql.raw(`"${field}"`)} = ${c.when} THEN ${c.then}`);
+    const caseSQL = sql `CASE ${sql.join(caseParts, sql ` `)} ELSE ${defaultValue} END`;
+    const normalizedDirection = direction.toUpperCase();
+    return normalizedDirection === 'ASC' ? asc(caseSQL) : desc(caseSQL);
+}
+/**
+ * Sort nulls first or last
+ * PostgreSQL default: ASC puts nulls last, DESC puts nulls first
+ * This function allows explicit control
+ */
+export function sortWithNulls(column, direction = 'ASC', nullsFirst = false) {
+    const normalizedDirection = direction.toUpperCase();
+    const baseSort = normalizedDirection === 'ASC' ? asc(column) : desc(column);
+    // Use sql literals instead of sql.raw for keywords
+    if (nullsFirst) {
+        return sql `${baseSort} NULLS FIRST`;
+    }
+    else {
+        return sql `${baseSort} NULLS LAST`;
+    }
+}
+/**
+ * Parse sort string formats
+ * Supports various input formats:
+ * - "name" -> { name: 'ASC' }
+ * - "-name" -> { name: 'DESC' }
+ * - "name,createdAt" -> { name: 'ASC', createdAt: 'ASC' }
+ * - "-name,createdAt" -> { name: 'DESC', createdAt: 'ASC' }
+ */
+export function parseSortString(sortStr) {
+    if (!sortStr || sortStr.trim() === '')
+        return {};
+    const result = {};
+    const fields = sortStr.split(',').map(f => f.trim());
+    for (const field of fields) {
+        if (field.startsWith('-')) {
+            // Descending
+            result[field.substring(1)] = 'DESC';
+        }
+        else {
+            // Ascending
+            result[field] = 'ASC';
+        }
+    }
+    return result;
+}
+/**
+ * Combine multiple sort criteria
+ * Earlier criteria take precedence
+ */
+export function combineSorts(...sorts) {
+    const result = {};
+    // Process in reverse order so earlier sorts override later ones
+    for (let i = sorts.length - 1; i >= 0; i--) {
+        const sort = sorts[i];
+        if (sort) {
+            Object.assign(result, sort);
+        }
+    }
+    return result;
+}
+/**
+ * Default sort (by ID descending for most recent first)
+ */
+export function defaultSort(ctx) {
+    return drizzleOrder({ id: 'DESC' }, ctx);
+}
+//# sourceMappingURL=orderUtils.js.map

package/dist/utils/orderUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderUtils.js","sourceRoot":"","sources":["../../baasix/utils/orderUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAO,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAOlD;;;GAGG;AACH,SAAS,gBAAgB,CACvB,SAAiB,EACjB,SAAwB,EACxB,GAAgB;IAEhB,MAAM,mBAAmB,GAAG,SAAS,CAAC,WAAW,EAAoB,CAAC;IAEtE,+BAA+B;IAC/B,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAEnC,4EAA4E;QAC5E,8EAA8E;QAC9E,mCAAmC;QACnC,EAAE;QACF,iCAAiC;QACjC,yDAAyD;QACzD,wEAAwE;QACxE,gCAAgC;QAChC,EAAE;QACF,yBAAyB;QACzB,oCAAoC;QACpC,kCAAkC;QAClC,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,yCAAyC;QACvF,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,0BAA0B;QAEvE,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,YAAY,MAAM,UAAU,GAAG,CAAC,CAAC;QAC/D,OAAO,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1E,CAAC;IAED,8CAA8C;IAC9C,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACrC,OAAO,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpE,CAAC;IAED,oDAAoD;IACpD,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS;QAC7B,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,SAAS,MAAM,SAAS,GAAG,CAAC;QAC9C,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC;IAE9B,OAAO,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAC1B,IAA4C,EAC5C,GAAgB;IAEhB,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,8BAA8B;IAC9B,IAAI,UAAsB,CAAC;IAC3B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,8BAA8B,EAAE,CAAC,CAAC,CAAC;YAChD,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,6CAA6C;IAC7C,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE;QAC3D,mCAAmC;QACnC,IAAI,KAAK,KAAK,WAAW,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC3D,MAAM,cAAc,GAAG,SAAgB,CAAC;YACxC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC;YAE9D,6BAA6B;YAC7B,IAAI,QAAgB,CAAC;YACrB,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,QAAQ,GAAG,MAAM,CAAC;YACpB,CAAC;iBAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAChC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBACvC,QAAQ,GAAG,IAAI,KAAK,MAAM,GAAG,GAAG,CAAC;YACnC,CAAC;iBAAM,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBACzB,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,MAAM,MAAM,GAAG,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,IAAI,MAAM,GAAG,CAAC;YAC3B,CAAC;YAED,OAAO,cAAc,CACnB,QAAQ,EACR,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EACtC,OAAwB,CACzB,CAAC;QACJ,CAAC;QAED,OAAO,gBAAgB,CAAC,KAAK,EAAE,SAA0B,EAAE,GAAG,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACxC,YAAsB,EACtB,WAAmB,EACnB,GAAgB;IAEhB,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC;IAE3C,yEAAyE;IACzE,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAC1C,GAAG,CAAA,YAAY,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,MAAM,KAAK,GAAG,CAAC,aAAa,CACjE,CAAC;IACF,MAAM,YAAY,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAA,aAAa,CAAC,CAAC;IAE5D,4DAA4D;IAC5D,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACnE,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAEnD,8CAA8C;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAA,kCAAkC,YAAY,4BAA4B,cAAc,IAAI,CAAC;IAEhH,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,mBAAwB,EACxB,YAA2B,MAAM;IAEjC,MAAM,mBAAmB,GAAG,SAAS,CAAC,WAAW,EAAoB,CAAC;IACtE,OAAO,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,cAA+D,EAC/D,YAA2B,KAAK;IAEhC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IAC/C,qFAAqF;IACrF,mFAAmF;IACnF,MAAM,QAAQ,GAAG,0CAA0C,CAAC;IAC5D,MAAM,WAAW,GAAG,GAAG,CAAA,uBAAuB,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,mCAAmC,OAAO,aAAa,QAAQ,GAAG,CAAC;IAEnI,MAAM,mBAAmB,GAAG,SAAS,CAAC,WAAW,EAAoB,CAAC;IACtE,OAAO,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CAAC,OAK1B;IACC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,YAAY,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC;IAExE,qEAAqE;IACrE,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAC9B,GAAG,CAAA,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,IAAI,EAAE,CAC9D,CAAC;IAEF,MAAM,OAAO,GAAG,GAAG,CAAA,QAAQ,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAA,GAAG,CAAC,SAAS,YAAY,MAAM,CAAC;IAElF,MAAM,mBAAmB,GAAG,SAAS,CAAC,WAAW,EAAoB,CAAC;IACtE,OAAO,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAgB,EAChB,YAA2B,KAAK,EAChC,aAAsB,KAAK;IAE3B,MAAM,mBAAmB,GAAG,SAAS,CAAC,WAAW,EAAoB,CAAC;IAEtE,MAAM,QAAQ,GAAG,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE5E,mDAAmD;IACnD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,GAAG,CAAA,GAAG,QAAQ,cAAc,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,CAAA,GAAG,QAAQ,aAAa,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAEjD,MAAM,MAAM,GAAe,EAAE,CAAC;IAE9B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAErD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,aAAa;YACb,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,YAAY;YACZ,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAG,KAAwC;IACtE,MAAM,MAAM,GAAe,EAAE,CAAC;IAE9B,gEAAgE;IAChE,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,YAAY,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC"}

package/dist/utils/queryBuilder.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Query Builder Module for Drizzle ORM
+ *
+ * This module provides query building utilities that convert Sequelize-style
+ * filter/where objects into Drizzle ORM where conditions.
+ *
+ * Features:
+ * - Convert filter objects to Drizzle where conditions
+ * - Support AND/OR logical operators
+ * - Handle nested conditions and relations
+ * - Column qualification for joins
+ * - Type casting support
+ * - Pagination helpers
+ *
+ * RELATION PATH FILTERING:
+ * - Relation path filters (e.g., "userRoles.role.name") ARE NOW SUPPORTED
+ *   1. Parses relation paths into segments
+ *   2. Recursively resolves each segment by looking up relation metadata
+ *   3. Builds LEFT JOIN clauses dynamically
+ *   4. Returns the final column reference for the WHERE clause
+ *
+ *   Example usage:
+ *     conditions: {
+ *       "userRoles.role.name": { in: ["admin", "user"] },
+ *       "author.company.name": { eq: "ACME" }
+ *     }
+ *
+ *   The query builder will automatically generate the necessary JOINs:
+ *     LEFT JOIN userRoles_... ON ...
+ *     LEFT JOIN roles_... ON ...
+ *     LEFT JOIN companies_... ON ...
+ *
+ *   Joins are accumulated in ctx.joins array and must be applied by the caller.
+ *
+ * NOTES:
+ * - Currently supports BelongsTo, HasMany, and HasOne relations
+ * - BelongsToMany (many-to-many) uses simplified join (needs junction table support)
+ * - Coordination with the two-query approach for HasMany sorting is handled by the caller
+ */
+import { SQL } from 'drizzle-orm';
+import { JoinDefinition as RelationJoinDefinition } from './relationPathResolver.js';
+import type { FilterObject, QueryContext, PaginationOptions, PaginationMetadata } from '../types/index.js';
+export type { FilterObject, QueryContext, PaginationOptions, PaginationMetadata };
+export type { RelationJoinDefinition as JoinDefinition };
+/**
+ * Main function: Convert Sequelize-style filter to Drizzle where condition
+ *
+ * @param filter - Filter object (Sequelize-style)
+ * @param ctx - Query context with table schema information
+ * @returns Drizzle SQL where condition
+ *
+ * @example
+ * ```typescript
+ * const filter = {
+ *   age: { gt: 18 },
+ *   status: { in: ['active', 'pending'] }
+ * };
+ *
+ * const where = drizzleWhere(filter, {
+ *   table: usersTable,
+ *   tableName: 'users',
+ *   schema: usersTable
+ * });
+ *
+ * // Use in query:
+ * const results = await db.select().from(usersTable).where(where);
+ * ```
+ */
+export declare function drizzleWhere(filter: FilterObject | null | undefined, ctx: QueryContext): SQL | undefined;
+/**
+ * Extract field paths from relational conditions
+ * Used to determine which relations need to be included/joined
+ */
+export declare function extractFieldPathsFromRelConditions(relConditions: any): string[];
+/**
+ * Combine multiple filters with AND logic
+ * Returns empty object instead of undefined for better type safety
+ */
+export declare function combineFilters(...filters: (FilterObject | null | undefined)[]): FilterObject;
+/**
+ * Apply pagination to query
+ * Supports both limit/offset and page/pageSize styles
+ * When page is provided with limit, uses limit as pageSize and calculates offset
+ */
+export declare function applyPagination(options: PaginationOptions): {
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Calculate pagination metadata
+ */
+export declare function calculatePaginationMetadata(total: number, options: PaginationOptions): PaginationMetadata;
+/**
+ * Helper to build WHERE clause from multiple filter sources
+ * Useful for combining base filters, user filters, tenant filters, etc.
+ */
+export declare function buildWhereClause(ctx: QueryContext, ...filters: (FilterObject | null | undefined)[]): SQL | undefined;
+/**
+ * Extract all field names from a filter object
+ * Useful for permission validation
+ */
+export declare function extractFieldNamesFromFilter(filter: FilterObject): string[];
+/**
+ * Apply PostgreSQL full-text search to a query
+ * Matches Sequelize implementation for compatibility
+ *
+ * @param tableName - Name of the table being searched
+ * @param tableColumns - Column definitions from the table schema
+ * @param searchQuery - The search string
+ * @param searchFields - Fields to search in (optional, defaults to string fields)
+ * @param sortByRelevance - Whether to sort by relevance score
+ * @returns SQL condition for full-text search and optional order clause
+ */
+export declare function applyFullTextSearch(tableName: string, tableColumns: Record<string, any>, searchQuery: string, searchFields?: string[], sortByRelevance?: boolean): {
+    searchCondition: SQL;
+    orderClause?: SQL;
+};
+//# sourceMappingURL=queryBuilder.d.ts.map

package/dist/utils/queryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryBuilder.d.ts","sourceRoot":"","sources":["../../baasix/utils/queryBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,GAAG,EAAgB,MAAM,aAAa,CAAC;AAQhD,OAAO,EAGL,cAAc,IAAI,sBAAsB,EACzC,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG3G,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAC;AAElF,YAAY,EAAE,sBAAsB,IAAI,cAAc,EAAE,CAAC;AA+QzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,YAAY,GAAG,GAAG,GAAG,SAAS,CAOxG;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAAC,aAAa,EAAE,GAAG,GAAG,MAAM,EAAE,CAoD/E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,OAAO,EAAE,CAAC,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,YAAY,CAS5F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAsB/F;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,GACzB,kBAAkB,CAapB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,YAAY,EACjB,GAAG,OAAO,EAAE,CAAC,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAC9C,GAAG,GAAG,SAAS,CAGjB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAsB1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,eAAe,GAAE,OAAe,GAC/B;IAAE,eAAe,EAAE,GAAG,CAAC;IAAC,WAAW,CAAC,EAAE,GAAG,CAAA;CAAE,CAoD7C"}