Allow replacement of supervision control block reference, closes #79.

tExtRef/doesFcdaMeetExtRefRestrictions.spec.ts

@@ -50,7 +50,7 @@ describe("Function compare FCDA basic types to ExtRef restrictions", () => {
     const extRef = findElement(extRefXSWIPosDbPos, "ExtRef") as Element;
 
     expect(
-      doesFcdaMeetExtRefRestrictions(extRef, fcda, { controlBlockType: "SMV" })
+      doesFcdaMeetExtRefRestrictions(extRef, fcda, { controlBlockType: "SMV" }),
     ).to.be.false;
   });
 
@@ -61,7 +61,7 @@ describe("Function compare FCDA basic types to ExtRef restrictions", () => {
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "GOOSE",
-      })
+      }),
     ).to.be.false;
   });
 
@@ -72,21 +72,21 @@ describe("Function compare FCDA basic types to ExtRef restrictions", () => {
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "GOOSE",
-      })
+      }),
     ).to.be.false;
   });
 
   it("returns false with not matching cdc", () => {
     const fcda = findElement(
       publisherIED,
-      `FCDA[desc="USERENSnull"]`
+      `FCDA[desc="USERENSnull"]`,
     ) as Element;
     const extRef = findElement(extRefPos, "ExtRef") as Element;
 
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "GOOSE",
-      })
+      }),
     ).to.be.false;
   });
 
@@ -97,35 +97,35 @@ describe("Function compare FCDA basic types to ExtRef restrictions", () => {
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "GOOSE",
-      })
+      }),
     ).to.be.false;
   });
 
   it("returns false with not matching bType", () => {
     const fcda = findElement(
       publisherIED,
-      `FCDA[desc="USERENSstVal"]`
+      `FCDA[desc="USERENSstVal"]`,
     ) as Element;
     const extRef = findElement(extRefBehstVal, "ExtRef") as Element;
 
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "GOOSE",
-      })
+      }),
     ).to.be.false;
   });
 
   it("returns true for matching types CMV/FLOAT32 ", () => {
     const fcda = findElement(
       publisherIED,
-      `FCDA[desc="CMVFLOAT32"]`
+      `FCDA[desc="CMVFLOAT32"]`,
     ) as Element;
     const extRef = findElement(extRefCMVFLOAT32, "ExtRef") as Element;
 
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "Report",
-      })
+      }),
     ).to.be.true;
   });
 
@@ -136,7 +136,7 @@ describe("Function compare FCDA basic types to ExtRef restrictions", () => {
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         controlBlockType: "GOOSE",
-      })
+      }),
     ).to.be.true;
   });
 
@@ -155,7 +155,7 @@ describe("Function compare FCDA basic types to ExtRef restrictions", () => {
     expect(
       doesFcdaMeetExtRefRestrictions(extRef, fcda, {
         checkOnlyBType: true,
-      })
+      }),
     ).to.be.true;
   });
 });

tExtRef/doesFcdaMeetExtRefRestrictions.ts

@@ -20,7 +20,7 @@ export type DoesFcdaMeetExtRefRestrictionsOptions = {
 export function doesFcdaMeetExtRefRestrictions(
   extRef: Element,
   fcda: Element,
-  options: DoesFcdaMeetExtRefRestrictionsOptions = { checkOnlyBType: false }
+  options: DoesFcdaMeetExtRefRestrictionsOptions = { checkOnlyBType: false },
 ): boolean {
   // Vendor does not provide data for the check so any FCDA meets restriction
   if (!extRef.hasAttribute("pDO")) return true;

tLN/supervision/canInstantiateSubscriptionSupervision.spec.ts

@@ -506,4 +506,19 @@ describe("Function that checks whether subscription supervision can be instantia
       }),
     ).to.be.true;
   });
+
+  it("can replace a valid supervision with correct option", () => {
+    const sourceControlBlock = doc.querySelector('GSEControl[name="GOOSE3"]')!;
+    const ln1 = doc.querySelector('LN[lnClass="LGOS"][inst="1"]')!;
+
+    expect(
+      canInstantiateSubscriptionSupervision(
+        {
+          sourceControlBlock,
+          subscriberIedOrLn: ln1,
+        },
+        { allowReplacement: true },
+      ),
+    ).to.be.true;
+  });
 });

tLN/supervision/canInstantiateSubscriptionSupervision.ts

@@ -147,6 +147,9 @@ function isControlBlockSupervised(supervision: Supervision): boolean {
  * - check whether `Service` element requirements are met
  * - check whether the logical node has missing or empty `Val` content
  *   (iedOrLn is LN)
+ *
+ * CAUTION: Using options.allowReplacement and options.newSupervisionLn together
+ *          may result in unexpected behaviour.
  * ```
  * @returns Whether subscription supervision can be done */
 export function canInstantiateSubscriptionSupervision(
@@ -157,6 +160,7 @@ export function canInstantiateSubscriptionSupervision(
     checkEditableSrcRef: true,
     checkDuplicateSupervisions: true,
     checkMaxSupervisionLimits: true,
+    allowReplacement: false,
   },
 ): boolean {
   if (
@@ -170,13 +174,18 @@ export function canInstantiateSubscriptionSupervision(
       supervision.sourceControlBlock.tagName === "GSEControl"
         ? "GoCBRef"
         : "SvCBRef";
-    if (holdsValidObjRef(supervision.subscriberIedOrLn, type)) return false;
+    if (
+      !options.allowReplacement &&
+      holdsValidObjRef(supervision.subscriberIedOrLn, type)
+    )
+      return false;
   } else {
     if (!existFirstSupervisionOfType(supervision)) return false;
   }
 
   if (
     options.checkMaxSupervisionLimits &&
+    !options.allowReplacement &&
     !withinSupervisionLimits(supervision)
   )
     return false;

tLN/supervision/foundation.ts

@@ -31,6 +31,15 @@ export type SupervisionOptions = {
    * empty or invalid and can be used. Defaulting to true.
    */
   checkMaxSupervisionLimits: boolean;
+  /**
+   * Allow replacement of an existing control block reference on an LN.
+   * If checking IED properties by passing in the first supervision instance
+   * be sure to set this.
+   *
+   * CAUTION: Using options.allowReplacement and options.newSupervisionLn together
+   *          may result in unexpected behaviour.
+   */
+  allowReplacement: boolean;
 };
 
 export function type(supervision: Supervision): "GoCBRef" | "SvCBRef" {

tLN/supervision/insertSubscriptionSupervisions.spec.ts

@@ -47,7 +47,7 @@ describe("Functions that inserts supervision to subscription edits", () => {
 
   it("return empty array with unsufficient update edit", () => {
     const extRef1 = doc.querySelector(
-      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.stVal"]'
+      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.stVal"]',
     )!;
 
     const attributes1 = {};
@@ -147,7 +147,7 @@ describe("Functions that inserts supervision to subscription edits", () => {
 
   it("return array of edits for update subscription edits", () => {
     const extRef1 = doc.querySelector(
-      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.stVal"]'
+      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.stVal"]',
     )!;
 
     const attributes1 = {
@@ -166,7 +166,7 @@ describe("Functions that inserts supervision to subscription edits", () => {
     const update1 = { element: extRef1, attributes: attributes1 };
 
     const extRef2 = doc.querySelector(
-      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.q"]'
+      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.q"]',
     )!;
 
     const attributes2 = {
@@ -231,10 +231,10 @@ describe("Functions that inserts supervision to subscription edits", () => {
 
   it("return array for multiple combined update/insert edits to multiple IEDs", () => {
     const ied4e1 = doc.querySelector(
-      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.stVal"]'
+      'IED[name="GOOSE_Subscriber4"] ExtRef[intAddr="Pos.stVal"]',
     )!;
     const ied5e1 = doc.querySelector(
-      'IED[name="GOOSE_Subscriber5"] ExtRef[intAddr="Pos.stVal"]'
+      'IED[name="GOOSE_Subscriber5"] ExtRef[intAddr="Pos.stVal"]',
     )!;
     const attributes1 = {
       iedName: "Publisher",
@@ -301,26 +301,26 @@ describe("Functions that inserts supervision to subscription edits", () => {
 
     expect(edits.length).to.equal(6);
     expect(
-      (edits[0].node as Element).querySelector("Val")?.textContent
+      (edits[0].node as Element).querySelector("Val")?.textContent,
     ).to.equal("PublisherGOOSE/LLN0.GOOSE3");
     expect(
-      (edits[1].node as Element).querySelector("Val")?.textContent
+      (edits[1].node as Element).querySelector("Val")?.textContent,
     ).to.equal("PublisherGOOSE/LLN0.GOOSE3");
     expect((edits[1].node as Element).getAttribute("inst")).to.equal("2");
     expect(
-      (edits[2].node as Element).querySelector("Val")?.textContent
+      (edits[2].node as Element).querySelector("Val")?.textContent,
     ).to.equal("PublisherGOOSE/LLN0.GOOSE5");
     expect((edits[2].node as Element).getAttribute("inst")).to.equal("4");
     expect(
-      (edits[3].node as Element).querySelector("Val")?.textContent
+      (edits[3].node as Element).querySelector("Val")?.textContent,
     ).to.equal("PublisherGOOSE/LLN0.GOOSE6");
     expect((edits[3].node as Element).getAttribute("inst")).to.equal("6");
     expect(
-      (edits[4].node as Element).querySelector("Val")?.textContent
+      (edits[4].node as Element).querySelector("Val")?.textContent,
     ).to.equal("PublisherGOOSE/LLN0.GOOSE5");
     expect((edits[4].node as Element).getAttribute("inst")).to.equal("3");
     expect(
-      (edits[5].node as Element).querySelector("Val")?.textContent
+      (edits[5].node as Element).querySelector("Val")?.textContent,
     ).to.equal("PublisherGOOSE/LLN0.GOOSE6");
     expect((edits[5].node as Element).getAttribute("inst")).to.equal("6");
   });

tLN/supervision/insertSubscriptionSupervisions.ts

@@ -17,7 +17,7 @@ import { createSupervisionEdit } from "./createSupervisionEdit.js";
  * @returns A sink IED for a given ExtRef insert or `null`*/
 function findIED(
   edit: Insert,
-  previousEdits: (Insert | Update)[]
+  previousEdits: (Insert | Update)[],
 ): Element | null {
   // case 1: Input is already in the SCL and ExtRef is added to it
   const inputs = edit.parent as Element;
@@ -26,7 +26,7 @@ function findIED(
 
   // case 2: Input element is added as part of the subscription as well.
   const inputsInsertEdit = previousEdits.find(
-    (otherEdit) => isInsert(otherEdit) && otherEdit.node === edit.parent
+    (otherEdit) => isInsert(otherEdit) && otherEdit.node === edit.parent,
   ) as Insert | undefined;
   if (inputsInsertEdit)
     return (inputsInsertEdit.parent as Element).closest("IED");
@@ -36,7 +36,7 @@ function findIED(
 }
 
 function uniqueSupervisions(
-  edits: (Insert | Update)[]
+  edits: (Insert | Update)[],
 ): Record<string, Supervision> {
   const uniqueSupervisions: Record<string, Supervision> = {};
   edits.forEach((edit) => {
@@ -75,7 +75,7 @@ function uniqueSupervisions(
 
     const controlBlock = findControlBlockBySrcAttributes(
       sink!.ownerDocument,
-      source!
+      source!,
     );
     if (!controlBlock) return;
     const controlBlockReference = controlBlockObjRef(controlBlock)!;
@@ -104,7 +104,7 @@ function uniqueSupervisions(
  * @returns Edit array adding supervision on top of the subscription
  */
 export function insertSubscriptionSupervisions(
-  edits: (Update | Insert)[]
+  edits: (Update | Insert)[],
 ): Insert[] {
   /** Global as multiple subscription could be defined for different subscriber IEDs */
   const instGenerator = globalLnInstGenerator();

tLN/supervision/instantiateSubscriptionSupervision.ts

@@ -24,6 +24,7 @@ export function instantiateSubscriptionSupervision(
     checkEditableSrcRef: true,
     checkDuplicateSupervisions: true,
     checkMaxSupervisionLimits: true,
+    allowReplacement: false,
   },
 ): Insert | null {
   if (!canInstantiateSubscriptionSupervision(supervision, options)) return null;