From 6476200541f8068120277a3371228bb680ab0f21 Mon Sep 17 00:00:00 2001
From: Baptiste Langlade <baptiste.langlade@hey.com>
Date: Sun, 25 Jan 2026 18:56:49 +0100
Subject: [PATCH] add NoDiscard attributes

---
 psalm.xml                | 3 +++
 src/Document.php         | 9 +++++++++
 src/Element/A.php        | 3 +++
 src/Element/Base.php     | 3 +++
 src/Element/Img.php      | 3 +++
 src/Element/Link.php     | 4 ++++
 src/Element/Script.php   | 2 ++
 src/Reader.php           | 2 ++
 src/Translator.php       | 2 ++
 src/Visitor/Element.php  | 4 ++++
 src/Visitor/Elements.php | 2 ++
 11 files changed, 37 insertions(+)

diff --git a/psalm.xml b/psalm.xml
index 510148d..feccc34 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -14,4 +14,7 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
+    <issueHandlers>
+        <UndefinedAttributeClass errorLevel="suppress" />
+    </issueHandlers>
 </psalm>
diff --git a/src/Document.php b/src/Document.php
index 6a1dce4..066669e 100644
--- a/src/Document.php
+++ b/src/Document.php
@@ -36,11 +36,13 @@ private function __construct(
      *
      * @param Sequence<Node|Element|Custom>|null $children
      */
+    #[\NoDiscard]
     public static function of(Type $type, ?Sequence $children = null): self
     {
         return new self($type, $children ?? Sequence::of());
     }
 
+    #[\NoDiscard]
     public function type(): Type
     {
         return $this->type;
@@ -49,11 +51,13 @@ public function type(): Type
     /**
      * @return Sequence<Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function children(): Sequence
     {
         return $this->children;
     }
 
+    #[\NoDiscard]
     public function hasChildren(): bool
     {
         return !$this->children->empty();
@@ -62,6 +66,7 @@ public function hasChildren(): bool
     /**
      * @param callable(Node|Element|Custom): bool $filter
      */
+    #[\NoDiscard]
     public function filterChild(callable $filter): self
     {
         return new self(
@@ -73,6 +78,7 @@ public function filterChild(callable $filter): self
     /**
      * @param callable(Node|Element|Custom): (Node|Element|Custom) $map
      */
+    #[\NoDiscard]
     public function mapChild(callable $map): self
     {
         return new self(
@@ -81,6 +87,7 @@ public function mapChild(callable $map): self
         );
     }
 
+    #[\NoDiscard]
     public function prependChild(Node|Element|Custom $child): self
     {
         return new self(
@@ -89,6 +96,7 @@ public function prependChild(Node|Element|Custom $child): self
         );
     }
 
+    #[\NoDiscard]
     public function appendChild(Node|Element|Custom $child): self
     {
         return new self(
@@ -97,6 +105,7 @@ public function appendChild(Node|Element|Custom $child): self
         );
     }
 
+    #[\NoDiscard]
     public function asContent(Format $format = Format::pretty): Content
     {
         /** @var Maybe<XMLDocument\Encoding> */
diff --git a/src/Element/A.php b/src/Element/A.php
index 8dc374b..832bf2e 100644
--- a/src/Element/A.php
+++ b/src/Element/A.php
@@ -30,6 +30,7 @@ private function __construct(
      * @param Sequence<Attribute>|null $attributes
      * @param Sequence<Node|Element|Custom>|null $children
      */
+    #[\NoDiscard]
     public static function of(
         Url $href,
         ?Sequence $attributes = null,
@@ -45,12 +46,14 @@ public static function of(
         );
     }
 
+    #[\NoDiscard]
     public function href(): Url
     {
         return $this->href;
     }
 
     #[\Override]
+    #[\NoDiscard]
     public function normalize(): Element
     {
         return $this->element->addAttribute(
diff --git a/src/Element/Base.php b/src/Element/Base.php
index 2e96406..68c47a4 100644
--- a/src/Element/Base.php
+++ b/src/Element/Base.php
@@ -28,6 +28,7 @@ private function __construct(
      *
      * @param Sequence<Attribute>|null $attributes
      */
+    #[\NoDiscard]
     public static function of(Url $href, ?Sequence $attributes = null): self
     {
         return new self($href, Element::selfClosing(
@@ -36,12 +37,14 @@ public static function of(Url $href, ?Sequence $attributes = null): self
         ));
     }
 
+    #[\NoDiscard]
     public function href(): Url
     {
         return $this->href;
     }
 
     #[\Override]
+    #[\NoDiscard]
     public function normalize(): Element
     {
         return $this->element->addAttribute(
diff --git a/src/Element/Img.php b/src/Element/Img.php
index 0fd08ef..5cd1801 100644
--- a/src/Element/Img.php
+++ b/src/Element/Img.php
@@ -28,6 +28,7 @@ private function __construct(
      *
      * @param Sequence<Attribute>|null $attributes
      */
+    #[\NoDiscard]
     public static function of(Url $src, ?Sequence $attributes = null): self
     {
         return new self($src, Element::selfClosing(
@@ -36,12 +37,14 @@ public static function of(Url $src, ?Sequence $attributes = null): self
         ));
     }
 
+    #[\NoDiscard]
     public function src(): Url
     {
         return $this->src;
     }
 
     #[\Override]
+    #[\NoDiscard]
     public function normalize(): Element
     {
         return $this->element->addAttribute(
diff --git a/src/Element/Link.php b/src/Element/Link.php
index 2d10097..1af0a67 100644
--- a/src/Element/Link.php
+++ b/src/Element/Link.php
@@ -33,6 +33,7 @@ private function __construct(
      * @param non-empty-string $relationship
      * @param Sequence<Attribute>|null $attributes
      */
+    #[\NoDiscard]
     public static function of(
         Url $href,
         string $relationship,
@@ -48,6 +49,7 @@ public static function of(
         );
     }
 
+    #[\NoDiscard]
     public function href(): Url
     {
         return $this->href;
@@ -56,12 +58,14 @@ public function href(): Url
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function relationship(): string
     {
         return $this->relationship;
     }
 
     #[\Override]
+    #[\NoDiscard]
     public function normalize(): Element
     {
         return $this
diff --git a/src/Element/Script.php b/src/Element/Script.php
index 05f3dcf..e6e1b49 100644
--- a/src/Element/Script.php
+++ b/src/Element/Script.php
@@ -26,6 +26,7 @@ private function __construct(private Element $element)
      *
      * @param Sequence<Attribute>|null $attributes
      */
+    #[\NoDiscard]
     public static function of(Node $text, ?Sequence $attributes = null): self
     {
         return new self(Element::of(
@@ -36,6 +37,7 @@ public static function of(Node $text, ?Sequence $attributes = null): self
     }
 
     #[\Override]
+    #[\NoDiscard]
     public function normalize(): Element
     {
         return $this->element;
diff --git a/src/Reader.php b/src/Reader.php
index 35a2b5e..5a7e59c 100644
--- a/src/Reader.php
+++ b/src/Reader.php
@@ -23,6 +23,7 @@ private function __construct(private Translator $translate)
     /**
      * @return Attempt<Document|Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Content $html): Attempt
     {
         $content = $html->toString();
@@ -41,6 +42,7 @@ public function __invoke(Content $html): Attempt
         }
     }
 
+    #[\NoDiscard]
     public static function new(): self
     {
         return new self(
diff --git a/src/Translator.php b/src/Translator.php
index 425a624..4597e5f 100644
--- a/src/Translator.php
+++ b/src/Translator.php
@@ -39,6 +39,7 @@ private function __construct(
     /**
      * @return Attempt<Document|Element|Custom|Node>
      */
+    #[\NoDiscard]
     public function __invoke(\Dom\Node $node): Attempt
     {
         return $this
@@ -49,6 +50,7 @@ public function __invoke(\Dom\Node $node): Attempt
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function new(): self
     {
         return new self(XmlTranslator::of(
diff --git a/src/Visitor/Element.php b/src/Visitor/Element.php
index 8af36dd..d1b0a0a 100644
--- a/src/Visitor/Element.php
+++ b/src/Visitor/Element.php
@@ -30,6 +30,7 @@ private function __construct(private string $name)
     /**
      * @return Maybe<Model|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Document|Node|Model|Custom $node): Maybe
     {
         return match (true) {
@@ -45,6 +46,7 @@ public function __invoke(Document|Node|Model|Custom $node): Maybe
      *
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public static function of(string $name): self
     {
         return new self($name);
@@ -53,6 +55,7 @@ public static function of(string $name): self
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function head(): self
     {
         return new self('head');
@@ -61,6 +64,7 @@ public static function head(): self
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function body(): self
     {
         return new self('body');
diff --git a/src/Visitor/Elements.php b/src/Visitor/Elements.php
index fa7e659..a9e71ea 100644
--- a/src/Visitor/Elements.php
+++ b/src/Visitor/Elements.php
@@ -26,6 +26,7 @@ private function __construct(private string $name)
     /**
      * @return Sequence<Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Document|Node|Element|Custom $node): Sequence
     {
         return match (true) {
@@ -41,6 +42,7 @@ public function __invoke(Document|Node|Element|Custom $node): Sequence
      *
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public static function of(string $name): self
     {
         return new self($name);