1.2.0 • Published 4 months ago

ngx-signal-plus v1.2.0

Weekly downloads
-
License
MIT
Repository
github
Last release
4 months ago

ngx-signal-plus

A powerful utility library that enhances Angular Signals with additional features for robust state management.

Features

  • Enhanced signal operations with built-in state tracking
  • Type-safe validations and transformations
  • Persistent storage with automatic serialization
  • Time-based operations (debounce, throttle, delay)
  • Signal operators for transformation and combination
  • Built-in undo/redo functionality
  • Form handling with validation
  • Automatic cleanup and memory management
  • Performance optimizations
  • Transactions and batching for atomic operations

Installation

npm install ngx-signal-plus

Requirements

  • Angular >= 16.0.0 (fully compatible with Angular 19)
  • TypeScript >= 5.0.0

Basic Usage

import { Component } from '@angular/core';
import { sp, enhance, spMap, spFilter } from 'ngx-signal-plus';
import { signal, computed } from '@angular/core';

@Component({
  standalone: true,
  selector: 'app-counter',
  template: `
    <div>Count: {{ counter.value() }}</div>
    <div>Doubled: {{ doubled() }}</div>
    <button (click)="increment()">Increment</button>
    <button (click)="decrement()">Decrement</button>
    
    @if (counter.canUndo()) {
      <button (click)="counter.undo()">Undo</button>
    }
  `,
})
export class CounterComponent {
  // Create an enhanced signal with persistence and history
  counter = sp(0)
    .persist('counter')
    .withHistory(10)
    .validate(value => value >= 0, 'Must be positive')
    .build();
  
  // Use signal operators
  doubled = computed(() => this.counter.value() * 2);
  
  increment() {
    this.counter.setValue(this.counter.value() + 1);
  }
  
  decrement() {
    if (this.counter.value() > 0) {
      this.counter.setValue(this.counter.value() - 1);
    }
  }
}

Core Features

Signal Creation

import { sp, spCounter, spToggle, spForm } from 'ngx-signal-plus';

// Simple enhanced signal
const name = sp('John').build();

// Counter with min/max validation
const counter = spCounter(0, { min: 0, max: 100 });

// Toggle (boolean) with persistence
const darkMode = spToggle(false, 'theme-mode');

// Form input with validation
const username = spForm.text('', {
  minLength: 3,
  maxLength: 20,
  debounce: 300
});

Signal Enhancement

Enhance existing signals with additional features:

import { enhance } from 'ngx-signal-plus';
import { signal } from '@angular/core';

const enhanced = enhance(signal(0))
  .persist('counter')
  .validate(n => n >= 0, 'Must be positive')
  .transform(Math.round)
  .withHistory(5)
  .debounce(300)
  .distinctUntilChanged()
  .build();

Signal Operators

import { spMap, spFilter, spDebounceTime, spCombineLatest } from 'ngx-signal-plus';
import { signal } from '@angular/core';

// Transform values
const price = signal(100);
const withTax = price.pipe(
  spMap(n => n * 1.2),
  spMap(n => Math.round(n * 100) / 100)
);

// Combine signals
const firstName = signal('John');
const lastName = signal('Doe');
const fullName = spCombineLatest([firstName, lastName])
  .pipe(spMap(([first, last]) => `${first} ${last}`));

Form Handling

import { spForm } from 'ngx-signal-plus';
import { computed } from '@angular/core';

// Form inputs with validation
const username = spForm.text('', { minLength: 3, maxLength: 20 });
const email = spForm.email('');
const age = spForm.number({ min: 18, max: 99, initial: 30 });

// Form validation
const isFormValid = computed(() => 
  username.isValid() && email.isValid() && age.isValid()
);

Validation and Presets

import { spValidators, spPresets } from 'ngx-signal-plus';

// Use validators
const email = sp('')
  .validate(spValidators.string.required, 'Email is required')
  .validate(spValidators.string.email, 'Must be a valid email')
  .build();

// Use presets for common patterns
const counter = spPresets.counter({
  initial: 0,
  min: 0,
  max: 100,
  step: 1,
  withHistory: true
});

const darkMode = spPresets.toggle({
  initial: false,
  persistent: true,
  storageKey: 'theme-mode'
});

State Management

import { spHistoryManager, spStorageManager } from 'ngx-signal-plus';

// History management
const history = new spHistoryManager(0, { maxSize: 10 });
history.push(1);
history.undo();
history.redo();

// Storage management
const storage = new spStorageManager<{theme: string}>('app-settings');
storage.save({ theme: 'dark' });
const settings = storage.load();

Available Features

CategoryFeatures
Signal Creationsp, spCounter, spToggle, spForm
Signal Enhancementenhance, validation, transformation, persistence, history
Signal OperatorsspMap, spFilter, spDebounceTime, spThrottleTime, spDelay, spDistinctUntilChanged, spSkip, spTake, spMerge, spCombineLatest
Transactions & BatchingspTransaction, spBatch, spIsTransactionActive, spIsInTransaction, spIsInBatch, spGetModifiedSignals
UtilitiesspValidators, spPresets
State ManagementspHistoryManager, spStorageManager
ComponentsspSignalPlusComponent, spSignalPlusService, spSignalBuilder

Documentation

For detailed documentation including all features, API reference, and examples, see our API Documentation.

Contributing

Please read our Contributing Guide.

Support

License

MIT

1.2.0

4 months ago

1.1.1

4 months ago

1.1.0

4 months ago

1.0.1

6 months ago

1.0.0-beta.2

6 months ago

1.0.0-beta.1

6 months ago

1.0.0-beta.0

6 months ago