Merge pull request 'refactor: entity move and delete' (#77) from refactor/entity-move-and-delete into main

Reviewed-on: #77

shared/lib/Mail/Service/ServiceEntityMutableInterface.php

@@ -11,6 +11,8 @@ namespace KTXF\Mail\Service;
 
 use KTXF\Mail\Entity\EntityBaseInterface;
 use KTXF\Mail\Entity\EntityMutableInterface;
+use KTXF\Resource\Identifier\CollectionIdentifier;
+use KTXF\Resource\Identifier\EntityIdentifier;
 
 /**
  * Mail Service Entity Mutable Interface
@@ -70,7 +72,11 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface {
      *
      * @param EntityIdentifier ...$identifiers Source entities to delete
      *
-     * @return array<string|int,bool|string> Results keyed by entity identifier (true on success, error string on failure)
+     * @return array<string, array{
+     *     disposition: 'moved'|'deleted'|'error',
+     *     destination: ?CollectionIdentifier,
+     *     mutation: EntityIdentifier
+     * }> Results keyed by source entity identifier
      */
     public function entityDelete(EntityIdentifier ...$identifiers): array;
 
@@ -82,7 +88,11 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface {
      * @param CollectionIdentifier $target Target collection identifier
      * @param EntityIdentifier ...$identifiers Source entities to copy
      *
-     * @return array<string|int,bool> List of copied entity identifiers
+     * @return array<string, array{
+     *     disposition: 'copied'|'error',
+     *     destination: ?CollectionIdentifier,
+     *     mutation: EntityIdentifier
+     * }> Results keyed by source entity identifier
      */
     public function entityCopy(CollectionIdentifier $target, EntityIdentifier ...$identifiers): array;
 
@@ -94,7 +104,11 @@ interface ServiceEntityMutableInterface extends ServiceBaseInterface {
      * @param CollectionIdentifier $target Target collection identifier
      * @param EntityIdentifier ...$identifiers Source entities to move
      *
-     * @return array<string|int,bool> List of moved entity identifiers
+     * @return array<string, array{
+     *     disposition: 'moved'|'error',
+     *     destination: ?CollectionIdentifier,
+     *     mutation: EntityIdentifier
+     * }> Results keyed by source entity identifier
      */
     public function entityMove(CollectionIdentifier $target, EntityIdentifier ...$identifiers): array;
 

shared/lib/Resource/Identifier/ResourceIdentifier.php

@@ -35,6 +35,10 @@ class ResourceIdentifier implements ResourceIdentifierInterface {
 		return $this->provider;
 	}
 
+	public function jsonSerialize(): string {
+		return (string) $this;
+	}
+
 	/**
 	 * Parse a colon-separated identifier string and return the appropriate level class
 	 * 

shared/lib/Resource/Identifier/ResourceIdentifierInterface.php

@@ -9,10 +9,12 @@ declare(strict_types=1);
 
 namespace KTXF\Resource\Identifier;
 
+use KTXF\Json\JsonSerializable;
+
 /**
  * Top-level identifier for resources (provider level)
  */
-interface ResourceIdentifierInterface extends \Stringable {
+interface ResourceIdentifierInterface extends JsonSerializable, \Stringable {
 
 	/** The provider segment (e.g. "imap") */
 	public function provider(): string;
@@ -23,4 +25,7 @@ interface ResourceIdentifierInterface extends \Stringable {
 	/** Canonical string form: provider[:service[:collection[:entity]]] */
 	public function __toString(): string;
 
+	/** Canonical JSON form: provider[:service[:collection[:entity]]] */
+	public function jsonSerialize(): string;
+
 }

shared/lib/Resource/Identifier/ResourceIdentifiers.php

@@ -151,4 +151,11 @@ class ResourceIdentifiers implements ResourceIdentifiersInterface {
 		return count($this->identifiers) === 0;
 	}
 
+	public function jsonSerialize(): array {
+		return array_map(
+			static fn (ResourceIdentifierInterface $identifier): string => $identifier->jsonSerialize(),
+			$this->identifiers,
+		);
+	}
+
 }

shared/lib/Resource/Identifier/ResourceIdentifiersInterface.php

@@ -9,10 +9,12 @@ declare(strict_types=1);
 
 namespace KTXF\Resource\Identifier;
 
+use KTXF\Json\JsonSerializable;
+
 /**
  * A typed collection of resource identifiers with search and filter capabilities
  */
-interface ResourceIdentifiersInterface extends \Countable, \IteratorAggregate {
+interface ResourceIdentifiersInterface extends JsonSerializable, \Countable, \IteratorAggregate {
 
 	/** Add an identifier to the collection */
 	public function add(ResourceIdentifierInterface $identifier): void;
@@ -47,4 +49,7 @@ interface ResourceIdentifiersInterface extends \Countable, \IteratorAggregate {
 	/** Get unique entity names */
 	public function entities(): array;
 
+	/** Serialize as an array of canonical identifier strings */
+	public function jsonSerialize(): array;
+
 }