@open-mercato/core 0.4.2-canary-10c7a8bf2a → 0.4.2-canary-c84cff7ed5

package/src/modules/dashboards/lib/__tests__/aggregations.test.ts

@@ -0,0 +1,327 @@
+/**
+ * @jest-environment node
+ */
+import {
+  buildAggregateExpression,
+  buildDateTruncExpression,
+  buildJsonbFieldExpression,
+  buildAggregationQuery,
+  isValidGranularity,
+  isValidAggregate,
+} from '../aggregations'
+import { createAnalyticsRegistry } from '../../services/analyticsRegistry'
+import { analyticsConfig as salesAnalyticsConfig } from '../../../sales/analytics'
+import { analyticsConfig as customersAnalyticsConfig } from '../../../customers/analytics'
+import { analyticsConfig as catalogAnalyticsConfig } from '../../../catalog/analytics'
+
+const testRegistry = createAnalyticsRegistry([salesAnalyticsConfig, customersAnalyticsConfig, catalogAnalyticsConfig])
+
+describe('aggregations', () => {
+  describe('isValidGranularity', () => {
+    it('returns true for valid granularities', () => {
+      expect(isValidGranularity('day')).toBe(true)
+      expect(isValidGranularity('week')).toBe(true)
+      expect(isValidGranularity('month')).toBe(true)
+      expect(isValidGranularity('quarter')).toBe(true)
+      expect(isValidGranularity('year')).toBe(true)
+    })
+
+    it('returns false for invalid granularities', () => {
+      expect(isValidGranularity('invalid')).toBe(false)
+      expect(isValidGranularity('')).toBe(false)
+      expect(isValidGranularity(null)).toBe(false)
+      expect(isValidGranularity(undefined)).toBe(false)
+      expect(isValidGranularity(123)).toBe(false)
+    })
+  })
+
+  describe('isValidAggregate', () => {
+    it('returns true for valid aggregates', () => {
+      expect(isValidAggregate('count')).toBe(true)
+      expect(isValidAggregate('sum')).toBe(true)
+      expect(isValidAggregate('avg')).toBe(true)
+      expect(isValidAggregate('min')).toBe(true)
+      expect(isValidAggregate('max')).toBe(true)
+    })
+
+    it('returns false for invalid aggregates', () => {
+      expect(isValidAggregate('invalid')).toBe(false)
+      expect(isValidAggregate('COUNT')).toBe(false) // case sensitive
+      expect(isValidAggregate('')).toBe(false)
+      expect(isValidAggregate(null)).toBe(false)
+    })
+  })
+
+  describe('isValidEntityType (via registry)', () => {
+    it('returns true for valid entity types', () => {
+      expect(testRegistry.isValidEntityType('sales:orders')).toBe(true)
+      expect(testRegistry.isValidEntityType('sales:order_lines')).toBe(true)
+      expect(testRegistry.isValidEntityType('customers:entities')).toBe(true)
+      expect(testRegistry.isValidEntityType('customers:deals')).toBe(true)
+      expect(testRegistry.isValidEntityType('catalog:products')).toBe(true)
+    })
+
+    it('returns false for invalid entity types', () => {
+      expect(testRegistry.isValidEntityType('invalid')).toBe(false)
+      expect(testRegistry.isValidEntityType('sales:invalid')).toBe(false)
+      expect(testRegistry.isValidEntityType('')).toBe(false)
+    })
+  })
+
+  describe('getEntityTypeConfig (via registry)', () => {
+    it('returns config for valid entity types', () => {
+      const config = testRegistry.getEntityTypeConfig('sales:orders')
+      expect(config).not.toBeNull()
+      expect(config?.tableName).toBe('sales_orders')
+      expect(config?.dateField).toBe('placed_at')
+    })
+
+    it('returns null for invalid entity types', () => {
+      expect(testRegistry.getEntityTypeConfig('invalid')).toBeNull()
+    })
+  })
+
+  describe('getFieldMapping (via registry)', () => {
+    it('returns mapping for valid fields', () => {
+      const mapping = testRegistry.getFieldMapping('sales:orders', 'grandTotalGrossAmount')
+      expect(mapping).not.toBeNull()
+      expect(mapping?.dbColumn).toBe('grand_total_gross_amount')
+      expect(mapping?.type).toBe('numeric')
+    })
+
+    it('returns null for invalid fields', () => {
+      expect(testRegistry.getFieldMapping('sales:orders', 'invalidField')).toBeNull()
+    })
+
+    it('returns null for invalid entity types', () => {
+      expect(testRegistry.getFieldMapping('invalid', 'grandTotalGrossAmount')).toBeNull()
+    })
+  })
+
+  describe('buildAggregateExpression', () => {
+    it('builds COUNT(*) for count with id column', () => {
+      expect(buildAggregateExpression('count', 'id')).toBe('COUNT(*)')
+    })
+
+    it('builds COUNT(column) for count with other columns', () => {
+      expect(buildAggregateExpression('count', 'status')).toBe('COUNT(status)')
+    })
+
+    it('builds SUM with COALESCE', () => {
+      expect(buildAggregateExpression('sum', 'amount')).toBe('COALESCE(SUM(amount::numeric), 0)')
+    })
+
+    it('builds AVG with COALESCE', () => {
+      expect(buildAggregateExpression('avg', 'amount')).toBe('COALESCE(AVG(amount::numeric), 0)')
+    })
+
+    it('builds MIN', () => {
+      expect(buildAggregateExpression('min', 'amount')).toBe('MIN(amount::numeric)')
+    })
+
+    it('builds MAX', () => {
+      expect(buildAggregateExpression('max', 'amount')).toBe('MAX(amount::numeric)')
+    })
+  })
+
+  describe('buildDateTruncExpression', () => {
+    it('builds DATE_TRUNC for valid granularity', () => {
+      expect(buildDateTruncExpression('created_at', 'day')).toBe("DATE_TRUNC('day', created_at)")
+      expect(buildDateTruncExpression('created_at', 'month')).toBe("DATE_TRUNC('month', created_at)")
+    })
+
+    it('throws for invalid granularity', () => {
+      expect(() => buildDateTruncExpression('created_at', 'invalid' as any)).toThrow('Invalid granularity')
+    })
+  })
+
+  describe('buildJsonbFieldExpression', () => {
+    it('builds single-level JSONB access', () => {
+      expect(buildJsonbFieldExpression('data', 'name')).toBe("data->>'name'")
+    })
+
+    it('builds nested JSONB access', () => {
+      expect(buildJsonbFieldExpression('data', 'address.city')).toBe("data->'address'->>'city'")
+    })
+
+    it('builds deeply nested JSONB access', () => {
+      expect(buildJsonbFieldExpression('data', 'a.b.c')).toBe("data->'a'->'b'->>'c'")
+    })
+
+    it('throws for invalid path parts', () => {
+      expect(() => buildJsonbFieldExpression('data', 'invalid-path')).toThrow('Invalid JSONB path part')
+      expect(() => buildJsonbFieldExpression('data', '123invalid')).toThrow('Invalid JSONB path part')
+      expect(() => buildJsonbFieldExpression('data', 'valid.123invalid')).toThrow('Invalid JSONB path part')
+    })
+
+    it('allows valid identifier characters', () => {
+      expect(buildJsonbFieldExpression('data', 'valid_name')).toBe("data->>'valid_name'")
+      expect(buildJsonbFieldExpression('data', '_private')).toBe("data->>'_private'")
+      expect(buildJsonbFieldExpression('data', 'CamelCase')).toBe("data->>'CamelCase'")
+    })
+  })
+
+  describe('buildAggregationQuery', () => {
+    const baseOptions = {
+      entityType: 'sales:orders',
+      metric: { field: 'grandTotalGrossAmount', aggregate: 'sum' as const },
+      scope: { tenantId: 'tenant-123' },
+      registry: testRegistry,
+    }
+
+    it('builds basic aggregation query', () => {
+      const result = buildAggregationQuery(baseOptions)
+      expect(result).not.toBeNull()
+      expect(result?.sql).toContain('SELECT')
+      expect(result?.sql).toContain('COALESCE(SUM(grand_total_gross_amount::numeric), 0)')
+      expect(result?.sql).toContain('FROM "sales_orders"')
+      expect(result?.sql).toContain('tenant_id = ?')
+      expect(result?.params).toContain('tenant-123')
+    })
+
+    it('includes organization filter when provided', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        scope: { tenantId: 'tenant-123', organizationIds: ['org-1', 'org-2'] },
+      })
+      expect(result?.sql).toContain('organization_id = ANY(?::uuid[])')
+      expect(result?.params).toContain('{org-1,org-2}')
+    })
+
+    it('includes date range filter', () => {
+      const start = new Date('2024-01-01')
+      const end = new Date('2024-01-31')
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        dateRange: { field: 'placedAt', start, end },
+      })
+      expect(result?.sql).toContain('placed_at >= ?')
+      expect(result?.sql).toContain('placed_at <= ?')
+      expect(result?.params).toContain(start)
+      expect(result?.params).toContain(end)
+    })
+
+    it('includes groupBy clause', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        groupBy: { field: 'status' },
+      })
+      expect(result?.sql).toContain('GROUP BY status')
+      expect(result?.sql).toContain('status AS group_key')
+    })
+
+    it('includes groupBy with granularity for timestamp fields', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        groupBy: { field: 'placedAt', granularity: 'month' },
+      })
+      expect(result?.sql).toContain("DATE_TRUNC('month', placed_at)")
+      expect(result?.sql).toContain('GROUP BY')
+    })
+
+    it('includes LIMIT when groupBy has limit', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        groupBy: { field: 'status', limit: 10 },
+      })
+      expect(result?.sql).toContain('LIMIT 10')
+    })
+
+    it('caps LIMIT at 100', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        groupBy: { field: 'status', limit: 200 },
+      })
+      expect(result?.sql).toContain('LIMIT 100')
+    })
+
+    it('includes deleted_at IS NULL filter', () => {
+      const result = buildAggregationQuery(baseOptions)
+      expect(result?.sql).toContain('deleted_at IS NULL')
+    })
+
+    it('handles various filter operators', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        filters: [
+          { field: 'status', operator: 'eq', value: 'completed' },
+          { field: 'grandTotalGrossAmount', operator: 'gte', value: 100 },
+        ],
+      })
+      expect(result?.sql).toContain('status = ?')
+      expect(result?.sql).toContain('grand_total_gross_amount >= ?')
+    })
+
+    it('handles is_null and is_not_null operators without value', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        filters: [
+          { field: 'customerEntityId', operator: 'is_null' },
+          { field: 'channelId', operator: 'is_not_null' },
+        ],
+      })
+      expect(result?.sql).toContain('customer_entity_id IS NULL')
+      expect(result?.sql).toContain('channel_id IS NOT NULL')
+    })
+
+    it('returns null for invalid entity type', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        entityType: 'invalid',
+      })
+      expect(result).toBeNull()
+    })
+
+    it('returns null for invalid metric field', () => {
+      const result = buildAggregationQuery({
+        ...baseOptions,
+        metric: { field: 'invalidField', aggregate: 'sum' },
+      })
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('entity type configs (via registry)', () => {
+    it('has all expected entity types', () => {
+      const entityIds = testRegistry.getAllEntityConfigs().map((c) => c.entityId)
+      expect(entityIds).toEqual(
+        expect.arrayContaining([
+          'sales:orders',
+          'sales:order_lines',
+          'customers:entities',
+          'customers:deals',
+          'catalog:products',
+        ]),
+      )
+      expect(entityIds).toHaveLength(5)
+    })
+
+    it('each config has required fields', () => {
+      testRegistry.getAllEntityConfigs().forEach((entityConfig) => {
+        expect(entityConfig.entityConfig.tableName).toBeDefined()
+        expect(entityConfig.entityConfig.dateField).toBeDefined()
+        expect(entityConfig.entityConfig.defaultScopeFields).toBeDefined()
+        expect(Array.isArray(entityConfig.entityConfig.defaultScopeFields)).toBe(true)
+      })
+    })
+  })
+
+  describe('field mappings (via registry)', () => {
+    it('has mappings for all entity types', () => {
+      testRegistry.getAllEntityConfigs().forEach((entityConfig) => {
+        const mappings = testRegistry.getAllFieldMappings(entityConfig.entityId)
+        expect(mappings).toBeDefined()
+      })
+    })
+
+    it('sales:orders has expected fields', () => {
+      const mappings = testRegistry.getAllFieldMappings('sales:orders')
+      expect(mappings).not.toBeNull()
+      const fields = Object.keys(mappings!)
+      expect(fields).toContain('id')
+      expect(fields).toContain('grandTotalGrossAmount')
+      expect(fields).toContain('status')
+      expect(fields).toContain('placedAt')
+    })
+  })
+})

package/src/modules/dashboards/lib/__tests__/formatters.test.ts

@@ -0,0 +1,128 @@
+/**
+ * @jest-environment node
+ */
+import {
+  formatCurrency,
+  formatCurrencyWithDecimals,
+  formatCurrencyCompact,
+  formatCurrencySafe,
+} from '../formatters'
+
+describe('formatters', () => {
+  describe('formatCurrency', () => {
+    it('formats positive numbers as currency', () => {
+      const result = formatCurrency(1234)
+      expect(result).toMatch(/\$?1,?234/)
+    })
+
+    it('formats zero', () => {
+      const result = formatCurrency(0)
+      expect(result).toMatch(/\$?0/)
+    })
+
+    it('formats negative numbers', () => {
+      const result = formatCurrency(-500)
+      expect(result).toMatch(/-?\$?500/)
+    })
+
+    it('uses custom currency', () => {
+      const result = formatCurrency(100, { currency: 'EUR' })
+      expect(result).toMatch(/€|EUR/)
+    })
+
+    it('respects minimumFractionDigits', () => {
+      const result = formatCurrency(100, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+      expect(result).toMatch(/100\.00|100,00/)
+    })
+
+    it('respects maximumFractionDigits', () => {
+      const result = formatCurrency(100.999, { maximumFractionDigits: 2 })
+      expect(result).toMatch(/101/)
+    })
+  })
+
+  describe('formatCurrencyWithDecimals', () => {
+    it('formats with 2 decimal places by default', () => {
+      const result = formatCurrencyWithDecimals(100)
+      expect(result).toMatch(/100\.00|100,00/)
+    })
+
+    it('rounds to 2 decimal places', () => {
+      const result = formatCurrencyWithDecimals(99.999)
+      expect(result).toMatch(/100\.00|100,00/)
+    })
+
+    it('shows trailing zeros', () => {
+      const result = formatCurrencyWithDecimals(50)
+      expect(result).toMatch(/50\.00|50,00/)
+    })
+  })
+
+  describe('formatCurrencyCompact', () => {
+    it('formats millions with M suffix', () => {
+      expect(formatCurrencyCompact(1000000)).toBe('$1.0M')
+      expect(formatCurrencyCompact(2500000)).toBe('$2.5M')
+      expect(formatCurrencyCompact(10000000)).toBe('$10.0M')
+    })
+
+    it('formats thousands with K suffix', () => {
+      expect(formatCurrencyCompact(1000)).toBe('$1.0K')
+      expect(formatCurrencyCompact(5500)).toBe('$5.5K')
+      expect(formatCurrencyCompact(999000)).toBe('$999.0K')
+    })
+
+    it('formats small numbers without suffix', () => {
+      expect(formatCurrencyCompact(500)).toBe('$500')
+      expect(formatCurrencyCompact(0)).toBe('$0')
+      expect(formatCurrencyCompact(999)).toBe('$999')
+    })
+
+    it('handles negative values', () => {
+      expect(formatCurrencyCompact(-1000000)).toBe('$-1.0M')
+      expect(formatCurrencyCompact(-5000)).toBe('$-5.0K')
+      expect(formatCurrencyCompact(-500)).toBe('$-500')
+    })
+
+    it('uses custom currency symbol', () => {
+      expect(formatCurrencyCompact(1000000, '€')).toBe('€1.0M')
+      expect(formatCurrencyCompact(5000, '£')).toBe('£5.0K')
+    })
+  })
+
+  describe('formatCurrencySafe', () => {
+    it('formats valid numbers', () => {
+      const result = formatCurrencySafe(1234)
+      expect(result).toMatch(/\$?1,?234/)
+    })
+
+    it('returns fallback for null', () => {
+      expect(formatCurrencySafe(null)).toBe('--')
+    })
+
+    it('returns fallback for undefined', () => {
+      expect(formatCurrencySafe(undefined)).toBe('--')
+    })
+
+    it('returns fallback for NaN', () => {
+      expect(formatCurrencySafe(NaN)).toBe('--')
+    })
+
+    it('returns fallback for Infinity', () => {
+      expect(formatCurrencySafe(Infinity)).toBe('--')
+    })
+
+    it('returns fallback for non-numeric strings', () => {
+      expect(formatCurrencySafe('not a number')).toBe('--')
+    })
+
+    it('converts numeric strings to numbers', () => {
+      const result = formatCurrencySafe('1234')
+      expect(result).toMatch(/\$?1,?234/)
+    })
+
+    it('uses custom fallback', () => {
+      expect(formatCurrencySafe(null, 'N/A')).toBe('N/A')
+      expect(formatCurrencySafe(undefined, '-')).toBe('-')
+    })
+  })
+})

package/src/modules/dashboards/lib/aggregations.ts

@@ -0,0 +1,225 @@
+import type { AnalyticsRegistry } from '../services/analyticsRegistry'
+import type { AnalyticsEntityTypeConfig, AnalyticsFieldMapping } from '@open-mercato/shared/modules/analytics'
+
+export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max'
+export type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+const VALID_GRANULARITIES: readonly DateGranularity[] = ['day', 'week', 'month', 'quarter', 'year']
+const VALID_AGGREGATES: readonly AggregateFunction[] = ['count', 'sum', 'avg', 'min', 'max']
+const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+export function isValidGranularity(value: unknown): value is DateGranularity {
+  return typeof value === 'string' && VALID_GRANULARITIES.includes(value as DateGranularity)
+}
+
+export function isValidAggregate(value: unknown): value is AggregateFunction {
+  return typeof value === 'string' && VALID_AGGREGATES.includes(value as AggregateFunction)
+}
+
+function isSafeIdentifier(value: string): boolean {
+  return SAFE_IDENTIFIER_PATTERN.test(value)
+}
+
+// Re-export types from shared module for convenience
+export type EntityTypeConfig = AnalyticsEntityTypeConfig
+export type FieldMapping = AnalyticsFieldMapping
+
+export function buildAggregateExpression(aggregate: AggregateFunction, column: string): string {
+  switch (aggregate) {
+    case 'count':
+      return column === 'id' ? 'COUNT(*)' : `COUNT(${column})`
+    case 'sum':
+      return `COALESCE(SUM(${column}::numeric), 0)`
+    case 'avg':
+      return `COALESCE(AVG(${column}::numeric), 0)`
+    case 'min':
+      return `MIN(${column}::numeric)`
+    case 'max':
+      return `MAX(${column}::numeric)`
+    default:
+      return `COUNT(*)`
+  }
+}
+
+export function buildDateTruncExpression(column: string, granularity: DateGranularity): string {
+  if (!isValidGranularity(granularity)) {
+    throw new Error(`Invalid granularity: ${granularity}`)
+  }
+  return `DATE_TRUNC('${granularity}', ${column})`
+}
+
+export function buildJsonbFieldExpression(column: string, path: string): string {
+  const parts = path.split('.')
+  for (const part of parts) {
+    if (!isSafeIdentifier(part)) {
+      throw new Error(`Invalid JSONB path part: ${part}`)
+    }
+  }
+  if (parts.length === 1) {
+    return `${column}->>'${parts[0]}'`
+  }
+  const intermediate = parts.slice(0, -1).map((p) => `'${p}'`).join('->')
+  const lastPart = parts[parts.length - 1]
+  return `${column}->${intermediate}->>'${lastPart}'`
+}
+
+export type AggregationQuery = {
+  sql: string
+  params: unknown[]
+}
+
+export type BuildAggregationQueryOptions = {
+  entityType: string
+  metric: {
+    field: string
+    aggregate: AggregateFunction
+  }
+  groupBy?: {
+    field: string
+    granularity?: DateGranularity
+    limit?: number
+  }
+  dateRange?: {
+    field: string
+    start: Date
+    end: Date
+  }
+  filters?: Array<{
+    field: string
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'is_null' | 'is_not_null'
+    value?: unknown
+  }>
+  scope: {
+    tenantId: string
+    organizationIds?: string[]
+  }
+  /** Analytics registry for resolving entity and field configurations */
+  registry: AnalyticsRegistry
+}
+
+export function buildAggregationQuery(options: BuildAggregationQueryOptions): AggregationQuery | null {
+  const { registry } = options
+  const config = registry.getEntityTypeConfig(options.entityType)
+  if (!config) return null
+
+  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
+  if (!metricMapping) return null
+
+  const params: unknown[] = []
+
+  const tableName = config.schema ? `"${config.schema}"."${config.tableName}"` : `"${config.tableName}"`
+  const aggregateExpr = buildAggregateExpression(options.metric.aggregate, metricMapping.dbColumn)
+
+  let selectClause = `SELECT ${aggregateExpr} AS value`
+  let groupByClause = ''
+  let orderByClause = ''
+  let limitClause = ''
+
+  if (options.groupBy) {
+    let groupMapping = registry.getFieldMapping(options.entityType, options.groupBy.field)
+    let groupExpr: string | null = null
+
+    // Handle JSONB path notation (e.g., shippingAddressSnapshot.region)
+    if (!groupMapping && options.groupBy.field.includes('.')) {
+      const [baseField, ...pathParts] = options.groupBy.field.split('.')
+      const baseMapping = registry.getFieldMapping(options.entityType, baseField)
+      if (baseMapping?.type === 'jsonb') {
+        groupExpr = buildJsonbFieldExpression(baseMapping.dbColumn, pathParts.join('.'))
+      }
+    } else if (groupMapping) {
+      if (groupMapping.type === 'timestamp' && options.groupBy.granularity) {
+        groupExpr = buildDateTruncExpression(groupMapping.dbColumn, options.groupBy.granularity)
+      } else {
+        groupExpr = groupMapping.dbColumn
+      }
+    }
+
+    if (groupExpr) {
+      selectClause = `SELECT ${groupExpr} AS group_key, ${aggregateExpr} AS value`
+      groupByClause = `GROUP BY ${groupExpr}`
+      orderByClause = `ORDER BY value DESC`
+
+      if (options.groupBy.limit && options.groupBy.limit > 0) {
+        limitClause = `LIMIT ${Math.min(options.groupBy.limit, 100)}`
+      }
+    }
+  }
+
+  const whereClauses: string[] = []
+
+  whereClauses.push(`tenant_id = ?`)
+  params.push(options.scope.tenantId)
+
+  if (options.scope.organizationIds && options.scope.organizationIds.length > 0) {
+    whereClauses.push(`organization_id = ANY(?::uuid[])`)
+    params.push(`{${options.scope.organizationIds.join(',')}}`)
+  }
+
+  whereClauses.push(`deleted_at IS NULL`)
+
+  if (options.dateRange) {
+    const dateMapping = registry.getFieldMapping(options.entityType, options.dateRange.field)
+    if (dateMapping) {
+      whereClauses.push(`${dateMapping.dbColumn} >= ?`)
+      params.push(options.dateRange.start)
+      whereClauses.push(`${dateMapping.dbColumn} <= ?`)
+      params.push(options.dateRange.end)
+    }
+  }
+
+  if (options.filters) {
+    for (const filter of options.filters) {
+      const filterMapping = registry.getFieldMapping(options.entityType, filter.field)
+      if (!filterMapping) continue
+
+      switch (filter.operator) {
+        case 'eq':
+          whereClauses.push(`${filterMapping.dbColumn} = ?`)
+          params.push(filter.value)
+          break
+        case 'neq':
+          whereClauses.push(`${filterMapping.dbColumn} != ?`)
+          params.push(filter.value)
+          break
+        case 'gt':
+          whereClauses.push(`${filterMapping.dbColumn} > ?`)
+          params.push(filter.value)
+          break
+        case 'gte':
+          whereClauses.push(`${filterMapping.dbColumn} >= ?`)
+          params.push(filter.value)
+          break
+        case 'lt':
+          whereClauses.push(`${filterMapping.dbColumn} < ?`)
+          params.push(filter.value)
+          break
+        case 'lte':
+          whereClauses.push(`${filterMapping.dbColumn} <= ?`)
+          params.push(filter.value)
+          break
+        case 'in':
+          whereClauses.push(`${filterMapping.dbColumn} = ANY(?)`)
+          params.push(filter.value)
+          break
+        case 'not_in':
+          whereClauses.push(`${filterMapping.dbColumn} != ALL(?)`)
+          params.push(filter.value)
+          break
+        case 'is_null':
+          whereClauses.push(`${filterMapping.dbColumn} IS NULL`)
+          break
+        case 'is_not_null':
+          whereClauses.push(`${filterMapping.dbColumn} IS NOT NULL`)
+          break
+      }
+    }
+  }
+
+  const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : ''
+
+  const sql = [selectClause, `FROM ${tableName}`, whereClause, groupByClause, orderByClause, limitClause]
+    .filter(Boolean)
+    .join(' ')
+
+  return { sql, params }
+}