Themes

A theme categorises boards. Two system kinds (system_bidding, system_play) carry translated labels and are shared by every account; two user kinds (user_theme, user_inspiration) belong to one teacher and carry a single untranslated label. The teacher app lists and edits themes, the deal filters select by theme id, the API exposes them, and the bulk-claim import of Boards creates user themes by slug.

Domain

BoardTheme

labels is a LocalizedLabels map (see Shared); usageCount is the number of boards linked to the theme.

Constants and guards

Label resolution

System labels follow the app language; user labels ignore it, because user-created themes are not translated.

export function labelsOf(faker: Faker) {
  const system = makeBoardTheme(faker, {
    type: BOARD_THEME_TYPES.SYSTEM_AUCTION,
    labels: { en: "Stayman", fr: "Stayman (2♣)" },
  });
  getBoardThemeLabel(system, "fr"); // => "Stayman (2♣)"
  isUserThemeType(system.type); // => false

  const user = makeBoardTheme(faker, {
    type: BOARD_THEME_TYPES.USER_THEME,
    labels: createUserThemeLabel("My Tuesday drills"), // => { default: "My Tuesday drills" }
  });
  getUserThemeLabel(user); // => "My Tuesday drills"
  getBoardThemeLabel(user, "fr"); // => "My Tuesday drills": user labels ignore the language
  return { system, user };
}

Application

ThemesService

createThemesService(deps: { themes: ThemeRepository; themesRead: ThemeReadRepository; boardsRead: BoardReadRepository })

AccountThemesService is ThemesService without listSystemPage and listUserPage. The API types its themesService with it, so a request on behalf of an account cannot reach the back-office pages across every owner.

type ThemesDeps = {
  themes: ThemeRepository;
  themesRead: ThemeReadRepository;
  boardsRead: BoardReadRepository;
};

export async function manageThemes(deps: ThemesDeps, ctx: ServiceContext) {
  const themes = createThemesService(deps);

  const mine = await themes.list(["user_theme", "user_inspiration"], ctx); // scoped to ctx.userId
  const systemOnly = await themes.list("system_bidding", ctx); // never owner-scoped

  const created = await themes.create(
    { labels: createUserThemeLabel("Squeeze"), type: "user_theme" },
    ctx
  );
  await themes.update(created.id, { labels: { default: "Simple squeeze" } }, ctx); // NotFoundError if absent
  const linked = await themes.listLinkedBoards(created.id, ctx); // [{ boardId, boardName, contract, level, teaching }]
  const boardsAffected = await themes.remove(created.id, ctx); // junction rows removed

  return { mine, systemOnly, linked, boardsAffected };
}

DTOs and view types

LinkedBoard is the response shape of listLinkedBoards; level is null when the board level is UNSET.

SystemThemes and UserThemes are the groupings the teacher app renders; the package only defines the shapes.

export function groupForUi(all: BoardTheme[]): {
  system: SystemThemes;
  user: UserThemes;
} {
  return {
    system: {
      auction: all.filter((t) => t.type === "system_bidding"),
      cardPlay: all.filter((t) => t.type === "system_play"),
    },
    user: {
      userDefined: all.filter((t) => t.type === "user_theme"),
      inspirations: all.filter((t) => t.type === "user_inspiration"),
    },
  };
}

Query objects

The generics (QueryObject, Criteria, Projection, Aggregation, pagination) are described on Queries. The theme family binds them as follows.

ThemeQuery (read side). ThemeQueryParams extends QueryParams<ThemeWhere, ThemeSort> with viewerUserId. When viewerUserId is set, the repository ANDs type is a system type OR ownerId = viewerUserId to every read, whatever the other filters: a viewer never reads another account's theme. Without a viewer the read is unscoped, which only the operator reads (back-office pages, PBN import) use.

ThemeCriteria (write side and aggregates). Refuses an empty where like every Criteria.

ThemeWhere: id, ownerId, slug and type, each an Equality<T> operator. ownerId maps to the owning account, slug to the theme identifier.

ThemeProjections

ThemeAggregations: count(criteria?) returning ThemeAggregation<number>. ThemeAggregation<TResult = unknown> is Aggregation<TResult> plus an optional criteria: ThemeCriteria, the type repositories switch on.

ThemeSort: { column: "label" \| "createdAt"; desc: boolean }, with THEME_SORT_COLUMNS as the whitelist. label is locale-dependent and sorted by the implementation on a label key.

ThemeUpdatePatch: { labels?: LocalizedLabels }, the only mutable column.

export async function themeIdsBySlug(
  themesRead: ThemeReadRepository,
  ownerId: string,
  slugs: string[]
): Promise<Map<string, string>> {
  const rows = await themesRead.findMany(
    ThemeQuery.empty().byOwner(ownerId).bySlugs(slugs),
    ThemeProjections.ids() // { id, slug }
  );
  return new Map(rows.flatMap((r) => (r.slug ? [[r.slug, r.id]] : [])));
}

export function deleteUserThemes(themes: ThemeRepository, ownerId: string) {
  return themes.delete(
    ThemeCriteria.byOwner(ownerId).and({ type: { eq: "user_theme" } })
  ); // => { deletedIds, boardsAffected }
}

Ports

ThemeReadRepository is ReadRepository<ThemeQuery>: getById(id, projection), findMany(query, projection), findManyPaginated(query, projection), aggregate(aggregation). getById throws NotFoundError when no row matches.

ThemeRepository is WriteRepository<ThemeCriteria, ThemeUpdatePatch, PersistableThemeWrite, undefined, ThemeUpdateResult, ThemeDeleteResult> plus the two inserts.

Errors

The HTTP API answers them as 404 THEME_NOT_FOUND and 403 ACCESS_DENIED. See Errors.