<?php

namespace App\Komma\Kms\Core\NestedSets\Workers;

/**
 * Part of the Nested Sets package.
 *
 * NOTICE OF LICENSE
 *
 * Licensed under the Cartalyst PSL License.
 *
 * This source file is subject to the Cartalyst PSL License that is
 * bundled with this package in the license.txt file.
 *
 * @version    2.0.2
 * @author     Cartalyst LLC
 * @license    Cartalyst PSL
 * @copyright  (c) 2011-2014, Cartalyst LLC
 * @link       http://cartalyst.com
 */

use App\Komma\Kms\Core\NestedSets\Nodes\TreeModelInterface;

interface WorkerInterface
{
    /**
     * Returns all nodes, in a flat array.
     *
     * @param int $tree
     * @return array
     */
    public function allFlat($tree = null);

    /**
     * Returns all root nodes, in a flat array.
     *
     * @return array
     */
    public function allRoot();

    /**
     * Finds all leaf nodes, in a flat array.
     * Leaf nodes are nodes which do not have
     * any children.
     *
     * @param int $tree
     * @return array
     */
    public function allLeaf($tree = null);

    /**
     * Returns if the given node is a leaf node (has
     * no children).
     *
     * @param TreeModelInterface $node
     * @return bool
     */
    public function isLeaf(TreeModelInterface $node);

    /**
     * Finds the path of the given node. The path is
     * the primary key of the node and all of it's
     * parents up to the root item.
     *
     * @param TreeModelInterface $node
     * @return array
     */
    public function path(TreeModelInterface $node);

    /**
     * Returns the depth of a node in a tree, where
     * 0 is a root node, 1 is a root node's direct
     * child and so on.
     *
     * @param TreeModelInterface $node
     * @return int
     */
    public function depth(TreeModelInterface $node);

    /**
     * Returns the relative depth of a node in a tree,
     * relative to the parent provided. The parent
     * must in fact be a parent in the path of this
     * item otherwise we cannot find the relative
     * depth.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $parentNode
     * @return int
     */
    public function relativeDepth(TreeModelInterface $node, TreeModelInterface $parentNode);

    /**
     * Returns the parnet node for the given node.
     *
     * @param TreeModelInterface $node
     * @return TreeModelInterface $parent
     */
    public function parentNode(TreeModelInterface $node);

    /**
     * Returns all children for the given node in a flat
     * array. If the depth is 1 or more, that is how many
     * levels of children we recurse through to put into
     * the flat array.
     *
     * @param TreeModelInterface $node
     * @param int $depth
     * @return array
     */
    public function childrenNodes(TreeModelInterface $node, $depth = 0);

    /**
     * Returns the count of the children for the given node, with an
     * optional depth limit.
     *
     * @param TreeModelInterface $node
     * @param int $depth
     * @return int
     */
    public function childrenCount(TreeModelInterface $node, $depth = 0);

    /**
     * Returns a tree for the given node. If the depth
     * is 0, we return all children. If the depth is
     * 1 or more, that is how many levels of children
     * nodes we recurse through.
     *
     * @param TreeModelInterface $node
     * @param int $depth
     * @return array
     */
    public function tree(TreeModelInterface $node, $depth = 0);

    /**
     * Maps a tree to the database. We update each items'
     * values as well if they're provided. This can be used
     * to create a whole new tree structure or simply to re-order
     * a tree.
     *
     * @param TreeModelInterface $parent
     * @param array $nodes
     * @param bool $delete
     * @return void
     */
    public function mapTree(TreeModelInterface $parent, array $nodes, $delete = true);

    /**
     * Maps a tree to the database and keep all nodes not present in
     * the passed array. This allows for allowing pushing new items
     * into a tree without affecting the entire tree.
     *
     * @param TreeModelInterface $parent
     * @param array $nodes
     * @return void
     */
    public function mapTreeAndKeep(TreeModelInterface $parent, array $nodes);

    /**
     * Makes a new node a root node.
     *
     * @param TreeModelInterface $node
     * @return void
     */
    public function insertNodeAsRoot(TreeModelInterface $node);

    /**
     * Inserts the given node as the first child of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $parent
     * @return void
     */
    public function insertNodeAsFirstChild(TreeModelInterface $node, TreeModelInterface $parent);

    /**
     * Inserts the given node as the last child of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $parent
     * @return void
     */
    public function insertNodeAsLastChild(TreeModelInterface $node, TreeModelInterface $parent);

    /**
     * Inserts the given node as the previous sibling of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $sibling
     * @return void
     */
    public function insertNodeAsPreviousSibling(TreeModelInterface $node, TreeModelInterface $sibling);

    /**
     * Inserts the given node as the next sibling of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $sibling
     * @return void
     */
    public function insertNodeAsNextSibling(TreeModelInterface $node, TreeModelInterface $sibling);

    /**
     * Makes the given node a root node.
     *
     * @param TreeModelInterface $node
     * @return void
     */
    public function moveNodeAsRoot(TreeModelInterface $node);

    /**
     * Moves the given node as the first child of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $parent
     * @return void
     */
    public function moveNodeAsFirstChild(TreeModelInterface $node, TreeModelInterface $parent);

    /**
     * Moves the given node as the last child of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $parent
     * @return void
     */
    public function moveNodeAsLastChild(TreeModelInterface $node, TreeModelInterface $parent);

    /**
     * Moves the given node as the previous sibling of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $sibling
     * @return void
     */
    public function moveNodeAsPreviousSibling(TreeModelInterface $node, TreeModelInterface $sibling);

    /**
     * Moves the given node as the next sibling of
     * the parent node. Updates node attributes as well.
     *
     * @param TreeModelInterface $node
     * @param TreeModelInterface $sibling
     * @return void
     */
    public function moveNodeAsNextSibling(TreeModelInterface $node, TreeModelInterface $sibling);

    /**
     * Removes a node from the database and orphans
     * it's children.
     *
     * @param TreeModelInterface $node
     * @return void
     */
    public function deleteNode(TreeModelInterface $node);

    /**
     * Removes a node from the database and all of
     * it's children.
     *
     * @param TreeModelInterface $node
     * @return void
     */
    public function deleteNodeWithChildren(TreeModelInterface $node);
}