ngx-query-params

Reactive and type-safe query parameter management using Angular Signals.

> 🔁 Two-way binding between URL query parameters and application state, powered by Angular’s modern reactivity model.

---

🚀 Features

- ✅ Auto-synced signals from query parameters
- ✅ Two-way binding: update signals → update URL
- ✅ Works with primitive types, arrays, booleans, numbers, enums, and more
- ✅ Fully tree-shakable, Angular-native
- ✅ Zero extra dependencies

---

📦 Installation

Using NPM:
``bash
npm install @geckosoft/ngx-query-params
`

Using YARN:
`bash
yarn add @geckosoft/ngx-query-params
`

---

🧩 Setup

Ensure your app uses Angular's Signals (Angular v17+).

No special setup needed—just import and use in any Angular component or service.

---

🧪 Usage

$3

`ts
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { qpNum } from '@geckosoft/ngx-query-params';

@Component({
selector: ...,
imports: [FormsModule],
template:

Next Page
,
})
export class MyComponent {
page = qpNum('page', 1); // ?page=1

nextPage() {
this.page.set(this.page() + 1);
}
}
`

$3

`ts
toggle = qpBool('debug', false); // ?debug=true
`

$3

`ts
filter = qp('filter', 'all'); // ?filter=all
`

$3

`ts
sort = qp('sort'); // string | undefined
`

$3

`ts
type Tab = 'home' | 'profile' | 'settings';
tab = qpCast1('tab', 'home'); // ?tab=home
`

$3

`ts
tags = qpMapN('tag', (x) => x.toLowerCase()); // ?tag=a&tag=b
`

---

🧠 How It Works

- Hooks into Angular Router's ActivatedRoute and queryParamMap
- Syncs with WritableSignal
- A global QueryParamsService batches and updates the URL when any param changes

---

📦 API Reference

$3

| Function | Type | Description |
|------------------|-----------------------------------------|-------------------------------------|
| qp() | WritableSignal | String param |
| qpNum() | WritableSignal | Number param |
| qpBool() | WritableSignal | Boolean param |
| qpCast1() | WritableSignal | Cast to enum/union type |
| qpMapN() | WritableSignal | Multi-value param with mapping |
| qpMap1() | WritableSignal | Generic one-value mapper |

---

🔧 Advanced

You can inject QueryParamsService to manually batch or set multiple parameters:

`ts
constructor(private readonly qps: QueryParamsService) {}

applyFilters() {
this.qps.set('filter', 'recent');
this.qps.set('limit', 20);
}
`

---

🧼 Cleanup

No need to manually unsubscribe—internally handles onDestroy()` and signal disposal.

---

📜 License

MIT

---

💬 Feedback / Contributions

Issues and PRs welcome!