feat(functional): add functional SQL syntax with Option-aware filtering and docs

Author: MPCoreDeveloper

docs/FUNCTIONAL_NULL_SAFETY.md

@@ -159,6 +159,62 @@ Database operations have inherently unpredictable data. Foreign keys reference d
 
 ---
 
+## Functional SQL Syntax (v1.7.0)
+
+SharpCoreDB.Functional now supports a functional SQL layer that maps directly to `Option<T>` semantics.
+
+### Example syntax
+
+```sql
+SELECT Id, Name, Email OPTIONALLY FROM Users
+WHERE Email IS SOME;
+```
+
+### Supported functional SQL keywords
+
+| Keyword | Meaning |
+|---|---|
+| `OPTIONALLY FROM` | Returns a `Seq<Option<T>>` result shape from `ExecuteFunctionalSqlAsync<T>` |
+| `IS SOME` | Semantic non-null check (filters out `null`, empty string, and `"NULL"`) |
+| `IS NONE` | Semantic null check (matches `null`, empty string, and `"NULL"`) |
+| `MATCH SOME column` | Alias of `column IS SOME` |
+| `MATCH NONE column` | Alias of `column IS NONE` |
+| `UNWRAP Column AS Alias DEFAULT 'x'` | Projects a value with default fallback metadata |
+
+### C# usage
+
+```csharp
+var functional = db.Functional();
+
+var rows = await functional.ExecuteFunctionalSqlAsync<UserDto>(
+    "SELECT Id, Name, Email OPTIONALLY FROM Users WHERE Email IS SOME");
+
+foreach (var row in rows)
+{
+    var email = row
+        .Map(u => u.Email)
+        .IfNone("no-email");
+
+    Console.WriteLine(email);
+}
+```
+
+### Verify functional SQL behavior yourself
+
+Run the dedicated functional SQL tests:
+
+```bash
+dotnet test tests/SharpCoreDB.Functional.Tests --filter "FullyQualifiedName~FunctionalSqlSyntaxTests" --verbosity normal
+```
+
+Test source:
+
+- [`tests/SharpCoreDB.Functional.Tests/FunctionalSqlSyntaxTests.cs`](../tests/SharpCoreDB.Functional.Tests/FunctionalSqlSyntaxTests.cs)
+
+This suite validates parser translation, `OPTIONALLY FROM`, `IS SOME` / `IS NONE`, match aliases, unwrap mapping, and end-to-end filtering behavior.
+
+---
+
 ## Verify It Yourself
 
 All claims above are backed by **12 passing tests** you can run right now.

src/SharpCoreDB.Functional/FunctionalDb.cs

@@ -131,6 +131,158 @@ public Task<Seq<T>> QueryAsync<T>(
         return Task.FromResult(toSeq(list));
     }
 
+    /// <summary>
+    /// Executes a Functional SQL statement that uses SharpCoreDB's extended syntax.
+    /// Supports <c>OPTIONALLY FROM</c>, <c>IS SOME</c>, <c>IS NONE</c>,
+    /// <c>UNWRAP column AS alias</c>, and <c>MATCH SOME/NONE</c> keywords.
+    /// </summary>
+    /// <typeparam name="T">Row model type.</typeparam>
+    /// <param name="functionalSql">The Functional SQL statement.</param>
+    /// <param name="parameters">Optional query parameters.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>
+    /// When <c>OPTIONALLY FROM</c> is used, returns a sequence of <see cref="Option{T}"/>
+    /// (each row wrapped). Otherwise returns <c>Some</c> rows only.
+    /// </returns>
+    /// <example>
+    /// <code>
+    /// // Get users who have an email, each wrapped in Option
+    /// var users = await fdb.ExecuteFunctionalSqlAsync&lt;UserDto&gt;(
+    ///     "SELECT Id, Name, Email OPTIONALLY FROM Users WHERE Email IS SOME");
+    ///
+    /// foreach (var userOpt in users)
+    /// {
+    ///     var name = userOpt.Map(u => u.Name).IfNone("unknown");
+    /// }
+    /// </code>
+    /// </example>
+    public Task<Seq<Option<T>>> ExecuteFunctionalSqlAsync<T>(
+        string functionalSql,
+        Dictionary<string, object?>? parameters = null,
+        CancellationToken cancellationToken = default)
+        where T : class, new()
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(functionalSql);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var translator = new FunctionalSqlTranslator();
+        var result = translator.Translate(functionalSql);
+
+        var rows = _inner.ExecuteQuery(result.StandardSql, parameters);
+        if (rows.Count == 0)
+        {
+            return Task.FromResult(Seq<Option<T>>.Empty);
+        }
+
+        var list = new List<Option<T>>(rows.Count);
+        foreach (var row in rows)
+        {
+            // Apply UNWRAP defaults: if column is null/empty, substitute default
+            foreach (var unwrap in result.UnwrapMappings)
+            {
+                if (TryGetValueIgnoreCase(row, unwrap.Column, out var val)
+                    && (val is null || (val is string s && string.IsNullOrEmpty(s)))
+                    && unwrap.DefaultValue is not null)
+                {
+                    row[unwrap.Column] = unwrap.DefaultValue;
+                }
+            }
+
+            // Apply post-filter for SOME columns (defense-in-depth beyond SQL translation)
+            if (result.SomeColumns.Count > 0 && !PassesSomeFilter(row, result.SomeColumns))
+            {
+                continue;
+            }
+
+            // Apply post-filter for NONE columns (defense-in-depth beyond SQL translation)
+            if (result.NoneColumns.Count > 0 && !PassesNoneFilter(row, result.NoneColumns))
+            {
+                continue;
+            }
+
+            var mapped = TryMapRow<T>(row);
+            list.Add(mapped);
+        }
+
+        return Task.FromResult(toSeq(list));
+    }
+
+    /// <summary>
+    /// Executes a Functional SQL query returning only successfully mapped rows
+    /// (unwrapped from <c>Option&lt;T&gt;</c>). Convenience method when you want
+    /// a flat sequence instead of <c>Seq&lt;Option&lt;T&gt;&gt;</c>.
+    /// </summary>
+    /// <typeparam name="T">Row model type.</typeparam>
+    /// <param name="functionalSql">The Functional SQL statement.</param>
+    /// <param name="parameters">Optional query parameters.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A flat <see cref="Seq{T}"/> of successfully mapped rows.</returns>
+    public async Task<Seq<T>> ExecuteFunctionalSqlUnwrappedAsync<T>(
+        string functionalSql,
+        Dictionary<string, object?>? parameters = null,
+        CancellationToken cancellationToken = default)
+        where T : class, new()
+    {
+        var results = await ExecuteFunctionalSqlAsync<T>(functionalSql, parameters, cancellationToken)
+            .ConfigureAwait(false);
+
+        var list = new List<T>(results.Count);
+        foreach (var opt in results)
+        {
+            opt.IfSome(list.Add);
+        }
+
+        return toSeq(list);
+    }
+
+    private static bool PassesSomeFilter(Dictionary<string, object> row, IReadOnlyList<string> someColumns)
+    {
+        foreach (var col in someColumns)
+        {
+            if (!TryGetValueIgnoreCase(row, col, out var val))
+            {
+                return false;
+            }
+
+            if (IsSemanticNone(val))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static bool PassesNoneFilter(Dictionary<string, object> row, IReadOnlyList<string> noneColumns)
+    {
+        foreach (var col in noneColumns)
+        {
+            if (!TryGetValueIgnoreCase(row, col, out var val))
+            {
+                continue;
+            }
+
+            if (!IsSemanticNone(val))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static bool IsSemanticNone(object? value)
+    {
+        return value switch
+        {
+            null => true,
+            DBNull => true,
+            string s when string.IsNullOrWhiteSpace(s) => true,
+            string s when string.Equals(s, "NULL", StringComparison.OrdinalIgnoreCase) => true,
+            _ => false
+        };
+    }
+
     /// <summary>
     /// Inserts an entity into a table.
     /// </summary>
@@ -378,7 +530,20 @@ private static bool TryGetValueIgnoreCase(Dictionary<string, object> row, string
         ArgumentNullException.ThrowIfNull(value);
         ArgumentNullException.ThrowIfNull(targetType);
 
-        var underlying = Nullable.GetUnderlyingType(targetType) ?? targetType;
+        if (value == DBNull.Value)
+        {
+            return Nullable.GetUnderlyingType(targetType) is not null || !targetType.IsValueType
+                ? null
+                : throw new InvalidOperationException($"Cannot map DBNull to non-nullable type '{targetType.Name}'.");
+        }
+
+        var nullableUnderlying = Nullable.GetUnderlyingType(targetType);
+        var underlying = nullableUnderlying ?? targetType;
+
+        if (value is string textValue && string.IsNullOrEmpty(textValue) && nullableUnderlying is not null)
+        {
+            return null;
+        }
 
         if (underlying.IsInstanceOfType(value))
         {