ocpp-ws-io 1.0.0-alpha

package/src/errors.ts

@@ -0,0 +1,183 @@
+// ─── Base Errors ─────────────────────────────────────────────────
+
+export class TimeoutError extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
+export class UnexpectedHttpResponse extends Error {
+  public readonly statusCode: number;
+  public readonly headers: Record<string, string | string[] | undefined>;
+
+  constructor(
+    message: string,
+    statusCode: number,
+    headers: Record<string, string | string[] | undefined> = {},
+  ) {
+    super(message);
+    this.name = "UnexpectedHttpResponse";
+    this.statusCode = statusCode;
+    this.headers = headers;
+  }
+}
+
+export class WebsocketUpgradeError extends Error {
+  constructor(message = "WebSocket upgrade failed") {
+    super(message);
+    this.name = "WebsocketUpgradeError";
+  }
+}
+
+// ─── RPC Error Base ──────────────────────────────────────────────
+
+export interface RPCError extends Error {
+  readonly rpcErrorCode: string;
+  readonly rpcErrorMessage: string;
+  readonly details: Record<string, unknown>;
+}
+
+export class RPCGenericError extends Error implements RPCError {
+  readonly rpcErrorCode: string = "GenericError";
+  readonly rpcErrorMessage: string = "";
+  readonly details: Record<string, unknown>;
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "RPCGenericError";
+    this.details = details;
+  }
+}
+
+// ─── Specific RPC Errors ─────────────────────────────────────────
+
+export class RPCNotImplementedError extends RPCGenericError {
+  override readonly rpcErrorCode = "NotImplemented";
+  override readonly rpcErrorMessage = "Requested method is not known";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCNotImplementedError";
+  }
+}
+
+export class RPCNotSupportedError extends RPCGenericError {
+  override readonly rpcErrorCode = "NotSupported";
+  override readonly rpcErrorMessage =
+    "Requested method is recognised but not supported";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCNotSupportedError";
+  }
+}
+
+export class RPCInternalError extends RPCGenericError {
+  override readonly rpcErrorCode = "InternalError";
+  override readonly rpcErrorMessage =
+    "An internal error occurred and the receiver was not able to process the requested action successfully";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCInternalError";
+  }
+}
+
+export class RPCProtocolError extends RPCGenericError {
+  override readonly rpcErrorCode = "ProtocolError";
+  override readonly rpcErrorMessage = "Payload for action is incomplete";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCProtocolError";
+  }
+}
+
+export class RPCSecurityError extends RPCGenericError {
+  override readonly rpcErrorCode = "SecurityError";
+  override readonly rpcErrorMessage =
+    "During the processing of action a security issue occurred preventing receiver from completing the action successfully";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCSecurityError";
+  }
+}
+
+export class RPCFormationViolationError extends RPCGenericError {
+  override readonly rpcErrorCode = "FormationViolation";
+  override readonly rpcErrorMessage =
+    "Payload for action is syntactically incorrect or not conform the PDU structure for action";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCFormationViolationError";
+  }
+}
+
+export class RPCFormatViolationError extends RPCGenericError {
+  override readonly rpcErrorCode = "FormatViolation";
+  override readonly rpcErrorMessage =
+    "Payload is syntactically correct but at least one field contains an invalid value";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCFormatViolationError";
+  }
+}
+
+export class RPCPropertyConstraintViolationError extends RPCGenericError {
+  override readonly rpcErrorCode = "PropertyConstraintViolation";
+  override readonly rpcErrorMessage =
+    "Payload is syntactically correct but at least one of the fields violates data type constraints";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCPropertyConstraintViolationError";
+  }
+}
+
+export class RPCOccurrenceConstraintViolationError extends RPCGenericError {
+  override readonly rpcErrorCode = "OccurrenceConstraintViolation";
+  override readonly rpcErrorMessage =
+    "Payload for action is syntactically correct but at least one of the fields violates occurrence constraints";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCOccurrenceConstraintViolationError";
+  }
+}
+
+export class RPCTypeConstraintViolationError extends RPCGenericError {
+  override readonly rpcErrorCode = "TypeConstraintViolation";
+  override readonly rpcErrorMessage =
+    "Payload for action is syntactically correct but at least one of the fields violates type constraints";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCTypeConstraintViolationError";
+  }
+}
+
+export class RPCMessageTypeNotSupportedError extends RPCGenericError {
+  override readonly rpcErrorCode = "MessageTypeNotSupported";
+  override readonly rpcErrorMessage =
+    "A message with a Message Type Number received that is not supported by this implementation";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCMessageTypeNotSupportedError";
+  }
+}
+
+export class RPCFrameworkError extends RPCGenericError {
+  override readonly rpcErrorCode = "RpcFrameworkError";
+  override readonly rpcErrorMessage =
+    "Content of the call is not a valid RPC request";
+
+  constructor(message?: string, details: Record<string, unknown> = {}) {
+    super(message, details);
+    this.name = "RPCFrameworkError";
+  }
+}

package/src/event-buffer.ts

@@ -0,0 +1,73 @@
+import { EventEmitter } from "node:events";
+
+/**
+ * An event buffer that captures events emitted during a critical transition period
+ * (e.g., during WebSocket connection setup) and replays them in order once the
+ * consumer is ready.
+ */
+export class EventBuffer {
+  private _target: EventEmitter;
+  private _events: string[];
+  private _buffer: Array<{ event: string; args: unknown[] }> = [];
+  private _listeners: Map<string, (...args: unknown[]) => void> = new Map();
+  private _active = false;
+
+  constructor(target: EventEmitter, events: string[]) {
+    this._target = target;
+    this._events = events;
+  }
+
+  /**
+   * Start buffering events. Any matching events emitted on the target
+   * will be captured instead of being processed immediately.
+   */
+  start(): void {
+    if (this._active) return;
+    this._active = true;
+
+    for (const event of this._events) {
+      const listener = (...args: unknown[]) => {
+        this._buffer.push({ event, args });
+      };
+      this._listeners.set(event, listener);
+      this._target.on(event, listener);
+    }
+  }
+
+  /**
+   * Stop buffering and replay all captured events on the target
+   * in the order they were received.
+   */
+  condense(): void {
+    if (!this._active) return;
+    this._active = false;
+
+    // Remove buffer listeners
+    for (const [event, listener] of this._listeners) {
+      this._target.removeListener(event, listener);
+    }
+    this._listeners.clear();
+
+    // Replay buffered events
+    const events = this._buffer.slice();
+    this._buffer = [];
+
+    for (const { event, args } of events) {
+      this._target.emit(event, ...args);
+    }
+  }
+
+  /**
+   * Stop buffering and discard all captured events.
+   */
+  discard(): void {
+    if (!this._active) return;
+    this._active = false;
+
+    for (const [event, listener] of this._listeners) {
+      this._target.removeListener(event, listener);
+    }
+    this._listeners.clear();
+    this._buffer = [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+// ─── Core ────────────────────────────────────────────────────────
+export { OCPPClient } from "./client.js";
+export { OCPPServer } from "./server.js";
+export { OCPPServerClient } from "./server-client.js";
+
+// ─── Validation ──────────────────────────────────────────────────
+export { Validator, createValidator } from "./validator.js";
+export { standardValidators } from "./standard-validators.js";
+
+// ─── Utilities ───────────────────────────────────────────────────
+export {
+  createRPCError,
+  getErrorPlainObject,
+  getPackageIdent,
+} from "./util.js";
+
+// ─── Adapters ────────────────────────────────────────────────────
+export { InMemoryAdapter } from "./adapters/adapter.js";
+
+// ─── Errors ──────────────────────────────────────────────────────
+export {
+  TimeoutError,
+  UnexpectedHttpResponse,
+  WebsocketUpgradeError,
+  type RPCError,
+  RPCGenericError,
+  RPCNotImplementedError,
+  RPCNotSupportedError,
+  RPCInternalError,
+  RPCProtocolError,
+  RPCSecurityError,
+  RPCFormationViolationError,
+  RPCFormatViolationError,
+  RPCPropertyConstraintViolationError,
+  RPCOccurrenceConstraintViolationError,
+  RPCTypeConstraintViolationError,
+  RPCMessageTypeNotSupportedError,
+  RPCFrameworkError,
+} from "./errors.js";
+
+// ─── Types ───────────────────────────────────────────────────────
+export {
+  ConnectionState,
+  SecurityProfile,
+  MessageType,
+  NOREPLY,
+  type OCPPProtocol,
+  type OCPPCall,
+  type OCPPCallResult,
+  type OCPPCallError,
+  type OCPPMessage,
+  type TLSOptions,
+  type HandlerContext,
+  type CallHandler,
+  type WildcardHandler,
+  type CallOptions,
+  type CloseOptions,
+  type HandshakeInfo,
+  type SessionData,
+  type ClientOptions,
+  type ServerOptions,
+  type ListenOptions,
+  type AuthAccept,
+  type AuthCallback,
+  type ClientEvents,
+  type ServerEvents,
+  type EventAdapterInterface,
+} from "./types.js";

package/src/queue.ts

@@ -0,0 +1,65 @@
+/**
+ * A concurrency-limited async queue.
+ * Enqueues async functions and executes them with a configurable concurrency limit.
+ */
+export class Queue {
+  private _concurrency: number;
+  private _running = 0;
+  private _queue: Array<{
+    fn: () => Promise<unknown>;
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+  }> = [];
+
+  constructor(concurrency = 1) {
+    this._concurrency = Math.max(1, concurrency);
+  }
+
+  get concurrency(): number {
+    return this._concurrency;
+  }
+
+  get pending(): number {
+    return this._queue.length;
+  }
+
+  get running(): number {
+    return this._running;
+  }
+
+  get size(): number {
+    return this._running + this._queue.length;
+  }
+
+  setConcurrency(concurrency: number): void {
+    this._concurrency = Math.max(1, concurrency);
+    this._drain();
+  }
+
+  push<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this._queue.push({
+        fn: fn as () => Promise<unknown>,
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      });
+      this._drain();
+    });
+  }
+
+  private _drain(): void {
+    while (this._running < this._concurrency && this._queue.length > 0) {
+      const item = this._queue.shift()!;
+      this._running++;
+
+      item
+        .fn()
+        .then(item.resolve)
+        .catch(item.reject)
+        .finally(() => {
+          this._running--;
+          this._drain();
+        });
+    }
+  }
+}