withReferences method

ProcessedTableManager<$Database, $Table, $Dataclass, $FilterComposer, $OrderingComposer, $ComputedFieldComposer, $CreateCompanionCallback, $UpdateCompanionCallback, $DataclassWithReferences, $DataclassWithReferences, $CreatePrefetchHooksCallback> withReferences([
  1. PrefetchHooks prefetch(
    1. $CreatePrefetchHooksCallback prefetch
    )?
])

This function with return a new manager which will return each item in the database with its references

The references are returned as a prefiltered manager, which will only return the items which are related to the item

For example:

for (final (group,refs) in await groups.withReferences().get()) {
  final usersInGroup = await refs.users.get();
  /// Is identical to:
  final usersInGroup = await users.filter((f) => f.group.id(group.id)).get();
}

Prefetching

The keen among you may notice that the above code is extremely inefficient, as it will run a query for each group to get the users in that group. This could mean hundreds of queries for a single page of data, grinding your application to a halt.

The solution to this is to use prefetching, which will run a single query to get all the data you need.

For example:

for (final (group,refs) in await groups.withReferences((prefetch) => prefetch(users: true)).get()) {
  final usersInGroup = refs.users.prefetchedData;
}

Note that prefetchedData will be null if the reference was not prefetched.

Implementation

ProcessedTableManager<
  $Database,
  $Table,
  $Dataclass,
  $FilterComposer,
  $OrderingComposer,
  $ComputedFieldComposer,
  $CreateCompanionCallback,
  $UpdateCompanionCallback,
  $DataclassWithReferences,
  $DataclassWithReferences,
  $CreatePrefetchHooksCallback
>
withReferences([
  final PrefetchHooks Function($CreatePrefetchHooksCallback prefetch)?
  prefetch,
]) {
  // Build the prefetch hooks based on the user's input
  final prefetchHooks = ($state._prefetchHooksCallback != null)
      ? prefetch?.call($state._prefetchHooksCallback!)
      : null;

  // Return a new manager which is configured to return a
  // `$DataclassWithReferences` instead of a `$Dataclass`
  return ProcessedTableManager(
    $state.copyWithActiveDataclass().copyWith(prefetchHooks: prefetchHooks),
  );
}