Creating an Angular Eagle Eye Context Service

`provideContextService(...)`

The provideContextService(...) is the context service provider. See usage here. It creates and provides an instance of the Angular Eagle Eye context service.

The `ContextService` Class

To access the Angular Eagle Eye context in Angular environment, a ContextService class has been provided. This service can be provided to the Angular application environment in two options. Namely:

at the root level (i.e. visible globally within the app).
at the scope level (visible within a specific section of the app).

Service Configuration

Before we begin with the creation and provision of the service, let us pave the way by acquainting ourselves with the input configurations expected by this service provider.

Configuration Object:

Property	Type	Optional	Description
attrs.prehooks	Prehooks<STATE>	Yes	Please see prehooks
attrs.storage	IStorage<STATE>	Yes	Please see storage
attrs.value	STATE \| AutoImmutable<STATE>	Yes	The state object where a state object is a plain object. Also acceptable is an AutoImmutable already holding this state object.
ref	InjectionToken<ContextService<STATE>>	Yes	A custom reference handle to this context instance. When none provided, `ContextService` will be used.

Providing the `ContextService` at the Root Level

Default Case

The following is the default case. In this case, our state will be initialized with an AutoImmutable instance holding an empty plain object as state object.

import { provideContextService } from '@webkrafters/ng-eagleeye';

export const appConfig: ApplicationConfig = {
    providers: [
        provideContextService() 
    ]
};

Custom Case

The follwing is a complete view of a provideContextService(...). Any omitted property is supplied a default equivalent.

import { provideContextService } from '@webkrafters/ng-eagleeye';

export const appConfig: ApplicationConfig = {
    providers: [
        provideContextService({
            attrs? : {
                prehooks? : Prehooks<T>;
                storage? : IStorage<T>;
                value? : T | AutoImmutable<T>;
            },
            ref? : InjectionToken<ContextService<T>>
        })
    ]
};

Providing the `ContextService` at a Scope Level

The provision of a new ContextService instance at any section of an application is identical to the requirement of doing same at the root level. The only difference is in the Angular DI interpretation.

A ContextService instance is only accessible within the scope (i.e. the resource at the provision point, all of its child resources and descendants).

A ContextService instance sharing identical ref config property with an earlier provided resource in the Angular DI chain overrides the earlier resource.

As such, a ContextService instance provided without the ref config property overrides any earlier provided resource in the Angular DI chain.

Service Referenceabiility

Custom reference handle for provided ContextService instance is generally unnecessary. Contrarily, there are a few cases in which this feature may be used to avoid resource override within the Angular DI system. For instance:

Scenario #1

Let's provide at the application root without a custom ref.

import { provideContextService } from '@webkrafters/ng-eagleeye';

export const appConfig: ApplicationConfig = {
    providers: [
        provideContextService() 
    ]
};

Let's consume the provided context service in our local component.

import { CustomService } from '@webkrafters/ng-eagleeye';

@Component()
export class TestComponent{
    myContext = inject( CustomService );
}

Aftermath:

this.myContext will hold the lone CustomService instance provided.

Scenario #2

Let's provide at an application root with and without a custom ref.

import {
    CONTEXT_DESCRIPTOR,
    provideContextService
} from '@webkrafters/ng-eagleeye';

export const CONTEXT_TOKEN = new InjectionToken( `${ CONTEXT_DESCRIPTOR }_Testing` );

export const appConfig: ApplicationConfig = {
    providers: [
        provideContextService(),
        provideContextService({
            ref: CONTEXT_TOKEN
        })
    ]
};

Let's attemept to consume our provided context services while introducing another non-custom referenced ContextService to the local component scope.

import { provideContextSerivce } from @webkrafters/ng-eagleeye;
import { CONTEXT_TOKEN } from './referenceable_base_context;

@Component({
    providers: [ provideContextSerivce() ]
})
export class TestComponent{
    myContext = inject( CustomService );
    sharedContext = inject( CONTEXT_TOKEN );
}

Aftermath:

Ironically, this.myContext will hold the non-custom referenced CustomService instance provided at the TestComponent scope level.

this.sharedContext will hold the custom referenced CustomService from the root provision.

The non-custom referenced CustomService provided at the root level is unreachable.

Note:

Custom Reference Naming Covention

The description string acceptable to config.ref must have the "EagleEye_Context_Service_" prefix.

Example of creating a StreamService using a custom reference to an existing ContextService can be observed in Joining context stream.

Next: Consuming Context (the Direct Method)