@adcops/autocore-react 3.1.1 → 3.3.2

package/src/core/AutoCoreTagTypes.ts

@@ -2,7 +2,7 @@
  * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
  * Created Date: 2025-09-05 07:57:49
  * -----
- * Last Modified: 2025-09-10 10:22:18
+ * Last Modified: 2026-01-29 09:31:54
  * -----
  *
  */
@@ -22,9 +22,9 @@ export type PrimitiveKind = "boolean" | "number" | "string" | "json";
 /** Strict JSON value (mirrors serde_json::Value) */
 type JsonPrimitive = string | number | boolean | null;
 export type JsonValue =
-  | JsonPrimitive
-  | { [key: string]: JsonValue }
-  | JsonValue[];
+    | JsonPrimitive
+    | { [key: string]: JsonValue }
+    | JsonValue[];
 
 /**
  * Extended client-side value you *may* choose to present in the UI.
@@ -37,10 +37,10 @@ export type ExtendedJsonValue = JsonValue | Date | Map<string, JsonValue>;
  * - "json" becomes ExtendedJsonValue so UIs can work with Date/Map when desired.
  */
 export type TagValueOf<K extends PrimitiveKind> =
-  K extends "boolean" ? boolean :
-  K extends "number"  ? number  :
-  K extends "string"  ? string  :
-  ExtendedJsonValue;
+    K extends "boolean" ? boolean :
+    K extends "number" ? number :
+    K extends "string" ? string :
+    ExtendedJsonValue;
 
 /**
  * Runtime binding for a single tag, as returned by hooks like `useAutoCoreTag`.
@@ -50,39 +50,147 @@ export type TagValueOf<K extends PrimitiveKind> =
  * - `tap` is typically for boolean momentaries (provider may pulse true→false)
  */
 export type TagBinding<T> = Readonly<{
-  /** App-visible value (scaled/decoded). */
-  value: T | undefined;
-  /** Last raw value from the server (pre-scale, pre-codec). */
-  rawValue: unknown | undefined;
-  /** Write a new app-visible value (provider will inverse-scale/encode). */
-  write: (displayValue: T) => Promise<void>;
-  /** Momentary action; typically boolean true→false pulse. */
-  tap: () => Promise<void>;
-  /** True while initial read/bootstrapping is in progress. */
-  isLoading: boolean;
+    /** App-visible value (scaled/decoded). */
+    value: T | undefined;
+    /** Last raw value from the server (pre-scale, pre-codec). */
+    rawValue: unknown | undefined;
+    /** Write a new app-visible value (provider will inverse-scale/encode). */
+    write: (displayValue: T) => Promise<void>;
+    /** Momentary action; typically boolean true→false pulse. */
+    tap: () => Promise<void>;
+    /** True while initial read/bootstrapping is in progress. */
+    isLoading: boolean;
 }>;
 
+/**
+ * Options that control how subscription updates are delivered to the client.
+ *
+ * This implements the "hybrid" subscription model where:
+ * - **Project configuration** defines limits and defaults (e.g., minimum sampling rate)
+ * - **Client requests** can customize within those bounds
+ *
+ * ## Behavior
+ *
+ * - `undefined` values mean "use server default"
+ * - Client requests are clamped to server limits (can't request faster than hardware supports)
+ * - All filtering (deadband, on_change_only) is applied server-side before sending updates
+ *
+ * @example Basic rate limiting
+ * ```typescript
+ * {
+ *   tagName: "fastSensor",
+ *   domain: "MODBUS",
+ *   symbolName: "sensor.temperature",
+ *   valueType: "number",
+ *   subscriptionOptions: {
+ *     sampling_interval_ms: 500,  // Limit to 2 updates/sec
+ *     on_change_only: true        // Only send when value changes
+ *   }
+ * }
+ * ```
+ *
+ * @example Deadband filtering for noisy signals
+ * ```typescript
+ * {
+ *   tagName: "analogInput",
+ *   domain: "MODBUS",
+ *   symbolName: "ai.pressure",
+ *   valueType: "number",
+ *   subscriptionOptions: {
+ *     deadband_percent: 1.0  // Ignore changes < 1% of full scale
+ *   }
+ * }
+ * ```
+ */
+export interface SubscriptionOptions {
+    /**
+     * Minimum interval between updates in milliseconds.
+     *
+     * The server will not send updates faster than this rate, even if the
+     * underlying data changes more frequently. This helps prevent UI overload.
+     *
+     * - `undefined`: Use server default (typically from project configuration)
+     * - If client requests faster than hardware polling rate, gets clamped to hardware rate
+     *
+     * @example `{ sampling_interval_ms: 100 }` - Max 10 updates/second
+     */
+    sampling_interval_ms?: number;
+
+    /**
+     * Only send updates when the value changes (vs periodic heartbeat).
+     *
+     * When `true`, the server only sends updates when the value differs from
+     * the last sent value (after applying deadband filtering).
+     *
+     * When `false` or `undefined`, updates may be sent periodically even if unchanged.
+     */
+    on_change_only?: boolean;
+
+    /**
+     * Deadband as a percentage of full scale (0.0 to 100.0).
+     *
+     * Updates are suppressed unless the value changes by at least this
+     * percentage of the full scale range. This reduces network traffic
+     * for noisy signals.
+     *
+     * - `deadband_percent: 1.0` means ignore changes less than 1% of full scale
+     * - Takes precedence over `deadband_absolute` if both are set
+     *
+     * @example `{ deadband_percent: 2.5 }` - Ignore changes < 2.5% of range
+     */
+    deadband_percent?: number;
+
+    /**
+     * Deadband as an absolute value change threshold.
+     *
+     * Updates are suppressed unless the value changes by at least this
+     * absolute amount. Useful when you know the meaningful change threshold.
+     *
+     * - Only used if `deadband_percent` is not set
+     *
+     * @example `{ deadband_absolute: 5.0 }` - Ignore changes < 5 units
+     */
+    deadband_absolute?: number;
+
+    /**
+     * Queue size for buffering updates when the client is slow.
+     *
+     * If the client can't consume updates fast enough, this many updates
+     * are queued before older ones are discarded.
+     *
+     * - `undefined`: Use server default (typically 1 - latest value only)
+     * - Higher values useful for historical trending or burst handling
+     */
+    queue_size?: number;
+
+
+    /**
+     * Custom arguments specific for the specified domain.
+     */
+    args?: Record<string, unknown>;
+}
+
 /**
  * Configuration for a named scale group.
  * Apply by setting `scale: "<name>"` on numeric tags.
  */
 export interface ScaleConfig {
-  /** Unique name for this scale group (e.g., "position", "load") */
-  name: string;
-  /** Current scale factor — incoming values ×= scale; outgoing values /= scale */
-  scale: number;
-  /** Units/label for display (e.g., "mm", "in", "lbs") */
-  label: string;
-  /** Optional description for debugging/documentation */
-  description?: string;
-  /**
-   * Optional server tag that provides the scale dynamically.
-   * (If used, your provider should subscribe and update `scale` when it changes.)
-   */
-  serverTag?: {
-    domain: string;
-    symbolName: string;
-  };
+    /** Unique name for this scale group (e.g., "position", "load") */
+    name: string;
+    /** Current scale factor — incoming values ×= scale; outgoing values /= scale */
+    scale: number;
+    /** Units/label for display (e.g., "mm", "in", "lbs") */
+    label: string;
+    /** Optional description for debugging/documentation */
+    description?: string;
+    /**
+     * Optional server tag that provides the scale dynamically.
+     * (If used, your provider should subscribe and update `scale` when it changes.)
+     */
+    serverTag?: {
+        domain: string;
+        symbolName: string;
+    };
 }
 
 /**
@@ -92,10 +200,10 @@ export interface ScaleConfig {
  * - Map-like blobs: object ⇄ Map<string, JsonValue>
  */
 export type TagCodec<TIn = unknown, TOut extends JsonValue = JsonValue> = {
-  /** raw JSON (from server) → app-visible value */
-  fromServer?: (raw: unknown) => TIn;
-  /** app-visible value → pure JSON (to server) */
-  toServer?: (value: TIn) => TOut;
+    /** raw JSON (from server) → app-visible value */
+    fromServer?: (raw: unknown) => TIn;
+    /** app-visible value → pure JSON (to server) */
+    toServer?: (value: TIn) => TOut;
 };
 
 /**
@@ -105,42 +213,66 @@ export type TagCodec<TIn = unknown, TOut extends JsonValue = JsonValue> = {
  * @typeParam T - Primitive kind for type mapping (boolean/number/string/json)
  */
 export type TagConfig<
-  K extends string = string,
-  T extends PrimitiveKind = PrimitiveKind
+    K extends string = string,
+    T extends PrimitiveKind = PrimitiveKind
 > = {
-  /** Local key used by UI/consumers (unique within your spec) */
-  tagName: K;
-  /** Domain for the symbol (e.g., "ADS", "MEMORYSTORE") */
-  domain: string;
-  /** Server symbol/topic name (as used by your backend invoke API) */
-  symbolName: string;
-  /** Declared primitive kind for typing and DevPanel rendering */
-  valueType: T;
-
-  /** Optional initial **raw** value before first server update */
-  initialValue?: TagValueOf<T>;
-  /** Optional per-tag hook/config options (e.g., cycle time, debounce) */
-  options?: Record<string, unknown>;
-
-  /**
-   * Optional scale group for numeric tags.
-   * If present, provider will:
-   * - Multiply incoming numbers by the group's `scale`
-   * - Divide outgoing numbers by the group's `scale`
-   */
-  scale?: string;
-
-  /**
-   * Optional codec to present richer UI types while keeping JSON on the wire.
-   * Only commonly used with `valueType: "json"`.
-   */
-  codec?: TagCodec;
+    /** Local key used by UI/consumers (unique within your spec) */
+    tagName: K;
+
+    /** Fully-Qualified Domain Name - the complete topic path.
+     * Format: "domain.path.to.symbol" (e.g., "ads.plc1.gio.bControlPowerOk", "modbus.holding_registers.5")
+     * The first segment is the domain, used for routing to the appropriate servelet.
+     */
+    fqdn: string;
+
+    /** Declared primitive kind for typing and DevPanel rendering */
+    valueType: T;
+
+    /** Optional initial **raw** value before first server update */
+    initialValue?: TagValueOf<T>;
+    
+
+    /**
+     * Optional scale group for numeric tags.
+     * If present, provider will:
+     * - Multiply incoming numbers by the group's `scale`
+     * - Divide outgoing numbers by the group's `scale`
+     */
+    scale?: string;
+
+    /**
+     * Optional codec to present richer UI types while keeping JSON on the wire.
+     * Only commonly used with `valueType: "json"`.
+     */
+    codec?: TagCodec;
+
+    /**
+     * Optional subscription options to control how updates are delivered.
+     *
+     * These options implement the hybrid subscription model where you can
+     * configure rate limiting, deadband filtering, and other delivery options
+     * to prevent overwhelming the UI with high-frequency updates.
+     *
+     * @example Rate limit a fast-updating tag
+     * ```typescript
+     * {
+     *   tagName: "position",
+     *   subscriptionOptions: {
+     *     sampling_interval_ms: 100,  // Max 10 updates/sec
+     *     on_change_only: true
+     *   }
+     * }
+     * ```
+     *
+     * @see SubscriptionOptions for all available options
+     */
+    subscriptionOptions?: SubscriptionOptions;
 };
 
 /** Extract the tag config for a particular tag name `K` from a `Spec` */
 export type ExtractByTag<
-  Spec extends readonly TagConfig[],
-  K
+    Spec extends readonly TagConfig[],
+    K
 > = Extract<Spec[number], { tagName: K }>;
 
 /**
@@ -148,15 +280,15 @@ export type ExtractByTag<
  * Use with `as const` specs to preserve literal tag names.
  */
 export type TagValueMap<Spec extends readonly TagConfig[]> = {
-  [K in Spec[number]["tagName"]]: TagValueOf<ExtractByTag<Spec, K>["valueType"]>;
+    [K in Spec[number]["tagName"]]: TagValueOf<ExtractByTag<Spec, K>["valueType"]>;
 };
 
 /**
  * Helper: binding type for a specific tag name from a spec.
  */
 export type BindingOf<
-  Spec extends readonly TagConfig[],
-  K extends Spec[number]["tagName"]
+    Spec extends readonly TagConfig[],
+    K extends Spec[number]["tagName"]
 > = TagBinding<TagValueMap<Spec>[K]>;
 
 /**
@@ -167,36 +299,36 @@ export type BindingOf<
  * - Inverse-scale/encode on write(t) before invoking backend
  */
 export interface BaseContextValue<VMap extends Record<string, any>> {
-  /** Current app-visible tag values (already scaled/decoded). */
-  values: Partial<VMap>;
-
-  /** Last raw (controller) values, as received (pre-scale, pre-codec). */
-  rawValues: Record<string, unknown>;
-
-  /** Whether initial reads are pending. */
-  isLoading: boolean;
-
-  /**
-   * Write a single tag value (app-visible → provider will inverse-scale/encode).
-   * Strongly typed by tag name when used with a typed Context.
-   */
-  write: <K extends keyof VMap & string>(tagName: K, value: VMap[K]) => Promise<void>;
-
-  /**
-   * Trigger a momentary/toggle action for a tag.
-   * Typically used for boolean "request" bits.
-   */
-  tap: <K extends keyof VMap & string>(tagName: K) => Promise<void>;
-
-  /** Current scale configurations by name. */
-  scales: Record<string, ScaleConfig>;
-
-  /**
-   * Update a scale group (factor and label). Providers should recompute affected tags from **raw**.
-   *
-   * @param scaleName - Name of the scale group (e.g., "position")
-   * @param newScale  - New scale factor (display = raw * newScale)
-   * @param newLabel  - New units label (e.g., "inches")
-   */
-  updateScale: (scaleName: string, newScale: number, newLabel: string) => Promise<void>;
+    /** Current app-visible tag values (already scaled/decoded). */
+    values: Partial<VMap>;
+
+    /** Last raw (controller) values, as received (pre-scale, pre-codec). */
+    rawValues: Record<string, unknown>;
+
+    /** Whether initial reads are pending. */
+    isLoading: boolean;
+
+    /**
+     * Write a single tag value (app-visible → provider will inverse-scale/encode).
+     * Strongly typed by tag name when used with a typed Context.
+     */
+    write: <K extends keyof VMap & string>(tagName: K, value: VMap[K]) => Promise<void>;
+
+    /**
+     * Trigger a momentary/toggle action for a tag.
+     * Typically used for boolean "request" bits.
+     */
+    tap: <K extends keyof VMap & string>(tagName: K) => Promise<void>;
+
+    /** Current scale configurations by name. */
+    scales: Record<string, ScaleConfig>;
+
+    /**
+     * Update a scale group (factor and label). Providers should recompute affected tags from **raw**.
+     *
+     * @param scaleName - Name of the scale group (e.g., "position")
+     * @param newScale  - New scale factor (display = raw * newScale)
+     * @param newLabel  - New units label (e.g., "inches")
+     */
+    updateScale: (scaleName: string, newScale: number, newLabel: string) => Promise<void>;
 }