Skip to content

docs: add import statements to doc pages #162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/docs/create-redux-state.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: createReduxState()
---

```typescript
import { createReduxState } from '@angular-architects/ngrx-toolkit/redux-connector';
```

The Redux Connector it is not an extension but turns any `signalStore()` into a Global State Management Slice following the Redux pattern.

It is available as secondary entry point, i.e. `import { createReduxState } from '@angular-architects/ngrx-toolkit/redux-connector'` and has a dependency to `@ngrx/store`.
Expand Down
6 changes: 6 additions & 0 deletions docs/docs/with-conditional.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: withConditional()
---

```typescript
import { withConditional } from '@angular-architects/ngrx-toolkit';
```

`withConditional` activates a feature based on a given condition.

## Use Cases
Expand All @@ -17,6 +21,8 @@ Otherwise, a type error will occur.
## Usage

```typescript
import { withConditional } from '@angular-architects/ngrx-toolkit';

const withUser = signalStoreFeature(
withState({ id: 1, name: 'Konrad' }),
withHooks((store) => ({
Expand Down
8 changes: 8 additions & 0 deletions docs/docs/with-data-service.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,17 @@
title: withDataService()
---

```typescript
import { withDataService } from '@angular-architects/ngrx-toolkit';
```

`withDataService()` allows to connect a Data Service to the store:

This gives you a store for a CRUD use case:

```typescript
import { withDataService, withCallState, withUndoRedo } from '@angular-architects/ngrx-toolkit';

export const SimpleFlightBookingStore = signalStore(
{ providedIn: 'root' },
withCallState(),
Expand Down Expand Up @@ -86,6 +92,8 @@ export class FlightSearchSimpleComponent {
To avoid naming conflicts, the properties set up by `withDataService` and the connected features can be configured in a typesafe way:

```typescript
import { withDataService, withCallState, withUndoRedo } from '@angular-architects/ngrx-toolkit';

export const FlightBookingStore = signalStore(
{ providedIn: 'root' },
withCallState({
Expand Down
36 changes: 36 additions & 0 deletions docs/docs/with-devtools.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,17 @@
title: withDevtools()
---

```typescript
import { withDevtools } from '@angular-architects/ngrx-toolkit';
```

Redux Devtools is a powerful browser extension tool, that allows you to inspect every change in your stores. Originally, it was designed for Redux, but it can also be used with the SignalStore. You can download it for Chrome [here](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd).

To use the Devtools, you need to add the `withDevtools()` extension to your SignalStore:

```typescript
import { withDevtools } from '@angular-architects/ngrx-toolkit';

export const FlightStore = signalStore(
{ providedIn: 'root' },
withDevtools('flights'), // <-- add this
Expand All @@ -27,9 +33,15 @@ The extensions don't activate during app initialization (as it is with `@ngrx/st

## `updateState()` vs `patchState()`

```typescript
import { updateState } from '@angular-architects/ngrx-toolkit';
```

The Signal Store does not use the Redux pattern, so there are no action names involved by default. Instead, every action is referred to as a "Store Update". If you want to customize the action name for better clarity, you can use the `updateState()` function instead of `patchState()`:

```typescript
import { updateState } from '@angular-architects/ngrx-toolkit';

patchState(this.store, { loading: false });

// updateState is a wrapper around patchState and has an action name as second parameter
Expand All @@ -38,13 +50,19 @@ updateState(this.store, 'update loading', { loading: false });

## `renameDevtoolsName()`

```typescript
import { renameDevtoolsName } from '@angular-architects/ngrx-toolkit';
```

If multiple instances of a given SignalStore exist, the Devtools will index the names. For example, if you have two `TodoDetail` instances with the name `todo-detail`, the first one will be named `todo-detail` and the second one `todo-detail-1`.

At any time, you can use `renameDevtoolsName()` to change the name of the store in the Devtools.

The following example shows a component, which has a locally provided store and renames it according to the `id` of the `todo` Signal.

```typescript
import { renameDevtoolsName, withDevtools } from '@angular-architects/ngrx-toolkit';

const TodoDetailStore = signalStore(withDevtools('todo-detail'), withState({ id: 1 }));

@Component({
Expand All @@ -65,6 +83,10 @@ export class TodoDetailComponent {

## `withGlitchTracking()`

```typescript
import { withGlitchTracking } from '@angular-architects/ngrx-toolkit';
```

It tracks all state changes of the State, including intermediary updates
that are typically suppressed by Angular's glitch-free mechanism.

Expand All @@ -73,6 +95,8 @@ This feature is especially useful for debugging.
Example:

```typescript
import { withGlitchTracking, withDevtools } from '@angular-architects/ngrx-toolkit';

const Store = signalStore(
{ providedIn: 'root' },
withState({ count: 0 }),
Expand All @@ -96,23 +120,35 @@ It is also possible to mix. So one store could have `withGlitchTracking()` and a

## `withDisabledNameIndices()`

```typescript
import { withDisabledNameIndices } from '@angular-architects/ngrx-toolkit';
```

`withDevtools()` foresees the possibility to add features which extend or modify it. At the moment, `withDisabledNameIndices()` is the only feature available. It disables the automatic indexing of the store names in the Devtools.

If multiple instances exist at the same time, `withDisabledNameIndices()` will throw an error. This is useful if you want to ensure that only one instance of a store is active at a time or that the store name is unique.

You activate per store:

```typescript
import { withDisabledNameIndices, withDevtools } from '@angular-architects/ngrx-toolkit';

const Store = signalStore({ providedIn: 'root' }, withDevtools('flights', withDisabledNameIndices()), withState({ airline: 'Lufthansa' }));
```

## `withMapper()`

```typescript
import { withMapper } from '@angular-architects/ngrx-toolkit';
```

`withMapper()` allows you to define a function that maps the state before it is sent to the Devtools.

Sometimes, it is necessary to map the state before it is sent to the Devtools. For example, you might want to exclude some properties, like passwords or other sensitive data.

```typescript
import { withMapper, withDevtools } from '@angular-architects/ngrx-toolkit';

const initialState = {
id: 1,
email: 'john.list@host.com',
Expand Down
10 changes: 10 additions & 0 deletions docs/docs/with-feature-factory.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,17 @@
title: withFeatureFactory()
---

```typescript
import { withFeatureFactory } from '@angular-architects/ngrx-toolkit';
```

The `withFeatureFactory()` function allows passing properties, methods, or signals from a SignalStore to a feature. It is an advanced feature, primarily targeted for library authors for SignalStore features.

Its usage is very simple. It is a function which gets the current store:

```typescript
import { withFeatureFactory } from '@angular-architects/ngrx-toolkit';

function withSum(a: Signal<number>, b: Signal<number>) {
return signalStoreFeature(
withComputed(() => ({
Expand Down Expand Up @@ -103,6 +109,8 @@ function withEntityLoader(load: (id: number) => Promise<Entity>) {
`withFeatureFactory` can now map the existing `load` method to the required one.

```typescript
import { withFeatureFactory } from '@angular-architects/ngrx-toolkit';

const store = signalStore(
withMethods((store) => ({
load(id: number): Observable<Entity> {
Expand Down Expand Up @@ -171,6 +179,8 @@ signalStore(
Again, `withFeatureFactory` can solve this issue by replacing the input constraint with a function parameter:

```typescript
import { withFeatureFactory } from '@angular-architects/ngrx-toolkit';

function withEntityLoader<T>(loader: (id: number) => Promise<T>) {
return signalStoreFeature(
withState({
Expand Down
8 changes: 8 additions & 0 deletions docs/docs/with-immutable-state.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: withImmutableState()
---

```typescript
import { withImmutableState } from '@angular-architects/ngrx-toolkit';
```

`withImmutableState` acts like `withState` but protects
the state against unintended mutable changes, by throwing
a runtime error.
Expand All @@ -10,6 +14,8 @@ The protection is not limited to changes within the
SignalStore but also outside of it.

```typescript
import { withImmutableState } from '@angular-architects/ngrx-toolkit';

const initialState = { user: { id: 1, name: 'Konrad' } };

const UserStore = signalStore(
Expand Down Expand Up @@ -62,5 +68,7 @@ By default, `withImmutableState` is only active in development mode.
There is a way to enable it in production mode as well:

```typescript
import { withImmutableState } from '@angular-architects/ngrx-toolkit';

const UserStore = signalStore({ providedIn: 'root' }, withImmutableState(initialState, { enableInProduction: true }));
```
20 changes: 20 additions & 0 deletions docs/docs/with-redux.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: withRedux()
---

```typescript
import { withRedux } from '@angular-architects/ngrx-toolkit';
```

`withRedux()` brings back the Redux pattern into the Signal Store.

It can be combined with any other extension of the Signal Store.
Expand All @@ -17,6 +21,8 @@ There is also a [Redux Connector](./create-redux-state) available, which is a se
Example:

```typescript
import { withRedux } from '@angular-architects/ngrx-toolkit';

export const FlightStore = signalStore(
{ providedIn: 'root' },
withState({ flights: [] as Flight[] }),
Expand Down Expand Up @@ -53,13 +59,23 @@ export const FlightStore = signalStore(

## Extracting actions, reducer and effects into separate files

```typescript
import { createReducer } from '@angular-architects/ngrx-toolkit';
```

```typescript
import { createEffects } from '@angular-architects/ngrx-toolkit';
```

`createReducer` and `createEffects` allow you to extract the reducer and effects into separate files.

There is no need for a `createActions` function, because the actions are just an object literal.

Example:

```typescript
import { withRedux, createReducer, createEffects } from '@angular-architects/ngrx-toolkit';

interface FlightState {
flights: Flight[];
effect1: boolean;
Expand Down Expand Up @@ -110,6 +126,10 @@ signalStore(

### Configuring the Redux Devtools Extension

```typescript
import { provideDevtoolsConfig } from '@angular-architects/ngrx-toolkit';
```

The `provideDevtoolsConfig` function allows you to configure the Redux DevTools integration for your NgRx SignalStore. This function is essential for setting up the DevTools with custom options. The function only needs to be called once in your appConfig or AppModule.

To use `provideDevtoolsConfig`, you need to import it and call it in your providers array.
Expand Down
11 changes: 11 additions & 0 deletions docs/docs/with-reset.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,17 @@
title: withReset()
---

```typescript
import { withReset } from '@angular-architects/ngrx-toolkit';
```

`withReset()` adds a method to reset the state of the Signal Store to its initial value. Nothing more to say about it 😅

Example:

```typescript
import { withReset } from '@angular-architects/ngrx-toolkit';

const Store = signalStore(
withState({
user: { id: 1, name: 'Konrad' },
Expand Down Expand Up @@ -34,12 +40,17 @@ console.log(store.user()); // { id: 1, name: 'Konrad' }

## `setResetState()`

```typescript
import { setResetState } from '@angular-architects/ngrx-toolkit';
```

If you want to set a custom reset state, you can use the `setResetState()` method.

Example:

```typescript
// continue from the previous example
import { setResetState } from '@angular-architects/ngrx-toolkit';

setResetState(store, { user: { id: 3, name: 'Jane' }, address: { city: 'Berlin', zip: '10115' } });
store.changeUser(4, 'Alice');
Expand Down
6 changes: 6 additions & 0 deletions docs/docs/with-storage-sync.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
title: withStorageSync()
---

```typescript
import { withStorageSync } from '@angular-architects/ngrx-toolkit';
```

`withStorageSync` adds automatic or manual synchronization with Web Storage (`localstorage`/`sessionstorage`).

:::warning
Expand All @@ -11,6 +15,8 @@ As Web Storage only works in browser environments it will fallback to a stub imp
Example:

```typescript
import { withStorageSync } from '@angular-architects/ngrx-toolkit';

const SyncStore = signalStore(
withStorageSync<User>({
key: 'synced', // key used when writing to/reading from storage
Expand Down
6 changes: 6 additions & 0 deletions docs/docs/with-undo-redo.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,17 @@
title: withUndoRedo()
---

```typescript
import { withUndoRedo } from '@angular-architects/ngrx-toolkit';
```

`withUndoRedo` adds undo and redo functionality to the store.

Example:

```typescript
import { withUndoRedo } from '@angular-architects/ngrx-toolkit';

const SyncStore = signalStore(
withUndoRedo({
maxStackSize: 100, // limit of undo/redo steps - `100` by default
Expand Down