@stardyn/angular-updater/README.md

Angular Version Tracker Package - Lightweight, configurable version tracking and update notification service for Angular applications with Service Worker support

# @stardyn/angular-updater

Lightweight, configurable version tracking and update notification service for Angular applications with Service Worker support. Provides automatic version checking and user-friendly update prompts.

## Features

- **Service Worker Integration**: Seamless integration with Angular Service Worker
- **Automatic Version Checking**: Configurable interval-based version checking
- **User-Friendly Update Prompts**: Customizable dialog for update notifications
- **Performance Focused**: Zero overhead when Service Worker is disabled
- **Singleton Pattern**: Prevents multiple instances and ensures efficient resource usage
- **Rich Logging**: Debug mode with detailed logging for development
- **Theme Support**: Customizable UI themes for update dialogs
- **Production Ready**: Automatically optimized for production environments

## Installation

```bash
npm install @stardyn/angular-updater
```

## Prerequisites

This package requires Angular Service Worker to be configured in your application:

```bash
ng add @angular/pwa
```

## Quick Start

### 1. App Module Configuration

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ServiceWorkerModule } from '@angular/service-worker';
import { provideXconVersionTracker } from '@stardyn/angular-updater';
import { ActionTheme } from '@xcon-platform/core-ui-actions';

import { AppComponent } from './app.component';
import { environment } from '../environments/environment';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    ServiceWorkerModule.register('ngsw-worker.js', {
      enabled: environment.production,
      registrationStrategy: 'registerWhenStable:30000'
    })
  ],
  providers: [
    provideXconVersionTracker({
      checkInterval: 300, // Check every 5 minutes
      debugMode: !environment.production,
      theme: ActionTheme.DARK
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }
```

### 2. Standalone Application Configuration

```typescript
// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideServiceWorker } from '@angular/service-worker';
import { provideXconVersionTracker } from '@stardyn/angular-updater';
import { ActionTheme } from '@xcon-platform/core-ui-actions';

import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

bootstrapApplication(AppComponent, {
  providers: [
    provideServiceWorker('ngsw-worker.js', {
      enabled: environment.production,
      registrationStrategy: 'registerWhenStable:30000'
    }),
    provideXconVersionTracker({
      checkInterval: 180, // Check every 3 minutes
      debugMode: !environment.production,
      theme: ActionTheme.LIGHT
    })
  ]
});
```

### 3. Manual Service Usage

```typescript
import { Component, OnInit } from '@angular/core';
import { XconVersionTrackerService } from '@stardyn/angular-updater';

@Component({
  selector: 'app-root',
  template: `
    <h1>{{ title }}</h1>
    <button (click)="checkForUpdates()">Check for Updates</button>
  `
})
export class AppComponent implements OnInit {
  title = 'My App with Version Tracking';

  constructor(private versionTracker: XconVersionTrackerService) {}

  ngOnInit() {
    // Service is automatically initialized via APP_INITIALIZER
    console.log('Version tracker is ready');
  }

  checkForUpdates() {
    // Manual configuration if needed
    this.versionTracker.configure({
      checkInterval: 60,
      debugMode: true,
      theme: ActionTheme.DARK
    });
  }
}
```

## API Reference

### XconVersionTrackerConfig

```typescript
interface XconVersionTrackerConfig {
  debugMode?: boolean;     // Enable/disable debug logging (default: false)
  checkInterval?: number;  // Version check interval in seconds (default: 60)
  theme: ActionTheme;     // UI theme for update dialogs (required)
}
```

### XconVersionTrackerService

#### Configuration

```typescript
// Configure the service
versionTracker.configure(config: XconVersionTrackerConfig): void
```

#### Initialization

The service is automatically initialized when provided via `provideXconVersionTracker()`. Manual initialization is not required.

```typescript
// Automatic initialization via APP_INITIALIZER
versionTracker.initialize(): void
```

### Provider Function

```typescript
// Provide the version tracker service with configuration
provideXconVersionTracker(config: XconVersionTrackerConfig): (Provider | EnvironmentProviders)[]
```

### Utility Functions

```typescript
// Reset singleton instance (useful for testing)
resetVersionTrackerInstance(): void
```

## Configuration Examples

### Development Configuration

```typescript
provideXconVersionTracker({
  checkInterval: 30, // Check every 30 seconds for quick testing
  debugMode: true,   // Enable detailed logging
  theme: ActionTheme.LIGHT
})
```

### Production Configuration

```typescript
provideXconVersionTracker({
  checkInterval: 600, // Check every 10 minutes
  debugMode: false,   // Disable logging for performance
  theme: ActionTheme.DARK
})
```

### Environment-Based Configuration

```typescript
// environments/environment.ts
export const environment = {
  production: false,
  versionTracker: {
    checkInterval: 60,
    debugMode: true,
    theme: ActionTheme.LIGHT
  }
};

// app.module.ts or main.ts
provideXconVersionTracker(environment.versionTracker)
```

## Update Flow

1. **Version Detection**: Service Worker detects a new version is available
2. **Download**: New version is downloaded in the background
3. **Ready Notification**: User is prompted with an update dialog
4. **User Choice**: User can accept or decline the update
5. **Update Application**: If accepted, page reloads with the new version

## Debug Output Examples

When debug mode is enabled, console outputs appear in this format:

```
[XconVersionTracker] XconVersionTracker service initialized
[XconVersionTracker] XconVersionTracker configured {checkInterval: 60, debugMode: true, theme: "light"}
[XconVersionTracker] Version Tracker Initializing
[XconVersionTracker] New application version found, beginning download: abc123def
[XconVersionTracker] New app version ready: xyz789ghi
```

## Dependencies

### Peer Dependencies

- `@angular/core` >= 16.0.0
- `@angular/common` >= 16.0.0
- `@angular/service-worker` >= 16.0.0
- `rxjs` >= 7.0.0

### Internal Dependencies

- `@stardyn/angular-console` - Console logging service
- `@stardyn/angular-core-ui-actions` - UI action dialogs and themes

## Performance

- **Service Worker Disabled**: Zero overhead - service returns early
- **Singleton Pattern**: Only one instance created regardless of provider calls
- **Zone Optimization**: Version checking runs outside Angular zone
- **Memory Efficient**: Minimal memory footprint with proper cleanup

## TypeScript Support

Full TypeScript support with intellisense and type safety:

```typescript
import { XconVersionTrackerConfig, ActionTheme } from '@stardyn/angular-updater';

const config: XconVersionTrackerConfig = {
  checkInterval: 300,
  debugMode: false,
  theme: ActionTheme.DARK
};
```

## Troubleshooting

### Service Worker Not Working

Ensure Angular Service Worker is properly configured:

```bash
ng add @angular/pwa
```

### Update Dialog Not Appearing

1. Check if Service Worker is enabled in your environment
2. Verify debug mode is enabled to see console logs
3. Ensure the app is served over HTTPS (required for Service Workers)

### Multiple Instance Warning

The service uses a singleton pattern. If you see multiple initialization messages, ensure you're only calling `provideXconVersionTracker()` once in your application.

## License

MIT License - see LICENSE file for details.

## Repository

https://github.com/stardyn/angular-updater