Generator: resolve a field's type from the type's own schema, and retire @AckField(schema:)

Aperta
#185 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
dart

Direzione di ricerca

Start with _namedSchemaForType in packages/ack_generator/lib/src/analyzer/class_model_graph_builder.dart and follow resolveNamed in inference/schema_inference.dart. Trace how named types are resolved inside collections, then review #173 and the open questions about generic schemas, extension types, global registration, and @AckField(schema:) deprecation. Done means the design and generation-time behavior are specified for owned, generic, and externally owned types.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement

Problem

A class-first model can only use field types the generator already knows: JSON primitives, collections, @Schemable classes, and generated schema-first models. Any other type stops generation:

MetricDto.activate uses unsupported JamInvoke<Object?>; use a concrete type with a static class-first schema contract.

The only way through today is @AckField(schema: fn) on every field of that type, where fn is a top-level, zero-parameter function. Building this against #184's branch (b31d4b4) showed three costs:

  • Repetition. The annotation is written on each field, in every model that uses the type.
  • It replaces the whole field schema. On a List<T> field it does not apply per item, so a list needs its own schema function.
  • Generic types lose their type argument. @AckField(schema: invokeSchema<CompletionAction>) is accepted, but the generator emits invokeSchema() without the type argument (class_model_graph_builder.dart, _escapeHatchExpression, which uses only function.name). The analyzer reports nothing and parse fails at runtime. Today this forces one non-generic wrapper per type argument.

Proposal

Let a type say what its schema is, once, and have the generator resolve it wherever the type appears: as a field, as a list item, as a map value. Nothing is registered on the models that use it.

Types you own: a static schema on the type.

final class Slot {
  const Slot(this.id);
  final String id;

  static final schema = Ack.string().codec(decode: Slot.new, encode: (s) => s.id);
}

@Schemable()
final class SectionDto({
  required final Slot header,          // resolves to Slot.schema
  required final List<Slot> children,  // resolves per item
}) with _$SectionDtoAck;

This is the same name #173 gives schema-first models (Model.schema), so one convention covers generated and hand-written types. It should work for a class and for an extension type (the lookup in _namedSchemaForType currently accepts only a ClassElement).

Generic types: the same name, as a static generic method. A static field cannot use the class's type parameter, so:

final class Invoke<A extends Object?> {
  static AckSchema<String, Invoke<A>> schema<A extends Object?>() => …;
}

A field Invoke<CompletionAction> toggle resolves to Invoke.schema<CompletionAction>(), with the type arguments rendered from the field's type.

Types you do not own: one global registration. A static member cannot be added to DateTime, Uri or a Flutter Color. For these, register a schema once for the whole package, not per model. Candidates: generator options in build.yaml mapping a type to a schema function, or a library-level annotation. This is the part of the closed #93 (SchemaProvider<T> with @Schemable(useProviders: …)) worth keeping, without the per-model registration.

Deprecating @AckField(schema:)

With type-owned schemas, @AckField(schema:) has two remaining uses:

  1. A custom type. Replaced by the proposal above.
  2. A built-in type with a special shape, for example a String that must be a calendar date. This can be expressed as a constraint annotation, or as a small value type with its own schema (an extension type on String).

If case 2 holds up, @AckField(schema:) can be deprecated in 2.0 and removed later. @AckField(description:) and the other options stay.

Where it goes

_namedSchemaForType in packages/ack_generator/lib/src/analyzer/class_model_graph_builder.dart already resolves two kinds of named types (a @Schemable class through its facade, a generated schema-first model through $ack.schema) and returns null otherwise, which becomes the "unsupported" error at inference/schema_inference.dart (resolveNamed(type) ?? unsupported(type)). The new cases belong there, so they also apply inside collections.

Open questions

  • Should the generator require the static schema to be typed AckSchema<_, Self> and report a mismatch at generation time? Today a mismatched @AckField(schema:) only fails at runtime through a cast in the generated bridge.
  • What happens when a type has both a static schema and a global registration: reject, or prefer the type's own?
  • The form of the global registration: build.yaml options or a library-level annotation.
  • x-transformed: true is added to every codec schema and cannot be turned off. Should a type-owned schema be able to opt out?

Related

  • #173: Model.schema shorthand for schema-first models.
  • #184: @Schemable with primary constructors, the branch this was tested against.
  • #93 (closed): SchemaProvider<T> with per-model useProviders.
Lingua principale
Dart
Stelle
64
Fork
3
Merge medio
17h 32m
PR unite (30g)
33

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di btwld/ack

Tutte le issue di btwld/ack

Issue simili

Altre issue su Dart

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.