diff --git a/experimental/fluent/func/src/main/java/io/serverlessworkflow/fluent/func/dsl/FuncDSL.java b/experimental/fluent/func/src/main/java/io/serverlessworkflow/fluent/func/dsl/FuncDSL.java index cbe692b0a..79dc2c5b1 100644 --- a/experimental/fluent/func/src/main/java/io/serverlessworkflow/fluent/func/dsl/FuncDSL.java +++ b/experimental/fluent/func/src/main/java/io/serverlessworkflow/fluent/func/dsl/FuncDSL.java @@ -479,24 +479,88 @@ static String defaultUniqueId(WorkflowContextData wctx, TaskContextData tctx) { } /** - * Build a call step for functions that expect a composite "unique id" as the first parameter. - * This id is derived from the workflow instance id and the task definition position, encoded as a - * JSON pointer. + * Build a named call step for functions that expect a composite "unique id" as the first + * parameter. This id is derived from the workflow instance id and the task definition position, + * encoded as a JSON pointer. * - *
Signature expected: {@code (uniqueId, payload) -> result} + *
The unique ID follows the pattern: {@code " This overload requires explicit input class and infers the output type from the function
+ * signature.
+ *
+ * Signature expected: {@code (uniqueId, payload) -> result}
+ *
+ * Example:
+ *
+ * The unique ID follows the pattern: {@code " This overload provides complete control over type conversion by explicitly specifying both
+ * input and output classes. Use this when automatic type inference is not sufficient or when you
+ * need to ensure specific serialization/deserialization behavior.
+ *
+ * Signature expected: {@code (uniqueId, payload) -> result}
+ *
+ * Example:
+ *
+ * The unique ID follows the pattern: {@code " This overload uses reflection to automatically infer both input and output types from the
+ * {@link UniqueIdBiFunction} interface. This is the most concise variant but requires the
+ * function to be serializable for type inference to work.
+ *
+ * Signature expected: {@code (uniqueId, payload) -> result}
+ *
+ * Example:
+ *
+ * The unique ID follows the pattern: {@code " This overload requires an explicit input class and infers the output type from the function
+ * signature. Use this when you don't need to assign a specific task name.
+ *
+ * Signature expected: {@code (uniqueId, payload) -> result}
+ *
+ * Example:
+ *
+ * The unique ID follows the pattern: {@code " This is the most concise overload, using reflection to automatically infer both input and
+ * output types. It creates an anonymous task, which is useful for quick inline operations.
+ *
+ * Signature expected: {@code (uniqueId, payload) -> result}
+ *
+ * Example:
+ *
+ * {@code
+ * tasks(
+ * withUniqueId("processOrder",
+ * (String uniqueId, OrderRequest order) -> {
+ * // Use uniqueId for stateful operations (e.g., database keys, cache entries)
+ * return orderService.process(uniqueId, order);
+ * },
+ * OrderRequest.class
+ * )
+ * );
+ * }
*
* @param name task name (or {@code null} for an anonymous task)
- * @param fn unique-id-aware function
- * @param in payload input class
+ * @param fn unique-id-aware function accepting (uniqueId, payload) and returning a result
+ * @param in payload input class for type-safe conversion
* @param {@code
+ * tasks(
+ * withUniqueId("enrichData",
+ * (String uniqueId, Map
+ *
+ * @param name task name (or {@code null} for an anonymous task)
+ * @param fn unique-id-aware function accepting (uniqueId, payload) and returning a result
+ * @param in payload input class for type-safe conversion
+ * @param out result output class for type-safe conversion
+ * @param {@code
+ * tasks(
+ * withUniqueId("cacheResult",
+ * (String uniqueId, ProcessRequest req) -> {
+ * cache.store(uniqueId, req);
+ * return processor.handle(req);
+ * }
+ * )
+ * );
+ * }
+ *
+ * @param name task name (or {@code null} for an anonymous task)
+ * @param fn unique-id-aware function with serializable signature for type inference
+ * @param {@code
+ * tasks(
+ * withUniqueId(
+ * (String uniqueId, CustomerData data) -> {
+ * logger.log("Processing " + uniqueId);
+ * return customerProcessor.process(data);
+ * },
+ * CustomerData.class
+ * )
+ * );
+ * }
+ *
+ * @param fn unique-id-aware function accepting (uniqueId, payload) and returning a result
+ * @param in payload input class for type-safe conversion
* @param {@code
+ * tasks(
+ * withUniqueId((String uniqueId, String input) -> {
+ * // Quick stateful operation with unique ID
+ * stateManager.update(uniqueId, input);
+ * return input.toUpperCase();
+ * })
+ * );
+ * }
+ *
+ * @param fn unique-id-aware function with serializable signature for type inference
+ * @param