feat: streaming entities

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-02-21 10:06:07 -05:00
parent e5eeeeb546
commit f520b8e5ac
6 changed files with 323 additions and 24 deletions
--- a/lib/Manager.php
+++ b/lib/Manager.php
@@ -763,6 +763,83 @@ class Manager {

        return $responseData;
    }
+
+    /**
+     * Stream entities
+     * 
+     * @since 2026.02.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string $userId User identifier
+     * @param SourceSelector $sources Message sources with collection identifiers
+     * @param array|null $filter Message filter
+     * @param array|null $sort Message sort
+     * @param array|null $range Message range/pagination
+     *
+     * @return \Generator<EntityBaseInterface> Yields each entity as it is retrieved
+     */
+    public function entityStream(string $tenantId, string $userId, SourceSelector $sources, array|null $filter = null, array|null $sort = null, array|null $range = null): \Generator {
+        // retrieve providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
+        // retrieve services for each provider
+        foreach ($providers as $provider) {
+            $serviceSelector = $sources[$provider->identifier()];
+            $servicesSelected = $provider->serviceList($tenantId, $userId, $serviceSelector->identifiers());
+            /** @var ServiceBaseInterface $service */
+            foreach ($servicesSelected as $service) {
+                // retrieve collections for each service
+                $collectionSelector = $serviceSelector[$service->identifier()];
+                $collectionSelected = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
+                if ($collectionSelected === []) {
+                    $collections = $service->collectionList('');
+                    $collectionSelected = array_map(
+                        fn($collection) => $collection->identifier(),
+                        $collections
+                    );
+                }
+                if ($collectionSelected === []) {
+                    continue;
+                }
+                // construct filter for entities
+                $entityFilter = null;
+                if ($filter !== null && $filter !== []) {
+                    $entityFilter = $service->entityListFilter();
+                    foreach ($filter as $attribute => $value) {
+                        $entityFilter->condition($attribute, $value);
+                    }
+                }
+                // construct sort for entities
+                $entitySort = null;
+                if ($sort !== null && $sort !== []) {
+                    $entitySort = $service->entityListSort();
+                    foreach ($sort as $attribute => $direction) {
+                        $entitySort->condition($attribute, $direction);
+                    }
+                }
+                // construct range for entities
+                $entityRange = null;
+                if ($range !== null && $range !== [] && isset($range['type'])) {
+                    $entityRange = $service->entityListRange(RangeType::from($range['type']));
+                    if ($entityRange->type() === RangeType::TALLY) {
+                        /** @var IRangeTally $entityRange */
+                        if (isset($range['anchor'])) {
+                            $entityRange->setAnchor(RangeAnchorType::from($range['anchor']));
+                        }
+                        if (isset($range['position'])) {
+                            $entityRange->setPosition($range['position']);
+                        }
+                        if (isset($range['tally'])) {
+                            $entityRange->setTally($range['tally']);
+                        }
+                    }
+                }
+                // yield entities for each collection individually
+                foreach ($collectionSelected as $collectionId) {
+                    yield from $service->entityListStream($collectionId, $entityFilter, $entitySort, $entityRange, null);
+                }
+            }
+        }
+    }
    
    /**
     * Fetch specific messages