@adcops/autocore-react 3.3.9 → 3.3.14

package/src/core/AutoCoreTagTypes.ts

@@ -1,334 +1,334 @@
-/*
- * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
- * Created Date: 2025-09-05 07:57:49
- * -----
- * Last Modified: 2026-01-29 09:31:54
- * -----
- *
- */
-
-/**
- * @module core/AutoCoreTagTypes
- *
- * Core type system for AutoCore's tag layer:
- * - Strongly-typed tag values (boolean/number/string/json)
- * - Optional **scales** for numeric unit conversion (e.g., mm ⇄ in)
- * - Optional **codecs** to present richer client-side types (Date/Map) while
- *   keeping pure JSON across the wire (serde_json::Value on the server)
- */
-
-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[];
-
-/**
- * Extended client-side value you *may* choose to present in the UI.
- * Use codecs to round-trip these as pure JSON to the server.
- */
-export type ExtendedJsonValue = JsonValue | Date | Map<string, JsonValue>;
-
-/**
- * Map a tag's declared primitive kind to the app-visible type.
- * - "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;
-
-/**
- * Runtime binding for a single tag, as returned by hooks like `useAutoCoreTag`.
- * - `value` is app-visible (already scaled/decoded)
- * - `rawValue` is the last **unscaled, un-decoded** controller value received (server JSON)
- * - `write` expects app-visible value (provider will inverse-scale/encode)
- * - `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;
-}>;
-
-/**
- * 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;
-    };
-}
-
-/**
- * A codec lets a tag expose a richer client-side type while staying JSON on the wire.
- * Common examples:
- * - Date values: ISO string ⇄ Date
- * - 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;
-};
-
-/**
- * Tag configuration descriptor used to build a typed spec.
- *
- * @typeParam K - Literal tag name (use `as const` on your spec array)
- * @typeParam T - Primitive kind for type mapping (boolean/number/string/json)
- */
-export type TagConfig<
-    K extends string = string,
-    T extends PrimitiveKind = PrimitiveKind
-> = {
-    /** 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
-> = Extract<Spec[number], { tagName: K }>;
-
-/**
- * Build a strongly-typed map of tagName → app-visible value type.
- * 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"]>;
-};
-
-/**
- * Helper: binding type for a specific tag name from a spec.
- */
-export type BindingOf<
-    Spec extends readonly TagConfig[],
-    K extends Spec[number]["tagName"]
-> = TagBinding<TagValueMap<Spec>[K]>;
-
-/**
- * Enhanced context value with scale management.
- * Providers should:
- * - Buffer **raw** values in `rawValues` (pre-scale, pre-codec)
- * - Populate `values` from `rawValues` using current scales/codecs
- * - 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>;
-}
+/*
+ * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2025-09-05 07:57:49
+ * -----
+ * Last Modified: 2026-01-29 09:31:54
+ * -----
+ *
+ */
+
+/**
+ * @module core/AutoCoreTagTypes
+ *
+ * Core type system for AutoCore's tag layer:
+ * - Strongly-typed tag values (boolean/number/string/json)
+ * - Optional **scales** for numeric unit conversion (e.g., mm ⇄ in)
+ * - Optional **codecs** to present richer client-side types (Date/Map) while
+ *   keeping pure JSON across the wire (serde_json::Value on the server)
+ */
+
+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[];
+
+/**
+ * Extended client-side value you *may* choose to present in the UI.
+ * Use codecs to round-trip these as pure JSON to the server.
+ */
+export type ExtendedJsonValue = JsonValue | Date | Map<string, JsonValue>;
+
+/**
+ * Map a tag's declared primitive kind to the app-visible type.
+ * - "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;
+
+/**
+ * Runtime binding for a single tag, as returned by hooks like `useAutoCoreTag`.
+ * - `value` is app-visible (already scaled/decoded)
+ * - `rawValue` is the last **unscaled, un-decoded** controller value received (server JSON)
+ * - `write` expects app-visible value (provider will inverse-scale/encode)
+ * - `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;
+}>;
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * A codec lets a tag expose a richer client-side type while staying JSON on the wire.
+ * Common examples:
+ * - Date values: ISO string ⇄ Date
+ * - 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;
+};
+
+/**
+ * Tag configuration descriptor used to build a typed spec.
+ *
+ * @typeParam K - Literal tag name (use `as const` on your spec array)
+ * @typeParam T - Primitive kind for type mapping (boolean/number/string/json)
+ */
+export type TagConfig<
+    K extends string = string,
+    T extends PrimitiveKind = PrimitiveKind
+> = {
+    /** 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
+> = Extract<Spec[number], { tagName: K }>;
+
+/**
+ * Build a strongly-typed map of tagName → app-visible value type.
+ * 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"]>;
+};
+
+/**
+ * Helper: binding type for a specific tag name from a spec.
+ */
+export type BindingOf<
+    Spec extends readonly TagConfig[],
+    K extends Spec[number]["tagName"]
+> = TagBinding<TagValueMap<Spec>[K]>;
+
+/**
+ * Enhanced context value with scale management.
+ * Providers should:
+ * - Buffer **raw** values in `rawValues` (pre-scale, pre-codec)
+ * - Populate `values` from `rawValues` using current scales/codecs
+ * - 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>;
+}