ROADMAP.md

Arkormˣ Roadmap & Implementation Status

This document tracks all implemented and upcoming features for Arkormˣ.

Implemented Features

Adapter-First Baseline

• Model.setClient(...) and direct delegate-map bootstrapping are deprecated in the current next line.
• Model.setAdapter(...) with createPrismaDatabaseAdapter(...) or createKyselyAdapter(...) is the primary documented runtime path.
• Prisma compatibility remains supported and covered by CI through the Arkorm 2.x compatibility window.
• Prisma compatibility boundaries are now explicit: raw SQL predicates and adapter-owned relation batch loading stay compatibility-only gaps, while direct select/include translation remains supported.
• SQL-backed relation filters and aggregates now fail fast when a callback shape cannot be compiled into adapter specs instead of silently dropping to the generic in-memory path.
• Eager loading, relation filters, and relation aggregates now compile through Arkorm-owned relation specs end to end on the adapter-first path; the Kysely adapter consumes those specs for both unconstrained and constrained eager loading while Prisma compatibility keeps the generic eager-loader path.
• Earliest removal target for delegate-first runtime APIs is Arkorm 3.0 after migration docs, parity coverage, and adapter-first examples remain in place.

Core ORM

• Model base class with attribute casting, mutators, and serialization
• Attribute casting system with built-in and custom casts via Attribute({ get, set }) objects
• Query builder with fluent API
• Query ergonomics helpers (latest, oldest, limit, offset, forPage)
• Existence helpers (exists, doesntExist)
• Typed collection-based query results (get() returns ArkormCollection)
• LengthAwarePaginator support via paginate(perPage, page)
• Paginator support via simplePaginate(perPage, page)
• Pagination URL options (path, query, fragment, pageName) via URLDriver
• Framework-specific URL driver override via arkormx.config.*
• Collection integration (collect.js)
• Attribute visibility (hidden / visible / appends)
• Local scopes
• Soft deletes (withTrashed, onlyTrashed, restore, forceDelete)
• Global scopes
• Model lifecycle events (retrieved, creating, created, updating, updated, deleting, deleted, etc.)

Relationship Layer

• Familiar relationships (hasOne, hasMany, belongsTo, belongsToMany, hasOneThrough, hasManyThrough, morphOne, morphMany, morphToMany)
• Eager loading with constraints
• Fluent relationship query chaining (relation.where(...).orderBy(...).getResults())
• Relationship execution helpers (relation.get() and relation.first())

Adapter & Runtime

• Prisma delegate adapter/helper
• Database adapter layer (Model.setAdapter + PrismaAdapter)
• Prisma schema + migration workflow

Testing & Quality

• Comprehensive test suite
• Dedicated relationship coverage in both core and PostgreSQL test suites
• PostgreSQL integration test suite (real DB)
• CI PostgreSQL service integration tests
• Publish pipeline PostgreSQL integration gate
• TypeScript strict mode compatibility

Upcoming / Planned Features

• Global scopes
• Transaction support
• Event hooks (retrieved, creating, updating, deleting, etc.)
• CLI tooling for model/resource generation/runnging migrations and seeders
• Improved error handling and messages
• Documentation site
• More advanced relationship constraints
• Performance optimizations
• Class based event listeners via dispatchesEvents Model property
• Callback-based event listeners via booted and boot Model methods and Model.event() method
• Quiet mode for suppressing events and global scopes via Model.withoutEvents() and saveQuietly(), deleteQuietly(), restoreQuietly(), etc. methods.
• Model comparison operators (is, isNot) and identity checks (isSame, isNotSame)

Eloquent Parity (Phased)

Eloquent features a broad list of methods that make it a powerful ORM. For Arkormˣ, the most relevant methods are those that map cleanly to our current Model -> QueryBuilder -> delegate architecture and keep adapter portability, we have prioritized these for implementation.

Phase 1 — High-impact, low-risk query ergonomics

• latest(column = 'createdAt') (alias for orderBy({ column: 'desc' }))
• oldest(column = 'createdAt') (alias for orderBy({ column: 'asc' }))
• limit(value) (alias for take(value))
• offset(value) (alias for skip(value))
• forPage(page, perPage) (page helper over skip/take)
• exists() (fast existence check via constrained findFirst)
• doesntExist() (negation of exists())

Phase 2 — Core filtering parity for day-to-day usage

• orWhere(...)
• whereNot(...) / orWhereNot(...)
• whereNull(column) / whereNotNull(column)
• whereBetween(column, [min, max])
• whereDate/whereMonth/whereYear (initial date helpers)
• whereKeyNot(key, value)
• firstWhere(column, operator?, value?)
• orWhereIn(...) / whereNotIn(...) / orWhereNotIn(...)

Phase 3 — Read helpers and utility shortcuts

• findOr(id, callback)
• value(column) (first row column value)
• valueOrFail(column)
• pluck(column, key?)
• inRandomOrder()
• reorder(column?, direction?)
• when(value, callback, default?) / unless(value, callback, default?)
• tap(callback) / pipe(callback)

Phase 4 — Aggregates and advanced querying

• min(column)
• max(column)
• sum(column)
• avg(column)
• whereRaw(...) / orWhereRaw(...) (adapter-gated)
• existsOr(callback) / doesntExistOr(callback)

Phase 4.5 — Insert and upsert write parity

• insert(values)
• insertOrIgnore(values)
• insertGetId(values, sequence?)
• insertUsing(columns, query)
• insertOrIgnoreUsing(columns, query)
• updateFrom(values)
• updateOrInsert(attributes, values)
• upsert(values, uniqueBy, update?)

Phase 5 — Relationship existence/query parity

• has(...) / orHas(...)
• doesntHave(...) / orDoesntHave(...)
• whereHas(...) / orWhereHas(...)
• whereDoesntHave(...) / orWhereDoesntHave(...)
• withCount(...)
• withExists(...)
• withSum(...) / withAvg(...) / withMin(...) / withMax(...)

Phase 6 — Database migration, seeding and factory helpers

• Factory definitions and helpers
• Seeder classes and execution helpers
• Migration file generation and schema builder

Phase 7 — Final Transition

• Remove delegate-first runtime APIs from the primary Model surface
• Remove Model.setClient(...) and direct delegate-map bootstrapping from the supported runtime path
• Replace Model.getDelegate() usage in runtime code with adapter-owned execution paths only
• Remove Prisma-shaped generic constraints from core model and query types
• Replace PrismaDelegateLike-anchored ModelStatic, QueryBuilder, and helper typing with adapter-native types
• Move transaction APIs to adapter-first contracts without requiring Prisma client callback types in core runtime APIs
• Eliminate remaining runtime fallbacks that still depend on delegate-shaped behavior for relation execution
• Complete adapter-level relation load execution for the Kysely path
• Close the remaining Prisma compatibility adapter feature gaps or explicitly isolate them to compatibility-only behavior
• Ensure eager loading, relation aggregates, and relation filters run through Arkorm-owned specs end to end
• Remove or rename delegate-oriented metadata and internals where table or adapter terminology is now the real runtime contract
• Update docs, examples, and upgrade guides to mark the adapter-first migration as complete rather than transitional
• Add parity and regression coverage proving adapter-first behavior without delegate-only runtime APIs
• Define and execute the final removal checklist for merging next into main as the completed adapter-first baseline

Success criteria:

• Arkorm no longer depends on Prisma delegate semantics in its core runtime or public typing model
• adapter-first execution is the only primary runtime path for new code, including relation execution fallback paths
• Prisma support remains only as a compatibility adapter, not as a shaping abstraction for core internals
• next can merge into main as the fully completed adapter-first architecture

Final merge checklist status:

• docs and examples teach adapter-first as the default 2.x runtime path
• delegate-first runtime APIs are isolated to compatibility-only surfaces with explicit deprecation/removal guidance
• neutral query-schema typing is the primary core type surface
• relation execution and eager loading no longer depend on delegate-only runtime APIs
• parity/regression coverage exists for both Prisma compatibility and Kysely adapter-backed execution
• repo state is currently clean and the latest pnpm test:all run passed

Out of scope

Lower priority until global scopes, events, and transactions are stable:

• Chunking/lazy/cursor APIs (chunk, lazy, cursorPaginate, etc.)
• SQL-specific join family (join*, crossJoin*, lateral joins)
• Macro system parity (macro, mixin, flushMacros)

Status Legend

• Implemented
• Planned / Not yet implemented

---

This document will be updated as features are implemented.