Add atomic circuit update commands

src/domain/errors/project-revision-conflict.error.ts

@@ -0,0 +1,14 @@
+export class ProjectRevisionConflictError extends Error {
+  constructor(
+    readonly projectId: string,
+    readonly expectedRevision: number,
+    readonly actualRevision: number | null
+  ) {
+    super(
+      actualRevision === null
+        ? `Project ${projectId} does not exist.`
+        : `Project ${projectId} is at revision ${actualRevision}, expected ${expectedRevision}.`
+    );
+    this.name = "ProjectRevisionConflictError";
+  }
+}

src/domain/models/circuit-project-command.model.ts

@@ -0,0 +1,168 @@
+import type { SerializedProjectCommand } from "./project-command.model.js";
+
+export const circuitUpdateCommandType = "circuit.update" as const;
+export const circuitUpdateCommandSchemaVersion = 1 as const;
+
+export interface CircuitUpdateValues {
+  sectionId: string;
+  equipmentIdentifier: string;
+  displayName: string | null;
+  sortOrder: number;
+  protectionType: string | null;
+  protectionRatedCurrent: number | null;
+  protectionCharacteristic: string | null;
+  cableType: string | null;
+  cableCrossSection: string | null;
+  cableLength: number | null;
+  rcdAssignment: string | null;
+  terminalDesignation: string | null;
+  voltage: number | null;
+  controlRequirement: string | null;
+  status: string | null;
+  isReserve: boolean;
+  remark: string | null;
+}
+
+export type CircuitUpdateField = keyof CircuitUpdateValues;
+export type CircuitUpdatePatch = Partial<CircuitUpdateValues>;
+
+export interface CircuitUpdateFieldChange<
+  TField extends CircuitUpdateField = CircuitUpdateField,
+> {
+  field: TField;
+  value: CircuitUpdateValues[TField];
+}
+
+export interface CircuitUpdateCommandPayload {
+  circuitId: string;
+  changes: CircuitUpdateFieldChange[];
+}
+
+export interface CircuitUpdateProjectCommand
+  extends SerializedProjectCommand<CircuitUpdateCommandPayload> {
+  schemaVersion: typeof circuitUpdateCommandSchemaVersion;
+  type: typeof circuitUpdateCommandType;
+}
+
+export function createCircuitUpdateProjectCommand(
+  circuitId: string,
+  patch: CircuitUpdatePatch
+): CircuitUpdateProjectCommand {
+  const changes = Object.entries(patch).map(([field, value]) => ({
+    field: field as CircuitUpdateField,
+    value,
+  })) as CircuitUpdateFieldChange[];
+  const command: CircuitUpdateProjectCommand = {
+    schemaVersion: circuitUpdateCommandSchemaVersion,
+    type: circuitUpdateCommandType,
+    payload: { circuitId, changes },
+  };
+  assertCircuitUpdateProjectCommand(command);
+  return command;
+}
+
+export function assertCircuitUpdateProjectCommand(
+  command: SerializedProjectCommand<unknown>
+): asserts command is CircuitUpdateProjectCommand {
+  if (
+    command.schemaVersion !== circuitUpdateCommandSchemaVersion ||
+    command.type !== circuitUpdateCommandType
+  ) {
+    throw new Error("Unsupported circuit update command.");
+  }
+  if (!isPlainObject(command.payload)) {
+    throw new Error("Circuit update payload must be an object.");
+  }
+  const circuitId = command.payload.circuitId;
+  const changes = command.payload.changes;
+  if (typeof circuitId !== "string" || !circuitId.trim()) {
+    throw new Error("Circuit update command requires a circuit id.");
+  }
+  if (!Array.isArray(changes) || changes.length === 0) {
+    throw new Error("Circuit update command requires at least one change.");
+  }
+
+  const seenFields = new Set<string>();
+  for (const change of changes) {
+    if (!isPlainObject(change) || typeof change.field !== "string") {
+      throw new Error("Circuit update command contains an invalid change.");
+    }
+    if (!isCircuitUpdateField(change.field) || seenFields.has(change.field)) {
+      throw new Error("Circuit update command contains an invalid or duplicate field.");
+    }
+    assertCircuitUpdateFieldValue(change.field, change.value);
+    seenFields.add(change.field);
+  }
+}
+
+function assertCircuitUpdateFieldValue(
+  field: CircuitUpdateField,
+  value: unknown
+) {
+  if (field === "sectionId" || field === "equipmentIdentifier") {
+    if (typeof value !== "string" || !value.trim()) {
+      throw new Error(`${field} must be a non-empty string.`);
+    }
+    return;
+  }
+  if (field === "sortOrder") {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new Error("sortOrder must be a finite number.");
+    }
+    return;
+  }
+  if (field === "isReserve") {
+    if (typeof value !== "boolean") {
+      throw new Error("isReserve must be a boolean.");
+    }
+    return;
+  }
+  if (
+    field === "protectionRatedCurrent" ||
+    field === "cableLength" ||
+    field === "voltage"
+  ) {
+    if (value === null) {
+      return;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new Error(`${field} must be a finite number or null.`);
+    }
+    if (
+      (field === "voltage" && value <= 0) ||
+      (field !== "voltage" && value < 0)
+    ) {
+      throw new Error(`${field} is outside its allowed range.`);
+    }
+    return;
+  }
+  if (value !== null && typeof value !== "string") {
+    throw new Error(`${field} must be a string or null.`);
+  }
+}
+
+function isCircuitUpdateField(value: string): value is CircuitUpdateField {
+  return [
+    "sectionId",
+    "equipmentIdentifier",
+    "displayName",
+    "sortOrder",
+    "protectionType",
+    "protectionRatedCurrent",
+    "protectionCharacteristic",
+    "cableType",
+    "cableCrossSection",
+    "cableLength",
+    "rcdAssignment",
+    "terminalDesignation",
+    "voltage",
+    "controlRequirement",
+    "status",
+    "isReserve",
+    "remark",
+  ].includes(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

src/domain/models/project-command.model.ts

@@ -6,18 +6,22 @@ export type ProjectCommandJsonValue =
   | ProjectCommandJsonValue[]
   | { [key: string]: ProjectCommandJsonValue };
 
-export interface SerializedProjectCommand {
+export interface SerializedProjectCommand<TPayload = ProjectCommandJsonValue> {
   schemaVersion: number;
   type: string;
-  payload: ProjectCommandJsonValue;
+  payload: TPayload;
 }
 
-export function serializeProjectCommand(command: SerializedProjectCommand): string {
+export function serializeProjectCommand(
+  command: SerializedProjectCommand<unknown>
+): string {
   assertSerializedProjectCommand(command);
   return JSON.stringify(command);
 }
 
-export function deserializeProjectCommand(serialized: string): SerializedProjectCommand {
+export function deserializeProjectCommand(
+  serialized: string
+): SerializedProjectCommand<ProjectCommandJsonValue> {
   const parsed: unknown = JSON.parse(serialized);
   assertSerializedProjectCommand(parsed);
   return parsed;

src/domain/ports/circuit-project-command.store.ts

@@ -0,0 +1,25 @@
+import type { CircuitUpdateProjectCommand } from "../models/circuit-project-command.model.js";
+import type {
+  AppendedProjectRevision,
+  ProjectRevisionSource,
+} from "./project-revision.store.js";
+
+export interface ExecuteCircuitUpdateCommandInput {
+  projectId: string;
+  expectedRevision: number;
+  source: ProjectRevisionSource;
+  description?: string;
+  actorId?: string;
+  command: CircuitUpdateProjectCommand;
+}
+
+export interface ExecutedCircuitUpdateCommand {
+  revision: AppendedProjectRevision;
+  inverse: CircuitUpdateProjectCommand;
+}
+
+export interface CircuitProjectCommandStore {
+  executeUpdate(
+    input: ExecuteCircuitUpdateCommandInput
+  ): ExecutedCircuitUpdateCommand;
+}

src/domain/ports/project-revision.store.ts

@@ -13,8 +13,8 @@ export interface AppendProjectRevisionInput {
   source: ProjectRevisionSource;
   description?: string;
   actorId?: string;
-  forward: SerializedProjectCommand;
-  inverse: SerializedProjectCommand;
+  forward: SerializedProjectCommand<unknown>;
+  inverse: SerializedProjectCommand<unknown>;
 }
 
 export interface AppendedProjectRevision {