('dt');
readonly tableState = PrimeNgDynamicTableStateHelper.create({
url: '/api/users/query',
httpClient: this.httpClient
});
ngOnInit() {
// Optional: Configure unique key and query parameters
this.tableState
.setUniqueKey('id')
.patchQueryParams({ includeDeleted: false });
}
### 2. Using Table Configuration Utilities
```typescript
import {
createTextColumn,
createNumericColumn,
createBooleanColumn,
createDateColumn,
createDropdownColumn,
mergeTableHeaders,
createStatusSelectItems
} from 'ngx-primeng-toolkit';
@Component({
// ... component configuration
})
export class AdvancedTableComponent {
readonly tableHeaders = mergeTableHeaders(
createTextColumn('name', 'Full Name', {
hasSort: true,
placeholder: 'Search names...'
}),
createTextColumn('email', 'Email Address', {
defaultMatchMode: 'contains'
}),
createNumericColumn('age', 'Age', {
defaultMatchMode: 'greaterThanOrEqual'
}),
createBooleanColumn('active', 'Status'),
createDateColumn('createdAt', 'Created Date'),
createDropdownColumn('role', 'Role', createStatusSelectItems({
'admin': 'Administrator',
'user': 'Regular User',
'moderator': 'Moderator'
}))
);
}
```
### 3. Advanced Configuration
```typescript
@Component({
// ... component configuration
})
export class AdvancedUserTableComponent {
private readonly httpClient = inject(HttpClient);
readonly tableState = PrimeNgDynamicTableStateHelper.create({
url: '/api/users/query',
httpClient: this.httpClient,
// Optional: Pass loading spinner context token
skipLoadingSpinnerContext: SkipLoadingSpinner
});
async ngOnInit() {
// Set up the table with advanced configuration
this.tableState
.setUniqueKey('userId')
.setQueryParams({
includeDeleted: false,
tenantId: this.currentTenant.id
});
// Load initial data
await this.tableState.refreshData();
}
// Method to change API endpoint dynamically
async switchToInactiveUsers() {
this.tableState
.setUrl('/api/users/inactive/query')
.clearTableData(this.dataTableRef());
await this.tableState.refreshData();
}
// Method to add route parameters
async loadUsersByDepartment(departmentId: number) {
this.tableState
.setRouteParam(departmentId.toString())
.clearTableData(this.dataTableRef());
await this.tableState.refreshData();
}
// Method to update query parameters
async filterByTenant(tenantId: number) {
this.tableState
.patchQueryParams({ tenantId })
.clearTableData(this.dataTableRef());
await this.tableState.refreshData();
}
}
```
## API Response Format
The table state helper expects your API to return data in the following format:
```typescript
interface ApiResponse {
data: T[]; // Array of table row data
last_page: number; // Total number of pages
last_row: number; // Total number of records
}
```
## API Request Format
The helper sends POST requests with the following structure:
```typescript
interface DynamicQueryDto {
size: number; // Page size
page: number; // Current page (1-based)
filter: DynamicQueryFilterDto[]; // Array of filters
sort: DynamicQuerySortDto[]; // Array of sort criteria
}
interface DynamicQueryFilterDto {
field: string; // Field name to filter
value: string; // Filter value (always string)
type: FilterTypeMapped; // Filter operation type
}
interface DynamicQuerySortDto {
field: string; // Field name to sort
dir: 'asc' | 'desc'; // Sort direction
}
```
## Filter Types
The library supports the following filter mappings:
| PrimeNG Filter Type | Backend Filter Type | Description |
|-------------------|-------------------|-------------|
| `startsWith` | `starts` | Field starts with value |
| `notStartsWith` | `!starts` | Field does not start with value |
| `endsWith` | `ends` | Field ends with value |
| `notEndsWith` | `!ends` | Field does not end with value |
| `contains` | `like` | Field contains value |
| `notContains` | `!like` | Field does not contain value |
| `equals` | `=` | Field equals value |
| `notEquals` | `!=` | Field does not equal value |
| `greaterThan` | `>` | Field is greater than value |
| `lessThan` | `<` | Field is less than value |
| `greaterThanOrEqual` | `>=` | Field is greater than or equal to value |
| `lessThanOrEqual` | `<=` | Field is less than or equal to value |
## Utility Functions
### Column Creation Functions
- `createTextColumn(field, label, options)` - Creates text column with string filtering
- `createNumericColumn(field, label, options)` - Creates numeric column with number filtering
- `createBooleanColumn(field, label, options)` - Creates boolean column with true/false filtering
- `createDateColumn(field, label, options)` - Creates date column with date filtering
- `createDropdownColumn(field, label, options, dropdownOptions)` - Creates dropdown filtered column
- `createMultiselectColumn(field, label, options, selectOptions)` - Creates multiselect filtered column
- `createSimpleColumn(field, label, options)` - Creates basic column without filtering
### Helper Functions
- `createPrimengStringMatchModes()` - Returns SelectItem array for string filter modes
- `createPrimengNumberMatchModes()` - Returns SelectItem array for numeric filter modes
- `createBooleanSelectItems()` - Creates boolean dropdown options
- `createStatusSelectItems()` - Creates status dropdown from object mapping
- `mergeTableHeaders()` - Combines multiple table header configurations
## Class Methods
### PrimeNgDynamicTableStateHelper Methods
- `static create(options)` - Creates new instance
- `setUniqueKey(key)` - Sets unique identifier field name
- `setUrl(url)` - Sets API endpoint URL and resets state
- `setRouteParam(param)` - Appends route parameter to URL
- `patchQueryParams(params)` - Merges additional query parameters
- `removeQueryParam(key)` - Removes specific query parameter
- `setQueryParams(params)` - Replaces all query parameters
- `refreshData()` - Reloads data with current state
- `clearTableData(table)` - Clears table data and resets state
- `onLazyLoad(event)` - Handles PrimeNG lazy load events
### Readonly Signals
- `data` - Current table data array
- `isLoading` - Loading state boolean
- `totalRecords` - Total number of records
- `uniqueKey` - Current unique key field name
## Memoized Data Storage
The library also includes a powerful memoized data storage system for caching HTTP responses and managing single/multiple data objects.
### Basic Usage
```typescript
import { Component, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { MemoizedDataStorage } from 'ng-component-state-utils';
interface User {
id: number;
name: string;
email: string;
}
@Component({
selector: 'app-data-example',
template: `
@if (userStorage.singleData(); as user) {
{{ user.name }}
{{ user.email }}
}
@for (user of userStorage.multipleData(); track user.id) {
{{ user.name }}
}
`
})
export class DataExampleComponent {
private httpClient = inject(HttpClient);
userStorage = new MemoizedDataStorage(this.httpClient);
async loadUser() {
await this.userStorage.loadSingleData('/api/user/1');
}
async loadUsers() {
await this.userStorage.loadMultipleData('/api/users');
}
}
```
### Advanced Usage with Cache Control
```typescript
export class AdvancedDataComponent {
private httpClient = inject(HttpClient);
// Create storage for different data types
configStorage = new MemoizedDataStorage>(this.httpClient);
categoryStorage = new MemoizedDataStorage>(this.httpClient);
async loadConfig() {
// First call fetches from API
await this.configStorage.loadSingleData('/api/config');
// Second call uses cached data
await this.configStorage.loadSingleData('/api/config');
}
async refreshConfig() {
// Force fresh data on next load
this.configStorage.disableMemoizationOnNextRead();
await this.configStorage.loadSingleData('/api/config');
}
async loadCategoriesWithParams() {
await this.categoryStorage.loadMultipleData('/api/categories', {
active: true,
sort: 'name'
});
}
clearAllData() {
this.configStorage.clear();
this.categoryStorage.clear();
}
}
```
### MemoizedDataStorage Methods
- `loadSingleData(url, queryParams?)` - Loads single object with optional query parameters
- `loadMultipleData(url, queryParams?)` - Loads array of objects with optional query parameters
- `disableMemoizationOnNextRead()` - Forces fresh data on next load call
- `clear()` - Clears all cached data
- `hasSingleData()` - Checks if single data is cached
- `hasMultipleData()` - Checks if multiple data is cached
### MemoizedDataStorage Signals
- `singleData` - Current single data object or null
- `multipleData` - Current array of data objects
- `isLoading` - Loading state boolean
## Simple Paged Table Helper
For scenarios where you only need basic pagination without filtering or sorting, use the `PrimengPagedDataTableStateHelper`:
```typescript
import { PrimengPagedDataTableStateHelper } from 'ngx-primeng-toolkit';
interface Product {
id: number;
name: string;
price: number;
}
@Component({
selector: 'app-simple-table',
template: `
{{ product.name }}
{{ product.price | currency }}
`
})
export class SimpleTableComponent {
private httpClient = inject(HttpClient);
pagedHelper = PrimengPagedDataTableStateHelper.create({
url: '/api/products',
httpClient: this.httpClient
});
}
```
### Paged Table Expected Response Format
```typescript
interface PagedResponse {
payload: T[]; // Array of data objects
totalCount: number; // Total number of records
}
```
## Component State Management
The `ComponentState` class provides reactive state management for common component operations using Angular signals.
### Basic Usage
```typescript
import { Component } from '@angular/core';
import { ComponentState, ManipulationType } from 'ng-component-state-utils';
@Component({
selector: 'app-user-management',
template: `
`
})
export class UserManagementComponent {
componentState = new ComponentState()
.updateComponentTitle('User')
.updateCheckBoxSelectionStatus(true);
openCreateDialog() {
this.componentState
.updateManipulationType(ManipulationType.Create)
.setCreateOrUpdateDialogOpen(true);
}
}
```
### ComponentState Properties
#### Signals
- `isAjaxDataIncoming` - Incoming data loading state
- `isAjaxRequestOutgoing` - Outgoing request state
- `enableCheckBoxSelection` - Checkbox selection enabled state
- `isSelectableRowEnabled` - Row selection enabled state
- `hasMultipleSelection` - Multiple selection mode state
- `isCreateOrUpdateDialogOpen` - Generic dialog open state
- `isUpdateDialogOpen` - Update dialog specific state
- `isCreateDialogOpen` - Create dialog specific state
- `manipulationType` - Current operation type (Create/Update/Delete/View)
- `componentTitle` - Component title
#### Computed Signals
- `componentTitleWithManipulationType()` - Title combined with operation type
- `isOnUpdateState()` - True if in update mode
- `isOnCreateState()` - True if in create mode
- `isOnDeleteState()` - True if in delete mode
- `isOnViewState()` - True if in view mode
- `isAnyAjaxOperationRunning()` - True if any Ajax operation is active
- `isAnyDialogOpen()` - True if any dialog is open
### ComponentState Methods
```typescript
// Fluent API for chaining operations
componentState
.updateComponentTitle('Product Management')
.updateManipulationType(ManipulationType.Update)
.setCreateOrUpdateDialogOpen(true)
.updateMultipleSelectionStatus(false);
```
## Component Data Storage
The `ComponentDataStorage` class provides reactive data management for single objects and arrays.
### Basic Usage
```typescript
import { Component, OnInit } from '@angular/core';
import { ComponentDataStorage } from 'ng-component-state-utils';
interface User {
id: number;
name: string;
email: string;
}
@Component({
selector: 'app-user-data',
template: `
@if (dataStorage.singleData(); as user) {
{{ user.name }}
{{ user.email }}
}
Users ({{ dataStorage.getMultipleDataCount() }})
@for (user of dataStorage.multipleData(); track user.id) {
{{ user.name }} - {{ user.email }}
}
`
})
export class UserDataComponent implements OnInit {
dataStorage = new ComponentDataStorage();
ngOnInit() {
// Initialize with sample data
this.dataStorage
.updateSingleData({ id: 1, name: 'John Doe', email: 'john@example.com' })
.updateMultipleData([
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]);
}
updateEmail() {
this.dataStorage.patchSingleData({
email: `updated-${Date.now()}@example.com`
});
}
addSampleUser() {
const newUser: User = {
id: Date.now(),
name: 'New User',
email: 'newuser@example.com'
};
this.dataStorage.addToMultipleData(newUser);
}
removeUser(userId: number) {
this.dataStorage.removeFromMultipleData(user => user.id === userId);
}
}
```
### ComponentDataStorage Methods
#### Data Operations
- `updateSingleData(data)` - Replace single data completely
- `updateMultipleData(array)` - Replace multiple data array
- `patchSingleData(partial)` - Merge partial data with existing single data
- `patchMultipleData(array)` - Append new items to existing array
- `addToMultipleData(item)` - Add single item to array
- `removeFromMultipleData(predicate)` - Remove items matching predicate
- `updateItemInMultipleData(predicate, updateFn)` - Update specific items
#### Utility Methods
- `clearAll()` - Clear both single and multiple data
- `clearSingleData()` - Clear only single data
- `clearMultipleData()` - Clear only multiple data
- `hasSingleData()` - Check if single data exists
- `hasMultipleData()` - Check if multiple data has items
- `getMultipleDataCount()` - Get count of multiple data items
- `findInMultipleData(predicate)` - Find item in multiple data
- `existsInMultipleData(predicate)` - Check if item exists
### Advanced Usage Example
```typescript
@Component({
selector: 'app-advanced-data-management'
})
export class AdvancedDataManagementComponent {
userStorage = new ComponentDataStorage();
componentState = new ComponentState()
.updateComponentTitle('Advanced User Management');
async loadUsers() {
this.componentState.setAjaxDataIncoming(true);
try {
const users = await this.fetchUsers();
this.userStorage.updateMultipleData(users);
// Set first user as selected
if (users.length > 0) {
this.userStorage.updateSingleData(users[0]);
}
} catch (error) {
console.error('Failed to load users:', error);
} finally {
this.componentState.setAjaxDataIncoming(false);
}
}
async updateUser(userId: number, updates: Partial) {
this.componentState.setAjaxRequestOutgoing(true);
try {
const updatedUser = await this.updateUserAPI(userId, updates);
// Update in both single and multiple data if it's the same user
this.userStorage.updateItemInMultipleData(
user => user.id === userId,
() => updatedUser
);
if (this.userStorage.singleData()?.id === userId) {
this.userStorage.updateSingleData(updatedUser);
}
} catch (error) {
console.error('Failed to update user:', error);
} finally {
this.componentState.setAjaxRequestOutgoing(false);
}
}
private async fetchUsers(): Promise {
// Your API call here
return [];
}
private async updateUserAPI(userId: number, updates: Partial): Promise {
// Your API call here
return {} as User;
}
}
```
## NgSelect Helper with Centralized Initialization
The library provides an `initNgSelect` utility function for streamlined initialization of multiple NgSelect helpers with centralized error handling.
### Recommended Usage Pattern
```typescript
import { Component, inject, signal } from '@angular/core';
import { toObservable } from '@angular/core/rxjs-interop';
import { HttpClient } from '@angular/common/http';
import { DestroyRef } from '@angular/core';
import { NgSelectHelper, initNgSelect } from 'ngx-primeng-toolkit';
interface KeyData {
key: K;
data: V;
}
@Component({
selector: 'app-select-example'
})
export class SelectExampleComponent {
private readonly httpClient = inject(HttpClient);
private readonly destroyRef = inject(DestroyRef);
private readonly toastService = inject(ToastService); // Your toast service
// Define NgSelect helpers
readonly floorOptionsHelper = new NgSelectHelper>(
'/api/shared/floors',
this.httpClient,
this.destroyRef,
false, // usePostRequest
50, // limit (page size)
false // useCache
);
readonly lineOptionsHelper = new NgSelectHelper>(
'/api/shared/lines',
this.httpClient,
this.destroyRef,
false, // usePostRequest
50, // limit
false // useCache
);
// Centralized helper management
readonly ngSelectHelpers = signal([
this.floorOptionsHelper,
this.lineOptionsHelper
]);
constructor() {
// Initialize all NgSelect helpers with error handling
initNgSelect(
toObservable(this.ngSelectHelpers),
this.destroyRef,
(err) => this.toastService.showAjaxErrorToast(err)
);
}
}
```
### Benefits of Centralized Initialization
1. **Single Point of Error Handling**: All NgSelect errors are handled consistently
2. **Automatic Cleanup**: Uses `takeUntilDestroyed` for proper subscription cleanup
3. **Lazy Initialization**: Only initializes helpers that haven't been initialized yet
4. **Type Safety**: Full TypeScript support with proper type inference
### initNgSelect Function API
```typescript
function initNgSelect(
helpers$: Observable[]>,
destroyRef: DestroyRef,
onAjaxError: (err: Error) => void
): void
```
**Parameters:**
- `helpers$`: Observable of NgSelectHelper instances (typically from `toObservable(signal)`)
- `destroyRef`: Angular DestroyRef for automatic subscription cleanup
- `onAjaxError`: Callback function to handle AJAX errors from any helper
## NgSelectHelper (Individual Usage)
The `NgSelectHelper` class provides comprehensive state management for ng-select components with features like pagination, search, caching, and error handling.
### Basic Usage
```typescript
import { Component, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { NgSelectHelper } from 'ng-component-state-utils';
interface User {
id: number;
name: string;
email: string;
}
@Component({
selector: 'app-user-select',
template: `
`
})
export class UserSelectComponent {
private httpClient = inject(HttpClient);
private destroyRef = inject(DestroyRef);
userSelectHelper = NgSelectHelper.create({
ajaxUrl: '/api/users',
httpClient: this.httpClient,
destroyRef: this.destroyRef,
limit: 20,
useCache: true
});
selectedUserId: number | null = null;
ngOnInit() {
this.userSelectHelper.init();
}
}
```
### Advanced Usage with POST Requests
```typescript
@Component({
selector: 'app-product-select'
})
export class ProductSelectComponent {
productSelectHelper = NgSelectHelper.create({
ajaxUrl: '/api/products/search',
httpClient: this.httpClient,
destroyRef: this.destroyRef,
usePostRequest: true,
limit: 15,
useCache: false
});
ngOnInit() {
this.productSelectHelper
.setDebounceTimeInSecond(1)
.setBody({
filters: [{ field: 'active', value: true }],
sort: [{ field: 'name', direction: 'asc' }]
})
.init();
// Handle errors
this.productSelectHelper.ajaxError$.subscribe(error => {
console.error('Product search failed:', error);
});
}
filterByCategory(categoryId: number) {
this.productSelectHelper
.setBody({
filters: [
{ field: 'active', value: true },
{ field: 'categoryId', value: categoryId }
]
})
.resetAll({ resetCache: true });
}
}
```
### Multi-Select with Form Integration
```typescript
import { FormControl, FormGroup } from '@angular/forms';
@Component({
selector: 'app-department-multi-select',
template: `
`
})
export class DepartmentMultiSelectComponent {
departmentSelectHelper = NgSelectHelper.create({
ajaxUrl: '/api/departments',
httpClient: this.httpClient,
destroyRef: this.destroyRef,
limit: 50
});
form = new FormGroup({
departments: new FormControl([])
});
ngOnInit() {
this.departmentSelectHelper
.setDebounceTimeInSecond(0.5)
.init();
}
}
```
### NgSelectHelper Configuration Options
```typescript
interface NgSelectHelperConfig {
ajaxUrl: string; // API endpoint URL
httpClient: HttpClient; // Angular HttpClient
destroyRef: DestroyRef; // Angular DestroyRef for cleanup
usePostRequest?: boolean; // Use POST instead of GET (default: false)
limit?: number; // Items per page (default: 10)
useCache?: boolean; // Enable response caching (default: false)
queryParams?: Record; // Initial query parameters
body?: any; // Request body for POST requests
httpOptions?: any; // Additional HTTP options
}
```
### NgSelectHelper Methods
**Configuration Methods:**
- `init()` - Initialize the helper and load first page
- `setDebounceTimeInSecond(seconds: number)` - Set search debounce time
- `patchQueryParams(params: Record)` - Update query parameters
- `removeQueryParam(key: string)` - Remove a query parameter
- `setBody(body: any)` - Set request body for POST requests
- `resetAll(options)` - Reset all data with options
**Event Handlers:**
- `onOpen()` - Handle ng-select open event
- `onClose()` - Handle ng-select close event
- `onClear()` - Handle ng-select clear event
- `onScrollToEnd()` - Handle infinite scroll
**Cache Management:**
- `clearCache()` - Clear cached responses
- `refreshData()` - Refresh current data
### NgSelectHelper Signals
**Data Signals:**
- `loadedData()` - Currently loaded data with pagination info
- `isLoading()` - Loading state
- `totalCount` - Total available records
- `page` - Current page number
- `limitReached` - Whether pagination limit reached
**Input Management:**
- `inputSubject` - Subject for search input (use with typeahead)
**Error Handling:**
- `ajaxError$` - Observable for API errors
- `isLastApiCallSuccessful` - Whether last API call succeeded
### Integration with Other Helpers
```typescript
@Component({
selector: 'app-integrated-form'
})
export class IntegratedFormComponent {
// Component state management
componentState = new ComponentState()
.updateComponentTitle('User Management');
// Data storage
userDataStorage = new ComponentDataStorage();
// Select helpers
departmentSelectHelper = NgSelectHelper.create({
ajaxUrl: '/api/departments',
httpClient: this.httpClient,
destroyRef: this.destroyRef
});
async createUser(userData: Partial) {
this.componentState.setAjaxRequestOutgoing(true);
try {
const newUser = await this.userService.create(userData);
this.userDataStorage.addToMultipleData(newUser);
// Clear department select cache to ensure fresh data
this.departmentSelectHelper.clearCache();
} catch (error) {
console.error('Failed to create user:', error);
} finally {
this.componentState.setAjaxRequestOutgoing(false);
}
}
}
```
For a comprehensive ng-select example, see `example-ng-select-usage.ts`.
## Complete Integration Example
For a comprehensive example showing all features working together, see the `example-usage-all-features.ts` file which demonstrates:
- Table state management with filtering and sorting
- Memoized data storage for reference data
- Component state management for dialogs and operations
- Component data storage for selected items
- Integration between all systems
## Error Handling
```
The library includes built-in error handling:
```typescript
try {
await this.tableState.refreshData();
} catch (error) {
// Handle API errors
console.error('Failed to load table data:', error);
this.toastService.showError('Failed to load data');
}
```
## TypeScript Support
Full TypeScript support with generic typing:
```typescript
interface CustomUser {
id: string;
firstName: string;
lastName: string;
department: {
id: number;
name: string;
};
}
const tableState = PrimeNgDynamicTableStateHelper.create({
url: '/api/users',
httpClient: this.httpClient
});
// tableState.data() is typed as Signal
```
## Utility Functions & TypeScript Types
The library includes general utility functions and TypeScript helper types for common development tasks.
### Object Utilities
#### cleanNullishFromObject
Removes null and undefined values from an object, useful for cleaning query parameters before API calls.
```typescript
import { cleanNullishFromObject } from 'ngx-primeng-toolkit';
// Basic usage
const queryParams = {
name: 'John',
email: null,
age: undefined,
status: 'active',
department: ''
};
const cleaned = cleanNullishFromObject(queryParams);
// Result: { name: 'John', status: 'active', department: '' }
// With array values
const filters = {
categories: ['tech', 'business'],
tags: null,
priority: undefined,
active: true
};
const cleanedFilters = cleanNullishFromObject(filters);
// Result: { categories: ['tech', 'business'], active: true }
// In component for API calls
export class UserSearchComponent {
searchForm = new FormGroup({
name: new FormControl(null),
email: new FormControl(null),
department: new FormControl(null)
});
async searchUsers() {
const searchParams = cleanNullishFromObject(this.searchForm.value);
// Only sends non-null/undefined values to API
const users = await this.userService.searchUsers(searchParams);
}
}
```
### TypeScript Utility Types
The library provides several utility types for handling nullable and partial types:
#### RecursiveNullable
Makes all properties of a type nullable (T | null):
```typescript
import { RecursiveNullable } from 'ngx-primeng-toolkit';
type User = {
id: number;
name: string;
email: string;
};
type NullableUser = RecursiveNullable;
// Result: {
// id: number | null;
// name: string | null;
// email: string | null;
// }
// Useful for form models
export class UserFormComponent {
userForm: FormGroup<{
[K in keyof User]: FormControl[K]>
}>;
}
```
#### Nullish
Represents a value that can be null or undefined:
```typescript
import { Nullish } from 'ngx-primeng-toolkit';
type MaybeString = Nullish; // string | null | undefined
type MaybeUser = Nullish; // User | null | undefined
// Useful for optional service responses
export class UserService {
getCurrentUser(): Observable> {
// May return user, null, or undefined
return this.http.get('/api/user/current')
.pipe(catchError(() => of(null)));
}
}
```
#### RecursiveNullish
Makes all properties nullish (T | null | undefined) recursively:
```typescript
import { RecursiveNullish } from 'ngx-primeng-toolkit';
type User = {
id: number;
profile: {
name: string;
age: number;
};
};
type NullishUser = RecursiveNullish;
// Result: {
// id: number | null | undefined;
// profile: {
// name: string | null | undefined;
// age: number | null | undefined;
// } | null | undefined;
// }
// Useful for deeply nullable form states
export interface FormState extends RecursiveNullish {}
```
#### RecursivePartial
Makes all properties optional recursively:
```typescript
import { RecursivePartial } from 'ngx-primeng-toolkit';
type User = {
id: number;
profile: {
name: string;
age: number;
};
settings: {
theme: string;
notifications: boolean;
};
};
type PartialUser = RecursivePartial;
// Result: {
// id?: number;
// profile?: {
// name?: string;
// age?: number;
// };
// settings?: {
// theme?: string;
// notifications?: boolean;
// };
// }
// Perfect for update operations
export class UserService {
updateUser(id: number, updates: RecursivePartial) {
// Can update any subset of user properties
return this.http.patch(`/api/users/${id}`, updates);
}
}
// Usage in components
export class UserProfileComponent {
updateProfile() {
const updates: RecursivePartial = {
profile: {
name: 'New Name' // Only updating name, age is optional
}
// settings and id are completely optional
};
this.userService.updateUser(this.userId, updates);
}
}
```
### Combining Utilities
These utilities work great together for complex form and API scenarios:
```typescript
import {
cleanNullishFromObject,
RecursivePartial,
RecursiveNullish
} from 'ngx-primeng-toolkit';
export class AdvancedFormComponent {
// Form model with nullable fields
formModel: RecursiveNullish = {
id: null,
profile: {
name: null,
age: undefined
}
};
// Update with partial data
updateUser(updates: RecursivePartial) {
// Clean nullish values before sending to API
const cleanUpdates = cleanNullishFromObject(updates);
if (Object.keys(cleanUpdates).length > 0) {
this.userService.updateUser(this.userId, cleanUpdates);
}
}
}
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.
## Support
For issues and questions, please use the GitHub issues page.
This package uses automated versioning and publishing through GitHub Actions. Contributors don't need to manually update versions or publish to NPM.
#### Commit Message Format
Use conventional commit messages to trigger automatic version bumps:
```bash
# For bug fixes (patch version: 1.0.0 → 1.0.1)
git commit -m "fix: resolve checkbox state issue"
# For new features (minor version: 1.0.0 → 1.1.0)
git commit -m "feat: add new utility function"
# For breaking changes (major version: 1.0.0 → 2.0.0)
git commit -m "major: change API interface"
# OR
git commit -m "feat: new feature
BREAKING CHANGE: API has changed"
# Other commits (no version bump)
git commit -m "docs: update README"
git commit -m "chore: update dependencies"
```
#### Development Workflow
1. **Make your changes**
2. **Commit with proper message format**
3. **Push to main branch**
4. **GitHub Actions automatically:**
- Runs tests and type checking
- Bumps version based on commit message
- Publishes to NPM
- Creates git tags
```bash
# Example workflow
git add .
git commit -m "feat: add new tri-state utility"
git push origin main
# 🎉 Package automatically published!
```
#### Pull Request Workflow
For larger changes, use pull requests:
```bash
# Create feature branch
git checkout -b feature/new-functionality
# Make changes and commit
git commit -m "feat: add advanced tri-state features"
# Push and create PR
git push origin feature/new-functionality
# Create PR on GitHub → Merge → Automatic publish!
```
## Browser Support
- Modern browsers supporting ES2020+
- Angular 19+ (Angular 20+ recommended)
- PrimeNG 19+ (PrimeNG 20+ recommended) (optional, for table helpers)
- @ng-select/ng-select 15+ (optional, for select helpers)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License. See LICENSE file for details.
## Links
- [PrimeNG Documentation](https://primeng.org/)
- [@ng-select/ng-select Documentation](https://github.com/ng-select/ng-select)
- [Angular Reactive Forms](https://angular.io/guide/reactive-forms)
- [NgRx Signals](https://ngrx.io/guide/signals)