@owlmeans/client-config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# @owlmeans/client-config
+
+Client-side configuration management library for OwlMeans Common applications. This package extends the base `@owlmeans/config` package with client-specific configuration capabilities including web service management, primary host/port settings, and service aliases.
+
+## Installation
+
+```bash
+npm install @owlmeans/client-config
+```
+
+**Note**: This package depends on `@owlmeans/config` and extends its functionality. Make sure you have the proper OwlMeans Common ecosystem set up in your project.
+
+## Overview
+
+The `@owlmeans/client-config` package is part of the OwlMeans Common libraries ecosystem and provides client-side configuration extensions. It follows the OwlMeans package structure with types, constants, and helpers specifically designed for client-side applications.
+
+**Important Note**: This package is not intended to be used separately from the OwlMeans Common ecosystem. It extends the functionality of `@owlmeans/config` and should be used in conjunction with it. The configuration objects created by this package build upon the configuration structure provided by `@owlmeans/config`.
+
+### Key Features
+
+- **Web Service Management**: Configure and manage web services with aliases
+- **Primary Host/Port Settings**: Set primary host and port configurations
+- **Service Aliases**: Create short aliases for services
+- **Client-Side Extensions**: Extend base configuration with client-specific properties
+- **Seamless Integration**: Works seamlessly with the base `@owlmeans/config` package
+
+## Core Concepts
+
+### Client Configuration
+
+Client configurations extend the base `CommonConfig` from `@owlmeans/config` with client-specific properties that are relevant for client-side applications.
+
+### Web Service Management
+
+The package provides functionality to manage web services, supporting both single service configurations and multiple aliased services for complex client applications.
+
+### Service Aliases
+
+Service aliases allow you to create short, memorable names for services, making it easier to reference them in client-side code.
+
+## Quick Start
+
+### Basic Client Configuration
+
+```typescript
+import { BasicClientConfig, addWebService } from '@owlmeans/client-config'
+import { makeConfig } from '@owlmeans/config'
+import { AppType } from '@owlmeans/config/exports'
+
+// Create a client configuration
+const config: BasicClientConfig = makeConfig(AppType.Frontend, 'my-client', {
+  webService: 'https://api.example.com',
+  primaryHost: 'app.example.com',
+  primaryPort: 443,
+  shortAlias: 'myapp'
+})
+```
+
+### Adding Web Services
+
+```typescript
+import { addWebService } from '@owlmeans/client-config'
+
+// Add a single web service
+const configWithService = addWebService('https://api.example.com', config)
+
+// Add a web service with alias
+const configWithAlias = addWebService('https://api.example.com', 'api', config)
+
+// Add multiple services with aliases
+let multiServiceConfig = addWebService('https://api.example.com', 'api', config)
+multiServiceConfig = addWebService('https://auth.example.com', 'auth', multiServiceConfig)
+```
+
+## API Reference
+
+### Types
+
+#### `BasicClientConfig`
+
+Extends `CommonConfig` from `@owlmeans/config` with client-specific properties.
+
+```typescript
+interface BasicClientConfig extends CommonConfig {
+  webService?: string | Record<string, string>
+  primaryHost?: string
+  primaryPort?: number
+  shortAlias?: string
+}
+```
+
+**Properties:**
+
+- `webService` - Web service configuration. Can be a single service URL (string) or a record of aliased services
+- `primaryHost` - Primary host for the client application
+- `primaryPort` - Primary port for the client application
+- `shortAlias` - Short alias for the service, useful for client-side identification
+
+**Example:**
+```typescript
+const clientConfig: BasicClientConfig = {
+  // ... inherited from CommonConfig
+  webService: {
+    default: 'https://api.example.com',
+    auth: 'https://auth.example.com',
+    storage: 'https://storage.example.com'
+  },
+  primaryHost: 'app.example.com',
+  primaryPort: 443,
+  shortAlias: 'myapp'
+}
+```
+
+### Helper Functions
+
+#### `addWebService<C extends BasicClientConfig>(service: string, alias?: string | Partial<C>, cfg?: Partial<C>): C`
+
+Adds a web service to the client configuration. This function handles both single services and multiple aliased services.
+
+**Parameters:**
+- `service` - The web service URL to add
+- `alias` - Service alias (string) or partial configuration object
+- `cfg` - Optional partial configuration to extend
+
+**Returns:** Configuration with added web service
+
+**Behavior:**
+- If `alias` is not provided or is an object, sets the service as the default or single web service
+- If `alias` is a string, adds the service with the specified alias
+- Handles conversion between string and record-based web service configurations
+- Maintains existing services when adding new ones
+
+**Examples:**
+
+**Adding a single web service:**
+```typescript
+const config = addWebService('https://api.example.com')
+// Result: { webService: 'https://api.example.com' }
+```
+
+**Adding a web service with alias:**
+```typescript
+const config = addWebService('https://api.example.com', 'api')
+// Result: { webService: { default: 'https://api.example.com', api: 'https://api.example.com' } }
+```
+
+**Adding multiple services:**
+```typescript
+let config = addWebService('https://api.example.com', 'api')
+config = addWebService('https://auth.example.com', 'auth', config)
+// Result: { 
+//   webService: { 
+//     default: 'https://api.example.com', 
+//     api: 'https://api.example.com',
+//     auth: 'https://auth.example.com'
+//   } 
+// }
+```
+
+**Adding service with existing string configuration:**
+```typescript
+const baseConfig = { webService: 'https://base.example.com' }
+const config = addWebService('https://api.example.com', 'api', baseConfig)
+// Result: { 
+//   webService: { 
+//     default: 'https://base.example.com', 
+//     api: 'https://api.example.com'
+//   } 
+// }
+```
+
+**Using partial configuration object:**
+```typescript
+const config = addWebService('https://api.example.com', {
+  primaryHost: 'app.example.com',
+  shortAlias: 'myapp'
+})
+// Result: { 
+//   webService: 'https://api.example.com',
+//   primaryHost: 'app.example.com',
+//   shortAlias: 'myapp'
+// }
+```
+
+## Constants
+
+### `DEFAULT_KEY`
+
+Default key used for web service configurations when no alias is specified.
+
+```typescript
+const DEFAULT_KEY = 'default'
+```
+
+**Usage:**
+```typescript
+import { DEFAULT_KEY } from '@owlmeans/client-config'
+
+// Access default web service
+const defaultService = config.webService?.[DEFAULT_KEY]
+```
+
+## Usage Examples
+
+### Complete Client Application Configuration
+
+```typescript
+import { 
+  BasicClientConfig, 
+  addWebService, 
+  DEFAULT_KEY 
+} from '@owlmeans/client-config'
+import { makeConfig, service } from '@owlmeans/config'
+import { AppType } from '@owlmeans/config/exports'
+
+// Create base client configuration
+let config: BasicClientConfig = makeConfig(AppType.Frontend, 'web-app', {
+  debug: { enabled: true },
+  brand: { home: '/dashboard' },
+  primaryHost: 'app.example.com',
+  primaryPort: 443,
+  shortAlias: 'webapp'
+})
+
+// Add web services
+config = addWebService('https://api.example.com', 'api', config)
+config = addWebService('https://auth.example.com', 'auth', config)
+config = addWebService('https://storage.example.com', 'storage', config)
+
+// Add backend services (using base config functionality)
+config = service({
+  service: 'websocket',
+  host: 'ws.example.com',
+  port: 8080,
+  base: '/ws'
+}, config)
+
+console.log('API Service:', config.webService?.api)
+console.log('Auth Service:', config.webService?.auth)
+console.log('Default Service:', config.webService?.[DEFAULT_KEY])
+```
+
+### Dynamic Service Configuration
+
+```typescript
+import { addWebService, BasicClientConfig } from '@owlmeans/client-config'
+
+class ClientConfigManager {
+  private config: BasicClientConfig
+
+  constructor(baseConfig: BasicClientConfig) {
+    this.config = baseConfig
+  }
+
+  addService(url: string, alias: string): void {
+    this.config = addWebService(url, alias, this.config)
+  }
+
+  getService(alias: string = DEFAULT_KEY): string | undefined {
+    if (typeof this.config.webService === 'string') {
+      return alias === DEFAULT_KEY ? this.config.webService : undefined
+    }
+    return this.config.webService?.[alias]
+  }
+
+  getAllServices(): Record<string, string> {
+    if (typeof this.config.webService === 'string') {
+      return { [DEFAULT_KEY]: this.config.webService }
+    }
+    return this.config.webService || {}
+  }
+}
+
+// Usage
+const manager = new ClientConfigManager(baseConfig)
+manager.addService('https://api.example.com', 'api')
+manager.addService('https://auth.example.com', 'auth')
+
+const apiUrl = manager.getService('api')
+const allServices = manager.getAllServices()
+```
+
+### Environment-Specific Configuration
+
+```typescript
+import { addWebService, BasicClientConfig } from '@owlmeans/client-config'
+
+function createEnvironmentConfig(env: 'development' | 'staging' | 'production'): BasicClientConfig {
+  const hosts = {
+    development: 'localhost:3000',
+    staging: 'staging.example.com',
+    production: 'app.example.com'
+  }
+
+  const apiUrls = {
+    development: 'http://localhost:8000',
+    staging: 'https://staging-api.example.com',
+    production: 'https://api.example.com'
+  }
+
+  let config: BasicClientConfig = {
+    primaryHost: hosts[env],
+    primaryPort: env === 'development' ? 3000 : 443,
+    shortAlias: `app-${env}`
+  }
+
+  // Add environment-specific services
+  config = addWebService(apiUrls[env], 'api', config)
+  
+  if (env !== 'development') {
+    config = addWebService(`https://${env}-auth.example.com`, 'auth', config)
+  }
+
+  return config
+}
+
+// Usage
+const devConfig = createEnvironmentConfig('development')
+const prodConfig = createEnvironmentConfig('production')
+```
+
+## Integration with OwlMeans Ecosystem
+
+The `@owlmeans/client-config` package integrates seamlessly with other OwlMeans packages:
+
+- **@owlmeans/config**: Provides base configuration functionality that this package extends
+- **@owlmeans/context**: Supports context management for client configurations
+- **@owlmeans/client**: Works with other client-side packages in the ecosystem
+- **@owlmeans/route**: Complements routing capabilities with client configuration
+- **@owlmeans/web-client**: Provides web-specific implementations
+
+## Best Practices
+
+1. **Service Organization**: Use aliases for different types of services (api, auth, storage, etc.)
+
+2. **Environment Configuration**: Create environment-specific configurations for different deployment stages
+
+3. **Type Safety**: Always use the `BasicClientConfig` type for type-safe configuration management
+
+4. **Service Discovery**: Use meaningful aliases that reflect the service purpose
+
+5. **Configuration Validation**: Validate service URLs and configuration before use
+
+6. **Fallback Handling**: Always handle cases where services might not be configured
+
+## Migration from Base Config
+
+If you're migrating from using only `@owlmeans/config`, here's how to adopt client-config:
+
+```typescript
+// Before (base config only)
+import { makeConfig } from '@owlmeans/config'
+
+const config = makeConfig(AppType.Frontend, 'my-app', {
+  // ... base configuration
+})
+
+// After (with client-config)
+import { makeConfig } from '@owlmeans/config'
+import { addWebService, BasicClientConfig } from '@owlmeans/client-config'
+
+let config: BasicClientConfig = makeConfig(AppType.Frontend, 'my-app', {
+  // ... base configuration
+  primaryHost: 'app.example.com',
+  shortAlias: 'myapp'
+})
+
+config = addWebService('https://api.example.com', 'api', config)
+```
+
+## License
+
+This package is part of the OwlMeans Common libraries and follows the project's licensing terms.

package/build/consts.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_KEY = "default";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,YAAY,CAAA"}

package/build/consts.js

@@ -0,0 +1,2 @@
+export const DEFAULT_KEY = 'default';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1,3 @@
+import type { BasicClientConfig } from './types.js';
+export declare const addWebService: <C extends BasicClientConfig>(service: string, alias?: string | Partial<C>, cfg?: Partial<C>) => C;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGnD,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,iBAAiB,WAAW,MAAM,UAAU,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,CAAC,KAAG,CAoB3H,CAAA"}

package/build/helper.js

@@ -0,0 +1,25 @@
+import { DEFAULT_KEY } from './consts.js';
+export const addWebService = (service, alias, cfg) => {
+    const _cfg = (cfg ?? (typeof alias === 'object' ? alias : undefined) ?? {});
+    if (alias == null || typeof alias === 'object') {
+        if (typeof _cfg.webService === 'string' || _cfg.webService == null) {
+            _cfg.webService = service;
+        }
+        else {
+            _cfg.webService[DEFAULT_KEY] = service;
+        }
+    }
+    else {
+        if (_cfg.webService == null) {
+            _cfg.webService = { [DEFAULT_KEY]: service, [alias]: service };
+        }
+        else if (typeof _cfg.webService === 'string') {
+            _cfg.webService = { [DEFAULT_KEY]: _cfg.webService, [alias]: service };
+        }
+        else {
+            _cfg.webService[alias] = service;
+        }
+    }
+    return _cfg;
+};
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,CAAC,MAAM,aAAa,GAAG,CAA8B,OAAe,EAAE,KAA2B,EAAE,GAAgB,EAAK,EAAE;IAC9H,MAAM,IAAI,GAAM,CAAC,GAAG,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAE,IAAI,EAAE,CAAM,CAAA;IAEpF,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,IAAI,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;YACnE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAA;QAC3B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,OAAO,CAAA;QACxC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;QAChE,CAAC;aAAM,IAAI,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YAC/C,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;QACxE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,OAAO,CAAA;QAClC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './helper.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './consts.js';
+export * from './helper.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,8 @@
+import type { CommonConfig } from '@owlmeans/config';
+export interface BasicClientConfig extends CommonConfig {
+    webService?: string | Record<string, string>;
+    primaryHost?: string;
+    primaryPort?: number;
+    shortAlias?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@owlmeans/client-config",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 72 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/config": "^0.1.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.7",
+    "typescript": "^5.6.3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,2 @@
+
+export const DEFAULT_KEY = 'default'

package/src/helper.ts

@@ -0,0 +1,24 @@
+import type { BasicClientConfig } from './types.js'
+import { DEFAULT_KEY } from './consts.js'
+
+export const addWebService = <C extends BasicClientConfig>(service: string, alias?: string | Partial<C>, cfg?: Partial<C>): C => {
+  const _cfg: C = (cfg ?? (typeof alias === 'object' ? alias : undefined ) ?? {}) as C
+
+  if (alias == null || typeof alias === 'object') {
+    if (typeof _cfg.webService === 'string' || _cfg.webService == null) {
+      _cfg.webService = service
+    } else {
+      _cfg.webService[DEFAULT_KEY] = service
+    }
+  } else {
+    if (_cfg.webService == null) {
+      _cfg.webService = { [DEFAULT_KEY]: service, [alias]: service }
+    } else if (typeof _cfg.webService === 'string') {
+      _cfg.webService = { [DEFAULT_KEY]: _cfg.webService, [alias]: service }
+    } else {
+      _cfg.webService[alias] = service
+    }
+  }
+
+  return _cfg
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+
+export type * from './types.js'
+export * from './consts.js'
+export * from './helper.js'

package/src/types.ts

@@ -0,0 +1,8 @@
+import type { CommonConfig } from '@owlmeans/config'
+
+export interface BasicClientConfig extends CommonConfig {
+  webService?: string | Record<string, string>
+  primaryHost?: string
+  primaryPort?: number
+  shortAlias?: string
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": [
+    "../tsconfig.default.json",
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/consts.ts","./src/helper.ts","./src/index.ts","./src/types.ts"],"version":"5.6.3"}