website·Indexed 30 days ago
https://ngrx-traits.devA library for NgRx that provides store features for backend calls, entity management (filtering, pagination, selection, and sorting), and state synchronization with URLs, Web Storage, and SSR. It includes a variety of traits such as withEntities, withCalls, and withSyncToRouteQueryParams, as well as utility functions and a writeTo mechanism.
Ngrx Traits provides a set of reusable store features (traits) that can be plugged into a signalStore to implement common state management patterns. Key feature categories include:
withCalls, withCallStatus).withEntitiesLocalPagination, withEntitiesRemoteFilter).withSyncToWebStorage, withRouteParams).withCallStatusMap trait generates the state, computed signals, and methods necessary to track the progress status of backend calls. Unlike a single status trait, it uses a map (keyed by string or number), allowing multiple calls of the same type to run in parallel, each with its own independent status. This is particularly useful for scenarios not handled by withEntitiesCalls.import { withCallStatusMap } from '@ngrx-traits/signals';
const store = signalStore(withCallStatusMap({ prop: 'loadDetails' }));When syncing multiple entity collections within a single store, use the prefix option in withEntitiesSyncToRouteQueryParams to prevent query parameter collisions.
Because signalStore has a limit of 15 features, it is recommended to group each collection's traits into a custom signalStoreFeature using entityConfig to maintain readability and avoid hitting the feature limit.
// Define config for a collection
export const productEntityConfig = entityConfig({
entity: type<Product>(),
collection: 'product',
});
export function withProductEntities() {
return signalStoreFeature(
withEntities(productEntityConfig),
withCallStatus({ ...productEntityConfig, initialValue: 'loading' }),
// ... other traits
withEntitiesSyncToRouteQueryParams({
...productEntityConfig,
prefix: 'p', // Params become p-filter, p-page, etc.
}),
);
}
// Compose multiple collection features into one store
export const ProductsShopStore = signalStore(
withProductEntities(),
withOrderEntities(),
);To enable full type inference and autocompletion in factory functions when one feature depends on another, follow these patterns:
signalStoreFeature in a function.type() helper as the first argument to the signalStoreFeature call, passing the type of the dependent feature (e.g., type<ProductEntitiesStoreFeature>()).model() type does not match the store's state type, syncWith cannot be used. Instead, combine readFrom (to map the model into the store's type) and writeTo (to map store changes back to the model). The store's equal guard prevents echo loops between these two mappings.@Component({ /* ... */ })
export class ProductSearchComponent {
store = inject(ProductsStore);
// Parent uses string, store uses { search: string }
search = model<string>('');
linked = this.store.linkProductEntitiesFilter({
// Map model -> store type
readFrom: computed(() => ({ search: this.search() })),
// Map store type -> model
writeTo: (value) => this.search.set(value.search),
});
}withEntitiesHybridFilter determines a remote filter is required (via isRemoteFilter), it sets the collection to a loading state. To actually fetch the data from a backend, you should either create a custom effect that listens to the loading state or use the withEntitiesLoadingCall trait to map the filter parameters to an API call.withEntitiesLoadingCall({
...entityConfig,
fetchEntities: ({ productEntitiesFilter }) => {
return inject(ProductService).getProducts({
categoryId: productEntitiesFilter().categoryId,
});
},
}),The withEntitiesMultiSelection trait generates the state, computed signals, and methods required to handle the selection of multiple entities. It requires withEntities to be present in the store.
Caveat: isAll[Collection]Selected and toggleSelectAll[Collection] will not work correctly when using remote pagination, as they cannot access the full dataset on the server.
import { signalStore } from '@ngrx-traits/signals';
import { withEntities, withEntitiesMultiSelection, entityConfig } from '@ngrx-traits/signals';
const entity = entityConfig({
entity: type<Product>(),
collection: 'product'
});
const store = signalStore(
withEntities(entity),
withEntitiesMultiSelection(entity)
);
The withStatePrivateSetter trait generates private setter methods for specified state properties. For each provided state prop, it creates a method named _set[PropName](). Because the method name starts with an underscore, @ngrx/signals excludes it from the store's public type, making it callable only from within the store (e.g., inside withMethods). This is used when a property should be publicly readable but only writable internally.
Generated setters are signalMethods and support:
(current) => next for partial updates.import { signalStore, withState, withMethods } from '@ngrx/signals';
import { withStatePrivateSetter } from '@ngrx-traits/signals';
const Store = signalStore(
withState({
filter: '',
d: 12,
}),
// generates _setFilter()
withStatePrivateSetter('filter'),
withMethods((store) => ({
clearFilter: () => store._setFilter(''), // usable inside the store
})),
);
const store = new Store();
store.filter(); // readable from outside
store.clearFilter();
// store._setFilter('x'); // compile error: not part of the public store typewithLogger trait from @ngrx-traits/signals logs state signals and computed signals of the store to the console on every change. It can be configured with a name for identification and an optional filter to limit which signals are logged.import { signalStore, withState, withEntities } from '@ngrx-traits/signals';
import { withLogger } from '@ngrx-traits/signals';
const store = signalStore(
withState({ foo: 'foo' }),
withEntities({entity: type<Product>()}),
withLogger({ name: "MyStore" }),
);withLinkEntitiesMultiSelection is a prebuilt version of withLink specifically for withEntitiesMultiSelection. It generates a link[Collection]IdsSelected() method that connects the store's selected entity IDs to Angular component signals such as input(), model(), or Signal Forms.
Key behaviors:
[collection]IdsSelected computed signal.select[Collection]Entities with clearSelectionBeforeSelect enabled (meaning each write replaces the current selection, and an empty array clears it).withEntitiesMultiSelection must be used in the store before withLinkEntitiesMultiSelection.const entity = type<Genre>();
export const GenresStore = signalStore(
{ providedIn: 'root' },
withEntities({ entity }),
withEntitiesMultiSelection({ entity }),
// generates linkIdsSelected()
withLinkEntitiesMultiSelection({ entity }),
);