Add Deque Interface and Corresponding Tests (#12)

- Created Deque interface extending Queue interface to define additional methods for double-ended queues.
- Added methods: addFirst, removeLast, and peekLast to the Deque interface.
- Implemented unit tests for Deque interface to ensure proper contract implementation.

Interface:
- KaririCode\Contract\DataStructure\Deque

Tests:
- KaririCode\Contract\Tests\DataStructure\DequeTest

Author: walmir-silva

src/DataStructure/Deque.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DataStructure;
+
+/**
+ * Interface Deque.
+ *
+ * Extends the Queue interface to define the contract for double-ended queue data structures,
+ * which allow elements to be added and removed from both ends.
+ *
+ * @category  Interfaces
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Deque extends Queue
+{
+    /**
+     * Adds an element to the front of the deque.
+     *
+     * @param mixed $element the element to add
+     */
+    public function addFirst(mixed $element): void;
+
+    /**
+     * Removes and returns the element at the end of the deque.
+     *
+     * @return mixed the removed element or null if the deque is empty
+     */
+    public function removeLast(): mixed;
+
+    /**
+     * Returns the element at the end of the deque without removing it.
+     *
+     * @return mixed the last element or null if the deque is empty
+     */
+    public function peekLast(): mixed;
+}

src/DataStructure/DequeTest.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\DataStructure;
+
+use KaririCode\Contract\DataStructure\Deque;
+use PHPUnit\Framework\TestCase;
+
+final class DequeTest extends TestCase
+{
+    public function testEnqueue(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->expects($this->once())->method('enqueue')->with('element');
+
+        $mock->enqueue('element');
+    }
+
+    public function testDequeue(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->method('dequeue')->willReturn('element');
+
+        $this->assertSame('element', $mock->dequeue());
+    }
+
+    public function testPeek(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->method('peek')->willReturn('element');
+
+        $this->assertSame('element', $mock->peek());
+    }
+
+    public function testAddFirst(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->expects($this->once())->method('addFirst')->with('element');
+
+        $mock->addFirst('element');
+    }
+
+    public function testRemoveLast(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->method('removeLast')->willReturn('element');
+
+        $this->assertSame('element', $mock->removeLast());
+    }
+
+    public function testPeekLast(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->method('peekLast')->willReturn('element');
+
+        $this->assertSame('element', $mock->peekLast());
+    }
+
+    public function testIsEmpty(): void
+    {
+
+        $mock = $this->createMock(Deque::class);
+        $mock->method('isEmpty')->willReturn(true);
+
+        $this->assertTrue($mock->isEmpty());
+    }
+
+    public function testSize(): void
+    {
+        $mock = $this->createMock(Deque::class);
+        $mock->method('size')->willReturn(0);
+
+        $this->assertSame(0, $mock->size());
+    }
+}