; }; ``` ## Vue Integration ```vue ``` ## Features The Monaco integration provides: * **Syntax Highlighting** - Color coding for JEXL expressions * **IntelliSense** - Auto-completion for all 80+ functions * **Hover Documentation** - Function descriptions on hover * **Error Detection** - Real-time syntax validation * **Code Folding** - Collapse arrays and objects ## Configuration Options ```typescript const editor = Monaco.createJexlEditor(monaco, container, { value: '', // Initial expression height: 400, // Editor height theme: 'vs-dark', // vs, vs-dark, or vs-light fontSize: 14, // Font size minimap: { enabled: false }, // Show/hide minimap lineNumbers: 'on', // Show line numbers wordWrap: 'on', // Enable word wrapping automaticLayout: true // Auto-resize with container }); ``` ## Getting Values ```typescript // Get current expression const expression = editor.getValue(); // Set new expression editor.setValue('new.expression | here'); // Listen for changes editor.onDidChangeModelContent(() => { const currentValue = editor.getValue(); console.log('Expression changed:', currentValue); }); ``` That's it! The Monaco integration handles all the complex setup internally, so you can focus on providing a great expression editing experience for your users. # Python Implementation # Python Implementation The Python implementation of JEXL Extended provides identical functionality to the JavaScript version with Pythonic APIs. ## Installation ```bash pip install pyjexl-extended ``` ## Basic Usage ```python from pyjexl_extended import jexl # Simple expression evaluation result = jexl.eval('5 + 3 * 2') # 11 # With context data context = {'name': 'Alice', 'scores': [85, 92, 78]} greeting = jexl.eval('"Hello " + name', context) # "Hello Alice" average = jexl.eval('scores | average', context) # 85 ``` ## Expression Examples Based on the actual test suite, here are working examples: ### String Operations ```python # String conversion and manipulation jexl.eval('string(123)') # "123" jexl.eval('123456|string') # "123456" jexl.eval('{a:123456}|string') # '{"a":123456}' # Case conversion jexl.eval('uppercase("hello world")') # "HELLO WORLD" jexl.eval('lowercase("HELLO WORLD")') # "hello world" jexl.eval('"FOObar"|lower') # "foobar" # camelCase and PascalCase jexl.eval('"foo bar "|camelCase') # "fooBar" jexl.eval('$camelCase("Foo_bar")') # "fooBar" jexl.eval('"FooBar"|toCamelCase') # "fooBar" jexl.eval('"foo bar"|toPascalCase') # "FooBar" jexl.eval('"fooBar"|toPascalCase') # "FooBar" # Substring operations jexl.eval('substring(123456,2,2)') # "34" jexl.eval('$substring("test",(-2))') # "st" jexl.eval('"hello world"|substringBefore(" ")') # "hello" jexl.eval('substringBefore("hello world", "o")') # "hell" jexl.eval('"hello world"|substringAfter(" ")') # "world" jexl.eval('substringAfter("hello world", "x")') # "" # String utilities jexl.eval('trim(" baz ")') # "baz" jexl.eval('trim("__baz--","--")') # "__baz" jexl.eval('pad("foo",5)') # "foo " jexl.eval('pad("foo",(-5),0)') # "00foo" jexl.eval('"foo-bar"|contains("bar")') # True jexl.eval('"foo-bar"|contains("baz")') # False ``` ### Array Operations ```python # Array manipulation jexl.eval('["foo", "bar", "baz"]|append("tek")') # ['foo', 'bar', 'baz', 'tek'] jexl.eval('["tek", "baz", "bar", "foo"]|reverse') # ['foo', 'bar', 'baz', 'tek'] jexl.eval('["tek", "baz", "bar", "foo", "foo"]|reverse|distinct') # ['foo', 'bar', 'baz', 'tek'] # Array splitting and joining jexl.eval('split("foo-bar", "-")') # ['foo', 'bar'] jexl.eval('split("foo-bar", "-")[1]') # "bar" jexl.eval('join(["foo", "bar"], "-")') # "foo-bar" jexl.eval('["foo", "bar"]|join') # "foo,bar" # Contains operations jexl.eval('"foo-bar"|contains("bar")') # True jexl.eval('["foo-bar"]|contains("bar")') # False jexl.eval('["foo-bar"]|contains("foo-bar")') # True jexl.eval('["baz", "foo", "bar"]|contains("bar")') # True # Object operations jexl.eval('{foo:0, bar:1, baz:2, tek:3}|keys') # ['foo', 'bar', 'baz', 'tek'] jexl.eval('{a:"foo", b:"bar", c:"baz", d:"tek"}|values') # ['foo', 'bar', 'baz', 'tek'] ``` ### Mathematical Operations ```python # Number operations jexl.eval('$number("1")') # 1 jexl.eval('$number("1.1")') # 1.1 jexl.eval('$number("-1.1")') # -1.1 jexl.eval('$number(-1.1)|floor') # -2 jexl.eval('$number("10.6")|ceil') # 11 jexl.eval('10.123456|round(2)') # 10.12 jexl.eval('10.123456|toInt') # 10 jexl.eval('"10.123456"|toInt') # 10 jexl.eval('3|power(2)') # 9 jexl.eval('3|power') # 9 jexl.eval('9|sqrt') # 3 jexl.eval('random() < 1') # True # Formatting jexl.eval('16325.62|formatNumber("0,0.000")') # "16,325.620" jexl.eval('12|formatBase(16)') # "c" jexl.eval('16325.62|formatInteger("0000000")') # "0016325" # Aggregations jexl.eval('[1,2,3]|sum') # 6 jexl.eval('sum(1,2,3,4,5)') # 15 jexl.eval('[1,3]|sum(1,2,3,4,5)') # 19 jexl.eval('[1,3]|sum([1,2,3,4,5])') # 19 jexl.eval('[1,3]|max([1,2,3,4,5])') # 5 jexl.eval('[2,3]|min([1,2,3,4,5])') # 1 jexl.eval('[4,5,6]|avg') # 5 ``` ### Boolean Operations ```python # Boolean conversion jexl.eval('1|toBoolean') # True jexl.eval('3|toBoolean') # True jexl.eval('"1"|toBoolean') # True jexl.eval('0|toBool') # False jexl.eval('"false"|toBool') # False jexl.eval('"False"|toBool') # False jexl.eval('"fALSE"|toBool') # False jexl.eval('"tRUE "|toBoolean') # True # Logical operations jexl.eval('"False"|toBool|not') # True jexl.eval('"TRUE"|toBool|not') # False ``` ### Encoding and Conversion ```python # Base64 encoding jexl.eval('base64Encode("foobar")') # "Zm9vYmFy" jexl.eval('base64Decode("Zm9vYmFy")') # "foobar" # URL encoding jexl.eval('{foo:"bar",baz:"tek"}|formUrlEncoded') # "foo=bar&baz=tek" # Text replacement jexl.eval('replace("foo-bar", "-", "_")') # "foo_bar" jexl.eval('replace("foo-bar---", "-", "")') # "foobar" jexl.eval('"123ab123ab123ab"|replace("123")') # "ababab" ``` ## Integration Patterns ### Flask Application ```python from flask import Flask, request, jsonify from pyjexl_extended import jexl app = Flask(__name__) @app.route('/api/filter', methods=['POST']) def filter_data(): data = request.json expression = data.get('expression', '') context = data.get('context', {}) try: result = jexl.eval(expression, context) return jsonify({'result': result}) except Exception as e: return jsonify({'error': str(e)}), 400 # Usage: # POST /api/filter # { # "expression": "users | filter(\"value.active\") | length", # "context": {"users": [...]} # } ``` ### Django Integration ```python from django.http import JsonResponse from pyjexl_extended import jexl import json def evaluate_expression(request): if request.method == 'POST': data = json.loads(request.body) expression = data.get('expression') context = data.get('context', {}) try: result = jexl.eval(expression, context) return JsonResponse({'result': result}) except Exception as e: return JsonResponse({'error': str(e)}, status=400) return JsonResponse({'error': 'Method not allowed'}, status=405) ``` ### Data Processing Pipeline ```python from pyjexl_extended import jexl def process_user_data(users): """Process user data using JEXL expressions""" # Filter active users active_users = jexl.eval('users | filter("value.active")', {'users': users}) # Calculate statistics stats = { 'total_users': jexl.eval('users | length', {'users': users}), 'active_users': jexl.eval('users | length', {'users': active_users}), 'average_age': jexl.eval('users | average("value.age")', {'users': active_users}), 'departments': jexl.eval('users | map("value.department") | distinct', {'users': active_users}) } return stats # Usage users = [ {'name': 'Alice', 'age': 30, 'active': True, 'department': 'Engineering'}, {'name': 'Bob', 'age': 25, 'active': False, 'department': 'Marketing'}, {'name': 'Carol', 'age': 35, 'active': True, 'department': 'Engineering'} ] stats = process_user_data(users) print(stats) ``` ### Configuration System ```python from pyjexl_extended import jexl class ConfigManager: def __init__(self, config_data, user_context): self.config = config_data self.user_context = user_context def get_feature_flag(self, feature_name): """Evaluate feature flag based on user context""" if feature_name not in self.config['features']: return False feature = self.config['features'][feature_name] condition = feature.get('condition', 'true') context = { **self.user_context, 'config': self.config } try: return jexl.eval(condition, context) except: return False def get_setting(self, setting_name, default=None): """Get configuration setting with conditional logic""" if setting_name not in self.config['settings']: return default setting = self.config['settings'][setting_name] if isinstance(setting, dict) and 'condition' in setting: context = {**self.user_context, 'config': self.config} if jexl.eval(setting['condition'], context): return setting['value'] else: return setting.get('default', default) return setting # Usage config = { 'features': { 'premium_feature': { 'condition': 'user.subscription == "premium" || user.role == "admin"' }, 'beta_features': { 'condition': 'user.beta_tester == true' } }, 'settings': { 'max_file_size': { 'condition': 'user.subscription == "premium"', 'value': '100MB', 'default': '10MB' } } } user_context = { 'user': { 'id': 123, 'subscription': 'premium', 'role': 'user', 'beta_tester': False } } config_manager = ConfigManager(config, user_context) has_premium = config_manager.get_feature_flag('premium_feature') # True max_size = config_manager.get_setting('max_file_size', '5MB') # "100MB" ``` ## Error Handling ```python from pyjexl_extended import jexl def safe_eval(expression, context, default_value=None): """Safely evaluate JEXL expression with error handling""" try: return jexl.eval(expression, context) except Exception as e: print(f"Expression evaluation failed: {e}") return default_value # Usage context = {'user': {'name': 'John'}} result = safe_eval('user.profile.email', context, 'No email') # "No email" name = safe_eval('user.name | uppercase', context, 'Unknown') # "JOHN" ``` ## Validation Example ```python from pyjexl_extended import jexl def validate_form(form_data): """Validate form using JEXL expressions""" rules = { 'email': 'email && email | contains("@") && email | contains(".")', 'age': 'age >= 18 && age <= 120', 'password': 'password && password | length >= 8', 'confirm_password': 'password == confirm_password' } results = {} for field, rule in rules.items(): try: results[field] = jexl.eval(rule, form_data) except: results[field] = False return results # Usage form_data = { 'email': 'user@example.com', 'age': 25, 'password': 'securepass123', 'confirm_password': 'securepass123' } validation_results = validate_form(form_data) all_valid = all(validation_results.values()) ``` ## Testing JEXL Expressions ```python import unittest from pyjexl_extended import jexl class TestJexlExpressions(unittest.TestCase): def setUp(self): self.context = { 'users': [ {'name': 'Alice', 'age': 30, 'active': True}, {'name': 'Bob', 'age': 25, 'active': False} ] } def test_string_operations(self): self.assertEqual(jexl.eval('string(123)'), "123") self.assertEqual(jexl.eval('"hello"|uppercase'), "HELLO") self.assertEqual(jexl.eval('"WORLD"|lowercase'), "world") def test_array_operations(self): result = jexl.eval('users | filter("value.active") | length', self.context) self.assertEqual(result, 1) names = jexl.eval('users | map("value.name")', self.context) self.assertEqual(names, ['Alice', 'Bob']) def test_math_operations(self): self.assertEqual(jexl.eval('[1,2,3] | sum'), 6) self.assertEqual(jexl.eval('3 | power(2)'), 9) self.assertEqual(jexl.eval('9 | sqrt'), 3) if __name__ == '__main__': unittest.main() ``` ## Performance Considerations 1. **Reuse the JEXL instance**: The `jexl` object can be reused across evaluations 2. **Minimize context size**: Only include necessary data in the context 3. **Cache results**: For expensive operations, consider caching results 4. **Use appropriate data types**: Python lists and dicts work efficiently with JEXL ```python # Efficient batch processing expressions = [ 'users | length', 'users | filter("value.active") | length', 'users | average("value.age")' ] results = {} for i, expr in enumerate(expressions): results[f'metric_{i}'] = jexl.eval(expr, context) ``` ## Common Patterns ### Data Transformation ```python # Transform API response api_data = { 'users': [ {'first_name': 'John', 'last_name': 'Doe', 'email': 'john@example.com'}, {'first_name': 'Jane', 'last_name': 'Smith', 'email': 'jane@example.com'} ] } transformed = jexl.eval(''' users | map("{ fullName: value.first_name + ' ' + value.last_name, email: value.email, domain: value.email | substringAfter('@') }") ''', api_data) print(transformed) # [ # {'fullName': 'John Doe', 'email': 'john@example.com', 'domain': 'example.com'}, # {'fullName': 'Jane Smith', 'email': 'jane@example.com', 'domain': 'example.com'} # ] ``` ### Conditional Logic ```python # Business rules evaluation user = {'age': 25, 'premium': True, 'country': 'US'} discount = jexl.eval(''' user.premium ? 0.2 : ( user.age < 25 ? 0.1 : ( user.country == "US" ? 0.05 : 0 ) ) ''', {'user': user}) print(f"Discount: {discount * 100}%") # Discount: 20.0% ``` ## Next Steps * **Language Guide** - Learn [JEXL syntax](../language/) that works across all implementations * **Function Reference** - Browse all [built-in functions](../reference/) * **GitHub Repository** - Check [pyjexl-extended](https://github.com/konnektr-io/pyjexl-extended) for latest updates * **Test Examples** - See the [test files](https://github.com/konnektr-io/pyjexl-extended/tree/main/tests) for more examples # Function Reference # Function Reference JEXL Extended provides over 80 built-in functions and transforms organized into the following categories: * [**Math**](./math): Mathematical operations and calculations (11 functions, 10 transforms) * [**Array**](./array): Array operations and transformations (17 functions, 17 transforms) * [**Encoding**](./encoding): Data encoding and formatting utilities (3 functions, 3 transforms) * [**Conversion**](./conversion): Convert between different data types (8 functions, 8 transforms) * [**String**](./string): String manipulation and formatting functions (14 functions, 14 transforms) * [**Utility**](./utility): General utility functions (6 functions, 5 transforms) * [**DateTime**](./datetime): Date and time operations (8 functions, 6 transforms) * [**Object**](./object): Object manipulation and inspection (3 functions, 3 transforms) ## Usage Functions are called directly: ```javascript abs(-5) // Returns: 5 max([1, 2, 3]) // Returns: 3 ``` Transforms are used with the pipe operator: ```javascript "hello world" | uppercase // Returns: "HELLO WORLD" [1, 2, 3] | map("value * 2") // Returns: [2, 4, 6] ``` Many functions can also be used as transforms when they have a single parameter. # Access Control # Access Control KtrlPlane uses a robust Role-Based Access Control (RBAC) system to ensure that users have exactly the permissions they need—no more, no less. Permissions are managed hierarchically across three scopes: **Organization**, **Project**, and **Resource**. ## Permission Scopes Access can be granted at three different levels. Permissions granted at a higher level automatically inherit down to lower levels. | Scope | Description | Example | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Organization** | The top-level boundary. Roles assigned here apply to the entire organization and all projects within it. | granting `Owner` on the Organization gives full control over all projects. | | **Project** | A workspace for related resources. Roles assigned here apply to all resources within the project. | Granting `Viewer` on a Project allows a user to see all resources in that project. | | **Resource** | The individual deployable unit (e.g., a specific Graph or Secret). Roles assigned here apply ONLY to that specific resource. | Granting `Editor` on a specific Secret allows modifying that secret but nothing else. | ## System Roles KtrlPlane provides a set of pre-defined roles designed to cover common access patterns. These roles are categorized into **Platform Access**, **Data Access**, and **Resource-Specific Access**. ### Platform Access Roles These roles control access to the KtrlPlane control plane (configuration, deployment, settings). | Role | Permissions | Best For | | ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------- | | **Owner** | Full administrative access. Can manage billing, users, roles, and delete the scope (Project/Org). | Organization Admins, Project Leads | | **Editor** | Can create, update, and delete resources. Cannot manage user access or billing. | Developers, DevOps Engineers | | **Viewer** | Read-only access to configuration and status. Cannot make any changes. | Auditors, Support Staff, Stakeholders | ### Data Access Roles These roles control access to the *data plane*—the actual data stored within your resources. | Role | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **Konnektr.Data.Owner** | Grants full access to the data within resources. For example, allows querying all nodes in a Graph or reading values in a Secret. | **Control Plane vs. Data Plane**: An `Editor` can change the configuration of a database (Control Plane) but might not have permission to read the customer data inside it (Data Plane). Assign `Konnektr.Data.Owner` to grant data access. ### Resource-Specific Roles These roles are tailored for specific resource types and offer more granular control. * **Konnektr.Graph.Owner**, **Konnektr.Graph.Editor**, **Konnektr.Graph.Viewer** * **Konnektr.Flow\.Owner**, **Konnektr.Flow\.Editor**, **Konnektr.Flow\.Viewer** * **Konnektr.Secret.Owner**, **Konnektr.Secret.Editor**, **Konnektr.Secret.Viewer** Use these when you need to grant access to a specific *type* of resource without granting blanket access to the entire project. ## Inheritance Model Permissions are additive and hierarchical. * **Organization Owner** implies **Project Owner** for all projects. * **Project Viewer** implies **Resource Viewer** for all resources in that project. Best Practice: Assign roles at the **Project** level for teams to reduce management overhead. Use **Resource** level assignments only for exceptions (e.g., a specific secret that only one person should see). ## Managing Access To manage access: 1. Navigate to the scope you want to manage (Organization Settings, Project Settings, or Resource Details). 2. Click on the **"Access"** or **"Permissions"** tab. 3. Click **"Add Assignment"**. 4. Select the **User** (by email) and the **Role**. 5. Save the assignment. Effective permissions are calculated instantly, allowing users immediate access. # Organizations # Organizations Organizations are the highest-level grouping construct in KtrlPlane. They represent a company, business unit, or major team boundary. ## Purpose * Group related projects * Provide a shared billing context * Define a top-level RBAC boundary (org\_owner, org\_admin, org\_viewer) * Serve as a logical tenant anchor for multi-tenancy ## Key Characteristics | Attribute | Description | | ------------- | -------------------------------------------------------------- | | Multi-tenancy | Each organization establishes isolation across data and access | | Billing | Can own billing settings or allow project-specific overrides | | Membership | Users may belong to multiple organizations | | Governance | Central place to enforce policies and audit access | ## Lifecycle 1. Creation: An initial owner establishes the organization 2. Project Provisioning: Projects are added under the organization 3. Growth: Roles and billing are refined as usage scales 4. Decommissioning: Resources and projects archived prior to deletion ## RBAC Overview Organization-level roles often influence which projects are visible and manageable. ## Best Practices * Use descriptive names (e.g., "Acme Data Platform") * Centralize billing at the organization unless specific chargeback is required * Periodically audit role assignments ## Next Steps * [Projects](/concepts/projects) * [Access Control](/concepts/access-control) # Projects # Projects Projects are operational workspaces that group resources and define an RBAC boundary for day-to-day execution. ## Purpose * Provide a focused context for an application or workload * Group related resources (Graph, Flow, Assembler, Compass) * Act as a billing scope (inherit or override organization billing) * Enable scoped role assignments (project\_owner, project\_editor, project\_viewer) ## When to Create a New Project Create a new project when: * You have a logical application boundary * Different teams manage separate workloads * You require isolated access control for a feature set * You want to segment billing or usage reporting ## Project Lifecycle 1. Initialization: Project defined with name and organization association 2. Resource Provisioning: Platform resources created inside the project 3. Expansion: Additional roles and monitoring added 4. Evolution: Configuration updated based on scaling needs 5. Archival: Project retired and resources terminated ## RBAC Scope Project-level roles govern access to all resources within the project unless overridden by resource-specific roles. ## Billing Inheritance Projects can inherit billing from the parent organization or specify their own subscription context. ## Best Practices * Use consistent naming patterns (e.g., `data-analytics-prod`) * Keep resource count manageable for clarity * Regularly review resource health and RBAC assignments ## Next Steps * [Resources](/concepts/resources) * [Access Control](/concepts/access-control) # Resources # Resources Resources are the core deployable services and applications within the Konnektr Platform. They represent the actual functionality you're building and deploying - from graph databases to AI-powered builders. ## What Are Resources? Resources in KtrlPlane are: * **Deployable services** that provide specific functionality * **Managed instances** of Konnektr products (Graph, Flow, Assembler, Compass) * **Configurable applications** with specific settings and tiers * **Billable entities** that consume compute, storage, and network resources ## Available Resource Types ### Konnektr.Graph **High-performance graph database and API layer** * **Purpose**: Store and query connected data for digital twin models * **Use Cases**: * IoT device networks and relationships * Digital twin data models * Knowledge graphs * Social networks and organizational structures * **Key Features**: * CRUD operations for nodes and relationships * Advanced graph query capabilities * Real-time data synchronization * Built-in analytics and reporting **Configuration Options:** ```json { "database_name": "my-digital-twins", "enable_analytics": true, "backup_retention_days": 7, "query_timeout_seconds": 30, "max_concurrent_connections": 100, "enable_audit_logging": false } ``` **Available Tiers:** * **Free**: Development and testing usage * **Pro**: Production workloads with higher limits * **Enterprise**: Custom limits and dedicated support ### Konnektr.Flow **Real-time data and event processing** * **Purpose**: Process streaming data and handle events in real-time * **Use Cases**: * Sensor data processing and transformation * Event-driven workflows and automation * Real-time analytics and alerting * Data pipeline orchestration * **Key Features**: * Visual flow design interface * Pre-built connectors and transformations * Error handling and retry mechanisms * Scalable event processing **Configuration Options:** ```json { "max_concurrent_flows": 10, "retention_days": 30, "enable_dead_letter_queue": true, "processing_mode": "streaming", "auto_scaling": { "enabled": true, "min_instances": 1, "max_instances": 5 } } ``` **Available Tiers:** * **Free**: Development and testing usage * **Pro**: Production workloads with higher limits * **Enterprise**: Custom limits and dedicated support Tier limits and enforcement are planned features. Currently, all tiers provide full functionality for development and testing. ### Konnektr.Assembler **AI-powered digital twin builder** * **Purpose**: Automatically generate digital twin models using AI * **Use Cases**: * Automated DTDL model generation * Data source integration and mapping * Intelligent schema inference * Model validation and optimization * **Key Features**: * AI-powered model generation * Multiple data source connectors * Visual model editor * Validation and testing tools **Configuration Options:** ```json { "model_complexity": "standard", "output_format": "dtdl_v2", "confidence_threshold": 0.8 } ``` **Available Tiers:** * **Free**: Development and testing usage * **Pro**: Production workloads with higher limits * **Enterprise**: Custom limits and dedicated support ### Konnektr.Compass (Coming Soon) **Navigation and discovery tools** * **Purpose**: Intelligent navigation and discovery for digital twin networks * **Use Cases**: * Intelligent search and discovery * Automated relationship mapping * Navigation optimization * Recommendation systems ## Resource Lifecycle ### 1. Creation When you create a resource: 1. **Selection**: Choose the resource type and tier 2. **Configuration**: Set up resource-specific settings 3. **Validation**: KtrlPlane validates your configuration 4. **Provisioning**: Infrastructure is allocated and configured 5. **Deployment**: The resource is deployed and becomes available ### 2. Running State Once deployed, resources provide: * **Service endpoints** for accessing functionality * **Configuration management** for updating settings * **Monitoring and logging** for operational visibility * **Scaling capabilities** based on usage patterns ### 3. Management Throughout their lifecycle, you can: * **Update configuration** to modify behavior * **Scale up or down** to handle changing demands * **Monitor performance** and usage metrics * **Access logs and diagnostics** for troubleshooting ### 4. Termination When you no longer need a resource: 1. **Backup data** if needed (some services have automatic backups) 2. **Remove dependencies** from other resources 3. **Delete the resource** through the KtrlPlane interface 4. **Billing stops** when the resource is fully terminated ## Resource Configuration ### Settings Schema Each resource type has a specific JSON schema for configuration: ```typescript // Example: Graph Resource Settings interface GraphSettings { database_name: string; enable_analytics: boolean; backup_retention_days: number; query_timeout_seconds: number; max_concurrent_connections: number; enable_audit_logging: boolean; } ``` ### Configuration Best Practices 1. **Start Conservative**: Begin with modest resource limits and scale up as needed 2. **Use Descriptive Names**: Choose clear, descriptive names for your resources 3. **Plan for Growth**: Consider future scaling needs when setting initial configuration 4. **Security First**: Enable security features like audit logging when available 5. **Regular Reviews**: Periodically review and optimize your resource configurations ### Dynamic Configuration Many settings can be updated without recreating the resource: * **Scaling parameters** (memory, CPU, connections) * **Retention policies** (backup, logging, data retention) * **Security settings** (access control, audit logging) * **Performance tuning** (timeouts, caching, optimization) ## Resource Tiers and Billing ### Understanding Tiers Each resource type offers multiple tiers: * **Free Tier**: Perfect for development, testing, and small projects * **Pro Tier**: Production-ready with higher limits and additional features * **Enterprise Tier**: Maximum performance, dedicated infrastructure, and SLA ### Billing Model Resources are billed based on: 1. **Base tier cost**: Monthly subscription for the selected tier 2. **Usage-based charges**: Additional costs for usage beyond tier limits 3. **Storage costs**: Data storage charges for persistent data 4. **Network egress**: Charges for data transfer out of the platform ### Cost Optimization * **Right-sizing**: Choose appropriate tiers based on actual usage * **Monitoring**: Use built-in monitoring to track resource utilization * **Scaling**: Configure auto-scaling to optimize costs * **Cleanup**: Remove unused resources to avoid ongoing charges ## Resource Access and Security ### Access URLs Each resource provides secure access endpoints: ``` https://graph-abc123.konnektr.io/api/v1 https://flow-def456.konnektr.io/webhooks https://assembler-ghi789.konnektr.io/models ``` ### Authentication Resources use multiple authentication methods: * **API Keys**: For programmatic access * **JWT Tokens**: For user-based authentication * **OAuth 2.0**: For third-party integrations * **Service Accounts**: For service-to-service communication ### Network Security * **TLS Encryption**: All traffic is encrypted in transit * **VPC Isolation**: Enterprise tiers offer network isolation * **IP Whitelisting**: Restrict access to specific IP ranges * **Private Endpoints**: Direct private connectivity options ## Resource Integration ### Inter-Resource Communication Resources within the same project can communicate securely: ```json { "flow_config": { "graph_endpoint": "graph://my-graph-resource/api/v1", "assembler_endpoint": "assembler://my-assembler-resource/models" } } ``` ### External Integrations Connect resources to external services: * **Webhooks**: Receive notifications from external systems * **API Connectors**: Pull data from external APIs * **Database Connections**: Connect to external databases * **Message Queues**: Integrate with messaging systems ### SDK and Libraries Each resource type provides: * **REST APIs**: Standard HTTP-based interfaces * **SDKs**: Language-specific client libraries * **GraphQL**: Query-based APIs where applicable * **WebSocket**: Real-time bidirectional communication ## Monitoring and Observability ### Built-in Metrics All resources provide standard metrics: * **Performance**: Response times, throughput, error rates * **Resource Utilization**: CPU, memory, storage usage * **Business Metrics**: Custom metrics specific to each resource type * **Cost Metrics**: Resource consumption and billing information ### Logging Comprehensive logging capabilities: * **Application Logs**: Resource-specific operational logs * **Access Logs**: All API calls and user interactions * **Audit Logs**: Security and configuration changes * **Performance Logs**: Detailed performance and debugging information ### Alerting Set up alerts for: * **Performance Issues**: High response times or error rates * **Resource Limits**: Approaching tier limits or quotas * **Security Events**: Unauthorized access attempts * **Cost Thresholds**: Unexpected billing increases ## Next Steps Now that you understand resources: 1. **[Create Your First Resource](/getting-started/first-project)**: Deploy a resource in your project 2. **[Resource Management Guide](/guides/resources)**: Learn advanced resource management 3. **[Billing and Optimization](/guides/billing)**: Understand costs and optimization strategies 4. **[API Integration](/api/resources)**: Learn how to integrate with resource APIs Start with free tiers to experiment and learn. You can always upgrade to higher tiers as your needs grow and you become more familiar with each resource type. # Creating Your First Project # Creating Your First Project Projects are the core workspaces in KtrlPlane where you organize and deploy your resources. This guide will walk you through creating, configuring, and managing your first project. ## Understanding Projects A project in KtrlPlane is: * **A workspace** for related resources and applications * **A billing boundary** where costs can be tracked separately * **An access control scope** where you can grant team members specific permissions * **A deployment environment** for your Konnektr resources Projects belong to organizations. If you haven't created an organization yet, follow the [Quick Start Guide](/getting-started/quick-start) first. ## Step 1: Navigate to Project Creation 1. Log in to KtrlPlane and select your organization 2. From the organization dashboard, you'll see your projects (if any) 3. Click the **"New Project"** button or **"Create Your First Project"** if this is your first one ## Step 2: Basic Project Information Fill out the project creation form: ### Project Name * Choose a descriptive name that reflects the project's purpose * Examples: "IoT Sensor Network", "Customer Analytics Platform", "Smart Building Management" * Names must be unique within your organization ### Description (Optional) * Add a brief description explaining the project's goals * This helps team members understand the project's purpose * Examples: "Real-time monitoring system for manufacturing equipment", "Customer behavior analysis for e-commerce platform" ### Project ID * Automatically generated based on your project name * Used in URLs and API calls * Can be customized if needed (must be unique) ## Step 3: Advanced Configuration ### Billing Configuration You have two options for project billing: #### Option 1: Inherit from Organization (Recommended) * Uses your organization's billing account and payment method * Simplifies billing management * All project costs appear on the organization's invoice * **Choose this if**: You want centralized billing management #### Option 2: Separate Project Billing * Set up dedicated billing for this project * Requires separate payment method configuration * Useful for client projects or cost center tracking * **Choose this if**: You need separate invoicing or charge-backs ### Access Control Template Choose who can access your project initially: * **Private**: Only you have access (you can invite others later) * **Organization Members**: All organization members get viewer access * **Custom**: Define specific roles for organization members You can always modify access permissions later through the project's Access Control settings. ## Step 4: Create the Project 1. Review your configuration 2. Click **"Create Project"** 3. Wait for the project to be created (usually takes a few seconds) 4. You'll be redirected to your new project dashboard ## Step 5: Project Dashboard Overview Your project dashboard provides: ### Quick Stats * Number of resources deployed * Current monthly usage and costs * Active team members * Project health status ### Recent Activity * Recent resource deployments * Team member access changes * Configuration updates * Billing events ### Quick Actions * **Add Resource**: Deploy a new Konnektr service * **Invite Team Member**: Grant project access to someone * **View Billing**: Check usage and costs * **Project Settings**: Modify project configuration ## Step 6: Deploy Your First Resource Now that your project is created, let's deploy your first resource: 1. Click **"Add Resource"** from the project dashboard 2. Choose a resource type based on your needs: ### Konnektr.Graph * **Best for**: Storing and querying connected data * **Use cases**: Digital twin data models, relationship mapping, IoT device networks * **Free tier**: Up to 1,000 nodes and 10,000 relationships ### Konnektr.Flow * **Best for**: Real-time data processing and event handling * **Use cases**: Sensor data processing, alert systems, data transformation pipelines * **Free tier**: Up to 1,000 events per hour ### Konnektr.Assembler * **Best for**: AI-powered digital twin creation * **Use cases**: Automated model generation, data source integration, intelligent mapping * **Free tier**: 5 AI generations per month 3. Select your preferred tier (Free, Pro, or Enterprise) 4. Configure the resource settings 5. Click **"Create Resource"** ## Step 7: Configure Resource Settings Each resource type has specific configuration options: ### Graph Database Settings ```json { "database_name": "my-digital-twins", "enable_analytics": true, "backup_retention_days": 7, "access_control": { "enable_row_level_security": false } } ``` ### Flow Processing Settings ```json { "max_concurrent_flows": 10, "retention_days": 30, "enable_dead_letter_queue": true, "auto_scaling": { "enabled": true, "max_instances": 5 } } ``` ### Assembler AI Settings ```json { "model_complexity": "standard", "auto_validation": true, "output_format": "dtdl_v2", "training_data_retention": "30_days" } ``` Don't worry about getting all settings perfect initially. You can modify most configuration options after the resource is deployed. ## Step 8: Monitor Deployment After creating a resource: 1. You'll see the deployment progress in real-time 2. Deployment typically takes 2-5 minutes depending on the resource type 3. You'll receive an email notification when deployment completes 4. The resource will appear in your project dashboard with a "Running" status ## Managing Your Project ### Project Settings Access project settings to: * Change project name and description * Modify billing configuration * Update access control policies * Configure integrations and webhooks ### Team Management Invite team members and manage permissions: * **Viewer**: Can see resources and their configurations * **Editor**: Can create, modify, and delete resources * **Admin**: Can manage billing and team access * **Owner**: Full project control (transferable) ### Resource Management From your project dashboard you can: * View all deployed resources * Check resource health and status * Access resource configuration * Monitor usage and performance * Scale resources up or down ## Next Steps Now that you have your first project set up: 1. **[Explore Resource Management](/guides/resources)**: Learn advanced resource configuration 2. **[Set Up Billing Alerts](/guides/billing)**: Monitor costs and set up notifications 3. **[Configure Access Control](/guides/access-control)**: Fine-tune team permissions 4. **[Connect External Services](/guides/integrations)**: Integrate with your existing tools ## Project Best Practices ### Naming Conventions * Use descriptive, consistent names * Include environment indicators (dev, staging, prod) * Consider using prefixes for different project types ### Resource Organization * Group related resources in the same project * Use separate projects for different environments * Consider project size limits for better management ### Access Control * Follow the principle of least privilege * Regularly review team access * Use temporary access for contractors or external collaborators ### Cost Management * Set up billing alerts for your projects * Monitor resource usage regularly * Use free tiers for development and testing 🎉 You've successfully created and configured your first project! You're now ready to build and deploy powerful digital twin solutions using the Konnektr Platform. # Understanding Organizations # Understanding Organizations Organizations are the foundational structure in KtrlPlane. They represent your company, team, or personal workspace and serve as the top-level container for all your projects and resources. ## What is an Organization? An organization in KtrlPlane is: * **The top-level entity** that contains all your projects and resources * **A billing boundary** where payment methods and subscriptions are managed * **A team workspace** where you collaborate with colleagues * **An administrative scope** for managing company-wide policies and settings Think of an organization like a company account on other platforms - it's where your team collaborates and where billing is centralized. ## Organization Structure ``` Organization (Acme Corp) ├── Project A (IoT Platform) │ ├── Resource 1 (Graph Database) │ ├── Resource 2 (Flow Processor) │ └── Resource 3 (Assembler AI) ├── Project B (Analytics Dashboard) │ ├── Resource 1 (Graph Database) │ └── Resource 2 (Flow Processor) └── Project C (Mobile App Backend) └── Resource 1 (Graph Database) ``` ## Creating Your Organization ### First Organization When you first sign up for KtrlPlane, you'll be prompted to create your initial organization: 1. **Organization Name**: Choose a name that represents your team or company 2. **Description**: Optional description of your organization's purpose 3. **Billing Email**: Email address for billing notifications (can be different from your account email) ### Additional Organizations You can create multiple organizations if you: * Work with different companies or teams * Need separate billing for different business units * Manage client projects that require isolation To create additional organizations: 1. Click your profile menu in the top right 2. Select **"Switch Organization"** 3. Click **"Create New Organization"** 4. Fill out the organization details ## Organization Settings ### Basic Information Manage your organization's core details: * **Name**: The display name for your organization * **Description**: Brief description of your organization's purpose * **Organization ID**: Unique identifier used in URLs and APIs * **Contact Information**: Primary contact details ### Billing Configuration Organizations handle billing for all contained projects (unless projects have separate billing): * **Payment Methods**: Credit cards, bank accounts, or invoicing * **Billing Address**: Address for tax calculations and invoices * **Tax Information**: VAT numbers, tax exemption certificates * **Billing Contacts**: Who receives billing notifications and invoices ### Default Settings Set organization-wide defaults that apply to new projects: * **Default Resource Tiers**: Which tiers to suggest for new resources * **Access Control Policies**: Default permissions for organization members * **Compliance Settings**: Security and compliance requirements * **Integration Defaults**: Default connections to external services ## Team Management ### Organization Roles There are several roles available at the organization level: #### Owner * **Full control** over the organization * Can delete the organization * Manage billing and payment methods * Transfer ownership to another member * **Limit**: Only one owner per organization #### Admin * **Administrative access** to organization settings * Create and manage projects * Invite and remove team members * Configure billing (but not delete payment methods) * **Cannot**: Delete organization or transfer ownership #### Member * **Standard user access** * Can view projects they have access to * Can create new projects (if allowed by org policy) * Cannot modify organization settings * **Access**: Determined by individual project permissions #### Viewer * **Read-only access** to organization information * Can see organization projects (but not access them unless specifically granted) * Cannot create projects or modify settings * Useful for stakeholders who need visibility but not control ### Inviting Team Members 1. Go to **Organization Settings > Team Management** 2. Click **"Invite Team Member"** 3. Enter their email address 4. Select their organization role 5. Optionally set an expiration date for the invitation 6. Click **"Send Invitation"** The invited user will receive an email with instructions to join your organization. ### Managing Existing Members From the team management page, you can: * **Change roles**: Promote or demote team members * **Remove members**: Remove access to the organization * **View activity**: See when members last accessed the organization * **Manage invitations**: Cancel pending invitations or resend them ## Billing and Subscriptions ### Organization-Level Billing Organizations can have their own billing configuration: * **Primary payment method** for all projects in the organization * **Consolidated invoicing** for all resource usage * **Usage-based billing** across all projects * **Subscription management** for organization-wide features ### Project Billing Inheritance Projects can either: 1. **Inherit billing** from the organization (recommended) 2. **Use separate billing** with their own payment methods Benefits of inheritance: * Simplified billing management * Consolidated invoices * Easier cost tracking across projects * Reduced administrative overhead ### Setting Up Billing 1. Go to **Organization Settings > Billing** 2. Add a payment method (credit card, bank account, or request invoicing) 3. Configure your billing address and tax information 4. Set up billing notifications and contacts 5. Choose your subscription plan (if applicable) ## Organization Best Practices ### Naming Strategy * Use your actual company or team name * Keep it professional and recognizable * Avoid abbreviations that might be confusing to team members ### Team Structure * **Start small**: Begin with just essential team members * **Use appropriate roles**: Don't give everyone admin access * **Regular reviews**: Periodically review team access and roles * **Clear policies**: Document who can invite new members and create projects ### Billing Management * **Centralized approach**: Use organization-level billing for most use cases * **Set up alerts**: Configure billing notifications to avoid surprises * **Regular monitoring**: Review usage and costs monthly * **Budget planning**: Use project-level cost tracking for budgeting ### Security Considerations * **Enable two-factor authentication** for all team members * **Regular access reviews** to ensure only current team members have access * **Audit logs** to track important changes to the organization * **Compliance settings** based on your industry requirements ## Multiple Organizations ### When to Use Multiple Organizations Create separate organizations when you need: 1. **Complete isolation** between different business units 2. **Separate billing** for different companies or clients 3. **Different compliance requirements** (e.g., HIPAA vs. non-HIPAA projects) 4. **Distinct team structures** with no overlap ### Managing Multiple Organizations * **Organization switching**: Use the organization switcher in the top navigation * **Unified billing**: Set up consolidated billing across organizations if needed * **Cross-organization collaboration**: Invite the same users to multiple organizations * **Consistent policies**: Apply similar security and compliance settings ### Organization Consolidation If you find you have too many organizations: 1. **Evaluate necessity**: Determine if separation is still needed 2. **Plan migration**: Move projects between organizations if possible 3. **Billing consideration**: Understand billing implications of consolidation 4. **Team communication**: Inform all stakeholders about changes ## Next Steps Now that you understand organizations: 1. **[Create Your First Project](/getting-started/first-project)**: Set up a project within your organization 2. **[Configure Team Access](/guides/access-control)**: Learn advanced permission management 3. **[Set Up Billing](/guides/billing)**: Configure payment methods and billing policies 4. **[Explore Projects](/concepts/projects)**: Deep dive into project management Most teams should start with a single organization and create additional ones only when there's a clear business need for separation. # Quick Start Guide # Quick Start Guide Welcome to KtrlPlane! This guide will help you get started with the Control Plane for the Konnektr Platform in just a few minutes. ## What is KtrlPlane? KtrlPlane is the centralized management system for the Konnektr Platform. It provides: * **Organization Management**: Create and manage teams and workspaces * **Project Management**: Organize your applications and resources * **Resource Lifecycle**: Deploy and manage Konnektr products (Graph, Flow, Assembler, Compass) * **Access Control**: Role-based permissions for secure collaboration * **Billing**: Integrated subscription and usage-based billing ## Prerequisites To use KtrlPlane, you need: * A modern web browser (Chrome, Firefox, Safari, Edge) * An internet connection * An email address for account creation ## Step 1: Create Your Account 1. Visit the KtrlPlane login page 2. Click **"Sign Up"** to create a new account 3. Enter your email address and create a secure password 4. Verify your email address by clicking the link sent to your inbox 5. Complete your profile setup ## Step 2: Create Your First Organization Organizations are the top-level containers in KtrlPlane. They represent your company, team, or personal workspace. 1. After logging in, you'll be prompted to create your first organization 2. Enter your organization name (e.g., "Acme Corp", "Personal Projects") 3. Add an optional description 4. Click **"Create Organization"** You can create multiple organizations if you work with different teams or manage separate businesses. ## Step 3: Create Your First Project Projects are workspaces within your organization where you'll deploy and manage your resources. 1. From your organization dashboard, click **"Create Project"** 2. Enter a project name (e.g., "IoT Dashboard", "Customer Analytics") 3. Add a description explaining what this project is for 4. Click **"Create Project"** ## Step 4: Deploy Your First Resource Resources are the actual Konnektr products and services you'll use in your project. 1. Navigate to your project dashboard 2. Click **"Add Resource"** 3. Choose from available resource types: * **Graph**: High-performance graph database for digital twin data * **Flow**: Real-time data and event processing * **Assembler**: AI-powered digital twin builder * **Compass**: Navigation and discovery tools (coming soon) 4. Select a resource tier (Free, Pro, Enterprise) 5. Configure your resource settings 6. Click **"Create Resource"** Start with the Free tier to explore the platform without any cost. You can always upgrade later as your needs grow. ## Step 5: Invite Team Members If you're working with a team, you can invite collaborators to your organization or specific projects. 1. Go to your organization or project settings 2. Click **"Access Control"** 3. Click **"Invite User"** 4. Enter their email address 5. Select their role: * **Viewer**: Can view resources but not modify them * **Editor**: Can create and modify resources * **Admin**: Full access including billing and user management * **Owner**: Complete control (only one per organization/project) 6. Click **"Send Invitation"** ## What's Next? Now that you have KtrlPlane set up, you can: * **[Create More Projects](/getting-started/first-project)**: Learn advanced project management * **[Explore Resource Types](/concepts/resources)**: Understand what each Konnektr product offers * **[Set Up Billing](/guides/billing)**: Configure payment methods and subscriptions * **[Manage Access Control](/guides/access-control)**: Fine-tune permissions for your team ## Need Help? If you run into any issues: * Check our **[FAQ](/support/faq)** for common questions * Visit our **[Troubleshooting Guide](/support/troubleshooting)** * Reach out to our **[Community](/support/community)** for help 🎉 Congratulations! You've successfully set up KtrlPlane and deployed your first resource. You're now ready to build amazing digital twin solutions with the Konnektr Platform. # Development Setup # Development Setup This guide will help you set up a local development environment for contributing to KtrlPlane. Whether you're fixing bugs, adding features, or improving documentation, this guide will get you up and running quickly. ## Prerequisites Before you begin, ensure you have the following installed: ### Required Software * **Go 1.21+**: Backend development * **Node.js 18+**: Frontend development * **pnpm**: Package management for frontend * **PostgreSQL 14+**: Local database * **Git**: Version control * **Docker** (optional): For containerized development ### Development Tools (Recommended) * **VS Code**: With Go and TypeScript extensions * **Postman/Insomnia**: API testing * **pgAdmin/DBeaver**: Database administration * **GitHub CLI**: For easier contribution workflow ## Quick Setup ### 1. Clone the Repository ```bash git clone https://github.com/konnektr-io/ktrlplane.git cd ktrlplane ``` ### 2. Database Setup **Option A: Local PostgreSQL** ```bash # Create database and user sudo -u postgres psql CREATE USER ktrlplane_dev WITH ENCRYPTED PASSWORD 'dev_password'; CREATE DATABASE ktrlplane_dev OWNER ktrlplane_dev; GRANT ALL PRIVILEGES ON DATABASE ktrlplane_dev TO ktrlplane_dev; \q ``` **Option B: Docker PostgreSQL** ```bash cd deployments/docker docker-compose up -d postgres ``` ### 3. Backend Setup ```bash # Install Go dependencies go mod tidy # Copy example configuration cp config.yaml.example config.yaml # Edit config.yaml with your database settings nano config.yaml # Run database migrations go run cmd/migrate/main.go # Start the backend server go run cmd/server/main.go ``` The backend will be available at `http://localhost:8080` ### 4. Frontend Setup ```bash cd web # Install dependencies pnpm install # Start development server pnpm dev ``` The frontend will be available at `http://localhost:5173` ### 5. Verify Setup 1. Open your browser to `http://localhost:5173` 2. You should see the KtrlPlane login page 3. Backend health check: `curl http://localhost:8080/health` ## Detailed Setup ### Configuration The `config.yaml` file contains all application configuration: ```yaml # config.yaml database: host: "localhost" port: 5432 username: "ktrlplane_dev" password: "dev_password" database: "ktrlplane_dev" ssl_mode: "disable" auth: domain: "your-dev-auth0-domain.auth0.com" audience: "https://api.ktrlplane.localhost" client_id: "your-auth0-client-id" server: port: 8080 cors: allowed_origins: - "http://localhost:5173" - "http://localhost:3000" logging: level: "debug" format: "text" ``` ### Environment Variables For local development, you can also use environment variables: ```bash # Create .env file cat > .env << EOF DB_HOST=localhost DB_PORT=5432 DB_USER=ktrlplane_dev DB_PASSWORD=dev_password DB_NAME=ktrlplane_dev DB_SSL_MODE=disable AUTH_DOMAIN=your-dev-auth0-domain.auth0.com AUTH_AUDIENCE=https://api.ktrlplane.localhost AUTH_CLIENT_ID=your-auth0-client-id LOG_LEVEL=debug EOF # Source environment variables source .env ``` ### Auth0 Development Setup For authentication to work, you'll need an Auth0 development account: 1. Create a free Auth0 account at [auth0.com](https://auth0.com) 2. Create a new Application (Single Page Application) 3. Configure callback URLs: * `http://localhost:5173/callback` * `http://localhost:5173/silent-callback` 4. Configure logout URLs: `http://localhost:5173` 5. Create an API with identifier: `https://api.ktrlplane.localhost` 6. Update your `config.yaml` with Auth0 settings ## Project Structure Understanding the codebase structure: ``` ktrlplane/ ├── cmd/ # Application entry points │ ├── migrate/ # Database migration tool │ └── server/ # HTTP server ├── internal/ # Private application code │ ├── api/ # HTTP handlers and routes │ ├── auth/ # Authentication logic │ ├── config/ # Configuration management │ ├── db/ # Database layer │ ├── models/ # Data models │ └── service/ # Business logic ├── migrations/ # SQL migration files ├── web/ # React frontend │ ├── src/ │ │ ├── components/ # Reusable UI components │ │ ├── features/ # Feature-specific code │ │ ├── hooks/ # Custom React hooks │ │ ├── lib/ # Utility libraries │ │ ├── pages/ # Page components │ │ └── store/ # State management ├── deployments/ # Deployment configurations ├── docs/ # Documentation └── README.md ``` ## Development Workflow ### 1. Backend Development **Starting the backend:** ```bash # Development with auto-reload (install air first) go install github.com/cosmtrek/air@latest air # Or run directly go run cmd/server/main.go ``` **Running tests:** ```bash # All tests go test ./... # Specific package go test ./internal/service/... # With coverage go test -cover ./... ``` **Database migrations:** ```bash # Create new migration migrate create -ext sql -dir migrations -seq add_new_feature # Run migrations go run cmd/migrate/main.go # Or use make make migrate ``` ### 2. Frontend Development **Starting the frontend:** ```bash cd web pnpm dev ``` **Running tests:** ```bash # Unit tests pnpm test # E2E tests pnpm test:e2e # Test coverage pnpm test:coverage ``` **Linting and formatting:** ```bash # Lint pnpm lint # Fix linting issues pnpm lint:fix # Format code pnpm format ``` ### 3. Full Stack Development Use the provided VS Code tasks for efficient development: 1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) 2. Type "Tasks: Run Task" 3. Choose from: * `go: run backend` - Start backend server * `vite: dev` - Start frontend development server ## Debugging ### Backend Debugging **Using VS Code:** 1. Install the Go extension 2. Set breakpoints in your code 3. Press F5 to start debugging 4. The debugger will attach to the running process **Using Delve directly:** ```bash # Install delve go install github.com/go-delve/delve/cmd/dlv@latest # Start debugging dlv debug cmd/server/main.go ``` ### Frontend Debugging **Browser DevTools:** * Use Chrome DevTools or Firefox Developer Tools * React components are visible in React DevTools extension * Zustand store can be inspected with Redux DevTools **VS Code Debugging:** 1. Install the "Debugger for Chrome" extension 2. Set breakpoints in TypeScript/JavaScript files 3. Use the debug configuration in `.vscode/launch.json` ## Testing ### Backend Tests **Unit Tests:** ```bash # Run all tests go test ./... # Run tests with verbose output go test -v ./... # Run tests for specific package go test -v ./internal/service/ ``` **Integration Tests:** ```bash # Start test database cd deployments/docker docker-compose -f docker-compose.test.yml up -d # Run integration tests go test -tags=integration ./... ``` **Test Coverage:** ```bash # Generate coverage report go test -coverprofile=coverage.out ./... go tool cover -html=coverage.out -o coverage.html open coverage.html ``` ### Frontend Tests **Unit Tests:** ```bash cd web # Run all tests pnpm test # Watch mode pnpm test:watch # Coverage pnpm test:coverage ``` **E2E Tests:** ```bash # Install Playwright browsers pnpm exec playwright install # Run E2E tests pnpm test:e2e # Run in UI mode pnpm test:e2e:ui ``` ## Database Development ### Migrations Create new migrations for schema changes: ```bash # Create migration file migrate create -ext sql -dir migrations -seq add_user_preferences # This creates: # migrations/001_add_user_preferences.up.sql # migrations/001_add_user_preferences.down.sql ``` **Migration best practices:** * Always create both up and down migrations * Test migrations on a copy of production data * Keep migrations small and focused * Never modify existing migrations in production ### Schema Changes ```sql -- Example migration: 005_add_user_preferences.up.sql CREATE TABLE user_preferences ( user_id VARCHAR(255) PRIMARY KEY, preferences JSONB NOT NULL DEFAULT '{}', created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() ); CREATE INDEX idx_user_preferences_user_id ON user_preferences(user_id); ``` ```sql -- Example rollback: 005_add_user_preferences.down.sql DROP TABLE IF EXISTS user_preferences; ``` ## API Development ### Adding New Endpoints 1. **Define the model** in `internal/models/models.go` 2. **Add service methods** in `internal/service/` 3. **Create handlers** in `internal/api/handlers.go` 4. **Add routes** in `internal/api/routes.go` 5. **Write tests** for all layers **Example:** ```go // 1. Model (internal/models/models.go) type UserPreference struct { UserID string `json:"user_id" db:"user_id"` Preferences json.RawMessage `json:"preferences" db:"preferences"` CreatedAt time.Time `json:"created_at" db:"created_at"` UpdatedAt time.Time `json:"updated_at" db:"updated_at"` } // 2. Service (internal/service/user_service.go) func (s *UserService) GetPreferences(userID string) (*UserPreference, error) { // Implementation } // 3. Handler (internal/api/handlers.go) func (h *APIHandler) GetUserPreferences(c *gin.Context) { // Implementation } // 4. Route (internal/api/routes.go) apiV1.GET("/users/:userId/preferences", handler.GetUserPreferences) ``` ## Code Quality ### Go Standards Follow Go best practices: ```bash # Format code go fmt ./... # Vet code go vet ./... # Run linters (install golangci-lint first) golangci-lint run ``` ### TypeScript Standards Follow TypeScript and React best practices: ```bash cd web # Type checking pnpm type-check # Linting pnpm lint # Formatting pnpm format ``` ## Git Workflow ### Branch Naming * `feature/add-user-preferences` - New features * `bugfix/fix-login-issue` - Bug fixes * `docs/update-api-docs` - Documentation updates * `refactor/optimize-database-queries` - Code refactoring ### Commit Messages Use conventional commits: ``` feat: add user preferences endpoint fix: resolve authentication timeout issue docs: update API documentation refactor: optimize database connection pooling test: add unit tests for billing service ``` ### Pull Request Process 1. Create feature branch from `main` 2. Make your changes 3. Add tests for new functionality 4. Update documentation if needed 5. Ensure all tests pass 6. Create pull request with descriptive title and description 7. Request review from maintainers ## Troubleshooting Development Issues ### Common Backend Issues **Database connection errors:** ```bash # Check PostgreSQL is running sudo systemctl status postgresql # Check connection psql -h localhost -U ktrlplane_dev -d ktrlplane_dev -c "SELECT version();" ``` **Port conflicts:** ```bash # Check what's using port 8080 lsof -i :8080 sudo netstat -tulpn | grep :8080 ``` ### Common Frontend Issues **Node/pnpm version conflicts:** ```bash # Check versions node --version pnpm --version # Use Node Version Manager if needed nvm use 18 ``` **Module resolution issues:** ```bash # Clear cache and reinstall rm -rf node_modules pnpm-lock.yaml pnpm install ``` ## VS Code Configuration Recommended VS Code settings for the project: ```json // .vscode/settings.json { "go.toolsManagement.checkForUpdates": "local", "go.useLanguageServer": true, "go.lintOnSave": "package", "go.formatTool": "goimports", "typescript.preferences.importModuleSpecifier": "relative", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll.eslint": true } } ``` Recommended extensions: * Go (Google) * TypeScript and JavaScript (Microsoft) * ES7+ React/Redux/React-Native snippets * Prettier - Code formatter * ESLint * GitLens ## Next Steps After setting up your development environment: 1. **[Read the Architecture Guide](/development/architecture)** - Understand the system design 2. **[Review Contributing Guidelines](/development/contributing)** - Learn how to contribute effectively 3. **[Explore the API](/development/api)** - Understand the API design patterns 4. **[Write Tests](/development/testing)** - Learn the testing strategy Join our developer community on Discord to get help, share ideas, and collaborate with other contributors! # Creating Resources # Creating Resources This guide walks you through the process of creating new resources in your KtrlPlane projects. KtrlPlane uses a unified wizard to make resource creation simple and consistent across different types. ## The Creation Wizard To start creating a resource: 1. Navigate to your **Project** dashboard. 2. Click the **"Add Resource"** button in the top right or the **"Create Resource"** card in the dashboard. ### Step 1: Select Resource Type Choose the type of resource you need from the catalog. * **Konnektr.Graph**: A high-performance graph database for digital twins. * **Konnektr.Flow**: A real-time event processing and routing engine. * **Konnektr.Assembler**: An AI-powered tool for generating data models. ### Step 2: Configure Details 1. **Name**: Enter a unique display name for your resource. 2. **ID**: A DNS-compliant ID will be automatically generated from your name. You can customize this if needed, but it must be unique within the project. 3. **Tier**: Select a performance tier. * **Free**: Good for development and testing. Shared infrastructure. * **Pro**: For production workloads requiring guaranteed performance. * **Enterprise**: Dedicated infrastructure with custom SLAs. ### Step 3: Billing (If Required) If you select a paid tier (Pro or Enterprise) and haven't set up billing for your project yet, you will be prompted to: 1. Enter your billing details. 2. Add a payment method via the secure Stripe portal. *Note: You only need to do this once per project.* ### Step 4: Resource Configuration Different resources require different configuration settings. * **Graphs**: configuring database names, backup retention, and scaling options. * **Flows**: configuring processing modes (streaming/batch), retention policies, and instance counts. * **Secrets**: Add key-value pairs for sensitive data. Refer to the specific product documentation for detailed configuration parameters for each resource type. ### Step 5: Creation and Deployment Once configured, click **Create Resource**. KtrlPlane will provision your dedicated infrastructure. This process typically takes 1-3 minutes. You will be redirected to the resource details page automatically. ## Next Steps After your resource is created: 1. **View Details**: Check the resource overview for status and connection endpoints. 2. **Manage Access**: Use the **Access** tab to grant permissions to other users or service accounts. 3. **Check Logs**: Use the **Logs** tab to monitor initialization and runtime events. # Resource Management Guide # Resource Management Guide This comprehensive guide covers everything you need to know about managing resources in KtrlPlane, from initial deployment to optimization and troubleshooting. ## Creating Resources For a detailed step-by-step walkthrough of the creation process, please refer to the **[Creating Resources](/guides/creating-resources)** guide. ## Secret Management KtrlPlane employs a modern, secure approach to secret management that minimizes the need for handling long-lived static credentials. ### Federated Identity For integrations with external services like Kafka or Azure Data Explorer, KtrlPlane utilizes **Federated Identity** (Workload Identity). This means you don't need to manually create or store secrets for these connections. Instead, you configure the connection details (like endpoints or cluster URIs), and authentication is handled securely and automatically via OAUTHBEARER tokens. ### Project Credentials (M2M) For programmatic access to the KtrlPlane API (e.g., for CI/CD pipelines or external scripts), you should use **Service Accounts**. 1. Navigate to your **Project Dashboard**. 2. Locate the **API Authentication** card. 3. You will see your **Client ID** and **Client Secret**. 4. Use these credentials to obtain an access token via the standard OAuth2 Client Credentials flow. Store your Client Secret securely. It is only visible to Project Admins and allows full programmatic access to your project's resources. For more details on using these credentials, see the [Service Accounts](/guides/service-accounts) guide. ## Managing Existing Resources ### Resource Dashboard Your resource dashboard provides: **Status Overview** * Current operational status * Health and performance metrics * Recent activity and events * Resource utilization **Quick Actions** * Access resource endpoints * View configuration * Update settings * Scale resource * Access logs ### Updating Resource Configuration Most settings can be updated without recreating the resource: 1. Navigate to your resource 2. Click **"Settings"** 3. Modify the configuration 4. Click **"Save Changes"** 5. Monitor the update process Some configuration changes may cause brief service interruptions. Plan updates during maintenance windows when possible. ### Scaling Resources #### Manual Scaling Adjust resource capacity based on current needs: 1. Go to resource settings 2. Find the scaling section 3. Adjust capacity limits or performance tiers 4. Apply changes #### Auto-Scaling (Future Feature) Automatic scaling based on resource metrics is planned for future releases. Currently, you can manually adjust resource configuration through the dashboard or API. ## Resource Integration ### Inter-Resource Communication Resources within the same project can communicate using internal service discovery: ```javascript // Graph to Flow integration const flowClient = new FlowClient({ endpoint: process.env.FLOW_INTERNAL_ENDPOINT, authentication: 'service_account' }); // Assembler to Graph integration const graphClient = new GraphClient({ endpoint: process.env.GRAPH_INTERNAL_ENDPOINT, authentication: 'service_account' }); ``` ### External Integrations Connect your resources to external services: #### API Integration ```javascript // Configure external API endpoint in resource settings { "external_apis": { "weather_service": { "endpoint": "https://api.weather.com/v1", "authentication": "api_key", "rate_limit": 1000 } } } ``` #### Webhook Configuration ```json { "webhooks": { "incoming": { "endpoint": "/webhooks/data-ingestion", "authentication": "hmac_sha256", "payload_validation": true }, "outgoing": { "alerts": "https://your-system.com/alerts", "events": "https://your-system.com/events" } } } ``` ## Security and Access Control ### API Key Management Each resource provides API keys for programmatic access: 1. Navigate to resource settings 2. Go to **"API Keys"** section 3. Click **"Generate New Key"** 4. Configure key permissions and expiration 5. Copy the key (it won't be shown again) ### Resource-Level Permissions Control who can access and modify resources: * **Viewer**: Read-only access to resource data and configuration * **Editor**: Can modify configuration and manage the resource * **Admin**: Full access including security settings and key management ### Network Security Configure network access controls: ```json { "network_security": { "ip_whitelist": [ "192.168.1.0/24", "10.0.0.0/8" ], "enable_private_endpoints": true, "require_tls": true, "min_tls_version": "1.2" } } ``` ## Monitoring and Observability ### Built-in Monitoring KtrlPlane provides comprehensive monitoring for all resources: **Performance Metrics** * Response time percentiles (p50, p95, p99) * Request throughput and error rates * Resource utilization (CPU, memory, storage) * Custom business metrics **Operational Metrics** * Service availability and uptime * Deployment and configuration changes * Error patterns and trends * Cost and billing information ### Custom Monitoring Add custom metrics to your resources: ```javascript // Graph resource custom metrics const metrics = { nodes_created_per_minute: nodeCreationRate, query_complexity_average: averageQueryComplexity, relationship_depth_max: maxRelationshipDepth }; await graphResource.recordMetrics(metrics); ``` ### Alerting Set up alerts for important events: 1. Go to resource monitoring 2. Click **"Create Alert"** 3. Choose alert conditions: * Performance thresholds * Error rate limits * Resource utilization * Cost thresholds 4. Configure notification channels (email, Slack, webhooks) 5. Save alert configuration ## Troubleshooting ### Common Issues and Solutions #### High Response Times **Symptoms**: Slow API responses, timeouts **Solutions**: * Scale up resource capacity * Optimize queries or processing logic * Enable caching * Check for resource bottlenecks #### Resource Unavailability **Symptoms**: Service unreachable, connection errors **Solutions**: * Check resource status in dashboard * Review recent configuration changes * Verify network connectivity * Check API key validity #### High Costs **Symptoms**: Unexpected billing increases **Solutions**: * Review resource utilization metrics * Optimize resource configuration * Implement auto-scaling policies * Consider tier adjustments ### Diagnostic Tools #### Resource Logs Access detailed logs for troubleshooting: ```bash # Using KtrlPlane CLI ktrlplane logs --resource-id res-abc123 --follow # Via API curl -H "Authorization: Bearer $API_KEY" \ https://ktrlplane.konnektr.io/v1/resources/res-abc123/logs ``` #### Health Checks Monitor resource health: ```json { "health_check": { "endpoint": "/health", "interval_seconds": 30, "timeout_seconds": 10, "healthy_threshold": 2, "unhealthy_threshold": 3 } } ``` ## Best Practices ### Configuration Management * **Use version control**: Track configuration changes * **Environment consistency**: Use similar configs across environments * **Gradual rollouts**: Test configuration changes in staging first * **Backup configurations**: Keep copies of working configurations ### Performance Optimization * **Right-sizing**: Choose appropriate resource sizes * **Caching strategies**: Implement appropriate caching * **Connection pooling**: Use connection pools for database resources * **Batch processing**: Use batch operations where possible ### Security Practices * **Rotate API keys**: Regularly rotate authentication keys * **Principle of least privilege**: Grant minimum required permissions * **Network segmentation**: Use private networks where possible * **Audit logging**: Enable comprehensive audit logs ### Cost Management * **Resource monitoring**: Regularly review resource usage * **Auto-scaling**: Use auto-scaling to optimize costs * **Cleanup unused resources**: Remove resources no longer needed * **Tier optimization**: Regularly review and optimize tier selections ## Advanced Features ### Blue-Green Deployments For critical resources, use blue-green deployment strategies: 1. Create a new resource with updated configuration 2. Test the new resource thoroughly 3. Gradually shift traffic from old to new resource 4. Remove the old resource once migration is complete ### Multi-Region Deployment Deploy resources across multiple regions for high availability: ```json { "deployment": { "strategy": "multi_region", "regions": ["us-east-1", "eu-west-1", "asia-southeast-1"], "replication": { "mode": "active_active", "consistency": "eventual" } } } ``` ### Disaster Recovery Implement disaster recovery for critical resources: ```json { "disaster_recovery": { "backup_frequency": "daily", "backup_retention": "30_days", "cross_region_backup": true, "automated_failover": { "enabled": true, "rto_minutes": 15, "rpo_minutes": 5 } } } ``` ## Next Steps Now that you understand resource management: 1. **[Explore API Integration](/api/resources)**: Learn how to integrate with your applications 2. **[Set Up Monitoring](/guides/monitoring)**: Implement comprehensive monitoring 3. **[Optimize Costs](/guides/billing)**: Learn advanced cost optimization strategies 4. **[Security Hardening](/guides/security)**: Implement enterprise security practices 🎉 You're now equipped to effectively manage resources in KtrlPlane! Remember to start simple and gradually add complexity as your needs grow. # Service Accounts (M2M) # Service Accounts for Permission Checking ## Overview Service accounts allow your backend services to authenticate with KtrlPlane and check user permissions on behalf of those users. This is useful when: * Your service has a different Auth0 audience than KtrlPlane * You need to verify user permissions without forwarding user tokens * Auth0's on-behalf-of flow isn't available for your use case ## How It Works 1. **M2M Application**: Create an Auth0 Machine-to-Machine application 2. **Client Credentials Flow**: Your service authenticates using client ID and secret 3. **Special Permission**: Grant the M2M app permission to check permissions on behalf of users 4. **API Call**: Call `/api/v1/permissions/check` with a `userId` parameter ## Setup Guide ### Step 1: Create Auth0 M2M Application 1. Go to your Auth0 Dashboard → Applications → Create Application 2. Choose "Machine to Machine Applications" 3. Name it (e.g., "My Service - KtrlPlane Integration") 4. Select the KtrlPlane API as the authorized API 5. Grant the necessary permissions (the API must be configured to allow M2M access) 6. Note the **Client ID** and **Client Secret** ### Step 2: Grant Service Account Permission The service account needs a special permission to check permissions on behalf of users. You'll need to create a role assignment at the global scope. #### Option A: Using SQL (Recommended for initial setup) ```sql -- 1. Find or create a role with the special permission INSERT INTO ktrlplane.roles (role_id, name, description, scope_type, display_order, created_at, updated_at) VALUES ( 'service-account-permission-checker', 'Service Account: Permission Checker', 'Allows service accounts to check permissions on behalf of users', 'global', 1000, NOW(), NOW() ) ON CONFLICT (role_id) DO NOTHING; -- 2. Add the check_permissions_on_behalf_of permission to the role INSERT INTO ktrlplane.role_permissions (role_id, permission_id) VALUES ('service-account-permission-checker', '00000000-0001-0000-0000-000000000006') ON CONFLICT DO NOTHING; -- 3. Assign the role to your service account (use the client ID as user_id) INSERT INTO ktrlplane.role_assignments ( assignment_id, user_id, -- This is the Auth0 client ID (the 'sub' from the M2M token) role_id, scope_type, scope_id, assigned_by, created_at, updated_at ) VALUES ( gen_random_uuid(), 'YOUR_M2M_CLIENT_ID_HERE', -- Replace with your M2M application's client ID 'service-account-permission-checker', 'global', 'global', 'system', -- Or use your admin user ID NOW(), NOW() ); ``` #### Option B: Using the API (Future Enhancement) Currently, service account role assignments must be created via SQL. In the future, an API endpoint will be available for this. ### Step 3: Authenticate Your Service Your service needs to obtain an access token using the client credentials flow: ```typescript // Example using Node.js import axios from 'axios'; async function getServiceAccountToken() { const response = await axios.post(`https://YOUR_AUTH0_DOMAIN/oauth/token`, { grant_type: 'client_credentials', client_id: process.env.M2M_CLIENT_ID, client_secret: process.env.M2M_CLIENT_SECRET, audience: process.env.KTRLPLANE_API_AUDIENCE, }); return response.data.access_token; } ``` ```go // Example using Go package main import ( "encoding/json" "fmt" "net/http" "net/url" "strings" ) type TokenResponse struct { AccessToken string `json:"access_token"` TokenType string `json:"token_type"` ExpiresIn int `json:"expires_in"` } func getServiceAccountToken(auth0Domain, clientID, clientSecret, audience string) (string, error) { data := url.Values{} data.Set("grant_type", "client_credentials") data.Set("client_id", clientID) data.Set("client_secret", clientSecret) data.Set("audience", audience) req, err := http.NewRequest("POST", fmt.Sprintf("https://%s/oauth/token", auth0Domain), strings.NewReader(data.Encode())) if err != nil { return "", err } req.Header.Set("Content-Type", "application/x-www-form-urlencoded") client := &http.Client{} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() var tokenResp TokenResponse if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil { return "", err } return tokenResp.AccessToken, nil } ``` ### Step 4: Check Permissions on Behalf of Users Now your service can check permissions for any user: ```typescript // Example using Node.js async function checkUserPermissions( userId: string, scopeType: string, scopeId: string ) { const token = await getServiceAccountToken(); const response = await axios.get( `${process.env.KTRLPLANE_API_URL}/api/v1/permissions/check`, { params: { userId: userId, // The user you're checking permissions for scopeType: scopeType, // e.g., "project", "organization", "resource" scopeId: scopeId, // The specific project/org/resource ID }, headers: { Authorization: `Bearer ${token}`, }, } ); return response.data.permissions; // Array of permission strings } // Usage example const permissions = await checkUserPermissions( 'auth0|123456789', // User's Auth0 sub claim 'project', 'my-project-id' ); if (permissions.includes('read')) { // User can read the project } ``` ```go // Example using Go func checkUserPermissions(token, userID, scopeType, scopeID string) ([]string, error) { url := fmt.Sprintf("%s/api/v1/permissions/check?userId=%s&scopeType=%s&scopeId=%s", os.Getenv("KTRLPLANE_API_URL"), url.QueryEscape(userID), url.QueryEscape(scopeType), url.QueryEscape(scopeID), ) req, err := http.NewRequest("GET", url, nil) if err != nil { return nil, err } req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", token)) client := &http.Client{} resp, err := client.Do(req) if err != nil { return nil, err } defer resp.Body.Close() var result struct { Permissions []string `json:"permissions"` } if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { return nil, err } return result.Permissions, nil } ``` ## API Reference ### Check Permissions **Endpoint:** `GET /api/v1/permissions/check` **Authentication:** Bearer token (user token or service account token) **Query Parameters:** | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------- | | `scopeType` | string | Yes | Type of scope: "organization", "project", "resource" | | `scopeId` | string | Yes | ID of the specific scope | | `userId` | string | No\* | User ID to check permissions for (M2M only) | \*Required when using service account to check another user's permissions **Response:** ```json { "user_id": "auth0|123456789", "scope_type": "project", "scope_id": "my-project-id", "permissions": [ "read", "write", "manage_access" ] } ``` **Error Responses:** * `400 Bad Request`: Missing required parameters * `401 Unauthorized`: Invalid or missing token * `403 Forbidden`: Service account lacks permission to check on behalf of users * `500 Internal Server Error`: Server-side error ## Security Considerations ### Why This Is Safe 1. **Explicit Permission Required**: Service accounts must be explicitly granted the `check_permissions_on_behalf_of` permission 2. **Global Scope Only**: This permission is only checked at the global scope, making it easy to audit 3. **Read-Only Operation**: Service accounts can only *check* permissions, not grant or modify them 4. **Audit Trail**: All permission checks are logged (if logging is enabled) ### Best Practices 1. **Limit Service Accounts**: Only create service accounts when necessary 2. **Rotate Credentials**: Regularly rotate client secrets 3. **Use Environment Variables**: Never hardcode credentials 4. **Monitor Usage**: Set up alerts for unusual permission check patterns 5. **Principle of Least Privilege**: Only grant the specific permission needed ### What Service Accounts CANNOT Do Service accounts with `check_permissions_on_behalf_of` permission: * ❌ Cannot modify user permissions or role assignments * ❌ Cannot create, update, or delete resources * ❌ Cannot impersonate users for other API calls * ❌ Cannot access user data beyond permission information * ✅ Can only read what permissions a user has on a specific scope ## Troubleshooting ### "Only service accounts can check permissions on behalf of other users" **Cause**: You're using a regular user token, not an M2M token. **Solution**: Ensure you're authenticating with client credentials flow, not a user token. ### "Service account does not have permission to check permissions on behalf of users" **Cause**: The service account hasn't been granted the `check_permissions_on_behalf_of` permission. **Solution**: Follow Step 2 in the setup guide to create the role assignment. ### How to Find Your M2M Client ID The client ID becomes the `sub` claim in the M2M token. To verify: 1. Decode your M2M token at [jwt.io](https://jwt.io) 2. Look for the `sub` claim - this is your client ID 3. Verify the `gty` claim is `"client-credentials"` Example token payload: ```json { "iss": "https://your-tenant.auth0.com/", "sub": "AbC123xyz@clients", // This is your client ID "aud": "https://api.ktrlplane.io", "gty": "client-credentials", // Identifies this as M2M token "azp": "AbC123xyz", "exp": 1234567890, "iat": 1234567890 } ``` ## Example: Integration with Konnektr.Graph Here's a real-world example of how Konnektr.Graph uses service accounts to verify user permissions: ```typescript // In Konnektr.Graph API middleware async function verifyUserCanAccessGraph(userId: string, graphResourceId: string) { // Get service account token const token = await getServiceAccountToken(); // Check if user has read permission on the graph resource const permissions = await checkUserPermissions( userId, 'resource', graphResourceId ); if (!permissions.includes('read')) { throw new UnauthorizedError('User does not have access to this graph'); } // Permission verified, proceed with graph operation return true; } ``` ## Related Documentation * [Access Control Overview](/concepts/access-control) * [RBAC API Reference](/api/rbac) * [Authentication](/api/authentication) # Installation Guide # Self-Hosting Installation Guide This guide covers how to install and deploy KtrlPlane in your own environment, whether that's on-premises, in your own cloud account, or in a private cloud. ## Overview KtrlPlane can be deployed in several ways: * **Docker Compose** (Development/Testing) * **Kubernetes** (Production - Recommended) * **Helm Chart** (Kubernetes with simplified configuration) * **Manual Installation** (Advanced users) ## Prerequisites ### System Requirements **Minimum Requirements:** * 2 CPU cores * 4 GB RAM * 20 GB storage * PostgreSQL 14+ * Docker or Kubernetes cluster **Recommended for Production:** * 4+ CPU cores * 8+ GB RAM * 100+ GB storage (depending on usage) * PostgreSQL 14+ with high availability * Kubernetes cluster with multiple nodes ### Software Dependencies * **Container Runtime**: Docker 20.10+ or containerd 1.5+ * **Database**: PostgreSQL 14+ * **Authentication**: Auth0 account (or compatible OIDC provider) * **TLS Certificates**: For HTTPS in production * **Load Balancer**: For high availability deployments ## Quick Start with Docker Compose For development or testing environments: ### Step 1: Clone Repository ```bash git clone https://github.com/konnektr-io/ktrlplane.git cd ktrlplane ``` ### Step 2: Configure Environment Create a `.env` file: ```bash # Database Configuration DB_HOST=postgres DB_PORT=5432 DB_NAME=ktrlplane_dev DB_USER=ktrlplane DB_PASSWORD=change_this_password # Auth0 Configuration AUTH_DOMAIN=your-domain.auth0.com AUTH_AUDIENCE=https://api.ktrlplane.yourdomain.com # Application Configuration API_BASE_URL=http://localhost:8080 FRONTEND_URL=http://localhost:5173 ``` ### Step 3: Start Services ```bash cd deployments/docker docker-compose up -d ``` This will start: * PostgreSQL database * KtrlPlane backend (port 8080) * KtrlPlane frontend (port 5173) ### Step 4: Run Database Migrations ```bash docker-compose exec backend /app/migrate ``` ### Step 5: Access KtrlPlane Open your browser to `http://localhost:5173` to access the KtrlPlane interface. ## Production Kubernetes Deployment For production environments, we recommend using Kubernetes: ### Step 1: Prerequisites Ensure you have: * Kubernetes cluster 1.21+ * kubectl configured * Helm 3.0+ * PostgreSQL database (managed service recommended) ### Step 2: Add Helm Repository ```bash helm repo add konnektr https://charts.konnektr.io helm repo update ``` ### Step 3: Create Configuration Create a `values.yaml` file: ```yaml # values.yaml global: domain: "ktrlplane.yourdomain.com" # Database configuration (external managed database recommended) postgresql: enabled: false # Using external database database: external: true host: "your-postgres-host.amazonaws.com" port: 5432 name: "ktrlplane_production" username: "ktrlplane" password: "your-secure-password" # Auth0 configuration auth: domain: "your-domain.auth0.com" audience: "https://api.ktrlplane.yourdomain.com" clientId: "your-auth0-client-id" # Backend configuration backend: image: repository: ghcr.io/konnektr-io/ktrlplane-backend tag: "v1.0.0" resources: requests: cpu: 500m memory: 1Gi limits: cpu: 2000m memory: 4Gi autoscaling: enabled: true minReplicas: 2 maxReplicas: 10 # Frontend configuration frontend: image: repository: ghcr.io/konnektr-io/ktrlplane-frontend tag: "v1.0.0" resources: requests: cpu: 100m memory: 256Mi limits: cpu: 500m memory: 512Mi # Ingress configuration ingress: enabled: true className: nginx annotations: cert-manager.io/cluster-issuer: letsencrypt-prod nginx.ingress.kubernetes.io/force-ssl-redirect: "true" tls: - secretName: ktrlplane-tls hosts: - ktrlplane.yourdomain.com # Security configuration securityContext: runAsNonRoot: true runAsUser: 10001 fsGroup: 10001 ``` ### Step 4: Install KtrlPlane ```bash helm install ktrlplane konnektr/ktrlplane \ --namespace ktrlplane \ --create-namespace \ --values values.yaml ``` ### Step 5: Run Database Migrations ```bash kubectl run migrate --rm -i --tty \ --image=ghcr.io/konnektr-io/ktrlplane-backend:v1.0.0 \ --restart=Never \ --env="DATABASE_URL=postgresql://user:pass@host:5432/dbname" \ -- /app/migrate ``` ### Step 6: Verify Installation ```bash # Check pod status kubectl get pods -n ktrlplane # Check ingress kubectl get ingress -n ktrlplane # Check logs kubectl logs -f deployment/ktrlplane-backend -n ktrlplane ``` ## Manual Installation For environments where Docker/Kubernetes isn't available: ### Step 1: Install Dependencies **Ubuntu/Debian:** ```bash # Install PostgreSQL sudo apt update sudo apt install postgresql postgresql-contrib # Install Go 1.21+ wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc # Install Node.js 18+ curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # Install pnpm npm install -g pnpm ``` **CentOS/RHEL:** ```bash # Install PostgreSQL sudo dnf install postgresql postgresql-server postgresql-contrib sudo postgresql-setup --initdb sudo systemctl enable --now postgresql # Install Go and Node.js (similar to above) ``` ### Step 2: Setup Database ```bash # Switch to postgres user sudo -u postgres psql # Create database and user CREATE USER ktrlplane WITH ENCRYPTED PASSWORD 'your-secure-password'; CREATE DATABASE ktrlplane_production OWNER ktrlplane; GRANT ALL PRIVILEGES ON DATABASE ktrlplane_production TO ktrlplane; \q ``` ### Step 3: Build Backend ```bash git clone https://github.com/konnektr-io/ktrlplane.git cd ktrlplane # Build backend go build -o ktrlplane-server ./cmd/server # Run migrations export DATABASE_URL="postgresql://ktrlplane:your-password@localhost/ktrlplane_production?sslmode=disable" go run ./cmd/migrate ``` ### Step 4: Build Frontend ```bash cd web pnpm install pnpm build ``` ### Step 5: Configure Systemd Services Create `/etc/systemd/system/ktrlplane-backend.service`: ```ini [Unit] Description=KtrlPlane Backend After=network.target postgresql.service [Service] Type=simple User=ktrlplane WorkingDirectory=/opt/ktrlplane ExecStart=/opt/ktrlplane/ktrlplane-server Restart=always RestartSec=10 Environment=DB_HOST=localhost Environment=DB_PORT=5432 Environment=DB_NAME=ktrlplane_production Environment=DB_USER=ktrlplane Environment=DB_PASSWORD=your-secure-password Environment=AUTH_DOMAIN=your-domain.auth0.com Environment=AUTH_AUDIENCE=https://api.ktrlplane.yourdomain.com [Install] WantedBy=multi-user.target ``` Start the service: ```bash sudo systemctl enable --now ktrlplane-backend sudo systemctl status ktrlplane-backend ``` ### Step 6: Setup Web Server Configure nginx to serve the frontend and proxy API requests: ```nginx server { listen 80; server_name ktrlplane.yourdomain.com; # Redirect to HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name ktrlplane.yourdomain.com; ssl_certificate /etc/letsencrypt/live/ktrlplane.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/ktrlplane.yourdomain.com/privkey.pem; # Frontend location / { root /opt/ktrlplane/web/dist; try_files $uri $uri/ /index.html; } # API proxy location /api { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # Health check location /health { proxy_pass http://localhost:8080; } } ``` ## Configuration ### Environment Variables | Variable | Required | Description | Default | | --------------- | -------- | ------------------- | ------- | | `DB_HOST` | Yes | PostgreSQL hostname | - | | `DB_PORT` | Yes | PostgreSQL port | 5432 | | `DB_NAME` | Yes | Database name | - | | `DB_USER` | Yes | Database username | - | | `DB_PASSWORD` | Yes | Database password | - | | `AUTH_DOMAIN` | Yes | Auth0 domain | - | | `AUTH_AUDIENCE` | Yes | Auth0 API audience | - | | `PORT` | No | Server port | 8080 | | `LOG_LEVEL` | No | Logging level | info | ### Security Configuration For production deployments: ```yaml security: # Enable HTTPS only tls: enabled: true cert_file: /etc/ssl/certs/ktrlplane.crt key_file: /etc/ssl/private/ktrlplane.key # CORS configuration cors: allowed_origins: - "https://ktrlplane.yourdomain.com" allowed_methods: - GET - POST - PUT - DELETE allowed_headers: - Authorization - Content-Type # Rate limiting rate_limit: enabled: true requests_per_minute: 100 burst_size: 20 ``` ## High Availability Setup For production environments requiring high availability: ### Database High Availability Use PostgreSQL with read replicas: ```yaml database: primary: host: "pg-primary.yourdomain.com" port: 5432 read_replicas: - host: "pg-replica1.yourdomain.com" port: 5432 - host: "pg-replica2.yourdomain.com" port: 5432 ``` ### Application High Availability Deploy multiple backend instances behind a load balancer: ```yaml backend: replicas: 3 antiAffinity: enabled: true readinessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 10 periodSeconds: 5 livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 30 periodSeconds: 10 ``` ## Monitoring and Observability ### Health Checks KtrlPlane provides health check endpoints: * `/health` - Basic health check * `/health/ready` - Readiness check (database connectivity) * `/health/live` - Liveness check ### Metrics Enable Prometheus metrics: ```yaml monitoring: metrics: enabled: true port: 9090 path: /metrics ``` ### Logging Configure structured logging: ```yaml logging: level: info format: json output: stdout ``` ## Backup and Recovery ### Database Backups Set up automated PostgreSQL backups: ```bash # Daily backup script #!/bin/bash BACKUP_DIR="/backups/ktrlplane" DATE=$(date +%Y%m%d_%H%M%S) pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME > "$BACKUP_DIR/ktrlplane_$DATE.sql" # Compress backup gzip "$BACKUP_DIR/ktrlplane_$DATE.sql" # Clean up old backups (keep 30 days) find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete ``` ### Configuration Backups Backup your configuration files: ```bash # Backup Kubernetes configs kubectl get secret,configmap -n ktrlplane -o yaml > ktrlplane-config-backup.yaml # Backup Helm values helm get values ktrlplane -n ktrlplane > values-backup.yaml ``` ## Troubleshooting Installation ### Common Issues **Database Connection Failed** ```bash # Check connectivity telnet $DB_HOST $DB_PORT # Verify credentials psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT version();" ``` **Auth0 Configuration Issues** ```bash # Verify Auth0 settings curl -H "Authorization: Bearer $JWT_TOKEN" \ https://$AUTH_DOMAIN/.well-known/jwks.json ``` **Port Conflicts** ```bash # Check what's using port 8080 sudo lsof -i :8080 sudo netstat -tulpn | grep :8080 ``` ### Getting Help If you encounter issues: 1. Check the [troubleshooting guide](/self-hosting/troubleshooting) 2. Review application logs 3. Verify all prerequisites are met 4. Check the [community forums](/support/community) ## Next Steps After successful installation: 1. **[Configure Authentication](/self-hosting/authentication)**: Set up Auth0 integration 2. **[Database Setup](/self-hosting/database)**: Optimize database configuration 3. **[Monitoring](/self-hosting/monitoring)**: Set up comprehensive monitoring 4. **[Security Hardening](/self-hosting/security)**: Implement security best practices 🎉 Congratulations! You have successfully installed KtrlPlane. You can now access the web interface and start creating organizations, projects, and resources. # Frequently Asked Questions # Frequently Asked Questions Find answers to common questions about KtrlPlane, the Control Plane for the Konnektr Platform. ## General Questions ### What is KtrlPlane? KtrlPlane is the centralized Control Plane for the Konnektr Platform. It manages organizations, projects, resources, billing, and access control for all Konnektr products (Graph, Flow, Assembler, and Compass). ### How does KtrlPlane relate to other Konnektr products? KtrlPlane serves as the management layer for the entire Konnektr ecosystem: * **KtrlPlane**: Control Plane - manages users, projects, billing, and deployments * **Konnektr.Graph**: Graph database and API layer for digital twin data * **Konnektr.Flow**: Real-time data and event processing * **Konnektr.Assembler**: AI-powered digital twin builder * **Konnektr.Compass**: Navigation and discovery tools (coming soon) ### Is KtrlPlane free to use? KtrlPlane itself is free - you only pay for the resources you deploy. Each resource type (Graph, Flow, Assembler) offers free tiers perfect for development and small projects. ## Account and Authentication ### How do I create an account? Simply visit the KtrlPlane web interface and click "Sign Up". You'll need to provide an email address and create a password. Email verification is required before you can start using the platform. ### Can I use single sign-on (SSO)? Yes, KtrlPlane supports Auth0-based authentication, which can be configured for various SSO providers including Google, Microsoft, SAML, and more. ### How do I reset my password? Click "Forgot Password" on the login page and enter your email address. You'll receive a password reset link via email. ### Can I change my email address? Currently, email address changes must be done through your Auth0 profile. Contact support if you need assistance with this. ## Organizations and Projects ### What's the difference between organizations and projects? * **Organizations**: Top-level containers representing your company or team. Handle billing, team management, and company-wide policies. * **Projects**: Workspaces within organizations where you deploy and manage resources. Each project can have its own team members and access controls. ### How many organizations can I create? There's no limit on the number of organizations you can create. Most users start with one organization and create additional ones only when needed for business separation. ### Can I transfer projects between organizations? Currently, projects cannot be transferred between organizations. However, you can create a new project in the target organization and migrate your resources individually. ### How do I invite team members? Go to your organization or project settings, click "Access Control", then "Invite User". Enter their email address and select the appropriate role. They'll receive an invitation email with instructions to join. ## Resources and Billing ### What resource types are available? KtrlPlane supports four main resource types: 1. **Konnektr.Graph**: Graph database for connected data and digital twins 2. **Konnektr.Flow**: Real-time event and data processing 3. **Konnektr.Assembler**: AI-powered digital twin model builder 4. **Konnektr.Compass**: Navigation and discovery (coming soon) ### How is billing calculated? Billing is resource-based with three components: * **Base tier cost**: Monthly fee for your selected tier (Free, Pro, Enterprise) * **Usage charges**: Additional costs for usage beyond tier limits * **Storage costs**: Data storage charges for persistent data ### Can I change resource tiers after creation? Yes, you can upgrade or downgrade resource tiers at any time. Changes take effect immediately, and billing is prorated to reflect the change. ### What happens if I exceed my tier limits? * **Free tier**: Your resource may be temporarily throttled or paused * **Paid tiers**: You'll be charged for additional usage beyond your tier limits * **All tiers**: You'll receive email notifications when approaching limits ### How do I set up billing alerts? Go to your organization or project billing settings and configure alert thresholds. You can set alerts for: * Monthly spending limits * Usage approaching tier limits * Unexpected billing increases ## Technical Questions ### What are the system requirements for KtrlPlane? KtrlPlane is a web-based platform with no local installation required. You just need: * A modern web browser (Chrome, Firefox, Safari, Edge) * Internet connection * JavaScript enabled ### Can I use KtrlPlane APIs programmatically? Yes! KtrlPlane provides comprehensive REST APIs for all functionality. You can: * Manage organizations, projects, and resources * Control access and permissions * Monitor usage and billing * Automate deployments API documentation is available at `/api/` in this documentation. ### Is there a command-line interface (CLI)? Yes, we provide a CLI tool for KtrlPlane that allows you to manage resources from the command line. Install it with: ```bash npm install -g @konnektr/ktrlplane-cli # or pip install ktrlplane-cli ``` ### How do I integrate KtrlPlane with my CI/CD pipeline? Use the KtrlPlane API or CLI in your deployment scripts: ```yaml # GitHub Actions example - name: Deploy to KtrlPlane run: | ktrlplane resource create \ --project $PROJECT_ID \ --type Konnektr.Graph \ --config @graph-config.json env: KTRLPLANE_API_KEY: ${{ secrets.KTRLPLANE_API_KEY }} ``` ## Troubleshooting ### I can't log in to KtrlPlane Common solutions: 1. Check your email address and password 2. Try resetting your password 3. Clear your browser cache and cookies 4. Try a different browser or incognito mode 5. Check if you're using the correct login URL ### My resource deployment failed Check the resource status page for error details. Common causes: * Invalid configuration settings * Insufficient tier limits * Network connectivity issues * Billing account problems ### I'm getting API authentication errors Verify that: * Your API key is valid and not expired * You're using the correct API endpoint * Your account has the required permissions * The API key is properly included in the Authorization header ### How do I report a bug or request a feature? You can: 1. Create an issue on our [GitHub repository](https://github.com/konnektr-io/ktrlplane) 2. Contact support through the platform 3. Join our community forums 4. Reach out on Discord ## Data and Privacy ### Where is my data stored? Data is stored in secure, SOC 2 compliant data centers. The specific location depends on your chosen region during resource creation. ### Is my data encrypted? Yes, all data is encrypted: * **In transit**: All API calls and web traffic use TLS 1.2+ * **At rest**: All stored data is encrypted using AES-256 * **In processing**: Memory encryption for sensitive operations ### Can I export my data? Yes, you can export your data at any time: * **Configuration data**: Use the API to export project and resource configurations * **Resource data**: Each resource type provides data export capabilities * **Billing data**: Download invoices and usage reports from billing settings ### What is your data retention policy? * **Active accounts**: Data is retained as long as your account is active * **Deleted resources**: Data is permanently deleted within 30 days * **Closed accounts**: Data is retained for 90 days then permanently deleted * **Billing data**: Retained for 7 years for compliance purposes ## Limits and Quotas ### Are there any usage limits? Yes, limits vary by tier and resource type: **Organization limits:** * Free: 3 projects per organization * Pro: 50 projects per organization * Enterprise: Unlimited projects **Resource limits:** * Vary by resource type and tier * Detailed in each resource type's documentation * Can be increased by upgrading tiers ### How do I request limit increases? For limits beyond the Enterprise tier, contact our sales team. We can provide custom quotas for large deployments. ## Support and Community ### How do I get help? Multiple support options are available: 1. **Documentation**: Comprehensive guides and API references 2. **Community Forums**: Get help from other users 3. **Discord**: Real-time chat with the community 4. **Email Support**: For Pro and Enterprise customers 5. **Dedicated Support**: For Enterprise customers ### What are your support hours? * **Community Support**: 24/7 via forums and Discord * **Email Support**: Business hours (9 AM - 6 PM PST, Monday-Friday) * **Enterprise Support**: 24/7 for critical issues ### Do you offer training or consulting? Yes, we offer: * **Documentation and tutorials**: Self-service learning * **Webinars**: Regular training sessions * **Professional services**: Custom training and consulting (Enterprise) * **Partner program**: Certified implementation partners Still have questions? Check our [community forums](/support/community) or [contact support](/support/contact). # boolean # boolean Converts the input to a boolean. **Type:** transform ## Aliases `toBoolean`, `bool`, `boolean`, `toBool` ## Parameters * **input** (unknown): The input to convert to a boolean. ## Returns **Type:** `boolean` The boolean value, or undefined for ambiguous string values. ## Examples ```javascript toBoolean("true") // true ``` ```javascript "false"|toBoolean // false ``` ```javascript toBoolean(1) // true ``` # formatBase # formatBase Formats a number as a string in the specified base. **Type:** transform ## Parameters * **input** (unknown): The input number to format. * **base** (number): The numeric base to convert to (2-36). ## Returns **Type:** `string` The number formatted in the specified base, or empty string if input cannot be converted to a number. ## Examples ```javascript formatBase(255, 16) // "ff" ``` ```javascript (10)|formatBase(2) // "1010" ``` ```javascript formatBase(64, 8) // "100" ``` # formatInteger # formatInteger Formats a number as an integer with zero padding. **Type:** transform ## Parameters * **input** (unknown): The input number to format. * **format** (string): The format string indicating the minimum number of digits. ## Returns **Type:** `string` The zero-padded integer string, or empty string if input cannot be converted to a number. ## Examples ```javascript formatInteger(42, "000") // "042" ``` ```javascript (7)|formatInteger("0000") // "0007" ``` ```javascript formatInteger(123, "00") // "123" ``` # formatNumber # formatNumber Formats a number to a decimal representation as specified by the format string. **Type:** transform ## Parameters * **input** (unknown): The input number to format. * **format** (string): The format string specifying decimal places and grouping. ## Returns **Type:** `string` The formatted number string, or empty string if input cannot be converted to a number. ## Examples ```javascript formatNumber(1234.567, "#,##0.00") // "1,234.57" ``` ```javascript (1000)|formatNumber("0.00") // "1000.00" ``` ```javascript formatNumber(42, "#,###") // "42" ``` # Conversion # Conversion Convert between different data types ## Functions * [`boolean`](./conversion/boolean): Converts the input to a boolean. * [`formatBase`](./conversion/formatBase): Formats a number as a string in the specified base. * [`formatInteger`](./conversion/formatInteger): Formats a number as an integer with zero padding. * [`formatNumber`](./conversion/formatNumber): Formats a number to a decimal representation as specified by the format string. * [`json`](./conversion/json): Parses the string and returns a JSON object. * [`number`](./conversion/number): Converts the input to a number. * [`parseInteger`](./conversion/parseInteger): Parses a string and returns an integer. * [`string`](./conversion/string): Casts the input to a string. ## Transforms * [`boolean`](./conversion/boolean): Converts the input to a boolean. * [`formatBase`](./conversion/formatBase): Formats a number as a string in the specified base. * [`formatInteger`](./conversion/formatInteger): Formats a number as an integer with zero padding. * [`formatNumber`](./conversion/formatNumber): Formats a number to a decimal representation as specified by the format string. * [`json`](./conversion/json): Parses the string and returns a JSON object. * [`number`](./conversion/number): Converts the input to a number. * [`parseInteger`](./conversion/parseInteger): Parses a string and returns an integer. * [`string`](./conversion/string): Casts the input to a string. # json # json Parses the string and returns a JSON object. **Type:** transform ## Aliases `toJson`, `parseJson` ## Parameters * **input** (string): The JSON string to parse. ## Returns **Type:** `any` The parsed JSON object or value. ## Examples ```javascript toJson('{"key": "value"}') // { key: "value" } ``` ```javascript '{"name": "John", "age": 30}'|toJson // { name: "John", age: 30 } ``` # number # number Converts the input to a number. **Type:** transform ## Aliases `toNumber`, `parseFloat`, `number`, `float`, `toFloat` ## Parameters * **input** (unknown): The input to convert to a number. ## Returns **Type:** `number` The numeric value, or NaN if conversion fails. ## Examples ```javascript toNumber("123") // 123 ``` ```javascript "45.67"|toNumber // 45.67 ``` ```javascript toNumber("abc") // NaN ``` # parseInteger # parseInteger Parses a string and returns an integer. **Type:** transform ## Aliases `parseInt`, `toInt`, `integer` ## Parameters * **input** (unknown): The input to parse as an integer. ## Returns **Type:** `number` The integer value, or NaN if parsing fails. ## Examples ```javascript parseInteger("123") // 123 ``` ```javascript "45.67"|parseInteger // 45 ``` ```javascript parseInteger(123.89) // 123 ``` # string # string Casts the input to a string. **Type:** transform ## Aliases `toString`, `string` ## Parameters * **input** (unknown): The input can be any type. * **prettify** (boolean): If true, the output will be pretty-printed. ## Returns **Type:** `string` The input converted to a JSON string representation. ## Examples ```javascript string(123) // "123" ``` ```javascript 123|string // "123" ``` # all # all Checks whether the provided array has all elements that match the specified expression. **Type:** transform ## Aliases `arrayEvery`, `every`, `all` ## Parameters * **input** (array): The input array to test. * **expression** (string): The JEXL expression to test against each element (supports value, index and array as context). ## Returns **Type:** `boolean` True if all elements match the expression, false otherwise or if input is not an array. ## Examples ```javascript every([2, 4, 6], "value % 2 == 0") // true ``` ```javascript [{age: 25}, {age: 35}]|every("value.age > 20") // true ``` ```javascript every([1, 2, 3], "value > 2") // false ``` # any # any Checks whether the provided array has any elements that match the specified expression. **Type:** transform ## Aliases `arrayAny`, `some`, `any` ## Parameters * **input** (array): The input array to test. * **expression** (string): The JEXL expression to test against each element (supports value, index and array as context). ## Returns **Type:** `boolean` True if any element matches the expression, false otherwise or if input is not an array. ## Examples ```javascript any([1, 2, 3], "value > 2") // true ``` ```javascript [{age: 25}, {age: 35}]|any("value.age > 30") // true ``` ```javascript any([1, 2, 3], "value > 5") // false ``` # append # append Appends elements to an array. **Type:** transform ## Aliases `arrayAppend`, `concat`, `append` ## Parameters * **input** (array): The input values to append to an array. ## Returns **Type:** `array` A new array with all inputs flattened and appended, or empty array if no valid input. ## Examples ```javascript append([1, 2], 3) // [1, 2, 3] ``` ```javascript [1, 2]|append(3, 4) // [1, 2, 3, 4] ``` ```javascript append([], 1, 2, 3) // [1, 2, 3] ``` # distinct # distinct Returns a new array with duplicate elements removed. **Type:** transform ## Aliases `arrayDistinct`, `distinct` ## Parameters * **input** (array): The input array to remove duplicates from. ## Returns **Type:** `array` A new array with duplicates removed, or empty array if input is not an array. ## Examples ```javascript distinct([1, 2, 2, 3, 1]) // [1, 2, 3] ``` ```javascript [1, 2, 2, 3]|distinct // [1, 2, 3] ``` ```javascript distinct(["a", "b", "a", "c"]) // ["a", "b", "c"] ``` # filter # filter Returns a new array with the elements of the input array that match the specified expression. **Type:** transform ## Aliases `arrayFilter`, `filter` ## Parameters * **input** (array): The input array to filter. * **expression** (string): The JEXL expression to test against each element (supports value, index and array as context). ## Returns **Type:** `array` A new array containing only elements that match the expression, or empty array if input is not an array. ## Examples ```javascript filter([1, 2, 3, 4], "value > 2") // [3, 4] ``` ```javascript [{age: 25}, {age: 35}]|filter("value.age > 30") // [{age: 35}] ``` ```javascript filter([1, 2, 3, 4], "value % 2 == 0") // [2, 4] ``` # find # find Finds the first element in an array that matches the specified expression. **Type:** transform ## Aliases `arrayFind`, `find` ## Parameters * **input** (array): The input array to search. * **expression** (string): The JEXL expression to test against each element (supports value, index and array as context). ## Returns **Type:** `unknown` The first element that matches the expression, or undefined if no match found or input is not an array. ## Examples ```javascript find([1, 2, 3, 4], "value > 2") // 3 ``` ```javascript [{name: "John"}, {name: "Jane"}]|find("value.name == 'Jane'") // {name: "Jane"} ``` ```javascript find([1, 2, 3], "value > 5") // undefined ``` # findIndex # findIndex Finds the index of the first element in the input array that satisfies the given Jexl expression. **Type:** transform ## Aliases `arrayFindIndex`, `findIndex` ## Parameters * **input** (array): The array to search through. * **expression** (string): A Jexl expression string to evaluate for each element. The expression has access to ## Returns **Type:** `number` The index of the first matching element, or ## Examples ```javascript [1, 2, 3, 4]|findIndex('value > 2'); // returns 2 ``` # Array # Array Array operations and transformations ## Functions * [`all`](./array/all): Checks whether the provided array has all elements that match the specified expression. * [`any`](./array/any): Checks whether the provided array has any elements that match the specified expression. * [`append`](./array/append): Appends elements to an array. * [`distinct`](./array/distinct): Returns a new array with duplicate elements removed. * [`filter`](./array/filter): Returns a new array with the elements of the input array that match the specified expression. * [`find`](./array/find): Finds the first element in an array that matches the specified expression. * [`findIndex`](./array/findIndex): Finds the index of the first element in the input array that satisfies the given Jexl expression. * [`join`](./array/join): Joins elements of an array into a string. * [`keys`](./array/keys): Returns the keys of an object as an array. * [`map`](./array/map): Returns an array containing the results of applying the expression parameter to each value in the array parameter. * [`mapField`](./array/mapField): Returns a new array with elements transformed by extracting a specific field. * [`range`](./array/range): Returns a sub-array from start index to end index. * [`reduce`](./array/reduce): Returns an aggregated value derived from applying the function parameter successively to each value in array in combination with the result of the previous application of the function. * [`reverse`](./array/reverse): Reverses the elements of an array. * [`shuffle`](./array/shuffle): Shuffles the elements of an array randomly. * [`sort`](./array/sort): Sorts the elements of an array. * [`toObject`](./array/toObject): Creates a new object based on key-value pairs or string keys. ## Transforms * [`all`](./array/all): Checks whether the provided array has all elements that match the specified expression. * [`any`](./array/any): Checks whether the provided array has any elements that match the specified expression. * [`append`](./array/append): Appends elements to an array. * [`distinct`](./array/distinct): Returns a new array with duplicate elements removed. * [`filter`](./array/filter): Returns a new array with the elements of the input array that match the specified expression. * [`find`](./array/find): Finds the first element in an array that matches the specified expression. * [`findIndex`](./array/findIndex): Finds the index of the first element in the input array that satisfies the given Jexl expression. * [`join`](./array/join): Joins elements of an array into a string. * [`keys`](./array/keys): Returns the keys of an object as an array. * [`map`](./array/map): Returns an array containing the results of applying the expression parameter to each value in the array parameter. * [`mapField`](./array/mapField): Returns a new array with elements transformed by extracting a specific field. * [`range`](./array/range): Returns a sub-array from start index to end index. * [`reduce`](./array/reduce): Returns an aggregated value derived from applying the function parameter successively to each value in array in combination with the result of the previous application of the function. * [`reverse`](./array/reverse): Reverses the elements of an array. * [`shuffle`](./array/shuffle): Shuffles the elements of an array randomly. * [`sort`](./array/sort): Sorts the elements of an array. * [`toObject`](./array/toObject): Creates a new object based on key-value pairs or string keys. # join # join Joins elements of an array into a string. **Type:** transform ## Aliases `arrayJoin`, `join` ## Parameters * **input** (unknown): The input array to join. * **separator** (string?): The separator string to use between elements. Defaults to comma. ## Returns **Type:** `string` The joined string, or undefined if input is not an array. ## Examples ```javascript arrayJoin(["foo", "bar", "baz"], ",") // "foo,bar,baz" ``` ```javascript ["one", "two", "three"]|arrayJoin("-") // "one-two-three" ``` ```javascript arrayJoin([1, 2, 3]) // "1,2,3" ``` # keys # keys Returns the keys of an object as an array. **Type:** transform ## Aliases `objectKeys`, `keys` ## Parameters * **input** (unknown): The input object to get keys from. ## Returns **Type:** `array` An array of object keys, or undefined if input is not an object. ## Examples ```javascript keys({name: "John", age: 30}) // ["name", "age"] ``` ```javascript {a: 1, b: 2}|keys // ["a", "b"] ``` ```javascript keys({}) // [] ``` # map # map Returns an array containing the results of applying the expression parameter to each value in the array parameter. **Type:** transform ## Aliases `arrayMap`, `map` ## Parameters * **input** (array): The input array to transform. * **expression** (string): The JEXL expression to apply to each element. ## Returns **Type:** `array` A new array with transformed elements, or undefined if input is not an array. ## Examples ```javascript map([1, 2, 3], "value * 2") // [2, 4, 6] ``` ```javascript [{name: "John"}, {name: "Jane"}]|map("value.name") // ["John", "Jane"] ``` ```javascript map([1, 2, 3], "value + index") // [1, 3, 5] ``` # mapField # mapField Returns a new array with elements transformed by extracting a specific field. **Type:** transform ## Parameters * **input** (array): The input array of objects to extract fields from. * **field** (string): The field name to extract from each object. ## Returns **Type:** `array` A new array with extracted field values, or empty array if input is not an array. ## Examples ```javascript mapField([{name: "John"}, {name: "Jane"}], "name") // ["John", "Jane"] ``` ```javascript [{age: 30}, {age: 25}]|mapField("age") // [30, 25] ``` ```javascript mapField([{x: 1, y: 2}, {x: 3, y: 4}], "x") // [1, 3] ``` # range # range Returns a sub-array from start index to end index. **Type:** transform ## Aliases `arrayRange`, `range` ## Parameters * **array** (array): The input array. * **start** (number): The starting index (inclusive). * **end** (number?): The ending index (exclusive). If not provided, slices to the end of the array. ## Returns **Type:** `array` The sub-array from start to end, or empty array if input is not an array. ## Examples ```javascript range([1, 2, 3, 4, 5], 1, 4) // [2, 3, 4] ``` ```javascript [10, 20, 30, 40]|range(0, 2) // [10, 20] ``` ```javascript range(["a", "b", "c", "d"], 2) // ["c", "d"] ``` # reduce # reduce Returns an aggregated value derived from applying the function parameter successively to each value in array in combination with the result of the previous application of the function. **Type:** transform ## Aliases `arrayReduce`, `reduce` ## Parameters * **input** (array): The input array to reduce. * **expression** (string): The JEXL expression to apply for each reduction step. * **initialValue** (unknown): The initial value for the accumulator. ## Returns **Type:** `unknown` The final accumulated value, or undefined if input is not an array. ## Examples ```javascript reduce([1, 2, 3, 4], "accumulator + value", 0) // 10 ``` ```javascript [1, 2, 3]|reduce("accumulator * value", 1) // 6 ``` ```javascript reduce(["a", "b", "c"], "accumulator + value", "") // "abc" ``` # reverse # reverse Reverses the elements of an array. **Type:** transform ## Aliases `arrayReverse`, `reverse` ## Parameters * **input** (array): The input values to reverse. ## Returns **Type:** `array` A new array with elements in reverse order, or empty array if no valid input. ## Examples ```javascript reverse([1, 2, 3]) // [3, 2, 1] ``` ```javascript [1, 2, 3]|reverse // [3, 2, 1] ``` ```javascript reverse(["a", "b", "c"]) // ["c", "b", "a"] ``` # shuffle # shuffle Shuffles the elements of an array randomly. **Type:** transform ## Aliases `arrayShuffle`, `shuffle` ## Parameters * **input** (array): The input array to shuffle. ## Returns **Type:** `array` The same array with elements randomly shuffled, or empty array if input is not an array. ## Examples ```javascript shuffle([1, 2, 3]) // [2, 1, 3] (random order) ``` ```javascript [1, 2, 3]|shuffle // [3, 1, 2] (random order) ``` ```javascript shuffle(["a", "b", "c"]) // ["c", "a", "b"] (random order) ``` # sort # sort Sorts the elements of an array. **Type:** transform ## Aliases `arraySort`, `order`, `sort` ## Parameters * **input** (array): The input array to sort. * **expression** (string?): Optional JEXL expression to determine sort value for objects. * **descending** (boolean?): Optional flag to sort in descending order. ## Returns **Type:** `array` A new sorted array, or empty array if input is not an array. ## Examples ```javascript sort([3, 1, 2]) // [1, 2, 3] ``` ```javascript [3, 1, 2]|sort // [1, 2, 3] ``` ```javascript sort([{age: 30}, {age: 20}], "age") // [{age: 20}, {age: 30}] ``` # toObject # toObject Creates a new object based on key-value pairs or string keys. **Type:** transform ## Aliases `arrayToObject`, `fromEntries`, `toObject` ## Parameters * **input** (unknown): The input string key or array of key-value pairs. * **val** (unknown?): Optional default value for string keys or when array elements are strings. ## Returns **Type:** `any` A new object created from the input, or empty object if input is invalid. ## Examples ```javascript toObject([["name", "John"], ["age", 30]]) // {name: "John", age: 30} ``` ```javascript toObject("name", "John") // {name: "John"} ``` ```javascript toObject(["key1", "key2"], "defaultValue") // {key1: "defaultValue", key2: "defaultValue"} ``` # base64Decode # base64Decode Decodes a Base64 encoded string. **Type:** transform ## Parameters * **input** (unknown): The Base64 encoded string to decode. ## Returns **Type:** `string` The decoded string, or empty string if input is not a string. ## Examples ```javascript base64Decode("aGVsbG8=") // "hello" ``` ```javascript "aGVsbG8gd29ybGQ="|base64Decode // "hello world" ``` ```javascript base64Decode("dGVzdA==") // "test" ``` # base64Encode # base64Encode Encodes a string to Base64. **Type:** transform ## Parameters * **input** (unknown): The input string to encode. ## Returns **Type:** `string` The Base64 encoded string, or empty string if input is not a string or encoding fails. ## Examples ```javascript base64Encode("hello") // "aGVsbG8=" ``` ```javascript "hello world"|base64Encode // "aGVsbG8gd29ybGQ=" ``` ```javascript base64Encode("test") // "dGVzdA==" ``` # formUrlEncoded # formUrlEncoded Encodes a string or object to URI component format. **Type:** transform ## Parameters * **input** (unknown): The input string or object to encode. ## Returns **Type:** `string` The URL encoded string, or empty string if input is not a string or object. ## Examples ```javascript formUrlEncoded("hello world") // "hello%20world" ``` ```javascript formUrlEncoded({name: "John", age: 30}) // "name=John&age=30" ``` ```javascript "hello & world"|formUrlEncoded // "hello%20%26%20world" ``` # Encoding # Encoding Data encoding and formatting utilities ## Functions * [`base64Decode`](./encoding/base64Decode): Decodes a Base64 encoded string. * [`base64Encode`](./encoding/base64Encode): Encodes a string to Base64. * [`formUrlEncoded`](./encoding/formUrlEncoded): Encodes a string or object to URI component format. ## Transforms * [`base64Decode`](./encoding/base64Decode): Decodes a Base64 encoded string. * [`base64Encode`](./encoding/base64Encode): Encodes a string to Base64. * [`formUrlEncoded`](./encoding/formUrlEncoded): Encodes a string or object to URI component format. # entries # entries Returns an array of key-value pairs from the input object. **Type:** transform ## Aliases `objectEntries`, `entries` ## Parameters * **input** (unknown): The input object to get entries from. ## Returns **Type:** `array` An array of \[key, value] pairs, or undefined if input is not an object. ## Examples ```javascript entries({name: "John", age: 30}) // [["name", "John"], ["age", 30]] ``` ```javascript {a: 1, b: 2}|entries // [["a", 1], ["b", 2]] ``` ```javascript entries({}) // [] ``` # Object # Object Object manipulation and inspection ## Functions * [`entries`](./object/entries): Returns an array of key-value pairs from the input object. * [`merge`](./object/merge): Returns a new object with the properties of the input objects merged together. * [`values`](./object/values): Returns the values of an object as an array. ## Transforms * [`entries`](./object/entries): Returns an array of key-value pairs from the input object. * [`merge`](./object/merge): Returns a new object with the properties of the input objects merged together. * [`values`](./object/values): Returns the values of an object as an array. # merge # merge Returns a new object with the properties of the input objects merged together. **Type:** transform ## Aliases `objectMerge`, `merge` ## Parameters * **args** (array): The input objects to merge. ## Returns **Type:** `Record` A new object with all properties merged together. ## Examples ```javascript merge({a: 1}, {b: 2}) // {a: 1, b: 2} ``` ```javascript {a: 1}|merge({b: 2}, {c: 3}) // {a: 1, b: 2, c: 3} ``` ```javascript merge({a: 1}, {a: 2}) // {a: 2} (later values override) ``` # values # values Returns the values of an object as an array. **Type:** transform ## Aliases `objectValues`, `values` ## Parameters * **input** (unknown): The input object to get values from. ## Returns **Type:** `array` An array of object values, or undefined if input is not an object. ## Examples ```javascript values({name: "John", age: 30}) // ["John", 30] ``` ```javascript {a: 1, b: 2}|values // [1, 2] ``` ```javascript values({}) // [] ``` # abs # abs Returns the absolute value of a number. **Type:** transform ## Aliases `absoluteValue`, `abs` ## Parameters * **input** (unknown): The input number to get the absolute value of. ## Returns **Type:** `number` The absolute value, or NaN if input cannot be converted to a number. ## Examples ```javascript absoluteValue(-5) // 5 ``` ```javascript (-10)|absoluteValue // 10 ``` ```javascript absoluteValue(3.14) // 3.14 ``` # average # average Calculates the average of an array of numbers. **Type:** transform ## Aliases `avg` ## Parameters * **input** (array): The input array of numbers or individual number arguments. ## Returns **Type:** `number` The average value, or NaN if input is not an array. ## Examples ```javascript average([1, 2, 3, 4]) // 2.5 ``` ```javascript [10, 20, 30]|average // 20 ``` ```javascript average(1, 2, 3, 4) // 2.5 ``` # ceil # ceil Rounds a number up to the nearest integer. **Type:** transform ## Parameters * **input** (unknown): The input number to round up. ## Returns **Type:** `number` The rounded up integer, or NaN if input cannot be converted to a number. ## Examples ```javascript ceil(3.2) // 4 ``` ```javascript (3.14)|ceil // 4 ``` ```javascript ceil(-2.8) // -2 ``` # floor # floor Rounds a number down to the nearest integer. **Type:** transform ## Parameters * **input** (unknown): The input number to round down. ## Returns **Type:** `number` The rounded down integer, or NaN if input cannot be converted to a number. ## Examples ```javascript floor(3.7) // 3 ``` ```javascript (3.14)|floor // 3 ``` ```javascript floor(-2.8) // -3 ``` # Math # Math Mathematical operations and calculations ## Functions * [`abs`](./math/abs): Returns the absolute value of a number. * [`average`](./math/average): Calculates the average of an array of numbers. * [`ceil`](./math/ceil): Rounds a number up to the nearest integer. * [`floor`](./math/floor): Rounds a number down to the nearest integer. * [`max`](./math/max): Finds the maximum value in an array of numbers. * [`min`](./math/min): Finds the minimum value in an array of numbers. * [`power`](./math/power): Returns the value of a number raised to a power. * [`random`](./math/random): Generates a random number between 0 (inclusive) and 1 (exclusive). * [`round`](./math/round): Rounds a number to the nearest integer or to specified decimal places. * [`sqrt`](./math/sqrt): Returns the square root of a number. * [`sum`](./math/sum): Calculates the sum of an array of numbers. ## Transforms * [`abs`](./math/abs): Returns the absolute value of a number. * [`average`](./math/average): Calculates the average of an array of numbers. * [`ceil`](./math/ceil): Rounds a number up to the nearest integer. * [`floor`](./math/floor): Rounds a number down to the nearest integer. * [`max`](./math/max): Finds the maximum value in an array of numbers. * [`min`](./math/min): Finds the minimum value in an array of numbers. * [`power`](./math/power): Returns the value of a number raised to a power. * [`round`](./math/round): Rounds a number to the nearest integer or to specified decimal places. * [`sqrt`](./math/sqrt): Returns the square root of a number. * [`sum`](./math/sum): Calculates the sum of an array of numbers. # max # max Finds the maximum value in an array of numbers. **Type:** transform ## Parameters * **input** (array): The input array of numbers or individual number arguments. ## Returns **Type:** `number` The maximum value, or NaN if input is not an array. ## Examples ```javascript max([1, 5, 3, 2]) // 5 ``` ```javascript [10, 20, 15]|max // 20 ``` ```javascript max(1, 5, 3, 2) // 5 ``` # min # min Finds the minimum value in an array of numbers. **Type:** transform ## Parameters * **input** (array): The input array of numbers or individual number arguments. ## Returns **Type:** `number` The minimum value, or NaN if input is not an array. ## Examples ```javascript min([1, 5, 3, 2]) // 1 ``` ```javascript [10, 20, 15]|min // 10 ``` ```javascript min(1, 5, 3, 2) // 1 ``` # power # power Returns the value of a number raised to a power. **Type:** transform ## Parameters * **input** (unknown): The base number. * **exponent** (number?): The exponent to raise the base to. Defaults to 2. ## Returns **Type:** `number` The result of base raised to the exponent, or NaN if input cannot be converted to a number. ## Examples ```javascript power(2, 3) // 8 ``` ```javascript (2)|power(4) // 16 ``` ```javascript power(9) // 81 (defaults to power of 2) ``` # random # random Generates a random number between 0 (inclusive) and 1 (exclusive). **Type:** function ## Aliases `randomNumber` ## Returns **Type:** `number` A random floating-point number between 0 and 1. ## Examples ```javascript randomNumber() // 0.123456789 (example output) ``` ```javascript randomNumber() // 0.987654321 (different each time) ``` # round # round Rounds a number to the nearest integer or to specified decimal places. **Type:** transform ## Parameters * **input** (unknown): The input number to round. * **decimals** (number?): Optional number of decimal places to round to. ## Returns **Type:** `number` The rounded number, or NaN if input cannot be converted to a number. ## Examples ```javascript round(3.7) // 4 ``` ```javascript round(3.14159, 2) // 3.14 ``` ```javascript (2.567)|round // 3 ``` # sqrt # sqrt Returns the square root of a number. **Type:** transform ## Parameters * **input** (unknown): The input number to get the square root of. ## Returns **Type:** `number` The square root of the input, or NaN if input cannot be converted to a number. ## Examples ```javascript sqrt(16) // 4 ``` ```javascript (25)|sqrt // 5 ``` ```javascript sqrt(2) // 1.4142135623730951 ``` # sum # sum Calculates the sum of an array of numbers. **Type:** transform ## Parameters * **input** (array): The input array of numbers or individual number arguments. ## Returns **Type:** `number` The sum of all numbers, or NaN if input is not an array. ## Examples ```javascript sum([1, 2, 3, 4]) // 10 ``` ```javascript [1.5, 2.5, 3.0]|sum // 7 ``` ```javascript sum(1, 2, 3, 4) // 10 ``` # convertTimeZone # convertTimeZone Converts an ISO datetime string to a target timezone, handling daylight savings, and returns an ISO string with the correct offset. **Type:** transform ## Parameters * **input** (unknown): ISO datetime string * **targetTimeZone** (unknown): Target timezone (IANA or Windows ID or fixed offset) ## Returns **Type:** `string` ISO datetime string with correct offset ## Examples ```javascript convertTimeZone('2025-06-26T12:00:00Z', 'Europe/Amsterdam') // 2025-06-26T14:00:00.0000000+02:00 ``` ```javascript '2025-06-26T12:00:00Z'|convertTimeZone('Pacific Standard Time') // '2025-06-26T05:00:00.0000000-07:00' ``` # dateTimeAdd # dateTimeAdd Adds a time range to a date and time in the ISO 8601 format. **Type:** transform ## Parameters * **input** (string): The input date and time string in ISO 8601 format. * **unit** (string): The time unit to add ("day", "hour", "minute", "second", "month", "year", etc.). * **value** (number): The amount to add (can be negative to subtract). ## Returns **Type:** `string` The new date and time as an ISO 8601 string. ## Examples ```javascript dateTimeAdd("2023-12-25T10:30:00.000Z", "day", 1) // "2023-12-26T10:30:00.000Z" ``` ```javascript now()|dateTimeAdd("hour", -2) // Two hours ago ``` ```javascript dateTimeAdd("2023-01-01T00:00:00.000Z", "month", 3) // "2023-04-01T00:00:00.000Z" ``` # dateTimeFormat # dateTimeFormat Converts a date and time to a provided format. **Type:** transform ## Parameters * **input** (union): The input date and time, either as a string or number. * **format** (string): The format to convert the date and time to. ## Returns **Type:** `string` The date and time in the specified format. ## Examples ```javascript dateTimeFormat(datetime, format) ``` ```javascript datetime|dateTimeFormat(format) ``` # dateTimeToMillis # dateTimeToMillis Parses the date and time in the ISO 8601 format and returns the number of milliseconds since the Unix epoch. **Type:** transform ## Aliases `toMillis` ## Parameters * **input** (string): The date and time string to parse. ## Returns **Type:** `number` The timestamp in milliseconds since Unix epoch. ## Examples ```javascript dateTimeToMillis("2023-12-25T10:30:00.000Z") // 1703505000000 ``` ```javascript "2023-01-01T00:00:00.000Z"|dateTimeToMillis // 1672531200000 ``` ```javascript dateTimeToMillis("2023-12-25") // 1703462400000 ``` # DateTime # DateTime Date and time operations ## Functions * [`convertTimeZone`](./datetime/convertTimeZone): Converts an ISO datetime string to a target timezone, handling daylight savings, and returns an ISO string with the correct offset. * [`dateTimeAdd`](./datetime/dateTimeAdd): Adds a time range to a date and time in the ISO 8601 format. * [`dateTimeFormat`](./datetime/dateTimeFormat): Converts a date and time to a provided format. * [`dateTimeToMillis`](./datetime/dateTimeToMillis): Parses the date and time in the ISO 8601 format and returns the number of milliseconds since the Unix epoch. * [`localTimeToIsoWithOffset`](./datetime/localTimeToIsoWithOffset): Converts a local time string in a specified timezone to an ISO datetime string with the correct offset. * [`millis`](./datetime/millis): Returns the current date and time in milliseconds since the Unix epoch. * [`millisToDateTime`](./datetime/millisToDateTime): Parses the number of milliseconds since the Unix epoch or parses a string (with or without specified format) and returns the date and time in the ISO 8601 format. * [`now`](./datetime/now): Returns the current date and time in the ISO 8601 format. ## Transforms * [`convertTimeZone`](./datetime/convertTimeZone): Converts an ISO datetime string to a target timezone, handling daylight savings, and returns an ISO string with the correct offset. * [`dateTimeAdd`](./datetime/dateTimeAdd): Adds a time range to a date and time in the ISO 8601 format. * [`dateTimeFormat`](./datetime/dateTimeFormat): Converts a date and time to a provided format. * [`dateTimeToMillis`](./datetime/dateTimeToMillis): Parses the date and time in the ISO 8601 format and returns the number of milliseconds since the Unix epoch. * [`localTimeToIsoWithOffset`](./datetime/localTimeToIsoWithOffset): Converts a local time string in a specified timezone to an ISO datetime string with the correct offset. * [`millisToDateTime`](./datetime/millisToDateTime): Parses the number of milliseconds since the Unix epoch or parses a string (with or without specified format) and returns the date and time in the ISO 8601 format. # localTimeToIsoWithOffset # localTimeToIsoWithOffset Converts a local time string in a specified timezone to an ISO datetime string with the correct offset. **Type:** transform ## Parameters * **localTime** (string): Local time string * **timeZone** (string): Timezone (IANA or Windows ID or fixed offset) ## Returns **Type:** `string` ISO datetime string with correct offset ## Examples ```javascript localTimeToIsoWithOffset('2025-06-26 14:00:00', 'Europe/Amsterdam') // '2025-06-26T14:00:00.0000000+02:00' ``` ```javascript '2025-06-26 05:00:00'|localTimeToIsoWithOffset('Pacific Standard Time') // '2025-06-26T05:00:00.0000000-08:00' ``` # millis # millis Returns the current date and time in milliseconds since the Unix epoch. **Type:** function ## Returns **Type:** `number` The current timestamp in milliseconds. ## Examples ```javascript millis() // 1703505000000 ``` ```javascript millis() // 1703505123456 (different time) ``` # millisToDateTime # millisToDateTime Parses the number of milliseconds since the Unix epoch or parses a string (with or without specified format) and returns the date and time in the ISO 8601 format. **Type:** transform ## Aliases `toDateTime`, `fromMillis`, `dateTimeString`, `millisToDateTime` ## Parameters * **input** (union?): Optional timestamp in milliseconds or date string. * **format** (string?): Optional format string for parsing date strings. ## Returns **Type:** `string` The date and time as an ISO 8601 string, or undefined if parsing fails. ## Examples ```javascript toDateTime(1703505000000) // "2023-12-25T10:30:00.000Z" ``` ```javascript toDateTime("2023-12-25") // "2023-12-25T00:00:00.000Z" ``` ```javascript toDateTime("25/12/2023", "dd/MM/yyyy") // "2023-12-25T00:00:00.000Z" ``` # now # now Returns the current date and time in the ISO 8601 format. **Type:** function ## Returns **Type:** `string` The current date and time as an ISO 8601 string. ## Examples ```javascript now() // "2023-12-25T10:30:00.000Z" ``` ```javascript now() // "2023-12-25T14:45:30.123Z" (different time) ``` # case # case Evaluates a list of predicates and returns the first result expression whose predicate is satisfied. **Type:** transform ## Aliases `switchCase`, `switch`, `case` ## Parameters * **args** (array): The arguments array where the first element is the expression to evaluate, followed by pairs of case and result, and optionally a default value. ## Returns **Type:** `unknown` The result of the first case whose predicate is satisfied, or the default value if no case is satisfied. ## Examples ```javascript switch(expression, case1, result1, case2, result2, ..., default) ``` # eval # eval Evaluates a JEXL expression and returns the result. **Type:** transform ## Aliases `_eval`, `eval` ## Parameters * **input** (unknown): Either a JEXL expression string or a context object. * **expression** (string): Optional JEXL expression when first argument is context. ## Returns **Type:** `any` The result of evaluating the expression, or undefined if evaluation fails. ## Examples ```javascript _eval("1 + 2") // 3 ``` ```javascript _eval({x: 5, y: 10}, "x + y") // 15 ``` ```javascript "2 * 3"|_eval // 6 ``` # Utility # Utility General utility functions ## Functions * [`case`](./utility/case): Evaluates a list of predicates and returns the first result expression whose predicate is satisfied. * [`eval`](./utility/eval): Evaluates a JEXL expression and returns the result. * [`length`](./utility/length): Returns the number of characters in a string, or the length of an array. * [`not`](./utility/not): Returns the logical NOT of the input. * [`type`](./utility/type): Returns the type of the input value as a string. * [`uuid`](./utility/uuid): Generates a new UUID (Universally Unique Identifier). ## Transforms * [`case`](./utility/case): Evaluates a list of predicates and returns the first result expression whose predicate is satisfied. * [`eval`](./utility/eval): Evaluates a JEXL expression and returns the result. * [`length`](./utility/length): Returns the number of characters in a string, or the length of an array. * [`not`](./utility/not): Returns the logical NOT of the input. * [`type`](./utility/type): Returns the type of the input value as a string. # length # length Returns the number of characters in a string, or the length of an array. **Type:** transform ## Aliases `count`, `size` ## Parameters * **input** (unknown): The input can be a string, an array, or an object. ## Returns **Type:** `number` The number of characters in a string, or the length of an array. ## Examples ```javascript length("hello") // 5 ``` ```javascript length([1, 2, 3]) // 3 ``` # not # not Returns the logical NOT of the input. **Type:** transform ## Parameters * **input** (unknown): The input to apply logical NOT to. ## Returns **Type:** `boolean` The logical NOT of the input converted to boolean. ## Examples ```javascript not(true) // false ``` ```javascript false|not // true ``` ```javascript not(0) // true ``` # type # type Returns the type of the input value as a string. **Type:** transform ## Aliases `getType`, `type` ## Parameters * **input** (unknown): The value to check the type of. ## Returns **Type:** `string` The type of the input value. ## Examples ```javascript type(5); // "number" ``` ```javascript foo|type; // "string" ``` ```javascript type(true); // "boolean" ``` # uuid # uuid Generates a new UUID (Universally Unique Identifier). **Type:** function ## Aliases `uid` ## Returns **Type:** `string` A new UUID v4 string. ## Examples ```javascript uuid() // "123e4567-e89b-12d3-a456-426614174000" ``` ```javascript uuid() // "987fcdeb-51a2-43d7-b123-456789abcdef" (different each time) ``` # camelCase # camelCase Converts the input string to camel case. **Type:** transform ## Aliases `camelcase`, `toCamelCase` ## Parameters * **input** (unknown): The input string to convert to camel case. ## Returns **Type:** `string` The camel case string, or empty string if input is not a string. ## Examples ```javascript camelCase("foo bar") // "fooBar" ``` ```javascript "hello-world"|camelCase // "helloWorld" ``` ```javascript camelCase("HELLO_WORLD") // "helloWorld" ``` # contains # contains Checks if the input string or array contains the specified value. **Type:** transform ## Aliases `includes` ## Parameters * **input** (unknown): The input string or array to search in. * **search** (string): The value to search for. ## Returns **Type:** `boolean` True if the input contains the search value, false otherwise. ## Examples ```javascript contains("hello world", "world") // true ``` ```javascript "foo-bar"|contains("bar") // true ``` ```javascript contains([1, 2, 3], 2) // true ``` # endsWith # endsWith Checks if the input string ends with the specified substring. **Type:** transform ## Parameters * **input** (unknown): The input string to check. * **search** (string): The substring to search for at the end. ## Returns **Type:** `boolean` True if the input ends with the search string, false otherwise. ## Examples ```javascript endsWith("hello world", "world") // true ``` ```javascript "foo-bar"|endsWith("bar") // true ``` ```javascript endsWith("test", "xyz") // false ``` # String # String String manipulation and formatting functions ## Functions * [`camelCase`](./string/camelCase): Converts the input string to camel case. * [`contains`](./string/contains): Checks if the input string or array contains the specified value. * [`endsWith`](./string/endsWith): Checks if the input string ends with the specified substring. * [`lowercase`](./string/lowercase): Converts the input string to lowercase. * [`pad`](./string/pad): Pads the input string to the specified width. * [`pascalCase`](./string/pascalCase): Converts the input string to pascal case. * [`replace`](./string/replace): Replaces occurrences of a specified string with a replacement string. * [`split`](./string/split): Splits the input string into an array of substrings. * [`startsWith`](./string/startsWith): Checks if the input string starts with the specified substring. * [`substring`](./string/substring): Gets a substring of a string. * [`substringAfter`](./string/substringAfter): Returns the substring after the first occurrence of the character sequence chars in str. * [`substringBefore`](./string/substringBefore): Returns the substring before the first occurrence of the character sequence chars in str. * [`trim`](./string/trim): Trims whitespace from both ends of a string. * [`uppercase`](./string/uppercase): Converts the input string to uppercase. ## Transforms * [`camelCase`](./string/camelCase): Converts the input string to camel case. * [`contains`](./string/contains): Checks if the input string or array contains the specified value. * [`endsWith`](./string/endsWith): Checks if the input string ends with the specified substring. * [`lowercase`](./string/lowercase): Converts the input string to lowercase. * [`pad`](./string/pad): Pads the input string to the specified width. * [`pascalCase`](./string/pascalCase): Converts the input string to pascal case. * [`replace`](./string/replace): Replaces occurrences of a specified string with a replacement string. * [`split`](./string/split): Splits the input string into an array of substrings. * [`startsWith`](./string/startsWith): Checks if the input string starts with the specified substring. * [`substring`](./string/substring): Gets a substring of a string. * [`substringAfter`](./string/substringAfter): Returns the substring after the first occurrence of the character sequence chars in str. * [`substringBefore`](./string/substringBefore): Returns the substring before the first occurrence of the character sequence chars in str. * [`trim`](./string/trim): Trims whitespace from both ends of a string. * [`uppercase`](./string/uppercase): Converts the input string to uppercase. # lowercase # lowercase Converts the input string to lowercase. **Type:** transform ## Aliases `lower` ## Parameters * **input** (unknown): The input to convert to lowercase. Non-string inputs are converted to JSON string first. ## Returns **Type:** `string` The lowercase string. ## Examples ```javascript lowercase("HELLO") // "hello" ``` ```javascript "HELLO WORLD"|lowercase // "hello world" ``` # pad # pad Pads the input string to the specified width. **Type:** transform ## Parameters * **input** (unknown): The input to pad. Non-string inputs are converted to JSON string first. * **width** (number): The target width. Positive values pad to the right, negative values pad to the left. * **char** (string): The character to use for padding. Defaults to space. ## Returns **Type:** `string` The padded string. ## Examples ```javascript pad("hello", 10) // "hello " ``` ```javascript pad("world", -8, "0") // "000world" ``` ```javascript "foo"|pad(5, ".") // "foo.." ``` # pascalCase # pascalCase Converts the input string to pascal case. **Type:** transform ## Aliases `pascalcase`, `toPascalCase` ## Parameters * **input** (unknown): The input string to convert to pascal case. ## Returns **Type:** `string` The pascal case string, or empty string if input is not a string. ## Examples ```javascript pascalCase("foo bar") // "FooBar" ``` ```javascript "hello-world"|pascalCase // "HelloWorld" ``` ```javascript pascalCase("HELLO_WORLD") // "HelloWorld" ``` # replace # replace Replaces occurrences of a specified string with a replacement string. **Type:** transform ## Parameters * **input** (unknown): The input string to perform replacements on. * **search** (string): The string to search for and replace. * **replacement** (string): The string to replace matches with. Defaults to empty string. ## Returns **Type:** `string` The string with replacements made, or undefined if input is not a string. ## Examples ```javascript replace("foo-bar-baz", "-", "_") // "foo_bar_baz" ``` ```javascript "hello world"|replace("world", "there") // "hello there" ``` ```javascript replace("test test test", "test", "demo") // "demo demo demo" ``` # split # split Splits the input string into an array of substrings. **Type:** transform ## Parameters * **input** (unknown): The input string to split. * **separator** (string): The separator string to split on. ## Returns **Type:** `array` An array of substrings, or empty array if input is not a string. ## Examples ```javascript split("foo,bar,baz", ",") // ["foo", "bar", "baz"] ``` ```javascript "one-two-three"|split("-") // ["one", "two", "three"] ``` ```javascript split("hello world", " ") // ["hello", "world"] ``` # startsWith # startsWith Checks if the input string starts with the specified substring. **Type:** transform ## Parameters * **input** (unknown): The input string to check. * **search** (string): The substring to search for at the beginning. ## Returns **Type:** `boolean` True if the input starts with the search string, false otherwise. ## Examples ```javascript startsWith("hello world", "hello") // true ``` ```javascript "foo-bar"|startsWith("foo") // true ``` ```javascript startsWith("test", "xyz") // false ``` # substring # substring Gets a substring of a string. **Type:** transform ## Parameters * **input** (unknown): The input string. * **start** (number): The starting index of the substring. * **length** (number): The length of the substring. ## Returns **Type:** `string` The substring of the input string. ## Examples ```javascript substring("hello world", 0, 5) // "hello" ``` # substringAfter # substringAfter Returns the substring after the first occurrence of the character sequence chars in str. **Type:** transform ## Parameters * **input** (unknown): The input string. * **chars** (unknown): The character sequence to search for. ## Returns **Type:** `string` The substring after the first occurrence of the character sequence chars in str. ## Examples ```javascript substringAfter("hello world", " ") // "world" ``` # substringBefore # substringBefore Returns the substring before the first occurrence of the character sequence chars in str. **Type:** transform ## Parameters * **input** (unknown): The input string. * **chars** (unknown): The character sequence to search for. ## Returns **Type:** `string` The substring before the first occurrence of the character sequence chars in str. ## Examples ```javascript substringBefore("hello world", " ") // "hello" ``` # trim # trim Trims whitespace from both ends of a string. **Type:** transform ## Parameters * **input** (unknown): The input string to trim. * **trimChar** (string?): Optional character to trim instead of whitespace. ## Returns **Type:** `string` The trimmed string, or empty string if input is not a string. ## Examples ```javascript trim(" hello ") // "hello" ``` ```javascript " world "|trim // "world" ``` ```javascript trim("__hello__", "_") // "hello" ``` # uppercase # uppercase Converts the input string to uppercase. **Type:** transform ## Aliases `upper` ## Parameters * **input** (unknown): The input to convert to uppercase. Non-string inputs are converted to JSON string first. ## Returns **Type:** `string` The uppercase string. ## Examples ```javascript uppercase("hello") // "HELLO" ``` ```javascript "hello world"|uppercase // "HELLO WORLD" ```