@ngrx/signals 19.0.1 → 19.2.0

package/entities/src/helpers.d.ts

@@ -17,9 +17,9 @@ export declare function getEntityUpdaterResult(state: EntityState<any>, stateKey
     entityMapKey: string;
     idsKey: string;
 }, didMutate: DidMutate): Record<string, any>;
-export declare function addEntityMutably(state: EntityState<any>, entity: any, selectId: SelectEntityId<any>): DidMutate;
-export declare function addEntitiesMutably(state: EntityState<any>, entities: any[], selectId: SelectEntityId<any>): DidMutate;
-export declare function setEntityMutably(state: EntityState<any>, entity: any, selectId: SelectEntityId<any>): DidMutate;
-export declare function setEntitiesMutably(state: EntityState<any>, entities: any[], selectId: SelectEntityId<any>): DidMutate;
+export declare function addEntityMutably(state: EntityState<any>, entity: any, selectId: SelectEntityId<any>, prepend?: boolean): DidMutate;
+export declare function addEntitiesMutably(state: EntityState<any>, entities: any[], selectId: SelectEntityId<any>, prepend?: boolean): DidMutate;
+export declare function setEntityMutably(state: EntityState<any>, entity: any, selectId: SelectEntityId<any>, replace?: boolean): DidMutate;
+export declare function setEntitiesMutably(state: EntityState<any>, entities: any[], selectId: SelectEntityId<any>, replace?: boolean): DidMutate;
 export declare function removeEntitiesMutably(state: EntityState<any>, idsOrPredicate: EntityId[] | EntityPredicate<any>): DidMutate;
 export declare function updateEntitiesMutably(state: EntityState<any>, idsOrPredicate: EntityId[] | EntityPredicate<any>, changes: EntityChanges<any>, selectId: SelectEntityId<any>): DidMutate;

package/entities/src/index.d.ts

@@ -1,5 +1,7 @@
 export { addEntity } from './updaters/add-entity';
 export { addEntities } from './updaters/add-entities';
+export { prependEntity } from './updaters/prepend-entity';
+export { prependEntities } from './updaters/prepend-entities';
 export { removeEntity } from './updaters/remove-entity';
 export { removeEntities } from './updaters/remove-entities';
 export { removeAllEntities } from './updaters/remove-all-entities';
@@ -9,6 +11,8 @@ export { setAllEntities } from './updaters/set-all-entities';
 export { updateEntity } from './updaters/update-entity';
 export { updateEntities } from './updaters/update-entities';
 export { updateAllEntities } from './updaters/update-all-entities';
+export { upsertEntity } from './updaters/upsert-entity';
+export { upsertEntities } from './updaters/upsert-entities';
 export { entityConfig } from './entity-config';
 export { EntityId, EntityMap, EntityProps, EntityState, NamedEntityProps, NamedEntityState, SelectEntityId, } from './models';
 export { withEntities } from './with-entities';

package/entities/src/updaters/prepend-entities.d.ts

@@ -0,0 +1,17 @@
+import { PartialStateUpdater } from '@ngrx/signals';
+import { EntityId, EntityState, NamedEntityState, SelectEntityId } from '../models';
+export declare function prependEntities<Entity extends {
+    id: EntityId;
+}>(entities: Entity[]): PartialStateUpdater<EntityState<Entity>>;
+export declare function prependEntities<Entity, Collection extends string>(entities: Entity[], config: {
+    collection: Collection;
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function prependEntities<Entity extends {
+    id: EntityId;
+}, Collection extends string>(entities: Entity[], config: {
+    collection: Collection;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function prependEntities<Entity>(entities: Entity[], config: {
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<EntityState<Entity>>;

package/entities/src/updaters/prepend-entity.d.ts

@@ -0,0 +1,17 @@
+import { PartialStateUpdater } from '@ngrx/signals';
+import { EntityId, EntityState, NamedEntityState, SelectEntityId } from '../models';
+export declare function prependEntity<Entity extends {
+    id: EntityId;
+}>(entity: Entity): PartialStateUpdater<EntityState<Entity>>;
+export declare function prependEntity<Entity, Collection extends string>(entity: Entity, config: {
+    collection: Collection;
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function prependEntity<Entity extends {
+    id: EntityId;
+}, Collection extends string>(entity: Entity, config: {
+    collection: Collection;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function prependEntity<Entity>(entity: Entity, config: {
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<EntityState<Entity>>;

package/entities/src/updaters/upsert-entities.d.ts

@@ -0,0 +1,17 @@
+import { PartialStateUpdater } from '@ngrx/signals';
+import { EntityId, EntityState, NamedEntityState, SelectEntityId } from '../models';
+export declare function upsertEntities<Entity extends {
+    id: EntityId;
+}>(entities: Entity[]): PartialStateUpdater<EntityState<Entity>>;
+export declare function upsertEntities<Entity, Collection extends string>(entities: Entity[], config: {
+    collection: Collection;
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function upsertEntities<Entity extends {
+    id: EntityId;
+}, Collection extends string>(entities: Entity[], config: {
+    collection: Collection;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function upsertEntities<Entity>(entities: Entity[], config: {
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<EntityState<Entity>>;

package/entities/src/updaters/upsert-entity.d.ts

@@ -0,0 +1,17 @@
+import { PartialStateUpdater } from '@ngrx/signals';
+import { EntityId, EntityState, NamedEntityState, SelectEntityId } from '../models';
+export declare function upsertEntity<Entity extends {
+    id: EntityId;
+}>(entity: Entity): PartialStateUpdater<EntityState<Entity>>;
+export declare function upsertEntity<Entity, Collection extends string>(entity: Entity, config: {
+    collection: Collection;
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function upsertEntity<Entity extends {
+    id: EntityId;
+}, Collection extends string>(entity: Entity, config: {
+    collection: Collection;
+}): PartialStateUpdater<NamedEntityState<Entity, Collection>>;
+export declare function upsertEntity<Entity>(entity: Entity, config: {
+    selectId: SelectEntityId<NoInfer<Entity>>;
+}): PartialStateUpdater<EntityState<Entity>>;

package/events/index.d.ts

@@ -0,0 +1 @@
+export * from './src/index';

package/events/src/case-reducer.d.ts

@@ -0,0 +1,20 @@
+import { PartialStateUpdater } from '@ngrx/signals';
+import { EventCreator } from './event-creator';
+export type CaseReducerResult<State extends object, EventCreators extends EventCreator<string, any>[]> = {
+    reducer: CaseReducer<State, EventCreators>;
+    events: EventCreators;
+};
+type CaseReducer<State extends object, EventCreators extends EventCreator<string, any>[]> = (event: {
+    [K in keyof EventCreators]: ReturnType<EventCreators[K]>;
+}[number]) => Partial<State> | PartialStateUpdater<State> | Array<Partial<State> | PartialStateUpdater<State>>;
+/**
+ * @experimental
+ * @description
+ *
+ * Creates a case reducer that can be used with the `withReducer` feature.
+ */
+export declare function on<State extends object, EventCreators extends EventCreator<string, any>[]>(...args: [
+    ...events: [...EventCreators],
+    reducer: CaseReducer<NoInfer<State>, NoInfer<EventCreators>>
+]): CaseReducerResult<State, EventCreators>;
+export {};

package/events/src/dispatcher.d.ts

@@ -0,0 +1,33 @@
+import { EventInstance } from './event-instance';
+import { Events, ReducerEvents } from './events-service';
+import * as i0 from "@angular/core";
+/**
+ * @experimental
+ * @description
+ *
+ * Globally provided service for dispatching events.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Dispatcher, event } from '@ngrx/signals/events';
+ *
+ * const increment = event('[Counter Page] Increment');
+ *
+ * \@Component({ \/* ... *\/ })
+ * class Counter {
+ *   readonly #dispatcher = inject(Dispatcher);
+ *
+ *   increment(): void {
+ *     this.#dispatcher.dispatch(increment());
+ *   }
+ * }
+ * ```
+ */
+export declare class Dispatcher {
+    protected readonly reducerEvents: ReducerEvents;
+    protected readonly events: Events;
+    dispatch(event: EventInstance<string, unknown>): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<Dispatcher, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<Dispatcher>;
+}

package/events/src/event-creator-group.d.ts

@@ -0,0 +1,33 @@
+import { Prettify } from '@ngrx/signals';
+import { EventCreator } from './event-creator';
+type EventType<Source extends string, EventName extends string> = `[${Source}] ${EventName}`;
+type EventCreatorGroup<Source extends string, Events extends Record<string, any>> = {
+    [EventName in keyof Events]: EventName extends string ? EventCreator<EventType<Source, EventName>, Events[EventName]> : never;
+};
+/**
+ * @experimental
+ * @description
+ *
+ * Creates a group of event creators.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { type } from '@ngrx/signals';
+ * import { eventGroup } from '@ngrx/signals/events';
+ *
+ * const counterPageEvents = eventGroup({
+ *   source: 'Counter Page',
+ *   events: {
+ *     increment: type<void>(),
+ *     decrement: type<void>(),
+ *     set: type<number>(),
+ *   },
+ * });
+ * ```
+ */
+export declare function eventGroup<Source extends string, Events extends Record<string, unknown>>(config: {
+    source: Source;
+    events: Events;
+}): Prettify<EventCreatorGroup<Source, Events>>;
+export {};

package/events/src/event-creator.d.ts

@@ -0,0 +1,9 @@
+import { EventInstance } from './event-instance';
+/**
+ * @experimental
+ */
+export type EventCreator<Type extends string, Payload> = ((payload: Payload) => EventInstance<Type, Payload>) & {
+    type: Type;
+};
+export declare function event<Type extends string>(type: Type): EventCreator<Type, void>;
+export declare function event<Type extends string, Payload>(type: Type, payload: Payload): EventCreator<Type, Payload>;

package/events/src/event-instance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @experimental
+ */
+export type EventInstance<Type extends string, Payload> = {
+    type: Type;
+    payload: Payload;
+};
+export declare function isEventInstance(value: unknown): value is EventInstance<string, unknown>;

package/events/src/events-service.d.ts

@@ -0,0 +1,47 @@
+import { Observable } from 'rxjs';
+import { EventInstance } from './event-instance';
+import { EventCreator } from './event-creator';
+import * as i0 from "@angular/core";
+export declare const EVENTS: unique symbol;
+export declare const SOURCE_TYPE: unique symbol;
+declare abstract class BaseEvents {
+    on(): Observable<EventInstance<string, unknown>>;
+    on<EventCreators extends EventCreator<string, any>[]>(...events: [...EventCreators]): Observable<{
+        [K in keyof EventCreators]: ReturnType<EventCreators[K]>;
+    }[number]>;
+}
+/**
+ * @experimental
+ * @description
+ *
+ * Globally provided service for listening to dispatched events.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { event, Events } from '@ngrx/signals/events';
+ *
+ * const increment = event('[Counter Page] Increment');
+ *
+ * \@Component({ \/* ... *\/ })
+ * class Counter {
+ *   readonly #events = inject(Events);
+ *
+ *   constructor() {
+ *     this.#events
+ *       .on(increment)
+ *       .pipe(takeUntilDestroyed())
+ *       .subscribe(() => \/* handle increment event *\/);
+ *   }
+ * }
+ * ```
+ */
+export declare class Events extends BaseEvents {
+    static ɵfac: i0.ɵɵFactoryDeclaration<Events, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<Events>;
+}
+export declare class ReducerEvents extends BaseEvents {
+    static ɵfac: i0.ɵɵFactoryDeclaration<ReducerEvents, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ReducerEvents>;
+}
+export {};

package/events/src/index.d.ts

@@ -0,0 +1,9 @@
+export { on } from './case-reducer';
+export { Dispatcher } from './dispatcher';
+export { event, EventCreator } from './event-creator';
+export { eventGroup } from './event-creator-group';
+export { EventInstance } from './event-instance';
+export { Events } from './events-service';
+export { injectDispatch } from './inject-dispatch';
+export { withEffects } from './with-effects';
+export { withReducer } from './with-reducer';

package/events/src/inject-dispatch.d.ts

@@ -0,0 +1,46 @@
+import { Injector } from '@angular/core';
+import { Prettify } from '@ngrx/signals';
+import { EventCreator } from './event-creator';
+type InjectDispatchResult<EventGroup extends Record<string, EventCreator<string, any>>> = {
+    [EventName in keyof EventGroup]: Parameters<EventGroup[EventName]> extends [
+        infer Payload
+    ] ? (payload: Payload) => void : () => void;
+};
+/**
+ * @experimental
+ * @description
+ *
+ * Creates self-dispatching events for a given event group.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { type } from '@ngrx/signals';
+ * import { eventGroup, injectDispatch } from '@ngrx/signals/events';
+ *
+ * const counterPageEvents = eventGroup({
+ *   source: 'Counter Page',
+ *   events: {
+ *     increment: type<void>(),
+ *     decrement: type<void>(),
+ *   },
+ * });
+ *
+ * \@Component({ \/* ... *\/ })
+ * class Counter {
+ *   readonly dispatch = injectDispatch(counterPageEvents);
+ *
+ *   increment(): void {
+ *     this.dispatch.increment();
+ *   }
+ *
+ *   decrement(): void {
+ *     this.dispatch.decrement();
+ *   }
+ * }
+ * ```
+ */
+export declare function injectDispatch<EventGroup extends Record<string, EventCreator<string, any>>>(events: EventGroup, config?: {
+    injector?: Injector;
+}): Prettify<InjectDispatchResult<EventGroup>>;
+export {};

package/events/src/with-effects.d.ts

@@ -0,0 +1,28 @@
+import { Observable } from 'rxjs';
+import { EmptyFeatureResult, Prettify, SignalStoreFeature, SignalStoreFeatureResult, StateSignals, WritableStateSource } from '@ngrx/signals';
+/**
+ * @experimental
+ * @description
+ *
+ * SignalStore feature for defining side effects.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signalStore, withState } from '@ngrx/signals';
+ * import { event, Events, withEffects } from '@ngrx/signals/events';
+ *
+ * const increment = event('[Counter Page] Increment');
+ * const decrement = event('[Counter Page] Decrement');
+ *
+ * const CounterStore = signalStore(
+ *   withState({ count: 0 }),
+ *   withEffects(({ count }, events = inject(Events)) => ({
+ *     logCount$: events.on(increment, decrement).pipe(
+ *       tap(({ type }) => console.log(type, count())),
+ *     ),
+ *   })),
+ * );
+ * ```
+ */
+export declare function withEffects<Input extends SignalStoreFeatureResult>(effectsFactory: (store: Prettify<StateSignals<Input['state']> & Input['props'] & Input['methods'] & WritableStateSource<Prettify<Input['state']>>>) => Record<string, Observable<unknown>>): SignalStoreFeature<Input, EmptyFeatureResult>;

package/events/src/with-reducer.d.ts

@@ -0,0 +1,30 @@
+import { EmptyFeatureResult, SignalStoreFeature } from '@ngrx/signals';
+import { CaseReducerResult } from './case-reducer';
+import { EventCreator } from './event-creator';
+/**
+ * @experimental
+ * @description
+ *
+ * SignalStore feature for defining state changes based on dispatched events.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signalStore, type, withState } from '@ngrx/signals';
+ * import { event, on, withReducer } from '@ngrx/signals/events';
+ *
+ * const set = event('[Counter Page] Set', type<number>());
+ *
+ * const CounterStore = signalStore(
+ *   withState({ count: 0 }),
+ *   withReducer(
+ *     on(set, ({ payload }) => ({ count: payload })),
+ *   ),
+ * );
+ * ```
+ */
+export declare function withReducer<State extends object>(...caseReducers: CaseReducerResult<State, EventCreator<string, any>[]>[]): SignalStoreFeature<{
+    state: State;
+    props: {};
+    methods: {};
+}, EmptyFeatureResult>;

package/fesm2022/ngrx-signals-entities.mjs

@@ -41,39 +41,46 @@ function getEntityUpdaterResult(state, stateKeys, didMutate) {
         }
     }
 }
-function addEntityMutably(state, entity, selectId) {
+function addEntityMutably(state, entity, selectId, prepend = false) {
     const id = selectId(entity);
     if (state.entityMap[id]) {
         return DidMutate.None;
     }
     state.entityMap[id] = entity;
-    state.ids.push(id);
+    if (prepend) {
+        state.ids.unshift(id);
+    }
+    else {
+        state.ids.push(id);
+    }
     return DidMutate.Both;
 }
-function addEntitiesMutably(state, entities, selectId) {
+function addEntitiesMutably(state, entities, selectId, prepend = false) {
     let didMutate = DidMutate.None;
     for (const entity of entities) {
-        const result = addEntityMutably(state, entity, selectId);
+        const result = addEntityMutably(state, entity, selectId, prepend);
         if (result === DidMutate.Both) {
             didMutate = result;
         }
     }
     return didMutate;
 }
-function setEntityMutably(state, entity, selectId) {
+function setEntityMutably(state, entity, selectId, replace = true) {
     const id = selectId(entity);
     if (state.entityMap[id]) {
-        state.entityMap[id] = entity;
+        state.entityMap[id] = replace
+            ? entity
+            : { ...state.entityMap[id], ...entity };
         return DidMutate.Entities;
     }
     state.entityMap[id] = entity;
     state.ids.push(id);
     return DidMutate.Both;
 }
-function setEntitiesMutably(state, entities, selectId) {
+function setEntitiesMutably(state, entities, selectId, replace = true) {
     let didMutate = DidMutate.None;
     for (const entity of entities) {
-        const result = setEntityMutably(state, entity, selectId);
+        const result = setEntityMutably(state, entity, selectId, replace);
         if (didMutate === DidMutate.Both) {
             continue;
         }
@@ -122,7 +129,9 @@ function updateEntitiesMutably(state, idsOrPredicate, changes, selectId) {
         state.ids = state.ids.map((id) => newIds[id] ?? id);
         didMutate = DidMutate.Both;
     }
-    if (ngDevMode && state.ids.length !== Object.keys(state.entityMap).length) {
+    if (typeof ngDevMode !== 'undefined' &&
+        ngDevMode &&
+        state.ids.length !== Object.keys(state.entityMap).length) {
         console.warn('@ngrx/signals/entities: Entities with IDs:', ids, 'are not updated correctly.', 'Make sure to apply valid changes when using `updateEntity`,', '`updateEntities`, and `updateAllEntities` updaters.');
     }
     return didMutate;
@@ -148,6 +157,35 @@ function addEntities(entities, config) {
     };
 }
 
+function prependEntity(entity, config) {
+    const selectId = getEntityIdSelector(config);
+    const stateKeys = getEntityStateKeys(config);
+    return (state) => {
+        const clonedState = cloneEntityState(state, stateKeys);
+        const didMutate = addEntityMutably(clonedState, entity, selectId, true);
+        return getEntityUpdaterResult(clonedState, stateKeys, didMutate);
+    };
+}
+
+function prependEntities(entities, config) {
+    const selectId = getEntityIdSelector(config);
+    const stateKeys = getEntityStateKeys(config);
+    return (state) => {
+        const clonedState = cloneEntityState(state, stateKeys);
+        const uniqueEntities = [];
+        const seenIds = new Set();
+        for (const entity of entities) {
+            const id = selectId(entity);
+            if (!seenIds.has(id)) {
+                uniqueEntities.unshift(entity);
+                seenIds.add(id);
+            }
+        }
+        const didMutate = addEntitiesMutably(clonedState, uniqueEntities, selectId, true);
+        return getEntityUpdaterResult(clonedState, stateKeys, didMutate);
+    };
+}
+
 function removeEntity(id, config) {
     const stateKeys = getEntityStateKeys(config);
     return (state) => {
@@ -238,6 +276,26 @@ function updateAllEntities(changes, config) {
     };
 }
 
+function upsertEntity(entity, config) {
+    const selectId = getEntityIdSelector(config);
+    const stateKeys = getEntityStateKeys(config);
+    return (state) => {
+        const clonedState = cloneEntityState(state, stateKeys);
+        const didMutate = setEntityMutably(clonedState, entity, selectId, false);
+        return getEntityUpdaterResult(clonedState, stateKeys, didMutate);
+    };
+}
+
+function upsertEntities(entities, config) {
+    const selectId = getEntityIdSelector(config);
+    const stateKeys = getEntityStateKeys(config);
+    return (state) => {
+        const clonedState = cloneEntityState(state, stateKeys);
+        const didMutate = setEntitiesMutably(clonedState, entities, selectId, false);
+        return getEntityUpdaterResult(clonedState, stateKeys, didMutate);
+    };
+}
+
 function entityConfig(config) {
     return config;
 }
@@ -260,5 +318,5 @@ function withEntities(config) {
  * Generated bundle index. Do not edit.
  */
 
-export { addEntities, addEntity, entityConfig, removeAllEntities, removeEntities, removeEntity, setAllEntities, setEntities, setEntity, updateAllEntities, updateEntities, updateEntity, withEntities };
+export { addEntities, addEntity, entityConfig, prependEntities, prependEntity, removeAllEntities, removeEntities, removeEntity, setAllEntities, setEntities, setEntity, updateAllEntities, updateEntities, updateEntity, upsertEntities, upsertEntity, withEntities };
 //# sourceMappingURL=ngrx-signals-entities.mjs.map