supertypes

Description:

supertypes

Supertypes is a library for generating complex records. This library has been heavily inspired by
TypeScript's Utility Types.
Installation #
Add supertypes and it's companion generator to your pubspec.yaml. The easiest way to do this is to use the command
line:
For Dart projects:
dart pub add supertypes dev:supertypes_generator dev:build_runner
copied to clipboard
For Flutter projects:
flutter pub add supertypes dev:supertypes_generator dev:build_runner
copied to clipboard
To generate the types, run build_runner:
For Dart projects:
dart run build_runner build # Build once
dart run build_runner watch # Build continuously
copied to clipboard
For Flutter projects:
flutter pub run build_runner build # Build once
flutter pub run build_runner watch # Build continuously
copied to clipboard
Usage #
Every file containing a supertype must have the following:
It should start with a part directive.
import 'package:supertypes/supertypes.dart';

part 'example.supertypes.dart';
copied to clipboard
It should contain a typedef with the name of the supertype, prefixed with $ for public generated records, or _$
for private generated records.
// Generates a public record called `Example`
@superType
typedef $Example = ();

// Generates a private record called `_Example`
@superType
typedef _$Example = ();
copied to clipboard
Index #

Modifier types

Partial
WithPartial
Required
WithRequired
Omit

Omitting positional fields


Pick

Picking positional fields


Merge


Using Supertypes within another Supertype

Modifier types #
Modifier types are types that take one or more types and return a new type.
Partial #
The Partial modifier type takes a type and makes all of it's fields optional.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String firstName,
String lastName,
int age,
});

// We want to make all the field nullable to support partial updates
@superType
typedef $UpdatePerson = Partial<Person>;

// This generates:
typedef UpdatePerson = ({
String? firstName,
String? lastName,
int? age,
});
copied to clipboard
WithPartial #
The WithPartial modifier type takes a type and a list of fields to make optional.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
int id,
String firstName,
String lastName,
int age,
});

// We want to make `id` nullable
@superType
typedef $PersonWithNullableId = WithPartial<Person, ({Partial id})>;

// This generates:

/// Generate for [$PersonWithNullableId]
typedef PersonWithNullableId = ({
int? id,
String firstName,
String lastName,
int age,
});
copied to clipboard
Required #
The Required modifier type takes a type and makes all of it's fields required.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

// Let's say we have a person type with `lastName` nullable,
// and we can't update the type easily.
// We can instead create a new type with all fields required.
typedef Person = ({
String firstName,
String? lastName,
int age,
});

// We want to make all the field nullable to support partial updates
@superType
typedef $CreatePerson = Required<Person>;

// This generates:
typedef CreatePerson = ({
String firstName,
String lastName,
int age,
});
copied to clipboard
WithRequired #
The WithRequired modifier type takes a type and a list of fields to make required.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String firstName,
String? lastName,
int age,
});

// We want to make `lastName` required
@superType
typedef $PersonWithRequiredLastName = WithRequired<Person, ({Required lastName})>;

// This generates:
typedef PersonWithRequiredLastName = ({
String firstName,
String lastName,
int age,
});
copied to clipboard
Omit #
The Omit modifier type takes a type and a list of fields to omit from the type.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String firstName,
String lastName,
int age,
});

// We want to remove age from the type
@superType
typedef $PersonWithoutAge = Omit<Person, ({Omit age})>;

// This generates:

/// Generate for [$PersonWithoutAge]
typedef PersonWithoutAge = ({
String firstName,
String lastName,
});
copied to clipboard
Omitting positional fields
It's possible to also omit a positional field. For example:
typedef Person = (String name, int age);

// We want to remove the x field from the type
@superType
typedef $Age = Omit<Person, (Omit,)>; // This removes the first positional field

// This removes the second positional field.
// We use `Pick` as a placeholder for the first positional field.
@superType
typedef $Name = Omit<Person, (Pick, Omit)>;

// This generates:

/// Generate for [$Age]
typedef Age = (int,);

/// Generate for [$Name]
typedef Name = (String,);
copied to clipboard
Pick #
The Pick modifier type takes a type and a list of fields to pick from the type and ignores the rest.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String firstName,
String lastName,
int age,
});

// We want to remove age from the type
@superType
typedef $PersonWithoutAge = Pick<Person, ({Pick firstName, Pick lastName})>;

// This generates:

/// Generate for [$PersonWithoutAge]
typedef PersonWithoutAge = ({
String firstName,
String lastName,
});
copied to clipboard
You can also apply a modifier type to the fields you pick:
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String? firstName,
String? lastName,
int age,
});

// Let's make age nullable and and pick firstName as a required field
@superType
typedef $PersonWithNullableAge = Pick<Person, ({Required firstName, Partial age})>;

// This generates:

/// Generate for [$PersonWithNullableAge]
typedef PersonWithNullableAge = ({
int? age,
String firstName,
});
copied to clipboard
Picking positional fields
It's possible to also pick a positional field. For example:
typedef Person = (String name, int age);

// We want to remove the x field from the type
@superType
typedef $Name = Pick<Person, (Pick,)>; // This removes the first positional field

// This removes the second positional field.
// We use `Pick` as a placeholder for the first positional field.
@superType
typedef $Age = Pick<Person, (Omit, Pick)>;

// This generates:

/// Generate for [$Name]
typedef Name = (String,);

/// Generate for [$Age]
typedef Age = (int,);
copied to clipboard
Merge #
The Merge modifier type takes two types and merges them into one type.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String firstName,
String lastName,
int age,
});

typedef Address = ({
String street,
String city,
String country,
});

// We want to merge the two types
@superType
typedef $PersonWithAddress = Merge<Person, Address>;

// This generates:

/// Generate for [$PersonWithAddress]
typedef PersonWithAddress = ({
String firstName,
String lastName,
int age,
String street,
String city,
String country,
});
copied to clipboard
Using Supertypes within another Supertype #
Supertypes can be used within other supertypes. This is useful for creating complex types that can be reused.
To use a supertype within another supertype, simply use the original type you prefixed with $ or _$.
import 'package:supertypes/supertypes.dart';

part 'person.supertypes.dart';

typedef Person = ({
String firstName,
String lastName,
int age,
});

@superType
typedef $CreatePerson = Required<Person>;

@superType
typedef $UpdatePerson = Partial<Person>;

@superType
typedef $PersonOperation = ({
$CreatePerson create,
$UpdatePerson update,
});

// This generates:

/// Generate for [$CreatePerson]
typedef CreatePerson = ({
int age,
String firstName,
String lastName,
});

/// Generate for [$UpdatePerson]
typedef UpdatePerson = ({
int? age,
String? firstName,
String? lastName,
});

/// Generate for [$PersonOperation]
typedef PersonOperation = ({
({
int age,
String firstName,
String lastName,
}) create,
({
int? age,
String? firstName,
String? lastName,
}) update,
});
copied to clipboard
Features: #

More modifier types

✅ Partial - Make all fields nullable
✅ Required - Make all fields required
✅ Omit - Omit fields from a type
✅ Pick - Pick fields from a type
✅ Merge - Merge two types
✅ WithRequired - Make certain fields required
✅ WithPartial - Make certain fields optional
Awaited - Unwrap a Future type recursively


JSON serialization and deserialization for records

Generate fromJson top level function
Generate toJson extension method on the record


Support for using classes in the supertype records by extracting their fields