Merge pull request 'refactor: list and fetch' (#95) from refactor/list-and-fetch into main

Reviewed-on: #95

shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php

@@ -28,6 +28,8 @@ use KTXF\Resource\Provider\ResourceServiceLocationInterface;
  */
 interface ProviderServiceDiscoverInterface {
 
+    public const CAPABILITY_SERVICE_DISCOVER = 'ServiceDiscover';    
+    
     /**
      * Attempts to discover service configuration using provider-specific methods.
      * 

shared/lib/Mail/Provider/ProviderServiceTestInterface.php

@@ -28,6 +28,8 @@ use KTXF\Mail\Service\ServiceMutableInterface;
  */
 interface ProviderServiceTestInterface {
 
+    public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
+
     /**
      * Test a service connection
      * 

shared/lib/Mail/Service/ServiceBaseInterface.php

@@ -14,6 +14,7 @@ use KTXF\Mail\Collection\CollectionBaseInterface;
 use KTXF\Mail\Object\AddressInterface;
 use KTXF\Resource\Delta\Delta;
 use KTXF\Resource\Filter\IFilter;
+use KTXF\Resource\Identifier\EntityIdentifierInterface;
 use KTXF\Resource\Provider\ResourceServiceBaseInterface;
 use KTXF\Resource\Range\IRange;
 use KTXF\Resource\Range\RangeType;
@@ -166,9 +167,9 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      * @param IRange|null $range Optional pagination
      * @param array|null $properties Optional message properties to fetch
      *
-     * @return array<string|int,EntityBaseInterface> Messages indexed by ID
+     * @return array<string,EntityBaseInterface> Messages indexed by Urn
      */
-    public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
+    public function entityListBulk(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
 
     /**
      * Lists messages in a collection
@@ -244,11 +245,21 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      *
      * @since 2025.05.01
      *
-     * @param string|int $collection Collection ID
+     * @param EntityIdentifierInterface ...$identifiers Message identifiers to fetch
-     * @param string|int ...$identifiers Message IDs to fetch
      *
-     * @return array<string|int,EntityBaseInterface> Messages indexed by ID
+     * @return array<string,EntityBaseInterface> Messages indexed by Urn
      */
-    public function entityFetch(string|int $collection, string|int ...$identifiers): array;
+    public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array;
+
+        /**
+     * Fetches one or more entities
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface ...$identifiers Message identifiers to fetch
+     *
+     * @return Generator<string,EntityBaseInterface> Yields messages one by one
+     */
+    public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator;
 
 }

shared/lib/Resource/Provider/Node/NodeBaseAbstract.php

@@ -71,6 +71,13 @@ abstract class NodeBaseAbstract implements NodeBaseInterface {
         return $this->data[static::PROPERTY_TYPE];
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function urn(): string {
+        return (string) $this->nodeIdentifier();
+    }
+
     /**
      * @inheritDoc
      */

shared/lib/Resource/Provider/Node/NodeBaseInterface.php

@@ -36,6 +36,13 @@ interface NodeBaseInterface extends JsonSerializable {
      */
     public function type(): string;
 
+    /**
+     * Node URN
+     *
+     * @since 2025.05.01
+     */
+    public function urn(): string;
+    
     /**
      * Provider identifier
      *

shared/lib/Resource/Provider/ResourceProviderBaseInterface.php

@@ -14,11 +14,6 @@ interface ResourceProviderBaseInterface extends ProviderInterface, JsonSerializa
 	public const CAPABILITY_SERVICE_LIST = 'ServiceList';
 	public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
 	public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
-	public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
-	public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
-	public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
-	public const CAPABILITY_SERVICE_DISCOVER = 'ServiceDiscover';
-	public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
 
 	public const JSON_TYPE = 'resource.provider';
 	public const JSON_PROPERTY_TYPE = '@type';

shared/lib/Resource/Provider/ResourceProviderServiceMutateInterface.php

@@ -13,6 +13,10 @@ use KTXF\Json\JsonDeserializable;
 
 interface ResourceProviderServiceMutateInterface extends JsonDeserializable {
 	
+	public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
+	public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
+	public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
+
 	/**
 	 * construct and new blank service instance
 	 *