@djodjonx/x32-simulator 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djodjonx/x32-simulator",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "X32 Simulator",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/application/use-cases/SimulationService.ts

@@ -27,6 +27,10 @@ function getLocalIp(): string {
     return '127.0.0.1';
 }
 
+/**
+ * The core service that manages the X32 simulation, including networking, 
+ * state management, and OSC message handling.
+ */
 export class SimulationService {
     private subscriptionManager: SubscriptionManager;
     private messageHandler: OscMessageHandler;
@@ -43,6 +47,17 @@ export class SimulationService {
     private updateInterval: NodeJS.Timeout | null = null;
     private cleanupInterval: NodeJS.Timeout | null = null;
 
+    /**
+     * Creates a new SimulationService instance.
+     * @param gateway - The network gateway for OSC communication.
+     * @param logger - The logger service.
+     * @param stateRepo - The repository managing the mixer state.
+     * @param schemaRegistry - The registry for X32 OSC schema.
+     * @param port - UDP port to listen on (default 10023).
+     * @param ip - IP address to bind to (default '0.0.0.0').
+     * @param name - Reported console name.
+     * @param model - Reported console model.
+     */
     constructor(
         private gateway: INetworkGateway,
         private logger: ILogger,
@@ -96,6 +111,9 @@ export class SimulationService {
         this.gateway.onPacket((packet, source) => this.processPacket.execute(packet, source));
     }
 
+    /**
+     * Starts the simulator server and internal loops.
+     */
     public async start(): Promise<void> {
         await this.gateway.start(this.port, this.ip);
         
@@ -110,12 +128,18 @@ export class SimulationService {
         }, 100);
     }
 
+    /**
+     * Stops the simulator server and stops all internal loops.
+     */
     public async stop(): Promise<void> {
         if (this.updateInterval) clearInterval(this.updateInterval);
         if (this.cleanupInterval) clearInterval(this.cleanupInterval);
         await this.gateway.stop();
     }
 
+    /**
+     * Resets the mixer state to default values.
+     */
     public resetState() {
         this.stateRepo.reset();
     }

package/src/domain/entities/X32State.ts

@@ -3,7 +3,7 @@ import { X32Node } from '../models/X32Node';
 
 /**
  * Manages the internal "Digital Twin" state of the X32 console.
- * acts as a single source of truth for all parameters.
+ * It acts as a single source of truth for all parameters.
  * Emits 'change' events whenever a value is updated.
  */
 export class X32State extends EventEmitter {

package/src/domain/models/X32Address.ts

@@ -1,6 +1,5 @@
 /**
- * Represents an X32 OSC Address path.
- * parsing logic and component extraction.
+ * Represents an X32 OSC Address path, providing parsing logic and component extraction.
  */
 export class X32Address {
     private readonly _path: string;
@@ -24,11 +23,6 @@ export class X32Address {
         return this._path;
     }
 
-    /**
-     * Gets the full string representation of the path.
-        return this._path;
-    }
-
     /**
      * Gets the root category (e.g., "ch", "bus", "config").
      * @returns The first segment of the path.
@@ -75,4 +69,4 @@ export class X32Address {
         }
         return pattern.test(this._path);
     }
-}
+}

package/src/domain/models/types.ts

@@ -43,16 +43,6 @@ export interface OscMsg {
   args: OscArgumentValue[];
 }
 
-/**
- * Metadata for a single state node.
- */
-export interface X32Node {
-  /** Value type (float, int, or string). */
-  type: 'f' | 'i' | 's';
-  /** Default value for reset. */
-  default: number | string;
-}
-
 /**
  * Represents an active subscription from a client.
  */

package/src/infrastructure/repositories/InMemoryStateRepository.ts

@@ -3,17 +3,33 @@ import { X32State } from '../../domain/entities/X32State';
 import { ILogger, LogCategory } from '../../domain/ports/ILogger';
 import { SchemaRegistry } from '../../domain/services/SchemaRegistry';
 
+/**
+ * In-memory implementation of the state repository.
+ * Stores the mixer state in volatile memory during the simulator's execution.
+ */
 export class InMemoryStateRepository implements IStateRepository {
     private state: X32State;
 
+    /**
+     * Creates a new InMemoryStateRepository.
+     * @param logger - Logger service.
+     * @param schemaRegistry - Registry providing the initial state schema.
+     */
     constructor(private logger: ILogger, schemaRegistry: SchemaRegistry) {
         this.state = new X32State(schemaRegistry.getSchema());
     }
 
+    /**
+     * Returns the current mixer state instance.
+     * @returns The X32State entity.
+     */
     public getState(): X32State {
         return this.state;
     }
 
+    /**
+     * Resets the entire state to its default values.
+     */
     public reset(): void {
         this.logger.info(LogCategory.SYSTEM, 'Resetting state to defaults');
         this.state.reset();

package/src/infrastructure/services/UdpNetworkGateway.ts

@@ -4,19 +4,38 @@ import { OscPacket, RemoteClient } from '../../domain/models/types';
 import { OscCodec } from '../mappers/OscCodec';
 import { ILogger, LogCategory } from '../../domain/ports/ILogger';
 
+/**
+ * Node.js UDP implementation of the network gateway.
+ * Handles the low-level socket communication and OSC packet routing.
+ */
 export class UdpNetworkGateway implements INetworkGateway {
     private socket: dgram.Socket;
     private isRunning = false;
     private packetCallback: ((packet: OscPacket, source: RemoteClient) => void) | null = null;
 
+    /**
+     * Creates a new UdpNetworkGateway.
+     * @param logger - Logger service.
+     * @param codec - OSC codec for encoding/decoding.
+     */
     constructor(private logger: ILogger, private codec: OscCodec) {
         this.socket = dgram.createSocket('udp4');
     }
 
+    /**
+     * Registers a callback to be executed whenever a new OSC packet arrives.
+     * @param callback - Function called with decoded packet and source info.
+     */
     public onPacket(callback: (packet: OscPacket, source: RemoteClient) => void): void {
         this.packetCallback = callback;
     }
 
+    /**
+     * Starts the UDP server on the specified port and IP.
+     * @param port - UDP port.
+     * @param ip - IP address to bind to.
+     * @returns Promise resolving when the socket is bound.
+     */
     public start(port: number, ip: string): Promise<void> {
         return new Promise((resolve, reject) => {
             this.socket.on('error', (err) => {
@@ -44,6 +63,10 @@ export class UdpNetworkGateway implements INetworkGateway {
         });
     }
 
+    /**
+     * Shuts down the UDP server.
+     * @returns Promise resolving when the socket is closed.
+     */
     public stop(): Promise<void> {
         return new Promise((resolve) => {
             if (!this.isRunning) return resolve();
@@ -55,6 +78,12 @@ export class UdpNetworkGateway implements INetworkGateway {
         });
     }
 
+    /**
+     * Sends an OSC message to a specific remote client.
+     * @param target - Target client info (IP/port).
+     * @param address - OSC address pattern.
+     * @param args - Array of arguments.
+     */
     public send(target: RemoteClient, address: string, args: any[]): void {
         const buf = this.codec.encode(address, args);
         const cat = address.startsWith('/meters') ? LogCategory.METER : LogCategory.OSC_OUT;

package/src/presentation/library/library.ts

@@ -1,9 +1,139 @@
+/**
+ * @module x32-simulator
+ * @description
+ * The main entry point for the X32 Simulator library.
+ * This module exports all the necessary classes, interfaces, and types required to
+ * integrate the X32 simulator into your own Node.js applications or testing frameworks.
+ *
+ * It provides access to:
+ * - The core `SimulationService` for running the simulator.
+ * - Domain entities like `X32State` and `SubscriptionManager`.
+ * - Infrastructure components for networking and logging.
+ * - All OSC-related models and types.
+ *
+ * @example
+ * ```typescript
+ * import { SimulationService, ConsoleLogger, InMemoryStateRepository, SchemaRegistry, SchemaFactory, UdpNetworkGateway, OscCodec } from '@djodjonx/x32-simulator';
+ *
+ * // 1. Setup Dependencies
+ * const logger = ConsoleLogger.getInstance();
+ * const schemaRegistry = new SchemaRegistry(new SchemaFactory());
+ * const codec = new OscCodec(schemaRegistry);
+ * const gateway = new UdpNetworkGateway(logger, codec);
+ * const repository = new InMemoryStateRepository(logger, schemaRegistry);
+ *
+ * // 2. Initialize Service
+ * const simulator = new SimulationService(
+ *   gateway,
+ *   logger,
+ *   repository,
+ *   schemaRegistry,
+ *   10023,       // Port
+ *   '127.0.0.1'  // Host
+ * );
+ *
+ * // 3. Start
+ * await simulator.start();
+ * ```
+ */
+
+// Application layer
+/**
+ * The main service class that orchestrates the simulation logic.
+ */
 export { SimulationService } from '../../application/use-cases/SimulationService';
+
+// Domain entities
+/**
+ * Represents the complete state of the X32 console, including all parameters and faders.
+ */
+export { X32State } from '../../domain/entities/X32State';
+
+/**
+ * Manages client subscriptions to OSC updates (e.g. /xremote, /subscribe).
+ */
+export { SubscriptionManager } from '../../domain/entities/SubscriptionManager';
+
+// Domain models
+/**
+ * Represents a parsed OSC message.
+ */
+export { OscMessage } from '../../domain/models/OscMessage';
+
+/**
+ * Utility class for parsing and manipulating X32 OSC address strings.
+ */
+export { X32Address } from '../../domain/models/X32Address';
+
+/**
+ * Represents a single parameter node (fader, button, knob) in the X32 state.
+ */
+export { X32Node } from '../../domain/models/X32Node';
+
+/**
+ * Handles meter data generation and binary blob creation.
+ */
+export { MeterData } from '../../domain/models/MeterData';
+
+/**
+ * Configuration constant defining the number of meters per meter bank.
+ */
+export { METER_COUNTS } from '../../domain/models/MeterConfig';
+
+/**
+ * Exports all shared TypeScript types and interfaces used across the domain.
+ */
+export * from '../../domain/models/types';
+
+// Domain ports (interfaces)
+/**
+ * Interface for the network gateway (UDP communication).
+ */
 export type { INetworkGateway } from '../../domain/ports/INetworkGateway';
+
+/**
+ * Interface for the logger.
+ */
 export type { ILogger, LogData } from '../../domain/ports/ILogger';
+
+/**
+ * Enum for log categories.
+ */
 export { LogCategory } from '../../domain/ports/ILogger';
+
+/**
+ * Interface for the state repository (persistence/storage).
+ */
 export type { IStateRepository } from '../../domain/ports/IStateRepository';
+
+// Infrastructure layer
+/**
+ * In-memory implementation of the state repository.
+ */
 export { InMemoryStateRepository } from '../../infrastructure/repositories/InMemoryStateRepository';
+
+/**
+ * Console-based implementation of the logger.
+ */
 export { ConsoleLogger } from '../../infrastructure/services/ConsoleLogger';
+
+/**
+ * Node.js UDP implementation of the network gateway.
+ */
 export { UdpNetworkGateway } from '../../infrastructure/services/UdpNetworkGateway';
-export * from '../../domain/models/types';
+
+/**
+ * OSC Codec for encoding and decoding X32-specific OSC packets.
+ */
+export { OscCodec } from '../../infrastructure/mappers/OscCodec';
+
+// Domain services
+/**
+ * Factory service for creating the initial X32 state schema.
+ */
+export { SchemaFactory } from '../../domain/services/SchemaFactory';
+
+/**
+ * Registry service for looking up X32 nodes and definitions.
+ */
+export { SchemaRegistry } from '../../domain/services/SchemaRegistry';