- checkpoint: extend LINQ support

Author: NinjaRocks

docs/linq-querying.md

@@ -74,12 +74,20 @@ Internally, `Query<T>()` creates a template instance (`conn.Create(typeof(T))`),
 | `Where(x => cond1 \|\| cond2)` | `OrTerm` | |
 | `Where(x => !cond)` | `NotTerm` | |
 | `Where(x => list.Contains(x.Field))` | `InTerm` | |
+| `Where(x => x.Field.StartsWith(v))` | `LikeTerm` (`v%`) | |
+| `Where(x => x.Field.EndsWith(v))` | `LikeTerm` (`%v`) | |
+| `Where(x => x.BoolField)` | `EqualTerm` with `true` | Evaluates raw boolean fields natively |
 | `OrderBy(x => x.Field)` | `OrderAscending` | |
 | `OrderByDescending(x => x.Field)` | `OrderDescending` | |
 | `ThenBy(x => x.Field)` | Appended `OrderAscending` | Composites with primary sort |
 | `ThenByDescending(x => x.Field)` | Appended `OrderDescending` | |
 | `Take(n)` | `pageSize` parameter | |
 | `Skip(n)` | `start` parameter in `QueryPage` | |
+| `Count()`, `LongCount()` | `DataConnection.QueryCount` | Executes scalar COUNT immediately |
+| `First()`, `FirstOrDefault()` | `DataConnection.QueryFirst` | Executes scalar SELECT TOP 1 immediately |
+| `Single()`, `SingleOrDefault()`| `DataConnection.QueryFirst` | Throws if multiple results |
+| `Any()` | `DataConnection.QueryFirst` | Evaluates existence query directly |
+| `Select(x => new { ... })` | FieldSubset projection | Constructs partial SELECTs dynamically |
 
 ---
 
@@ -129,6 +137,27 @@ conn.Query<Product>().Where(p => names.Contains(p.Name))
 // → WHERE Name IN (@IN_Name0, @IN_Name1)
 ```
 
+### String Wildcards
+
+```csharp
+conn.Query<Product>().Where(p => p.Name.StartsWith("App"))
+// → WHERE Name LIKE 'App%'
+
+conn.Query<Product>().Where(p => p.Name.EndsWith("inc"))
+// → WHERE Name LIKE '%inc'
+
+// Note: MongoDB handles these as regular expressions (.*pattern or pattern.*) automatically.
+```
+
+### Implicit Booleans
+
+You can natively pass `TBool` fields directly into the lambda constraint, mimicking standard .NET semantics.
+
+```csharp
+conn.Query<Product>().Where(p => p.IsActive)
+// → WHERE IsActive = 1
+```
+
 ### Captured local variables
 
 ```csharp
@@ -176,6 +205,40 @@ Without `Skip`/`Take`, execution uses `conn.LazyQueryAll(...)` for memory-effici
 
 ---
 
+## Scalar & Terminal Methods
+
+ActiveForge supports invoking terminal scalar executors directly on the query, compiling immediately and sending a constrained scalar demand to the DB.
+
+```csharp
+// Returns scalar INT directly
+int count = conn.Query<Product>().Where(p => p.IsActive).Count();
+
+// Returns scalar Bool (Exists check)
+bool hasAny = conn.Query<Product>().Where(p => p.Price > 100).Any();
+
+// Retrieves the TOP 1 entity
+var topItem = conn.Query<Product>().OrderBy(p => p.Price).FirstOrDefault();
+```
+
+---
+
+## Projections (Select)
+
+Anonymous type projection parses requested properties to prune the retrieved columns securely at the database level by evaluating a tailored `FieldSubset`.
+
+```csharp
+// The SQL executed will ONLY 'SELECT p.Id, p.Name FROM Products p'
+var lightweightList = conn.Query<Product>()
+    .Where(p => p.IsActive)
+    .Select(p => new {
+        p.ID,
+        p.Name
+    })
+    .ToList();
+```
+
+---
+
 ## Lazy Enumeration
 
 `IQueryable<T>` is lazy — the database is not queried until you start iterating:
@@ -312,8 +375,6 @@ The expression tree is traversed **at execution time**, so local variables are c
 |------------|-------|
 | No `GroupBy` | Not supported; use raw SQL or `ExecSQL`. |
 | No `Join` clause | Cross-join predicates and sorts work via embedded `Record` fields. See [joins.md](joins.md). |
-| No `Select` projection | Returns full typed `Record` instances; field subsets can be applied at the `conn.Query<T>(template)` level. |
-| No `Count()`, `First()`, etc. | Call the standard ORM methods (`conn.QueryCount(...)`, `conn.QueryFirst(...)`) directly. |
 | No async support | Use the synchronous API; async is planned for a future release. |
 
 ---

docs/provider-appendix.md

@@ -478,6 +478,8 @@ public abstract class DBDataConnection : DataConnection, IDisposable
     ///
     /// SQL Server: SELECT @@IDENTITY  (not SCOPE_IDENTITY — see note in MEMORY.md)
     /// PostgreSQL: RETURNING id  (implemented via RETURNING clause in INSERT SQL)
+    ///             Note: PostgreSQL row locking (ReadForUpdate) requires overriding 
+    ///             GetReadForUpdateSQL to append "FOR UPDATE" to the end of the query.
     /// SQLite:     SELECT last_insert_rowid()
     /// MongoDB:    n/a (uses auto-increment counter collection)
     /// </summary>
@@ -602,6 +604,12 @@ public class MyConnection : DBDataConnection
     // Identity insert wrappers (if not supported, return empty strings)
     public override string PreInsertIdentityCommand(string sourceName)  => "";
     public override string PostInsertIdentityCommand(string sourceName) => "";
+
+    // PostgreSQL ReadForUpdate requires custom placement of FOR UPDATE
+    protected override string GetReadForUpdateSQL(Record obj, RecordBinding binding, List<FieldBinding> fieldBindingSubset, FieldSubset fieldSubset) {
+        // ... (see PostgreSQLConnection implementation for details)
+        return "SELECT ... FROM ... WHERE ... FOR UPDATE";
+    }
 }
 ```
 

docs/transactions.md

@@ -207,7 +207,8 @@ conn.ProcessActionQueue();
 ## Read-for-update (advisory lock)
 
 `ReadForUpdate` acquires a row-level update lock on SQL Server
-(`SELECT ... WITH (UPDLOCK)`) so that no other session can update the row
+(`SELECT ... WITH (UPDLOCK)`) and PostgreSQL (`SELECT ... FOR UPDATE`)
+so that no other session can update the row
 between your read and your subsequent write:
 
 ```csharp

docs/wiki.md

@@ -692,7 +692,28 @@ conn.Query<Product>().Where(p => !(p.InStock == true)).ToList();
 var names = new List<string> { "Widget", "Gadget", "Gizmo" };
 conn.Query<Product>().Where(p => names.Contains(p.Name)).ToList();
 
-// Local variable capture (evaluated at translation time)
+### String Wildcards
+
+```csharp
+conn.Query<Product>().Where(p => p.Name.StartsWith("App")).ToList();
+// → WHERE Name LIKE 'App%'
+
+conn.Query<Product>().Where(p => p.Name.EndsWith("inc")).ToList();
+// → WHERE Name LIKE '%inc'
+```
+
+### Implicit Booleans
+
+You can natively pass `TBool` fields directly into the lambda constraint:
+
+```csharp
+conn.Query<Product>().Where(p => p.IsActive).ToList();
+// → WHERE IsActive = 1
+```
+
+### Captured local variables
+
+```csharp
 string target  = "Widget";
 decimal minP   = 10m;
 conn.Query<Product>().Where(p => p.Name == target && p.Price >= minP).ToList();
@@ -771,24 +792,60 @@ List<Product> results = conn.Query<Product>()
 | `a \|\| b` | `OrTerm` | |
 | `!a` | `NotTerm` | |
 | `list.Contains(x.F)` | `InTerm` | Use `List<T>`, not arrays |
+| `x.F.StartsWith(v)` | `LikeTerm` (`v%`) | |
+| `x.F.EndsWith(v)` | `LikeTerm` (`%v`) | |
+| `x.BoolField` | `EqualTerm` with `true` | Evaluates raw boolean fields natively |
 | `OrderBy` | `OrderAscending` | |
 | `OrderByDescending` | `OrderDescending` | |
 | `ThenBy` | Appended ascending | |
 | `ThenByDescending` | Appended descending | |
 | `Take(n)` | `pageSize` | |
 | `Skip(n)` | `startRecord` | |
+| `Count()`, `LongCount()` | `DataConnection.QueryCount` | Executes scalar COUNT immediately |
+| `First()`, `FirstOrDefault()` | `DataConnection.QueryFirst` | Executes scalar SELECT TOP 1 immediately |
+| `Single()`, `SingleOrDefault()`| `DataConnection.QueryFirst` | Throws if multiple results |
+| `Any()` | `DataConnection.QueryFirst` | Evaluates existence query directly |
+| `Select(x => new { ... })` | FieldSubset projection | Constructs partial SELECTs dynamically |
+
+### 9.8 Scalar & Terminal Methods
 
-### 9.8 Limitations
+ActiveForge supports invoking terminal scalar executors directly on the query, compiling immediately and sending a constrained scalar demand to the DB.
+
+```csharp
+// Returns scalar INT directly
+int count = conn.Query<Product>().Where(p => p.IsActive).Count();
+
+// Returns scalar Bool (Exists check)
+bool hasAny = conn.Query<Product>().Where(p => p.Price > 100).Any();
+
+// Retrieves the TOP 1 entity
+var topItem = conn.Query<Product>().OrderBy(p => p.Price).FirstOrDefault();
+```
+
+### 9.9 Projections (Select)
+
+Anonymous type projection parses requested properties to prune the retrieved columns securely at the database level by evaluating a tailored `FieldSubset`.
+
+```csharp
+// The SQL executed will ONLY 'SELECT p.Id, p.Name FROM Products p'
+var lightweightList = conn.Query<Product>()
+    .Where(p => p.IsActive)
+    .Select(p => new {
+        p.ID,
+        p.Name
+    })
+    .ToList();
+```
+
+### 9.10 Limitations
 
 | Limitation | Workaround |
 |------------|-----------|
 | No `GroupBy` | Use raw SQL (`ExecSQL`) |
 | No `Join` | Use embedded `Record` fields |
-| No `Select` projection | Use `FieldSubset` on template |
-| No `Count()`, `First()` | Use `conn.QueryCount()`, `conn.QueryFirst()` |
 | No async | Async planned for a future release |
 
-### 9.9 Mixing LINQ with QueryTerm
+### 9.11 Mixing LINQ with QueryTerm
 
 ```csharp
 OrmQueryable<Product> orm = (OrmQueryable<Product>)conn.Query<Product>()
@@ -1411,7 +1468,7 @@ foreach (Shape s in results)
 
 ---
 
-## 17. Optimistic Locking
+### 17.1 Optimistic Locking
 
 `RecordLock.UpdateOption` controls what happens when another process has modified the row:
 
@@ -1429,6 +1486,23 @@ product.Update(RecordLock.UpdateOption.ReleaseLock);
 product.Update(RecordLock.UpdateOption.RetainLock);
 ```
 
+### 17.2 Pessimistic Locking (ReadForUpdate)
+
+Acquires a row-level update lock (SQL Server `UPDLOCK`, PostgreSQL `FOR UPDATE`) within a transaction to block other writers until commit.
+
+```csharp
+using var tx = conn.BeginTransaction();
+
+var product = new Product(conn);
+product.ID.SetValue(42);
+conn.ReadForUpdate(product, null); // Blocks other sessions
+
+product.Price.SetValue(20.00m);
+product.Update();
+
+conn.CommitTransaction(tx); // Lock released
+```
+
 Handle lock conflicts:
 
 ```csharp
@@ -1473,28 +1547,42 @@ foreach (Product p in conn.Query<Product>().Where(p => p.InStock == true))
 
 ## 19. Raw SQL and Stored Procedures
 
-### 19.1 ExecSQL
+### 19.1 ExecSQL (Direct Results)
 
-```csharp
-// Returns DataTable:
-DataTable table = conn.ExecSQL(
-    "SELECT Name, SUM(Qty) AS Total FROM OrderLines GROUP BY Name",
-    null);
+Executes raw SQL and returns a `ReaderBase` for manual iteration.
 
-foreach (DataRow row in table.Rows)
-    Console.WriteLine($"{row["Name"]} — {row["Total"]}");
+```csharp
+using var reader = conn.ExecSQL("SELECT COUNT(*) FROM Products");
+if (reader.Read())
+{
+    int count = (int)reader.ColumnValue(0);
+}
 ```
 
-### 19.2 Stored Procedures
+### 19.2 ExecSQL (Typed Mapping)
+
+Maps raw SQL results directly to `Record` instances using a template.
 
 ```csharp
-var parameters = new Dictionary<string, object>
+var template = new Product(conn);
+var results  = conn.ExecSQL(template, "SELECT * FROM Products WHERE Price > 100");
+
+foreach (Product p in results)
 {
-    ["@CategoryId"] = 5,
-    ["@MaxPrice"]   = 100m
-};
+    Console.WriteLine(p.Name.GetValue());
+}
+```
+
+### 19.3 Stored Procedures
+
+Executes a command set to `CommandType.StoredProcedure`.
 
-DataTable result = conn.ExecStoredProcedure("usp_GetProductsByCategory", parameters);
+```csharp
+var pCategoryId = new Record.SPParameter { Name = "CategoryId", Value = 5 };
+var pMaxPrice   = new Record.SPParameter { Name = "MaxPrice",   Value = 100m };
+
+var template = new Product(conn);
+var results  = conn.ExecStoredProcedure(template, "GetProductsByCategory", 0, 0, pCategoryId, pMaxPrice);
 ```
 
 ---

src/ActiveForge.MongoDB/Internal/MongoQueryTranslator.cs

@@ -108,9 +108,7 @@ private static FilterDefinition<BsonDocument> TranslateLeaf(
                 GreaterOrEqualTerm _ => Builders<BsonDocument>.Filter.Gte(fieldName, MongoMapper.ClrToBson(value)),
                 LessThanTerm       _ => Builders<BsonDocument>.Filter.Lt(fieldName, MongoMapper.ClrToBson(value)),
                 LessOrEqualTerm    _ => Builders<BsonDocument>.Filter.Lte(fieldName, MongoMapper.ClrToBson(value)),
-                LikeTerm           _ => Builders<BsonDocument>.Filter.Regex(fieldName,
-                                            new BsonRegularExpression(
-                                                System.Text.RegularExpressions.Regex.Escape(value?.ToString() ?? ""), "i")),
+                LikeTerm           _ => TranslateLike(fieldName, value?.ToString() ?? ""),
                 EqualTerm          _ => Builders<BsonDocument>.Filter.Eq(fieldName, MongoMapper.ClrToBson(value)),
                 _                    => Builders<BsonDocument>.Filter.Eq(fieldName, MongoMapper.ClrToBson(value)),
             };
@@ -124,6 +122,21 @@ private static FilterDefinition<BsonDocument> TranslateIn(string fieldName, ILis
             return Builders<BsonDocument>.Filter.In(fieldName, bsonValues);
         }
 
+        private static FilterDefinition<BsonDocument> TranslateLike(string fieldName, string pattern)
+        {
+            // Convert SQL LIKE pattern (%) to Regex pattern (.*)
+            // SQL LIKE matches the whole string.
+            // Note: Regex.Escape does NOT escape % or _, which are SQL wildcards.
+            string regex = System.Text.RegularExpressions.Regex.Escape(pattern)
+                .Replace("%", ".*")
+                .Replace("_", ".");
+            
+            // Anchors for full string match
+            regex = "^" + regex + "$";
+
+            return Builders<BsonDocument>.Filter.Regex(fieldName, new BsonRegularExpression(regex, "i"));
+        }
+
         // ── Sort translation ──────────────────────────────────────────────────────────
 
         public static SortDefinition<BsonDocument>? TranslateSort(SortOrder? sortOrder, Record obj,

src/ActiveForge.PostgreSQL/PostgreSQLConnection.cs

@@ -125,6 +125,40 @@ protected override string PopulateIdentity(Record obj, RecordBinding binding, Co
             return id;
         }
 
+        protected override string GetReadForUpdateSQL(Record obj, RecordBinding binding, List<FieldBinding> fieldBindingSubset, FieldSubset fieldSubset)
+        {
+            var fields   = new System.Text.StringBuilder();
+            string criteria = "";
+            string joins  = GetJoinSQL(binding, fieldSubset, true);
+
+            foreach (var fb in fieldBindingSubset)
+            {
+                var tfi  = fb.Info;
+                var node = fb.MapNode;
+                if (node == null) continue;
+
+                if (tfi.IsInPK && binding.UseAsPK(tfi) && binding.UpdateTableAliases.Contains(node.Alias))
+                {
+                    if (criteria.Length > 0) criteria += " AND ";
+                    if (node.Alias.Length > 0)
+                        criteria += node.Alias + GetSourceNameSeparator();
+                    criteria += QuoteName(tfi.TargetName) + "=" + GetParameterMark() + tfi.TargetName;
+                }
+                else
+                {
+                    if (fields.Length > 0) fields.Append(',');
+                    if (node.Alias.Length > 0)
+                        fields.Append(node.Alias).Append(GetSourceNameSeparator());
+                    fields.Append(QuoteName(tfi.TargetName));
+                    if (fb.Alias.Length > 0)
+                        fields.Append(' ').Append(fb.Alias);
+                }
+            }
+
+            if (fields.Length == 0) fields.Append('*');
+            return $"SELECT {fields} FROM {ResolveFullyQualifiedName(binding.SourceName, binding.Function)} {binding.GetRootAlias()}{joins} WHERE {criteria} FOR UPDATE";
+        }
+
         // ── Schema introspection ──────────────────────────────────────────────────────
 
         /// <summary>

src/ActiveForge/DBDataConnection.cs

@@ -1440,7 +1440,7 @@ protected string GetReadSQL(Record obj, RecordBinding binding, List<FieldBinding
             return $"SELECT {fields} FROM {ResolveFullyQualifiedName(binding.SourceName, binding.Function)} {binding.GetRootAlias()}{joins} WHERE {criteria}";
         }
 
-        protected string GetReadForUpdateSQL(Record obj, RecordBinding binding, List<FieldBinding> fieldBindingSubset, FieldSubset fieldSubset)
+        protected virtual string GetReadForUpdateSQL(Record obj, RecordBinding binding, List<FieldBinding> fieldBindingSubset, FieldSubset fieldSubset)
         {
             var fields   = new StringBuilder();
             string criteria = "";