docs(signals): add API docs for Entities plugin (#5071)

Author: markostanimirovic

modules/signals/entities/src/entity-config.ts

@@ -14,6 +14,37 @@ export function entityConfig<Entity, Collection extends string>(config: {
   collection: Collection;
 }): typeof config;
 export function entityConfig<Entity>(config: { entity: Entity }): typeof config;
+/**
+ * @description
+ *
+ * Creates a custom entity configuration and ensures strong typing.
+ * Allows defining named entity collections and a custom id selector.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signalStore, type, withMethods } from '@ngrx/signals';
+ * import { addEntity, entityConfig, withEntities } from '@ngrx/signals/entities';
+ *
+ * type Todo = { key: number; text: string };
+ *
+ * const todoConfig = entityConfig({
+ *   entity: type<Todo>(),
+ *   collection: 'todo',
+ *   selectId: (todo) => todo.key,
+ * });
+ *
+ * export const TodosStore = signalStore(
+ *   // 👇 Adds `todoEntityMap`, `todoIds`, and `todoEntities` signals to the store.
+ *   withEntities(todoConfig),
+ *   withMethods((store) => ({
+ *     addTodo(todo: Todo): void {
+ *       patchState(store, addEntity(todo, todoConfig));
+ *     },
+ *   }))
+ * );
+ * ```
+ */
 export function entityConfig<Entity>(config: {
   entity: Entity;
   collection?: string;

modules/signals/entities/src/updaters/add-entities.ts

@@ -31,6 +31,21 @@ export function addEntities<Entity>(
   entities: Entity[],
   config: { selectId: SelectEntityId<NoInfer<Entity>> }
 ): PartialStateUpdater<EntityState<Entity>>;
+/**
+ * @description
+ *
+ * Adds multiple entities to the collection.
+ * Does not override existing entities with same IDs.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { addEntities } from '@ngrx/signals/entities';
+ *
+ * patchState(store, addEntities([todo1, todo2]));
+ * ```
+ */
 export function addEntities(
   entities: any[],
   config?: { collection?: string; selectId?: SelectEntityId<any> }

modules/signals/entities/src/updaters/add-entity.ts

@@ -31,6 +31,21 @@ export function addEntity<Entity>(
   entity: Entity,
   config: { selectId: SelectEntityId<NoInfer<Entity>> }
 ): PartialStateUpdater<EntityState<Entity>>;
+/**
+ * @description
+ *
+ * Adds an entity to the collection.
+ * Does not override if entity with same ID exists.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { addEntity } from '@ngrx/signals/entities';
+ *
+ * patchState(store, addEntity(todo));
+ * ```
+ */
 export function addEntity(
   entity: any,
   config?: { collection?: string; selectId?: SelectEntityId<any> }

modules/signals/entities/src/updaters/prepend-entities.ts

@@ -31,6 +31,21 @@ export function prependEntities<Entity>(
   entities: Entity[],
   config: { selectId: SelectEntityId<NoInfer<Entity>> }
 ): PartialStateUpdater<EntityState<Entity>>;
+/**
+ * @description
+ *
+ * Adds multiple entities to the beginning of the collection.
+ * Does not add existing entities with same IDs.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { prependEntities } from '@ngrx/signals/entities';
+ *
+ * patchState(store, prependEntities([todo1, todo2]));
+ * ```
+ */
 export function prependEntities(
   entities: any[],
   config?: { collection?: string; selectId?: SelectEntityId<any> }

modules/signals/entities/src/updaters/prepend-entity.ts

@@ -31,6 +31,21 @@ export function prependEntity<Entity>(
   entity: Entity,
   config: { selectId: SelectEntityId<NoInfer<Entity>> }
 ): PartialStateUpdater<EntityState<Entity>>;
+/**
+ * @description
+ *
+ * Adds an entity to the beginning of the collection.
+ * Does not add if entity with same ID exists.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { prependEntity } from '@ngrx/signals/entities';
+ *
+ * patchState(store, prependEntity(todo));
+ * ```
+ */
 export function prependEntity(
   entity: any,
   config?: { collection?: string; selectId?: SelectEntityId<any> }

modules/signals/entities/src/updaters/remove-all-entities.ts

@@ -6,6 +6,20 @@ export function removeAllEntities(): PartialStateUpdater<EntityState<any>>;
 export function removeAllEntities<Collection extends string>(config: {
   collection: Collection;
 }): PartialStateUpdater<NamedEntityState<any, Collection>>;
+/**
+ * @description
+ *
+ * Removes all entities from the collection.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { removeAllEntities } from '@ngrx/signals/entities';
+ *
+ * patchState(store, removeAllEntities());
+ * ```
+ */
 export function removeAllEntities(config?: {
   collection?: string;
 }): PartialStateUpdater<EntityState<any> | NamedEntityState<any, string>> {

modules/signals/entities/src/updaters/remove-entities.ts

@@ -30,6 +30,24 @@ export function removeEntities<
   predicate: EntityPredicate<Entity>,
   config: { collection: Collection }
 ): PartialStateUpdater<State>;
+/**
+ * @description
+ *
+ * Removes multiple entities from the collection by IDs or predicate.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { removeEntities } from '@ngrx/signals/entities';
+ *
+ * // Remove by IDs
+ * patchState(store, removeEntities([1, 2, 3]));
+ *
+ * // Remove by predicate
+ * patchState(store, removeEntities((todo) => todo.completed));
+ * ```
+ */
 export function removeEntities(
   idsOrPredicate: EntityId[] | EntityPredicate<any>,
   config?: { collection?: string }

modules/signals/entities/src/updaters/remove-entity.ts

@@ -14,6 +14,20 @@ export function removeEntity<Collection extends string>(
   id: EntityId,
   config: { collection: Collection }
 ): PartialStateUpdater<NamedEntityState<any, Collection>>;
+/**
+ * @description
+ *
+ * Removes an entity from the collection by ID.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { removeEntity } from '@ngrx/signals/entities';
+ *
+ * patchState(store, removeEntity(1));
+ * ```
+ */
 export function removeEntity(
   id: EntityId,
   config?: { collection?: string }

modules/signals/entities/src/updaters/set-all-entities.ts

@@ -29,6 +29,20 @@ export function setAllEntities<Entity>(
   entities: Entity[],
   config: { selectId: SelectEntityId<NoInfer<Entity>> }
 ): PartialStateUpdater<EntityState<Entity>>;
+/**
+ * @description
+ *
+ * Replaces the entire entity collection with the provided entities.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { setAllEntities } from '@ngrx/signals/entities';
+ *
+ * patchState(store, setAllEntities([todo1, todo2, todo3]));
+ * ```
+ */
 export function setAllEntities(
   entities: any[],
   config?: { collection?: string; selectId?: SelectEntityId<any> }

modules/signals/entities/src/updaters/set-entities.ts

@@ -31,6 +31,20 @@ export function setEntities<Entity>(
   entities: Entity[],
   config: { selectId: SelectEntityId<NoInfer<Entity>> }
 ): PartialStateUpdater<EntityState<Entity>>;
+/**
+ * @description
+ *
+ * Adds or replaces multiple entities in the collection.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState } from '@ngrx/signals';
+ * import { setEntities } from '@ngrx/signals/entities';
+ *
+ * patchState(store, setEntities([todo1, todo2]));
+ * ```
+ */
 export function setEntities(
   entities: any[],
   config?: { collection?: string; selectId?: SelectEntityId<any> }