<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Chrono\Service;

use KTXF\Chrono\Collection\ICollectionBase;
use KTXF\Chrono\Collection\ICollectionMutable;

interface IServiceCollectionMutable extends IServiceBase {

	public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
	public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
	public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
	public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';

	/**
	 * Creates a new, empty collection object
	 *
	 * @since 2025.05.01
	 *
	 * @return ICollectionMutable
	 */
	public function collectionFresh(): ICollectionMutable;

	/**
	 * Creates a new collection at the specified location
	 *
	 * @since 2025.05.01
	 *
	 * @param string $location The parent collection to create this collection in, or empty string for root
	 * @param ICollectionMutable $collection The collection to create
	 * @param array $options Additional options for the collection creation
	 *
	 * @return ICollectionBase
	 * 
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionCreate(string|int $location, ICollectionMutable $collection, array $options): ICollectionBase;

	/**
	 * Modifies an existing collection
	 *
	 * @since 2025.05.01
	 *
	 * @param string $identifier The ID of the collection to modify
	 * @param ICollectionMutable $collection The collection with modifications
	 *
	 * @return ICollectionBase
	 * 
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionModify(string|int $identifier, ICollectionMutable $collection): ICollectionBase;

	/**
	 * Destroys an existing collection
	 *
	 * @since 2025.05.01
	 *
	 * @param string $identifier The ID of the collection to destroy
	 *
	 * @return bool
	 * 
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionDestroy(string|int $identifier): bool;

}