@owlmeans/client-context 0.1.2 → 0.1.3

package/README.md

@@ -1,471 +1,50 @@
 # @owlmeans/client-context
 
-Client-side context management for OwlMeans Common applications. This package extends the basic context system with client-specific functionality including service routing, API client integration, and configuration management designed for frontend applications.
+Client-side context factory extending `BasicContext` with API client and service routing.
 
 ## Overview
 
-The `@owlmeans/client-context` package provides client-side context management for the OwlMeans ecosystem, offering:
-
-- **Client Context Factory**: Creates contexts specifically configured for frontend applications
-- **Service Route Management**: Manages service routes and API endpoints for client-server communication
-- **API Client Integration**: Automatic integration with the OwlMeans API client system
-- **Configuration Management**: Client-specific configuration with service definitions and i18n support
-- **Frontend Context Utilities**: Helper functions for managing client application contexts
-
-This package follows the OwlMeans "quadra" pattern as a client-side implementation extending the basic `@owlmeans/context` package.
+- `makeClientContext(cfg)` creates a client context with HTTP API client pre-configured
+- Adds `ClientContext` capabilities: service URL resolution, API route calls
+- Base for higher-level context factories (`@owlmeans/web-client`'s `makeContext`)
+- Usually not used directly — use `makeContext` from your platform-specific package
 
 ## Installation
 
 ```bash
-npm install @owlmeans/client-context
+bun add @owlmeans/client-context
 ```
 
-## Dependencies
-
-This package requires and integrates with:
-- `@owlmeans/context`: Base context management system
-- `@owlmeans/client-config`: Client configuration management
-- `@owlmeans/api`: API client integration
-- `@owlmeans/route`: Service route definitions
-- `@owlmeans/i18n`: Internationalization support
-
-## Core Concepts
-
-### Client Context
-
-A client context is a specialized application context that manages client-side dependencies, service routes, and API communication. It extends the basic context with client-specific functionality.
-
-### Service Routes
-
-Service routes define how the client communicates with backend services, including endpoint definitions, authentication requirements, and communication protocols.
-
-### Configuration Management
-
-Client contexts handle configuration specific to frontend applications, including service definitions, internationalization settings, and client-specific parameters.
-
-## API Reference
-
-### Types
-
-#### `ClientConfig`
-Configuration interface for client contexts extending BasicClientConfig.
-
-```typescript
-interface ClientConfig extends BasicClientConfig {
-  services: Record<string, CommonServiceRoute>  // Service route definitions
-  i18n?: I18nConfig                            // Internationalization configuration
-}
-```
+## Usage
 
-#### `ClientContext<C>`
-Main client context interface extending BasicContext with client-specific functionality.
+Typically called through a higher-level factory:
 
 ```typescript
-interface ClientContext<C extends ClientConfig = ClientConfig> extends BasicContext<C>, ConfigResourceAppend {
-  serviceRoute: (alias: string, makeDefault?: boolean) => CommonServiceRoute
-}
+// Via @owlmeans/web-client
+import { makeContext } from '@owlmeans/web-client'
+const context = makeContext(appConfig)
 ```
 
-**Methods:**
-- **`serviceRoute(alias: string, makeDefault?: boolean): CommonServiceRoute`**: Retrieves service route by alias and optionally sets as default
-
-### Factory Functions
-
-#### `makeClientContext<C, T>(cfg: C): T`
-
-Creates a client context instance with automatic API client integration.
+Direct usage:
 
-**Parameters:**
-- `cfg`: Client configuration object
-
-**Returns:** ClientContext instance
-
-**Features:**
-- Automatically integrates API client
-- Sets up service route management
-- Configures context for frontend operation
-
-**Example:**
 ```typescript
-import { makeClientContext, config } from '@owlmeans/client-context'
-
-// Create client configuration
-const clientConfig = config('my-app', {
-  services: {
-    'user-service': {
-      alias: 'user-service',
-      route: {
-        alias: 'users',
-        path: '/api/users',
-        service: 'user-service'
-      }
-    }
-  }
-})
-
-// Create client context
+import { makeClientContext } from '@owlmeans/client-context'
 const context = makeClientContext(clientConfig)
-
-await context.configure().init()
-
-// Access service route
-const userService = context.serviceRoute('user-service')
-```
-
-#### `config<C>(service: string, cfg?: Partial<C>): C`
-
-Creates a client configuration with default frontend settings.
-
-**Parameters:**
-- `service`: Service name identifier
-- `cfg` (optional): Additional configuration options
-
-**Returns:** ClientConfig object configured for frontend
-
-**Example:**
-```typescript
-import { config } from '@owlmeans/client-context'
-
-const clientConfig = config('frontend-app', {
-  layer: Layer.Service,
-  services: {
-    'api': {
-      alias: 'api',
-      route: {
-        alias: 'api',
-        path: '/api',
-        service: 'backend'
-      }
-    }
-  },
-  i18n: {
-    defaultLng: 'en',
-    defaultNs: 'translation'
-  }
-})
-```
-
-### Service Route Management
-
-#### `serviceRoute(alias: string, makeDefault?: boolean): CommonServiceRoute`
-
-Retrieves and manages service routes for API communication.
-
-**Parameters:**
-- `alias`: Service route alias
-- `makeDefault` (optional): Whether to mark this route as default
-
-**Returns:** CommonServiceRoute object
-
-**Throws:** `SyntaxError` if service route not found
-
-**Example:**
-```typescript
-// Get service route
-const apiRoute = context.serviceRoute('api')
-
-// Set as default service
-const defaultRoute = context.serviceRoute('main-api', true)
-
-// Use route for API calls
-const apiClient = context.service('api-client')
-await apiClient.call(apiRoute, 'users', { method: 'GET' })
 ```
 
-### Constants
+## API
 
-#### `PLUGINS`
-Constant for plugin configuration.
+### `makeClientContext<C, T>(cfg): T`
 
-```typescript
-const PLUGINS = 'plugins'
-```
-
-## Usage Examples
-
-### Basic Client Context Setup
+Creates a client context configured for API calls.
 
-```typescript
-import { makeClientContext, config } from '@owlmeans/client-context'
-import { Layer } from '@owlmeans/context'
-
-// Create configuration with service routes
-const clientConfig = config('web-app', {
-  layer: Layer.User,
-  services: {
-    'auth-service': {
-      alias: 'auth',
-      route: {
-        alias: 'auth',
-        path: '/api/auth',
-        service: 'auth-backend'
-      }
-    },
-    'user-service': {
-      alias: 'users',
-      route: {
-        alias: 'users',
-        path: '/api/users',
-        service: 'user-backend'
-      }
-    }
-  }
-})
-
-// Create and initialize context
-const context = makeClientContext(clientConfig)
-await context.configure().init()
+### `ClientContext<C>`
 
-// Access services and routes
-const authRoute = context.serviceRoute('auth-service')
-const userRoute = context.serviceRoute('user-service')
-```
-
-### API Integration
-
-```typescript
-// Context automatically includes API client
-const apiClient = context.service('api-client')
-
-// Use service routes for API calls
-const authRoute = context.serviceRoute('auth-service')
-const response = await apiClient.call(authRoute, 'login', {
-  method: 'POST',
-  body: { username: 'user', password: 'pass' }
-})
-
-// Handle different services
-const userRoute = context.serviceRoute('user-service', true) // Set as default
-const users = await apiClient.call(userRoute, 'list', { method: 'GET' })
-```
-
-### Internationalization Integration
-
-```typescript
-const clientConfig = config('i18n-app', {
-  services: { /* service definitions */ },
-  i18n: {
-    defaultLng: 'en',
-    defaultNs: 'app',
-    resources: {
-      en: {
-        app: {
-          title: 'My Application',
-          welcome: 'Welcome to our app'
-        }
-      }
-    }
-  }
-})
-
-const context = makeClientContext(clientConfig)
-await context.configure().init()
-
-// i18n is automatically configured and available
-```
-
-### Multi-Service Configuration
-
-```typescript
-const multiServiceConfig = config('complex-app', {
-  services: {
-    'auth': {
-      alias: 'auth',
-      route: {
-        alias: 'auth',
-        path: '/api/auth',
-        service: 'auth-service'
-      }
-    },
-    'users': {
-      alias: 'users', 
-      route: {
-        alias: 'users',
-        path: '/api/users',
-        service: 'user-service'
-      }
-    },
-    'orders': {
-      alias: 'orders',
-      route: {
-        alias: 'orders',
-        path: '/api/orders',
-        service: 'order-service'  
-      }
-    }
-  }
-})
-
-const context = makeClientContext(multiServiceConfig)
-await context.configure().init()
-
-// Access different service routes
-const authRoute = context.serviceRoute('auth')
-const userRoute = context.serviceRoute('users')
-const orderRoute = context.serviceRoute('orders')
-
-// Use with API client
-const apiClient = context.service('api-client')
-await apiClient.call(authRoute, 'me')
-await apiClient.call(userRoute, 'profile')
-await apiClient.call(orderRoute, 'recent')
-```
-
-### Context with Resource Configuration
-
-```typescript
-import { config } from '@owlmeans/client-context'
-
-const resourceConfig = config('resource-app', {
-  services: {
-    'storage': {
-      alias: 'storage',
-      route: {
-        alias: 'storage',
-        path: '/api/storage',
-        service: 'storage-service'
-      }
-    }
-  },
-  // Additional resource configuration
-  resources: [{
-    alias: 'local-storage',
-    type: 'storage',
-    config: {
-      provider: 'localStorage'
-    }
-  }]
-})
-
-const context = makeClientContext(resourceConfig)
-await context.configure().init()
-
-// Access both service routes and resources
-const storageRoute = context.serviceRoute('storage')
-const localStorage = context.resource('local-storage')
-```
-
-### Service Route Error Handling
-
-```typescript
-try {
-  const route = context.serviceRoute('non-existent-service')
-} catch (error) {
-  if (error instanceof SyntaxError && error.message.includes('Service not found')) {
-    console.error('Service route not configured')
-    // Handle missing service configuration
-  }
-}
-
-// Safe service route access
-const hasUserService = 'user-service' in context.cfg.services
-if (hasUserService) {
-  const userRoute = context.serviceRoute('user-service')
-  // Use the route safely
-}
-```
-
-### Default Service Management
-
-```typescript
-// Set a service as default
-const primaryApi = context.serviceRoute('primary-api', true)
-
-// The service is now marked as default
-console.log(primaryApi.default) // true
-
-// Other services remain non-default unless explicitly set
-const secondaryApi = context.serviceRoute('secondary-api')
-console.log(secondaryApi.default) // false or undefined
-```
-
-## Configuration
-
-Client configuration supports various options for frontend applications:
-
-```typescript
-interface ClientConfig extends BasicClientConfig {
-  // Service route definitions
-  services: Record<string, CommonServiceRoute>
-  
-  // Internationalization settings
-  i18n?: {
-    defaultLng?: string
-    defaultNs?: string
-    resources?: Record<string, Record<string, any>>
-  }
-  
-  // Additional client-specific configuration
-  // (inherited from BasicClientConfig)
-}
-```
-
-### Service Route Configuration
-
-```typescript
-interface CommonServiceRoute {
-  alias: string                    // Service route alias
-  route: {
-    alias: string                  // Route alias
-    path: string                   // API endpoint path
-    service: string                // Backend service identifier
-    method?: string                // HTTP method
-    // Additional route configuration
-  }
-  default?: boolean                // Whether this is the default service
-}
-```
-
-## Error Handling
-
-The package provides descriptive error messages:
-
-- **Service not found**: Thrown when accessing non-configured service routes
-- **Configuration errors**: Thrown during context initialization with invalid config
-
-```typescript
-try {
-  const context = makeClientContext(invalidConfig)
-  await context.configure().init()
-} catch (error) {
-  console.error('Context initialization failed:', error)
-}
-```
-
-## Integration with OwlMeans Ecosystem
-
-This package integrates with:
-
-- **@owlmeans/context**: Base context management system
-- **@owlmeans/api**: API client for service communication  
-- **@owlmeans/client-config**: Client configuration management
-- **@owlmeans/route**: Service route definitions
-- **@owlmeans/i18n**: Internationalization support
-
-## Best Practices
-
-1. **Define all service routes** in configuration for proper API communication
-2. **Use meaningful service aliases** for easy identification
-3. **Configure i18n settings** for internationalized applications
-4. **Handle service route errors** gracefully with try-catch blocks
-5. **Set default services** appropriately for primary API endpoints
+Extends `BasicContext<C>` with:
+- Service URL resolution for configured service routes
 
 ## Related Packages
 
-- **@owlmeans/server-context**: Server-side context management
-- **@owlmeans/context**: Base context system
-- **@owlmeans/api**: API client integration
-- **@owlmeans/client-config**: Client configuration
-- **@owlmeans/route**: Route management
-
-## Utilities
-
-The package also provides utility functions in the `/utils` subpackage for advanced context management and configuration operations.
-
-```typescript
-import { /* utility functions */ } from '@owlmeans/client-context/utils'
-```
-
-## TypeScript Support
-
-The package is written in TypeScript and provides comprehensive type definitions for all client context operations, ensuring type safety for service routes, configuration, and API integration.
+- [`@owlmeans/context`](../context) — `BasicContext` base
+- [`@owlmeans/web-client`](../web-client) — wraps this with React Router integration
+- [`@owlmeans/client-config`](../client-config) — `addWebService` for service URL config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-context",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -28,16 +28,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/api": "^0.1.2",
-    "@owlmeans/client-config": "^0.1.2",
-    "@owlmeans/config": "^0.1.2",
-    "@owlmeans/context": "^0.1.2",
-    "@owlmeans/i18n": "^0.1.2",
-    "@owlmeans/route": "^0.1.2"
+    "@owlmeans/api": "^0.1.3",
+    "@owlmeans/client-config": "^0.1.3",
+    "@owlmeans/config": "^0.1.3",
+    "@owlmeans/context": "^0.1.3",
+    "@owlmeans/i18n": "^0.1.3",
+    "@owlmeans/route": "^0.1.3"
   },
   "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
     "nodemon": "^3.1.11",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.2"
   },
   "publishConfig": {
     "access": "public"

package/tsconfig.json

@@ -1,16 +1,11 @@
 {
   "extends": [
-    "../tsconfig.default.json",
-    "../tsconfig.react.json",
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.react.json"
   ],
   "compilerOptions": {
-    "rootDir": "./src/", /* Specify the root folder within your source files. */
-    "outDir": "./build/", /* Specify an output folder for all emitted files. */
-    "moduleResolution": "Bundler"
+    "rootDir": "./src/",
+    "outDir": "./build/"
   },
-  "exclude": [
-    "./dist/**/*",
-    "./build/**/*",
-    "./*.ts"
-  ]
-}
+  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+}