@springfield/ham-radio-utils 2.0.2 → 2.2.0

package/dist/utils/ui-logger-factory.js

@@ -0,0 +1,48 @@
+import { BaseTransport } from '@loglayer/transport';
+import { LogLayer } from 'loglayer';
+import { UILogger } from './ui-logger.js';
+/**
+ * Custom LogLayer transport for capturing UI log entries.
+ */
+const UILogTransport = class extends BaseTransport {
+    #callback;
+    constructor(callback) {
+        // Pass a dummy logger to BaseTransport
+        super({ enabled: true, id: 'ui-logger-transport', logger: { log: () => { } } });
+        this.#callback = callback;
+    }
+    shipToLogger(params) {
+        const logEntry = {
+            data: params.data,
+            hasData: params.hasData,
+            level: params.logLevel,
+            message: params.messages.join(' '),
+            timestamp: new Date().toISOString(),
+        };
+        this.#callback(logEntry);
+        return [];
+    }
+};
+export const createUILogger = function createUILogger(config = {}) {
+    // By default, just print to console as JSON
+    const defaultCallback = (logEntry) => {
+        console.log(JSON.stringify(logEntry));
+    };
+    const transport = config.customTransport || new UILogTransport(defaultCallback);
+    const logger = new LogLayer({
+        consoleDebug: config.enableConsoleDebug ?? false,
+        transport,
+    });
+    logger.setLevel('debug');
+    return new UILogger(logger);
+};
+export const createUILoggerWithCallback = function createUILoggerWithCallback(callback, config = {}) {
+    const transport = new UILogTransport(callback);
+    const logger = new LogLayer({
+        consoleDebug: config.enableConsoleDebug ?? false,
+        transport,
+    });
+    logger.setLevel('debug');
+    return new UILogger(logger);
+};
+//# sourceMappingURL=ui-logger-factory.js.map

package/dist/utils/ui-logger-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger-factory.js","sourceRoot":"","sources":["../../src/utils/ui-logger-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;GAEG;AACH,MAAM,cAAc,GAAG,KAAM,SAAQ,aAAkB;IACrD,SAAS,CAA0B;IAEnC,YAAY,QAAiC;QAC3C,uCAAuC;QACvC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,qBAAqB,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/E,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,YAAY,CAAC,MAAW;QACtB,MAAM,QAAQ,GAAG;YACf,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,QAAQ;YACtB,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;YAClC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;CACF,CAAC;AAOF,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,cAAc,CAAC,SAAyB,EAAE;IAC/E,4CAA4C;IAC5C,MAAM,eAAe,GAAG,CAAC,QAAa,EAAE,EAAE;QACxC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,CAAC,eAAe,IAAI,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC,kBAAkB,IAAI,KAAK;QAChD,SAAS;KACV,CAAC,CAAC;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,0BAA0B,CAAC,QAAiC,EAAE,SAAyB,EAAE;IAC1I,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC,kBAAkB,IAAI,KAAK;QAChD,SAAS;KACV,CAAC,CAAC;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC,CAAC","sourcesContent":["import { BaseTransport } from '@loglayer/transport';\nimport { LogLayer } from 'loglayer';\nimport { UILogger } from './ui-logger.js';\n\n/**\n * Custom LogLayer transport for capturing UI log entries.\n */\nconst UILogTransport = class extends BaseTransport<any> {\n  #callback: (logEntry: any) => void;\n\n  constructor(callback: (logEntry: any) => void) {\n    // Pass a dummy logger to BaseTransport\n    super({ enabled: true, id: 'ui-logger-transport', logger: { log: () => {} } });\n    this.#callback = callback;\n  }\n\n  shipToLogger(params: any) {\n    const logEntry = {\n      data: params.data,\n      hasData: params.hasData,\n      level: params.logLevel,\n      message: params.messages.join(' '),\n      timestamp: new Date().toISOString(),\n    };\n    this.#callback(logEntry);\n    return [];\n  }\n};\n\nexport interface UILoggerConfig {\n  customTransport?: any;\n  enableConsoleDebug?: boolean;\n}\n\nexport const createUILogger = function createUILogger(config: UILoggerConfig = {}): UILogger {\n  // By default, just print to console as JSON\n  const defaultCallback = (logEntry: any) => {\n    console.log(JSON.stringify(logEntry));\n  };\n  const transport = config.customTransport || new UILogTransport(defaultCallback);\n  const logger = new LogLayer({\n    consoleDebug: config.enableConsoleDebug ?? false,\n    transport,\n  });\n  logger.setLevel('debug');\n  return new UILogger(logger);\n};\n\nexport const createUILoggerWithCallback = function createUILoggerWithCallback(callback: (logEntry: any) => void, config: UILoggerConfig = {}): UILogger {\n  const transport = new UILogTransport(callback);\n  const logger = new LogLayer({\n    consoleDebug: config.enableConsoleDebug ?? false,\n    transport,\n  });\n  logger.setLevel('debug');\n  return new UILogger(logger);\n};\n"]}

package/dist/utils/ui-logger.d.ts

@@ -0,0 +1,43 @@
+import type { ILogLayer } from 'loglayer';
+/**
+ * UI Logger: Command-Level Logging for UI Display
+ *
+ * This module provides a specialized logger for capturing command-level information
+ * that can be easily parsed and displayed in a UI. It captures details about
+ * commands, data sent, data expected, and data received in a structured format.
+ *
+ * Purpose:
+ * - Captures command-level information for UI display
+ * - Provides structured JSON logging for easy parsing
+ * - Tracks command execution details including timing
+ * - Supports protocol debugging in UI environments
+ * - Maintains separation from debug logging
+ *
+ * Design Rationale:
+ * - Single log entry per command provides clean UI display
+ * - JSON structure enables easy parsing and filtering
+ * - Command-level granularity is appropriate for UI debugging
+ * - Structured data supports rich UI representations
+ * - Separate from debug logging avoids UI noise
+ */
+/**
+ * Generic protocol step interface for UI logging
+ */
+export interface UIProtocolStep {
+    [key: string]: any;
+}
+/**
+ * UI Logger for capturing command-level information for UI display
+ */
+export declare class UILogger {
+    private logger;
+    private commandStartTimes;
+    constructor(logger: ILogLayer);
+    startCommand(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep): void;
+    logCommandSuccess(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, context: any): void;
+    logCommandFailure(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, error: Error, context: any): void;
+    private getCommandType;
+    private getStepDescription;
+    private getExpectedData;
+}
+//# sourceMappingURL=ui-logger.d.ts.map

package/dist/utils/ui-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger.d.ts","sourceRoot":"","sources":["../../src/utils/ui-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,iBAAiB,CAA6B;gBAE1C,MAAM,EAAE,SAAS;IAK7B,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAsBlG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IA6CrH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAkCnI,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,eAAe;CAiBxB"}

package/dist/utils/ui-logger.js

@@ -0,0 +1,155 @@
+/**
+ * UI Logger for capturing command-level information for UI display
+ */
+export class UILogger {
+    logger;
+    commandStartTimes = new Map();
+    constructor(logger) {
+        this.logger = logger;
+    }
+    // eslint-disable-next-line max-params
+    startCommand(stepIndex, totalSteps, operation, step) {
+        const commandId = `${operation}-${stepIndex}`;
+        const startTime = Date.now();
+        this.commandStartTimes.set(commandId, startTime);
+        const commandType = this.getCommandType(step);
+        const description = this.getStepDescription(step);
+        this.logger
+            .withMetadata({
+            commandId,
+            commandType,
+            description,
+            operation,
+            startTime,
+            stepIndex,
+            totalSteps,
+        })
+            .info('Command started');
+    }
+    // eslint-disable-next-line max-params
+    logCommandSuccess(stepIndex, totalSteps, operation, step, context) {
+        const commandId = `${operation}-${stepIndex}`;
+        const startTime = this.commandStartTimes.get(commandId) || Date.now();
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+        const commandType = this.getCommandType(step);
+        const description = this.getStepDescription(step);
+        // Extract sent and received data from context
+        const dataSent = context.variables?.get('lastSentData');
+        const dataReceived = context.variables?.get('lastReceivedData');
+        const dataExpected = this.getExpectedData(step);
+        // For readSegment, also extract chunk logs if present
+        let dataChunks = undefined;
+        if ('readSegment' === commandType) {
+            dataChunks = context.variables?.get('lastReadSegmentChunks');
+            // For readSegment, we don't need the flattened dataSent/dataReceived since we have dataChunks
+        }
+        // Convert dataSent and dataReceived to byte array format if they exist
+        const dataSentArray = dataSent ? [...dataSent] : undefined;
+        const dataReceivedArray = dataReceived ? [...dataReceived] : undefined;
+        this.logger
+            .withMetadata({
+            commandType,
+            dataChunks,
+            dataExpected,
+            dataReceived: dataReceivedArray,
+            dataSent: dataSentArray,
+            description,
+            duration,
+            endTime,
+            operation,
+            startTime,
+            stepIndex,
+            success: true,
+            totalSteps,
+        })
+            .info('Command completed successfully');
+    }
+    // eslint-disable-next-line max-params
+    logCommandFailure(stepIndex, totalSteps, operation, step, error, context) {
+        const commandId = `${operation}-${stepIndex}`;
+        const startTime = this.commandStartTimes.get(commandId) || Date.now();
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+        const commandType = this.getCommandType(step);
+        const description = this.getStepDescription(step);
+        // Extract sent data from context
+        const dataSent = context.variables?.get('lastSentData');
+        const dataExpected = this.getExpectedData(step);
+        // Convert dataSent to byte array format if it exists
+        const dataSentArray = dataSent ? [...dataSent] : undefined;
+        this.logger
+            .withMetadata({
+            commandType,
+            dataExpected,
+            dataSent: dataSentArray,
+            description,
+            duration,
+            endTime,
+            error: error.message,
+            operation,
+            startTime,
+            stepIndex,
+            success: false,
+            totalSteps,
+        })
+            .info('Command failed');
+    }
+    getCommandType(step) {
+        if ('sendReceive' in step) {
+            return 'sendReceive';
+        }
+        if ('send' in step) {
+            return 'send';
+        }
+        if ('receive' in step) {
+            return 'receive';
+        }
+        if ('readSegment' in step) {
+            return 'readSegment';
+        }
+        if ('writeSegment' in step) {
+            return 'writeSegment';
+        }
+        if ('setVariable' in step) {
+            return 'setVariable';
+        }
+        return 'unknown';
+    }
+    getStepDescription(step) {
+        if ('sendReceive' in step && step.sendReceive.description) {
+            return step.sendReceive.description;
+        }
+        if ('send' in step && step.send.description) {
+            return step.send.description;
+        }
+        if ('receive' in step && step.receive.description) {
+            return step.receive.description;
+        }
+        if ('readSegment' in step && step.readSegment.description) {
+            return step.readSegment.description;
+        }
+        if ('writeSegment' in step && step.writeSegment.description) {
+            return step.writeSegment.description;
+        }
+        return 'No description';
+    }
+    getExpectedData(step) {
+        if ('sendReceive' in step && step.sendReceive.receive) {
+            return step.sendReceive.receive;
+        }
+        if ('receive' in step) {
+            return step.receive;
+        }
+        if ('readSegment' in step) {
+            // For readSegment, return both start and end chunk receive patterns
+            return {
+                endChunk: step.readSegment.endChunk.receive,
+                startChunk: step.readSegment.startChunk.receive,
+                type: 'readSegment',
+            };
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=ui-logger.js.map

package/dist/utils/ui-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger.js","sourceRoot":"","sources":["../../src/utils/ui-logger.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ILogLayer } from 'loglayer';\n\n/**\n * UI Logger: Command-Level Logging for UI Display\n *\n * This module provides a specialized logger for capturing command-level information\n * that can be easily parsed and displayed in a UI. It captures details about\n * commands, data sent, data expected, and data received in a structured format.\n *\n * Purpose:\n * - Captures command-level information for UI display\n * - Provides structured JSON logging for easy parsing\n * - Tracks command execution details including timing\n * - Supports protocol debugging in UI environments\n * - Maintains separation from debug logging\n *\n * Design Rationale:\n * - Single log entry per command provides clean UI display\n * - JSON structure enables easy parsing and filtering\n * - Command-level granularity is appropriate for UI debugging\n * - Structured data supports rich UI representations\n * - Separate from debug logging avoids UI noise\n */\n\n/**\n * Generic protocol step interface for UI logging\n */\nexport interface UIProtocolStep {\n  [key: string]: any;\n}\n\n/**\n * UI Logger for capturing command-level information for UI display\n */\nexport class UILogger {\n  private logger: ILogLayer;\n  private commandStartTimes = new Map<string, number>();\n\n  constructor(logger: ILogLayer) {\n    this.logger = logger;\n  }\n\n  // eslint-disable-next-line max-params\n  startCommand(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep): void {\n    const commandId = `${operation}-${stepIndex}`;\n    const startTime = Date.now();\n    this.commandStartTimes.set(commandId, startTime);\n\n    const commandType = this.getCommandType(step);\n    const description = this.getStepDescription(step);\n\n    this.logger\n      .withMetadata({\n        commandId,\n        commandType,\n        description,\n        operation,\n        startTime,\n        stepIndex,\n        totalSteps,\n      })\n      .info('Command started');\n  }\n\n  // eslint-disable-next-line max-params\n  logCommandSuccess(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, context: any): void {\n    const commandId = `${operation}-${stepIndex}`;\n    const startTime = this.commandStartTimes.get(commandId) || Date.now();\n    const endTime = Date.now();\n    const duration = endTime - startTime;\n\n    const commandType = this.getCommandType(step);\n    const description = this.getStepDescription(step);\n\n    // Extract sent and received data from context\n    const dataSent = context.variables?.get('lastSentData');\n    const dataReceived = context.variables?.get('lastReceivedData');\n    const dataExpected = this.getExpectedData(step);\n\n    // For readSegment, also extract chunk logs if present\n    let dataChunks = undefined;\n    if ('readSegment' === commandType) {\n      dataChunks = context.variables?.get('lastReadSegmentChunks');\n      // For readSegment, we don't need the flattened dataSent/dataReceived since we have dataChunks\n    }\n\n    // Convert dataSent and dataReceived to byte array format if they exist\n    const dataSentArray = dataSent ? [...dataSent] : undefined;\n    const dataReceivedArray = dataReceived ? [...dataReceived] : undefined;\n\n    this.logger\n      .withMetadata({\n        commandType,\n        dataChunks,\n        dataExpected,\n        dataReceived: dataReceivedArray,\n        dataSent: dataSentArray,\n        description,\n        duration,\n        endTime,\n        operation,\n        startTime,\n        stepIndex,\n        success: true,\n        totalSteps,\n      })\n      .info('Command completed successfully');\n  }\n\n  // eslint-disable-next-line max-params\n  logCommandFailure(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, error: Error, context: any): void {\n    const commandId = `${operation}-${stepIndex}`;\n    const startTime = this.commandStartTimes.get(commandId) || Date.now();\n    const endTime = Date.now();\n    const duration = endTime - startTime;\n\n    const commandType = this.getCommandType(step);\n    const description = this.getStepDescription(step);\n\n    // Extract sent data from context\n    const dataSent = context.variables?.get('lastSentData');\n    const dataExpected = this.getExpectedData(step);\n\n    // Convert dataSent to byte array format if it exists\n    const dataSentArray = dataSent ? [...dataSent] : undefined;\n\n    this.logger\n      .withMetadata({\n        commandType,\n        dataExpected,\n        dataSent: dataSentArray,\n        description,\n        duration,\n        endTime,\n        error: error.message,\n        operation,\n        startTime,\n        stepIndex,\n        success: false,\n        totalSteps,\n      })\n      .info('Command failed');\n  }\n\n  private getCommandType(step: UIProtocolStep): string {\n    if ('sendReceive' in step) {\n      return 'sendReceive';\n    }\n    if ('send' in step) {\n      return 'send';\n    }\n    if ('receive' in step) {\n      return 'receive';\n    }\n    if ('readSegment' in step) {\n      return 'readSegment';\n    }\n    if ('writeSegment' in step) {\n      return 'writeSegment';\n    }\n    if ('setVariable' in step) {\n      return 'setVariable';\n    }\n    return 'unknown';\n  }\n\n  private getStepDescription(step: UIProtocolStep): string {\n    if ('sendReceive' in step && step.sendReceive.description) {\n      return step.sendReceive.description;\n    }\n    if ('send' in step && step.send.description) {\n      return step.send.description;\n    }\n    if ('receive' in step && step.receive.description) {\n      return step.receive.description;\n    }\n    if ('readSegment' in step && step.readSegment.description) {\n      return step.readSegment.description;\n    }\n    if ('writeSegment' in step && step.writeSegment.description) {\n      return step.writeSegment.description;\n    }\n    return 'No description';\n  }\n\n  private getExpectedData(step: UIProtocolStep): any {\n    if ('sendReceive' in step && step.sendReceive.receive) {\n      return step.sendReceive.receive;\n    }\n    if ('receive' in step) {\n      return step.receive;\n    }\n    if ('readSegment' in step) {\n      // For readSegment, return both start and end chunk receive patterns\n      return {\n        endChunk: step.readSegment.endChunk.receive,\n        startChunk: step.readSegment.startChunk.receive,\n        type: 'readSegment',\n      };\n    }\n    return undefined;\n  }\n}\n"]}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@springfield/ham-radio-utils",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "author": "Bryan Hunt",
+  "license": "MIT",
   "packageManager": "yarn@4.9.2",
   "readme": "README.md",
   "type": "module",
@@ -12,7 +13,7 @@
     "dist/"
   ],
   "scripts": {
-    "build": "tsc && cp src/db/* dist/db/",
+    "build": "tsc && cp src/db/* dist/db/ && cp src/schemas/* dist/schemas/",
     "commitlint": "commitlint --edit",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix --fix-suggestions",
@@ -50,7 +51,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@springfield/ham-radio-api": "^14.0.0",
+    "@springfield/ham-radio-api": "^16.1.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "fishery": "^2.3.1",
     "loglayer": "^6.4.3",
     "sprintf-js": "^1.1.3"
@@ -61,9 +64,11 @@
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
     "@semantic-release/gitlab": "13.2.6",
+    "@types/chai": "^5.2.2",
     "@types/sprintf-js": "1.1.4",
+    "chai": "^5.2.0",
     "husky": "9.1.7",
-    "oxlint": "1.1.0",
+    "oxlint": "1.3.0",
     "semantic-release": "23.1.1",
     "semantic-release-yarn": "3.0.2",
     "typescript": "5.8.3"

package/src/index.ts

@@ -9,4 +9,10 @@ export * from './utils/frequency-display.js';
 export * from './utils/memory-channel-utils.js';
 export * from './utils/memory-data-utils.js';
 export * from './utils/number-to-bcd.js';
+export * from './utils/schema-validator.js';
 export * from './utils/to-hex-words.js';
+export * from './utils/ui-logger.js';
+export * from './utils/ui-logger-factory.js';
+
+// Export the radio protocol schema
+export { default as radioProtocolSchema } from './schemas/radio-protocol-schema.json' with { type: 'json' };