Wrap data with Task before passing to TasksResults

[norkunas]

Pull Request

Related issue

Part of #842

What does this PR do?

• Wraps tasks arrays with Task before passing to TasksResults

Migration guide

TasksResults Constructor

use Meilisearch\Contracts\Task;
use Meilisearch\Contracts\TasksResults;

// Before: Passing raw response data directly
$response = [
    'results' => [
        ['uid' => 1, 'status' => 'succeeded'],
        ['uid' => 2, 'status' => 'processing'],
    ],
    // other parameters
];
$tasksResults = new TasksResults($response);

// After: Data must be mapped to Task objects first
$response = [
    'results' => [
        Task::fromArray(['uid' => 1, 'status' => 'succeeded']),
        Task::fromArray(['uid' => 2, 'status' => 'processing']),
    ],
    // ...
];

$tasksResults = new TasksResults($response);

Tasks::all() Return Value

$tasks = $client->tasks->all();

// Before: $tasks['results'] was an array of arrays
// After: $tasks['results'] is now an array of Meilisearch\Contracts\Task objects

PR checklist

Please check if your PR fulfills the following requirements:

• Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
• Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
• Have you read the contributing guidelines?
• Have you made sure that the title is accurate and descriptive of the changes?

Summary by CodeRabbit

• Breaking Changes

  • Removed the public count() method from task-results.
  • Task-results payload now requires limit and total fields.
  • Exported task-results array shape and field order updated; "next" behavior clarified.

• Improvements

  • Task result entries are now typed Task objects instead of raw arrays.
  • Task-fetching and option handling streamlined for clearer, more readable behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

TasksResults is now final; its constructor requires mapped Task objects and mandates limit/total. Endpoints (Tasks, Indexes) convert HTTP response results arrays into Task instances. A null-safe inline call replaced a manual options check in HandlesTasks.

Changes

Cohort / File(s)	Summary
Contracts — TasksResults src/Contracts/TasksResults.php	Made final; constructor docblock updated to require `array{results: array<int, Task>, from: non-negative-int
Endpoints — map results to Task src/Endpoints/Tasks.php, src/Endpoints/Indexes.php	Post-process HTTP responses: each item in results is converted to a Task via Task::fromArray(..., partial(Tasks::waitTask(...), $this->http)), so returned results contain Task objects instead of raw arrays.
Delegate — null-safe options call src/Endpoints/Delegates/HandlesTasks.php	Simplified options handling to an inline null-safe expression: $response = $this->tasks->all($options?->toArray() ?? []); (removed explicit null check and temp variable).

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant IndexesEndpoint as Indexes Endpoint
  participant HTTP as HTTP Client
  participant TaskFactory as Task::fromArray
  participant TasksResults as TasksResults

  Client->>IndexesEndpoint: getTasks(options)
  IndexesEndpoint->>HTTP: GET /tasks with query/options
  HTTP-->>IndexesEndpoint: response { results: [array...], from, limit, next, total }
  IndexesEndpoint->>TaskFactory: Task::fromArray(arrayItem, partial(waitTask, http))
  TaskFactory-->>IndexesEndpoint: Task instance
  IndexesEndpoint->>TasksResults: new TasksResults({ results: [Task,...], from, limit, next, total })
  TasksResults-->>Client: TasksResults (results contain Task objects)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add raw data to Task and implement ArrayAccess #863 — Changes introducing per-item Task::fromArray usage and related Task construction logic.
• Bump to PHP 8.1, improve type safety for Tasks #735 — Earlier adjustments touching TasksResults and mapping task result arrays to Task objects.

Suggested reviewers

• curquiza
• brunoocasali

Poem

🐰 I hop where arrays once lay,
Now each result dons a Task by day.
Limit and total stand in line,
Count snoozes while constructors shine.
A tiny hop — mapped things are fine.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Wrap data with Task before passing to TasksResults' accurately summarizes the main objective of the pull request, which is to transform task arrays into Task objects before passing them to TasksResults.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/Contracts/TasksResults.php`:
- Around line 29-45: The TasksResults constructor is assigning $params['next']
which can be null, but the docblock and property expect a non-negative-int;
update the signature and property to accept null by changing the array docblock
for 'next' to allow null (non-negative-int|null) and adjust the TasksResults
class property declaration (e.g. $next) to a nullable type, and ensure the
__construct continues to assign $this->next = $params['next'] without forcing a
non-null cast so null values are preserved.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/Contracts/TasksResults.php (1)

19-22: Fix nullable handling for $from - pipeline failure.

The pipeline failure indicates that $params['from'] can be null when the API returns no results, but the property is typed as int. This is the same pattern as the $next field which was already made nullable."If from is set with an out of bounds task uid, the response returns the tasks that are the nearest to the specified uid." However, the Meilisearch API specification indicates that from can be null when no tasks exist or when paginating past all results.

🐛 Proposed fix to make `$from` nullable

 /**
- * `@var` non-negative-int
+ * `@var` non-negative-int|null
  */
-private int $from;
+private ?int $from;

 /**
  * `@param` array{
  *     results: array<int, Task>,
- *     from: non-negative-int,
+ *     from: non-negative-int|null,
  *     limit: non-negative-int,
  *     next: non-negative-int|null,
  *     total: non-negative-int
  * } $params
  */
 public function __construct(array $params)
 {
     parent::__construct($params['results']);

     $this->from = $params['from'];
     $this->limit = $params['limit'];
     $this->next = $params['next'];
     $this->total = $params['total'];
 }

Also update getFrom() return type:

 /**
- * `@return` non-negative-int
+ * `@return` non-negative-int|null
  */
-public function getFrom(): int
+public function getFrom(): ?int
 {
     return $this->from;
 }

And update toArray() docblock:

 /**
  * `@return` array{
  *     results: array<int, Task>,
- *     from: non-negative-int,
+ *     from: non-negative-int|null,
  *     limit: non-negative-int,
  *     next: non-negative-int|null,
  *     total: non-negative-int
  * }
  */

Also applies to: 29-45

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.25%. Comparing base (0078a8c) to head (ba7669c).
⚠️ Report is 116 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #864      +/-   ##
==========================================
- Coverage   89.78%   87.25%   -2.53%     
==========================================
  Files          59       81      +22     
  Lines        1449     1766     +317     
==========================================
+ Hits         1301     1541     +240     
- Misses        148      225      +77     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/Contracts/TasksResults.php`:
- Around line 88-96: The docblock for TasksResults::toArray() incorrectly allows
next to be null; update the return annotation so next is non-negative-int
(remove the |null) to match the non-nullable property $next and the coercion
logic in the constructor and toArray() method (refer to class TasksResults,
property $next, and method toArray()).