How krile136/apexeloquent works
Project Type & Purpose
• ApexEloquent is an open-source Apex ORM framework for Salesforce, inspired by Laravel Eloquent.
• Its goal is to replace raw SOQL string concatenation with a fluent, typesafe query builder (Scribe), provide an execution layer (Eloquent) that maps results into IEntry objects, and enable database-free unit testing via MockEloquent/MockEntry.
File Structure Overview
• Top-level classes:
• Scribe.cls (+ metadata) – the fluent SOQL builder
• Eloquent.cls / IEloquent.cls – execution API for queries
• Entry abstractions (Entries folder) – IEntry, AbstractEntry, Entry, MockEntry
• Clauses modules:
– ConditionClauses (implement IConditionClause – where* methods)
– AggregateClauses (implement IAggregateClause – groupBy, having)
• FieldStructure.cls – holds metadata about SObjects/fields
• tests & mock modules (MockEloquent, MockEntry, unit tests)
• Deployment artifacts:
• manifest/package-empty.xml, manifest/uninstall.xml
• Makefile, GitHub Actions workflow (deploy.yml)
Main Architectural Components
A. Query Builder Layer
• Scribe API
• ConditionClauses & AggregateClauses (Strategy pattern)
• FieldStructure (metadata provider)
B. Execution Layer
• Eloquent (implements IEloquent)
• Transforms Scribe → SOQL string → Database.query → List<SObject>
• Maps SObjects → Entry instances (AbstractEntry → Entry)
C. Domain Model
• IEntry interface, AbstractEntry, Entry, MockEntry
• Provides get(), getName(), getParent(), getChildren(), getThrough()
D. Test Double Layer
• MockEloquent (implements IEloquent)
• MockEntry
• Enables in-memory “queries” and parent/child/through relationships without DML
E. External System
• Salesforce database & metadata (SObjects, fields)
• Database.query, DML operations
Component Interactions & Data Flow
1. Developer code calls Scribe.source(...) → builds a Scribe instance.
2. Scribe accumulates ConditionClause and AggregateClause objects.
3. Developer passes Scribe to Eloquent.get()/first()/getAggregate().
4. Eloquent invokes Scribe.toSoql(), executes Database.query().
5. Eloquent uses FieldStructure to map raw SObject records into Entry objects.
6. Entry exposes values via IEntry API; relationships fetched by nested Scribe builders.
7. In tests, developer injects MockEloquent; Scribe is bypassed and predetermined MockEntry trees are returned.
Key Architectural Patterns & Principles
• Fluent Interface (Scribe) for readable query composition
• Strategy Pattern for clause implementations (IConditionClause, IAggregateClause)
• Dependency Inversion / Interface-based design (IEloquent, IEntry) to allow mocking
• Separation of Concerns: builder vs. executor vs. domain model vs. test double
• Metadata abstraction via FieldStructure
Step-by-Step Approach
c. Inside Execution Layer, show FieldStructure feeding metadata to Eloquent and Entry.