@jmruthers/pace-core 0.2.4

package/docs/api-reference/utilities.md

@@ -0,0 +1,1104 @@
+# Utilities API Reference
+
+This section provides detailed documentation for all utility functions in `@jmruthers/pace-core`.
+
+## Authentication Utilities
+
+### createSupabaseClient
+
+Creates a configured Supabase client instance.
+
+```typescript
+function createSupabaseClient(
+  supabaseUrl: string,
+  supabaseAnonKey: string,
+  options?: SupabaseClientOptions
+): SupabaseClient<Database>;
+```
+
+#### Usage
+
+```typescript
+import { createSupabaseClient } from '@jmruthers/pace-core';
+
+const supabase = createSupabaseClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+);
+```
+
+### validateAuthSession
+
+Validates a user session and returns user information.
+
+```typescript
+function validateAuthSession(session: Session | null): {
+  isValid: boolean;
+  user: User | null;
+  error?: string;
+};
+```
+
+#### Usage
+
+```typescript
+import { validateAuthSession } from '@jmruthers/pace-core';
+
+const { isValid, user, error } = validateAuthSession(session);
+
+if (!isValid) {
+  console.error('Invalid session:', error);
+}
+```
+
+### refreshAuthToken
+
+Refreshes an authentication token.
+
+```typescript
+function refreshAuthToken(
+  supabase: SupabaseClient<Database>,
+  refreshToken: string
+): Promise<{
+  success: boolean;
+  session?: Session;
+  error?: string;
+}>;
+```
+
+#### Usage
+
+```typescript
+import { refreshAuthToken } from '@jmruthers/pace-core';
+
+const { success, session, error } = await refreshAuthToken(
+  supabase,
+  currentSession.refresh_token
+);
+
+if (success && session) {
+  // Update session
+}
+```
+
+## Event Utilities
+
+### filterEventsByAccess
+
+Filters events based on user access permissions.
+
+```typescript
+function filterEventsByAccess(
+  events: Event[],
+  userAccess: EventAccess[]
+): Event[];
+```
+
+#### Usage
+
+```typescript
+import { filterEventsByAccess } from '@jmruthers/pace-core';
+
+const accessibleEvents = filterEventsByAccess(events, userAccess);
+```
+
+### sortEventsByDate
+
+Sorts events by date with configurable order.
+
+```typescript
+function sortEventsByDate(
+  events: Event[],
+  order: 'asc' | 'desc' = 'asc'
+): Event[];
+```
+
+#### Usage
+
+```typescript
+import { sortEventsByDate } from '@jmruthers/pace-core';
+
+const sortedEvents = sortEventsByDate(events, 'desc');
+```
+
+### groupEventsByDate
+
+Groups events by date for display purposes.
+
+```typescript
+function groupEventsByDate(events: Event[]): {
+  [date: string]: Event[];
+};
+```
+
+#### Usage
+
+```typescript
+import { groupEventsByDate } from '@jmruthers/pace-core';
+
+const groupedEvents = groupEventsByDate(events);
+
+// Result: { '2024-01-15': [event1, event2], '2024-01-16': [event3] }
+```
+
+### calculateEventDuration
+
+Calculates the duration of an event in various formats.
+
+```typescript
+function calculateEventDuration(
+  startDate: string,
+  endDate: string,
+  format: 'hours' | 'days' | 'minutes' = 'hours'
+): number;
+```
+
+#### Usage
+
+```typescript
+import { calculateEventDuration } from '@jmruthers/pace-core';
+
+const duration = calculateEventDuration(
+  '2024-01-15T09:00:00Z',
+  '2024-01-15T17:00:00Z',
+  'hours'
+); // Returns 8
+```
+
+## RBAC Utilities
+
+### checkPermission
+
+Checks if a user has a specific permission.
+
+```typescript
+function checkPermission(
+  userPermissions: Permission[],
+  requiredPermission: string
+): boolean;
+```
+
+#### Usage
+
+```typescript
+import { checkPermission } from '@jmruthers/pace-core';
+
+const canEditUsers = checkPermission(userPermissions, 'edit:users');
+```
+
+### hasRole
+
+Checks if a user has a specific role.
+
+```typescript
+function hasRole(userRoles: Role[], roleName: string): boolean;
+```
+
+#### Usage
+
+```typescript
+import { hasRole } from '@jmruthers/pace-core';
+
+const isAdmin = hasRole(userRoles, 'admin');
+```
+
+### canAccessResource
+
+Checks if a user can access a specific resource with a given action.
+
+```typescript
+function canAccessResource(
+  userPermissions: Permission[],
+  resource: string,
+  action: string
+): boolean;
+```
+
+#### Usage
+
+```typescript
+import { canAccessResource } from '@jmruthers/pace-core';
+
+const canCreateEvents = canAccessResource(
+  userPermissions,
+  'events',
+  'create'
+);
+```
+
+### buildPermissionString
+
+Builds a permission string from resource and action.
+
+```typescript
+function buildPermissionString(resource: string, action: string): string;
+```
+
+#### Usage
+
+```typescript
+import { buildPermissionString } from '@jmruthers/pace-core';
+
+const permission = buildPermissionString('users', 'read'); // Returns 'read:users'
+```
+
+## Organisation Utilities
+
+### validateOrganisationAccess
+
+Validates if a user has access to an organisation.
+
+```typescript
+function validateOrganisationAccess(
+  userId: string,
+  organisationId: string,
+  organisationMembers: OrganisationMember[]
+): {
+  hasAccess: boolean;
+  role?: string;
+  error?: string;
+};
+```
+
+#### Usage
+
+```typescript
+import { validateOrganisationAccess } from '@jmruthers/pace-core';
+
+const { hasAccess, role } = validateOrganisationAccess(
+  userId,
+  organisationId,
+  organisationMembers
+);
+```
+
+### getOrganisationSettings
+
+Retrieves organisation settings with defaults.
+
+```typescript
+function getOrganisationSettings(
+  organisation: Organisation
+): OrganisationSettings;
+```
+
+#### Usage
+
+```typescript
+import { getOrganisationSettings } from '@jmruthers/pace-core';
+
+const settings = getOrganisationSettings(organisation);
+```
+
+### formatOrganisationName
+
+Formats organisation name for display.
+
+```typescript
+function formatOrganisationName(
+  organisation: Organisation,
+  options?: {
+    includeDescription?: boolean;
+    maxLength?: number;
+  }
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatOrganisationName } from '@jmruthers/pace-core';
+
+const displayName = formatOrganisationName(organisation, {
+  includeDescription: true,
+  maxLength: 50
+});
+```
+
+## Form Utilities
+
+### validateFormData
+
+Validates form data against a Zod schema.
+
+```typescript
+function validateFormData<T>(
+  data: any,
+  schema: ZodSchema<T>
+): {
+  isValid: boolean;
+  data?: T;
+  errors?: Record<string, string>;
+};
+```
+
+#### Usage
+
+```typescript
+import { validateFormData } from '@jmruthers/pace-core';
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+const { isValid, data, errors } = validateFormData(formData, schema);
+```
+
+### formatFormErrors
+
+Formats form validation errors for display.
+
+```typescript
+function formatFormErrors(errors: Record<string, string>): string[];
+```
+
+#### Usage
+
+```typescript
+import { formatFormErrors } from '@jmruthers/pace-core';
+
+const errorMessages = formatFormErrors(errors);
+```
+
+### sanitizeFormData
+
+Sanitizes form data to prevent XSS attacks.
+
+```typescript
+function sanitizeFormData(data: Record<string, any>): Record<string, any>;
+```
+
+#### Usage
+
+```typescript
+import { sanitizeFormData } from '@jmruthers/pace-core';
+
+const sanitizedData = sanitizeFormData(formData);
+```
+
+## Date and Time Utilities
+
+### formatDate
+
+Formats a date string with various options.
+
+```typescript
+function formatDate(
+  date: string | Date,
+  options?: {
+    format?: 'short' | 'long' | 'relative' | 'iso';
+    timezone?: string;
+    locale?: string;
+  }
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatDate } from '@jmruthers/pace-core';
+
+const formattedDate = formatDate('2024-01-15T09:00:00Z', {
+  format: 'long',
+  timezone: 'Australia/Sydney'
+});
+```
+
+### isDateInRange
+
+Checks if a date falls within a specified range.
+
+```typescript
+function isDateInRange(
+  date: string | Date,
+  startDate: string | Date,
+  endDate: string | Date,
+  inclusive?: boolean
+): boolean;
+```
+
+#### Usage
+
+```typescript
+import { isDateInRange } from '@jmruthers/pace-core';
+
+const isInRange = isDateInRange(
+  new Date(),
+  startDate,
+  endDate,
+  true
+);
+```
+
+### getDateRange
+
+Gets a date range with various options.
+
+```typescript
+function getDateRange(
+  startDate: string | Date,
+  endDate: string | Date,
+  interval: 'day' | 'week' | 'month' | 'year' = 'day'
+): Date[];
+```
+
+#### Usage
+
+```typescript
+import { getDateRange } from '@jmruthers/pace-core';
+
+const dateRange = getDateRange(startDate, endDate, 'day');
+```
+
+## String Utilities
+
+### truncateText
+
+Truncates text to a specified length with ellipsis.
+
+```typescript
+function truncateText(
+  text: string,
+  maxLength: number,
+  options?: {
+    ellipsis?: string;
+    preserveWords?: boolean;
+  }
+): string;
+```
+
+#### Usage
+
+```typescript
+import { truncateText } from '@jmruthers/pace-core';
+
+const truncated = truncateText('This is a long text', 10, {
+  ellipsis: '...',
+  preserveWords: true
+});
+```
+
+### slugify
+
+Converts a string to a URL-friendly slug.
+
+```typescript
+function slugify(text: string, options?: {
+  separator?: string;
+  lowercase?: boolean;
+}): string;
+```
+
+#### Usage
+
+```typescript
+import { slugify } from '@jmruthers/pace-core';
+
+const slug = slugify('My Event Title'); // Returns 'my-event-title'
+```
+
+### generateId
+
+Generates a unique identifier.
+
+```typescript
+function generateId(prefix?: string): string;
+```
+
+#### Usage
+
+```typescript
+import { generateId } from '@jmruthers/pace-core';
+
+const id = generateId('event'); // Returns 'event_abc123'
+```
+
+## Array Utilities
+
+### groupBy
+
+Groups array items by a specified key.
+
+```typescript
+function groupBy<T>(
+  array: T[],
+  key: keyof T | ((item: T) => string)
+): Record<string, T[]>;
+```
+
+#### Usage
+
+```typescript
+import { groupBy } from '@jmruthers/pace-core';
+
+const groupedEvents = groupBy(events, 'status');
+```
+
+### uniqueBy
+
+Removes duplicate items from an array based on a key.
+
+```typescript
+function uniqueBy<T>(
+  array: T[],
+  key: keyof T | ((item: T) => string)
+): T[];
+```
+
+#### Usage
+
+```typescript
+import { uniqueBy } from '@jmruthers/pace-core';
+
+const uniqueUsers = uniqueBy(users, 'id');
+```
+
+### sortBy
+
+Sorts an array by a specified key.
+
+```typescript
+function sortBy<T>(
+  array: T[],
+  key: keyof T,
+  order: 'asc' | 'desc' = 'asc'
+): T[];
+```
+
+#### Usage
+
+```typescript
+import { sortBy } from '@jmruthers/pace-core';
+
+const sortedEvents = sortBy(events, 'start_date', 'asc');
+```
+
+## Object Utilities
+
+### deepMerge
+
+Deeply merges two objects.
+
+```typescript
+function deepMerge<T extends Record<string, any>>(
+  target: T,
+  source: Partial<T>
+): T;
+```
+
+#### Usage
+
+```typescript
+import { deepMerge } from '@jmruthers/pace-core';
+
+const merged = deepMerge(defaultSettings, userSettings);
+```
+
+### pick
+
+Creates an object with only the specified keys.
+
+```typescript
+function pick<T, K extends keyof T>(
+  object: T,
+  keys: K[]
+): Pick<T, K>;
+```
+
+#### Usage
+
+```typescript
+import { pick } from '@jmruthers/pace-core';
+
+const userData = pick(user, ['id', 'email', 'name']);
+```
+
+### omit
+
+Creates an object without the specified keys.
+
+```typescript
+function omit<T, K extends keyof T>(
+  object: T,
+  keys: K[]
+): Omit<T, K>;
+```
+
+#### Usage
+
+```typescript
+import { omit } from '@jmruthers/pace-core';
+
+const publicUser = omit(user, ['password', 'private_data']);
+```
+
+## Validation Utilities
+
+### isValidEmail
+
+Validates an email address.
+
+```typescript
+function isValidEmail(email: string): boolean;
+```
+
+#### Usage
+
+```typescript
+import { isValidEmail } from '@jmruthers/pace-core';
+
+const isValid = isValidEmail('user@example.com');
+```
+
+### isValidPhone
+
+Validates a phone number.
+
+```typescript
+function isValidPhone(phone: string): boolean;
+```
+
+#### Usage
+
+```typescript
+import { isValidPhone } from '@jmruthers/pace-core';
+
+const isValid = isValidPhone('+1234567890');
+```
+
+### isValidUrl
+
+Validates a URL.
+
+```typescript
+function isValidUrl(url: string): boolean;
+```
+
+#### Usage
+
+```typescript
+import { isValidUrl } from '@jmruthers/pace-core';
+
+const isValid = isValidUrl('https://example.com');
+```
+
+## Security Utilities
+
+### hashPassword
+
+Hashes a password using bcrypt.
+
+```typescript
+function hashPassword(password: string): Promise<string>;
+```
+
+#### Usage
+
+```typescript
+import { hashPassword } from '@jmruthers/pace-core';
+
+const hashedPassword = await hashPassword('myPassword123');
+```
+
+### verifyPassword
+
+Verifies a password against a hash.
+
+```typescript
+function verifyPassword(password: string, hash: string): Promise<boolean>;
+```
+
+#### Usage
+
+```typescript
+import { verifyPassword } from '@jmruthers/pace-core';
+
+const isValid = await verifyPassword('myPassword123', hashedPassword);
+```
+
+### generateToken
+
+Generates a secure random token.
+
+```typescript
+function generateToken(length?: number): string;
+```
+
+#### Usage
+
+```typescript
+import { generateToken } from '@jmruthers/pace-core';
+
+const token = generateToken(32);
+```
+
+### sanitizeHtml
+
+Sanitizes HTML content to prevent XSS attacks.
+
+```typescript
+function sanitizeHtml(html: string): string;
+```
+
+#### Usage
+
+```typescript
+import { sanitizeHtml } from '@jmruthers/pace-core';
+
+const sanitized = sanitizeHtml(userInput);
+```
+
+## Performance Utilities
+
+### debounce
+
+Creates a debounced function.
+
+```typescript
+function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void;
+```
+
+#### Usage
+
+```typescript
+import { debounce } from '@jmruthers/pace-core';
+
+const debouncedSearch = debounce((query: string) => {
+  performSearch(query);
+}, 300);
+```
+
+### throttle
+
+Creates a throttled function.
+
+```typescript
+function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void;
+```
+
+#### Usage
+
+```typescript
+import { throttle } from '@jmruthers/pace-core';
+
+const throttledScroll = throttle(() => {
+  updateScrollPosition();
+}, 100);
+```
+
+### memoize
+
+Creates a memoized function.
+
+```typescript
+function memoize<T extends (...args: any[]) => any>(
+  func: T,
+  keyGenerator?: (...args: Parameters<T>) => string
+): T;
+```
+
+#### Usage
+
+```typescript
+import { memoize } from '@jmruthers/pace-core';
+
+const memoizedCalculation = memoize((a: number, b: number) => {
+  return expensiveCalculation(a, b);
+});
+```
+
+## Error Handling Utilities
+
+### createError
+
+Creates a standardized error object.
+
+```typescript
+function createError(
+  message: string,
+  code?: string,
+  details?: any
+): {
+  message: string;
+  code?: string;
+  details?: any;
+  timestamp: number;
+};
+```
+
+#### Usage
+
+```typescript
+import { createError } from '@jmruthers/pace-core';
+
+const error = createError('User not found', 'USER_NOT_FOUND', { userId });
+```
+
+### isError
+
+Checks if a value is an error object.
+
+```typescript
+function isError(value: any): value is Error;
+```
+
+#### Usage
+
+```typescript
+import { isError } from '@jmruthers/pace-core';
+
+if (isError(result)) {
+  console.error(result.message);
+}
+```
+
+### handleAsyncError
+
+Wraps an async function with error handling.
+
+```typescript
+function handleAsyncError<T>(
+  asyncFn: () => Promise<T>,
+  errorHandler?: (error: Error) => void
+): Promise<T | null>;
+```
+
+#### Usage
+
+```typescript
+import { handleAsyncError } from '@jmruthers/pace-core';
+
+const result = await handleAsyncError(
+  () => fetchData(),
+  (error) => console.error('Fetch failed:', error)
+);
+```
+
+## Logging Utilities
+
+### createLogger
+
+Creates a logger instance with configurable levels.
+
+```typescript
+function createLogger(options?: {
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  prefix?: string;
+  enableConsole?: boolean;
+}): Logger;
+```
+
+#### Usage
+
+```typescript
+import { createLogger } from '@jmruthers/pace-core';
+
+const logger = createLogger({
+  level: 'info',
+  prefix: '[MyApp]',
+  enableConsole: true
+});
+
+logger.info('Application started');
+logger.error('An error occurred', error);
+```
+
+### Logger Interface
+
+```typescript
+interface Logger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+}
+```
+
+## Storage Utilities
+
+### storage
+
+Provides a unified interface for localStorage and sessionStorage.
+
+```typescript
+const storage = {
+  get<T>(key: string, defaultValue?: T): T | null;
+  set<T>(key: string, value: T): void;
+  remove(key: string): void;
+  clear(): void;
+  has(key: string): boolean;
+};
+```
+
+#### Usage
+
+```typescript
+import { storage } from '@jmruthers/pace-core';
+
+// Store data
+storage.set('user-preferences', { notifications: true });
+
+// Retrieve data
+const preferences = storage.get('user-preferences');
+
+// Check if key exists
+if (storage.has('user-preferences')) {
+  // Do something
+}
+```
+
+## Utility Composition
+
+### createUtilityComposer
+
+Creates a utility composer for combining multiple utilities.
+
+```typescript
+function createUtilityComposer<T extends Record<string, any>>(
+  utilities: T
+): T & {
+  compose: <U extends Record<string, any>>(additional: U) => T & U;
+};
+```
+
+#### Usage
+
+```typescript
+import { createUtilityComposer } from '@jmruthers/pace-core';
+
+const baseUtils = createUtilityComposer({
+  formatDate,
+  truncateText,
+  generateId,
+});
+
+const allUtils = baseUtils.compose({
+  validateEmail,
+  sanitizeHtml,
+});
+```
+
+## Export Summary
+
+All utilities are exported from the main package:
+
+```typescript
+export {
+  // Authentication
+  createSupabaseClient,
+  validateAuthSession,
+  refreshAuthToken,
+  
+  // Events
+  filterEventsByAccess,
+  sortEventsByDate,
+  groupEventsByDate,
+  calculateEventDuration,
+  
+  // RBAC
+  checkPermission,
+  hasRole,
+  canAccessResource,
+  buildPermissionString,
+  
+  // Organisations
+  validateOrganisationAccess,
+  getOrganisationSettings,
+  formatOrganisationName,
+  
+  // Forms
+  validateFormData,
+  formatFormErrors,
+  sanitizeFormData,
+  
+  // Date and Time
+  formatDate,
+  isDateInRange,
+  getDateRange,
+  
+  // Strings
+  truncateText,
+  slugify,
+  generateId,
+  
+  // Arrays
+  groupBy,
+  uniqueBy,
+  sortBy,
+  
+  // Objects
+  deepMerge,
+  pick,
+  omit,
+  
+  // Validation
+  isValidEmail,
+  isValidPhone,
+  isValidUrl,
+  
+  // Security
+  hashPassword,
+  verifyPassword,
+  generateToken,
+  sanitizeHtml,
+  
+  // Performance
+  debounce,
+  throttle,
+  memoize,
+  
+  // Error Handling
+  createError,
+  isError,
+  handleAsyncError,
+  
+  // Logging
+  createLogger,
+  
+  // Storage
+  storage,
+  
+  // Composition
+  createUtilityComposer,
+} from '@jmruthers/pace-core';
+```
+
+## Utility Best Practices
+
+### Performance Considerations
+
+- Use memoization for expensive calculations
+- Debounce user input to reduce API calls
+- Throttle scroll and resize events
+- Cache frequently accessed data
+
+### Security Guidelines
+
+- Always sanitize user input
+- Validate data before processing
+- Use secure token generation
+- Hash sensitive data
+
+### Error Handling
+
+- Always wrap async operations in try-catch
+- Provide meaningful error messages
+- Log errors for debugging
+- Gracefully handle failures
+
+### Type Safety
+
+- Use TypeScript for all utilities
+- Provide proper type definitions
+- Validate input parameters
+- Return consistent types
+
+For more information about using utilities effectively, see the [Best Practices Guide](../best-practices/utilities.md).