Docs: Transform - rollthecloudinc/quell GitHub Wiki

1. Introduction
2. Installation
3. Overview
4. Core Components
   • TransformSelectComponent
   • TransformMergeComponent
   • SelectSourceFormComponent
5. Core Models
   • SelectTransform
6. Factories
   • selectDatasourcePluginFactory
   • mergeDatasourcePluginFactory
7. Key Services
   • DatasourcePluginManager
8. Usage
   • Registering Plugins
   • Fetching Data through Transformations
9. API Reference
10. Examples
11. Testing

The Transform Angular Library provides developers with tools to create, manage, and apply transformations to data sources using dynamic queries and merging. It offers a modular approach to apply lightweight data manipulation through custom plugins and dynamic forms.

Install the library along with its required dependencies:

npm install transform @rollthecloudinc/datasource @rollthecloudinc/attributes

The Transform library enables the creation and management of data transformations through pre-defined plugins (Select, Merge) and is extensible for additional transformations. It integrates seamlessly with Angular Forms while leveraging DatasourcePluginManager.

• Dynamic Select Transformations: Apply JSONPath queries to select subsets of data dynamically.
• Merge Transformations: Combine datasets dynamically through customizable plugins.
• Custom Forms for Settings: Use dynamic forms for user inputs to configure transformations.
• Plugin Registration: Easily manage and register transformation plugins via factories.

The TransformSelectComponent provides a form-based interface to configure and apply filtering transformations through JSONPath queries.

Selector: classifieds-ui-transform-select

Dependencies:

• Angular's ControlContainer
• AttributeValue for serialized attribute settings

Usage:

<classifieds-ui-transform-select
  [settings]="transformSettings">
</classifieds-ui-transform-select>

The TransformMergeComponent serves as a placeholder for implementing merging functionality between multiple datasets. While currently minimally scoped, it sets up the structure for advanced merging implementations.

Selector: classifieds-ui-transform-merge

Usage:

<classifieds-ui-transform-merge></classifieds-ui-transform-merge>

The SelectSourceFormComponent is a dynamic form component for defining and managing JSONPath queries in the Select transformation.

Selector: classifieds-ui-select-source-form

Form Control Elements:

• query (required): The JSONPath query string to define the data subset.

Example:

<classifieds-ui-select-source-form
  [settings]="attributeSettings">
</classifieds-ui-select-source-form>

The SelectTransform model encapsulates the structure for making a JSONPath query to filter or transform a dataset dynamically.

Properties:

• query (string): The JSONPath query used for selecting data from the source dataset.

Example:

const selectTransform = new SelectTransform({
  query: '$.store.books[?(@.price < 10)]'
});

The selectDatasourcePluginFactory creates a DatasourcePlugin for performing selection transformations using JSONPath queries. This plugin processes input datasets and applies a query defined within its settings.

Key Plugin Configuration:

• id: select
• title: Select
• editor: TransformSelectComponent
• fetch: Applies the JSONPath filtering logic.

Example:

const plugin = selectDatasourcePluginFactory(attributeSerializerService);
plugin.fetch({
  settings: transformSettings,
  dataset: dataSourceDataset
});

The mergeDatasourcePluginFactory creates a DatasourcePlugin for combining datasets. (Currently returns an empty dataset as the merging logic is to be extended.)

Key Plugin Configuration:

• id: merge
• title: Merge
• editor: TransformMergeComponent

Example:

const plugin = mergeDatasourcePluginFactory();
plugin.fetch({ settings: mergeSettings });

The DatasourcePluginManager is responsible for managing, registering, and applying transformations via plugins.

Responsibilities:

• Register plugins.
• Manage their lifecycle.
• Apply transformations dynamically at runtime.

Example:

constructor(private pluginManager: DatasourcePluginManager) {}

pluginManager.register(selectDatasourcePluginFactory(attributeSerializerService));
pluginManager.register(mergeDatasourcePluginFactory());

Plugins are registered within the TransformModule constructor using the DatasourcePluginManager.

Example:

@NgModule({
  ...
})
export class TransformModule { 
  constructor(dpm: DatasourcePluginManager, attributeSerializer: AttributeSerializerService) {
    dpm.register(selectDatasourcePluginFactory(attributeSerializer));
    dpm.register(mergeDatasourcePluginFactory());
  }
}

To fetch data using a transformation:

1. Attach appropriate settings to the plugin.
2. Use the fetch method to process the dataset.

Example:

const result$ = plugin.fetch({
  settings: transformSettings,
  dataset: inputDataset
});

result$.subscribe(dataset => {
  console.log('Transformed Dataset:', dataset);
});

1. SelectTransform

   • Properties:
     • query (string)
   • Constructor: SelectTransform(data?: SelectTransform)

2. DatasourcePlugin

   • Methods:
     • fetch(config): Observable<Dataset>

1. TransformSelectComponent

   • Inputs:
     • settings: Array of serialized key-value pairs for transform configuration.

2. TransformMergeComponent

3. SelectSourceFormComponent

   • Inputs:
     • settings: Array of serialized attributes.
   • Form Controls:
     • query (required): JSONPath query string.

import { DatasourcePluginManager } from '@rollthecloudinc/datasource';

constructor(private dpm: DatasourcePluginManager, private attributeSerializer: AttributeSerializerService) {}

ngOnInit() {
  this.dpm.register(selectDatasourcePluginFactory(this.attributeSerializer));
  const plugin = this.dpm.get('select');
  const result$ = plugin.fetch({
    settings: transformSettings,
    dataset: inputDataset
  });
}

<form [formGroup]="formGroup">
  <classifieds-ui-select-source-form
    formControlName="query"
    [settings]="settings">
  </classifieds-ui-select-source-form>
</form>

describe('TransformSelectComponent', () => {
  let component: TransformSelectComponent;

  beforeEach(() => {
    component = new TransformSelectComponent(/* init */);
  });

  it('should initialize with default settings', () => {
    expect(component.settings).toEqual([]);
  });
});

it('should filter dataset based on JSONPath query', (done) => {
  const plugin = selectDatasourcePluginFactory(mockSerializer);
  const settings = [new AttributeValue({ key: 'query', value: '$.items[?(@.price < 50)]' })];
  const dataset = new Dataset({ results: exampleData });

  plugin.fetch({ settings, dataset }).subscribe(results => {
    expect(results).toBeDefined();
    done();
  });
});

The Transform Angular Library is a robust tool for creating reusable and dynamic data transformations. By combining dynamic forms and plugins, it provides developers with powerful utilities for handling complex datasets efficiently. The library can be extended for a wide range of transformation use cases, making it suitable for modern data-driven applications.

For issues and contributions, please feel free to reach out!