Docs: Dparam - rollthecloudinc/quell GitHub Wiki

1. Introduction
2. Installation
3. Overview
4. Key Concepts
   • Param Models
   • Param Plugins
   • Param Evaluation and Resolution
5. Core Components
   • DparamModule
   • ParamsFormComponent
   • ParamsQuerystringComponent
   • PluginInstanceComponent
6. Key Services
   • ParamEvaluatorService
   • ParamPluginManager
7. Usage
   • Defining Parameters
   • Extending Parameters with Plugins
   • Forms and Binding Parameters Dynamically
8. API Reference
9. Examples
10. Testing

The Angular Dparam Library provides a flexible and plugin-driven mechanism for managing dynamic parameters in Angular applications. It supports parameter evaluation, plugin-based parameter extensions, and reactive form components for parameter management. The library is ideal for applications requiring dynamic configuration or runtime parameter resolution.

Install the library and its dependencies using the following command:

npm install @rollthecloudinc/material @rollthecloudinc/utils @rollthecloudinc/plugin @rollthecloudinc/token qs

Ensure Angular dependencies for forms and material design are also installed.

The Dparam library helps in defining, managing, and evaluating parameters dynamically within an Angular application. It introduces ParamPlugins to extend parameter logic and supports reactive forms for parameter configuration.

• Dynamic Parameter Models: Define complex parameter structures with mapping and flags.
• Plugin-driven Evaluation: Extend parameter evaluation logic with custom plugins.
• Reactive Components: Use Angular reactive forms for parameter configuration and binding.
• Query String Parsing: Parse and manage parameters from query strings.

A Param represents a structured dynamic parameter containing:

• Mapping: Information about the type, value, context, and test value of the parameter.
• Flags: Additional settings or metadata for controlling the behavior of the parameter.

Example:

const param = new Param({
  mapping: { type: 'string', value: 'username', context: 'query', testValue: 'testUser' },
  flags: [{ name: 'required', enabled: true }]
});

Param Plugins (ParamPlugin) extend parameter evaluation logic dynamically at runtime. Each plugin can define custom evaluation criteria, conditions for usage, and contexts for usage.

Example:

const staticParamPlugin = new ParamPlugin<string>({
  id: 'static',
  title: 'Static Param Plugin',
  evalParam: ({ param, metadata }) => of(param.mapping.value),
});

Parameters can be resolved dynamically using the ParamEvaluatorService. This service evaluates parameter values by leveraging registered plugins. It also handles metadata, token substitution, and runtime context resolution.

The entry point for the library encapsulates services, components, and param-related utilities. It registers default plugins (static and inputparam) during initialization.

Example:

import { DparamModule } from '@rollthecloudinc/dparam';

@NgModule({
  imports: [DparamModule],
})
export class AppModule { }

A reactive form component for managing parameters dynamically, with support for plugins and metadata binding. The ParamsFormComponent allows creating, editing, and binding parameters within your application.

• params: A map of parameters to manage.
• paramValues: Resolved values of the parameters.
• contexts: Parameter contexts for runtime evaluation.

<classifieds-ui-params-form
  [params]="paramsMap"
  [paramValues]="resolvedValues"
  [contexts]="availableContexts"
  (valueChanges)="onParamsChange($event)">
</classifieds-ui-params-form>

Handles query string parsing and parameter management. This component parses and modifies parameters dynamically based on the provided paramsString.

• settings: Parameter settings, including the string representation and resolved parameters.
• contexts: Parameter contexts for parsing.

<druid-params-querystring
  [settings]="paramSettings"
  [contexts]="availableContexts"
  (valueChanges)="onQueryStringChange($event)">
</druid-params-querystring>

Manages parameter plugins dynamically. This component can be used to instantiate specific plugin logic and bind settings at runtime.

• title: Title for the plugin instance.
• plugins: List of available plugins.
• instance: Plugin instance settings.

<druid-params-plugin-instance
  [title]="'Custom Plugin'"
  [plugins]="registeredPlugins"
  [instance]="pluginInstanceSettings"
  (valueChanges)="onPluginSettingsChange($event)">
</druid-params-plugin-instance>

Evaluates parameter values by applying registered plugins and optionally resolves tokens or contexts dynamically.

• paramValue(param: Param, metadata: Map<string, any>): Evaluates the value of a specific parameter.
• paramValues(params: Map<string, Param>): Evaluates values for multiple parameters.
• resolveParams(params): Resolves parameters dynamically and returns structured results.

Manages lifecycle operations for param plugins, including registration and retrieval.

• register(plugin: ParamPlugin): Registers a new plugin.
• getPlugins(): Retrieves all registered plugins.

Create and manage parameters using the provided Param model:

const param = new Param({
  mapping: { type: 'user-input', value: 'username', testValue: 'exampleUser' },
  flags: [{ name: 'required', enabled: true }]
});

Extend parameter evaluation logic by defining plugins and registering them dynamically.

import { ParamPluginManager } from './services/param-plugin-manager.service';

const staticPlugin = new ParamPlugin<string>({
  id: 'static',
  title: 'Static Plugin',
  evalParam: ({ param, metadata }) => of(param.mapping.value),
});

pluginManager.register(staticPlugin);

Use reactive components like ParamsFormComponent and ParamsQuerystringComponent to manage and bind parameters interactively with runtime updates.

<classifieds-ui-params-form
  [params]="parameterMap"
  (valueChanges)="handleParameterChanges($event)">
</classifieds-ui-params-form>

1. Param

   • Represents structured parameters with flags and mapping information.

2. ParamPlugin

   • Represents plugin logic for dynamic evaluation of parameters.

3. ParamSettings

   • Represents collections of parameters and their string representations.

1. ParamEvaluatorService

   • Evaluates and resolves parameter values dynamically.

2. ParamPluginManager

   • Registers and manages plugins for parameter evaluation.

1. ParamsFormComponent

   • Reactive form component for managing dynamic parameters.

2. ParamsQuerystringComponent

   • Handles query string-based parameter parsing and management.

3. PluginInstanceComponent

   • Instantiates and binds plugin settings dynamically.

<classifieds-ui-params-form
  [params]="dynamicParameters"
  [contexts]="['query', 'body']"
  (valueChanges)="onParameterChange($event)">
</classifieds-ui-params-form>

const staticPlugin = new ParamPlugin<string>({
  id: 'default',
  title: 'Default Plugin',
  evalParam: ({ param }) => of(param.mapping.value),
});

pluginManager.register(staticPlugin);

import { ParamEvaluatorService } from './services/param-evaluator.service';

describe('ParamEvaluatorService', () => {
  let service: ParamEvaluatorService;

  it('should resolve parameter values', () => {
    const param = new Param({
      mapping: { type: 'static', value: 'example' }
    });

    service.paramValue(param, new Map()).subscribe(value => {
      expect(value).toEqual('example');
    });
  });
});

The Angular Dparam Library provides a robust framework for managing dynamic parameters, plugin-driven evaluation logic, and reactive components for interactive configuration. It is ideal for applications requiring runtime parameter customization or plugin-based extensibility.

For contributions, issues, or questions, feel free to reach out!