@quazardous/qdadm 1.19.3

package/src/types/index.ts

@@ -0,0 +1,285 @@
+/**
+ * Core types for qdadm framework
+ */
+
+// ============ ENTITY TYPES ============
+
+/**
+ * Base interface for all entity records
+ */
+export interface EntityRecord {
+  id: string | number
+  [key: string]: unknown
+}
+
+/**
+ * Parameters for list operations
+ */
+export interface ListParams {
+  page?: number
+  page_size?: number
+  search?: string
+  filters?: Record<string, unknown>
+  sort_by?: string
+  sort_order?: 'asc' | 'desc'
+  cacheSafe?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * Result of list operations
+ */
+export interface ListResult<T = EntityRecord> {
+  items: T[]
+  total: number
+  fromCache?: boolean
+}
+
+// ============ STORAGE TYPES ============
+
+/**
+ * Storage capabilities declaration
+ */
+export interface StorageCapabilities {
+  supportsTotal: boolean
+  supportsFilters: boolean
+  supportsPagination: boolean
+  supportsCaching: boolean
+  requiresAuth?: boolean
+  searchFields?: string[]
+  /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Can be set dynamically from API headers. */
+  cacheTtlMs?: number
+  /** Asymmetric mode: list() and get() return different structures. Falls back from EntityManagerOptions. */
+  asymmetric?: boolean
+}
+
+// ============ FIELD TYPES ============
+
+/**
+ * Field type definitions
+ */
+export type FieldType =
+  | 'text'
+  | 'number'
+  | 'boolean'
+  | 'select'
+  | 'multiselect'
+  | 'date'
+  | 'datetime'
+  | 'email'
+  | 'url'
+  | 'textarea'
+  | 'password'
+  | 'array'
+  | 'object'
+  | 'json'
+  | string
+
+/**
+ * Field configuration
+ */
+export interface FieldConfig {
+  type: FieldType
+  label?: string
+  required?: boolean
+  default?: unknown | (() => unknown)
+  options?: Array<{ label: string; value: unknown }>
+  reference?: {
+    entity: string
+    labelField?: string
+    valueField?: string
+  }
+  listable?: boolean
+  editable?: boolean
+  sortable?: boolean
+  filterable?: boolean
+  searchable?: boolean
+  validator?: (value: unknown) => boolean | string
+  [key: string]: unknown
+}
+
+// ============ ENTITY MANAGER TYPES ============
+
+/**
+ * Child entity configuration
+ */
+export interface ChildConfig {
+  entity: string
+  endpoint?: string
+}
+
+/**
+ * Parent entity configuration
+ */
+export interface ParentConfig {
+  entity: string
+  foreignKey: string
+}
+
+/**
+ * Relation configuration
+ */
+export interface RelationConfig {
+  entity: string
+  through?: string
+}
+
+/**
+ * Navigation configuration for auto-generated menus
+ */
+export interface NavConfig {
+  icon?: string
+  section?: string
+  weight?: number
+  visible?: boolean | (() => boolean)
+}
+
+/**
+ * EntityManager constructor options
+ */
+export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
+  name: string
+  storage?: IStorage<T> | null
+  idField?: string
+  label?: string
+  labelPlural?: string
+  routePrefix?: string
+  labelField?: string | ((entity: T) => string)
+  fields?: Record<string, FieldConfig>
+  localFilterThreshold?: number | null
+  /** 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. */
+  asymmetric?: boolean
+  /** Detail cache TTL in milliseconds (0=disabled (default), -1=infinite, >0=TTL). Only used when asymmetric=true. */
+  detailCacheTtlMs?: number
+  readOnly?: boolean
+  warmup?: boolean
+  authSensitive?: boolean
+  system?: boolean
+  scopeWhitelist?: string[] | null
+  isOwn?: ((record: T, user: unknown) => boolean) | null
+  children?: Record<string, ChildConfig>
+  parent?: ParentConfig | null
+  parents?: Record<string, ParentConfig>
+  relations?: Record<string, RelationConfig>
+  authAdapter?: EntityAuthAdapter | null
+  nav?: NavConfig
+}
+
+// ============ AUTH TYPES ============
+
+/**
+ * Standard auth actions
+ */
+export type AuthAction = 'read' | 'list' | 'create' | 'update' | 'delete'
+
+/**
+ * Entity auth adapter interface
+ */
+export interface EntityAuthAdapter {
+  canPerform(entity: string, action: AuthAction): boolean
+  canAccessRecord?(entity: string, record: unknown): boolean
+  isGranted?(permission: string, record?: unknown): boolean
+  getCurrentUser?(): unknown
+}
+
+// ============ SIGNAL TYPES ============
+
+/**
+ * Signal handler context
+ */
+export interface ListenerContext {
+  id?: string
+  cancel: () => void
+  emit: (signal: string, payload: unknown) => Promise<void>
+}
+
+/**
+ * Signal event object
+ */
+export interface SignalEvent {
+  name: string
+  data: unknown
+}
+
+/**
+ * Signal handler function
+ */
+export type SignalHandler = (
+  event: SignalEvent,
+  ctx: ListenerContext
+) => void | Promise<void>
+
+// ============ HOOK TYPES ============
+
+/**
+ * Hook registration options
+ */
+export interface HookOptions {
+  priority?: number
+  id?: string
+  after?: string | string[]
+  once?: boolean
+}
+
+/**
+ * Hook event object
+ */
+export interface HookEvent {
+  name: string
+  data: unknown
+  cancel: () => void
+}
+
+/**
+ * Hook handler function
+ */
+export type HookHandler = (event: HookEvent) => void | Promise<void>
+
+// ============ PERMISSION TYPES ============
+
+/**
+ * Permission definition
+ */
+export interface PermissionDefinition {
+  key: string
+  namespace: string
+  action: string
+  module: string | null
+  label: string
+  description: string | null
+  custom: boolean
+}
+
+// ============ FORWARD DECLARATIONS ============
+
+// These will be properly typed when their modules are converted
+
+/**
+ * IStorage interface (forward declaration)
+ */
+export interface IStorage<T extends EntityRecord = EntityRecord> {
+  list(params?: ListParams, context?: unknown): Promise<ListResult<T>>
+  get(id: string | number, context?: unknown): Promise<T | null>
+  create(data: Partial<T>): Promise<T>
+  update(id: string | number, data: Partial<T>): Promise<T>
+  patch?(id: string | number, data: Partial<T>): Promise<T>
+  delete(id: string | number): Promise<void>
+  request?(
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    endpoint: string,
+    options?: RequestOptions
+  ): Promise<unknown>
+  reset?(): void
+}
+
+/**
+ * Request options for storage
+ */
+export interface RequestOptions {
+  data?: unknown
+  params?: Record<string, unknown>
+  headers?: Record<string, string>
+  context?: unknown
+}

package/src/types/pluralize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations for pluralize module
+ */
+declare module 'pluralize' {
+  function pluralize(word: string, count?: number, inclusive?: boolean): string
+
+  namespace pluralize {
+    function plural(word: string): string
+    function singular(word: string): string
+    function isPlural(word: string): boolean
+    function isSingular(word: string): boolean
+    function addPluralRule(rule: string | RegExp, replacement: string): void
+    function addSingularRule(rule: string | RegExp, replacement: string): void
+    function addIrregularRule(single: string, plural: string): void
+    function addUncountableRule(word: string | RegExp): void
+  }
+
+  export = pluralize
+}

package/src/types/quarkernel.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Type declarations for @quazardous/quarkernel
+ *
+ * quarkernel is an event-driven kernel library used by qdadm
+ * for signal/event handling.
+ */
+
+declare module '@quazardous/quarkernel' {
+  export interface KernelOptions {
+    debug?: boolean
+    [key: string]: unknown
+  }
+
+  export interface ListenerOptions {
+    priority?: number
+    id?: string
+    after?: string | string[]
+    once?: boolean
+  }
+
+  export interface ListenerContext {
+    id?: string
+    cancel: () => void
+    emit: (signal: string, payload: unknown) => Promise<void>
+  }
+
+  export type ListenerCallback = (
+    event: { name: string; data: unknown },
+    ctx: ListenerContext
+  ) => void | Promise<void>
+
+  export interface ExecutionError {
+    listenerId: string
+    error: Error
+  }
+
+  export interface QuarKernel {
+    on(signal: string, handler: ListenerCallback, options?: ListenerOptions): () => void
+    once(signal: string, handler?: ListenerCallback, options?: ListenerOptions): () => void
+    off(signal: string, handler: ListenerCallback): void
+    emit(signal: string, payload?: unknown): Promise<void>
+    emitSerial(signal: string, payload?: unknown): Promise<void>
+    clearExecutionErrors(): void
+    getExecutionErrors(): ExecutionError[]
+    debug(enabled: boolean): void
+    destroy(): void
+  }
+
+  export function createKernel(options?: KernelOptions): QuarKernel
+}

package/src/utils/formatters.ts

@@ -0,0 +1,174 @@
+/**
+ * Centralized formatting utilities
+ *
+ * Usage:
+ *   import { formatDate, formatDateTime, formatDuration } from '@/dashboard/utils/formatters'
+ *
+ *   {{ formatDate(item.created_at) }}
+ *   {{ formatDateTime(item.updated_at) }}
+ */
+
+// =============================================================================
+// DATE/TIME FORMATTING
+// =============================================================================
+
+/**
+ * Format a date string to localized date+time
+ * Default format: toLocaleString() (e.g., "20/12/2025, 14:30:00")
+ *
+ * @param dateStr - ISO date string or Date object
+ * @param options - Intl.DateTimeFormat options
+ * @returns Formatted date string or '-' if empty
+ */
+export function formatDate(
+  dateStr: string | Date | null | undefined,
+  options: Intl.DateTimeFormatOptions = {}
+): string {
+  if (!dateStr) return '-'
+  const date = new Date(dateStr)
+  if (isNaN(date.getTime())) return '-'
+
+  if (Object.keys(options).length === 0) {
+    return date.toLocaleString()
+  }
+  return date.toLocaleString(undefined, options)
+}
+
+/**
+ * Format to full datetime with year (20/12/2025 14:30)
+ */
+export function formatDateTime(dateStr: string | Date | null | undefined): string {
+  return formatDate(dateStr, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+/**
+ * Format to short datetime without year (20/12 14:30)
+ */
+export function formatDateTimeShort(dateStr: string | Date | null | undefined): string {
+  return formatDate(dateStr, {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+/**
+ * Format to date only (20/12/2025)
+ */
+export function formatDateOnly(dateStr: string | Date | null | undefined): string {
+  if (!dateStr) return '-'
+  const date = new Date(dateStr)
+  if (isNaN(date.getTime())) return '-'
+  return date.toLocaleDateString(undefined, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  })
+}
+
+/**
+ * Format to time only (14:30:00)
+ */
+export function formatTimeOnly(dateStr: string | Date | null | undefined): string {
+  if (!dateStr) return '-'
+  const date = new Date(dateStr)
+  if (isNaN(date.getTime())) return '-'
+  return date.toLocaleTimeString()
+}
+
+/**
+ * Format with "Never" as default (for last_used fields)
+ */
+export function formatDateOrNever(dateStr: string | Date | null | undefined): string {
+  if (!dateStr) return 'Never'
+  return formatDate(dateStr)
+}
+
+// =============================================================================
+// DURATION FORMATTING
+// =============================================================================
+
+/**
+ * Format a duration in milliseconds to human-readable string
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Human-readable duration (e.g., "2h 30m 15s" or "45.2s")
+ */
+export function formatDuration(ms: number | null | undefined): string {
+  if (ms === null || ms === undefined) return '-'
+  if (ms < 1000) return `${ms}ms`
+
+  const seconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60
+    const remainingSeconds = seconds % 60
+    return `${hours}h ${remainingMinutes}m ${remainingSeconds}s`
+  }
+  if (minutes > 0) {
+    const remainingSeconds = seconds % 60
+    return `${minutes}m ${remainingSeconds}s`
+  }
+  // Show decimal seconds for short durations
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+/**
+ * Format duration from start/end timestamps
+ */
+export function formatDurationBetween(
+  startDate: string | Date | null | undefined,
+  endDate: string | Date | null | undefined
+): string {
+  if (!startDate || !endDate) return '-'
+  const start = new Date(startDate)
+  const end = new Date(endDate)
+  if (isNaN(start.getTime()) || isNaN(end.getTime())) return '-'
+  return formatDuration(end.getTime() - start.getTime())
+}
+
+// =============================================================================
+// NUMBER FORMATTING
+// =============================================================================
+
+/**
+ * Format a number with locale-specific separators
+ */
+export function formatNumber(
+  value: number | null | undefined,
+  options: Intl.NumberFormatOptions = {}
+): string {
+  if (value === null || value === undefined) return '-'
+  return value.toLocaleString(undefined, options)
+}
+
+/**
+ * Format bytes to human-readable size
+ */
+export function formatBytes(bytes: number | null | undefined): string {
+  if (bytes === null || bytes === undefined) return '-'
+  if (bytes === 0) return '0 B'
+
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  const k = 1024
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+
+  return `${(bytes / Math.pow(k, i)).toFixed(1)} ${units[i]}`
+}
+
+/**
+ * Format a percentage
+ */
+export function formatPercent(value: number | null | undefined, decimals = 1): string {
+  if (value === null || value === undefined) return '-'
+  return `${(value * 100).toFixed(decimals)}%`
+}

package/src/utils/index.ts

@@ -0,0 +1,35 @@
+/**
+ * qdadm - Utils exports
+ */
+
+// Formatters
+export {
+  formatDate,
+  formatDateTime,
+  formatDateTimeShort,
+  formatDateOnly,
+  formatTimeOnly,
+  formatDateOrNever,
+  formatDuration,
+  formatDurationBetween,
+  formatNumber,
+  formatBytes,
+  formatPercent,
+} from './formatters'
+
+// Transformers
+export {
+  toKeyValueArray,
+  toKeyValueObject,
+  toLanguageCodes,
+  toLanguageObjects,
+  toDateObject,
+  toIsoDate,
+  toIsoDateTime,
+  deepClone,
+  getSparseUpdate,
+  isEqual,
+} from './transformers'
+
+// Type exports
+export type { KeyValuePair, LanguageObject } from './transformers'

package/src/utils/transformers.ts

@@ -0,0 +1,131 @@
+/**
+ * Data transformation utilities for forms
+ *
+ * Provides consistent conversions between API data formats and form structures.
+ */
+
+/**
+ * Key-value pair structure for KeyValueEditor
+ */
+export interface KeyValuePair {
+  key: string
+  value: unknown
+}
+
+/**
+ * Language object structure
+ */
+export interface LanguageObject {
+  code: string
+  fluency: number
+}
+
+/**
+ * Convert object {key: value} to array [{key, value}] for KeyValueEditor
+ */
+export function toKeyValueArray(obj: Record<string, unknown> | null | undefined): KeyValuePair[] {
+  if (!obj || typeof obj !== 'object') return []
+  return Object.entries(obj).map(([key, value]) => ({ key, value }))
+}
+
+/**
+ * Convert array [{key, value}] to object {key: value} for API
+ */
+export function toKeyValueObject(arr: KeyValuePair[] | null | undefined): Record<string, unknown> {
+  if (!Array.isArray(arr)) return {}
+  return Object.fromEntries(
+    arr.filter((item) => item.key && item.key.trim()).map((item) => [item.key.trim(), item.value])
+  )
+}
+
+/**
+ * Convert language objects [{code, fluency}] to array of codes ['en', 'fr']
+ */
+export function toLanguageCodes(
+  languages: Array<string | LanguageObject> | null | undefined
+): string[] {
+  if (!Array.isArray(languages)) return []
+  return languages
+    .map((l) => (typeof l === 'string' ? l : l.code))
+    .filter((code): code is string => Boolean(code))
+}
+
+/**
+ * Convert array of codes to language objects [{code, fluency}]
+ */
+export function toLanguageObjects(
+  codes: Array<string | LanguageObject> | null | undefined,
+  defaultFluency = 1
+): LanguageObject[] {
+  if (!Array.isArray(codes)) return []
+  return codes.filter(Boolean).map((code) => ({
+    code: typeof code === 'string' ? code : code.code,
+    fluency: typeof code === 'object' && code !== null ? code.fluency : defaultFluency,
+  }))
+}
+
+/**
+ * Convert ISO date string to Date object
+ */
+export function toDateObject(dateStr: string | Date | null | undefined): Date | null {
+  if (!dateStr) return null
+  if (dateStr instanceof Date) return dateStr
+  return new Date(dateStr)
+}
+
+/**
+ * Convert Date to ISO date string (YYYY-MM-DD)
+ */
+export function toIsoDate(date: string | Date | null | undefined): string | null {
+  if (!date) return null
+  if (typeof date === 'string') return date.split('T')[0] ?? date
+  return date.toISOString().split('T')[0] ?? null
+}
+
+/**
+ * Convert Date to ISO datetime string
+ */
+export function toIsoDateTime(date: string | Date | null | undefined): string | null {
+  if (!date) return null
+  if (typeof date === 'string') return date
+  return date.toISOString()
+}
+
+/**
+ * Deep clone an object (for snapshots)
+ */
+export function deepClone<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') return obj
+  if (obj instanceof Date) return new Date(obj) as unknown as T
+  if (Array.isArray(obj)) return obj.map(deepClone) as unknown as T
+  return Object.fromEntries(
+    Object.entries(obj as Record<string, unknown>).map(([k, v]) => [k, deepClone(v)])
+  ) as unknown as T
+}
+
+/**
+ * Get sparse update object (only changed fields)
+ */
+export function getSparseUpdate<T extends Record<string, unknown>>(
+  original: T,
+  modified: T,
+  excludeFields: string[] = []
+): Partial<T> {
+  const patch: Partial<T> = {}
+  for (const key in modified) {
+    if (excludeFields.includes(key)) continue
+    const origVal = JSON.stringify(original[key])
+    const modVal = JSON.stringify(modified[key])
+    if (origVal !== modVal) {
+      patch[key as keyof T] = modified[key]
+    }
+  }
+  return patch
+}
+
+/**
+ * Check if two values are deeply equal
+ */
+export function isEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}