Run summary

docs/README.md

@@ -12,6 +12,8 @@ Cron job scheduler - with locks, parallelism and more
 - [Job types](#job-types)
 	- [Callback job](#callback-job)
 	- [Custom job](#custom-job)
+- [Job info and result](#job-info-and-result)
+- [Run summary](#run-summary)
 
 ## Why do you need it?
 
@@ -135,13 +137,12 @@ $scheduler->addBeforeJobCallback(
 $scheduler->addAfterJobCallback(
 	function(JobInfo $info, JobResult $result): void {
 		// Executes after job finish
-
-		$end = $result->getEnd(); // DateTimeImmutable
-		$throwable = $result->getThrowable(); // Throwable|null
 	},
 );
 ```
 
+Check [job info and result](#job-info-and-result) for available status info
+
 ## Logging errors
 
 Because any exceptions and errors are suppressed to prevent one failing job from failing others, you have to handle
@@ -217,3 +218,37 @@ $scheduler->addJob(
 	/* ... */,
 );
 ```
+
+## Job info and result
+
+Status information available via [events](#events) and [run summary](#run-summary)
+
+Info:
+
+```php
+$name = $info->getName(); // string
+$expression = $info->getExpression(); // string, e.g. '* * * * *'
+$start = $info->getStart(); // DateTimeImmutable
+```
+
+Result:
+
+```php
+$end = $result->getEnd(); // DateTimeImmutable
+$throwable = $result->getThrowable(); // Throwable|null
+```
+
+## Run summary
+
+Scheduler run returns summary for inspection
+
+```php
+$summary = $scheduler->run(); // RunSummary
+
+foreach ($summary->getJobs() as [$info, $result]) {
+	// $info instanceof JobInfo
+	// $result instanceof JobResult
+}
+```
+
+Check [job info and result](#job-info-and-result) for available jobs status info

src/Scheduler.php

@@ -8,6 +8,7 @@
 use Orisai\Scheduler\Job\Job;
 use Orisai\Scheduler\Status\JobInfo;
 use Orisai\Scheduler\Status\JobResult;
+use Orisai\Scheduler\Status\RunSummary;
 use Psr\Clock\ClockInterface;
 use Throwable;
 
@@ -35,7 +36,7 @@ public function addJob(Job $job, CronExpression $expression): void
 		$this->jobs[] = [$job, $expression];
 	}
 
-	public function run(): void
+	public function run(): RunSummary
 	{
 		$runStart = $this->clock->now();
 		$jobs = [];
@@ -45,6 +46,7 @@ public function run(): void
 			}
 		}
 
+		$summaryJobs = [];
 		foreach ($jobs as [$job, $expression]) {
 			$info = new JobInfo(
 				$job->getName(),
@@ -68,7 +70,11 @@ public function run(): void
 			foreach ($this->afterJob as $cb) {
 				$cb($info, $result);
 			}
+
+			$summaryJobs[] = [$info, $result];
 		}
+
+		return new RunSummary($summaryJobs);
 	}
 
 	/**

src/Status/RunSummary.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types = 1);
+
+namespace Orisai\Scheduler\Status;
+
+final class RunSummary
+{
+
+	/** @var list<array{JobInfo, JobResult}> */
+	private array $jobs;
+
+	/**
+	 * @param list<array{JobInfo, JobResult}> $jobs
+	 */
+	public function __construct(array $jobs)
+	{
+		$this->jobs = $jobs;
+	}
+
+	/**
+	 * @return list<array{JobInfo, JobResult}>
+	 */
+	public function getJobs(): array
+	{
+		return $this->jobs;
+	}
+
+}

tests/Unit/SchedulerTest.php

@@ -254,4 +254,43 @@ static function () use (&$i): void {
 		self::assertSame(1, $i);
 	}
 
+	public function testRunSummary(): void
+	{
+		$clock = new FrozenClock(1);
+		$scheduler = new Scheduler($clock);
+
+		$job = new CallbackJob(
+			static function (): void {
+				// Noop
+			},
+		);
+		$scheduler->addJob($job, new CronExpression('* * * * *'));
+		$scheduler->addJob($job, new CronExpression('* * * * *'));
+
+		$summary = $scheduler->run();
+
+		$now = $clock->now();
+		self::assertEquals(
+			[
+				[
+					new JobInfo(
+						'Tests\Orisai\Scheduler\Unit\{closure}',
+						'* * * * *',
+						$now,
+					),
+					new JobResult($now, null),
+				],
+				[
+					new JobInfo(
+						'Tests\Orisai\Scheduler\Unit\{closure}',
+						'* * * * *',
+						$now,
+					),
+					new JobResult($now, null),
+				],
+			],
+			$summary->getJobs(),
+		);
+	}
+
 }

tests/Unit/Status/RunSummaryTest.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types = 1);
+
+namespace Tests\Orisai\Scheduler\Unit\Status;
+
+use DateTimeImmutable;
+use Orisai\Scheduler\Status\JobInfo;
+use Orisai\Scheduler\Status\JobResult;
+use Orisai\Scheduler\Status\RunSummary;
+use PHPUnit\Framework\TestCase;
+
+final class RunSummaryTest extends TestCase
+{
+
+	public function test(): void
+	{
+		$jobs = [
+			[
+				new JobInfo('1', '* * * * *', new DateTimeImmutable()),
+				new JobResult(new DateTimeImmutable(), null),
+			],
+			[
+				new JobInfo('2', '1 * * * *', new DateTimeImmutable()),
+				new JobResult(new DateTimeImmutable(), null),
+			],
+		];
+
+		$summary = new RunSummary($jobs);
+		self::assertSame(
+			$jobs,
+			$summary->getJobs(),
+		);
+	}
+
+}