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

---
 psalm.xml                       |  3 +++
 src/Attribute.php               |  5 +++++
 src/Document.php                | 10 ++++++++++
 src/Document/Encoding.php       |  2 ++
 src/Document/Type.php           |  6 ++++++
 src/Document/Version.php        |  5 +++++
 src/Element.php                 | 13 +++++++++++++
 src/Element/Custom.php          |  1 +
 src/Element/Name.php            |  4 ++++
 src/Node.php                    |  7 +++++++
 src/Reader.php                  |  2 ++
 src/Translator.php              |  2 ++
 src/Visitor/NextSibling.php     |  2 ++
 src/Visitor/ParentNode.php      |  2 ++
 src/Visitor/PreviousSibling.php |  2 ++
 tests/Document/TypeTest.php     |  2 +-
 tests/Document/VersionTest.php  |  4 ++--
 17 files changed, 69 insertions(+), 3 deletions(-)

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/Attribute.php b/src/Attribute.php
index 77df4ef..abc7f40 100644
--- a/src/Attribute.php
+++ b/src/Attribute.php
@@ -26,6 +26,7 @@ private function __construct(
      *
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public static function of(string $name, string $value = ''): self
     {
         return new self(null, $name, $value);
@@ -37,6 +38,7 @@ public static function of(string $name, string $value = ''): self
      * @param non-empty-string $namespace
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public static function namespaced(
         string $namespace,
         string $name,
@@ -48,6 +50,7 @@ public static function namespaced(
     /**
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(string $name, string $value = ''): Maybe
     {
         if ($name === '') {
@@ -61,11 +64,13 @@ public static function maybe(string $name, string $value = ''): Maybe
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function name(): string
     {
         return $this->name;
     }
 
+    #[\NoDiscard]
     public function value(): string
     {
         return $this->value;
diff --git a/src/Document.php b/src/Document.php
index 9c67f1f..7b72279 100644
--- a/src/Document.php
+++ b/src/Document.php
@@ -41,6 +41,7 @@ private function __construct(
      * @param Maybe<Encoding> $encoding
      * @param Sequence<Node|Element|Custom> $children
      */
+    #[\NoDiscard]
     public static function of(
         Version $version,
         Maybe $type,
@@ -50,6 +51,7 @@ public static function of(
         return new self($version, $type, $encoding, $children ?? Sequence::of());
     }
 
+    #[\NoDiscard]
     public function version(): Version
     {
         return $this->version;
@@ -58,6 +60,7 @@ public function version(): Version
     /**
      * @return Maybe<Type>
      */
+    #[\NoDiscard]
     public function type(): Maybe
     {
         return $this->type;
@@ -66,6 +69,7 @@ public function type(): Maybe
     /**
      * @return Sequence<Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function children(): Sequence
     {
         return $this->children;
@@ -74,6 +78,7 @@ public function children(): Sequence
     /**
      * @param callable(Node|Element|Custom): bool $filter
      */
+    #[\NoDiscard]
     public function filterChild(callable $filter): self
     {
         return new self(
@@ -87,6 +92,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(
@@ -97,6 +103,7 @@ public function mapChild(callable $map): self
         );
     }
 
+    #[\NoDiscard]
     public function prependChild(Node|Element|Custom $child): self
     {
         $document = clone $this;
@@ -105,6 +112,7 @@ public function prependChild(Node|Element|Custom $child): self
         return $document;
     }
 
+    #[\NoDiscard]
     public function appendChild(Node|Element|Custom $child): self
     {
         $document = clone $this;
@@ -116,11 +124,13 @@ public function appendChild(Node|Element|Custom $child): self
     /**
      * @return Maybe<Encoding>
      */
+    #[\NoDiscard]
     public function encoding(): Maybe
     {
         return $this->encoding;
     }
 
+    #[\NoDiscard]
     public function asContent(Format $format = Format::pretty): Content
     {
         $writer = new \XMLWriter;
diff --git a/src/Document/Encoding.php b/src/Document/Encoding.php
index 7e67af0..cabb2a6 100644
--- a/src/Document/Encoding.php
+++ b/src/Document/Encoding.php
@@ -18,6 +18,7 @@ enum Encoding
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function of(string $value): Maybe
     {
         return Maybe::of(match ($value) {
@@ -30,6 +31,7 @@ public static function of(string $value): Maybe
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function toString(): string
     {
         // @see https://www.iana.org/assignments/character-sets/character-sets.xml
diff --git a/src/Document/Type.php b/src/Document/Type.php
index e684899..89c1605 100644
--- a/src/Document/Type.php
+++ b/src/Document/Type.php
@@ -28,6 +28,7 @@ private function __construct(
      *
      * @throws DomainException If the name is empty
      */
+    #[\NoDiscard]
     public static function of(
         string $name,
         string $publicId = '',
@@ -44,6 +45,7 @@ public static function of(
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(
         string $name,
         string $publicId = '',
@@ -60,21 +62,25 @@ public static function maybe(
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function name(): string
     {
         return $this->name;
     }
 
+    #[\NoDiscard]
     public function publicId(): string
     {
         return $this->publicId;
     }
 
+    #[\NoDiscard]
     public function systemId(): string
     {
         return $this->systemId;
     }
 
+    #[\NoDiscard]
     public function toString(): string
     {
         return \sprintf(
diff --git a/src/Document/Version.php b/src/Document/Version.php
index b1add98..1777a4e 100644
--- a/src/Document/Version.php
+++ b/src/Document/Version.php
@@ -29,6 +29,7 @@ private function __construct(
      *
      * @throws DomainException
      */
+    #[\NoDiscard]
     public static function of(int $major, int $minor = 0): self
     {
         return self::maybe($major, $minor)->match(
@@ -42,6 +43,7 @@ public static function of(int $major, int $minor = 0): self
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(int $major, int $minor = 0): Maybe
     {
         $major = Maybe::just($major)->filter(static fn($int) => $int >= 0);
@@ -55,6 +57,7 @@ public static function maybe(int $major, int $minor = 0): Maybe
     /**
      * @return int<0, max>
      */
+    #[\NoDiscard]
     public function major(): int
     {
         return $this->major;
@@ -63,11 +66,13 @@ public function major(): int
     /**
      * @return int<0, max>
      */
+    #[\NoDiscard]
     public function minor(): int
     {
         return $this->minor;
     }
 
+    #[\NoDiscard]
     public function toString(): string
     {
         return $this->major.'.'.$this->minor;
diff --git a/src/Element.php b/src/Element.php
index eabf3b8..49ecf45 100644
--- a/src/Element.php
+++ b/src/Element.php
@@ -38,6 +38,7 @@ private function __construct(
      * @param Sequence<Attribute>|null $attributes
      * @param Sequence<Node|self|Custom>|null $children
      */
+    #[\NoDiscard]
     public static function of(
         Name $name,
         ?Sequence $attributes = null,
@@ -61,6 +62,7 @@ public static function of(
      *
      * @param Sequence<Attribute>|null $attributes
      */
+    #[\NoDiscard]
     public static function selfClosing(
         Name $name,
         ?Sequence $attributes = null,
@@ -75,6 +77,7 @@ public static function selfClosing(
         );
     }
 
+    #[\NoDiscard]
     public function name(): Name
     {
         return $this->name;
@@ -83,6 +86,7 @@ public function name(): Name
     /**
      * @return Sequence<Attribute>
      */
+    #[\NoDiscard]
     public function attributes(): Sequence
     {
         return $this->attributes;
@@ -93,6 +97,7 @@ public function attributes(): Sequence
      *
      * @return Maybe<Attribute>
      */
+    #[\NoDiscard]
     public function attribute(string $name): Maybe
     {
         return $this->attributes->find(
@@ -103,6 +108,7 @@ public function attribute(string $name): Maybe
     /**
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public function removeAttribute(string $name): self
     {
         return new self(
@@ -115,6 +121,7 @@ public function removeAttribute(string $name): self
         );
     }
 
+    #[\NoDiscard]
     public function addAttribute(Attribute $attribute): self
     {
         return new self(
@@ -131,6 +138,7 @@ public function addAttribute(Attribute $attribute): self
     /**
      * @return Sequence<Node|self|Custom>
      */
+    #[\NoDiscard]
     public function children(): Sequence
     {
         return $this->children;
@@ -139,6 +147,7 @@ public function children(): Sequence
     /**
      * @param callable(Node|self|Custom): bool $filter
      */
+    #[\NoDiscard]
     public function filterChild(callable $filter): self
     {
         if ($this->selfClosing) {
@@ -156,6 +165,7 @@ public function filterChild(callable $filter): self
     /**
      * @param callable(Node|self|Custom): (Node|self|Custom) $map
      */
+    #[\NoDiscard]
     public function mapChild(callable $map): self
     {
         if ($this->selfClosing) {
@@ -170,6 +180,7 @@ public function mapChild(callable $map): self
         );
     }
 
+    #[\NoDiscard]
     public function prependChild(Node|self|Custom $child): self
     {
         if ($this->selfClosing) {
@@ -184,6 +195,7 @@ public function prependChild(Node|self|Custom $child): self
         );
     }
 
+    #[\NoDiscard]
     public function appendChild(Node|self|Custom $child): self
     {
         if ($this->selfClosing) {
@@ -198,6 +210,7 @@ public function appendChild(Node|self|Custom $child): self
         );
     }
 
+    #[\NoDiscard]
     public function asContent(Format $format = Format::pretty): Content
     {
         $writer = new \XMLWriter;
diff --git a/src/Element/Custom.php b/src/Element/Custom.php
index a0a5169..6f8a384 100644
--- a/src/Element/Custom.php
+++ b/src/Element/Custom.php
@@ -10,5 +10,6 @@
  */
 interface Custom
 {
+    #[\NoDiscard]
     public function normalize(): Element;
 }
diff --git a/src/Element/Name.php b/src/Element/Name.php
index 76bdba9..ae45ea6 100644
--- a/src/Element/Name.php
+++ b/src/Element/Name.php
@@ -25,6 +25,7 @@ private function __construct(
      *
      * @param non-empty-string $value
      */
+    #[\NoDiscard]
     public static function of(string $value): self
     {
         return new self(null, $value);
@@ -36,6 +37,7 @@ public static function of(string $value): self
      * @param non-empty-string $namespace
      * @param non-empty-string $value
      */
+    #[\NoDiscard]
     public static function namespaced(string $namespace, string $value): self
     {
         return new self($namespace, $value);
@@ -46,6 +48,7 @@ public static function namespaced(string $namespace, string $value): self
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(string $value): Maybe
     {
         /** @var Maybe<self> */
@@ -58,6 +61,7 @@ public static function maybe(string $value): Maybe
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function toString(): string
     {
         if ($this->namespace !== null) {
diff --git a/src/Node.php b/src/Node.php
index 4315e2d..3cda25c 100644
--- a/src/Node.php
+++ b/src/Node.php
@@ -30,6 +30,7 @@ private function __construct(
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function characterData(string $data): self
     {
         return new self(CharacterData::of($data));
@@ -38,6 +39,7 @@ public static function characterData(string $data): self
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function text(string $data): self
     {
         return new self(Text::of($data));
@@ -46,6 +48,7 @@ public static function text(string $data): self
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function comment(string $data): self
     {
         return new self(Comment::of($data));
@@ -54,6 +57,7 @@ public static function comment(string $data): self
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function entityReference(string $data): self
     {
         return new self(EntityReference::of($data));
@@ -62,16 +66,19 @@ public static function entityReference(string $data): self
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function processingInstruction(string $kind, string $value): self
     {
         return new self(ProcessingInstruction::of($kind, $value));
     }
 
+    #[\NoDiscard]
     public function content(): string
     {
         return $this->implementation->content();
     }
 
+    #[\NoDiscard]
     public function asContent(): Content
     {
         $writer = new \XMLWriter;
diff --git a/src/Reader.php b/src/Reader.php
index ff97aad..f76701a 100644
--- a/src/Reader.php
+++ b/src/Reader.php
@@ -22,6 +22,7 @@ private function __construct()
     /**
      * @return Attempt<Document|Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Content $content): Attempt
     {
         $content = $content->toString();
@@ -42,6 +43,7 @@ public function __invoke(Content $content): Attempt
         return ($this->translate)($xml);
     }
 
+    #[\NoDiscard]
     public static function of(): self
     {
         return new self();
diff --git a/src/Translator.php b/src/Translator.php
index 0bc22c8..ef3e886 100644
--- a/src/Translator.php
+++ b/src/Translator.php
@@ -33,6 +33,7 @@ private function __construct(
     /**
      * @return Attempt<Document|Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(\Dom\Node $node): Attempt
     {
         return $this
@@ -45,6 +46,7 @@ public function __invoke(\Dom\Node $node): Attempt
      *
      * @param ?pure-callable(Element): Maybe<Custom> $custom
      */
+    #[\NoDiscard]
     public static function of(?callable $custom = null): self
     {
         /** @var Maybe<Custom> */
diff --git a/src/Visitor/NextSibling.php b/src/Visitor/NextSibling.php
index d425a11..c4048cc 100644
--- a/src/Visitor/NextSibling.php
+++ b/src/Visitor/NextSibling.php
@@ -24,6 +24,7 @@ private function __construct(
     /**
      * @return Maybe<Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Document|Node|Element|Custom $tree): Maybe
     {
         return ParentNode::of($this->node)($tree)
@@ -40,6 +41,7 @@ public function __invoke(Document|Node|Element|Custom $tree): Maybe
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function of(Node|Element|Custom $node): self
     {
         return new self($node);
diff --git a/src/Visitor/ParentNode.php b/src/Visitor/ParentNode.php
index ddf7bd2..c834c70 100644
--- a/src/Visitor/ParentNode.php
+++ b/src/Visitor/ParentNode.php
@@ -24,6 +24,7 @@ private function __construct(
     /**
      * @return Maybe<Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Document|Node|Element|Custom $tree): Maybe
     {
         /** @var Maybe<Element|Custom> */
@@ -55,6 +56,7 @@ function(Maybe $parent, $child) use ($tree): Maybe {
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function of(Node|Element|Custom $node): self
     {
         return new self($node);
diff --git a/src/Visitor/PreviousSibling.php b/src/Visitor/PreviousSibling.php
index d5ba564..edc3ce4 100644
--- a/src/Visitor/PreviousSibling.php
+++ b/src/Visitor/PreviousSibling.php
@@ -29,6 +29,7 @@ private function __construct(
     /**
      * @return Maybe<Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function __invoke(Document|Node|Element|Custom $tree): Maybe
     {
         return ParentNode::of($this->node)($tree)
@@ -61,6 +62,7 @@ public function __invoke(Document|Node|Element|Custom $tree): Maybe
     /**
      * @psalm-pure
      */
+    #[\NoDiscard]
     public static function of(Node|Element|Custom $node): self
     {
         return new self($node);
diff --git a/tests/Document/TypeTest.php b/tests/Document/TypeTest.php
index 8552b02..cc809c6 100644
--- a/tests/Document/TypeTest.php
+++ b/tests/Document/TypeTest.php
@@ -27,7 +27,7 @@ public function testThrowWhenEmptyName()
     {
         $this->expectException(DomainException::class);
 
-        Type::of('');
+        $_ = Type::of('');
     }
 
     public static function cases(): array
diff --git a/tests/Document/VersionTest.php b/tests/Document/VersionTest.php
index 862c977..481ae10 100644
--- a/tests/Document/VersionTest.php
+++ b/tests/Document/VersionTest.php
@@ -26,13 +26,13 @@ public function testThrowWhenMajorTooLow()
     {
         $this->expectException(DomainException::class);
 
-        Version::of(-1);
+        $_ = Version::of(-1);
     }
 
     public function testThrowWhenMinorTooLow()
     {
         $this->expectException(DomainException::class);
 
-        Version::of(1, -1);
+        $_ = Version::of(1, -1);
     }
 }