Docs: Transform

Documentation for Transform Angular Library

---

Table of Contents

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

---

1. Introduction

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.

---

2. Installation

Install the library along with its required dependencies:

npm install transform @rollthecloudinc/datasource @rollthecloudinc/attributes

---

3. Overview

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.

Features:

• 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.

---

4. Core Components

4.1 TransformSelectComponent

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>

---

4.2 TransformMergeComponent

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>

---

4.3 SelectSourceFormComponent

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>

---

5. Core Models

SelectTransform

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)]'
});

---

6. Factories

6.1 selectDatasourcePluginFactory

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
});

---

6.2 mergeDatasourcePluginFactory

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 });

---

7. Key Services

DatasourcePluginManager

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());

---

8. Usage

8.1 Registering Plugins

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());
  }
}

---

8.2 Fetching Data through Transformations

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);
});

---

9. API Reference

Classes

1. SelectTransform

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

2. DatasourcePlugin

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

Components

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.

---

10. Examples

Example 1: Registering Plugins and Applying a Transform

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
  });
}

Example 2: Dynamic Form for JSONPath Transformation

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

---

11. Testing

Unit Test: Transform Select Component

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

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

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

Unit Test: SelectDatasourcePlugin

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();
  });
});

---

Conclusion

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!