@statezero/core 0.1.0

package/dist/filtering/localFiltering.js

@@ -0,0 +1,834 @@
+import sift, { createEqualsOperation } from 'sift';
+import { configInstance } from '../config.js';
+import { DateTime } from 'luxon';
+/**
+ * Gets the backend timezone for a model class
+ * @param {Class} ModelClass - The model class
+ * @returns {string} The backend timezone or 'UTC' as fallback
+ */
+function getBackendTimezone(ModelClass) {
+    if (!ModelClass || !ModelClass.configKey) {
+        return 'UTC'; // Default fallback
+    }
+    const config = configInstance.getConfig();
+    const backendConfig = config.backendConfigs[ModelClass.configKey] || config.backendConfigs.default;
+    return backendConfig.BACKEND_TZ || 'UTC';
+}
+/**
+ * Process a Django-style field path with relationships to match Django ORM behavior.
+ * This handles nested relationships by traversing the model schema and properly
+ * resolving relationship fields to their primary keys.
+ *
+ * @param {string} fieldPath - The Django-style field path (e.g., 'level2__level3__name')
+ * @param {any} value - The value to filter by
+ * @param {Class} ModelClass - The root model class to start traversal from
+ * @param {Object} options - Additional options
+ * @returns {Object} An object with processed field path and operator
+ */
+function processFieldPath(fieldPath, value, ModelClass, options = {}) {
+    // Split the field path into parts
+    const parts = fieldPath.split('__');
+    // Check if the last part is a lookup operator
+    const knownLookups = [
+        'exact', 'iexact', 'contains', 'icontains', 'startswith',
+        'istartswith', 'endswith', 'iendswith', 'in', 'gt', 'gte',
+        'lt', 'lte', 'isnull', 'regex', 'iregex', 'year', 'month',
+        'day', 'week_day', 'hour', 'minute', 'second'
+    ];
+    // Date part lookups that can be followed by comparison lookups
+    const dateParts = ['year', 'month', 'day', 'week_day', 'hour', 'minute', 'second'];
+    // Comparison lookups that can follow date parts
+    const comparisonLookups = ['gt', 'gte', 'lt', 'lte', 'exact'];
+    let lookupChain = [];
+    let fieldParts = [...parts];
+    // Check for date part + comparison operator pattern (e.g., hour__gt)
+    if (parts.length >= 3) {
+        const potentialDatePart = parts[parts.length - 2];
+        const potentialComparison = parts[parts.length - 1];
+        if (dateParts.includes(potentialDatePart) && comparisonLookups.includes(potentialComparison)) {
+            // We have a date part followed by a comparison (e.g., created_at__hour__gt)
+            lookupChain = [potentialDatePart, potentialComparison];
+            fieldParts = parts.slice(0, -2);
+        }
+    }
+    // If no date part + comparison found, check for a single lookup
+    let lookup = null;
+    if (lookupChain.length === 0 && parts.length > 1 && knownLookups.includes(parts[parts.length - 1])) {
+        lookup = parts[parts.length - 1];
+        fieldParts = parts.slice(0, -1);
+    }
+    // Process the field parts to build the final path
+    let currentModel = ModelClass;
+    let processedPath = [];
+    let isRelationship = false;
+    for (let i = 0; i < fieldParts.length; i++) {
+        let part = fieldParts[i];
+        if (part === 'pk' && currentModel)
+            part = currentModel.primaryKeyField;
+        const isLastPart = i === fieldParts.length - 1;
+        // Check if this part refers to a relationship field
+        if (currentModel && currentModel.relationshipFields &&
+            currentModel.relationshipFields instanceof Map &&
+            currentModel.relationshipFields.has(part)) {
+            // This is a relationship field
+            const relationship = currentModel.relationshipFields.get(part);
+            const relatedModel = relationship.ModelClass();
+            // Add this relationship field to the path
+            processedPath.push(part);
+            // If this is not the last part, update the current model to the related model
+            if (!isLastPart) {
+                currentModel = relatedModel;
+            }
+            else {
+                // This is the last part and it's a relationship
+                // We need to add the primary key field of the related model
+                isRelationship = true;
+                // For foreign key relationships, we need to append the primary key field
+                // to properly match Django's behavior
+                const pkField = relatedModel.primaryKeyField || 'id';
+                processedPath.push(pkField);
+            }
+        }
+        else if (currentModel && currentModel.fields && currentModel.fields.includes(part)) {
+            // This is a regular field
+            processedPath.push(part);
+            // If it's the last part, we're done
+            if (isLastPart) {
+                break;
+            }
+            // If it's not the last part but it's a regular field, 
+            // we can't continue traversal
+            throw new Error(`Field '${part}' in '${fieldPath}' is not a relationship field and cannot be traversed.`);
+        }
+        else {
+            // Field not found in the model
+            throw new Error(`Field '${part}' in '${fieldPath}' not found in model ${currentModel.modelName}.`);
+        }
+    }
+    // Join the processed path parts, using dot notation for sift
+    const finalPath = processedPath.join('.');
+    // Handle the date part + comparison chain if present
+    if (lookupChain.length === 2) {
+        const [datePart, comparisonOperator] = lookupChain;
+        return createDatePartComparisonOperator(finalPath, datePart, comparisonOperator, value, isRelationship);
+    }
+    // Handle the single lookup operation if present
+    if (lookup) {
+        return createOperatorFromLookup(finalPath, lookup, value, isRelationship);
+    }
+    // If there's no explicit lookup and this is a relationship field,
+    // we've already appended the PK field name to the path
+    // so we just need to apply the equality operator to the value
+    if (isRelationship) {
+        // In case the user passed in a raw model as the query value
+        let raw = value;
+        if (value && typeof value === 'object' && 'pk' in value) {
+            raw = value.pk;
+        }
+        return { field: finalPath, operator: { $eq: raw } };
+    }
+    // Default to direct equality
+    return { field: finalPath, operator: { $eq: value } };
+}
+/**
+ * Creates a special operator for date part comparison (e.g., created_at__hour__gt: 12)
+ * @param {string} field - Processed field path
+ * @param {string} datePart - The date part to extract ('year', 'month', etc.)
+ * @param {string} comparisonOperator - The comparison operator ('gt', 'lt', etc.)
+ * @param {any} value - Value to filter by
+ * @param {boolean} isRelationship - Whether the field is a relationship
+ * @returns {Object} Object with field name and custom operator
+ */
+function createDatePartComparisonOperator(field, datePart, comparisonOperator, value, isRelationship) {
+    // If this is a relationship field, we handle it differently
+    if (isRelationship) {
+        console.warn(`Date part comparison on relationship fields may not work as expected: ${field}`);
+        // Fallback to direct equality as a safer option
+        return { field, operator: { $eq: value } };
+    }
+    // Create a custom operation name that combines the date part and comparison
+    // This will be handled by our custom operations in sift
+    return {
+        field,
+        operator: { [`$${datePart}_${comparisonOperator}`]: value }
+    };
+}
+/**
+ * Creates a sift operator from a Django-style lookup
+ * @param {string} field - Processed field path
+ * @param {string} lookup - Django-style lookup (e.g., 'contains', 'iexact')
+ * @param {any} value - Value to filter by
+ * @param {boolean} isRelationship - Whether the field is a relationship
+ * @returns {Object} Object with field name and sift operator
+ */
+function createOperatorFromLookup(field, lookup, value, isRelationship) {
+    // Helper function to escape special characters in regex
+    function escapeRegExp(string) {
+        return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    // Handle relationship fields differently
+    if (isRelationship) {
+        // For relationship fields with lookups, we need special handling
+        if (lookup === 'isnull') {
+            return {
+                field,
+                operator: value ? { $exists: false } : { $exists: true }
+            };
+        }
+        else if (lookup === 'in') {
+            return { field, operator: { $in: value } };
+        }
+        else {
+            // Default handling for relationship fields
+            return { field, operator: { $eq: value } };
+        }
+    }
+    // Handle date-related lookups
+    if (['year', 'month', 'day', 'week_day', 'hour', 'minute', 'second'].includes(lookup)) {
+        // For date part lookups, we'll use a custom operation
+        return {
+            field,
+            operator: { [`$${lookup}`]: value },
+            isDatePart: true // Add a flag to identify date part operators
+        };
+    }
+    // Regular field lookups (same as in the original code)
+    if (lookup === 'isnull') {
+        return {
+            field,
+            operator: value ? { $exists: false } : { $exists: true }
+        };
+    }
+    else if (lookup === 'exact') {
+        return { field, operator: { $eq: value } };
+    }
+    else if (lookup === 'iexact' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(`^${escapeRegExp(value)}$`, 'i') }
+        };
+    }
+    else if (lookup === 'contains' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(escapeRegExp(value)) }
+        };
+    }
+    else if (lookup === 'icontains' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(escapeRegExp(value), 'i') }
+        };
+    }
+    else if (lookup === 'startswith' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(`^${escapeRegExp(value)}`) }
+        };
+    }
+    else if (lookup === 'istartswith' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(`^${escapeRegExp(value)}`, 'i') }
+        };
+    }
+    else if (lookup === 'endswith' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(`${escapeRegExp(value)}$`) }
+        };
+    }
+    else if (lookup === 'iendswith' && typeof value === 'string') {
+        return {
+            field,
+            operator: { $regex: new RegExp(`${escapeRegExp(value)}$`, 'i') }
+        };
+    }
+    else if (lookup === 'in') {
+        return { field, operator: { $in: value } };
+    }
+    else if (lookup === 'gt') {
+        return { field, operator: { $gt: value } };
+    }
+    else if (lookup === 'gte') {
+        return { field, operator: { $gte: value } };
+    }
+    else if (lookup === 'lt') {
+        return { field, operator: { $lt: value } };
+    }
+    else if (lookup === 'lte') {
+        return { field, operator: { $lte: value } };
+    }
+    else {
+        // Default to direct equality if lookup not recognized
+        return { field, operator: { $eq: value } };
+    }
+}
+/**
+ * Creates custom operations for date parts to be used with Sift
+ * @param {string} timezone - The timezone to use for date operations
+ * @returns {Object} Object containing custom operations
+ */
+function createDateOperations(timezone = 'UTC') {
+    // Helper function to extract date parts with Django-compatible behavior
+    const getDatePart = (value, partExtractor) => {
+        if (!value)
+            return null;
+        const dateValue = value instanceof Date ? value : new Date(value);
+        if (isNaN(dateValue.getTime()))
+            return null;
+        // Convert to timezone using Luxon
+        const luxonDate = DateTime.fromJSDate(dateValue).setZone(timezone);
+        // Extract the part using the provided function
+        return partExtractor(luxonDate);
+    };
+    // Create operations with Django-compatible extractors
+    const operations = {
+        // Year - same in both
+        $year(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                const year = getDatePart(value, dt => dt.year);
+                return year !== null && year === params;
+            }, ownerQuery, options);
+        },
+        // Month - Luxon is 1-indexed like Django 
+        $month(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                const month = getDatePart(value, dt => dt.month); // Already 1-indexed
+                return month !== null && month === params;
+            }, ownerQuery, options);
+        },
+        // Day of month - same in both
+        $day(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                const day = getDatePart(value, dt => dt.day);
+                return day !== null && day === params;
+            }, ownerQuery, options);
+        },
+        // Day of week - convert to Django's 1=Sunday format
+        $week_day(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                // Convert from Luxon (1=Monday, 7=Sunday) to Django (1=Sunday, 7=Saturday)
+                const weekDay = getDatePart(value, dt => dt.weekday === 7 ? 1 : dt.weekday + 1);
+                return weekDay !== null && weekDay === params;
+            }, ownerQuery, options);
+        },
+        // Hour - same in both
+        $hour(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                const hour = getDatePart(value, dt => dt.hour);
+                return hour !== null && hour === params;
+            }, ownerQuery, options);
+        },
+        // Minute - same in both
+        $minute(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                const minute = getDatePart(value, dt => dt.minute);
+                return minute !== null && minute === params;
+            }, ownerQuery, options);
+        },
+        // Second - same in both
+        $second(params, ownerQuery, options) {
+            return createEqualsOperation((value) => {
+                const second = getDatePart(value, dt => dt.second);
+                return second !== null && second === params;
+            }, ownerQuery, options);
+        }
+    };
+    // Define part extractors for each date part with Django compatibility
+    const partExtractors = {
+        'year': (dt) => dt.year,
+        'month': (dt) => dt.month, // Already 1-indexed in Luxon
+        'day': (dt) => dt.day,
+        'week_day': (dt) => dt.weekday === 7 ? 1 : dt.weekday + 1, // Convert to Django's format
+        'hour': (dt) => dt.hour,
+        'minute': (dt) => dt.minute,
+        'second': (dt) => dt.second
+    };
+    // Generate comparison operations for each date part (year_gt, month_lt, etc.)
+    const datePartComparisons = ['gt', 'gte', 'lt', 'lte', 'exact'];
+    // For each date part, create operations with each comparison operator
+    Object.keys(partExtractors).forEach(part => {
+        const extractor = partExtractors[part];
+        datePartComparisons.forEach(op => {
+            // Create a custom operation for each combination (e.g., $year_gt, $month_lte)
+            operations[`$${part}_${op}`] = (params, ownerQuery, options) => {
+                return createEqualsOperation((value) => {
+                    if (!value)
+                        return false;
+                    const dateValue = value instanceof Date ? value : new Date(value);
+                    if (isNaN(dateValue.getTime()))
+                        return false;
+                    // Convert to timezone and extract part
+                    const luxonDate = DateTime.fromJSDate(dateValue).setZone(timezone);
+                    const partValue = extractor(luxonDate);
+                    // Apply the appropriate comparison
+                    switch (op) {
+                        case 'gt': return partValue > params;
+                        case 'gte': return partValue >= params;
+                        case 'lt': return partValue < params;
+                        case 'lte': return partValue <= params;
+                        case 'exact': return partValue === params;
+                        default: return false;
+                    }
+                }, ownerQuery, options);
+            };
+        });
+    });
+    return operations;
+}
+/**
+ * Process a Django-style filter query to use with sift, including date part operations
+ * @param {Object} criteria - Sift criteria with possible date operations
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Function} Sift filter function with date operations support
+ */
+function createFilterWithDateOperations(criteria, ModelClass) {
+    const timezone = getBackendTimezone(ModelClass);
+    return sift(criteria, {
+        operations: createDateOperations(timezone)
+    });
+}
+/**
+ * Convert Django-style filter conditions to Sift-compatible criteria
+ * @param {Object} conditions - Filter conditions
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Object} Sift-compatible criteria
+ */
+function convertToSiftCriteria(conditions, ModelClass) {
+    const result = {};
+    const datePartFilters = new Map(); // Map to collect date part filters by field
+    for (const [key, value] of Object.entries(conditions)) {
+        try {
+            const processedResult = processFieldPath(key, value, ModelClass);
+            const { field, operator, isDatePart } = processedResult;
+            if (isDatePart) {
+                // Handle date part operators separately
+                if (!datePartFilters.has(field)) {
+                    datePartFilters.set(field, []);
+                }
+                datePartFilters.get(field).push({ [field]: operator });
+            }
+            else {
+                // For regular operators, merge if we already have criteria for this field
+                if (result[field]) {
+                    result[field] = { ...result[field], ...operator };
+                }
+                else {
+                    result[field] = operator;
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to process field '${key}': ${error.message}`);
+        }
+    }
+    // If we have date part filters, combine them with the result
+    if (datePartFilters.size > 0) {
+        const andConditions = [];
+        let hasRegularFilters = Object.keys(result).length > 0;
+        // Add regular filters if any
+        if (hasRegularFilters) {
+            andConditions.push(result);
+        }
+        // Add each date part filter
+        for (const [field, operators] of datePartFilters.entries()) {
+            if (operators.length === 1) {
+                // If there's only one date filter for this field
+                if (hasRegularFilters || andConditions.length > 0) {
+                    andConditions.push(operators[0]);
+                }
+                else {
+                    // If this is the only filter, return it directly
+                    return operators[0];
+                }
+            }
+            else {
+                // Multiple date filters for the same field
+                andConditions.push(...operators);
+            }
+        }
+        // If we need to combine multiple conditions
+        if (andConditions.length > 1) {
+            return { $and: andConditions };
+        }
+    }
+    return result;
+}
+/**
+ * Processes a Q object array to match the backend AST structure
+ * @param {Array} qConditions - Array of Q objects or conditions
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Object} Sift criteria for Q conditions
+ */
+function processQConditions(qConditions, ModelClass) {
+    if (!qConditions || !qConditions.length)
+        return null;
+    // Convert each Q condition to sift criteria and combine with $or
+    return {
+        $or: qConditions.map(q => {
+            if ('operator' in q && 'conditions' in q) {
+                const op = q.operator === 'AND' ? '$and' : '$or';
+                return { [op]: q.conditions.map(c => convertToSiftCriteria(c, ModelClass)) };
+            }
+            else {
+                return convertToSiftCriteria(q, ModelClass);
+            }
+        })
+    };
+}
+/**
+ * Convert a filter node to sift criteria with proper relationship traversal
+ * @param {Object} filterNode - The filter node to convert
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Object} Sift criteria object
+ */
+function convertFilterNodeToSiftCriteria(filterNode, ModelClass) {
+    if (!filterNode)
+        return null;
+    // For simple filter nodes with conditions
+    if (filterNode.type === 'filter') {
+        const { conditions, Q: qConditions } = filterNode;
+        let criteria = {};
+        // Add regular conditions
+        if (conditions && Object.keys(conditions).length > 0) {
+            criteria = convertToSiftCriteria(conditions, ModelClass);
+        }
+        // Add Q conditions if present
+        if (qConditions && qConditions.length > 0) {
+            const qCriteria = processQConditions(qConditions, ModelClass);
+            if (qCriteria) {
+                // Combine with AND if both types of conditions exist
+                if (Object.keys(criteria).length > 0) {
+                    return { $and: [criteria, qCriteria] };
+                }
+                return qCriteria;
+            }
+        }
+        return criteria;
+    }
+    // For compound AND nodes
+    if (filterNode.type === 'and' && filterNode.children) {
+        const childCriteria = filterNode.children
+            .map(child => convertFilterNodeToSiftCriteria(child, ModelClass))
+            .filter(c => c != null);
+        if (childCriteria.length === 0)
+            return null;
+        if (childCriteria.length === 1)
+            return childCriteria[0];
+        return { $and: childCriteria };
+    }
+    // For compound OR nodes
+    if (filterNode.type === 'or' && filterNode.children) {
+        const childCriteria = filterNode.children
+            .map(child => convertFilterNodeToSiftCriteria(child, ModelClass))
+            .filter(c => c != null);
+        if (childCriteria.length === 0)
+            return null;
+        if (childCriteria.length === 1)
+            return childCriteria[0];
+        return { $or: childCriteria };
+    }
+    // Handle exclude nodes using $not
+    if (filterNode.type === 'exclude' && filterNode.child) {
+        const excludeCriteria = convertFilterNodeToSiftCriteria(filterNode.child, ModelClass);
+        if (!excludeCriteria)
+            return null;
+        return { $not: excludeCriteria };
+    }
+    return null;
+}
+/**
+ * Apply search criteria to a dataset
+ * @param {Array} data - Collection of objects to search
+ * @param {Object} searchNode - Search node from query
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Array} Filtered results
+ */
+function applySearch(data, searchNode, ModelClass) {
+    if (!searchNode || !searchNode.searchQuery)
+        return data;
+    // Default to all string fields if searchFields not specified
+    const searchFields = searchNode.searchFields ||
+        (data[0] ? Object.keys(data[0]).filter(key => typeof data[0][key] === 'string') : []);
+    if (!searchFields.length)
+        return data;
+    // Helper function to escape RegExp characters
+    function escapeRegExp(string) {
+        return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    // Process each search field through the model schema to handle relationships
+    const processedSearchConditions = searchFields.map(field => {
+        try {
+            // Convert field path to a dot notation path for Sift
+            const { field: processedField } = processFieldPath(field, '', ModelClass);
+            return {
+                [processedField]: {
+                    $regex: new RegExp(escapeRegExp(searchNode.searchQuery), 'i')
+                }
+            };
+        }
+        catch (error) {
+            console.error(`Error processing search field '${field}':`, error.message);
+            // Fall back to using field as is
+            return {
+                [field.replace(/__/g, '.')]: {
+                    $regex: new RegExp(escapeRegExp(searchNode.searchQuery), 'i')
+                }
+            };
+        }
+    });
+    return data.filter(sift({ $or: processedSearchConditions }));
+}
+/**
+ * Gets a nested value from an object using dot notation
+ * @param {Object} obj - Object to get value from
+ * @param {string} path - Path to value (dot notation)
+ * @returns {any} Value at path
+ */
+function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Process Django-style ordering fields
+ * @param {Array<string>} orderBy - Fields to order by (prefix with - for descending)
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Array<Object>} Processed ordering specifications
+ */
+function processOrderBy(orderBy, ModelClass) {
+    return orderBy.map(field => {
+        const isDescending = field.startsWith('-');
+        const fieldName = isDescending ? field.substring(1) : field;
+        try {
+            // Process the field path to handle relationships
+            const { field: processedField } = processFieldPath(fieldName, '', ModelClass);
+            return {
+                field: processedField,
+                desc: isDescending
+            };
+        }
+        catch (error) {
+            console.error(`Error processing order field '${fieldName}':`, error.message);
+            // Fall back to using the field as is with dot notation
+            return {
+                field: fieldName.replace(/__/g, '.'),
+                desc: isDescending
+            };
+        }
+    });
+}
+/**
+ * Applies ordering to a dataset based on a list of fields
+ * @param {Array} data - Collection of objects to order
+ * @param {Array<string>} orderBy - Fields to order by (prefix with - for descending)
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Array} Ordered results
+ */
+function applyOrderBy(data, orderBy, ModelClass) {
+    if (!orderBy || !orderBy.length)
+        return [...data];
+    const processedOrdering = processOrderBy(orderBy, ModelClass);
+    return [...data].sort((a, b) => {
+        for (const { field, desc } of processedOrdering) {
+            // Get values
+            const value1 = getNestedValue(a, field);
+            const value2 = getNestedValue(b, field);
+            if (value1 === value2)
+                continue;
+            // Handle nulls - null values should come last in ascending order
+            if (value1 === null && value2 !== null)
+                return desc ? -1 : 1;
+            if (value1 !== null && value2 === null)
+                return desc ? 1 : -1;
+            // Handle dates
+            if (value1 instanceof Date && value2 instanceof Date) {
+                return desc
+                    ? (value2.getTime() - value1.getTime())
+                    : (value1.getTime() - value2.getTime());
+            }
+            // Default comparison
+            if (value1 > value2)
+                return desc ? -1 : 1;
+            if (value1 < value2)
+                return desc ? 1 : -1;
+        }
+        return 0;
+    });
+}
+/**
+ * Process an array of denormalized objects to filter & order them,
+ * then return just the matching primary-keys in order.
+ *
+ * @param {Array<Object>} data       – denormalized rows, e.g. [{ id:1, name:"A", related:{ name:"B" } }, …]
+ * @param {Object}        queryBuild – the result of QuerySet.build()
+ * @param {Class}         ModelClass – your model class (for fieldPath resolution & date-ops)
+ * @returns {Array<*>}              – the primary keys of matching rows, in order
+ */
+function processQuery(data, queryBuild, ModelClass) {
+    if (!Array.isArray(data) || data.length === 0) {
+        return [];
+    }
+    if (!ModelClass) {
+        throw new Error('ModelClass is required for proper relationship traversal');
+    }
+    const pkField = ModelClass.primaryKeyField;
+    let results = [...data]; // assume already denormalized objects
+    // 1) Apply filtering
+    if (queryBuild.filter) {
+        const criteria = convertFilterNodeToSiftCriteria(queryBuild.filter, ModelClass);
+        if (criteria && Object.keys(criteria).length) {
+            results = results.filter(createFilterWithDateOperations(criteria, ModelClass));
+        }
+    }
+    // 2) Apply search
+    if (queryBuild.search && queryBuild.search.searchQuery) {
+        results = applySearch(results, queryBuild.search, ModelClass);
+    }
+    // 3) Apply ordering
+    if (Array.isArray(queryBuild.orderBy) && queryBuild.orderBy.length) {
+        results = applyOrderBy(results, queryBuild.orderBy, ModelClass);
+    }
+    // 4) Return only the primary-keys, in the filtered & ordered sequence
+    return results.map(item => item[pkField]);
+}
+/**
+ * Inspect a QuerySet.build() and collect every field path
+ * you’ll need to fetch before running sift.
+ *
+ * @param {Object} queryBuild – result of QuerySet.build()
+ * @param {Class} ModelClass – the root model class
+ * @returns {string[]} Array of dot-notation paths, e.g. ['author.id','createdAt.year']
+ */
+export function getRequiredFields(queryBuild, ModelClass) {
+    const paths = new Set();
+    const pkField = ModelClass.primaryKeyField;
+    // Always include the PK so we can re-map results
+    paths.add(pkField);
+    // Try to turn a Django-style key into the final dot path
+    function addPath(rawKey) {
+        try {
+            // We pass `null` as the value, since we only care about .field
+            const { field } = processFieldPath(rawKey, null, ModelClass);
+            paths.add(field);
+        }
+        catch (err) {
+            // if a key doesn’t map, warn and skip it
+            console.warn(`getRequiredFields: couldn’t process "${rawKey}": ${err.message}`);
+        }
+    }
+    // Recursively walk your filter AST
+    function walkFilter(node) {
+        if (!node)
+            return;
+        switch (node.type) {
+            case 'filter':
+                // simple conditions
+                Object.keys(node.conditions || {}).forEach(addPath);
+                // any Q-objects
+                (node.Q || []).forEach(q => {
+                    Object.keys(q.conditions || {}).forEach(addPath);
+                });
+                break;
+            case 'and':
+            case 'or':
+                (node.children || []).forEach(walkFilter);
+                break;
+            case 'exclude':
+                walkFilter(node.child);
+                break;
+        }
+    }
+    // collect from filter
+    if (queryBuild.filter) {
+        walkFilter(queryBuild.filter);
+    }
+    // collect from search
+    if (queryBuild.search && Array.isArray(queryBuild.search.searchFields)) {
+        queryBuild.search.searchFields.forEach(addPath);
+    }
+    // collect from orderBy
+    if (Array.isArray(queryBuild.orderBy)) {
+        queryBuild.orderBy.forEach(field => {
+            // strip leading '-' for desc sorts
+            addPath(field.replace(/^-/, ''));
+        });
+    }
+    return Array.from(paths);
+}
+/**
+ * Pick out only the required fields from a (possibly nested) model object.
+ *
+ * @param {string[]} requiredPaths  – e.g. ['id','related.name','related.age']
+ * @param {Object}   instance       – e.g. { id: 3, related: { name: 'bob', age: 12, foo: 'bar' } }
+ * @returns {Object}                – e.g. { id: 3, related: { name: 'bob', age: 12 } }
+ */
+export function pickRequiredFields(requiredPaths, instance) {
+    const result = {};
+    requiredPaths.forEach(path => {
+        const parts = path.split('.');
+        // Traverse the source instance to get the value
+        let value = instance;
+        for (const key of parts) {
+            if (value == null || !(key in value)) {
+                value = undefined;
+                break;
+            }
+            value = value[key];
+        }
+        if (value === undefined) {
+            // skip missing
+            return;
+        }
+        // Build nested structure in the result
+        let cursor = result;
+        parts.forEach((key, idx) => {
+            if (idx === parts.length - 1) {
+                cursor[key] = value;
+            }
+            else {
+                if (!(key in cursor)) {
+                    cursor[key] = {};
+                }
+                cursor = cursor[key];
+            }
+        });
+    });
+    return result;
+}
+/**
+ * Filter and order a collection of data objects according to a QuerySet's AST.
+ * This combines getRequiredFields, pickRequiredFields, and processQuery in one function.
+ *
+ * @param {Array<Object>} data - Collection of objects to filter and order
+ * @param {Object} ast - Abstract Syntax Tree from QuerySet.build()
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @param {boolean} [returnFullObjects=false] - If true, returns full objects instead of just primary keys
+ * @returns {Array} Filtered and ordered results (primary keys or full objects based on returnFullObjects)
+ */
+export function filter(data, ast, ModelClass, returnFullObjects = false) {
+    if (!Array.isArray(data) || data.length === 0) {
+        return [];
+    }
+    if (!ModelClass) {
+        throw new Error('ModelClass is required for proper relationship traversal');
+    }
+    const pkField = ModelClass.primaryKeyField || 'id';
+    let requiredFields = getRequiredFields(ast, ModelClass);
+    let denormalizedData = data.map(item => pickRequiredFields(requiredFields, item));
+    const resultKeys = processQuery(denormalizedData, ast, ModelClass);
+    if (returnFullObjects) {
+        const dataMap = new Map(data.map(item => [item[pkField], item]));
+        return resultKeys.map(key => dataMap.get(key));
+    }
+    return resultKeys;
+}
+// Export the utility functions for testing and usage
+export { processFieldPath, convertToSiftCriteria, processQConditions, convertFilterNodeToSiftCriteria, applySearch, applyOrderBy, processQuery, createDateOperations, createFilterWithDateOperations, createDatePartComparisonOperator, getBackendTimezone };