Docs: Durl - rollthecloudinc/quell GitHub Wiki

1. Introduction
2. Installation
3. Overview
4. Key Concepts
   • URL Generation
   • Param Plugins
   • Query String Assembly
5. Core Components
   • DurlModule
   • Registered Param Plugins
6. Key Services
   • UrlGeneratorService
7. Usage
   • Generating URLs Dynamically
   • Integrating Param Plugins for URL Parameters
8. API Reference
9. Examples
10. Testing

The Angular Durl Library provides dynamic URL generation capabilities tailored for Angular applications. It supports constructing URLs based on route parameters, metadata, query strings, and dynamic contexts. The library integrates with param plugins to enable runtime extensibility and customization for building URLs.

Install the library and required dependencies:

npm install @rollthecloudinc/dparam @rollthecloudinc/utils @rollthecloudinc/plugin @rollthecloudinc/token qs @ngrx/router-store

The Durl library assists in constructing URLs dynamically by resolving route parameters, query strings, and metadata through custom param plugins. It enables runtime flexibility and modular URL building.

• URL Generation: Dynamically create consistent URLs for navigation or API calls.
• Param Plugins: Extend and manage parameter evaluation logic for customizing URL construction.
• Query String Assembly: Parse and rebuild query strings dynamically based on parameter evaluation.

The library uses metadata, route contexts, and params to dynamically assemble URLs. For example, generated URLs can include resolved route parameters (:id) or query string keys and values (?key=value).

Param plugins extend the capabilities of the library by introducing parameter configuration and evaluation logic. For example, plugins can dynamically resolve pagination offsets, search strings, or query parameter values from metadata and application state.

The DurlModule initializes the library, registers default param plugins, and integrates the DparamModule functionality.

• Page Plugin: Resolves page-based values for pagination.
• Search String Plugin: Dynamically manages search strings in query params.
• Route Plugin: Resolves route parameters dynamically based on the ActivatedRoute.
• Query String Plugin: Parses and evaluates query parameters.
• Standard Pagination Plugin: Calculates offset values for paginated data.

The UrlGeneratorService is the primary service responsible for constructing URLs. It dynamically combines path parameters and query strings using registered param plugins.

Key Methods:

• getUrl(url: string, params: Array<Param>, metadata: Map<string, any>): Observable<string>
  Evaluates the given parameters, resolves their values using metadata and plugins, and generates the final URL.

• paramNames(url: string): Array<string>
  Extracts parameter names from URL segments and query strings.

• rebuildQueryString(q: any): any
  Reconstructs a query string object by removing invalid or undefined entries.

Example Usage:

constructor(private urlGenerator: UrlGeneratorService) {}

this.urlGenerator.getUrl('/api/resource/:id', params, metadata).subscribe(finalUrl => {
  console.log('Generated URL:', finalUrl);
});

The getUrl method in the UrlGeneratorService dynamically assembles URLs based on route parameters, query strings, and metadata.

Example:

const params = [
  new Param({
    mapping: { type: 'route', value: 'id', context: 'query', testValue: '123' },
    flags: [{ name: 'required', enabled: true }]
  }),
  new Param({
    mapping: { type: 'querystring', value: 'search', testValue: 'angular' },
    flags: []
  })
];

const metadata = new Map([
  ['searchString', 'Angular'],
  ['page', 1]
]);

this.urlGenerator.getUrl('/items/:id?page=:page', params, metadata).subscribe(url => {
  console.log(url);
  // Output: "/items/123?page=1"
});

Param plugins enable custom resolution of parameters dynamically. Plugins like Page Plugin help resolve pagination data seamlessly.

Example Plugin Registration:

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

paramPluginManager.register(customPlugin);

1. ParamPlugin
   Represents a plugin for param resolution.

   • id: Unique identifier of the plugin.
   • title: Display name.
   • evalParam: Evaluates the parameter’s value at runtime.
   • condition: Optional function to define execution conditions.

2. UrlGeneratorService
   Constructs URLs dynamically by evaluating params with metadata.

   • getUrl(url: string, params: Array<Param>, metadata: Map<string, any>): Observable<string>: Resolves the final URL.
   • paramNames(url: string): Array<string>: Extracts parameter names from a URL.
   • rebuildQueryString(q: any): any: Rebuilds cleaned query string objects.

const params = [
  new Param({
    mapping: { type: 'querystring', value: 'page', testValue: '2' }
  }),
  new Param({
    mapping: { type: 'querystring', value: 'search', testValue: 'text' }
  })
];

const metadata = new Map([['limit', 10], ['page', 2]]);

this.urlGenerator.getUrl('/api/:page', params, metadata).subscribe(url => {
  console.log(url); // Output: "/api/2"
});

constructor(private paramPluginManager: ParamPluginManager) {}

ngOnInit() {
  const plugin = new ParamPlugin<string>({
    id: 'customPlugin',
    title: 'Custom Plugin',
    evalParam: ({ param, metadata }) => of(metadata.get(param.mapping.value)),
  });

  this.paramPluginManager.register(plugin);
}

import { UrlGeneratorService } from './services/url-generator.service';
import { Param } from '@rollthecloudinc/dparam';

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

  it('should generate URLs correctly', () => {
    const params = [
      new Param({
        mapping: { type: 'route', value: 'id', testValue: '123' }
      })
    ];
    
    const metadata = new Map([['_route', { params: { id: '123' } }]]);

    service.getUrl('/user/:id', params, metadata).subscribe(url => {
      expect(url).toBe('/user/123');
    });
  });
});

The Angular Durl Library simplifies the process of generating dynamic URLs by combining route information, query parameters, and runtime metadata evaluation. With its integration of param plugins, customizable evaluation logic, and seamless orchestration, this library is ideal for applications requiring flexible, modular, and context-aware URL construction.

For contributions, questions, or bug reports, feel free to contact us!