ngxtension Platform

ngxtension provides a wide range of utilities for modern Angular development, categorized into several domains:

• Signal Utilities: Advanced computed, derived, and async signals, signal history, lazy signals, etc.
• DOM & Event Helpers: Click outside, gestures, resize observer, active element, host binding, etc.
• Forms: Control value accessor helpers, control error, form events, if-validator, etc.
• RxJS & Effects: Auto effects, explicit effects, create effect, rx-effect, take-latest-from, etc.
• Injection & DI: Create injectable, create injection token, assert injector, inject-destroy, inject-lazy, inject-network, etc.
• Array & Object Utilities: Filter array, map array, reduce array, merge-from, not-pattern, etc.
• Routing: Inject params, inject query params, inject route data/fragment, navigation-end, linked-query-param.
• Internationalization: Utilities for i18n and formatting.
• SVG & UI: SVG sprite helpers, repeat pipe, trackBy helpers, etc.

ngxtension provides a wide range of utilities for Angular developers, categorized into several functional areas:

Signal Utilities

Tools for advanced signal management, including connect, derivedFrom (combineLatest for signals), explicitEffect, createNotifier, signalSlice, toLazySignal, toObservableSignal, mergeFrom, and computedPrevious.

Router Utilities

Utilities for interacting with the Angular Router using signals, such as linkedQueryParam (bidirectional binding), injectQueryParams, injectParams, injectRouteData, injectRouteFragment, and injectNavigationEnd.

Injector Utilities

Enhanced dependency injection tools like injectLazy, createInjectionToken, injectDestroy (for easy unsubscription), injectNetwork, injectIsIntersecting, injectLocalStorage, injectTextSelection, injectInputs, createInjectable, and autoEffect.

RxJS Operators

Custom operators to simplify stream handling, including debug, filterArray, filterNil, mapArray, mapSkipUndefined, poll, whenDocumentVisible, deriveLoading, and takeLatestFrom.

Forms

Utilities for Angular Forms, such as ifValidator/ifAsyncValidator for conditional validation, controlValueAccessor for custom controls, controlError for error handling, and formEvents for enhanced event handling.

Other Utilities

• Pipes: repeatPipe and call/apply for templates.
• Effects & Lifecycle: createEffect (standalone NgRx-style), effectOnceIf, and rxEffect.
• Directives: clickOutside, repeat, resize, and TrackById/TrackByProp.
• Components: hostBinding (signal-based), svgSprite, and Gesture collection.
• Miscellaneous: createSingletonProxy, call/apply, intl (i18n), and mergeHttpContext.

A StateMatcher is a function used to define exactly when a control is considered to be in an "error state". The directive renders its template when the StateMatcher emits true and the control contains at least one of the tracked errors.

Type Definition:

export type StateMatcher = (
	control: AbstractControl,
	parent?: FormGroupDirective | NgForm,
) => Observable<boolean>;

Default Behavior: The control is in an error state if its status is INVALID and it is either touched or the parent form is submitted.

Customization Options:

1. Via Input: Pass the matcher directly to the directive in your template.
2. Via DI: Provide a global matcher using provideNgxControlError.

// 1. Define a custom matcher
export const customErrorStateMatcher: StateMatcher = (control) =>
	control.statusChanges.pipe(
		startWith(control.status),
		map((status) => status === 'INVALID'),
	);

// 2. Apply via DI (Global)
provideNgxControlError({ errorStateMatcher: customErrorStateMatcher });

// 3. Apply via Input (Local)

<strong *ngxControlError="name; track: 'required'; errorStateMatcher: customErrorStateMatcher">
  Name is required.
</strong>

Use SignalSet instead of a standard Set when your application logic depends on Angular Signals. While a regular Set is more memory-efficient, it cannot trigger updates in computed values or effect blocks when its contents change. SignalSet provides full API compatibility with core Set methods while adding reactivity.

| Feature             | Regular Set  | SignalSet                 |
| ------------------- | ------------ | ------------------------- |
| Reactivity          | ❌ No        | ✅ Yes                    |
| Works with computed | ❌ No        | ✅ Yes                    |
| Works with effect   | ❌ No        | ✅ Yes                    |
| Duplicate handling  | ✅ Yes       | ✅ Yes                    |
| Insertion order     | ✅ Yes       | ✅ Yes                    |
| Memory overhead     | Lower        | Slightly higher (signals) |
| API compatibility   | Full Set API | Core Set methods          |

The signalSlice utility is inspired by Redux Toolkit's createSlice. It allows you to declaratively create a "slice" of state that is exposed as a readonly signal.

Key characteristics:

• Declarative Updates: All state updates must be declared upfront via sources or actionSources. It is impossible to update the state imperatively.
• Readonly State: The primary state signal is read-only to ensure data integrity.
• Automatic Selectors: Top-level properties of the initialState are automatically exposed as individual computed signals on the state object.
• Action-Driven: State changes are driven by observable streams (sources) or manually triggered actions.

import { signalSlice } from 'ngxtension/signal-slice';

const state = signalSlice({
  initialState: { checklists: [], loaded: false, error: null },
});

// Access full state
console.log(state());

// Access top-level properties as individual signals
console.log(state.loaded());