ApexEloquent
A data-access OSS for Apex that separates query construction from query execution. The domain draws the blueprint of a query with Scribe; IEloquent takes care of running it.
Why ApexEloquent
Separating Query Construction From ExecutionQuery Delegation Pattern
The widely adopted Selector Pattern in Salesforce development has clear strengths: queries can be shared, and business logic fetches data via methods rather than embedding queries. But over long-term operation, every time someone wants "a slightly different query", a method or variable patch piles on, and that initial simplicity slowly erodes. On top of that, tests themselves require a database — you're stuck writing only integration tests.
ApexEloquent redesigns the Repository pattern for Apex, adopting the Query Delegation Pattern in which query "construction" and "execution" are kept separate. The domain layer draws the blueprint of a query with Scribe, hands it to IEloquent.get(scribe), and in production Eloquent issues the SOQL.
In tests, you just swap IEloquent for MockEloquent via DI, and you can write unit tests that don't go through the database. A framework that doesn't get in the way of long-term development.
ScribeIEloquentEloquent / MockEloquentCore Building Blocks
Three Core Pieces
Scribe
An immutable, typed method-chain query builder. SELECT / WHERE / sorting / aggregation / GROUP BY / HAVING all assemble through one API. Each method returns a new Scribe, so deriving a count query and a list query from the same conditions is natural.
IEloquent (Eloquent / MockEloquent)
The interface that receives a Scribe and executes SOQL. DML (insert / update / upsert / delete) is handled uniformly with bulk overloads. Production uses Eloquent, tests use MockEloquent, swapped via the Layered Constructor Pattern.
IEntry (Entry / MockEntry)
A unified wrapper that lets you read SObject and AggregateResult through the same get(field). MockEntry can also set non-writable fields freely — formula fields, rollups, parent relationships, auto-number.
Why This Design
ApexEloquent's Distinctive Design
Mock Non-Writable Fields, Parent-Child, and AggregateResult
Fields you can't normally write to — formula fields, rollups, parent relationships, auto-number — are set freely in mocks. Parent-child hierarchies and the result of aggregate queries are mocked through the same IEntry interface, consistently.
ORM and Mocking, Together
Many ORM libraries stop at query construction and leave DB-less testing to another library or a handwritten mock. ApexEloquent takes you from query construction all the way to fast, DB-less unit tests written against the built-in mocks — nonstop.
Read the MockEntry Deep Dive →Catch SELECT Omissions at Test Time
A real SObject fetched via SOQL throws immediately when you access a field that wasn't in the SELECT clause. But the common test pattern of injecting SObjects lets access to unfetched fields pass silently — unnoticed in unit tests, surfacing only in integration tests or in production. ApexEloquent remembers the SELECT clause of Scribe and, even with mocked injection, throws at unit-test time when an unfetched field is accessed.
Spy + failOn for Retry-Style Tests
Spy properties let you verify that records were created / updated / deleted correctly — all DB-less. The failOn methods let you raise errors at exactly the timing you intend, so you can verify catch blocks without polluting production code.
Read Data Access, DML, IEntry, Mock →Deep Dives
Digging into Motivations and Distinctive Features
Why ApexEloquent ended up in this shape, and how its distinctive features earn their keep — five documents go deep.
Query Delegation Pattern
Starting from the long-term operational challenges of the Selector Pattern, this article lays out the design philosophy of separating query construction (Scribe) from execution (IEloquent).
The Repository Pattern in Apex: Trial, Error, and Going Built-In
What happens when you write the Repository pattern naively in Apex, how it relates to Salesforce's official Selector Pattern, and why ApexEloquent provides a "built-in Repository" as IEloquent.
From Raw SOQL to a Chained-Method ORM in Apex
The cost we're paying in raw-SOQL-centric Apex development (readability / dynamic conditions / type safety / relations / testability), and how Scribe + IEloquent lighten that load — a migration primer with concrete examples.
MockEntry: How Apex Test Data Construction Becomes Possible
The two great difficulties of Apex testing — non-writable fields (formula / rollup / auto-number / relationship names) and building parent-child relationships — and how MockEntry's override map, dedicated factories, and aggregate-result mocks resolve them.
Catching Mock-Test False Positives: A Safety Net for SELECT Omissions
False positives of the "passes in tests, fails in production" variety — how ApexEloquent structurally closes that gap via Scribe coordination, demonstrated in four cases (primary object / parent relationship / child subquery / aggregate alias). A safety net unique to ApexEloquent.
Where It Sits in Apex Stem
Position in Apex Stem
ApexEloquent is the Data Access piece among the four OSS that make up Apex Stem. It comes into play in the Usecase layer of the Handler-Usecase Architecture whenever DB access is involved, and it carries the "Usecase unit test ↔ ApexEloquent" half of the test strategy.
- Handler-Usecase Architecture: the responsibility of the Usecase layer where ApexEloquent is called
- Layered Constructor Pattern: the design for DI'ing
IEloquentinto a Usecase - Test Strategy: Usecase unit tests centered on
MockEloquent - Apex Stem Introduction Guide: four steps with working code
Start with the Developer Guide
The developer guide walks through three usage paths — building queries with Scribe, fetching data and running DML, and working with relations — using real code. The API references can be cross-checked alongside.