|
1 | | -# <img src="https://github.com/CodeShayk/ActiveForge/blob/master/images/logo-1.png" alt="logo" style="width:80px;"/> ActiveForge ORM v1.0.0 |
| 1 | +# <img src="https://github.com/CodeShayk/ActiveForge/blob/master/images/Logo-5.png" alt="logo" style="width:40px;"/> ActiveForge ORM v1.0.0 |
2 | 2 | [](https://github.com/CodeShayk/ActiveForge/blob/master/LICENSE.md) |
3 | 3 | [](https://github.com/CodeShayk/ActiveForge/releases/latest) |
4 | 4 | [](https://github.com/CodeShayk/ActiveForge/actions/workflows/master-build.yml) |
5 | 5 | [](https://github.com/CodeShayk/ActiveForge/actions/workflows/master-codeql.yml) |
6 | 6 |
|
7 | | -A lightweight, Active Record-style ORM for .NET 8, with first-class support for SQL Server, PostgreSQL, and MongoDB. |
| 7 | +A lightweight, Active Record-style ORM for .NET 8 +, with first-class support for SQL Server, PostgreSQL, and MongoDB. |
8 | 8 |
|
9 | 9 | --- |
10 | 10 |
|
11 | 11 | ## Packages |
12 | 12 |
|
13 | 13 | | Package | Description | |
14 | 14 | |---------|-------------| |
15 | | -| `ActiveForge` | Core — entities, fields, predicates, LINQ, transactions, adapters, Castle proxy factory | |
16 | | -| `ActiveForge.SqlServer` | SQL Server provider — `SqlServerConnection`, ADO.NET adapters, `SqlServerUnitOfWork`, DI extensions | |
17 | | -| `ActiveForge.PostgreSQL` | PostgreSQL provider — `PostgreSQLConnection`, Npgsql adapters, `PostgreSQLUnitOfWork`, DI extensions | |
18 | | -| `ActiveForge.MongoDB` | MongoDB provider — `MongoDataConnection`, BSON mapping, `MongoUnitOfWork`, DI extensions | |
19 | | -| `ActiveForge.SQLite` | SQLite provider — `SQLiteConnection`, Microsoft.Data.Sqlite adapters, `SQLiteUnitOfWork`, DI extensions | |
| 15 | +| [](https://badge.fury.io/nu/ActiveForge.Core) | Core — entities, fields, predicates, LINQ, transactions, adapters, Castle proxy factory | |
| 16 | +| [](https://badge.fury.io/nu/ActiveForge.SqlServer) | SQL Server provider — `SqlServerConnection`, ADO.NET adapters, `SqlServerUnitOfWork`, DI extensions | |
| 17 | +| [](https://badge.fury.io/nu/ActiveForge.PostgreSQL)| PostgreSQL provider — `PostgreSQLConnection`, Npgsql adapters, `PostgreSQLUnitOfWork`, DI extensions | |
| 18 | +| [](https://badge.fury.io/nu/ActiveForge.MongoDB)| MongoDB provider — `MongoDataConnection`, BSON mapping, `MongoUnitOfWork`, DI extensions | |
| 19 | +| [](https://badge.fury.io/nu/ActiveForge.SQLite)| SQLite provider — `SQLiteConnection`, Microsoft.Data.Sqlite adapters, `SQLiteUnitOfWork`, DI extensions | |
20 | 20 |
|
21 | 21 | All connection types live in the `ActiveForge` namespace, so a single `using ActiveForge;` is sufficient regardless of the provider chosen. |
22 | 22 |
|
23 | 23 | --- |
24 | 24 |
|
| 25 | + |
25 | 26 | ## Features |
26 | 27 |
|
| 28 | +ActiveForge streamlines data-centric development with a cohesive approach to entities, queries, and data management. |
| 29 | + |
27 | 30 | ### 🗂 Entities & Mapping |
28 | | -- **Active Record pattern** — entities carry both data and persistence behaviour; no separate repository class required |
29 | | -- **Type-safe field wrappers** — `TString`, `TInt`, `TDecimal`, `TPrimaryKey`, `TForeignKey`, and 25+ more; each tracks null/loaded state and supports implicit conversion |
30 | | -- **Polymorphic mapping** — map abstract base types to concrete subtypes via `BaseFactory` |
31 | | -- **Custom field mappers** — implement `IDBFieldMapper` for non-standard type conversions |
32 | | -- **Field encryption** — transparent encrypt/decrypt via `[Encrypted]` attribute |
| 31 | + |
| 32 | +- **Active Record pattern** |
| 33 | + Entities contain both state and persistence logic, removing the need for external repositories. |
| 34 | +- **Type-safe fields** |
| 35 | + Provides wrappers for types (string, int, decimal, keys, etc.), tracking nullability and state, and handling conversion automatically. |
| 36 | +- **Polymorphic mapping** |
| 37 | + Maps base types to concrete subtypes at runtime. |
| 38 | +- **Custom field mappers** |
| 39 | + Easily support non-standard type conversions. |
| 40 | +- **Field encryption** |
| 41 | + Simple attribute-based encryption/decryption for sensitive data. |
33 | 42 |
|
34 | 43 | ### 🔍 Querying |
35 | | -- **Composable query predicates** — `EqualTerm`, `ContainsTerm`, `InTerm`, `GreaterThanTerm`, `LessThanTerm`, `LessOrEqualTerm`, `GreaterOrEqualTerm`, `IsNullTerm`, `LikeTerm`, composed with `&`, `|`, `!` |
36 | | -- **LINQ query support** — `conn.Query<T>().Where(...).OrderBy(...).Take(...).Skip(...)` translated to native ORM predicates |
37 | | -- **Pagination** — `QueryPage` with `StartRecord`, `PageSize`, `IsMoreData`, `TotalRowCount` |
38 | | -- **Lazy streaming** — `LazyQueryAll<T>` streams rows without buffering the full result set |
39 | | -- **Field subsets** — partial SELECTs and partial UPDATEs via `FieldSubset` |
40 | 44 |
|
41 | | -### 💾 Data Management |
42 | | -- **Transactions** — manual nested transactions via `BeginTransaction` / `CommitTransaction` / `RollbackTransaction` |
43 | | -- **Unit of Work** — `IUnitOfWork`, `BaseUnitOfWork`, provider-specific implementations (`SqlServerUnitOfWork`, `PostgreSQLUnitOfWork`, `MongoUnitOfWork`, `SQLiteUnitOfWork`), `With.Transaction`, `[Transaction]` attribute, Castle DynamicProxy interceptor. `[Transaction]` wraps a service method in an `IUnitOfWork` transaction; the UoW opens the connection before the first `CreateTransaction()` call and closes it after the outermost commit or rollback. |
44 | | -- **Connection-level lifecycle** — set `conn.UnitOfWork = uow` once; every write operation (`Insert`, `Update`, `Delete`, `ProcessActionQueue`, `ExecStoredProcedure`) automatically opens the connection, begins a transaction, commits, and closes — no proxy required. |
45 | | -- **Action queue** — batch operations via `QueueForInsert` / `QueueForUpdate` / `QueueForDelete` → `ProcessActionQueue` |
| 45 | +- **Composable predicates** |
| 46 | + Build queries with terms for equality, containment, ranges, null checks, and pattern matching; combine them with logical operators. |
| 47 | +- **LINQ support** |
| 48 | + Write queries using familiar C# syntax, auto-translated to efficient ORM operations. |
| 49 | +- **Pagination** |
| 50 | + Built-in paging with metadata for efficient handling of large datasets. |
| 51 | +- **Lazy streaming** |
| 52 | + Stream results row-by-row for memory efficiency. |
| 53 | +- **Field subsets** |
| 54 | + Load or update only the fields you need. |
46 | 55 |
|
47 | | -### 🌐 DI & Service Proxy Integration |
48 | | -- **Auto-scan registration** — `AddActiveForgeSqlServer(...).AddServices(assembly)` discovers all `IService` implementations and registers them as interface-proxied scoped services in one call. `IService` marker — implement on any service class for automatic discovery and proxy registration. `IActiveForgeBuilder` — fluent builder returned by all `AddActiveForge*` methods; chain `.AddServices()`, `.AddService<I, T>()` for granular control. |
| 56 | +### 💾 Data Management |
49 | 57 |
|
| 58 | +- **Transactions** |
| 59 | + Explicit and nested transaction support; control scope via code or attributes. |
| 60 | +- **Unit of Work** |
| 61 | + Integrated pattern for grouping multiple changes; supports both code-based and attribute-based usage. |
| 62 | +- **Connection lifecycle** |
| 63 | + Connections and transactions are managed automatically on every write, ensuring reliability. |
| 64 | +- **Batch operations** |
| 65 | + Queue up changes and execute them in bulk to reduce database round-trips. |
| 66 | + |
| 67 | +### 🌐 Dependency Injection & Service Proxy |
| 68 | + |
| 69 | +- **Auto-discovery & registration** |
| 70 | + Services marked with a simple interface are discovered and registered automatically. |
| 71 | +- **Fluent builder API** |
| 72 | + Register all or selected services with fine-grained control. |
| 73 | +- **Seamless DI integration** |
| 74 | + Simplifies service composition, testing, and enables proxy/interceptor scenarios. |
50 | 75 | --- |
51 | 76 |
|
52 | 77 | ## Requirements |
@@ -286,7 +311,7 @@ With.Transaction(uow, () => |
286 | 311 | | [LINQ Querying](docs/linq-querying.md) | `conn.Query<T>()` LINQ support | |
287 | 312 | | [Field Subsets](docs/field-subsets.md) | Partial fetches and partial updates | |
288 | 313 | | [Advanced](docs/advanced.md) | Encryption, custom mappers, polymorphism | |
289 | | -| [**Wiki**](docs/wiki.md) | Comprehensive reference — all concepts with examples | |
| 314 | +| [**Wiki**](https://github.com/CodeShayk/ActiveForge/wiki) | Comprehensive reference — all concepts with examples | |
290 | 315 |
|
291 | 316 | --- |
292 | 317 |
|
|
0 commit comments