fix(dashboard): delivery routes are searched, sorted, paged and summarised by the database

The Delivery Routes page read the 500 most recently active routes and did
everything in the browser, so an older route could not be found, edited or
deleted from it, and its cards (routes, linked couriers, stops, distance,
active in 24h) counted those 500.

GET /api/dashboard/commerce/delivery-routes now takes q, sort, direction,
page and per_page, refuses a bad value with a 422, and answers one page with
how many routes match and a summary of every route. Search covers the id,
the recorded courier and the linked courier's name, the vehicle, and the
stops, time and distance as text, ignoring case, with LIKE wildcards
escaped. The default order is most recently active first, `last_active`
compared as text: Unix milliseconds and seconds from different seconds
already compare that way in time order. Ties read most recently active
first, then by id. Couriers are read by exactly the ids the page references.
"Active in 24h" uses the overview's window (40738ed) and its exact cut.

The page client is shared now. useServerList (functions/dashboard-list.ts)
is the request counter, page, page size, header sort and search debounce
that the Orders, Payments, Products, Gift Cards, Reviews and waitlist pages
each wrote by hand: only the newest answer lands, a search or filter change
asks for page 1, and a header the server cannot sort by returns to the
default order. The routes page uses it, keeps useRecordsDashboard for the
dialog and the delete confirmation, and reloads the page after a save or
delete instead of patching a local copy.

The endpoint used to return a bare array, which the auto-imported
useDeliveryRoutes().fetchDeliveryRoutes read as "every route".
createDashboardResource takes `paged: true` for it, and fetchAll then reads
every page through readEveryPage, so it returns every route rather than the
first 500.

Tested on SQLite, PostgreSQL and MySQL with 520 routes and couriers, every
fiftieth stored as Unix seconds. Controls went red: reading the first 500
couriers ("DeliveryRoute 4 references missing Courier 505"), dropping
useServerList's newest-answer guard, and dropping readEveryPage's
count-reached stop. A control that removed padding seconds to milliseconds
stayed green; the padding did nothing, so it is gone and the comment says why.

Not verified live: the dev database's delivery_routes has no courier_id and
there is no couriers table, so this endpoint answers 503 there, as the page
did before, which loaded couriers and failed on them.

Refs #3218

Author: glennmichael123

storage/framework/auto-imports/RUNTIME.md

@@ -40,7 +40,7 @@ If boot reports a failed package or barrel, its names are unavailable until it l
 | `@stacksjs/i18n` | `I18n`, `getLocale`, `setLocale`, `t`, `tc`, `te` |
 | `@stacksjs/stx` | `derived`, `effect`, `state` |
 | `@stacksjs/browser` | `useDark`, `usePreferredDark`, `useStorage`, `useToggle` |
-| `auto-imports/functions.ts` | `DashboardApiEnvironmentError`, `DashboardApiError`, `applyMigrationOperations`, `askBuddy`, `authGuard`, `badgeClassToggles`, `badgeClasses`, `badgeDotClassToggles`, `badgeDotClasses`, `badgeShowsDot`, `buttonVariantClasses`, `buttonVariantToggles`, `clearAllToasts`, `clearBuddyChat`, `closeTerminalSession`, `count`, `createDashboardResource`, `createRecoveryDestination`, `createRecoveryPolicy`, `createResource`, `dashboardApi`, `dashboardDownload`, `dashboardStream`, `decideRelease`, `decrement`, `del`, `deleteBlogPost`, `deleteInboxEmail`, `describeAuthError`, `dismissToast`, `downloadDashboardInboxAttachment`, `ensureCraftNativeSidebarMarker`, `errorGroupPageParams`, `errorGroupParams`, `fetchAuditOperations`, `fetchBillingOverview`, `fetchBlogPost`, `fetchBlogPosts`, `fetchBuddyChat`, `fetchCampaignAnalytics`, `fetchCapturedMail`, `fetchCapturedMailMessage`, `fetchChangeOperations`, `fetchDashboardData`, `fetchDashboardHome`, `fetchDashboardInbox`, `fetchDashboardInboxBody`, `fetchDashboardQueries`, `fetchDashboardQuery`, `fetchDeployScript`, `fetchDeployment`, `fetchDeploymentTerminal`, `fetchDeployments`, `fetchEventAnalytics`, `fetchGlobalSearch`, `fetchInboxActivity`, `fetchIncidentOperations`, `fetchJob`, `fetchJobDefinitions`, `fetchJobStats`, `fetchJobs`, `fetchMailPreference`, `fetchMigrationOperations`, `fetchNotificationDeliveries`, `fetchNotificationDeliveryHistory`, `fetchNotificationDeliveryOverview`, `fetchQueueStats`, `fetchQueueWorkers`, `fetchRealtimeDashboard`, `fetchRecoveryOperations`, `fetchRemoteRegistry`, `fetchSalesAnalytics`, `fetchSchedulerOperations`, `fetchSearchEngineInventory`, `fetchWebAnalytics`, `formErrorMessages`, `get`, `increment`, `isCraftNative`, `isDark`, `isLoginResponse`, `isTwoFactorChallenge`, `mapDashboardInboxEntry`, `normalizeDeployment`, `normalizeDeploymentDetail`, `normalizeDeploymentList`, `normalizeInboxPreview`, `openTerminalSession`, `pageControls`, `parseDashboardDate`, `parseInboxSender`, `patch`, `planRecoveryRestore`, `post`, `preferredDark`, `previewDeploymentRollback`, `protectRecoveryPoint`, `publicApplicationUrl`, `pushToast`, `put`, `reconcileMigrationLedger`, `recordAnalyticsEvent`, `registerRemoteTerminal`, `requestRemoteCommand`, `reset`, `resizeTerminalSession`, `resolveApiBaseUrl`, `retryFailedJobs`, `retryJob`, `retryNotificationDelivery`, `retryQueueFailures`, `runDeploymentRollback`, `runRecoveryPolicy`, `runRecoveryRetention`, `runSchedulerTask`, `safeAuthRedirect`, `saveBlogPost`, `saveMailPreference`, `sendInboxEmail`, `sendTerminalInput`, `setInboxEmailReadState`, `slugify`, `summarizeDeployments`, `testRecoveryDestination`, `toggleDark`, `updateDeployScript`, `updateIncident`, `updateSchedulerTask`, `useAnalytics`, `useApi`, `useAppControls`, `useAuth`, `useBillable`, `useCategories`, `useCategorizables`, `useCoupons`, `useCouriers`, `useCraft`, `useCraftSidebarSelection`, `useCustomers`, `useDashboard`, `useDeliveryRoutes`, `useDigitalDeliveries`, `useDirectUpload`, `useErrors`, `useGiftCards`, `useInbox`, `useJobs`, `useLicenseKeys`, `useManufacturers`, `useOrders`, `usePages`, `usePayments`, `usePosts`, `useProducts`, `useQueue`, `useRealtimeStats`, `useRecordsDashboard`, `useReleases`, `useReviews`, `useShippingMethods`, `useShippingRates`, `useShippingZones`, `useTaggables`, `useTaxRates`, `useToasts`, `useUnits`, `useVariants`, `useWaitlistProducts`, `useWaitlistRestaurants`, `useWebsockets`, `useWindowControls`, `verifyRecoveryPoint` |
+| `auto-imports/functions.ts` | `DashboardApiEnvironmentError`, `DashboardApiError`, `LARGEST_PAGE`, `applyMigrationOperations`, `askBuddy`, `authGuard`, `badgeClassToggles`, `badgeClasses`, `badgeDotClassToggles`, `badgeDotClasses`, `badgeShowsDot`, `buttonVariantClasses`, `buttonVariantToggles`, `clearAllToasts`, `clearBuddyChat`, `closeTerminalSession`, `count`, `createDashboardResource`, `createRecoveryDestination`, `createRecoveryPolicy`, `createResource`, `dashboardApi`, `dashboardDownload`, `dashboardStream`, `decideRelease`, `decrement`, `del`, `deleteBlogPost`, `deleteInboxEmail`, `describeAuthError`, `dismissToast`, `downloadDashboardInboxAttachment`, `ensureCraftNativeSidebarMarker`, `errorGroupPageParams`, `errorGroupParams`, `fetchAuditOperations`, `fetchBillingOverview`, `fetchBlogPost`, `fetchBlogPosts`, `fetchBuddyChat`, `fetchCampaignAnalytics`, `fetchCapturedMail`, `fetchCapturedMailMessage`, `fetchChangeOperations`, `fetchDashboardData`, `fetchDashboardHome`, `fetchDashboardInbox`, `fetchDashboardInboxBody`, `fetchDashboardQueries`, `fetchDashboardQuery`, `fetchDeployScript`, `fetchDeployment`, `fetchDeploymentTerminal`, `fetchDeployments`, `fetchEventAnalytics`, `fetchGlobalSearch`, `fetchInboxActivity`, `fetchIncidentOperations`, `fetchJob`, `fetchJobDefinitions`, `fetchJobStats`, `fetchJobs`, `fetchMailPreference`, `fetchMigrationOperations`, `fetchNotificationDeliveries`, `fetchNotificationDeliveryHistory`, `fetchNotificationDeliveryOverview`, `fetchQueueStats`, `fetchQueueWorkers`, `fetchRealtimeDashboard`, `fetchRecoveryOperations`, `fetchRemoteRegistry`, `fetchSalesAnalytics`, `fetchSchedulerOperations`, `fetchSearchEngineInventory`, `fetchWebAnalytics`, `formErrorMessages`, `get`, `increment`, `isCraftNative`, `isDark`, `isLoginResponse`, `isTwoFactorChallenge`, `mapDashboardInboxEntry`, `normalizeDeployment`, `normalizeDeploymentDetail`, `normalizeDeploymentList`, `normalizeInboxPreview`, `openTerminalSession`, `pageControls`, `parseDashboardDate`, `parseInboxSender`, `patch`, `planRecoveryRestore`, `post`, `preferredDark`, `previewDeploymentRollback`, `protectRecoveryPoint`, `publicApplicationUrl`, `pushToast`, `put`, `readEveryPage`, `reconcileMigrationLedger`, `recordAnalyticsEvent`, `registerRemoteTerminal`, `requestRemoteCommand`, `reset`, `resizeTerminalSession`, `resolveApiBaseUrl`, `retryFailedJobs`, `retryJob`, `retryNotificationDelivery`, `retryQueueFailures`, `runDeploymentRollback`, `runRecoveryPolicy`, `runRecoveryRetention`, `runSchedulerTask`, `safeAuthRedirect`, `saveBlogPost`, `saveMailPreference`, `sendInboxEmail`, `sendTerminalInput`, `setInboxEmailReadState`, `slugify`, `summarizeDeployments`, `testRecoveryDestination`, `toggleDark`, `updateDeployScript`, `updateIncident`, `updateSchedulerTask`, `useAnalytics`, `useApi`, `useAppControls`, `useAuth`, `useBillable`, `useCategories`, `useCategorizables`, `useCoupons`, `useCouriers`, `useCraft`, `useCraftSidebarSelection`, `useCustomers`, `useDashboard`, `useDeliveryRoutes`, `useDigitalDeliveries`, `useDirectUpload`, `useErrors`, `useGiftCards`, `useInbox`, `useJobs`, `useLicenseKeys`, `useManufacturers`, `useOrders`, `usePages`, `usePayments`, `usePosts`, `useProducts`, `useQueue`, `useRealtimeStats`, `useRecordsDashboard`, `useReleases`, `useReviews`, `useServerList`, `useShippingMethods`, `useShippingRates`, `useShippingZones`, `useTaggables`, `useTaxRates`, `useToasts`, `useUnits`, `useVariants`, `useWaitlistProducts`, `useWaitlistRestaurants`, `useWebsockets`, `useWindowControls`, `verifyRecoveryPoint` |
 | `auto-imports/models.ts` + ORM proxies | `Activity`, `AnalyticsEvent`, `Auction`, `AuctionItem`, `Author`, `Automation`, `AutomationRun`, `Bid`, `Board`, `BoardColumn`, `Campaign`, `CampaignSend`, `CampaignVariant`, `Card`, `CardAttachment`, `CardComment`, `Cart`, `CartItem`, `Categorizable`, `Category`, `Comment`, `CommunicationSuppression`, `ConsentEvent`, `Coupon`, `Courier`, `CourierPing`, `Customer`, `DeliveryRoute`, `DeliveryStop`, `Deployment`, `DigitalDelivery`, `EmailIdempotency`, `EmailList`, `EmailListSubscriber`, `EmailSuppression`, `EmailWebhookEvent`, `ErrorModel`, `FailedJob`, `FeedbackToken`, `Form`, `FormField`, `FormSubmission`, `GdprRequest`, `GiftCard`, `Job`, `Label`, `LicenseKey`, `Log`, `LoyaltyPoint`, `LoyaltyReward`, `MagicLinkToken`, `MailPreference`, `Manufacturer`, `Menu`, `MenuItem`, `Notification`, `NotificationDelivery`, `Order`, `OrderIdempotency`, `OrderItem`, `Page`, `PageRevision`, `Payment`, `PaymentMethod`, `PaymentProduct`, `PaymentTransaction`, `PaymentWebhookEvent`, `PersonalAccessToken`, `Pledge`, `Post`, `PrintDevice`, `Product`, `ProductUnit`, `ProductVariant`, `QueryLog`, `QueueWorker`, `Receipt`, `Redirect`, `Referral`, `ReferralCode`, `Release`, `Review`, `SenderDomain`, `ShippingMethod`, `ShippingRate`, `ShippingZone`, `Site`, `SiteDomain`, `SmsOptOut`, `SocialAccount`, `SocialPost`, `StorageItem`, `StorageItemTask`, `Subscriber`, `SubscriberEmail`, `Subscription`, `Tag`, `TaxRate`, `Team`, `TeamInvitation`, `TeamMember`, `Transaction`, `UsageEvent`, `User`, `WaitlistProduct`, `WaitlistRestaurant`, `Websocket` |
 | `auto-imports/jobs.ts` | `ExampleJob`, `ExampleTwoJob`, `GenerateStoragePreviewJob`, `Inspire`, `OptimizeStorageImageJob`, `PruneModelsJob`, `PruneQueryLogsJob`, `PruneRetainedDataJob`, `PublishScheduledPagesJob`, `SendCampaignJob`, `SendEmailJob`, `SendPasswordResetEmailJob`, `SendWelcomeEmail`, `SyncSearchIndexJob`, `TagStorageMediaJob`, `TranscodeStorageVideoJob` |
 | `auto-imports/controllers.ts` | `ComingSoonController`, `QueryController` |

storage/framework/auto-imports/actions.ts

@@ -331,6 +331,7 @@ export const actions = {
   'Actions/Dashboard/Commerce/commerce-customer-records': '../defaults/app/Actions/Dashboard/Commerce/commerce-customer-records.ts',
   'Actions/Dashboard/Commerce/commerce-dashboard': '../defaults/app/Actions/Dashboard/Commerce/commerce-dashboard.ts',
   'Actions/Dashboard/Commerce/commerce-delivery-overview': '../defaults/app/Actions/Dashboard/Commerce/commerce-delivery-overview.ts',
+  'Actions/Dashboard/Commerce/commerce-delivery-route-list': '../defaults/app/Actions/Dashboard/Commerce/commerce-delivery-route-list.ts',
   'Actions/Dashboard/Commerce/commerce-delivery': '../defaults/app/Actions/Dashboard/Commerce/commerce-delivery.ts',
   'Actions/Dashboard/Commerce/commerce-gift-card-list': '../defaults/app/Actions/Dashboard/Commerce/commerce-gift-card-list.ts',
   'Actions/Dashboard/Commerce/commerce-order-list': '../defaults/app/Actions/Dashboard/Commerce/commerce-order-list.ts',

storage/framework/auto-imports/functions.ts

@@ -53,8 +53,8 @@ export type { BadgeVariant, BadgeSize } from '../defaults/functions/dashboard-ba
 export { buttonVariantToggles, buttonVariantClasses } from '../defaults/functions/dashboard-button'
 export { parseDashboardDate } from '../defaults/functions/dashboard-dates'
 export { formErrorMessages, slugify } from '../defaults/functions/dashboard-form'
-export { pageControls, useRecordsDashboard } from '../defaults/functions/dashboard-list'
-export type { PageControls, RecordsDashboardOptions, RecordsDashboard } from '../defaults/functions/dashboard-list'
+export { readEveryPage, pageControls, useRecordsDashboard, useServerList, LARGEST_PAGE } from '../defaults/functions/dashboard-list'
+export type { PageControls, RecordsDashboardOptions, RecordsDashboard, ServerListPage, ServerListOptions, ServerList } from '../defaults/functions/dashboard-list'
 export { fetchDashboardHome, useDashboard } from '../defaults/functions/dashboard'
 export type { DashboardStats, ActivityItem, SystemHealthItem, DashboardHttpMetric, DashboardIssue } from '../defaults/functions/dashboard'
 export { fetchDashboardData } from '../defaults/functions/data'

storage/framework/auto-imports/sources.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "5ec873edaed57eb99997d16e797df2ab4ac3ae8587353e913995ae5fa79a268c"
+  "fingerprint": "4f2c0a6599ac49fcec8d88e6c39bf2a34ed18ac4f7e6048f05df7d509abf7e94"
 }

storage/framework/defaults/app/Actions/Dashboard/Commerce/DeliveryRouteIndexAction.ts

@@ -1,24 +1,35 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions/runtime'
-import { DeliveryRoute, Courier } from '@stacksjs/orm'
+import { response } from '@stacksjs/router'
 import { dashboardOperationalError } from '../dashboard-response'
-import {
-  indexDeliveryRouteCouriers,
-  normalizeDeliveryRouteRecord,
-} from './delivery-route-records'
+import { parseDeliveryRouteListQuery, readDeliveryRoutePage } from './commerce-delivery-route-list'
 
+/**
+ * `GET /api/dashboard/commerce/delivery-routes` - one page of delivery routes,
+ * searched, sorted and counted by the database, with the summary of every
+ * route (commerce-delivery-route-list.ts, stacksjs/stacks#3218). It used to
+ * return the 500 most recently active routes as a bare array.
+ */
 export default new Action({
   name: 'Dashboard Delivery Routes',
-  description: 'Returns validated delivery routes and their optional Courier relationships.',
+  description: 'Returns one page of delivery routes with their linked couriers.',
   method: 'GET',
   apiResponse: true,
 
-  async handle() {
+  async handle(request: RequestInstance) {
+    const query = parseDeliveryRouteListQuery(key => request.get<unknown>(key, ''))
+    if ('error' in query)
+      return response.json({ message: query.error }, 422)
+
     try {
-      const routes = await DeliveryRoute.orderByDesc('last_active').limit(500).get()
-      const courierIds = [...new Set(routes.map(route => route.get('courier_id')).filter(Boolean))]
-      const couriers = courierIds.length ? await Courier.whereIn('id', courierIds).get() : []
-      const couriersById = indexDeliveryRouteCouriers(couriers)
-      return routes.map(route => normalizeDeliveryRouteRecord(route, couriersById))
+      const routes = await readDeliveryRoutePage(query)
+      return {
+        records: routes.records,
+        total: routes.total,
+        page: routes.page,
+        perPage: query.perPage,
+        summary: routes.summary,
+      }
     }
     catch (error) {
       return dashboardOperationalError(error, 'Delivery route records could not be read.', 'DeliveryRouteIndexAction')

storage/framework/defaults/app/Actions/Dashboard/Commerce/commerce-delivery-overview.ts

@@ -35,7 +35,7 @@ function activeFirst(dialect: QueryBuilderDialect): string {
  * else is kept from the day before the cutoff on, and buildDeliveryOverview
  * makes the exact cut.
  */
-function recentRoutes(dialect: QueryBuilderDialect, now: Date): { where: string, values: unknown[] } {
+export function recentRoutes(dialect: QueryBuilderDialect, now: Date): { where: string, values: unknown[] } {
   const { bind, values } = binder(dialect)
   const cutoff = now.getTime() - DAY_MS
   const column = asText('last_active', dialect)