<?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;

}