feat(store): add withExperimentalNgxsPendingTasks

CHANGELOG.md

@@ -6,6 +6,7 @@ $ npm install @ngxs/store@dev
 
 ### To become next patch version
 
+- Feat(store): Add `withExperimentalNgxsPendingTasks` [#2186](https://github.com/ngxs/store/pull/2186)
 - Fix(store): Decouple state signal updates from synchronous changes [#2189](https://github.com/ngxs/store/pull/2189)
 
 ### 18.0.0 2024-06-10

docs/SUMMARY.md

@@ -69,7 +69,7 @@
   - [Module Federation](recipes/module-federation.md)
   - [Unit Testing](recipes/unit-testing.md)
   - [RxAngular Integration](recipes/intregration-with-rxangular.md)
-  - [Waiting For App Stability](recipes/waiting-for-app-stability.md)
+  - [Zoneless Server-Side Rendering](recipes/zoneless-ssr.md)
 
 ## COMMUNITY & LABS
 

docs/recipes/waiting-for-app-stability.md → docs/recipes/zoneless-ssr.md

@@ -1,4 +1,4 @@
-# Waiting For App Stability
+# Zoneless Server-Side Rendering
 
 > :warning: Note that the current recipe may be used starting from Angular 18 because the experimental API was publicly exposed in Angular 18.
 
@@ -11,37 +11,11 @@ NGXS also executes actions during server-side rendering, and some of these actio
 Let's examine the recipe for updating the "pending tasks" state whenever any action is dispatched and completed:
 
 ```ts
-import { ApplicationConfig, inject, ExperimentalPendingTasks } from '@angular/core';
-import { ActionStatus, Actions, provideStore, withNgxsPreboot } from '@ngxs/store';
+import { ApplicationConfig } from '@angular/core';
+import { provideStore } from '@ngxs/store';
+import { withExperimentalNgxsPendingTasks } from '@ngxs/store/experimental';
 
 export const appConfig: ApplicationConfig = {
-  providers: [
-    provideStore(
-      [],
-      withNgxsPreboot(() => {
-        const pendingTasks = inject(ExperimentalPendingTasks);
-        const actions$ = inject(Actions);
-
-        const actionToRemoveTaskFnMap = new Map<any, () => void>();
-
-        // Note that you don't have to unsubscribe from the actions stream in
-        // this specific case, as we complete the actions subject when the root
-        // view is destroyed. In server-side rendering, the root view is destroyed
-        // immediately once the app stabilizes and its HTML is serialized.
-        actions$.subscribe(ctx => {
-          if (ctx.status === ActionStatus.Dispatched) {
-            const removeTaskFn = pendingTasks.add();
-            actionToRemoveTaskFnMap.set(ctx.action, removeTaskFn);
-          } else {
-            const removeTaskFn = actionToRemoveTaskFnMap.get(ctx.action);
-            if (typeof removeTaskFn === 'function') {
-              removeTaskFn();
-              actionToRemoveTaskFnMap.delete(ctx.action);
-            }
-          }
-        });
-      })
-    )
-  ]
+  providers: [provideStore([], withExperimentalNgxsPendingTasks())]
 };
 ```

packages/store/experimental/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../../node_modules/ng-packagr/ng-package.schema.json",
+  "lib": {
+    "entryFile": "src/index.ts",
+    "flatModuleFile": "ngxs-store-experimental"
+  }
+}

packages/store/experimental/src/index.ts

@@ -0,0 +1 @@
+export { withExperimentalNgxsPendingTasks } from './pending-tasks';

packages/store/experimental/src/pending-tasks.ts

@@ -0,0 +1,31 @@
+import { inject, ExperimentalPendingTasks } from '@angular/core';
+import { ActionStatus, Actions, withNgxsPreboot } from '@ngxs/store';
+
+/**
+ * This is an experimental feature that contributes to app stability,
+ * which is required during server-side rendering. With asynchronous
+ * actions being dispatched and handled, Angular is unaware of them in
+ * zoneless mode and doesn't know whether the app is still unstable.
+ * This may prematurely serialize the final HTML that is sent to the client.
+ */
+export function withExperimentalNgxsPendingTasks() {
+  return withNgxsPreboot(() => {
+    const pendingTasks = inject(ExperimentalPendingTasks);
+    const actions$ = inject(Actions);
+
+    const actionToRemoveTaskFnMap = new Map<any, () => void>();
+
+    actions$.subscribe(ctx => {
+      if (ctx.status === ActionStatus.Dispatched) {
+        const removeTaskFn = pendingTasks.add();
+        actionToRemoveTaskFnMap.set(ctx.action, removeTaskFn);
+      } else {
+        const removeTaskFn = actionToRemoveTaskFnMap.get(ctx.action);
+        if (typeof removeTaskFn === 'function') {
+          removeTaskFn();
+          actionToRemoveTaskFnMap.delete(ctx.action);
+        }
+      }
+    });
+  });
+}

packages/store/tests/standalone-features/preboot-wait-stable.spec.ts → packages/store/experimental/tests/preboot-wait-stable.spec.ts

@@ -3,46 +3,22 @@ import {
   AfterViewInit,
   Component,
   Injectable,
-  inject,
-  ExperimentalPendingTasks,
   provideExperimentalZonelessChangeDetection,
   ChangeDetectionStrategy
 } from '@angular/core';
 import { bootstrapApplication } from '@angular/platform-browser';
 import { renderApplication } from '@angular/platform-server';
 import {
   Action,
-  ActionStatus,
-  Actions,
   State,
   StateContext,
   StateToken,
   dispatch,
   provideStore,
-  select,
-  withNgxsPreboot
+  select
 } from '@ngxs/store';
 import { freshPlatform } from '@ngxs/store/internals/testing';
-
-function executeRecipeFromDocs() {
-  const pendingTasks = inject(ExperimentalPendingTasks);
-  const actions$ = inject(Actions);
-
-  const actionToRemoveTaskFnMap = new Map<any, () => void>();
-
-  actions$.subscribe(ctx => {
-    if (ctx.status === ActionStatus.Dispatched) {
-      const removeTaskFn = pendingTasks.add();
-      actionToRemoveTaskFnMap.set(ctx.action, removeTaskFn);
-    } else {
-      const removeTaskFn = actionToRemoveTaskFnMap.get(ctx.action);
-      if (typeof removeTaskFn === 'function') {
-        removeTaskFn();
-        actionToRemoveTaskFnMap.delete(ctx.action);
-      }
-    }
-  });
-}
+import { withExperimentalNgxsPendingTasks } from '@ngxs/store/experimental';
 
 describe('preboot feature + stable', () => {
   const COUNTRIES_STATE_TOKEN = new StateToken<string[]>('countries');
@@ -92,7 +68,7 @@ describe('preboot feature + stable', () => {
             providers: [
               provideExperimentalZonelessChangeDetection(),
 
-              provideStore([CountriesState], withNgxsPreboot(executeRecipeFromDocs))
+              provideStore([CountriesState], withExperimentalNgxsPendingTasks())
             ]
           }),
         {

tsconfig.base.json

@@ -29,6 +29,7 @@
       "@ngxs/storage-plugin": ["packages/storage-plugin/index.ts"],
       "@ngxs/storage-plugin/internals": ["packages/storage-plugin/internals/src/index.ts"],
       "@ngxs/store": ["packages/store/index.ts"],
+      "@ngxs/store/experimental": ["packages/store/experimental/src/index.ts"],
       "@ngxs/store/internals": ["packages/store/internals/src/index.ts"],
       "@ngxs/store/internals/testing": ["packages/store/internals/testing/src/index.ts"],
       "@ngxs/store/operators": ["packages/store/operators/src/index.ts"],