@quazardous/qdadm 2.4.2 → 2.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/entity/EntityManager.query.ts

@@ -1,6 +1,7 @@
 import { QueryExecutor, type QueryObject } from '../query/QueryExecutor'
 import type { ListParams, ListResult } from '../types'
 import type { EntityManagerInternal, OperationStats, QueryOptions } from './EntityManager.types'
+import { nullSortRank, type NullSortMode } from '../query/clientFilter'
 
 type Self = EntityManagerInternal<any>
 
@@ -172,17 +173,22 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
     // may still BE cache.items — an in-place sort would mutate the cache,
     // making later unsorted reads return whatever order the last sort left.
     if (sort_by) {
+      // Resolve null placement: field config > manager option > 'last'
+      const fieldCfg = this.getFieldConfig?.(sort_by) as { nullSort?: NullSortMode } | null
+      const nullMode: NullSortMode = fieldCfg?.nullSort ?? this.nullSort ?? 'last'
+      const nullCmp = nullSortRank(nullMode, sort_order === 'asc' ? 'asc' : 'desc')
       result = [...result]
       result.sort((a: any, b: any) => {
         const aVal = a[sort_by]
         const bVal = b[sort_by]
 
-        // Nulls always sort LAST, both directions (#1221) — matches the
-        // storage adapters' shared comparator; direction-aware placement
-        // put "never seen" rows on top of every desc date sort.
+        // Null placement is configurable per field/manager (#1222 —
+        // depends on the API and the field semantics). Default 'last'
+        // keeps the #1221 behavior; e.g. nullSort: 'low' makes "Never"
+        // sort beyond the oldest period on a last-seen date column.
         if (aVal == null && bVal == null) return 0
-        if (aVal == null) return 1
-        if (bVal == null) return -1
+        if (aVal == null) return nullCmp
+        if (bVal == null) return -nullCmp
 
         // Compare
         if (typeof aVal === 'string' && typeof bVal === 'string') {

package/src/entity/EntityManager.ts

@@ -30,6 +30,7 @@ import type {
   StorageResolution,
   Orchestrator,
 } from './EntityManager.types'
+import type { NullSortMode } from '../query/clientFilter'
 
 // Re-export public types from types file
 export type {
@@ -83,6 +84,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _fields: Record<string, FieldConfig>
 
   localFilterThreshold: number | null
+  /** Default null placement for local sorts (#1222); field-level nullSort wins. */
+  nullSort?: NullSortMode
   protected _cacheTtlMs: number | null
   protected _asymmetric: boolean
   protected _detailCache: DetailCacheState<T> = { items: new Map() }
@@ -153,6 +156,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       badges = null,
       fields = {},
       localFilterThreshold = null,
+      nullSort,
       cacheTtlMs = null,
       asymmetric = false,
       detailCacheTtlMs = 0,
@@ -183,6 +187,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._fields = fields
 
     this.localFilterThreshold = localFilterThreshold
+    this.nullSort = nullSort
     this._cacheTtlMs = cacheTtlMs
     this._asymmetric = asymmetric
     this._detailCacheTtlMs = detailCacheTtlMs

package/src/entity/EntityManager.types.ts

@@ -11,6 +11,7 @@ import type {
 } from '../types'
 import type { AuthUser, EntityAuthAdapter as IEntityAuthAdapter } from './auth/EntityAuthAdapter'
 import type { SignalBus } from '../kernel/SignalBus'
+import type { NullSortMode } from '../query/clientFilter'
 import type { HookRegistry } from '../hooks/HookRegistry'
 
 // Circular type import — safe because `import type` is erased at runtime
@@ -214,6 +215,8 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   badges?: (entity: T) => EntityBadge[]
   fields?: Record<string, FieldConfig>
   localFilterThreshold?: number | null
+  /** Default null placement for local sorts: 'first' | 'last' | 'low' | 'high' (default 'last', #1222). Field-level nullSort wins. */
+  nullSort?: NullSortMode
   /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Overrides global, overridden by storage. */
   cacheTtlMs?: number | null
   /** Asymmetric mode: list() and get() return different structures. get() skips list cache. */

package/src/index.ts

@@ -305,8 +305,11 @@ export {
   searchItems,
   paginate,
   defaultGenerateId,
+  nullSortRank,
   type SortOrder,
   type FilterItemsOptions,
+  type NullSortMode,
+  type SortItemsOptions,
 } from './query/clientFilter'
 export { useChildPage, type UseChildPageReturn } from './composables/useChildPage'
 export { useSidebarState, SIDEBAR_COLLAPSED_KEY } from './composables/useSidebarState'

package/src/query/clientFilter.ts

@@ -15,14 +15,55 @@
 
 export type SortOrder = 'asc' | 'desc'
 
-/** Sort by a field, nulls/undefined last — the canonical adapter comparator. */
-export function sortItems<T>(items: T[], sortBy?: string | null, sortOrder: SortOrder = 'asc'): T[] {
+/**
+ * Null placement when sorting (#1222 — configurable, it depends on the
+ * API and the field semantics):
+ * - 'last'  (default): nulls at the end, both directions — the historical
+ *   adapter behavior, keeps empty rows out of the way.
+ * - 'first': nulls at the top, both directions.
+ * - 'low':   null behaves as the lowest value — first in asc, last in
+ *   desc. Right for "last seen" dates ("Never" sorts beyond the oldest
+ *   period); equals PrimeVue nullSortOrder: -1.
+ * - 'high':  null behaves as the highest value — last in asc, first in desc.
+ */
+export type NullSortMode = 'first' | 'last' | 'low' | 'high'
+
+export interface SortItemsOptions {
+  nulls?: NullSortMode
+}
+
+export function nullSortRank(mode: NullSortMode, sortOrder: SortOrder): number {
+  // Return the comparator result for "a is null, b is not"
+  switch (mode) {
+    case 'first':
+      return -1
+    case 'low':
+      return sortOrder === 'asc' ? -1 : 1
+    case 'high':
+      return sortOrder === 'asc' ? 1 : -1
+    case 'last':
+    default:
+      return 1
+  }
+}
+
+/** Sort by a field — the canonical comparator (null placement configurable). */
+export function sortItems<T>(
+  items: T[],
+  sortBy?: string | null,
+  sortOrder: SortOrder = 'asc',
+  options: SortItemsOptions = {}
+): T[] {
   if (!sortBy) return items
+  const { nulls = 'last' } = options
   return items.sort((a, b) => {
     const aVal = a[sortBy as keyof T]
     const bVal = b[sortBy as keyof T]
-    if (aVal === undefined || aVal === null) return 1
-    if (bVal === undefined || bVal === null) return -1
+    const aNull = aVal === undefined || aVal === null
+    const bNull = bVal === undefined || bVal === null
+    if (aNull && bNull) return 0
+    if (aNull) return nullSortRank(nulls, sortOrder)
+    if (bNull) return -nullSortRank(nulls, sortOrder)
     if (aVal < bVal) return sortOrder === 'asc' ? -1 : 1
     if (aVal > bVal) return sortOrder === 'asc' ? 1 : -1
     return 0

package/src/types/index.ts

@@ -79,6 +79,8 @@ export type FieldType =
  * Field configuration
  */
 export interface FieldConfig {
+  /** Null placement when this field is locally sorted: 'first' | 'last' | 'low' | 'high' (#1222). */
+  nullSort?: 'first' | 'last' | 'low' | 'high'
   type: FieldType
   label?: string
   required?: boolean