From 9dbfd7da8eac1acac8230abb7f7a78145fc96d22 Mon Sep 17 00:00:00 2001
From: kj <webmaster@outcontrol.net>
Date: Mon, 7 Sep 2026 16:17:34 -0300
Subject: [PATCH] feat: add named parameter injection to resolve()

---
 src/Libs/Synapsis.php | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/Libs/Synapsis.php b/src/Libs/Synapsis.php
index 6f0b8d7..616769e 100644
--- a/src/Libs/Synapsis.php
+++ b/src/Libs/Synapsis.php
@@ -65,12 +65,14 @@ class Synapsis
     /**
      * Resolves and injects dependencies for a callable and returns its result.
      *
-     * @param callable $action
+     * @param callable             $action
+     * @param array<string, mixed> $named  Associative array of values injected into the callable's
+     *                                     parameters by exact name match. Consumed in resolveParameterValues().
      *
      * @return mixed
      * @throws Exception If an unhandled callable type is provided.
      */
-    public static function resolve(callable $action): mixed
+    public static function resolve(callable $action, array $named = []): mixed
     {
         if ($action instanceof Closure) { // If it's an anonymous function
             $reflectionCallback = new ReflectionFunction($action);
@@ -90,7 +92,7 @@ class Synapsis
         // Get the parameters
         return call_user_func_array(
             $action,
-            static::resolveParameterValues($reflectionCallback->getParameters())
+            static::resolveParameterValues($reflectionCallback->getParameters(), $named)
         );
     }
 
@@ -132,11 +134,15 @@ class Synapsis
      * Resolves parameter values by injecting dependencies.
      *
      * @param array<ReflectionParameter> $parameters
+     * @param array<string, mixed> $named
+     *                                   Values injected into parameters whose name matches the key,
+     *                                   taking precedence over optional defaults and DI resolution.
+     *                                   Keys matching no parameter are ignored.
      *
      * @return array<mixed>
      * @throws Exception    If a primitive parameter does not have a default value.
      */
-    public static function resolveParameterValues(array $parameters): array
+    public static function resolveParameterValues(array $parameters, array $named = []): array
     {
         $values = [];
         foreach ($parameters as $parameter) {
@@ -144,6 +150,11 @@ class Synapsis
                 continue;
             }
 
+            if (array_key_exists($parameter->getName(), $named)) { // Named values win over defaults and DI
+                $values[] = $named[$parameter->getName()];
+                continue;
+            }
+
             if ($parameter->isOptional()) { // Always use the default value first
                 $values[] = $parameter->getDefaultValue();
                 continue;