Getting Started topic

Getting Started

basalt_codegen is a build_runner/source_gen generator that derives row mappers and write statements for your data classes from the annotations in package:basalt.

Dependencies

dev_dependencies:
  basalt_codegen:
  build_runner: ^2.4.0

Wire into build.yaml

The package ships a build.yaml that auto-applies to dependents. If you need an explicit entry:

targets:
  $default:
    builders:
      basalt_codegen|queryable:
        enabled: true

The builder is queryableBuilder — a SharedPartBuilder that registers QueryableGenerator, InsertableGenerator, and AsChangesetGenerator. Generated code lands in <file>.g.dart alongside your model classes.

Usage

Annotate your model classes and add a part directive:

import 'package:basalt/basalt.dart';
import 'schema.dart';

part 'user.g.dart';

@Queryable(Users.table)
@Insertable(Users.table)
class User {
  final int id;
  final String name;
  const User(this.id, this.name);
}

Run:

dart run build_runner build

What gets generated

Annotation	Generator	Output
@Queryable	QueryableGenerator	XQuery companion class — is the query (extends MappedQuery/FoldMappedQuery) and carries static fromRow, static const mapper and (for @HasMany) static fold
@Insertable	InsertableGenerator	toInsert() extension on the class + a multi-row toInsert() extension on Iterable of it (one batch INSERT)
@AsChangeset	AsChangesetGenerator	toUpdate() extension

For annotation semantics, field mapping, @Relation join behavior, and edge cases, see basalt Annotations & Codegen — this package implements that contract; the annotations themselves live in package:basalt.

Libraries

basalt_codegen

build_runner code generator for the Basalt Dart ORM. Wire it via build.yaml; it derives a RowMapper<T> for every @Queryable class and toInsert() / toUpdate() extensions for @Insertable / @AsChangeset classes.

Classes

AsChangesetGenerator

Emits a toUpdate() extension for each @AsChangeset data class.

InsertableGenerator

Emits a toInsert() extension for each @Insertable data class — on the class itself (single-row insert) and on Iterable of it (one multi-row batch INSERT). Independent of @Queryable, so a write-only DTO works on its own.

QueryableGenerator

Generates a ${Class}Query companion for each @Queryable class — the companion is the canonical query (extends MappedQuery/FoldMappedQuery) and carries the alias-parameterized static fromRow reader plus its RowMapper. @Relation fields drive nested joins with per-edge depth limits and path-based table aliases.

Functions

queryableBuilder(BuilderOptions options) → Builder

build_runner entry point (wired in build.yaml). Emits a shared part so the generated readers/mappers and toInsert()/toUpdate() extensions live in <file>.g.dart alongside the user's classes. A class can carry several of @Queryable/@Insertable/@AsChangeset; each generator contributes its own (non-overlapping) units to the same part.