📚 [DOCS]: Share your custom State Operators here!

[markwhitfeld]

NGXS Provides some default state operators but the real power is in the pattern it offers.
Please share your custom state operators here, someone else may find them useful.
If they are general purpose, logical and popular then they might even get added to the default operators in the lib!

RULES to keep this thread clean:

• Please only submit one comment per operator (pointless comments will be deleted).
• Vote for the operators using the standard emojis (please don't add needless comments)
• In your comment please provide the following:
  • A description of the use case for the operator
  • A usage example of the operator as code
  • A link to a github gist with your operator and preferably tests too!
  • Any other useful information

PS. What makes a good operator?

• It only returns a new state if changes are needed. For Example:
  • if there is a predicate and it is not matched, then just return the original state
  • if the new value equals the old value, then just return the original state
• It is composable (you can pass other operators in, if applicable)
  • if a parameter requires a value then provide the option of passing an operator or a value (where it makes sense - ie. for updateItem but not for insertItem)
• These are good examples:
  • updateItem.ts
  • iif.ts

PS. If you have no clue what this is about read this article.

[markwhitfeld]

(As an example)

Use Case:

Sometimes we need to modify the state only if some condition is true. This operator will help you out here!

Example:

setState(
  iif((state) => state.message === 'Hello', 
    patch<MyState>({ waving: true }),
    patch<MyState>({ waving: false })
  )
);

The Code:

Source: iif.ts
Tests: iif.spec.ts
(... or just a gist link here if you have a gist with the source and tests 🚀 )

[mailok]

Hi! @markwhitfeld This is my operator proposal.
I took your advice of what you answered me: https://twitter.com/MarkWhitfeld/status/1106659719068950530
https://twitter.com/MarkWhitfeld/status/1106656004320755713

Use Case:

Sometimes we need to modify multiple elements of an array only if some condition is true or a array of indices. This operator will help you out here!
Examples:
1-Complete all Todos:

2-Complete only if text is 'ipsum':

3-Complete only idices 0 and 2:

Source: https://github.com/mailok/todo-ngxs/blob/master/src/app/store/operators/update-many-items.ts
Test: https://github.com/mailok/todo-ngxs/blob/master/src/app/store/operators/update-many-items.spec.ts
Utils: https://github.com/mailok/todo-ngxs/blob/master/src/app/store/operators/utils.ts

[mailok]

and another proposal

Use Case:

Sometimes we need to remove multiple elements of an array only if some condition is true or a array of indices. This operator will help you out here!

Examples:
1-Remove all Todos complete:

2-Remove index 1 and 2:

Source: https://github.com/mailok/todo-ngxs/blob/master/src/app/store/operators/remove-many-items.ts

[beaussan]

Use Case:

In our app, we have a lot of state that looks like this :

{
  folder1: [{name: 'file1'}, {name: 'file2'}, {name: 'file3'}],
  folder2: [{name: 'file5'}, {name: 'file4'}],
}

And the key are dynamic and can be added at runtime.

So we created an operator patchKey to work on a key, and create it if not created.

Example:

It can be used to set the value :

setState(
  patchKey('folder1', [{"name": "file5"}]),
);

Or to apply a state operator to the value :

setState(
  patchKey('folder1', updateItem(item => item.name === 'file2', patch({ isOpen: true }))),
);

The Code:

Source: patchKey.ts && patchKey.spec.ts

[beaussan]

Use Case:

When you have in your store an array where you could have duplication, like a state of selected items :

{
  selectedId: [1, 2, 3, 2],
}

With this operator, you can filter out dupliacates. It can be use in a standalone way or with composition.

Example:

Filter out duplicates :

setState(
  patch({ selectedId: uniqArray() }),
);

Or be composable :

setState(
  patch({
    selectedId: compose(
      append([3, 1]),
      uniqArray(),
    ),
  }),
);

The Code:

Source: uniqArray.ts && uniqArray.spec.ts

[joaqcid]

Use Case:

When you need to append items but skip those already in existing array. Allows to compare by any field if is object

Example:

setState(
  patch({ items: appendUniq(newItems, i => i.id) })
)

The Code:

Source: append-uniq

[joaqcid]

Use Case:

When you need to sort items before you store them. Allows to sort by any field of T

Example:

setState(
  patch({ items: sortBy(i => i.id) })
)

The Code:

sort-by

[joaqcid]

@markwhitfeld can we expect some of this state-operators to become part of the library? any timeline for this? thanks!

[splincode]

@joaqcid PR's please)

[arturovt]

@joaqcid For sure we're open to PRs. But also we expect those operators to be beneficial for the community. If I create an operator that traverses binary tree in my application that doesn't mean that it will be used by anyone else except me. Do you agree with me? (or maybe I'm wrong at some points)

[joaqcid]

@arturovt ok, yes agreed, though you never know when a binary-tree-traverse state-operator might become handy ;)