v2c-any 0.2.1 → 0.3.1

package/dist/device/shelly-pro-em/em1-status-provider.js

@@ -1,10 +1,8 @@
 import { Client, interceptors } from 'undici';
 import { logger } from '../../utils/logger.js';
 import { energyTypeToId } from '../../utils/mappers.js';
-import { AsymmetricEMAProvider } from '../../provider/asymmetric-emea-provider.js';
-import { RetryableProvider } from '../../provider/retryable-provider.js';
-import { em1StatusInterpolator } from '../../utils/interpolator.js';
-import { DecoratorProviderFactory } from '../../factory/decorator-provider-factory.js';
+import { createResiliantProvider } from '../../utils/resiliance.js';
+import { em1StatusComparator, em1StatusInterpolator, em1StatusZeroValue, } from '../../utils/interpolator.js';
 /**
  * Provider that fetches EM1 status data from a Shelly Pro EM device via HTTP.
  * Retrieves real-time energy monitoring data by querying the device's RPC API endpoint.
@@ -48,20 +46,12 @@ class EM1StatusProviderFactory {
      */
     create(options) {
         logger.debug({ ip: options.properties.ip, energyType: options.energyType }, 'Creating EM1StatusProvider');
-        return new EM1StatusProvider(options.properties.ip, options.energyType);
+        const provider = new EM1StatusProvider(options.properties.ip, options.energyType);
+        return createResiliantProvider(provider, em1StatusInterpolator, em1StatusZeroValue, em1StatusComparator, options.properties.breaker, options.properties.retry, options.properties.ema);
     }
 }
 /**
  * Singleton factory instance for creating `EM1StatusProvider` objects.
  * Provides a ready-to-use factory to build providers with supplied options.
  */
-const localEm1StatusProviderFactory = new EM1StatusProviderFactory();
-export const em1StatusProviderFactory = new DecoratorProviderFactory(localEm1StatusProviderFactory, (provider) => new AsymmetricEMAProvider(new RetryableProvider(provider, { retries: 3 }), em1StatusInterpolator, {
-    alphaRise: 1,
-    alphaFall: 0.2,
-    comparator: (a, b) => {
-        const powerA = a?.act_power ?? 0;
-        const powerB = b?.act_power ?? 0;
-        return powerA - powerB;
-    },
-}));
+export const em1StatusProviderFactory = new EM1StatusProviderFactory();

package/dist/provider/asymmetric-ema-provider.js

@@ -0,0 +1,86 @@
+import { logger } from '../utils/logger.js';
+/**
+ * Generic Asymmetric EMA Provider using algebraic interpolators.
+ * Implements exponential moving average (EMA) with different smoothing factors
+ * for rising and falling values, allowing asymmetric response to changes.
+ *
+ * @template T - The type of value this provider supplies
+ */
+export class AsymmetricEMAProvider {
+    /**
+     * Creates a new InnerAsymmetricEMAProvider.
+     * @param provider - The underlying provider to fetch raw values from
+     * @param interpolator - The interpolator to use for blending values
+     * @param options - Configuration options for the asymmetric EMA calculation
+     * @throws {Error} If alphaRise or alphaFall is not between 0 and 1
+     */
+    constructor(provider, interpolator, options) {
+        this.provider = provider;
+        this.interpolator = interpolator;
+        this.options = options;
+        this.ema = null;
+        this.lastUpdateTime = null;
+        if (options.alphaRise < 0 || options.alphaRise > 1) {
+            throw new Error('alphaRise must be between 0 and 1');
+        }
+        if (options.alphaFall < 0 || options.alphaFall > 1) {
+            throw new Error('alphaFall must be between 0 and 1');
+        }
+    }
+    onNewValue(newValue) {
+        if (this.ema === null) {
+            this.ema = newValue;
+        }
+        // Determine if value is rising or falling
+        const comparison = this.options.comparator(newValue, this.ema);
+        const alpha = comparison >= 0 ? this.options.alphaRise : this.options.alphaFall;
+        this.ema = this.interpolator.interpolate(newValue, this.ema, alpha);
+    }
+    onMissingValue() {
+        if (this.ema !== null) {
+            this.ema = this.interpolator.interpolate(this.options.zeroValue, this.ema, this.options.alphaMissing);
+        }
+    }
+    /**
+     * Fetches a value from the wrapped provider and updates the EMA.
+     * On first call, initializes the EMA with the fetched value.
+     * On subsequent calls, interpolates between the new value and current EMA,
+     * using alphaRise if the value is increasing or alphaFall if decreasing.
+     * @returns A promise that resolves to the updated EMA value
+     */
+    async get() {
+        try {
+            const newValue = await this.provider.get();
+            this.lastUpdateTime = Date.now();
+            this.onNewValue(newValue);
+            return newValue;
+        }
+        catch (error) {
+            if (this.options.freshnessThreshold === undefined ||
+                this.lastUpdateTime === null ||
+                Date.now() - this.lastUpdateTime >= this.options.freshnessThreshold) {
+                logger.info('Handling missing value');
+                this.onMissingValue();
+            }
+            if (this.ema !== null) {
+                logger.warn({ ema: this.ema }, 'Returning last EMA value');
+                return this.ema;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Gets the current EMA value without fetching a new value.
+     * @returns The current EMA value, or null if not yet initialized
+     */
+    getCurrentEMA() {
+        return this.ema;
+    }
+    /**
+     * Resets the EMA to its initial state.
+     * The next call to get() will reinitialize the EMA.
+     */
+    reset(value = null) {
+        this.ema = value;
+    }
+}

package/dist/provider/circuit-breaker-provider.js

@@ -0,0 +1,30 @@
+import CircuitBreaker from 'opossum';
+/**
+ * Resilient Asymmetric EMA Provider with circuit breaker pattern.
+ * Wraps an InnerAsymmetricEMAProvider with resilience features, providing
+ * fallback to the last known EMA value when the underlying provider fails.
+ *
+ * @template T - The type of value this provider supplies
+ */
+export class CircuitBreakerProvider {
+    /**
+     * Creates a new AsymmetricEMAProvider with circuit breaker protection.
+     * @param provider - The underlying provider to fetch raw values from
+     * @param interpolator - The interpolator to use for blending values
+     * @param asymmetricEmaOptions - Configuration options for the asymmetric EMA calculation
+     */
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+        this.circuitBreaker = new CircuitBreaker(this.provider.get.bind(this.provider), this.options);
+    }
+    /**
+     * Fetches the value from the wrapped provider with resilience features.
+     * If the underlying provider fails or times out, falls back to the last known EMA value.
+     * @returns A promise that resolves to the EMA value
+     * @throws {Error} If no EMA value is available for fallback when the provider fails
+     */
+    get() {
+        return this.circuitBreaker.fire();
+    }
+}

package/dist/provider/retryable-provider.js

@@ -1,5 +1,4 @@
 import pRetry from 'p-retry';
-import { logger } from '../utils/logger.js';
 /**
  * Provider that wraps another provider with automatic retry logic.
  * Uses exponential backoff strategy to retry failed operations,
@@ -27,11 +26,6 @@ export class RetryableProvider {
         const run = async () => {
             return this.provider.get();
         };
-        return pRetry(run, {
-            ...this.options,
-            onFailedAttempt: (error) => {
-                logger.warn(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
-            },
-        });
+        return pRetry(run, this.options);
     }
 }

package/dist/schema/common-configuration.js

@@ -0,0 +1,24 @@
+import z from 'zod';
+export const breakerScehema = z.object({
+    timeout: z.number().int().nonnegative().optional(),
+    errorThresholdPercentage: z.number().min(0).max(100).optional(),
+    resetTimeout: z.number().int().nonnegative().optional(),
+    rollingCountTimeout: z.number().int().nonnegative().optional(),
+    rollingCountBuckets: z.number().int().positive().optional(),
+    volumeThreshold: z.number().int().nonnegative().optional(),
+    allowWarmUp: z.boolean().optional(),
+});
+export const retrySchema = z.object({
+    attempts: z.number().int().nonnegative().optional(),
+    factor: z.number().positive().optional(),
+    minTimeout: z.number().int().nonnegative().optional(),
+    maxTimeout: z.number().int().nonnegative().optional(),
+    randomize: z.boolean().optional(),
+    maxRetryTime: z.number().int().nonnegative().optional(),
+});
+export const emaSchema = z.object({
+    alphaRise: z.number().min(0).max(1),
+    alphaFall: z.number().min(0).max(1),
+    alphaMissing: z.number().min(0).max(1),
+    freshnessThreshold: z.number().int().nonnegative().optional(),
+});

package/dist/schema/mqtt-configuration.js

@@ -1,4 +1,5 @@
 import z from 'zod';
+import { breakerScehema, emaSchema, retrySchema, } from './common-configuration.js';
 export const energyInformationSchema = z.object({
     power: z.number(),
 });
@@ -27,6 +28,9 @@ export const mqttPullAdapterFeedSchema = z
     interval: z.number().int().nonnegative(),
     device: z.string(),
     ip: z.string(),
+    breaker: breakerScehema.optional(),
+    retry: retrySchema.optional(),
+    ema: emaSchema.optional(),
 })
     .loose();
 export const mqttPullFeedSchema = z.discriminatedUnion('type', [

package/dist/schema/rest-configuration.js

@@ -1,4 +1,5 @@
 import z from 'zod';
+import { breakerScehema, emaSchema, retrySchema, } from './common-configuration.js';
 // EM1 status (used by mock emulator response)
 export const em1StatusSchema = z.object({
     /**
@@ -46,6 +47,9 @@ export const restAdapterFeedSchema = z
     .object({
     ip: z.string(),
     device: z.string(),
+    breaker: breakerScehema.optional(),
+    retry: retrySchema.optional(),
+    ema: emaSchema.optional(),
 })
     .loose();
 export const restMockFeedSchema = z

package/dist/utils/interpolator.js

@@ -11,3 +11,20 @@ export const em1StatusInterpolator = Interpolators.object({
     errors: Interpolators.identity(),
     flags: Interpolators.identity(),
 });
+export const em1StatusComparator = (a, b) => {
+    const powerA = a.act_power ?? 0;
+    const powerB = b.act_power ?? 0;
+    return powerA - powerB;
+};
+export const em1StatusZeroValue = {
+    id: 0,
+    calibration: '',
+    current: 0,
+    voltage: 0,
+    act_power: 0,
+    aprt_power: 0,
+    pf: 0,
+    freq: 0,
+    errors: [],
+    flags: [],
+};

package/dist/utils/resiliance.js

@@ -0,0 +1,48 @@
+import { AsymmetricEMAProvider } from '../provider/asymmetric-ema-provider.js';
+import { CircuitBreakerProvider } from '../provider/circuit-breaker-provider.js';
+import { RetryableProvider } from '../provider/retryable-provider.js';
+import { logger } from './logger.js';
+export function createResiliantProvider(provider, interpolator, zeroValue, comparator, breakerOptions, retryOptions, emaOptions) {
+    let result = provider;
+    if (breakerOptions) {
+        result = new CircuitBreakerProvider(result, breakerOptions);
+    }
+    if (retryOptions) {
+        result = new RetryableProvider(result, {
+            retries: retryOptions.attempts,
+            factor: retryOptions.factor,
+            minTimeout: retryOptions.minTimeout,
+            maxTimeout: retryOptions.maxTimeout,
+            randomize: retryOptions.randomize,
+            maxRetryTime: retryOptions.maxRetryTime,
+            shouldRetry: (context) => {
+                const error = context.error;
+                if (error.code === 'EOPENBREAKER') {
+                    // Do not retry if circuit is open
+                    return false;
+                }
+                return true;
+            },
+            onFailedAttempt: (context) => {
+                const attributes = {
+                    message: context.error.message,
+                    attemptNumber: context.attemptNumber,
+                    retriesLeft: context.retriesLeft,
+                    retriesConsumed: context.retriesConsumed,
+                };
+                logger.warn({ attributes }, 'Attempt to get value failed');
+            },
+        });
+    }
+    if (emaOptions) {
+        result = new AsymmetricEMAProvider(result, interpolator, {
+            alphaRise: emaOptions?.alphaRise,
+            alphaFall: emaOptions?.alphaFall,
+            alphaMissing: emaOptions?.alphaMissing,
+            freshnessThreshold: emaOptions?.freshnessThreshold,
+            zeroValue,
+            comparator,
+        });
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v2c-any",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "description": "Turn any device into V2C Dynamic Power Control",
   "main": "dist/index.js",

package/dist/factory/decorator-provider-factory.js

@@ -1,40 +0,0 @@
-/**
- * Generic factory that wraps another provider factory with a decorator pattern.
- * Enables composition by allowing providers to be enhanced with additional behavior
- * such as retry logic, caching, logging, validation, etc.
- *
- * This factory creates providers by first using the wrapped factory to create a base provider,
- * then applying a decorator function to enhance it with additional capabilities.
- *
- * @example
- * // Creating a provider factory with retry capability
- * const retryDecorator = (provider) => new RetryableProvider(provider, { retries: 3 });
- * const resilientFactory = new DecoratorProviderFactory(baseFactory, retryDecorator);
- * const resilientProvider = resilientFactory.create(options);
- *
- * @template Options - The configuration options type required by the wrapped factory
- * @template T - The type of data the created providers will supply
- */
-export class DecoratorProviderFactory {
-    /**
-     * Creates a new decorator provider factory.
-     * @param providerFactory - The underlying factory that creates base providers
-     * @param decorator - Function that enhances providers with additional behavior
-     */
-    constructor(providerFactory, decorator) {
-        this.providerFactory = providerFactory;
-        this.decorator = decorator;
-    }
-    /**
-     * Creates a decorated provider using the wrapped factory and decorator function.
-     * First creates a base provider using the wrapped factory, then applies the decorator
-     * to enhance it with additional capabilities.
-     *
-     * @param options - Configuration options for the wrapped provider factory
-     * @returns A decorated provider with enhanced behavior
-     */
-    create(options) {
-        const baseProvider = this.providerFactory.create(options);
-        return this.decorator(baseProvider);
-    }
-}

package/dist/provider/asymmetric-emea-provider.js

@@ -1,104 +0,0 @@
-import { logger } from '../utils/logger.js';
-import CircuitBreaker from 'opossum';
-/**
- * Generic Asymmetric EMA Provider using algebraic interpolators.
- * Implements exponential moving average (EMA) with different smoothing factors
- * for rising and falling values, allowing asymmetric response to changes.
- *
- * @template T - The type of value this provider supplies
- */
-class InnerAsymmetricEMAProvider {
-    /**
-     * Creates a new InnerAsymmetricEMAProvider.
-     * @param provider - The underlying provider to fetch raw values from
-     * @param interpolator - The interpolator to use for blending values
-     * @param options - Configuration options for the asymmetric EMA calculation
-     * @throws {Error} If alphaRise or alphaFall is not between 0 and 1
-     */
-    constructor(provider, interpolator, options) {
-        this.provider = provider;
-        this.interpolator = interpolator;
-        this.options = options;
-        this.ema = null;
-        if (options.alphaRise < 0 || options.alphaRise > 1) {
-            throw new Error('alphaRise must be between 0 and 1');
-        }
-        if (options.alphaFall < 0 || options.alphaFall > 1) {
-            throw new Error('alphaFall must be between 0 and 1');
-        }
-    }
-    /**
-     * Fetches a value from the wrapped provider and updates the EMA.
-     * On first call, initializes the EMA with the fetched value.
-     * On subsequent calls, interpolates between the new value and current EMA,
-     * using alphaRise if the value is increasing or alphaFall if decreasing.
-     * @returns A promise that resolves to the updated EMA value
-     */
-    async get() {
-        const newValue = await this.provider.get();
-        if (this.ema === null) {
-            this.ema = newValue;
-        }
-        else {
-            // Determine if value is rising or falling
-            const comparison = this.options.comparator(newValue, this.ema);
-            const alpha = comparison >= 0 ? this.options.alphaRise : this.options.alphaFall;
-            this.ema = this.interpolator.interpolate(newValue, this.ema, alpha);
-        }
-        return this.ema;
-    }
-    /**
-     * Gets the current EMA value without fetching a new value.
-     * @returns The current EMA value, or null if not yet initialized
-     */
-    getCurrentEMA() {
-        return this.ema;
-    }
-    /**
-     * Resets the EMA to its initial state.
-     * The next call to get() will reinitialize the EMA.
-     */
-    reset() {
-        this.ema = null;
-    }
-}
-/**
- * Resilient Asymmetric EMA Provider with circuit breaker pattern.
- * Wraps an InnerAsymmetricEMAProvider with resilience features, providing
- * fallback to the last known EMA value when the underlying provider fails.
- *
- * @template T - The type of value this provider supplies
- */
-export class AsymmetricEMAProvider {
-    /**
-     * Creates a new AsymmetricEMAProvider with circuit breaker protection.
-     * @param provider - The underlying provider to fetch raw values from
-     * @param interpolator - The interpolator to use for blending values
-     * @param asymmetricEmaOptions - Configuration options for the asymmetric EMA calculation
-     */
-    constructor(provider, interpolator, asymmetricEmaOptions) {
-        this.provider = new InnerAsymmetricEMAProvider(provider, interpolator, asymmetricEmaOptions);
-        this.circuitBreaker = new CircuitBreaker(this.provider.get.bind(this.provider), {
-            timeout: 5000, // 5 seconds
-        }).fallback(() => {
-            const fallbackValue = this.provider.getCurrentEMA();
-            if (fallbackValue) {
-                logger.warn('Using Asymmetric EMA value as fallback for ResilientProvider');
-                return fallbackValue;
-            }
-            else {
-                logger.error('No Asymmetric EMA value available for fallback in ResilientProvider');
-                throw new Error('No Asymmetric EMA value available for fallback');
-            }
-        });
-    }
-    /**
-     * Fetches the value from the wrapped provider with resilience features.
-     * If the underlying provider fails or times out, falls back to the last known EMA value.
-     * @returns A promise that resolves to the EMA value
-     * @throws {Error} If no EMA value is available for fallback when the provider fails
-     */
-    get() {
-        return this.circuitBreaker.fire();
-    }
-}