Added helper methods on Schema/Definition to manipulate metadata

Author: norberttech

src/adapter/etl-adapter-parquet/src/Flow/ETL/Adapter/Parquet/RowsNormalizer.php

@@ -30,7 +30,7 @@ public function normalize(Rows $rows, Schema $schema) : array
                 $columns[$entry->name()] = match ($entry::class) {
                     UuidEntry::class => $this->caster->to(type_string())->value($entry->value()),
                     XMLEntry::class => $this->caster->to(type_string())->value($entry->value()),
-                    default => $this->caster->to($schema->getDefinition($entry->ref())->type())->value($entry->value()),
+                    default => $this->caster->to($schema->get($entry->ref())->type())->value($entry->value()),
                 };
             }
 

src/core/etl/src/Flow/ETL/Row/EntryFactory.php

@@ -73,7 +73,7 @@ public function create(string $entryName, mixed $value, Schema|Definition|null $
         }
 
         if ($schema instanceof Schema) {
-            $definition = $schema->getDefinition($entryName);
+            $definition = $schema->get($entryName);
 
             return $this->createAs($definition->entry()->name(), $value, $definition->type(), $definition->metadata());
         }

src/core/etl/src/Flow/ETL/Row/Schema.php

@@ -93,6 +93,18 @@ public function add(Definition ...$definitions) : self
         return $this;
     }
 
+    /**
+     * Adds metadata to a given definition.
+     *
+     * @throws SchemaDefinitionNotFoundException
+     */
+    public function addMetadata(string $definition, string $name, int|string|bool|float|array $value) : self
+    {
+        $this->get($definition)->addMetadata($name, $value);
+
+        return $this;
+    }
+
     public function count() : int
     {
         return \count($this->definitions);
@@ -136,11 +148,21 @@ public function findDefinition(string|Reference $ref) : ?Definition
     /**
      * @throws SchemaDefinitionNotFoundException
      */
-    public function getDefinition(string|Reference $ref) : Definition
+    public function get(string|Reference $ref) : Definition
     {
         return $this->findDefinition($ref) ?: throw new SchemaDefinitionNotFoundException((string) $ref);
     }
 
+    /**
+     * @deprecated please use Schema::get() instead
+     *
+     * @throw SchemaDefinitionNotFoundException
+     */
+    public function getDefinition(string|Reference $ref) : Definition
+    {
+        return $this->get($ref);
+    }
+
     /**
      * Gracefully remove entries from schema without throwing an exception if entry does not exist.
      */
@@ -335,6 +357,18 @@ public function replace(string|Reference $entry, Definition $definition) : self
         return $this;
     }
 
+    /**
+     * Overwrites metadata for a given definition.
+     *
+     * @throws SchemaDefinitionNotFoundException
+     */
+    public function setMetadata(string $definition, Metadata $metadata) : self
+    {
+        $this->get($definition)->setMetadata($metadata);
+
+        return $this;
+    }
+
     private function setDefinitions(Definition ...$definitions) : void
     {
         $uniqueDefinitions = [];

src/core/etl/src/Flow/ETL/Row/Schema/Definition.php

@@ -22,18 +22,18 @@
 use Flow\ETL\PHP\Type\{Native\FloatType, Native\IntegerType, Native\StringType, Type, TypeFactory};
 use Flow\ETL\Row\{Entry, EntryReference, Reference};
 
-final readonly class Definition
+final class Definition
 {
     private Metadata $metadata;
 
-    private Reference $ref;
+    private readonly Reference $ref;
 
     /**
      * @param Type<mixed> $type
      */
     public function __construct(
         string|Reference $ref,
-        private Type $type,
+        private readonly Type $type,
         ?Metadata $metadata = null,
     ) {
 
@@ -160,6 +160,13 @@ public static function xml_element(string|Reference $entry, bool $nullable = fal
         return new self($entry, type_xml_element($nullable), $metadata);
     }
 
+    public function addMetadata(string $key, int|string|bool|float|array $value) : self
+    {
+        $this->metadata = $this->metadata->add($key, $value);
+
+        return $this;
+    }
+
     public function entry() : Reference
     {
         return $this->ref;
@@ -329,6 +336,13 @@ public function rename(string $newName) : self
         );
     }
 
+    public function setMetadata(Metadata $metadata) : self
+    {
+        $this->metadata = $metadata;
+
+        return $this;
+    }
+
     /**
      * @return Type<mixed>
      */

src/core/etl/src/Flow/ETL/Row/Schema/SelectiveValidator.php

@@ -16,7 +16,7 @@ final class SelectiveValidator implements SchemaValidator
     public function isValid(Rows $rows, Schema $schema) : bool
     {
         foreach ($schema->references() as $ref) {
-            $definition = $schema->getDefinition($ref);
+            $definition = $schema->get($ref);
 
             foreach ($rows as $row) {
                 try {

src/core/etl/tests/Flow/ETL/Tests/Unit/Row/Schema/DefinitionTest.php

@@ -263,6 +263,17 @@ public function test_not_matches_when_type_name_not_match() : void
         self::assertFalse($def->matches(int_entry('not-test', 1)));
     }
 
+    public function test_set_metadata() : void
+    {
+        $definition = integer_schema('id', metadata: Metadata::fromArray(['test' => 'test']));
+
+        self::assertEquals(
+            integer_schema('id', false, Metadata::fromArray(['description' => 'some_random_description'])),
+            $definition->setMetadata(Metadata::fromArray(['description' => 'some_random_description']))
+        );
+
+    }
+
     public function test_structure_definition_metadata() : void
     {
         $address = struct_entry(

src/core/etl/tests/Flow/ETL/Tests/Unit/Row/SchemaTest.php

@@ -25,11 +25,25 @@
     uuid_schema};
 use function Flow\ETL\DSL\{integer_schema, string_schema};
 use Flow\ETL\Exception\{InvalidArgumentException, SchemaDefinitionNotFoundException, SchemaDefinitionNotUniqueException};
+use Flow\ETL\Row\Schema\Metadata;
 use Flow\ETL\Row\{EntryReference, Schema};
 use Flow\ETL\Tests\FlowTestCase;
 
 final class SchemaTest extends FlowTestCase
 {
+    public function test_add_metadata() : void
+    {
+        $schema = schema(
+            int_schema('id'),
+            str_schema('name'),
+        );
+
+        self::assertEquals(
+            int_schema('id', metadata: Metadata::fromArray(['test' => 'test'])),
+            $schema->addMetadata('id', 'test', 'test')->get('id')
+        );
+    }
+
     public function test_adding_duplicated_definitions() : void
     {
         $this->expectException(SchemaDefinitionNotUniqueException::class);
@@ -96,6 +110,19 @@ public function test_creating_schema_from_invalid_json_format_at_definition_leve
         schema_from_json('[{"ref": "id", "type": "test", "metadata": []}]');
     }
 
+    public function test_get() : void
+    {
+        $schema = schema(
+            int_schema('id'),
+            str_schema('name'),
+        );
+
+        self::assertEquals(
+            int_schema('id'),
+            $schema->get('id')
+        );
+    }
+
     public function test_graceful_remove_non_existing_definition() : void
     {
 
@@ -385,4 +412,17 @@ public function test_schema_to_from_json() : void
             schema_from_json(schema_to_json($schema))
         );
     }
+
+    public function test_set_metadata() : void
+    {
+        $schema = schema(
+            int_schema('id', metadata: Metadata::fromArray(['foo' => 'bar'])),
+            str_schema('name'),
+        );
+
+        self::assertEquals(
+            int_schema('id', metadata: Metadata::fromArray(['test' => 'test'])),
+            $schema->setMetadata('id', Metadata::fromArray(['test' => 'test']))->get('id')
+        );
+    }
 }