Fix types and add docs

Author: GromNaN

psalm-baseline.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.20.0@3f284e96c9d9be6fe6b15c79416e1d1903dcfef4">
+<files psalm-version="5.21.1@8c473e2437be8b6a8fd8f630f0f11a16b114c494">
   <file src="src/Builder/Encoder/AbstractExpressionEncoder.php">
     <MixedAssignment>
       <code>$val</code>
@@ -113,6 +113,14 @@
       <code>stdClass</code>
     </TooManyTemplateParams>
   </file>
+  <file src="src/Builder/Stage/SortStage.php">
+    <PropertyTypeCoercion>
+      <code>$sort</code>
+    </PropertyTypeCoercion>
+    <TooManyTemplateParams>
+      <code>stdClass</code>
+    </TooManyTemplateParams>
+  </file>
   <file src="src/Builder/Type/OutputWindow.php">
     <DocblockTypeContradiction>
       <code><![CDATA[! is_string($documents[1]) && ! is_int($documents[1])]]></code>

src/Builder/BuilderEncoder.php

@@ -15,7 +15,7 @@
 use MongoDB\Builder\Encoder\VariableEncoder;
 use MongoDB\Builder\Expression\Variable;
 use MongoDB\Builder\Type\CombinedFieldQuery;
-use MongoDB\Builder\Type\Dictionnary;
+use MongoDB\Builder\Type\DictionaryInterface;
 use MongoDB\Builder\Type\ExpressionInterface;
 use MongoDB\Builder\Type\FieldPathInterface;
 use MongoDB\Builder\Type\OperatorInterface;
@@ -31,17 +31,17 @@
 use function array_key_exists;
 use function is_object;
 
-/** @template-implements Encoder<stdClass|array|string, Pipeline|StageInterface|ExpressionInterface|QueryInterface> */
+/** @template-implements Encoder<stdClass|array|string|int, Pipeline|StageInterface|ExpressionInterface|QueryInterface> */
 class BuilderEncoder implements Encoder
 {
-    /** @template-use EncodeIfSupported<stdClass|array|string, Pipeline|StageInterface|ExpressionInterface|QueryInterface> */
+    /** @template-use EncodeIfSupported<stdClass|array|string|int, Pipeline|StageInterface|ExpressionInterface|QueryInterface> */
     use EncodeIfSupported;
 
     /** @var array<class-string, class-string<ExpressionEncoder>> */
     private array $defaultEncoders = [
         Pipeline::class => PipelineEncoder::class,
         Variable::class => VariableEncoder::class,
-        Dictionnary::class => DictionaryEncoder::class,
+        DictionaryInterface::class => DictionaryEncoder::class,
         FieldPathInterface::class => FieldPathEncoder::class,
         CombinedFieldQuery::class => CombinedFieldQueryEncoder::class,
         QueryObject::class => QueryEncoder::class,

src/Builder/Encoder/DictionaryEncoder.php

@@ -4,20 +4,20 @@
 
 namespace MongoDB\Builder\Encoder;
 
-use MongoDB\Builder\Type\Dictionnary;
+use MongoDB\Builder\Type\DictionaryInterface;
 use MongoDB\Codec\EncodeIfSupported;
 use MongoDB\Exception\UnsupportedValueException;
 use stdClass;
 
-/** @template-extends AbstractExpressionEncoder<string, Dictionnary> */
+/** @template-extends AbstractExpressionEncoder<string|int|array|stdClass, DictionaryInterface> */
 class DictionaryEncoder extends AbstractExpressionEncoder
 {
-    /** @template-use EncodeIfSupported<string, Dictionnary> */
+    /** @template-use EncodeIfSupported<string|int|array|stdClass, DictionaryInterface> */
     use EncodeIfSupported;
 
     public function canEncode(mixed $value): bool
     {
-        return $value instanceof Dictionnary;
+        return $value instanceof DictionaryInterface;
     }
 
     public function encode(mixed $value): string|int|array|stdClass

src/Builder/Type/Dictionnary.php renamed to src/Builder/Type/DictionaryInterface.php

@@ -4,7 +4,7 @@
 
 namespace MongoDB\Builder\Type;
 
-interface Dictionnary
+interface DictionaryInterface
 {
     public function getValue(): string|int|array;
 }

src/Builder/Type/Sort.php

@@ -4,7 +4,12 @@
 
 namespace MongoDB\Builder\Type;
 
-enum Sort implements Dictionnary
+/**
+ * Sort order can be used with $sort stage and sortBy properties
+ *
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/
+ */
+enum Sort implements DictionaryInterface
 {
     case Asc;
     case Desc;

src/Builder/Type/TimeUnit.php

@@ -4,7 +4,10 @@
 
 namespace MongoDB\Builder\Type;
 
-enum TimeUnit: string implements Dictionnary
+/**
+ * Values for "unit" property of stages like $derivative and $integral, and operators like $dateAdd and $dateDiff
+ */
+enum TimeUnit: string implements DictionaryInterface
 {
     case Year = 'year';
     case Quarter = 'quarter';