From 625db726f603295338f065043826ca3bb04fd287 Mon Sep 17 00:00:00 2001
From: Sebastian Krupinski <krupinski01@gmail.com>
Date: Fri, 4 Sep 2026 20:59:01 -0400
Subject: [PATCH] feat: Service Node List Interface

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
---
 .../Service/ServiceNodeListInterface.php      | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 shared/lib/Documents/Service/ServiceNodeListInterface.php

diff --git a/shared/lib/Documents/Service/ServiceNodeListInterface.php b/shared/lib/Documents/Service/ServiceNodeListInterface.php
new file mode 100644
index 0000000..a32f2dc
--- /dev/null
+++ b/shared/lib/Documents/Service/ServiceNodeListInterface.php
@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Service;
+
+use Generator;
+use KTXF\Documents\Collection\CollectionBaseInterface;
+use KTXF\Documents\Entity\EntityBaseInterface;
+use KTXF\Resource\Filter\IFilter;
+use KTXF\Resource\Range\IRange;
+use KTXF\Resource\Range\RangeType;
+use KTXF\Resource\Sort\ISort;
+
+/**
+ * Service Node List Interface
+ *
+ * @since 2026.09.01
+ */
+interface ServiceNodeListInterface {
+
+    // Node capabilities
+    public const CAPABILITY_NODE_LIST = 'NodeList';
+    public const CAPABILITY_NODE_LIST_FILTER = 'NodeListFilter';
+    public const CAPABILITY_NODE_LIST_SORT = 'NodeListSort';
+    public const CAPABILITY_NODE_LIST_RANGE = 'NodeListRange';
+    // Filter capabilities
+    public const CAPABILITY_NODE_FILTER_LABEL = 'label';
+    // Sort capabilities
+    public const CAPABILITY_NODE_SORT_LABEL = 'label';
+    public const CAPABILITY_NODE_SORT_SIZE = 'size';
+    public const CAPABILITY_NODE_SORT_CREATED_ON = 'createdOn';
+    public const CAPABILITY_NODE_SORT_MODIFIED_ON = 'modifiedOn';
+    // Range capabilities
+    public const CAPABILITY_NODE_RANGE_TALLY = 'tally';
+    public const CAPABILITY_NODE_RANGE_TALLY_ABSOLUTE = 'absolute';
+    public const CAPABILITY_NODE_RANGE_TALLY_RELATIVE = 'relative';
+
+    /**
+     * Lists collections and entities within a location as one unified, ordered set
+     *
+     * Folders are always ordered before files, regardless of the sort applied within
+     * each group.
+     *
+     * @since 2026.09.01
+     *
+     * @param string|int|null $location Parent collection identifier to list within (null for root)
+     * @param IFilter|null $filter Optional filter criteria
+     * @param ISort|null $sort Optional sort order
+     * @param IRange|null $range Optional pagination
+     *
+     * @return Generator<string|int,CollectionBaseInterface|EntityBaseInterface> Nodes yielded by identifier, folders before files
+     */
+    public function nodeList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): Generator;
+
+    /**
+     * Creates a filter builder for the unified node list
+     *
+     * @since 2026.09.01
+     */
+    public function nodeListFilter(): IFilter;
+
+    /**
+     * Creates a sort builder for the unified node list
+     *
+     * @since 2026.09.01
+     */
+    public function nodeListSort(): ISort;
+
+    /**
+     * Creates a range builder for the unified node list
+     *
+     * @since 2026.09.01
+     *
+     * @param RangeType $type Range type
+     */
+    public function nodeListRange(RangeType $type): IRange;
+
+}