Skip to content

Docs: Alienalias

Jump to bottom
ng-druid edited this page Aug 8, 2025 · 1 revision

Documentation for Alienalias Angular Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • Core Modules
    • Metadata Factory
    • Loading Strategy
    • Matching Strategy
    • Redirect Handler
  5. Core Components
    • AlienaliasModule
  6. Key Services
    • AlienaliasFactory
    • Entity Metadata Factory
  7. Usage
    • Setting Up Entity Metadata
    • Plugin Registration via Factory
    • Matching and Redirect Handling
    • Dynamic Module Loading with Strategy
  8. API Reference
  9. Examples
  10. Testing

1. Introduction

The Alienalias Angular library simplifies the management of alias-based routing, dynamic module federation, and remote module loading in browser-based and server-side Angular applications. It integrates with modern libraries like @ngrx/data, @rollthecloudinc/crud, and @angular-architects/module-federation to provide fast and dynamic route resolution.

2. Installation

Install the library and its dependencies via npm:

npm install alienalias @ngrx/data @rollthecloudinc/crud @rollthecloudinc/alias @angular-architects/module-federation

3. Overview

Alienalias provides solutions for creating modular and dynamic applications using alias paths that map to remote modules. It includes tools for:

  • Dynamic route creation and resolution.
  • Matching alias paths loaded remotely.
  • Redirect handler for routing based on alias configuration.
  • Entity metadata creation for data management with custom CRUD mappings.

Features:

  • Modular route federation based on dynamic entity configuration.
  • Easy integration with @ngrx/data for efficient data management.
  • Server-side and browser-based fallback mechanisms for OpenSearch and IndexedDB operations.
  • Dynamic alias-based redirects powered by custom handlers.

4. Key Concepts

4.1 Core Modules

The AlienaliasModule is the entry point of the library. It automatically handles metadata registration, plugin configuration, and service injection for AlienAlias entities.

4.2 Metadata Factory

The entityMetadataFactory dynamically creates CRUD metadata mappings for the AlienAlias entities, enabling features like OpenSearch querying and IndexedDB-based caching.

4.3 Loading Strategy

The AlienaliasLoadingStrategy loads remote modules dynamically based on alias paths. It uses Angular's Router configuration to register these paths during runtime.

4.4 Matching Strategy

The AlienaliasMatchingStrategy matches alias paths based on the current Router snapshot. This strategy ensures smooth routing and alias recognition.

4.5 Redirect Handler

The AlienaliasRedirectHandler handles route redirection using alias metadata and dynamic queries. It resolves a proper alias and redirects to the associated path using query parameters.

5. Core Components

AlienaliasModule

The primary module of the library, responsible for:

  • Registering middleware for route alias handling.
  • Injecting dependencies such as AliasPluginManager, EntityServices, EntityDefinitionService, and Router.
  • Registering metadata and remote modules for AlienAlias entities.

6. Key Services

AlienaliasFactory

The alienaliasFactory creates instances of the AlienaliasPlugin class. These instances define the behavior and strategies for alias loading, matching, and redirect handling.

Entity Metadata Factory

The entityMetadataFactory generates configuration for AlienAlias entities, enabling OpenSearch queries and IndexedDB-based fallback strategies.

7. Usage

7.1 Setting Up Entity Metadata

Generate entity metadata dynamically for AlienAlias entities using entityMetadataFactory.

Example:

import { entityMetadataFactory } from './alienalias/entity-metadata';
import { AlienaliasSettings } from './models/alienalias.models';

const platformId = 'browser';
const alienaliasSettings: AlienaliasSettings = { openSearchDomain: 'your-opensearch-domain-url' };

const entityMetadata = entityMetadataFactory(platformId, alienaliasSettings);
console.log('Generated Metadata:', entityMetadata);

7.2 Plugin Registration via Factory

Use the alienaliasFactory to register dynamic alias plugins based on site-specific configurations:

Example:

import { alienaliasFactory } from './alienalias/alienalias.factories';
import { Router } from '@angular/router';
import { EntityServices } from '@ngrx/data';

const plugin = alienaliasFactory('my-site', entityServices, router);
aliasPluginManager.register(plugin);

7.3 Matching and Redirect Handling

Create a custom instance of AlienaliasMatchingStrategy and AlienaliasRedirectHandler for resolving aliases and handling redirects:

Example:

import { AlienaliasMatchingStrategy } from './strategies/alienalias-matching-strategy';
import { Router } from '@angular/router';
import { EntityServices } from '@ngrx/data';

constructor(private router: Router, private es: EntityServices) {}

ngOnInit() {
  const matchingStrategy = new AlienaliasMatchingStrategy('my-site', this.es, this.router);
  matchingStrategy.match(this.router.routerState.snapshot).subscribe(result => {
    if (result) {
      console.log('Alias Matched!');
    }
  });
}

7.4 Dynamic Module Loading with Strategy

Use the AlienaliasLoadingStrategy for runtime remote module loading and routing registration:

Example:

import { AlienaliasLoadingStrategy } from './strategies/alienalias-loading-strategy';
import { Router } from '@angular/router';
import { EntityServices } from '@ngrx/data';

constructor(private router: Router, private es: EntityServices) {}

ngOnInit() {
  const loadingStrategy = new AlienaliasLoadingStrategy('my-site', this.es, this.router);
  loadingStrategy.load().subscribe(result => {
    if (result) {
      console.log('Remote Alias Modules Loaded Successfully');
    }
  });
}

8. API Reference

Classes

  1. AlienaliasModule

    • Entry point module for the library.

  2. AlienaliasMatchingStrategy

    • Matches alias paths dynamically based on RouterStateSnapshot.

  3. AlienaliasLoadingStrategy

    • Registers routes dynamically based on alias entity definitions.

  4. AlienaliasRedirectHandler

    • Handles route redirection based on AlienAlias entity configurations.

  5. AlienAlias

    • Data model representing alias configurations including metadata like path, remoteEntry, and moduleName.

9. Examples

Example: Registering Entity Metadata for AlienAlias

Use the AlienaliasModule constructor to register dynamic metadata and plugins.

import { AlienaliasModule } from './alienalias/alienalias.module';
import { SITE_NAME } from '@rollthecloudinc/utils';

@NgModule({
  imports: [AlienaliasModule],
})
export class AppModule {
  constructor(
    @Inject(SITE_NAME) siteName: string,
    platformId: Object,
    alienAliasSettings: AlienaliasSettings
  ) {
    console.log('Alienalias Module Initialized');
  }
}

Example: Dynamic Route Loading

Use the AlienaliasLoadingStrategy to dynamically load and append alias routes to the Router configuration.

const loadingStrategy = new AlienaliasLoadingStrategy(siteName, entityServices, router);

loadingStrategy.load().subscribe(isLoaded => {
  if (isLoaded) {
    console.log('Dynamic Alias Routes Loaded');
  }
});

10. Testing

Example: Testing Metadata Factory

Ensure metadata maps are generated properly using factory functions.

import { entityMetadataFactory } from './alienalias/entity-metadata';

describe('Entity Metadata Factory', () => {
  it('should generate metadata for AlienAlias', () => {
    const platformId = 'server';
    const settings = { openSearchDomain: 'https://example.com' };
    const metadata = entityMetadataFactory(platformId, settings);
    
    expect(metadata.AlienAlias.entityName).toBe('AlienAlias');
  });
});

Example: Testing Loading Strategy

Ensure routes are dynamically loaded and registered.

import { AlienaliasLoadingStrategy } from './strategies/alienalias-loading-strategy';

describe('AlienaliasLoadingStrategy', () => {
  it('should dynamically load alias routes', done => {
    const strategy = new AlienaliasLoadingStrategy('my-site', mockEntityServices, mockRouter);
    
    strategy.load().subscribe(isLoaded => {
      expect(isLoaded).toBe(true);
      done();
    });
  });
});

Conclusion

The Alienalias Angular library is a robust and flexible solution for dynamic alias management, server-side querying, remote module federation, and entity-based configuration. By leveraging its powerful tools, you can build extensible applications that integrate seamlessly with modern Angular frameworks.

For feedback, support, or contributions, feel free to contact us!

Clone this wiki locally