@jmruthers/pace-core 0.5.74 → 0.5.75

package/docs/architecture/services.md

@@ -82,11 +82,11 @@ export abstract class BaseService {
 ### Basic Setup
 
 ```tsx
-import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+import { UnifiedAuthProvider, useUnifiedAuth } from '@jmruthers/pace-core';
 
 function App() {
   return (
-    <NewUnifiedAuthProvider
+    <UnifiedAuthProvider
       supabaseClient={supabase}
       appName="MY_APP"
       idleTimeoutMs={30 * 60 * 1000} // 30 minutes
@@ -94,7 +94,7 @@ function App() {
       onIdleLogout={() => window.location.href = '/login'}
     >
       <YourAppContent />
-    </NewUnifiedAuthProvider>
+    </UnifiedAuthProvider>
   );
 }
 ```
@@ -102,10 +102,10 @@ function App() {
 ### Using Services in Components
 
 ```tsx
-import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
 
 function MyComponent() {
-  const auth = useNewUnifiedAuth();
+  const auth = useUnifiedAuth();
   
   return (
     <div>
@@ -121,24 +121,26 @@ function MyComponent() {
 ### Using Individual Service Hooks
 
 ```tsx
-import { useAuth } from '@core/hooks/services/useAuth';
-import { usePermissions } from '@core/hooks/services/usePermissions';
-import { useCurrentOrganisation } from '@core/hooks/services/useCurrentOrganisation';
-import { useCurrentEvent } from '@core/hooks/services/useCurrentEvent';
+import { 
+  useAuthService,
+  useOrganisationService,
+  useEventService,
+  useRBACService 
+} from '@jmruthers/pace-core';
 
 function MyComponent() {
-  const auth = useAuth();
-  const permissions = usePermissions();
-  const organisation = useCurrentOrganisation();
-  const events = useCurrentEvent();
+  const authService = useAuthService();
+  const orgService = useOrganisationService();
+  const eventService = useEventService();
+  const rbacService = useRBACService();
   
   return (
     <div>
-      {auth.isAuthenticated && (
+      {authService.isAuthenticated() && (
         <div>
-          <h1>{organisation.selectedOrganisation?.display_name}</h1>
-          {permissions.hasPermission('events:read') && (
-            <EventList events={events.events} />
+          <h1>{orgService.getSelectedOrganisation()?.display_name}</h1>
+          {rbacService.hasPermission('events:read') && (
+            <EventList events={eventService.getEvents()} />
           )}
         </div>
       )}
@@ -238,17 +240,13 @@ describe('AuthServiceProvider Integration', () => {
 
 ### From Old Architecture
 
-The new architecture provides backward compatibility through the `NewUnifiedAuthProvider` which maintains the same API as the old `UnifiedAuthProvider`:
+The architecture is backward compatible. The `UnifiedAuthProvider` now uses the service-based architecture internally:
 
 ```tsx
-// Old way
-import { UnifiedAuthProvider } from '@core/providers';
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
 
-// New way
-import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
-
-// Same API, better architecture
-<NewUnifiedAuthProvider
+// Same API, service-based architecture internally
+<UnifiedAuthProvider
   supabaseClient={supabase}
   appName="MY_APP"
   idleTimeoutMs={30 * 60 * 1000}
@@ -256,17 +254,17 @@ import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthP
   onIdleLogout={() => window.location.href = '/login'}
 >
   <YourAppContent />
-</NewUnifiedAuthProvider>
+</UnifiedAuthProvider>
 ```
 
-### Gradual Migration
+### How It Works
 
-You can migrate gradually by:
+All providers use the service-based architecture:
 
-1. **Start with new apps**: Use `NewUnifiedAuthProvider` for new applications
-2. **Migrate existing apps**: Replace `UnifiedAuthProvider` with `NewUnifiedAuthProvider`
-3. **Use individual services**: Gradually move to individual service hooks for better performance
-4. **Remove old providers**: Once migration is complete, remove old provider imports
+1. **UnifiedAuthProvider**: Uses service architecture internally
+2. **Individual Services**: Available for advanced usage via hooks
+3. **Backward Compatible**: Existing code works without changes
+4. **Performance**: All providers instantiate services once and reuse them
 
 ## File Structure
 

package/docs/breaking-changes.md

@@ -87,14 +87,11 @@ The library now uses a service-based architecture with pure TypeScript service c
 
 #### Migration
 
-Migration is optional. Existing code continues to work. To adopt new architecture:
+The service architecture is now the default. Existing code continues to work without changes:
 
 ```tsx
-// Old way (still works)
+// Works out of the box - uses service architecture internally
 import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-// New way (optional)
-import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
 ```
 
 See [Service Architecture Guide](./architecture/services.md) for details.

package/docs/migration/service-architecture.md

@@ -1,257 +1,151 @@
-# Migration Guide: Service Architecture
+# Provider Architecture: Service-Based Design
 
 ## Overview
 
-This guide helps you migrate from the old provider architecture to the new service-based architecture. The new architecture provides better testability, maintainability, and follows SOLID principles.
+pace-core now uses a **service-based architecture** for all providers. This provides better testability, maintainability, and follows SOLID principles by separating business logic (services) from React context (providers).
 
-## Quick Start
-
-### 1. Update Provider Import
-
-Replace the old provider with the new one:
-
-```tsx
-// Old way
-import { UnifiedAuthProvider } from '@core/providers';
-
-// New way
-import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
-```
-
-### 2. Update Provider Usage
+## Architecture Benefits
 
-The new provider has the same API but requires additional configuration:
+- **Separation of Concerns**: Business logic in pure TypeScript services
+- **Better Testability**: Services can be tested without React
+- **Improved Performance**: Services instantiated once and reused
+- **Type Safety**: Full TypeScript support with clear interfaces
 
-```tsx
-// Old way
-<UnifiedAuthProvider supabaseClient={supabase} appName="MY_APP">
-  <YourAppContent />
-</UnifiedAuthProvider>
-
-// New way
-<NewUnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="MY_APP"
-  idleTimeoutMs={30 * 60 * 1000} // 30 minutes
-  warnBeforeMs={60 * 1000} // 60 seconds
-  onIdleLogout={() => {
-    // Handle idle logout - redirect to login
-    window.location.href = '/login';
-  }}
->
-  <YourAppContent />
-</NewUnifiedAuthProvider>
-```
-
-### 3. Update Hook Imports
-
-Replace the old hook with the new one:
-
-```tsx
-// Old way
-import { useUnifiedAuth } from '@core/providers';
-
-// New way
-import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
-```
-
-## Detailed Migration Steps
-
-### Step 1: Update Main App Setup
+## Quick Start
 
-Update your main app file (usually `main.tsx` or `App.tsx`):
+### Basic Usage
 
 ```tsx
-// Before
-import { UnifiedAuthProvider, OrganisationProvider, EventProvider } from '@core/providers';
+import { UnifiedAuthProvider, useUnifiedAuth } from '@jmruthers/pace-core';
 
 function App() {
   return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="MY_APP">
-      <OrganisationProvider>
-        <EventProvider>
-          <YourAppContent />
-        </EventProvider>
-      </OrganisationProvider>
-    </UnifiedAuthProvider>
-  );
-}
-
-// After
-import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
-
-function App() {
-  return (
-    <NewUnifiedAuthProvider
+    <UnifiedAuthProvider
       supabaseClient={supabase}
       appName="MY_APP"
-      idleTimeoutMs={30 * 60 * 1000}
-      warnBeforeMs={60 * 1000}
-      onIdleLogout={() => window.location.href = '/login'}
+      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+      warnBeforeMs={60 * 1000} // 60 seconds
+      onIdleLogout={() => {
+        // Handle idle logout - redirect to login
+        window.location.href = '/login';
+      }}
     >
       <YourAppContent />
-    </NewUnifiedAuthProvider>
+    </UnifiedAuthProvider>
   );
 }
 ```
 
-### Step 2: Update Component Hooks
-
-Update components that use the old hooks:
+### Using Hooks
 
 ```tsx
-// Before
-import { useUnifiedAuth } from '@core/providers';
+import { useUnifiedAuth, useEvents, useOrganisations } from '@jmruthers/pace-core';
 
 function MyComponent() {
   const { user, isAuthenticated, signOut } = useUnifiedAuth();
-  // ... component logic
-}
-
-// After
-import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
-
-function MyComponent() {
-  const { user, isAuthenticated, signOut } = useNewUnifiedAuth();
-  // ... component logic (same API)
+  const { events, selectedEvent, setSelectedEvent } = useEvents();
+  const { selectedOrganisation, organisations } = useOrganisations();
+  
+  // Use the hooks as needed
 }
 ```
 
-### Step 3: Update Individual Provider Usage
-
-If you were using individual providers, you can now use individual service hooks:
-
-```tsx
-// Before
-import { useAuth } from '@core/providers';
-import { useOrganisations } from '@core/providers';
-import { useEvents } from '@core/providers';
+## Service Architecture Overview
 
-function MyComponent() {
-  const auth = useAuth();
-  const orgs = useOrganisations();
-  const events = useEvents();
-  // ... component logic
-}
+### How It Works
 
-// After - Option 1: Use unified hook (same API)
-import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+1. **Services** (`src/services/`) - Pure TypeScript classes containing business logic
+2. **Service Providers** (`src/providers/services/`) - React context providers that create service instances
+3. **Hooks** - Convenience hooks that access services from context
 
-function MyComponent() {
-  const auth = useNewUnifiedAuth();
-  // ... component logic (same API)
-}
+### Service Layer
 
-// After - Option 2: Use individual service hooks (better performance)
-import { useAuth } from '@core/hooks/services/useAuth';
-import { useCurrentOrganisation } from '@core/hooks/services/useCurrentOrganisation';
-import { useCurrentEvent } from '@core/hooks/services/useCurrentEvent';
+Each service is a pure TypeScript class:
 
-function MyComponent() {
-  const auth = useAuth();
-  const orgs = useCurrentOrganisation();
-  const events = useCurrentEvent();
-  // ... component logic
+```typescript
+class AuthService extends BaseService {
+  signIn(email: string, password: string): Promise<AuthResult> { /* ... */ }
+  signOut(): Promise<AuthResult> { /* ... */ }
+  // ... other methods
 }
 ```
 
-## API Changes
+### Provider Layer
 
-### New Required Props
-
-The new provider requires additional props for inactivity management:
+Service providers create and manage service instances:
 
 ```tsx
-interface NewUnifiedAuthProviderProps {
-  // ... existing props
-  idleTimeoutMs: number; // REQUIRED: Inactivity timeout in milliseconds
-  warnBeforeMs: number; // REQUIRED: Warning time before logout in milliseconds
-  onIdleLogout: (reason: 'inactivity') => void; // REQUIRED: App handles redirect/navigation
+function AuthServiceProvider({ children, supabaseClient }) {
+  const authService = useMemo(() => new AuthService(supabaseClient), [supabaseClient]);
+  // Initialize and manage service lifecycle
+  return <AuthServiceContext.Provider value={{ authService }}>{children}</AuthServiceContext.Provider>;
 }
 ```
 
-### Backward Compatibility
+### Hook Layer
 
-The new provider maintains the same API as the old one, so existing components should work without changes:
+Convenience hooks provide easy access to services:
 
 ```tsx
-// This still works exactly the same
-const { user, isAuthenticated, signOut, hasRole, hasPermission } = useNewUnifiedAuth();
+function useAuth() {
+  const context = useContext(AuthServiceContext);
+  return context.authService;
+}
 ```
 
-## Performance Optimizations
+## Available Hooks
 
-### Use Individual Service Hooks
-
-For better performance, use individual service hooks instead of the unified hook:
+### Unified Hook (Recommended for Most Use Cases)
 
 ```tsx
-// Less efficient - re-renders on any state change
-const auth = useNewUnifiedAuth();
-
-// More efficient - only re-renders when auth state changes
-const auth = useAuth();
-const permissions = usePermissions();
-const organisation = useCurrentOrganisation();
-const events = useCurrentEvent();
-```
+import { useUnifiedAuth } from '@jmruthers/pace-core';
 
-### Service Subscription
-
-Services use an observable pattern for efficient updates:
-
-```tsx
-// Services automatically notify subscribers of state changes
-// No need to manually manage subscriptions
-const auth = useAuth(); // Automatically subscribes to auth service changes
+function MyComponent() {
+  const { 
+    user, 
+    isAuthenticated, 
+    signOut,
+    selectedOrganisation,
+    events,
+    selectedEvent,
+    permissions,
+    hasRole,
+    hasPermission
+  } = useUnifiedAuth();
+  
+  // Access all features from one hook
+}
 ```
 
-## Testing Updates
-
-### Update Test Imports
+### Individual Hooks (For Performance)
 
-Update your test files to use the new providers:
+For better performance, use individual hooks:
 
 ```tsx
-// Before
-import { UnifiedAuthProvider } from '@core/providers';
+import { 
+  useEvents, 
+  useOrganisations, 
+  useAuthService,
+  useRBACService 
+} from '@jmruthers/pace-core';
 
-// After
-import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+function MyComponent() {
+  const events = useEvents();
+  const orgs = useOrganisations();
+  const auth = useAuthService();
+  const rbac = useRBACService();
+  
+  // Only re-renders when relevant service state changes
+}
 ```
 
-### Update Test Setup
-
-Update your test setup to use the new provider:
-
-```tsx
-// Before
-render(
-  <UnifiedAuthProvider supabaseClient={mockSupabase} appName="TEST_APP">
-    <TestComponent />
-  </UnifiedAuthProvider>
-);
-
-// After
-render(
-  <NewUnifiedAuthProvider
-    supabaseClient={mockSupabase}
-    appName="TEST_APP"
-    idleTimeoutMs={30000}
-    warnBeforeMs={5000}
-    onIdleLogout={() => {}}
-  >
-    <TestComponent />
-  </NewUnifiedAuthProvider>
-);
-```
+## Testing
 
-### Service Testing
+### Testing Services
 
-You can now test services directly:
+Services are pure TypeScript classes, making them easy to unit test:
 
-```tsx
-// Test services in isolation
+```typescript
 describe('AuthService', () => {
   let authService: AuthService;
   
@@ -266,86 +160,53 @@ describe('AuthService', () => {
 });
 ```
 
-## Common Issues and Solutions
-
-### Issue 1: Missing Required Props
-
-**Error**: `Missing required prop: idleTimeoutMs`
+### Testing Providers
 
-**Solution**: Add the required inactivity management props:
+Providers can be tested with React Testing Library:
 
-```tsx
-<NewUnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="MY_APP"
-  idleTimeoutMs={30 * 60 * 1000} // Add this
-  warnBeforeMs={60 * 1000} // Add this
-  onIdleLogout={() => window.location.href = '/login'} // Add this
->
-  <YourAppContent />
-</NewUnifiedAuthProvider>
+```typescript
+render(
+  <UnifiedAuthProvider
+    supabaseClient={mockSupabase}
+    appName="TEST_APP"
+    idleTimeoutMs={30000}
+    warnBeforeMs={5000}
+    onIdleLogout={() => {}}
+  >
+    <TestComponent />
+  </UnifiedAuthProvider>
+);
 ```
 
-### Issue 2: Hook Not Found
-
-**Error**: `useUnifiedAuth must be used within a UnifiedAuthProvider`
-
-**Solution**: Update the hook import:
-
-```tsx
-// Change this
-import { useUnifiedAuth } from '@core/providers';
-
-// To this
-import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
-```
+## Common Issues
 
-### Issue 3: Provider Not Found
+### Missing Required Props
 
-**Error**: `useNewUnifiedAuth must be used within a NewUnifiedAuthProvider`
+**Error**: `Missing required prop: idleTimeoutMs`
 
-**Solution**: Ensure the component is wrapped in the new provider:
+Add the required inactivity management props:
 
 ```tsx
-// Make sure your app is wrapped in NewUnifiedAuthProvider
-<NewUnifiedAuthProvider {...props}>
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="MY_APP"
+  idleTimeoutMs={30 * 60 * 1000}
+  warnBeforeMs={60 * 1000}
+  onIdleLogout={() => window.location.href = '/login'}
+>
   <YourAppContent />
-</NewUnifiedAuthProvider>
+</UnifiedAuthProvider>
 ```
 
-## Migration Checklist
-
-- [ ] Update provider import from `UnifiedAuthProvider` to `NewUnifiedAuthProvider`
-- [ ] Add required inactivity management props (`idleTimeoutMs`, `warnBeforeMs`, `onIdleLogout`)
-- [ ] Update hook import from `useUnifiedAuth` to `useNewUnifiedAuth`
-- [ ] Update test imports and setup
-- [ ] Test the application to ensure everything works
-- [ ] Consider using individual service hooks for better performance
-- [ ] Remove old provider imports once migration is complete
-
-## Rollback Plan
-
-If you need to rollback:
-
-1. **Revert imports**: Change back to old provider imports
-2. **Revert provider usage**: Remove the new required props
-3. **Revert hook usage**: Change back to old hook imports
-4. **Test**: Ensure the application works with the old architecture
-
-## Support
-
-If you encounter issues during migration:
-
-1. **Check the documentation**: Review the service architecture documentation
-2. **Check the examples**: Look at the updated example app
-3. **Check the tests**: Review the test files for usage examples
-4. **Open an issue**: Report bugs or ask questions
+## Performance Tips
 
-## Next Steps
+1. **Use individual hooks** when you only need specific data
+2. **Avoid unnecessary re-renders** by selecting only what you need
+3. **Memoize expensive computations** in components
+4. **Test services in isolation** for better unit tests
 
-After migration:
+## Additional Resources
 
-1. **Explore individual services**: Consider using individual service hooks for better performance
-2. **Write service tests**: Add unit tests for your custom services
-3. **Optimize performance**: Use individual hooks instead of the unified hook where appropriate
-4. **Contribute**: Help improve the service architecture
+- [API Reference](../../api-reference/providers.md)
+- [Architecture Documentation](../../architecture/services.md)
+- [Example Apps](../../getting-started/examples/)