@angular-helpers/browser-web-apis 21.10.0 → 21.11.0

package/fesm2022/angular-helpers-browser-web-apis.mjs

@@ -1,22 +1,66 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, Injectable, inject, DestroyRef, PLATFORM_ID, signal, computed, isSignal, effect, ElementRef, makeEnvironmentProviders } from '@angular/core';
+import { InjectionToken, isDevMode, inject, Injectable, DestroyRef, PLATFORM_ID, signal, computed, isSignal, effect, ElementRef, makeEnvironmentProviders } from '@angular/core';
 import { isPlatformBrowser, isPlatformServer } from '@angular/common';
 import { Observable, fromEvent, Subject, of, map as map$1 } from 'rxjs';
 import { toObservable, takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { filter, map, distinctUntilChanged } from 'rxjs/operators';
 import { Router } from '@angular/router';
 
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 100,
+};
+/**
+ * Global log level for `BROWSER_API_LOGGER`. Defaults to `'debug'` in dev mode and
+ * `'warn'` in production. Override via `provideBrowserApiLogLevel('silent')` etc.
+ */
+const BROWSER_API_LOG_LEVEL = new InjectionToken('BROWSER_API_LOG_LEVEL', {
+    providedIn: 'root',
+    factory: () => (isDevMode() ? 'debug' : 'warn'),
+});
 const BROWSER_API_LOGGER = new InjectionToken('BROWSER_API_LOGGER', {
     providedIn: 'root',
-    factory: () => ({
-        // oxlint-disable-next-line no-console
-        info: (message) => console.info(message),
-        // oxlint-disable-next-line no-console
-        warn: (message) => console.warn(message),
-        // oxlint-disable-next-line no-console
-        error: (message, error) => console.error(message, error),
-    }),
+    factory: () => {
+        const level = inject(BROWSER_API_LOG_LEVEL);
+        return createLevelGatedLogger(level);
+    },
 });
+function createLevelGatedLogger(level) {
+    const min = LEVEL_RANK[level];
+    return {
+        debug: (message) => {
+            if (LEVEL_RANK.debug < min)
+                return;
+            // oxlint-disable-next-line no-console
+            console.debug(message);
+        },
+        info: (message) => {
+            if (LEVEL_RANK.info < min)
+                return;
+            // oxlint-disable-next-line no-console
+            console.info(message);
+        },
+        warn: (message) => {
+            if (LEVEL_RANK.warn < min)
+                return;
+            // oxlint-disable-next-line no-console
+            console.warn(message);
+        },
+        error: (message, error) => {
+            if (LEVEL_RANK.error < min)
+                return;
+            // oxlint-disable-next-line no-console
+            console.error(message, error);
+        },
+    };
+}
+/** Log level helper provider. Overrides the default `BROWSER_API_LOG_LEVEL`. */
+function provideBrowserApiLogLevel(level) {
+    return { provide: BROWSER_API_LOG_LEVEL, useValue: level };
+}
 
 const BROWSER_CAPABILITIES = [
     { id: 'permissions', label: 'Permissions API', requiresSecureContext: false },
@@ -267,6 +311,9 @@ class BrowserApiBaseService {
     logInfo(message) {
         this.logger.info(`[${this.getApiName()}] ${message}`);
     }
+    logDebug(message) {
+        this.logger.debug?.(`[${this.getApiName()}] ${message}`);
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: BrowserApiBaseService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: BrowserApiBaseService });
 }
@@ -3285,6 +3332,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
             type: Injectable
         }] });
 
+/**
+ * When set to `true`, suppresses the one-time runtime warning that experimental
+ * services emit on first use. Default is `false` (warnings emitted).
+ */
+const BROWSER_API_EXPERIMENTAL_SILENT = new InjectionToken('BROWSER_API_EXPERIMENTAL_SILENT', {
+    providedIn: 'root',
+    factory: () => false,
+});
+const warned = new Set();
+/**
+ * Emit a one-time runtime warning explaining that the API is experimental and
+ * subject to breaking changes. No-op after the first call for a given key, or if
+ * the consumer has provided `BROWSER_API_EXPERIMENTAL_SILENT` as `true`.
+ */
+function warnExperimental(key, context) {
+    if (context.silent)
+        return;
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    context.logger.warn(`[browser-web-apis:experimental] "${key}" is part of the experimental surface ` +
+        'and may change without a major bump. Provide BROWSER_API_EXPERIMENTAL_SILENT=true ' +
+        'to suppress this warning.');
+}
+/** Test-only: reset the in-memory dedup set. */
+function resetExperimentalWarnings() {
+    warned.clear();
+}
+
 // Common types for browser APIs
 
 function injectPageVisibility() {
@@ -4000,9 +4076,33 @@ const defaultBrowserWebApisConfig = {
     enableWebAudio: false,
     enableGamepad: false,
 };
+let legacyFlagsDeprecationLogged = false;
 function provideBrowserWebApis(config = {}) {
-    const mergedConfig = { ...defaultBrowserWebApisConfig, ...config };
+    const { services, ...flagConfig } = config;
+    // Composition-first path: only `services` provided, no flags.
+    if (services && Object.keys(flagConfig).length === 0) {
+        return makeEnvironmentProviders([
+            PermissionsService,
+            ...services.flatMap((env) => env.ɵproviders ?? []),
+        ]);
+    }
+    // Legacy flag-bag path. Log deprecation once if any enableX is set.
+    if (Object.keys(flagConfig).length > 0 && !legacyFlagsDeprecationLogged) {
+        legacyFlagsDeprecationLogged = true;
+        // oxlint-disable-next-line no-console
+        console.warn('[browser-web-apis] provideBrowserWebApis(enableX flags) is deprecated. ' +
+            'Pass `{ services: [provideCamera(), ...] }` instead. The flag-bag form will be ' +
+            'removed in v22.');
+    }
+    const mergedConfig = { ...defaultBrowserWebApisConfig, ...flagConfig };
     const providers = [PermissionsService];
+    if (services) {
+        for (const env of services) {
+            const inner = env.ɵproviders;
+            if (inner)
+                providers.push(...inner);
+        }
+    }
     const conditionalProviders = [
         [mergedConfig.enableCamera, CameraService],
         [mergedConfig.enableGeolocation, GeolocationService],
@@ -4048,4 +4148,4 @@ const version = '0.1.0';
  * Generated bundle index. Do not edit.
  */
 
-export { BROWSER_API_LOGGER, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, CompressionService, ConnectionRegistryBaseService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, StorageManagerService, VibrationService, WebAudioService, WebLocksService, WebShareService, WebSocketClient, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectBattery, injectClipboard, injectGamepad, injectGeolocation, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, injectWakeLock, permissionGuard, provideBattery, provideBroadcastChannel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideCompression, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideStorageManager, provideVibration, provideWebAudio, provideWebLocks, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version };
+export { BROWSER_API_EXPERIMENTAL_SILENT, BROWSER_API_LOGGER, BROWSER_API_LOG_LEVEL, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, CompressionService, ConnectionRegistryBaseService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, StorageManagerService, VibrationService, WebAudioService, WebLocksService, WebShareService, WebSocketClient, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectBattery, injectClipboard, injectGamepad, injectGeolocation, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, injectWakeLock, permissionGuard, provideBattery, provideBroadcastChannel, provideBrowserApiLogLevel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideCompression, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideStorageManager, provideVibration, provideWebAudio, provideWebLocks, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version, warnExperimental };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/browser-web-apis",
-  "version": "21.10.0",
+  "version": "21.11.0",
   "description": "Sistema de servicios Angular para acceso formalizado a Browser Web APIs (cámara, permisos, geolocalización, etc.)",
   "homepage": "https://gaspar1992.github.io/angular-helpers/docs/browser-web-apis",
   "repository": {

package/types/angular-helpers-browser-web-apis.d.ts

@@ -230,6 +230,7 @@ declare abstract class BrowserApiBaseService {
     protected logError(message: string, error?: unknown): void;
     protected logWarn(message: string): void;
     protected logInfo(message: string): void;
+    protected logDebug(message: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<BrowserApiBaseService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<BrowserApiBaseService>;
 }
@@ -392,12 +393,24 @@ type ErrorCallback = (error: BrowserError) => void;
  */
 type ElementInput = Element | ElementRef<Element> | Signal<Element | ElementRef<Element> | undefined>;
 
+type BrowserApiLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 interface BrowserApiLogger {
+    debug?(message: string): void;
     info(message: string): void;
     warn(message: string): void;
     error(message: string, error?: unknown): void;
 }
+/**
+ * Global log level for `BROWSER_API_LOGGER`. Defaults to `'debug'` in dev mode and
+ * `'warn'` in production. Override via `provideBrowserApiLogLevel('silent')` etc.
+ */
+declare const BROWSER_API_LOG_LEVEL: InjectionToken<BrowserApiLogLevel>;
 declare const BROWSER_API_LOGGER: InjectionToken<BrowserApiLogger>;
+/** Log level helper provider. Overrides the default `BROWSER_API_LOG_LEVEL`. */
+declare function provideBrowserApiLogLevel(level: BrowserApiLogLevel): {
+    provide: InjectionToken<BrowserApiLogLevel>;
+    useValue: BrowserApiLogLevel;
+};
 
 interface StorageOptions {
     /** Optional prefix used to namespace keys (e.g. `app:` -> `app:userId`). */
@@ -1242,6 +1255,24 @@ declare class CompressionService extends BrowserApiBaseService {
     static ɵprov: i0.ɵɵInjectableDeclaration<CompressionService>;
 }
 
+/**
+ * When set to `true`, suppresses the one-time runtime warning that experimental
+ * services emit on first use. Default is `false` (warnings emitted).
+ */
+declare const BROWSER_API_EXPERIMENTAL_SILENT: InjectionToken<boolean>;
+interface ExperimentalWarnContext {
+    silent: boolean;
+    logger: {
+        warn: (message: string) => void;
+    };
+}
+/**
+ * Emit a one-time runtime warning explaining that the API is experimental and
+ * subject to breaking changes. No-op after the first call for a given key, or if
+ * the consumer has provided `BROWSER_API_EXPERIMENTAL_SILENT` as `true`.
+ */
+declare function warnExperimental(key: string, context: ExperimentalWarnContext): void;
+
 interface MediaDevice {
     deviceId: string;
     groupId: string;
@@ -1547,7 +1578,20 @@ declare function provideLocationApis(): EnvironmentProviders;
 declare function provideStorageApis(): EnvironmentProviders;
 declare function provideCommunicationApis(): EnvironmentProviders;
 
-interface BrowserWebApisConfig {
+/**
+ * Composition-first config: pass an array of `provide*()` calls and we merge them
+ * into a single `EnvironmentProviders`. Preferred over the `enableX` flag bag.
+ *
+ * ```ts
+ * provideBrowserWebApis({
+ *   services: [provideCamera(), provideClipboard(), provideMediaApis()],
+ * })
+ * ```
+ */
+interface BrowserWebApisCompositionConfig {
+    services?: EnvironmentProviders[];
+}
+interface BrowserWebApisConfig extends BrowserWebApisCompositionConfig {
     enableCamera?: boolean;
     enableGeolocation?: boolean;
     enableNotifications?: boolean;
@@ -1581,5 +1625,5 @@ declare function provideBrowserWebApis(config?: BrowserWebApisConfig): Environme
 
 declare const version = "0.1.0";
 
-export { BROWSER_API_LOGGER, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, CompressionService, ConnectionRegistryBaseService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, StorageManagerService, VibrationService, WebAudioService, WebLocksService, WebShareService, WebSocketClient, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectBattery, injectClipboard, injectGamepad, injectGeolocation, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, injectWakeLock, permissionGuard, provideBattery, provideBroadcastChannel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideCompression, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideStorageManager, provideVibration, provideWebAudio, provideWebLocks, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version };
-export type { AudioAnalyserData, AudioContextState, BatteryInfo, BatteryManager, BatteryRef, BrowserApiLogger, BrowserCapabilityId, BrowserError, BrowserPermissions, BrowserWebApisConfig, CameraCapabilities, CameraInfo, ClipboardRef, CompressionFormat, ConnectionType, EffectiveConnectionType, ElementInput, ElementSize, ErrorCallback, EventHandler, FileOpenOptions, FileSaveOptions, GamepadRef, GamepadState, GeolocationCoordinates, GeolocationError, GeolocationOptions, GeolocationPosition$1 as GeolocationPosition, GeolocationRef, GeolocationWatchOptions, IntersectionObserverOptions, IntersectionRef, MediaDevice, MediaDeviceKind, MediaDevicesInfo, MediaStreamConstraints$1 as MediaStreamConstraints, MediaTrackConstraints$1 as MediaTrackConstraints, MutationObserverOptions, MutationRef, NetworkInformation, NetworkInformationRef, OrientationInfo, OrientationLockType, OrientationType, PageVisibilityRef, PerformanceEntryType, PerformanceObserverConfig, PerformanceObserverRef, PermissionNameExt, PermissionRequest, RecordingOptions, RecordingResult, RecordingState, ResizeObserverOptions, ResizeRef, SSEConfig, SSEConnectionState, SSEMessage, ScreenOrientationRef, SpeechOptions, SpeechState, StorageEvent, StorageNamespace, StorageOptions, StorageQuotaEstimate, StorageValue, VibrationPattern, VibrationPreset, VisibilityState, WakeLockRef, WakeLockStatus, WakeLockType, WebSocketClientConfig, WebSocketConfig, WebSocketMessage, WebSocketRequestOptions, WebSocketState, WebSocketStatus, WebSocketStatusV2, WorkerMessage, WorkerRequestOptions, WorkerStatus, WorkerTask };
+export { BROWSER_API_EXPERIMENTAL_SILENT, BROWSER_API_LOGGER, BROWSER_API_LOG_LEVEL, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, CompressionService, ConnectionRegistryBaseService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, StorageManagerService, VibrationService, WebAudioService, WebLocksService, WebShareService, WebSocketClient, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectBattery, injectClipboard, injectGamepad, injectGeolocation, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, injectWakeLock, permissionGuard, provideBattery, provideBroadcastChannel, provideBrowserApiLogLevel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideCompression, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideStorageManager, provideVibration, provideWebAudio, provideWebLocks, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version, warnExperimental };
+export type { AudioAnalyserData, AudioContextState, BatteryInfo, BatteryManager, BatteryRef, BrowserApiLogLevel, BrowserApiLogger, BrowserCapabilityId, BrowserError, BrowserPermissions, BrowserWebApisCompositionConfig, BrowserWebApisConfig, CameraCapabilities, CameraInfo, ClipboardRef, CompressionFormat, ConnectionType, EffectiveConnectionType, ElementInput, ElementSize, ErrorCallback, EventHandler, ExperimentalWarnContext, FileOpenOptions, FileSaveOptions, GamepadRef, GamepadState, GeolocationCoordinates, GeolocationError, GeolocationOptions, GeolocationPosition$1 as GeolocationPosition, GeolocationRef, GeolocationWatchOptions, IntersectionObserverOptions, IntersectionRef, MediaDevice, MediaDeviceKind, MediaDevicesInfo, MediaStreamConstraints$1 as MediaStreamConstraints, MediaTrackConstraints$1 as MediaTrackConstraints, MutationObserverOptions, MutationRef, NetworkInformation, NetworkInformationRef, OrientationInfo, OrientationLockType, OrientationType, PageVisibilityRef, PerformanceEntryType, PerformanceObserverConfig, PerformanceObserverRef, PermissionNameExt, PermissionRequest, RecordingOptions, RecordingResult, RecordingState, ResizeObserverOptions, ResizeRef, SSEConfig, SSEConnectionState, SSEMessage, ScreenOrientationRef, SpeechOptions, SpeechState, StorageEvent, StorageNamespace, StorageOptions, StorageQuotaEstimate, StorageValue, VibrationPattern, VibrationPreset, VisibilityState, WakeLockRef, WakeLockStatus, WakeLockType, WebSocketClientConfig, WebSocketConfig, WebSocketMessage, WebSocketRequestOptions, WebSocketState, WebSocketStatus, WebSocketStatusV2, WorkerMessage, WorkerRequestOptions, WorkerStatus, WorkerTask };