https://github.com/SlyTed/ngx-pipes-toolkit
Complementary pipes library for Angular
https://github.com/SlyTed/ngx-pipes-toolkit
Last synced: 8 months ago
JSON representation
Complementary pipes library for Angular
- Host: GitHub
- URL: https://github.com/SlyTed/ngx-pipes-toolkit
- Owner: SlyTed
- License: mit
- Created: 2024-07-19T13:43:03.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-07T19:36:48.000Z (about 1 year ago)
- Last Synced: 2025-02-21T10:06:41.587Z (8 months ago)
- Language: TypeScript
- Homepage:
- Size: 852 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-angular - ngx-pipes-toolkit - A complementary pipes library for Angular. (Third Party Components / Pipes)
- awesome-angular - ngx-pipes-toolkit - A complementary pipes library for Angular. (Third Party Components / Pipes)
- trackawesomelist - ngx-pipes-toolkit (⭐6) - A complementary pipes library for Angular. (Recently Updated / [Oct 13, 2024](/content/2024/10/13/README.md))
README
# NGX Pipes Toolkit
A complementary pipes library for Angular
## Table of contents
- [Motivation](#motivation)
- [Installation](#installation)
- [Usage](#usage)
- [Content](#content)
- [Array](#array)
- [Enumerate](#enumerate)
- [Math](#math)
- [Convert](#convert)
- [MeanBy](#mean-by)
- [SumBy](#sum-by)
- [MinBy](#min-by)
- [MaxBy](#max-by)
- [Contributing](#contributing)
## Motivation
**ngx-pipes-toolkit** library was born from the need to "wrap" the utility functions of [Lodash](https://lodash.com/docs) for a direct usage in the templates, especially the mathematical ones.
Typically, we manipulate collections of objects fetched from a REST API, and we want to display to the users some statistics based on a property of those objects. For example, we might want to display the mean age for a collection of users.
However, native Angular pipes or ones from other NPM packages like [NGX Pipes](https://www.npmjs.com/package/ngx-pipes) or [Angular Pipes](https://www.npmjs.com/package/angular-pipes) handle **only** data from native types (i.e. `number`, `string`, or `boolean`). Consequently, it is not possible to compute directly in the template the mean age. Therefore, we need to declare a derived value from the fetched collection in the component class (signals are used for convenience):
```typescript
import { meanBy } from 'lodash';
export type User = {
id: string;
age: number;
};
@Component({
template: `
Mean age: {{ $meanAge() }}
`,
})
export class DashboardComponent {
readonly $users: Signal = this.userApiService.fetchUsers();
readonly $meanAge = computed(() => {
return meanBy(this.$users(), 'age');
});
}
```
Even if this derived value `$meanAge` is relatively simple, it adds an extra layer for a straightforward computation using utility functions.
The primary motivation behind **ngx-pipes-toolkit** is to allow direct manipulation of collection of objets without declaring intermediate fields in the component class, thereby simplifying the code:
```typescript
import { MeanByPipe } from 'ngx-pipes-toolkit';
export type User = {
id: string;
age: number;
};
@Component({
imports: [MeanByPipe],
template: `
Mean age: {{ $users() | meanBy:'age' }}
`,
})
export class DashboardComponent {
readonly $users: Signal = this.userApiService.fetchUsers();
}
```
Moreover, the aim of **ngx-pipes-toolkit** is **not** to replace other libraries, but to complement them. That's why there are no duplicate pipes with the other main Angular pipes library: [NGX Pipes](https://www.npmjs.com/package/ngx-pipes).
## Installation
Use NPM to install the package
```bash
$ npm install ngx-pipes-toolkit --save
```
## Usage
All pipes in **ngx-pipes-toolkit** are implemented as standalone pipes. There are no Angular modules that wrap the pipes. Therefore, you can directly use them in your components or templates by importing them where needed. Furthermore, all pipes are pure.
- In templates:
```html
{{ 1_000 | convert:'m':'km' }}
```
- In components:
```typescript
import { ConvertPipe } from 'ngx-pipes-toolkit';
@Component({
providers: [ConvertPipe],
})
export class MyComponent {
readonly convertPipe = inject(ConvertPipe);
readonly conversion = this.convertPipe.transform(1_000, 'm', 'km'); // Returns "1"
}
```
## Content
### Array
#### Enumerate
Allows to use `*ngFor` directive or `@for` control flow block like a classic `for` loop (sometimes we just want to render something in the template a certain number of times, independently from a collection of objets)
```html
@for (index of $loadingCount() | enumerate; track index) {
}
```
### Math
#### Convert
Converts a value with its current unit to the final unit
```html
{{ 1_000 | convert:'m':'km' }}
{{ 32 | convert:'F':'C' }}
```
#### Mean by
Calculates the mean of an array of objects based on one of their `number`, parsable `string` or `Date` property
```typescript
const users = [
{ name: 'Alice', age: 20 },
{ name: 'Bob', age: 30 },
]
const games = [
{ name: 'Mass Effect 1', price: 30 }
{ name: 'Mass Effect Andromeda', price: 40 }
]
```
```html
{{ users | meanBy:'age' }}
{{ games | meanBy:'price' }}
```
#### Sum by
Calculates the sum of an array of objects based on one of their `number`, parsable `string` or `Date` property
```typescript
const users = [
{ name: 'Alice', age: 20 },
{ name: 'Bob', age: 30 },
]
const games = [
{ name: 'Mass Effect 1', price: 30 }
{ name: 'Mass Effect Andromeda', price: 40 }
]
```
```html
{{ users | sumBy:'age' }}
{{ games | sumBy:'price' }}
```
#### Min by
Returns the item with the smallest value of an array of object based on one of their `number`, parsable `string` or `Date` property
```typescript
const users = [
{ name: 'Alice', age: 20 },
{ name: 'Bob', age: 30 },
]
const games = [
{ name: 'Mass Effect 1', price: 30 }
{ name: 'Mass Effect Andromeda', price: 40 }
]
```
```html
{{ users | minBy:'age' }}
{{ games | minBy:'price' }}
```
#### Max by
Returns the item with the largest value of an array of object based on one of their `number`, parsable `string` or `Date` property
```typescript
const users = [
{ name: 'Alice', age: 20 },
{ name: 'Bob', age: 30 },
]
const games = [
{ name: 'Mass Effect 1', price: 30 }
{ name: 'Mass Effect Andromeda', price: 40 }
]
```
```html
{{ users | maxBy:'age' }}
{{ games | maxBy:'price' }}
```
## Contributing
- Any contribution is appreciated
- If you are planning to add a new pipe (or any new other feature) or make a fix, please open an issue before
- Follow the [conventional commit message format](https://www.conventionalcommits.org/en/v1.0.0/)
1. Clone the project
```bash
$ git clone https://github.com/SlyTed/ngx-pipes-toolkit.git
```
2. Install the dependencies
```bash
$ npm install
```
3. Make your changes in a new branch
```bash
$ git checkout -b
```
4. Add appropriate tests (cover all cases) and make sure everything is running properly (don't forget to lint)
```bash
$ npm run test:coverage
$ npm run lint
```
5. Push your branch
6. Make a pull request