Adapter Toolkit
Relevant source files
The following files were used as context for generating this wiki page:
The Adapter Toolkit (@better-tables/adapters-toolkit) is an ORM-agnostic library containing shared primitives, data structures, and logic for building database adapters within the Better Tables ecosystem. It serves as the foundational machinery that allows different data providers—such as Drizzle, Prisma, or custom HTTP backends—to translate high-level table definitions and UI states into provider-specific queries and responses.
Sources: CLAUDE.md:14, plans/039-documentation-truth.md:179-183
Architecture and Core Components
The toolkit is designed to provide a consistent interface for adapter authors while abstracting away the common complexities of data transformation, relationship resolution, and filter routing. It defines a set of ports and utilities that every adapter uses to fulfill the TableAdapter contract.
Core Primitives
The following table summarizes the primary components exported by the toolkit:
| Component | Description |
|---|---|
| FilterRouter | Manages the classification and dispatching of UI filters to specific predicate emitters. |
| PrimaryTableResolver | Handles the resolution of the main database table for a given query, including schema-level suggestions. |
| DataTransformer | Handles re-nesting flat database rows into objects based on relationship paths. |
| PredicateEmitter | An interface for translating individual filter operators into provider-specific query fragments. |
| SchemaIntrospectionPort | Defines standard interfaces for accessing schema metadata, models, and relationships. |
| Levenshtein Utils | Provides fuzzy-matching logic for "did you mean" suggestions when field paths are invalid. |
Sources: plans/039-documentation-truth.md:180-182, plans/061-prisma-adapter-full-parity.md:46-51
Adapter Implementation Flow
The toolkit orchestrates the flow of data from the UI to the database. The following diagram illustrates how toolkit components interact when a data request is processed:
The diagram shows the transformation of a request through filtering logic, query generation aided by schema introspection, and the final re-nesting of results via the DataTransformer.
Sources: CLAUDE.md:21-24, plans/008-prisma-adapter-spike.md:45-51
Implementation Details
Filter Routing and Predicates
Adapters utilize the FilterRouter to process incoming FilterState or FilterGroupNode objects. The router dispatches these to a PredicateEmitter, which must implement specific translations for operator families (Text, Number, Date, Boolean, etc.).
For instance, a Prisma-based adapter uses the toolkit to emit nested where fragments instead of standard SQL JOIN clauses.
Sources: plans/008-prisma-adapter-spike.md:47-49, plans/061-prisma-adapter-full-parity.md:120-128
Schema and Relationship Mapping
The toolkit provides standardized ports for schema introspection. This includes resolving "dotted" paths (e.g., profile.location) into relationship traversals.
The diagram illustrates the hierarchy of introspection interfaces used to map code-level identifiers to database entities.
Sources: plans/061-prisma-adapter-full-parity.md:50-51, plans/011-table-definition-dx-design.md:104-106
Data Transformation
Adapters that return flat row sets (like the Drizzle adapter) rely on the DataTransformer to perform re-nesting. This utility uses the relationship map to take a flat database result and nest related entities into their respective object paths.
Sources: plans/008-prisma-adapter-spike.md:50-51, plans/061-prisma-adapter-full-parity.md:48-49
Developer Experience (DX) and Usage
The Adapter Toolkit is intended for adapter authors, not for general application developers. It is consumed by packages like @better-tables/adapters-drizzle and the experimental @better-tables/adapters-prisma.
Conformance Testing
The toolkit co-evolves with a conformance suite (packages/adapters/conformance) that ensures all adapters—regardless of their underlying ORM—maintain identical observable semantics for pagination, filtering (including FilterGroupNode trees), and sorting.
Sources: plans/061-prisma-adapter-full-parity.md:106-118, plans/039-documentation-truth.md:183
Summary
The Adapter Toolkit provides the standardized "plumbing" required to integrate new data providers into Better Tables. By centralizing logic for filter routing, schema mapping, and data re-nesting, it ensures that features like relationship filtering and type-safe table definitions work consistently across Drizzle, Prisma, and custom implementations.
Sources: plans/009-dx-hygiene-sweep.md:162-164, plans/061-prisma-adapter-full-parity.md:45-55