BnsightsUtilitiesLibrary

BBSF Utilities package is part of BBSF 3 packages. It has all the common services used by BBSF Admin Portal or BBSF Controls

For more info please visit BBSF Controls documentation or BBSF documentation

🔄 Two Ways to Use This Library

1️⃣ Backward Compatible (All-in-One Module)

For existing applications or quick setup, import the BBSFUtilitiesModule to get everything:

// app.module.ts
import { BBSFUtilitiesModule } from '@bnsights/bbsf-utilities';

@NgModule({
  imports: [
    BBSFUtilitiesModule,  // Includes ALL services and modules
    // ... other imports
  ]
})
export class AppModule { }

What you get:

• ✅ All services automatically registered
• ✅ BlockUI and Toastr modules pre-configured
• ✅ Works exactly like the original version
• ⚠️ Larger bundle size (includes all dependencies)

2️⃣ Modular (Optimized for Bundle Size)

For new applications or to optimize bundle size, use secondary entry points:

// app.module.ts
import { EnvironmentService } from '@bnsights/bbsf-utilities';
import { AuthService } from '@bnsights/bbsf-utilities/auth';
import { BBSFTranslateService } from '@bnsights/bbsf-utilities/translate';
import { UtilityService } from '@bnsights/bbsf-utilities/ui';
import { RequestHandlerService } from '@bnsights/bbsf-utilities/http';

@NgModule({
  providers: [
    EnvironmentService,
    AuthService,
    BBSFTranslateService,
    UtilityService,
    RequestHandlerService,
    // Only import what you need
  ]
})
export class AppModule { }

Benefits:

• 🚀 Smaller bundle size (only include what you use)
• 📦 Better tree-shaking
• ⚡ Faster build times

📦 Secondary Entry Points (Optimized Dependencies)

To optimize bundle size, the library now supports secondary entry points - only install what you use!

📋 Features & Imports

| Feature | Import From | Dependencies | Size | |---------|-------------|--------------|------| | Core (Environment, Styling) | @bnsights/bbsf-utilities | lodash nanoid tslib | 2 MB | | Authentication | @bnsights/bbsf-utilities/auth | @auth0/angular-jwt ngx-cookie-service oidc-client | +3 MB | | Word Generation ⚡ | @bnsights/bbsf-utilities/word | jszip xmlbuilder2 html-to-vdom virtual-dom + 5 more | +8 MB (lazy-loaded) | | Translation/i18n | @bnsights/bbsf-utilities/translate | @ngx-translate/core | +2 MB | | UI Services (Toasts, Loading, Validation) | @bnsights/bbsf-utilities/ui | ng-block-ui ngx-toastr | +3 MB | | HTTP Handling | @bnsights/bbsf-utilities/http | class-transformer | +1 MB |

🚀 Simple Setup (30 seconds)

Create: src/app/core/bbsf.ts

export { EnvironmentService } from '@bnsights/bbsf-utilities';
export { AuthService } from '@bnsights/bbsf-utilities/auth';
export { BBSFTranslateService } from '@bnsights/bbsf-utilities/translate';
export { UtilityService } from '@bnsights/bbsf-utilities/ui';
export { RequestHandlerService } from '@bnsights/bbsf-utilities/http';

Add to: tsconfig.json

{
  "compilerOptions": {
    "paths": { "@bbsf": ["src/app/core/bbsf.ts"] }
  }
}

Use:

import { AuthService } from '@bbsf';  // Simple! ✅

📊 Savings:

• Core only: 87% smaller (15MB → 2MB)
• Core + Auth: 67% smaller (15MB → 5MB)
• Everything: Same size (but other apps save!)

⚡ Word Generation - Automatic Lazy Loading

Word generation dependencies (xmlbuilder2, jszip, etc.) use dynamic imports - they're automatically split into a separate chunk and only loaded when you first call generateWordByteFile(). No code changes needed!

Benefits:

• ✅ Main bundle: ~8 MB smaller
• ✅ Word chunk: Loaded on-demand only when needed
• ✅ Backward compatible: Works with existing code
• ✅ Automatic: Handled by build tools

See XMLBUILDER2_FIX.md for technical details.

📚 Documentation

• BACKWARD_COMPATIBILITY.md - Understand both usage patterns (BBSFUtilitiesModule vs Modular) ⭐ START HERE
• USAGE.md - Complete feature table & examples
• MIGRATION_GUIDE.md - Migrate to modular imports (optional)
• TROUBLESHOOTING.md - Fix import issues

===================================================

Change Log

1.2.6 / 04-02-2026

===================

• Fixed login page redirect issues after successful authentication
• Resolved session timer persistence after logout
• Fixed authentication state synchronization problems
• Prevented token refresh conflicts with logout
• Improved cookie expiration handling
• Enhanced cross-tab logout support

1.2.5 / 18-1-2026

===================

• Fix authentication race conditions causing intermittent login redirects on new tab
• Add 10-second grace period to token expiration check to prevent timing issues
• Remove cookie deletion window during token refresh to eliminate state inconsistency
• Add cross-tab logout synchronization via storage events
• Prevent concurrent token refresh calls across multiple tabs with locking mechanism
• Enhance token validation with defensive checks in getUserManager()

1.2.4 5-1-2026

===================

• export ServiceWorkerHelperService to public api.

1.2.3 5-1-2026

===================

• introduce new service ServiceWorkerHelperService that contains service worker helper methods.

1.2.2 / 25-12-202h5

=====================

• Upgrade to angular 19
• Enhance Auth service
• Enhance Preload service

1.0.72 / 27/10/2025

=====================

🔄 Enhanced Backward Compatibility

• Clarified BBSFUtilitiesModule usage: The module now explicitly exports all necessary Angular modules (CommonModule, RouterModule, BlockUIModule, ToastrModule) for complete backward compatibility
• Two usage patterns supported:
  1. All-in-One: Import BBSFUtilitiesModule for everything (original behavior maintained)
  2. Modular: Import from secondary entry points for optimized bundles
• No breaking changes: Existing applications using BBSFUtilitiesModule continue to work unchanged
• Documentation added:
  • BACKWARD_COMPATIBILITY.md - Quick reference guide
  • Updated README with clear comparison of both approaches
  • Enhanced MIGRATION_GUIDE.md with "no migration required" section

Benefits

• ✅ Zero migration required for existing apps
• ✅ Full flexibility for new projects
• ✅ Clear documentation for both patterns
• ✅ All services and modules properly exported

1.0.71 / 27/10/2025

=====================

🚀 Major Bundle Size Optimization

• Fixed xmlbuilder2 bundling issue: Word generation dependencies (~8 MB) are now lazy-loaded using dynamic imports
• Benefit: Main application bundle is ~8 MB smaller - word dependencies only loaded when actually generating documents
• Breaking Changes: None - fully backward compatible
• Technical Details: See XMLBUILDER2_FIX.md

Changes

• Modified WordDocumentService.generateWordByteFile() to use dynamic imports
• Word generation dependencies (xmlbuilder2, jszip, html-to-vdom, etc.) automatically split into separate chunk
• Consuming applications get automatic bundle size reduction without code changes

1.0.70 / 26/10/2025

=====================

• Made some enhancements to the StylesBundleService's loadStyleBundle method

1.0.69 / 14/10/2025

=====================

• Remove Language loaded console log

1.0.68 / 15/9/2025

=====================

• Fix RequestHandlerService options initialization

1.0.67 / 15/9/2025

===================== Refactor AuthService and ConfigurationService for improved user management and dependency injection

• Changed user property in AuthService to a private getter with lazy initialization.
• Updated TOKEN_KEY to use a private getter for lazy loading.
• Refactored ConfigurationService to use Injector for AuthService dependency.
• Removed redundant cookie name check in EnvironmentService.

Enhance AppSettingsLogic and BBSFBaseConfig for improved configuration handling

• Added logic to include additional custom variables in AppSettingsLogic.
• Introduced a list of default keys to populate configuration properties from BBSFBaseConfig.
• Refactored BBSFBaseConfig to use a helper method for retrieving configuration values, ensuring defaults are applied where necessary.

1.0.66 / 28-8-2025

=====================

• Add LanguageService and SpeechRecognitionService in BBSFUtilitiesModule for consistency.

1.0.65 /

=====================

1.0.64 / 26-8-2025

=====================

• Add function to check if user permission set in Roles.

1.0.62 / 11-8-2025

=====================

• Adding the ability to change the auth-service cookie name.

1.0.60 / 16-2-2024

=====================

• remove console.log

1.0.59 / 16-2-2024

=====================

• Add FileLoader to load environment.js, and translation files before app start
  • to use it add APP_INITIALIZER to use this Service inside ur app.module.ts

    export function initializeApp(preload: FileLoaderService) {
    return () => preload.loadEnvironment();
    }

    export function preloadTranslationsFactory(preload: FileLoaderService) {
    return () => preload.preloadTranslations();
    }

    {
      provide: APP_INITIALIZER,
      useFactory: initializeApp,
      deps: [FileLoaderService],
      multi: true,
    },
    {
      provide: APP_INITIALIZER,
      useFactory: preloadTranslationsFactory,
      deps: [FileLoaderService],
      multi: true,
    }

1.0.58 / 9-9-2024

===================== -multi tenant

1.0.57 / 8-8-2024

=================== -Update speech language model

1.0.56 / 4-8-2024

=================== -Added SpeechRecognitionService

1.0.55 / 3-6-2024

=================== -switching UAEPass login portal language based on user current language

1.0.54 / 2-4-2024

=================== -Fix Switching Language

1.0.53 / 1-4-2024

=================== -Fix Inertnet Connection Issue

1.0.52 / 28-3-2024

=================== -Fix Switching Language And Logout Issue

1.0.51 / 27-3-2024

=================== -Fix Redirect Url Issue

1.0.50 / 12-3-2024

=================== -Update query string 'state' in UAE Pass to contain current language

1.0.49 / 6-3-2024

=================== -Update AuthService To Delete Cookies

1.0.48 / 5-3-2024

=================== -Update AuthService To Handel Cookies

1.0.47 / 5-3-2024

=================== -Update AuthService To Fix Login Bug

1.0.46 / 8-2-2024

=================== -Update AuthService Access Token Handel

1.0.45 / 8-2-2024

=================== -Update AuthService Access Token Handel

1.0.44 / 4-1-2024

=================== -Update Request Handler For Upload File Async

1.0.43 / 11-12-2023

===================

• Upgraded Angular version (17) and upgraded related libraries.

1.0.41 / 3-12-2023

===================

• Update Environment Service && Fix all Merge Issues

1.0.40 / 29-11-2023

===================

• Update Environment Service To Check Windows Authentication

1.0.39 / 19-11-2023

===================

• Remove Login Function From Auth Service

1.0.38 / 16-11-2023

===================

• Remove Identity Server And Use JWT Authentication

1.0.36 / 19-7-2023

===================

• Update Control Validation Service

1.0.35 / 27-3-2022

===================

• Add Word Document Service
• Update Angular Version

1.0.34 / 26-3-2022 (!!!Warning!! Testing Release)

===================

• Only For Test

##1.0.33 / 22-3-2022

• Add Word Document Service

##1.0.31 / 5-1-2022

• Solve Change Language Issue

##1.0.30 / 3-1-2022

• Update Auth Service With ClearUserSessionClaims Function

##1.0.29 / 25-12-2022

• Update Request Handler Service

##1.0.28 / 22-12-2022

• Update Auth Service to enable external identity server integration
• Update Environment Service to read external identity configuration

##1.0.27 / 05-12-2022

• Update handleError() Function in Request Handler Service

##1.0.24 / 14-8-2022

• Add Configuration Service to read configurations from (configurations.json)
• Update Appearance Configuration Service to read from Configuration Service using (getConfigurationValue(key))

##1.0.23 / 28-7-2022

• Replace lang attribute with b-lang

##1.0.22 / 28-7-2022

• Add switchRole to masterlayout service

##1.0.21 / 4-7-2022

• Add castResponsetoClass (bool) by default is true to RequestOptionsModel to fix the issue when return type is arraybuffer
• Fix in all RequestHandlerService methods check if false return data and if true return plainToClass of data

##1.0.20 / 2-6-2022

• Add disableErrorHandler to RequestOptionsModel by default = false
• Handle requesthandler service if (disableErrorHandler) is true all requests will not handle error
• Remove "success" title from notifySuccessMessage

##1.0.18 / 16-5-2022

• Update Models

##1.0.17 / 27-4-2022

• Update Request Handler

##1.0.15 / 30-3-2022

• Update Toaster header

##1.0.14 / 29-3-2022

• Update request handler (add Client-Local-Time-Zone to header)

##1.0.13 / 22-3-2022

• Initial Version