🚀 NGX Signal Utils

Modern Angular state management with signals and @ngrx/signals

A comprehensive Angular utility suite providing extensive support for Angular signals and advanced features for the @ngrx/signals store, designed to enhance state management in modern Angular applications.

✨ Features

📄 Pagination Management

• Smart pagination with entities support
• Local and remote pagination modes
• Built-in computed properties
• Seamless Bootstrap components integration

🧭 Route & Query Params

• Type-safe parameter handling
• Reactive route parameter tracking
• Automatic signal updates
• Router integration utilities

📊 Status Management

• Loading, loaded, and error states
• Comprehensive state tracking
• Helper functions for state updates
• Async operation lifecycle management

🔧 Developer Experience

• Full TypeScript support
• Composable store features
• Tree-shakeable imports
• Zero configuration setup

🚀 Quick Start

Installation

npm install @dotted-labs/ngx-signal-utils

Basic Usage

import { signalStore } from '@ngrx/signals';
import { withEntities } from '@ngrx/signals/entities';
import { withPagination } from '@dotted-labs/ngx-signal-utils/pagination';
import { withStatus } from '@dotted-labs/ngx-signal-utils/status';

// Create a feature-rich store with pagination and status management
export const UserStore = signalStore(
  { providedIn: 'root' },
  withEntities<User>(),
  withPagination<User>({ isLocal: false }),
  withStatus(),
  withMethods((store) => ({
    async loadUsers() {
      patchState(store, setLoading());
      try {
        const users = await userService.getUsers({
          page: store.page(),
          pageSize: store.pageSize(),
        });
        patchState(store, setAllEntities(users.data), setTotalItems(users.total), setLoaded());
      } catch (error) {
        patchState(store, setError(error.message));
      }
    },
  })),
);

// Use in your component
@Component({
  template: `
    <div *ngIf="userStore.isLoading()">Loading...</div>
    <div *ngIf="userStore.error()">{{ userStore.error() }}</div>

    <user-list [users]="userStore.currentPage()" />

    <pagination
      [page]="userStore.page()"
      [totalPages]="userStore.totalPages()"
      [hasNext]="userStore.hasNextPage()"
      [hasPrevious]="userStore.hasPreviousPage()"
      (pageChange)="changePage($event)"
    />
  `,
})
export class UsersComponent {
  userStore = inject(UserStore);

  ngOnInit() {
    this.userStore.loadUsers();
  }

  changePage(page: number) {
    this.userStore.changePage(page, () => this.userStore.loadUsers());
  }
}

📚 Feature Guides

Complete Pagination Management

The pagination feature provides comprehensive pagination capabilities with both local and remote data handling.

import { withPagination, setTotalItems } from '@dotted-labs/ngx-signal-utils/pagination';

export const ProductStore = signalStore(
  withEntities<Product>(),
  withPagination<Product>({ pageSize: 20, entityName: 'product' }),
);

// Available computed properties
productStore.isEmpty(); // boolean
productStore.hasNextPage(); // boolean
productStore.hasPreviousPage(); // boolean
productStore.totalItems(); // number - total items count
productStore.totalPages(); // number
productStore.currentPage(); // Product[] (sliced for current page)

// Available methods
productStore.changePage(2, callback); // Navigate to page 2
productStore.changePageSize(20, callback); // Change items per page

📖 Full Pagination Documentation

Type-Safe Parameter Management

Handle route and query parameters with full type safety and reactive updates.

import { withRouteParams, withQueryParams } from '@dotted-labs/ngx-signal-utils/route';

// Route: /users/:userId
export const UserDetailStore = signalStore(
  withRouteParams({
    userId: (param: string) => Number(param), // Transform to number
  }),
  withQueryParams({
    tab: (param?: string) => param || 'profile', // Default value
    sort: (param?: string) => (param as 'asc' | 'desc') || 'asc',
  }),
  withMethods((store) => ({
    // Access parameters in methods
    loadUser() {
      const userId = store.userId(); // number
      const tab = store.tab(); // string
      // ... load user logic
    },
    // Update query parameters
    switchTab(tab: string) {
      store.updateTab(tab); // Updates URL automatically
    },
  })),
);

📖 Full Route Parameters Documentation

Comprehensive State Tracking

Track loading states, errors, and success states with built-in utilities.

import { withStatus, setLoading, setLoaded, setError } from '@dotted-labs/ngx-signal-utils/status';

export const ApiStore = signalStore(
  withStatus(),
  withMethods((store) => ({
    async fetchData() {
      patchState(store, setLoading());

      try {
        const data = await apiService.getData();
        patchState(store, { data }, setLoaded());
      } catch (error) {
        patchState(store, setError(error.message));
      }
    },
  })),
);

// Usage in templates
// apiStore.isLoading() -> boolean
// apiStore.isLoaded()  -> boolean
// apiStore.error()     -> string | null

📖 Full Status Management Documentation

🛠️ Requirements

• Angular: >=19.0.0
• @ngrx/signals: >=19.0.0
• TypeScript: >=5.8.0

🤝 Integration

Works Great With

• @ngrx/signals - Core signal store functionality
• Angular Router - Automatic route parameter tracking

📖 API Reference

Core Exports

// Pagination
export { withPagination, setTotalItems, PaginationState } from '@dotted-labs/ngx-signal-utils/pagination';

// Route Management
export { withRouteParams, withQueryParams, ParamsConfig } from '@dotted-labs/ngx-signal-utils/route';

// Status Management
export { withStatus, setLoading, setLoaded, setError, StatusState } from '@dotted-labs/ngx-signal-utils/status';

🧑‍💻 Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Lint code
npm run lint

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting PRs.

Development Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Submit a pull request

Made with ❤️ by Dotted Labs

🐛 Report Bug • ✨ Request Feature • 📖 Documentation