feat(pinia-orm): support Intl.Collator for locale aware sorting

orderBy() (query & repository), useSortBy and the orderBy util now
accept an Intl.Collator besides the existing sort flags. String values
are then compared with the collator, enabling locale aware ordering
(e.g. Lithuanian A, B, Š, T, U) and options like numeric sorting.
Different flags can be given per order clause.

closes #2006

Author: CodeDredd

docs/content/2.api/1.composables/2.helpers/use-sort-by.md

@@ -20,6 +20,9 @@ useSortBy(users, 'name')
 // sort by the `name` attribute case insensitive
 useSortBy(users, 'name', 'SORT_FLAG_CASE')
 
+// sort by the `name` attribute locale aware
+useSortBy(users, 'name', new Intl.Collator('lt'))
+
 // sorts the collection by 'name' descending and then by 'lastname' ascending
 useSortBy(users, [
     ['name', 'desc'],
@@ -36,6 +39,7 @@ useSortBy(users, (model) => model.age)
 ````ts
 export type sorting<T> = ((record: T) => any) | string | [string, 'asc' | 'desc'][]
 export type SortFlags = 'SORT_REGULAR' | 'SORT_FLAG_CASE'
+export type SortComparator = SortFlags | Intl.Collator
 
-export function useSortBy<T>(collection: T[], sort: sorting<T>, flags?: SortFlags): T[]
+export function useSortBy<T>(collection: T[], sort: sorting<T>, flags?: SortComparator): T[]
 ````

docs/content/2.api/3.query/order-by.md

@@ -24,10 +24,21 @@ useRepo(User)
 
 // Sort user name by its third character.
 useRepo(User).orderBy(user => user.name[2]).get()
+
+// Sort user names case insensitive.
+useRepo(User).orderBy('name', 'asc', 'SORT_FLAG_CASE').get()
+
+// Sort user names locale aware with an Intl.Collator,
+// e.g. for Lithuanian: A, B, Š, T, U instead of A, B, T, U, Š.
+useRepo(User).orderBy('name', 'asc', new Intl.Collator('lt')).get()
 ````
 
+The optional third argument accepts either one of the sort flags (`'SORT_REGULAR'`, `'SORT_FLAG_CASE'`) or any [`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator) instance. A collator is used to compare string values, which enables locale aware sorting as well as options like numeric ordering (`new Intl.Collator(undefined, { numeric: true })`).
+
 ## Typescript Declarations
 
 ````ts
-function orderBy(field: OrderBy, direction: OrderDirection = 'asc'): Query
+function orderBy(field: OrderBy, direction: OrderDirection = 'asc', flags: SortComparator = 'SORT_REGULAR'): Query
+
+type SortComparator = 'SORT_REGULAR' | 'SORT_FLAG_CASE' | Intl.Collator
 ````

packages/pinia-orm/src/composables/collection/useCollect.ts

@@ -1,5 +1,5 @@
 import type { Collection, Model } from '../../../src'
-import type { SortFlags } from '../../support/Utils'
+import type { SortComparator } from '../../support/Utils'
 import { useSum } from './useSum'
 import { useMax } from './useMax'
 import { useMin } from './useMin'
@@ -15,7 +15,7 @@ export interface UseCollect<M extends Model = Model> {
   max: (field: string) => number
   pluck: (field: string) => any[]
   groupBy: (fields: string[] | string) => Record<string, Collection<M>>
-  sortBy: (sort: sorting<M>, flags?: SortFlags) => M[]
+  sortBy: (sort: sorting<M>, flags?: SortComparator) => M[]
   keys: () => string[]
 }
 
@@ -29,7 +29,7 @@ export function useCollect<M extends Model = Model> (models: Collection<M>): Use
     max: field => useMax(models, field),
     pluck: field => usePluck(models, field),
     groupBy: fields => useGroupBy(models, fields),
-    sortBy: (sort, flags: SortFlags = 'SORT_REGULAR') => useSortBy(models, sort, flags),
+    sortBy: (sort, flags: SortComparator = 'SORT_REGULAR') => useSortBy(models, sort, flags),
     keys: () => useKeys(models),
   }
 }

packages/pinia-orm/src/composables/collection/useSortBy.ts

@@ -1,4 +1,4 @@
-import type { SortFlags } from '../../support/Utils'
+import type { SortComparator } from '../../support/Utils'
 import { orderBy } from '../../support/Utils'
 
 export type sorting<T> = ((record: T) => any) | string | [string, 'asc' | 'desc'][]
@@ -7,7 +7,7 @@ export type sorting<T> = ((record: T) => any) | string | [string, 'asc' | 'desc'
  * Creates an array of elements, sorted in specified order by the results
  * of running each element in a collection thru each iteratee.
  */
-export function useSortBy<T extends Record<string, any>> (collection: T[], sort: sorting<T>, flags?: SortFlags): T[] {
+export function useSortBy<T extends Record<string, any>> (collection: T[], sort: sorting<T>, flags?: SortComparator): T[] {
   const directions = []
   const iteratees = []
 

packages/pinia-orm/src/query/Options.ts

@@ -1,4 +1,5 @@
 import type { Model, WithKeys } from '../model/Model'
+import type { SortComparator } from '../support/Utils'
 import type { Query } from './Query'
 
 export interface Where<T = Model> {
@@ -23,6 +24,7 @@ export interface WhereGroup {
 export interface Order {
   field: OrderBy
   direction: OrderDirection
+  flags?: SortComparator
 }
 
 export interface Group {

packages/pinia-orm/src/query/Query.ts

@@ -9,6 +9,7 @@ import {
   isFunction,
   orderBy,
 } from '../support/Utils'
+import type { SortComparator } from '../support/Utils'
 import type { Collection, Element, Elements, GroupedCollection, Item, NormalizedData } from '../data/Data'
 import type { Database } from '../database/Database'
 import { Relation } from '../model/attributes/relations/Relation'
@@ -359,8 +360,8 @@ export class Query<M extends Model = Model> {
   /**
    * Add an "order by" clause to the query.
    */
-  orderBy (field: OrderBy, direction: OrderDirection = 'asc'): this {
-    this.orders.push({ field, direction })
+  orderBy (field: OrderBy, direction: OrderDirection = 'asc', flags: SortComparator = 'SORT_REGULAR'): this {
+    this.orders.push({ field, direction, flags })
 
     return this
   }
@@ -625,8 +626,9 @@ export class Query<M extends Model = Model> {
   protected filterOrder (models: Collection<M>): Collection<M> {
     const fields = this.orders.map(order => order.field)
     const directions = this.orders.map(order => order.direction)
+    const flags = this.orders.map(order => order.flags ?? 'SORT_REGULAR')
 
-    return orderBy(models, fields, directions)
+    return orderBy(models, fields, directions, flags)
   }
 
   /**

packages/pinia-orm/src/repository/Repository.ts

@@ -1,6 +1,7 @@
 import type { Pinia } from 'pinia'
 import type { Constructor } from '../types'
 import { assert, isArray } from '../support/Utils'
+import type { SortComparator } from '../support/Utils'
 import type { Collection, Element, Item } from '../data/Data'
 import type { Database } from '../database/Database'
 import type { Model, WithKeys } from '../model/Model'
@@ -332,8 +333,8 @@ export class Repository<M extends Model = Model> {
   /**
    * Add an "order by" clause to the query.
    */
-  orderBy (field: OrderBy, direction?: OrderDirection): Query<M> {
-    return this.query().orderBy(field, direction)
+  orderBy (field: OrderBy, direction?: OrderDirection, flags?: SortComparator): Query<M> {
+    return this.query().orderBy(field, direction, flags)
   }
 
   /**

packages/pinia-orm/src/support/Utils.ts

@@ -8,6 +8,8 @@ interface SortableArray<T> {
 
 export type SortFlags = 'SORT_REGULAR' | 'SORT_FLAG_CASE'
 
+export type SortComparator = SortFlags | Intl.Collator
+
 /**
  * Compare two values with custom string operator
  */
@@ -77,7 +79,7 @@ export function orderBy<T extends Element> (
   collection: T[],
   iteratees: (((record: T) => any) | string)[],
   directions: string[],
-  flags: SortFlags = 'SORT_REGULAR',
+  flags: SortComparator | SortComparator[] = 'SORT_REGULAR',
 ): T[] {
   let index = -1
 
@@ -130,7 +132,7 @@ function compareMultiple<T> (
   object: SortableArray<T>,
   other: SortableArray<T>,
   directions: string[],
-  flags: SortFlags,
+  flags: SortComparator | SortComparator[],
 ): number {
   let index = -1
 
@@ -139,7 +141,7 @@ function compareMultiple<T> (
   const length = objCriteria.length
 
   while (++index < length) {
-    const result = compareAscending(objCriteria[index], othCriteria[index], flags)
+    const result = compareAscending(objCriteria[index], othCriteria[index], isArray(flags) ? flags[index] ?? 'SORT_REGULAR' : flags)
 
     if (result) {
       const direction = directions[index]
@@ -153,8 +155,13 @@ function compareMultiple<T> (
 /**
  * Compares values to sort them in ascending order.
  */
-function compareAscending (value: any, other: any, flags: SortFlags): number {
+function compareAscending (value: any, other: any, flags: SortComparator): number {
   if (value !== other) {
+    if (typeof flags === 'object' && typeof value === 'string' && typeof other === 'string') {
+      const result = flags.compare(value, other)
+      return result > 0 ? 1 : result < 0 ? -1 : 0
+    }
+
     const valIsDefined = value !== undefined
     const valIsNull = value === null
     const valIsReflexive = value === value

packages/pinia-orm/tests/feature/repository/retrieves_order_by.spec.ts

@@ -115,6 +115,34 @@ describe('feature/repository/retrieves_order_by', () => {
     assertModels(users, expected)
   })
 
+  it('can sort records locale aware with a collator', () => {
+    const userRepo = useRepo(User)
+
+    fillState({
+      users: {
+        1: { id: 1, name: 'T', age: 40 },
+        2: { id: 2, name: 'A', age: 30 },
+        3: { id: 3, name: 'Š', age: 20 },
+        4: { id: 4, name: 'U', age: 20 },
+        5: { id: 5, name: 'B', age: 50 },
+      },
+    })
+
+    const users = userRepo.orderBy('name', 'asc', new Intl.Collator('lt')).get()
+
+    const expected = [
+      { id: 2, name: 'A', age: 30 },
+      { id: 5, name: 'B', age: 50 },
+      { id: 3, name: 'Š', age: 20 },
+      { id: 1, name: 'T', age: 40 },
+      { id: 4, name: 'U', age: 20 },
+    ]
+
+    expect(users).toHaveLength(5)
+    assertInstanceOf(users, User)
+    assertModels(users, expected)
+  })
+
   it('can sort nested records by pivot', () => {
     Model.clearRegistries()
     class User extends Model {

packages/pinia-orm/tests/unit/support/Utils_Order_By.spec.ts

@@ -98,4 +98,30 @@ describe('unit/support/Utils_Order_by', () => {
 
     expect(orderBy(collection, [v => v.id], ['asc'])).toEqual(expected)
   })
+
+  it('can order collection with a collator', () => {
+    const collection = [{ name: 'T' }, { name: 'Š' }, { name: 'A' }]
+
+    const expected = [{ name: 'A' }, { name: 'Š' }, { name: 'T' }]
+
+    expect(orderBy(collection, ['name'], ['asc'], new Intl.Collator('lt'))).toEqual(expected)
+  })
+
+  it('can order collection with different flags per field', () => {
+    const collection = [
+      { name: 'T', group: 'b' },
+      { name: 'Š', group: 'B' },
+      { name: 'A', group: 'B' },
+      { name: 'B', group: 'a' },
+    ]
+
+    const expected = [
+      { name: 'B', group: 'a' },
+      { name: 'A', group: 'B' },
+      { name: 'Š', group: 'B' },
+      { name: 'T', group: 'b' },
+    ]
+
+    expect(orderBy(collection, ['group', 'name'], ['asc', 'asc'], ['SORT_FLAG_CASE', new Intl.Collator('lt')])).toEqual(expected)
+  })
 })