@stacksjs/defaults 0.70.54

package/resources/functions/dashboard/config-io.ts

@@ -0,0 +1,316 @@
+/**
+ * Read & write `config/*.ts` files from the dashboard.
+ *
+ * Why this exists
+ * ---------------
+ * Config files use `export default { ... } satisfies XConfig` and pull
+ * defaults from `env.*`. The settings page needs to:
+ *   - List every config file
+ *   - Show its currently-resolved values (env-substituted)
+ *   - Persist edits back to the source `.ts` so they survive restarts
+ *
+ * Reading is straightforward: `await import(file)` returns the evaluated
+ * object. Writing is harder — we want to preserve comments, type imports,
+ * and the `env.*` references intact. Instead of regenerating the file,
+ * we mutate the source text in place: find the line containing
+ * `<key>: <oldValue>` and rewrite the value. This keeps the file
+ * round-trippable and human-readable.
+ *
+ * Edits supported (top-level scalar keys only):
+ *   - string  →  string  (single- or double-quoted)
+ *   - number  →  number
+ *   - boolean →  boolean
+ *
+ * Edits NOT supported (the settings UI surfaces a read-only badge):
+ *   - nested objects, arrays
+ *   - keys whose current value is a function call or expression
+ *     (`env.X ?? 'y'`) — those need to be edited via env, not config
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import process from 'node:process'
+
+let projectRootCache: string | null = null
+function projectRoot(): string {
+  if (projectRootCache) return projectRootCache
+  let dir = process.cwd()
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(resolve(dir, 'config'))) {
+      projectRootCache = dir
+      return dir
+    }
+    const parent = resolve(dir, '..')
+    if (parent === dir) break
+    dir = parent
+  }
+  projectRootCache = process.cwd()
+  return projectRootCache
+}
+
+function configDir(): string {
+  return resolve(projectRoot(), 'config')
+}
+
+export interface ConfigFileSummary {
+  /** Filename without extension, e.g. 'email'. */
+  name: string
+  /** Display title, e.g. 'Email'. */
+  title: string
+  /** Absolute path to the source file. */
+  path: string
+  /** Bytes — UI uses this to show "small / large config" hints. */
+  size: number
+}
+
+/** Enumerate every `.ts` config file. Hidden / non-ts files are skipped. */
+export function listConfigFiles(): ConfigFileSummary[] {
+  const dir = configDir()
+  if (!existsSync(dir)) return []
+  let entries: string[]
+  try { entries = readdirSync(dir) }
+  catch { return [] }
+  const out: ConfigFileSummary[] = []
+  for (const e of entries) {
+    if (!e.endsWith('.ts') || e.startsWith('.')) continue
+    const path = join(dir, e)
+    let size = 0
+    try { size = Bun.file(path).size }
+    catch { /* unreadable — leave at 0 */ }
+    const name = e.replace(/\.ts$/, '')
+    out.push({ name, title: titleCase(name), path, size })
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Cache of imported config modules. We re-import on every call when the
+ * file's mtime has changed so the dashboard reflects edits immediately,
+ * but skip the cost when nothing has changed in a tight burst of reads.
+ */
+const moduleCache = new Map<string, { mtimeMs: number, value: any }>()
+
+export interface ReadResult {
+  /** The fully-resolved default export, with env values substituted. */
+  values: any
+  /** Raw source text (used by the editor + the writer). */
+  source: string
+  /** Per-key metadata: what's editable, what's read-only and why. */
+  fields: ConfigField[]
+}
+
+export interface ConfigField {
+  key: string
+  /** The currently-resolved value (post env substitution). */
+  value: any
+  /** 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' */
+  type: string
+  /** True when this scalar can be safely round-tripped on write. */
+  editable: boolean
+  /** Human-readable reason when editable === false. */
+  reason?: string
+}
+
+/** Read one config file by name (e.g. 'email'). */
+export async function readConfig(name: string): Promise<ReadResult | null> {
+  const path = join(configDir(), `${name}.ts`)
+  if (!existsSync(path)) return null
+
+  const stat = await Bun.file(path).stat?.().catch(() => null)
+  const mtimeMs = stat?.mtimeMs ?? Date.now()
+
+  // Read the source as the source-of-truth for the field listing.
+  // We deliberately do NOT re-`import()` the file after every edit — Bun
+  // caches modules by URL, query-string cache-busting (`?t=…`) caused
+  // intermittent 0-status responses for some configs (likely when the
+  // resolved value held a function or unsupported sentinel). The source
+  // text + a one-off initial import gives us everything the editor
+  // needs without re-executing the config graph on every keystroke.
+  const source = readFileSync(path, 'utf8')
+
+  let modVal: any
+  const cached = moduleCache.get(path)
+  if (cached) {
+    modVal = cached.value
+  }
+  else {
+    try {
+      const mod = await import(path)
+      modVal = mod?.default ?? mod
+      moduleCache.set(path, { mtimeMs, value: modVal })
+    }
+    catch (err) {
+      throw new Error(`Failed to load config/${name}.ts: ${(err as Error).message}`)
+    }
+  }
+
+  // For previously-cached modules, refresh scalar fields from the source
+  // text instead of re-importing — that way edits made via this API are
+  // reflected immediately in subsequent reads without paying the import
+  // re-evaluation cost (and without tripping Bun's URL cache).
+  modVal = applySourceOverrides(modVal, source)
+  const fields = describeFields(modVal, source)
+  return { values: modVal, source, fields }
+}
+
+/**
+ * Update a single top-level key in a config file. Returns the rewritten
+ * source on success, or throws when the key is non-editable (nested,
+ * env-backed, etc.) — caller should surface that to the UI.
+ */
+export interface UpdateResult {
+  ok: boolean
+  newValue: any
+  source: string
+}
+
+export async function updateConfigKey(
+  name: string,
+  key: string,
+  newValue: string | number | boolean,
+): Promise<UpdateResult> {
+  const path = join(configDir(), `${name}.ts`)
+  if (!existsSync(path))
+    throw new Error(`config/${name}.ts not found`)
+
+  const source = readFileSync(path, 'utf8')
+  const rewritten = rewriteKey(source, key, newValue)
+  if (!rewritten)
+    throw new Error(`Cannot edit "${key}" in config/${name}.ts — key is not a top-level scalar literal (likely env-backed or nested).`)
+
+  writeFileSync(path, rewritten, 'utf8')
+  // We don't bust moduleCache here on purpose — re-importing with a
+  // changed-on-disk file via Bun reuses the original module from the
+  // first import; subsequent reads pick up the edit through the source-
+  // text overlay (`applySourceOverrides`) instead.
+  return { ok: true, newValue, source: rewritten }
+}
+
+/**
+ * Walk the source text for top-level scalar literal assignments and
+ * overlay them onto the given values object. This lets us reflect
+ * post-write edits without paying the cost (and risk) of re-importing
+ * the whole config module after every keystroke.
+ */
+function applySourceOverrides(values: any, source: string): any {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) return values
+  const out: Record<string, any> = { ...values }
+  for (const key of Object.keys(out)) {
+    const re = scalarLiteralRegex(key)
+    const m = re.exec(source)
+    if (!m) continue
+    const literal = m[4]
+    const parsed = parseLiteral(literal)
+    if (parsed !== UNSUPPORTED) out[key] = parsed
+  }
+  return out
+}
+
+const UNSUPPORTED = Symbol('unsupported')
+function parseLiteral(literal: string): any {
+  if (literal === 'true') return true
+  if (literal === 'false') return false
+  if (literal === 'null') return null
+  if (/^-?\d+(?:\.\d+)?$/.test(literal)) return Number(literal)
+  if ((literal.startsWith('\'') && literal.endsWith('\'')) || (literal.startsWith('"') && literal.endsWith('"'))) {
+    return literal.slice(1, -1)
+  }
+  return UNSUPPORTED
+}
+
+/* -------------------------------------------------------------------------- */
+/* Internals                                                                  */
+/* -------------------------------------------------------------------------- */
+
+function titleCase(name: string): string {
+  return name
+    .split(/[-_]/)
+    .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+    .join(' ')
+}
+
+function describeFields(values: any, source: string): ConfigField[] {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) return []
+  const out: ConfigField[] = []
+  for (const [key, value] of Object.entries(values)) {
+    const type = typeOf(value)
+    const editable = isScalar(type)
+    let reason: string | undefined
+    if (!editable) {
+      reason = type === 'object' || type === 'array'
+        ? 'Nested values can be edited by hand in the file'
+        : 'Unsupported type'
+    }
+    else if (!hasScalarLiteral(source, key)) {
+      // The source value is a non-literal expression like `env.FOO ?? 'x'`.
+      // We can't safely rewrite it without losing the env fallback.
+      // Mark as read-only and tell the user to set the env var instead.
+      out.push({
+        key,
+        value,
+        type,
+        editable: false,
+        reason: 'Defined via env var or expression — set the env variable to change',
+      })
+      continue
+    }
+    out.push({ key, value, type, editable, reason })
+  }
+  return out
+}
+
+function typeOf(v: any): string {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'array'
+  return typeof v
+}
+
+function isScalar(t: string): boolean {
+  return t === 'string' || t === 'number' || t === 'boolean'
+}
+
+/**
+ * Detects whether a top-level key in the export-default block is set
+ * directly to a scalar literal — `key: 'value'`, `key: 42`, `key: true`.
+ *
+ * The match is intentionally conservative: it only succeeds when the
+ * value following the colon is a single string/number/boolean literal,
+ * optionally followed by a comma. Anything more complex
+ * (`env.X ?? 'y'`, `[1, 2]`, `{ a: 1 }`, multi-line arrays, etc.)
+ * fails so we don't accidentally clobber an expression.
+ */
+function hasScalarLiteral(source: string, key: string): boolean {
+  const re = scalarLiteralRegex(key)
+  return re.test(source)
+}
+
+function scalarLiteralRegex(key: string): RegExp {
+  const k = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  // Matches:
+  //   <indent><key>: 'value' OR "value" OR 123 OR true/false/null
+  // followed by optional comma + line-ending. The line MUST not contain
+  // operators (??, ||, &&, +, ?), function calls, or sub-objects.
+  return new RegExp(
+    `^(\\s*)(${k})(\\s*:\\s*)('[^'\\n]*'|"[^"\\n]*"|-?\\d+(?:\\.\\d+)?|true|false|null)(\\s*,?\\s*)$`,
+    'm',
+  )
+}
+
+function rewriteKey(source: string, key: string, newValue: string | number | boolean): string | null {
+  const re = scalarLiteralRegex(key)
+  if (!re.test(source)) return null
+  const literal = serializeScalar(newValue)
+  return source.replace(re, (_full, indent, k, sep, _old, tail) => {
+    return `${indent}${k}${sep}${literal}${tail}`
+  })
+}
+
+function serializeScalar(v: string | number | boolean): string {
+  if (typeof v === 'string') {
+    // Prefer single quotes; fall back to double if the value contains a
+    // bare apostrophe (avoid escape gymnastics).
+    if (v.includes('\'') && !v.includes('"')) return `"${v}"`
+    return `'${v.replace(/'/g, '\\\'')}'`
+  }
+  return String(v)
+}

package/resources/functions/dashboard/data.ts

@@ -0,0 +1,375 @@
+/**
+ * Shared dashboard server-side helpers.
+ *
+ * Dashboard `.stx` pages run a `<script server>` block at request time,
+ * import the framework's ORM, query for data, and shape it for the
+ * template. Several pages need the same primitives — a safe model load
+ * (the orm package only re-exports User/Job/FailedJob, the rest must be
+ * loaded by file path), null-tolerant getters, and small aggregation
+ * helpers — so they live here instead of being copy-pasted into every
+ * page header.
+ *
+ * Usage from inside a page's `<script server>`:
+ *
+ *   const { loadModel, safeAll, safeGet, countBy } =
+ *     await import('../../../resources/functions/dashboard/data')
+ *   const Order = await loadModel('Order')
+ *   const orders = await safeAll(Order)
+ *   const byStatus = countBy(orders, 'status')
+ */
+
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+let projectRootCache: string | null = null
+
+function projectRoot(): string {
+  if (projectRootCache) return projectRootCache
+  // Walk up from this file location to find the project root (the dir
+  // that contains `storage/framework/defaults`). This mirrors what
+  // `@stacksjs/path` does, but without pulling in the path package
+  // (which has its own evaluation graph and would slow page renders).
+  let dir = dirname(new URL(import.meta.url).pathname)
+  for (let i = 0; i < 12; i++) {
+    if (existsSync(resolve(dir, 'storage/framework/defaults'))) {
+      projectRootCache = dir
+      return dir
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  // Fall back to cwd — STX serves run from the project root.
+  projectRootCache = process.cwd()
+  return projectRootCache
+}
+
+/**
+ * Map of model name → list of relative paths to try, in order. The first
+ * existing file wins. User overrides at `app/Models/<Name>.ts` always
+ * take priority over framework defaults. The defaults are organised in
+ * subdirectories (commerce/, Content/, realtime/) so each model needs an
+ * explicit lookup table — globbing at request time would add ~50ms per
+ * page render.
+ */
+const MODEL_PATHS: Record<string, string[]> = {
+  // Auth / core
+  User: ['app/Models/User.ts', 'storage/framework/defaults/app/Models/User.ts'],
+  Team: ['app/Models/Team.ts', 'storage/framework/defaults/app/Models/Team.ts'],
+  Subscriber: ['app/Models/Subscriber.ts', 'storage/framework/defaults/app/Models/Subscriber.ts'],
+  SubscriberEmail: ['app/Models/SubscriberEmail.ts', 'storage/framework/defaults/app/Models/SubscriberEmail.ts'],
+  Subscription: ['app/Models/Subscription.ts', 'storage/framework/defaults/app/Models/Subscription.ts'],
+
+  // Content
+  Post: ['app/Models/Post.ts', 'storage/framework/defaults/app/Models/Content/Post.ts'],
+  Page: ['app/Models/Page.ts', 'storage/framework/defaults/app/Models/Content/Page.ts'],
+  Author: ['app/Models/Author.ts', 'storage/framework/defaults/app/Models/Content/Author.ts'],
+  Comment: ['app/Models/Comment.ts', 'storage/framework/defaults/app/Models/Comment.ts'],
+  Tag: ['app/Models/Tag.ts', 'storage/framework/defaults/app/Models/Tag.ts'],
+  Category: ['app/Models/Category.ts', 'storage/framework/defaults/app/Models/commerce/Category.ts'],
+
+  // App / operations
+  Activity: ['app/Models/Activity.ts', 'storage/framework/defaults/app/Models/Activity.ts'],
+  Deployment: ['app/Models/Deployment.ts', 'storage/framework/defaults/app/Models/Deployment.ts'],
+  Release: ['app/Models/Release.ts', 'storage/framework/defaults/app/Models/Release.ts'],
+  Notification: ['app/Models/Notification.ts', 'storage/framework/defaults/app/Models/Notification.ts'],
+  Job: ['app/Models/Job.ts', 'storage/framework/defaults/app/Models/Job.ts'],
+  FailedJob: ['app/Models/FailedJob.ts', 'storage/framework/defaults/app/Models/FailedJob.ts'],
+  Log: ['app/Models/Log.ts', 'storage/framework/defaults/app/Models/Log.ts'],
+  Request: ['app/Models/Request.ts', 'storage/framework/defaults/app/Models/Request.ts'],
+  Error: ['app/Models/Error.ts', 'storage/framework/defaults/app/Models/Error.ts'],
+  Websocket: ['app/Models/Websocket.ts', 'storage/framework/defaults/app/Models/realtime/Websocket.ts'],
+
+  // Marketing
+  Campaign: ['app/Models/Campaign.ts', 'storage/framework/defaults/app/Models/Campaign.ts'],
+  EmailList: ['app/Models/EmailList.ts', 'storage/framework/defaults/app/Models/EmailList.ts'],
+  SocialPost: ['app/Models/SocialPost.ts', 'storage/framework/defaults/app/Models/SocialPost.ts'],
+
+  // Commerce
+  Order: ['app/Models/Order.ts', 'storage/framework/defaults/app/Models/commerce/Order.ts'],
+  OrderItem: ['app/Models/OrderItem.ts', 'storage/framework/defaults/app/Models/commerce/OrderItem.ts'],
+  Cart: ['app/Models/Cart.ts', 'storage/framework/defaults/app/Models/commerce/Cart.ts'],
+  CartItem: ['app/Models/CartItem.ts', 'storage/framework/defaults/app/Models/commerce/CartItem.ts'],
+  Customer: ['app/Models/Customer.ts', 'storage/framework/defaults/app/Models/commerce/Customer.ts'],
+  Product: ['app/Models/Product.ts', 'storage/framework/defaults/app/Models/commerce/Product.ts'],
+  ProductVariant: ['app/Models/ProductVariant.ts', 'storage/framework/defaults/app/Models/commerce/ProductVariant.ts'],
+  ProductUnit: ['app/Models/ProductUnit.ts', 'storage/framework/defaults/app/Models/commerce/ProductUnit.ts'],
+  Manufacturer: ['app/Models/Manufacturer.ts', 'storage/framework/defaults/app/Models/commerce/Manufacturer.ts'],
+  Coupon: ['app/Models/Coupon.ts', 'storage/framework/defaults/app/Models/commerce/Coupon.ts'],
+  GiftCard: ['app/Models/GiftCard.ts', 'storage/framework/defaults/app/Models/commerce/GiftCard.ts'],
+  LicenseKey: ['app/Models/LicenseKey.ts', 'storage/framework/defaults/app/Models/commerce/LicenseKey.ts'],
+  Review: ['app/Models/Review.ts', 'storage/framework/defaults/app/Models/commerce/Review.ts'],
+  Receipt: ['app/Models/Receipt.ts', 'storage/framework/defaults/app/Models/commerce/Receipt.ts'],
+  PrintDevice: ['app/Models/PrintDevice.ts', 'storage/framework/defaults/app/Models/commerce/PrintDevice.ts'],
+  ShippingMethod: ['app/Models/ShippingMethod.ts', 'storage/framework/defaults/app/Models/commerce/ShippingMethod.ts'],
+  ShippingRate: ['app/Models/ShippingRate.ts', 'storage/framework/defaults/app/Models/commerce/ShippingRate.ts'],
+  ShippingZone: ['app/Models/ShippingZone.ts', 'storage/framework/defaults/app/Models/commerce/ShippingZone.ts'],
+  DeliveryRoute: ['app/Models/DeliveryRoute.ts', 'storage/framework/defaults/app/Models/commerce/DeliveryRoute.ts'],
+  DigitalDelivery: ['app/Models/DigitalDelivery.ts', 'storage/framework/defaults/app/Models/commerce/DigitalDelivery.ts'],
+  Driver: ['app/Models/Driver.ts', 'storage/framework/defaults/app/Models/commerce/Driver.ts'],
+  TaxRate: ['app/Models/TaxRate.ts', 'storage/framework/defaults/app/Models/commerce/TaxRate.ts'],
+  WaitlistProduct: ['app/Models/WaitlistProduct.ts', 'storage/framework/defaults/app/Models/commerce/WaitlistProduct.ts'],
+  WaitlistRestaurant: ['app/Models/WaitlistRestaurant.ts', 'storage/framework/defaults/app/Models/commerce/WaitlistRestaurant.ts'],
+  LoyaltyPoint: ['app/Models/LoyaltyPoint.ts', 'storage/framework/defaults/app/Models/commerce/LoyaltyPoint.ts'],
+  LoyaltyReward: ['app/Models/LoyaltyReward.ts', 'storage/framework/defaults/app/Models/commerce/LoyaltyReward.ts'],
+  Payment: ['app/Models/Payment.ts', 'storage/framework/defaults/app/Models/commerce/Payment.ts'],
+  PaymentMethod: ['app/Models/PaymentMethod.ts', 'storage/framework/defaults/app/Models/PaymentMethod.ts'],
+  PaymentProduct: ['app/Models/PaymentProduct.ts', 'storage/framework/defaults/app/Models/PaymentProduct.ts'],
+  PaymentTransaction: ['app/Models/PaymentTransaction.ts', 'storage/framework/defaults/app/Models/PaymentTransaction.ts'],
+  Transaction: ['app/Models/Transaction.ts', 'storage/framework/defaults/app/Models/commerce/Transaction.ts'],
+}
+
+const modelCache = new Map<string, any>()
+
+/**
+ * Load a model class by name, searching userland first then framework
+ * defaults. Returns a stub with no-op `.all()` / `.orderBy()` / `.count()`
+ * methods if the model file doesn't exist or fails to import — pages can
+ * always call query methods on the result without try/catch around the
+ * load itself.
+ */
+export async function loadModel(name: string): Promise<any> {
+  if (modelCache.has(name)) return modelCache.get(name)
+
+  const candidates = MODEL_PATHS[name]
+  if (!candidates) {
+    const stub = makeStub(name)
+    modelCache.set(name, stub)
+    return stub
+  }
+
+  const root = projectRoot()
+  for (const rel of candidates) {
+    const abs = resolve(root, rel)
+    if (!existsSync(abs)) continue
+    try {
+      const mod = await import(abs)
+      const M = mod?.default ?? mod
+      if (M) {
+        modelCache.set(name, M)
+        return M
+      }
+    }
+    catch {
+      // Try the next candidate path; final fallback is the stub below.
+    }
+  }
+
+  const stub = makeStub(name)
+  modelCache.set(name, stub)
+  return stub
+}
+
+/**
+ * Load several models at once. Resolves to a record so callers can
+ * destructure: `const { Order, Product } = await loadModels(['Order', 'Product'])`.
+ */
+export async function loadModels<T extends string>(names: T[]): Promise<Record<T, any>> {
+  const out = {} as Record<T, any>
+  await Promise.all(names.map(async (n) => {
+    out[n] = await loadModel(n)
+  }))
+  return out
+}
+
+function makeStub(_name: string): any {
+  const empty: any[] = []
+  const chain: any = {
+    get: async () => empty,
+    all: async () => empty,
+    count: async () => 0,
+    first: async () => null,
+    find: async () => null,
+    where: () => chain,
+    orderBy: () => chain,
+    orderByDesc: () => chain,
+    limit: () => chain,
+    take: () => chain,
+    skip: () => chain,
+    select: () => chain,
+    distinct: () => chain,
+    groupBy: () => chain,
+    whereIn: () => chain,
+    whereNotNull: () => chain,
+    whereNull: () => chain,
+    _isStub: true,
+  }
+  return chain
+}
+
+/**
+ * Run `Model.all()` and always resolve to an array — never throws, never
+ * returns undefined. Use this whenever you need every row of a table for
+ * the page (the seeder caps each table at ~50 rows so the cost is fine).
+ */
+export async function safeAll(Model: any): Promise<any[]> {
+  if (!Model) return []
+  try {
+    if (typeof Model.all === 'function') {
+      const rows = await Model.all()
+      return Array.isArray(rows) ? rows : []
+    }
+    if (typeof Model.get === 'function') {
+      const rows = await Model.get()
+      return Array.isArray(rows) ? rows : []
+    }
+  }
+  catch {
+    // DB unreachable / table missing / model schema mismatch — page
+    // should render an empty state, not a 500.
+  }
+  return []
+}
+
+/**
+ * Run `Model.count()` and always resolve to a number — never throws. Falls
+ * back to `safeAll(Model).length` when the model has no `.count` method
+ * (rare, but the makeStub stub provides one so this is mostly defensive).
+ */
+export async function safeCount(Model: any): Promise<number> {
+  if (!Model) return 0
+  try {
+    if (typeof Model.count === 'function') {
+      const n = await Model.count()
+      return typeof n === 'number' ? n : 0
+    }
+  }
+  catch {
+    // count() may fail if the table doesn't exist; let safeAll absorb that
+    // by returning [] and we'll report 0 records.
+  }
+  const rows = await safeAll(Model)
+  return rows.length
+}
+
+/**
+ * Read a column off a model row, tolerating both proxy-style rows
+ * (`row.get('name')`) and plain object rows (`row.name`). Returns the
+ * fallback when the column is missing or null/undefined.
+ */
+export function safeGet(row: any, key: string, fallback: any = ''): any {
+  if (!row) return fallback
+  try {
+    if (typeof row.get === 'function') {
+      const v = row.get(key)
+      if (v !== undefined && v !== null) return v
+    }
+  }
+  catch { /* fall through to direct property access */ }
+  const direct = row[key]
+  return direct !== undefined && direct !== null ? direct : fallback
+}
+
+/** Group rows by the value of a column. */
+export function countBy(rows: any[], key: string): Record<string, number> {
+  const out: Record<string, number> = {}
+  for (const r of rows) {
+    const v = String(safeGet(r, key, '') || 'unknown')
+    out[v] = (out[v] || 0) + 1
+  }
+  return out
+}
+
+/** Sum a numeric column across rows. */
+export function sumBy(rows: any[], key: string): number {
+  let total = 0
+  for (const r of rows) {
+    const v = Number(safeGet(r, key, 0)) || 0
+    total += v
+  }
+  return total
+}
+
+/** Top N values of a column with their counts, sorted desc. */
+export function topN(rows: any[], key: string, n = 5): Array<{ value: string, count: number }> {
+  const counts = countBy(rows, key)
+  return Object.entries(counts)
+    .map(([value, count]) => ({ value, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, n)
+}
+
+/**
+ * Group rows into buckets by ISO date. Returns a window of `days` from
+ * today backwards, with zero-counts for empty days so charts render a
+ * smooth line. Date column is parsed as `Date(value)`.
+ */
+export function groupByDay(
+  rows: any[],
+  key: string,
+  days = 30,
+): Array<{ date: string, count: number }> {
+  const buckets: Record<string, number> = {}
+  const today = new Date()
+  today.setHours(0, 0, 0, 0)
+  for (let i = days - 1; i >= 0; i--) {
+    const d = new Date(today)
+    d.setDate(today.getDate() - i)
+    buckets[d.toISOString().slice(0, 10)] = 0
+  }
+  for (const r of rows) {
+    const raw = safeGet(r, key, null)
+    if (!raw) continue
+    const d = new Date(raw)
+    if (Number.isNaN(d.getTime())) continue
+    const k = d.toISOString().slice(0, 10)
+    if (k in buckets) buckets[k]++
+  }
+  return Object.entries(buckets).map(([date, count]) => ({ date, count }))
+}
+
+/**
+ * Sum a numeric column into per-day buckets. Same windowing semantics as
+ * `groupByDay` — useful for revenue-over-time charts.
+ */
+export function sumByDay(
+  rows: any[],
+  dateKey: string,
+  valueKey: string,
+  days = 30,
+): Array<{ date: string, total: number }> {
+  const buckets: Record<string, number> = {}
+  const today = new Date()
+  today.setHours(0, 0, 0, 0)
+  for (let i = days - 1; i >= 0; i--) {
+    const d = new Date(today)
+    d.setDate(today.getDate() - i)
+    buckets[d.toISOString().slice(0, 10)] = 0
+  }
+  for (const r of rows) {
+    const raw = safeGet(r, dateKey, null)
+    if (!raw) continue
+    const d = new Date(raw)
+    if (Number.isNaN(d.getTime())) continue
+    const k = d.toISOString().slice(0, 10)
+    if (!(k in buckets)) continue
+    buckets[k] += Number(safeGet(r, valueKey, 0)) || 0
+  }
+  return Object.entries(buckets).map(([date, total]) => ({ date, total }))
+}
+
+/** "5m ago" / "2h ago" / "3d ago" style relative time. Stable on server. */
+export function formatRelative(input: any): string {
+  if (!input) return ''
+  const d = new Date(input)
+  if (Number.isNaN(d.getTime())) return String(input)
+  const diff = Math.max(0, Date.now() - d.getTime())
+  const sec = Math.floor(diff / 1000)
+  if (sec < 60) return 'just now'
+  const min = Math.floor(sec / 60)
+  if (min < 60) return `${min}m ago`
+  const hr = Math.floor(min / 60)
+  if (hr < 24) return `${hr}h ago`
+  const day = Math.floor(hr / 24)
+  if (day < 30) return `${day}d ago`
+  const mo = Math.floor(day / 30)
+  if (mo < 12) return `${mo}mo ago`
+  const yr = Math.floor(mo / 12)
+  return `${yr}y ago`
+}
+
+/** Format any value as USD with no fractional cents for whole numbers. */
+export function formatCurrency(value: any): string {
+  const n = Number(value) || 0
+  return `$${n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`
+}