Refactor: modernize plugin with operation-based API

- Upgrade to .NET 10.0 and FlowSynx.PluginCore 1.4.0
- Replace handler-based API with strongly-typed operations (Extract, Map, Transform)
- Introduce per-operation parameter classes and metadata
- Add ParseDataHelper for input normalization
- Remove legacy handler interfaces and InputParameter
- Use strongly-typed JsonPluginSpecifications
- Overhaul test suite for new API and parameter validation
- Improve error handling, validation, and extensibility
- Set minimum FlowSynx version to 1.3.0

#9

Author: ziagham

src/FlowSynx.Plugins.Json.csproj

@@ -1,13 +1,13 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
 	<PropertyGroup>
-		<TargetFramework>net9.0</TargetFramework>
+		<TargetFramework>net10.0</TargetFramework>
 		<ImplicitUsings>enable</ImplicitUsings>
 		<Nullable>enable</Nullable>
 	</PropertyGroup>
 
 	<ItemGroup>
-		<PackageReference Include="FlowSynx.PluginCore" Version="1.3.2" />
+		<PackageReference Include="FlowSynx.PluginCore" Version="1.4.0" />
 	</ItemGroup>
 
 	<ItemGroup>

src/Helpers/ParseDataHelper.cs

@@ -0,0 +1,28 @@
+using FlowSynx.PluginCore;
+using FlowSynx.Plugins.Json.Services;
+
+namespace FlowSynx.Plugins.Json.Helpers;
+
+internal class ParseDataHelper
+{
+    private readonly IGuidProvider _guidProvider;
+
+    public ParseDataHelper(IGuidProvider guidProvider)
+    {
+        _guidProvider = guidProvider ?? throw new ArgumentNullException(nameof(guidProvider));
+    }
+
+    public PluginContext ParseDataToContext(object? data)
+    {
+        if (data is null)
+            throw new ArgumentNullException(nameof(data), "Input data cannot be null.");
+
+        return data switch
+        {
+            PluginContext singleContext => singleContext,
+            IEnumerable<PluginContext> => throw new NotSupportedException("List of PluginContext is not supported."),
+            string strData => new PluginContext(_guidProvider.NewGuid().ToString(), "Data") { Content = strData },
+            _ => throw new NotSupportedException("Unsupported input data format.")
+        };
+    }
+}

src/JsonPlugin.cs

@@ -1,15 +1,17 @@
 using FlowSynx.PluginCore;
 using FlowSynx.PluginCore.Extensions;
-using FlowSynx.Plugins.Json.Models;
+using FlowSynx.Plugins.Json.Operations.Extract;
+using FlowSynx.Plugins.Json.Operations.Map;
+using FlowSynx.Plugins.Json.Operations.Transform;
 using FlowSynx.Plugins.Json.Services;
-using Newtonsoft.Json.Linq;
 
 namespace FlowSynx.Plugins.Json;
 
 public class JsonPlugin : IPlugin
 {
     private readonly IGuidProvider _guidProvider;
     private readonly IReflectionGuard _reflectionGuard;
+    private JsonPluginSpecifications? _specifications = null;
     private IPluginLogger? _logger;
     private bool _isInitialized;
 
@@ -27,7 +29,7 @@ internal JsonPlugin(IGuidProvider guidProvider, IReflectionGuard reflectionGuard
         Name = "Json",
         CompanyName = "FlowSynx",
         Description = Resources.PluginDescription,
-        Version = new Version(1, 1, 1),
+        Version = new Version(1, 2, 0),
         Category = PluginCategory.Data,
         Authors = new List<string> { "FlowSynx" },
         Copyright = "© FlowSynx. All rights reserved.",
@@ -36,34 +38,40 @@ internal JsonPlugin(IGuidProvider guidProvider, IReflectionGuard reflectionGuard
         RepositoryUrl = "https://github.com/flowsynx/plugin-json",
         ProjectUrl = "https://flowsynx.io",
         Tags = new List<string>() { "flowSynx", "json", "data", "data-platform" },
-        MinimumFlowSynxVersion = new Version(1, 1, 1),
+        MinimumFlowSynxVersion = new Version(1, 3, 0),
     };
 
-    public PluginSpecifications? Specifications { get; set; }
+    public IPluginSpecifications? Specifications => _specifications;
 
-    public Type SpecificationsType => typeof(JsonPluginSpecifications);
-
-    private Dictionary<string, IJsonOperationHandler> OperationMap => new(StringComparer.OrdinalIgnoreCase)
+    public IReadOnlyCollection<IPluginOperation> SupportedOperations { get; } = new IPluginOperation[]
     {
-        ["extract"] = new ExtractOperationHandler(_guidProvider),
-        ["map"] = new MapOperationHandler(_guidProvider),
-        ["transform"] = new TransformOperationHandler(_guidProvider)
+        new ExtractOperation(),
+        new MapOperation(),
+        new TransformOperation()
     };
 
-    public IReadOnlyCollection<string> SupportedOperations => OperationMap.Keys;
-
-    public Task Initialize(IPluginLogger logger)
+    public Task InitializeAsync(IPluginLogger logger, IDictionary<string, object?>? specifications)
     {
         if (_reflectionGuard.IsCalledViaReflection())
             throw new InvalidOperationException(Resources.ReflectionBasedAccessIsNotAllowed);
 
-        ArgumentNullException.ThrowIfNull(logger);
-        _logger = logger;
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+
+        var jsonSpecifications = new JsonPluginSpecifications();
+        if (specifications != null)
+            jsonSpecifications.FromDictionary(specifications);
+
+        jsonSpecifications.Validate();
+        _specifications = jsonSpecifications;
+
         _isInitialized = true;
         return Task.CompletedTask;
     }
 
-    public Task<object?> ExecuteAsync(PluginParameters parameters, CancellationToken cancellationToken)
+    public async Task<object?> ExecuteAsync(
+        string? operationName,
+        PluginParameters parameters,
+        CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
 
@@ -73,30 +81,22 @@ public Task Initialize(IPluginLogger logger)
         if (!_isInitialized)
             throw new InvalidOperationException($"Plugin '{Metadata.Name}' v{Metadata.Version} is not initialized.");
 
-        var inputParameter = parameters.ToObject<InputParameter>();
-        if (!OperationMap.TryGetValue(inputParameter.Operation, out var handler))
+        var operation = SupportedOperations
+            .FirstOrDefault(op => string.Equals(op.Name, operationName, StringComparison.OrdinalIgnoreCase))
+            ?? throw new NotSupportedException($"Operation '{operationName}' is not supported.");
+
+        return operation.Name.ToLowerInvariant() switch
         {
-            throw new NotSupportedException($"Operation '{inputParameter.Operation}' is not supported.");
-        }
+            "extract" => await ((ExtractOperation)operation)
+                            .ExecuteAsync(parameters.ToObject<ExtractParameters>(), cancellationToken),
 
-        var context = ParseDataToContext(inputParameter.Data);
-        var json = context.Content ?? throw new ArgumentException("Input JSON is required.");
+            "map" => await ((MapOperation)operation)
+                            .ExecuteAsync(parameters.ToObject<MapParameters>(), cancellationToken),
 
-        var jsonToken = JToken.Parse(json);
-        return Task.FromResult(handler.Handle(jsonToken, inputParameter));
-    }
+            "transform" => await ((TransformOperation)operation)
+                            .ExecuteAsync(parameters.ToObject<TransformParameters>(), cancellationToken),
 
-    private PluginContext ParseDataToContext(object? data)
-    {
-        if (data is null)
-            throw new ArgumentNullException(nameof(data), "Input data cannot be null.");
-
-        return data switch
-        {
-            PluginContext singleContext => singleContext,
-            IEnumerable<PluginContext> => throw new NotSupportedException("List of PluginContext is not supported."),
-            string strData => new PluginContext(_guidProvider.NewGuid().ToString(), "Data") { Content = strData },
-            _ => throw new NotSupportedException("Unsupported input data format.")
+            _ => throw new InvalidOperationException($"Unsupported operation: {operation.Name}")
         };
     }
 }

src/JsonPluginSpecifications.cs

@@ -0,0 +1,11 @@
+using FlowSynx.PluginCore;
+
+namespace FlowSynx.Plugins.Json;
+
+public class JsonPluginSpecifications : PluginSpecifications
+{
+    public override void Validate()
+    {
+
+    }
+}

src/Models/InputParameter.cs

@@ -1,26 +1,31 @@
 using FlowSynx.PluginCore;
-using FlowSynx.Plugins.Json.Models;
+using FlowSynx.Plugins.Json.Helpers;
+using FlowSynx.Plugins.Json.Services;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 
-namespace FlowSynx.Plugins.Json.Services;
+namespace FlowSynx.Plugins.Json.Operations.Extract;
 
-internal class ExtractOperationHandler : IJsonOperationHandler
+internal class ExtractOperation : IPluginOperation<ExtractParameters, PluginContext>
 {
-    private readonly IGuidProvider _guidProvider;
+    private readonly IGuidProvider _guidProvider = new GuidProvider();
 
-    public ExtractOperationHandler(IGuidProvider guidProvider)
-    {
-        _guidProvider = guidProvider;
-    }
+    public string Name => "Extract";
+    public string Description => "Extracts data from a JSON content.";
 
-    public object Handle(JToken json, InputParameter inputParameter)
+    public async Task<PluginContext?> ExecuteAsync(ExtractParameters parameters, CancellationToken cancellationToken)
     {
-        string? path = inputParameter.Path;
+        string? path = parameters.Path;
         if (string.IsNullOrWhiteSpace(path))
             throw new ArgumentException("Path parameter is required for extract.");
 
-        var tokens = json.SelectTokens(path).ToList();
+        var helper = new ParseDataHelper(_guidProvider);
+
+        var jsonCtx = helper.ParseDataToContext(parameters.Data);
+        if (string.IsNullOrWhiteSpace(jsonCtx.Content))
+            throw new ArgumentException("Input JSON content cannot be empty.");
+        var jsonToken = JToken.Parse(jsonCtx.Content);
+        var tokens = jsonToken.SelectTokens(path).ToList();
         string filename = $"{_guidProvider.NewGuid()}.json";
 
         List<Dictionary<string, object>>? structuredData = null;
@@ -43,7 +48,7 @@ public object Handle(JToken json, InputParameter inputParameter)
         return new PluginContext(filename, "Data")
         {
             Format = "Json",
-            Content = result.ToString(inputParameter.Indented ? Formatting.Indented : Formatting.None),
+            Content = result.ToString(parameters.Indented ? Formatting.Indented : Formatting.None),
             StructuredData = structuredData
         };
     }
@@ -57,6 +62,8 @@ public object Handle(JToken json, InputParameter inputParameter)
             {
                 if (item is JObject obj)
                     list.Add(obj.Properties().ToDictionary(p => p.Name, p => (object)p.Value.Type.ToString()));
+                else if (item is JValue jv)
+                    list.Add(new Dictionary<string, object> { { "$value", jv.Type.ToString() } });
             }
             return list.Count > 0 ? list : null;
         }
@@ -67,6 +74,13 @@ public object Handle(JToken json, InputParameter inputParameter)
                 obj2.Properties().ToDictionary(p => p.Name, p => (object)p.Value.Type.ToString())
             };
         }
+        if (token is JValue jv2)
+        {
+            return new List<Dictionary<string, object>>
+            {
+                new Dictionary<string, object> { { "$value", jv2.Type.ToString() } }
+            };
+        }
         return null;
     }
 }

src/Models/JsonPluginSpecifications.cs

@@ -0,0 +1,15 @@
+using FlowSynx.PluginCore;
+
+namespace FlowSynx.Plugins.Json.Operations.Extract;
+
+internal class ExtractParameters
+{
+    [OperationParameterMetadata(Description = "The JSON data to extract information from.", IsRequired = true)]
+    public object? Data { get; set; }
+
+    [OperationParameterMetadata(Description = "The JSON path to extract specific data.", IsRequired = true)]
+    public string? Path { get; set; }
+
+    [OperationParameterMetadata(Description = "Whether to indent the output JSON for readability.", IsRequired = false)]
+    public bool Indented { get; set; } = false;
+}

src/Services/ExtractOperationHandler.cs …c/Operations/Extract/ExtractOperation.cssrc/Services/ExtractOperationHandler.cs renamed to src/Operations/Extract/ExtractOperation.cs src/Services/ExtractOperationHandler.cs renamed to src/Operations/Extract/ExtractOperation.cs

@@ -0,0 +1,94 @@
+using FlowSynx.PluginCore;
+using FlowSynx.Plugins.Json.Helpers;
+using FlowSynx.Plugins.Json.Services;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+
+namespace FlowSynx.Plugins.Json.Operations.Map;
+
+internal class MapOperation : IPluginOperation<MapParameters, PluginContext>
+{
+    private readonly IGuidProvider _guidProvider = new GuidProvider();
+
+    public string Name => "Map";
+    public string Description => "Maps data from one structure to another.";
+
+    public async Task<PluginContext?> ExecuteAsync(MapParameters parameters, CancellationToken cancellationToken)
+    {
+        if (parameters.Mappings == null)
+            throw new InvalidOperationException("Mappings not defined in specifications.");
+
+        var helper = new ParseDataHelper(_guidProvider);
+
+        var context = helper.ParseDataToContext(parameters.Data);
+        var jsonToken = JToken.Parse(context.Content);
+
+        object mappedResult;
+        List<Dictionary<string, object>>? structuredData = null;
+
+        if (jsonToken is JArray array)
+        {
+            var mappedList = array
+                .OfType<JObject>()
+                .Select(obj => MapSingleObject(obj, parameters.Mappings))
+                .ToList();
+            mappedResult = mappedList;
+            structuredData = mappedList
+                .Select(obj => obj.ToDictionary(kvp => kvp.Key, kvp => (object)(kvp.Value?.GetType()?.Name ?? "null")))
+                .ToList();
+        }
+        else if (jsonToken is JObject obj)
+        {
+            var mappedObj = MapSingleObject(obj, parameters.Mappings);
+            mappedResult = mappedObj;
+            structuredData = new List<Dictionary<string, object>>
+            {
+                mappedObj.ToDictionary(kvp => kvp.Key, kvp => (object)(kvp.Value?.GetType()?.Name ?? "null"))
+            };
+        }
+        else
+        {
+            throw new NotSupportedException("HandleMap only supports JSON objects or arrays of objects.");
+        }
+            
+        string convertedJson = JsonConvert.SerializeObject(mappedResult, parameters.Indented ? Formatting.Indented : Formatting.None);
+        string filename = $"{_guidProvider.NewGuid()}.json";
+        return new PluginContext(filename, "Data")
+        {
+            Format = "Json",
+            Content = convertedJson,
+            StructuredData = structuredData
+        };
+    }
+
+    private Dictionary<string, object?> MapSingleObject(JObject obj, Dictionary<string, string> mappings)
+    {
+        var result = new Dictionary<string, object?>();
+
+        foreach (var kvp in mappings)
+        {
+            var value = obj.SelectToken(kvp.Value);
+            if (value == null)
+            {
+                result[kvp.Key] = null;
+                continue;
+            }
+
+            // Convert primitives to CLR strings to avoid leaking JValue into the result
+            switch (value.Type)
+            {
+                case JTokenType.Object:
+                case JTokenType.Array:
+                    // Keep complex types as-is
+                    result[kvp.Key] = value;
+                    break;
+                default:
+                    // Ensure primitives are represented as strings (as expected by tests)
+                    result[kvp.Key] = value.ToString();
+                    break;
+            }
+        }
+
+        return result;
+    }
+}