Added intersection type

Author: norberttech

documentation/components/libs/types.md

@@ -87,6 +87,7 @@ By default all types are not nullabe, in order to achieve nullability two types
 
 - `type_optional(type_string())` - results in nullable string '?string'
 - `type_union(type_string(),type_integer(),type_null())` - results in `union<string,integer,null>` which is the same as `string|integer|null`
+- `type_intersection(type_integer(),type_string())` - results in `intersection<integer,string>` which is the same as `integer&string`, requiring values to be valid for ALL types in the intersection
 
 #### Lists 
 

documentation/contributing/guidelines.md

@@ -46,15 +46,19 @@ The project is structured as follows:
     - `bridge` contains bridges to connect flow libs with other libraries and frameworks.
     - `cli` contains the command line interface application.
     - `core` contains the core functionality of the project, it holds the entire DataFrame.
-    - `lib` contains standalone libraries that can be used independently of the project, like `doctrine-dbal-bulk` and `parquet`.
+    - `lib` contains standalone libraries that can be used independently of the project, like `doctrine-dbal-bulk` and
+      `parquet`.
     - `tools` contains tools used during development.
-- `tools` contains tools used during development, like the `phpstan`, `phpunit` and others, to not pollute project autoloader and
+- `tools` contains tools used during development, like the `phpstan`, `phpunit` and others, to not pollute project
+  autoloader and
   to keep tools outside of project dependencies.
 - `var` contains temporary files, like cache and logs.
 - `vendor` contains the dependencies of the project, managed by Composer.
 - `web`
-    - `landing` contains the landing page of the project, which is a symfony application that is automatically dumped to static HTML files
-      and served by GitHub Pages. It has it's own composer.json that defines the dependencies for the landing page and commands.
+    - `landing` contains the landing page of the project, which is a symfony application that is automatically dumped to
+      static HTML files
+      and served by GitHub Pages. It has it's own composer.json that defines the dependencies for the landing page and
+      commands.
 
 ## Monorepo packages
 
@@ -91,7 +95,8 @@ as wide as possible, so we don't block other projects by our constraints.
 Packages from this monorepo can depend on each other, but ther are strict rules about that:
 
 - `lib` - libraries can depend only on other `lib` packages, never on anything else.
-- `adapter` - adapters can depend on `lib` / `bridge` and they always depend on `core`. Adpaters should not depend on `cli`
+- `adapter` - adapters can depend on `lib` / `bridge` and they always depend on `core`. Adpaters should not depend on
+  `cli`
 - `bridge` - bridges can depend only on `lib`
 - `cli` - CLI can depend on `core`, `lib` and `adapter` and `bridge`, `cli` always depends on `core`
 - `core` - core can depend on `lib` or `bridge`, but should should never depend on `adapter`, or `cli`
@@ -100,7 +105,8 @@ The above rules apply also on namespaces. So for example Adapter for `CSV` can't
 
 # PHP Versions
 
-This project supports only the latest three PHP versions, for example: 8.2, 8.3, and 8.4. (assuming that 8.4 is the latest version).
+This project supports only the latest three PHP versions, for example: 8.2, 8.3, and 8.4. (assuming that 8.4 is the
+latest version).
 Development is done using the lowest supported version, which is currently PHP 8.2.
 The project is tested against all three versions, so you can use any of them for development.
 
@@ -111,7 +117,8 @@ Most of them are available as Composer scripts, so you can run them using `compo
 
 - `composer static:analyze` runs static analysis tools like PHPStan to check the code for errors and potential issues.
 - `composer cs:php:fix` runs the PHP CS Fixer and Rector to automatically fix coding standards issues in the code.
-    - `composer test` runs all tests in the project, including unit tests, functional tests, and integration tests. It's a combination of all other test commands:
+    - `composer test` runs all tests in the project, including unit tests, functional tests, and integration tests. It's
+      a combination of all other test commands:
     - `composer test:core`
         - `composer test:cli`
         - `composer test:lib:array-dot`
@@ -120,7 +127,8 @@ Most of them are available as Composer scripts, so you can run them using `compo
         - ...
         - `composer test:adapter:xml`
         - ...
-        - `composer test:benchmark` runs the benchmark tests to measure the performance of the certain parts of the project.
+        - `composer test:benchmark` runs the benchmark tests to measure the performance of the certain parts of the
+          project.
         - `composer test:website` runs the tests for the website
         - `composer test:examples` runs all examples
         - `composer test:mutation` runs the mutation tests to check the quality of the tests.
@@ -135,3 +143,23 @@ All functions defined in DSL (usually in `functions.php` files) are following th
 snake_case is used for function names and arguments in DSL. The only other place where snake_case is used is in the
 tests, where it is used for test method names.
 
+To make sure, that the whole project is aligned with the codding standards, run following commands:
+
+```
+composer cs:php:fix
+composer static:analyze
+```
+
+Only when both commands pass, you should commit your changes.
+
+# Testing
+
+- Tests in the project are divided into
+    - `Unit` - tests a single behavior in isolation, without any dependencies.
+    - `Integration` - tests a single behavior with dependencies, like database or external services.
+- Test cases of all packages should extends `\Flow\ETL\Tests\FlowTestCase` class, the only exceptions are `lib` and
+  `bridge` packages, which can use their own test cases.
+- Each test method should test only one scenario, when one behavior needs to be tested against multiple input data, use
+  `PHPUnit\Framework\Attributes\TestWith` or `PHPUnit\Framework\Attributes\DataProvider` attributes.
+
+

src/lib/types/src/Flow/Types/DSL/functions.php

@@ -28,6 +28,7 @@
     EnumType,
     FloatType,
     IntegerType,
+    IntersectionType,
     MixedType,
     NullType,
     ObjectType,
@@ -70,6 +71,27 @@ function type_union(Type $first, Type $second, Type ...$types) : UnionType
     return $type;
 }
 
+/**
+ * @template T
+ *
+ * @param \Flow\Types\Type<T> $first
+ * @param Type<T> $second
+ * @param \Flow\Types\Type<T> ...$types
+ *
+ * @return IntersectionType<T, T>
+ */
+#[DocumentationDSL(module: Module::TYPES, type: DSLType::TYPE)]
+function type_intersection(Type $first, Type $second, Type ...$types) : IntersectionType
+{
+    $type = new IntersectionType($first, $second);
+
+    foreach ($types as $t) {
+        $type = new IntersectionType($type, $t);
+    }
+
+    return $type;
+}
+
 /**
  * @template T
  *

src/lib/types/src/Flow/Types/Type/Native/IntersectionType.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Types\Type\Native;
+
+use Flow\Types\Exception\{CastingException};
+use Flow\Types\Exception\InvalidTypeException;
+use Flow\Types\Type;
+use Flow\Types\Type\{Logical\OptionalType, TypeFactory, Types};
+
+/**
+ * @template TLeft
+ * @template TRight
+ *
+ * @implements Type<TLeft&TRight>
+ */
+final readonly class IntersectionType implements Type
+{
+    private Types $flatTypes;
+
+    /**
+     * @param Type<TLeft> $left
+     * @param Type<TRight> $right
+     */
+    public function __construct(private Type $left, private Type $right)
+    {
+        if ($left instanceof MixedType || $right instanceof MixedType) {
+            throw new InvalidTypeException('IntersectionType cannot be mixed with MixedType, mixed is a standalone type');
+        }
+
+        $types = [];
+
+        if ($this->left instanceof self) {
+            $types = [...$types, ...$this->left->types()->all()];
+        } else {
+            $types[] = $this->left;
+        }
+
+        if ($this->right instanceof self) {
+            $types = [...$types, ...$this->right->types()->all()];
+        } else {
+            $types[] = $this->right;
+        }
+
+        $this->flatTypes = \Flow\Types\DSL\types(...$types);
+    }
+
+    /**
+     * @param array{type: 'intersection', left: array, right: array} $data
+     *
+     * @return type<TLeft&TRight>
+     */
+    public static function fromArray(array $data) : Type
+    {
+        return new self(
+            TypeFactory::fromArray($data['left']),
+            TypeFactory::fromArray($data['right']),
+        );
+    }
+
+    /**
+     * @return TLeft&TRight
+     */
+    public function assert(mixed $value) : mixed
+    {
+        if (!$this->isValid($value)) {
+            throw InvalidTypeException::value($value, $this);
+        }
+
+        return $value;
+    }
+
+    public function cast(mixed $value) : mixed
+    {
+        if ($this->isValid($value)) {
+            return $value;
+        }
+
+        try {
+            $leftCasted = $this->left->cast($value);
+
+            if ($this->right->isValid($leftCasted)) {
+                return $leftCasted;
+            }
+        } catch (CastingException) {
+        }
+
+        try {
+            $rightCasted = $this->right->cast($value);
+
+            if ($this->left->isValid($rightCasted)) {
+                return $rightCasted;
+            }
+        } catch (CastingException) {
+        }
+
+        throw new CastingException($value, $this);
+    }
+
+    public function isValid(mixed $value) : bool
+    {
+        return $this->left->isValid($value) && $this->right->isValid($value);
+    }
+
+    /**
+     * @return array{type: 'intersection', left: array, right: array}
+     */
+    public function normalize() : array
+    {
+        return [
+            'type' => 'intersection',
+            'left' => $this->left->normalize(),
+            'right' => $this->right->normalize(),
+        ];
+    }
+
+    public function toString() : string
+    {
+        $stringTypes = [];
+
+        foreach ($this->flatTypes->deduplicate()->all() as $type) {
+            if ($type instanceof OptionalType) {
+                if (!\in_array($type->base()->toString(), $stringTypes, true)) {
+                    $stringTypes[] = $type->base()->toString();
+                }
+
+                if (!\in_array('null', $stringTypes, true)) {
+                    $stringTypes[] = 'null';
+                }
+
+                continue;
+            }
+
+            $stringTypes[] = $type->toString();
+        }
+
+        asort($stringTypes);
+
+        return 'intersection<' . \implode('&', $stringTypes) . '>';
+    }
+
+    public function types() : Types
+    {
+        return $this->flatTypes;
+    }
+}

src/lib/types/src/Flow/Types/Type/TypeFactory.php

@@ -27,7 +27,7 @@
 use Flow\Types\Exception\InvalidArgumentException;
 use Flow\Types\Type;
 use Flow\Types\Type\Logical\{InstanceOfType, ListType, MapType, OptionalType, StructureType};
-use Flow\Types\Type\Native\{EnumType, UnionType};
+use Flow\Types\Type\Native\{EnumType, IntersectionType, UnionType};
 
 final class TypeFactory
 {
@@ -74,6 +74,8 @@ public static function fromArray(array $data) : Type
             /** @phpstan-ignore argument.type */
             'union' => UnionType::fromArray($data),
             /** @phpstan-ignore argument.type */
+            'intersection' => IntersectionType::fromArray($data),
+            /** @phpstan-ignore argument.type */
             'optional' => OptionalType::fromArray($data),
             'scalar' => type_scalar(),
             'mixed' => type_mixed(),

src/lib/types/tests/Flow/Types/Tests/Unit/Type/Fixtures/Intersection/Date.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Types\Tests\Unit\Type\Fixtures\Intersection;
+
+interface Date
+{
+}

src/lib/types/tests/Flow/Types/Tests/Unit/Type/Fixtures/Intersection/DateOrTime.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Types\Tests\Unit\Type\Fixtures\Intersection;
+
+final class DateOrTime implements Date, Time
+{
+}

src/lib/types/tests/Flow/Types/Tests/Unit/Type/Fixtures/Intersection/Time.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Types\Tests\Unit\Type\Fixtures\Intersection;
+
+interface Time
+{
+}