xpt-shared-types 1.0.4 → 1.3.0

package/scripts/sync-from-strapi.js

@@ -0,0 +1,281 @@
+/* eslint-disable no-console */
+/**
+ * Generates the shared API contract from the Strapi content-type schemas.
+ *
+ * `schema.json` is the source of truth — not `types/generated/contentTypes.d.ts`,
+ * which is gitignored in xpt-strapi and only exists after `strapi develop` has run.
+ *
+ *   node scripts/sync-from-strapi.js [pathToStrapiRepo]
+ *
+ * Output is committed to this repo; run this whenever a content type changes.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const STRAPI_ROOT =
+  process.argv[2] ||
+  process.env.XPT_STRAPI_PATH ||
+  path.resolve(__dirname, '../../xpt-strapi');
+const OUT = path.resolve(__dirname, '../src/generated');
+
+const BANNER = [
+  '// AUTO-GENERATED by scripts/sync-from-strapi.js — DO NOT EDIT MANUALLY.',
+  '// Source: xpt-strapi/src/**/content-types/**/schema.json',
+  '// Regenerate with: yarn sync',
+  '',
+].join('\n');
+
+// ── helpers ────────────────────────────────────────────────────────────────
+/** Quote a property name only when it is not a bare identifier. */
+const prop = (name) =>
+  /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+
+const pascal = (s) =>
+  String(s)
+    .replace(/[_-]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase())
+    .replace(/^([a-z])/, (_, c) => c.toUpperCase())
+    .replace(/[^A-Za-z0-9]/g, '');
+
+/** api::tournament-participant.tournament-participant -> TournamentParticipant */
+function modelNameFromUid(uid) {
+  if (uid === 'plugin::users-permissions.user') return 'User';
+  if (uid === 'plugin::users-permissions.role') return 'UserRole';
+  if (uid === 'plugin::upload.file') return 'StrapiMedia';
+  const m = /^api::[^.]+\.(.+)$/.exec(uid);
+  return m ? pascal(m[1]) : null;
+}
+
+const SCALARS = {
+  string: 'string',
+  text: 'string',
+  richtext: 'string',
+  uid: 'string',
+  email: 'string',
+  password: 'string',
+  datetime: 'string',
+  date: 'string',
+  time: 'string',
+  biginteger: 'string', // Strapi serialises bigint as string
+  integer: 'number',
+  float: 'number',
+  decimal: 'number',
+  boolean: 'boolean',
+  json: 'unknown',
+  blocks: 'BlocksContent',
+};
+
+// ── collect schemas ────────────────────────────────────────────────────────
+function findSchemas(root) {
+  const out = [];
+  const roots = [
+    path.join(root, 'src', 'api'),
+    path.join(root, 'src', 'extensions'),
+  ];
+  for (const base of roots) {
+    if (!fs.existsSync(base)) continue;
+    for (const dir of fs.readdirSync(base)) {
+      const ctDir = path.join(base, dir, 'content-types');
+      if (!fs.existsSync(ctDir)) continue;
+      for (const ct of fs.readdirSync(ctDir)) {
+        const file = path.join(ctDir, ct, 'schema.json');
+        if (fs.existsSync(file)) out.push(file);
+      }
+    }
+  }
+  return out.sort();
+}
+
+const files = findSchemas(STRAPI_ROOT);
+if (!files.length) {
+  console.error(
+    'No schema.json found under ' +
+      STRAPI_ROOT +
+      '. Pass the xpt-strapi path as an argument.'
+  );
+  process.exit(1);
+}
+
+const collected = [];
+for (const file of files) {
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const info = raw.info || {};
+  const singular = info.singularName || path.basename(path.dirname(file));
+  // The users-permissions extension augments the plugin's own user model.
+  const isUserExt = file.split(path.sep).includes('users-permissions');
+  collected.push({
+    name: isUserExt ? 'User' : pascal(singular),
+    singular: isUserExt ? 'user' : singular,
+    attributes: raw.attributes || {},
+  });
+}
+
+// Merge any model declared more than once (e.g. the user extension).
+const byName = new Map();
+for (const m of collected) {
+  if (byName.has(m.name)) {
+    Object.assign(byName.get(m.name).attributes, m.attributes);
+  } else {
+    byName.set(m.name, m);
+  }
+}
+const allModels = [...byName.values()].sort((a, b) =>
+  a.name.localeCompare(b.name)
+);
+
+// ── enums ──────────────────────────────────────────────────────────────────
+const enums = [];
+for (const m of allModels) {
+  for (const [field, def] of Object.entries(m.attributes)) {
+    if (def.type !== 'enumeration' || !Array.isArray(def.enum)) continue;
+    enums.push({
+      name: m.name + pascal(field),
+      values: def.enum,
+      model: m.name,
+      field,
+    });
+  }
+}
+enums.sort((a, b) => a.name.localeCompare(b.name));
+
+let enumsOut = BANNER + '\n';
+for (const e of enums) {
+  enumsOut +=
+    '/** `' +
+    e.model +
+    '.' +
+    e.field +
+    '` */\nexport type ' +
+    e.name +
+    ' =\n' +
+    e.values.map((v) => '  | ' + JSON.stringify(v)).join('\n') +
+    ';\n\n';
+}
+enumsOut +=
+  '/** Readability alias for `tournament.currentStatus`. */\n' +
+  'export type TournamentStatus = TournamentCurrentStatus;\n';
+
+// ── models (read shapes) ───────────────────────────────────────────────────
+const enumLookup = new Map(enums.map((e) => [e.model + '.' + e.field, e.name]));
+const usedEnums = new Set();
+
+function readTypeFor(model, field, def) {
+  if (def.type === 'enumeration') {
+    return enumLookup.get(model.name + '.' + field) || 'string';
+  }
+  if (def.type === 'media') {
+    return def.multiple ? 'StrapiMedia[]' : 'StrapiMedia';
+  }
+  if (def.type === 'relation') {
+    const target = modelNameFromUid(def.target);
+    if (!target) return 'unknown';
+    const many =
+      def.relation === 'oneToMany' || def.relation === 'manyToMany';
+    return many ? target + '[]' : target;
+  }
+  return SCALARS[def.type] || 'unknown';
+}
+
+let modelsBody = '';
+for (const m of allModels) {
+  const lines = [];
+  for (const [field, def] of Object.entries(m.attributes)) {
+    // `private` attributes are never returned by the content API.
+    if (def.private) continue;
+    const t = readTypeFor(m, field, def);
+    if (def.type === 'enumeration') usedEnums.add(t);
+    // Everything except id/documentId is optional, because nothing else is
+    // guaranteed on the wire:
+    //   - relations and media appear only when the query populates them;
+    //   - any scalar disappears when the query uses `fields`, which this
+    //     codebase does pervasively — so even a schema-`required` field like
+    //     user.email is absent from most responses.
+    // The base model is therefore the minimum guarantee; use `Populated<T, K>`
+    // at a call site to record what that particular query actually returned.
+    // Strapi also sends `null` rather than omitting an unset nullable value,
+    // so single-valued optionals are `?: T | null`. Lists come back as `[]`.
+    const isList = t.endsWith('[]');
+    const rendered = isList ? t : t + ' | null';
+    lines.push('  ' + prop(field) + '?: ' + rendered + ';');
+  }
+  modelsBody +=
+    '/** `' +
+    m.singular +
+    '` */\nexport interface ' +
+    m.name +
+    ' extends StrapiDocument {\n' +
+    lines.join('\n') +
+    '\n}\n\n';
+}
+
+const enumImportList = [...usedEnums]
+  .filter((e) => !e.endsWith('[]'))
+  .sort()
+  .map((e) => '  ' + e + ',')
+  .join('\n');
+
+const modelsOut =
+  BANNER +
+  "\nimport type {\n  BlocksContent,\n  StrapiDocument,\n  StrapiMedia,\n  UserRole,\n} from '../contracts';\n" +
+  (enumImportList ? 'import type {\n' + enumImportList + "\n} from './enums';\n" : '') +
+  '\n' +
+  modelsBody;
+
+// ── inputs (write shapes) ──────────────────────────────────────────────────
+// Write payloads differ structurally from read shapes: relations are sent as
+// documentIds or connect/set/disconnect, media as numeric file ids.
+let inputsBody = '';
+for (const m of allModels) {
+  const lines = [];
+  for (const [field, def] of Object.entries(m.attributes)) {
+    if (def.private) continue;
+    let t;
+    if (def.type === 'relation') {
+      const many =
+        def.relation === 'oneToMany' || def.relation === 'manyToMany';
+      t = many ? 'RelationInput | RelationInput[]' : 'RelationInput';
+    } else if (def.type === 'media') {
+      t = def.multiple ? 'MediaInput[]' : 'MediaInput';
+    } else if (def.type === 'enumeration') {
+      t = enumLookup.get(m.name + '.' + field) || 'string';
+    } else {
+      t = SCALARS[def.type] || 'unknown';
+    }
+    lines.push('  ' + prop(field) + '?: ' + t + ';');
+  }
+  inputsBody +=
+    '/** Write payload for `' +
+    m.singular +
+    '`. */\nexport interface ' +
+    m.name +
+    'Input {\n' +
+    lines.join('\n') +
+    '\n}\n\n';
+}
+
+const inputsOut =
+  BANNER +
+  "\nimport type {\n  BlocksContent,\n  MediaInput,\n  RelationInput,\n} from '../contracts';\n" +
+  (enumImportList ? 'import type {\n' + enumImportList + "\n} from './enums';\n" : '') +
+  '\n' +
+  inputsBody;
+
+// ── write ──────────────────────────────────────────────────────────────────
+fs.mkdirSync(OUT, { recursive: true });
+fs.writeFileSync(path.join(OUT, 'enums.ts'), enumsOut);
+fs.writeFileSync(path.join(OUT, 'models.ts'), modelsOut);
+fs.writeFileSync(path.join(OUT, 'inputs.ts'), inputsOut);
+fs.writeFileSync(
+  path.join(OUT, 'index.ts'),
+  BANNER +
+    "\nexport * from './enums';\nexport * from './models';\nexport * from './inputs';\n"
+);
+
+console.log(
+  'Generated ' +
+    allModels.length +
+    ' models and ' +
+    enums.length +
+    ' enums from ' +
+    files.length +
+    ' schemas.'
+);

package/src/bracket.ts

@@ -0,0 +1,193 @@
+/**
+ * Bracket shape — how many rounds a single-elimination tournament has, what
+ * each is called, how matches are numbered, and where each winner goes.
+ *
+ * This is the single source of truth for both apps: xpt-strapi re-exports it
+ * from `src/utils/bracket.ts` (adding the Strapi-coupled stage sync), and
+ * xpt-client's Storybook fixtures consume it directly — a fixture built any
+ * other way could show a bracket the backend can never produce.
+ */
+
+import type { MatchRound } from './generated';
+
+/** The largest bracket the round names can describe. */
+export const MAX_BRACKET_SIZE = 128;
+
+export function nextPowerOf2(n: number): number {
+  if (n <= 2) return 2;
+  let p = 2;
+  while (p < n) p *= 2;
+  return p;
+}
+
+export interface BracketRound {
+  name: MatchRound;
+  matchCount: number;
+}
+
+/**
+ * The name of the round that *starts* with this many players left. Halving
+ * from the bracket size down to 2 walks the whole bracket, so there is no
+ * table of per-size name lists to fall out of sync — the one way a size can
+ * go wrong is a size that is not a power of two in range, and that throws.
+ */
+const ROUND_NAME_BY_SIZE: Record<number, MatchRound> = {
+  128: 'Round 128',
+  64: 'Round 64',
+  32: 'Round 32',
+  16: 'Round 16',
+  8: 'Quarter Final',
+  4: 'Semi-Final',
+  2: 'Finals',
+};
+
+export function buildBracketRounds(
+  bracketSize: number,
+  hasThirdPlace: boolean
+): BracketRound[] {
+  // An unrecognised size used to fall back to a single round called "Finals"
+  // holding `bracketSize / 2` matches. An unplayable bracket is worse than no
+  // bracket.
+  if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+    throw new Error(
+      `Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${MAX_BRACKET_SIZE}`
+    );
+  }
+
+  const rounds: BracketRound[] = [];
+
+  for (let size = bracketSize; size >= 2; size /= 2) {
+    rounds.push({ name: ROUND_NAME_BY_SIZE[size], matchCount: size / 2 });
+  }
+
+  // Inject Third Round slot before Finals when enabled (4+ players)
+  if (hasThirdPlace && bracketSize >= 4) {
+    const finalsIdx = rounds.findIndex((r) => r.name === 'Finals');
+    if (finalsIdx > 0) {
+      rounds.splice(finalsIdx, 0, { name: 'Third Round', matchCount: 1 });
+    }
+  }
+
+  return rounds;
+}
+
+/** The rounds a tournament of this many entrants will be played over. */
+export function bracketRoundsForParticipants(
+  participants: number,
+  hasThirdPlace: boolean
+): BracketRound[] {
+  return buildBracketRounds(nextPowerOf2(participants), hasThirdPlace);
+}
+
+/** Uniform Fisher–Yates shuffle. A `sort(() => Math.random() - 0.5)` is
+ * biased — comparison sorts assume a consistent comparator, so some orderings
+ * come up measurably more often than others. */
+export function shuffle<T>(items: readonly T[]): T[] {
+  const result = [...items];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+/**
+ * Standard bracket seed order: which seed (0-based) sits in each first-round
+ * slot. Built by the usual doubling rule — each seed is paired with its
+ * complement, so seed 0 meets seed 1 only in the final.
+ *
+ * This is also the bye-safety property: slots are paired (s, size-1-s), and
+ * byes are the seeds from `checkedIn` upward. Both sides of a pair being byes
+ * would need `checkedIn <= (size-1)/2`, but `nextPowerOf2` guarantees
+ * `checkedIn > size/2` — so a bye always faces a real entrant.
+ */
+export function seedOrder(bracketSize: number): number[] {
+  if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+    throw new Error(
+      `Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${MAX_BRACKET_SIZE}`
+    );
+  }
+
+  let order = [0];
+  while (order.length < bracketSize) {
+    const size = order.length * 2;
+    const next: number[] = [];
+    for (const seed of order) {
+      next.push(seed, size - 1 - seed);
+    }
+    order = next;
+  }
+  return order;
+}
+
+export interface PlannedMatch {
+  round: MatchRound;
+  matchNumber: number;
+  /** Where this match's winner goes; null for Finals and Third Round. */
+  nextMatchNumber: number | null;
+  winnerSlot: 'home' | 'away' | null;
+  /** First-round matches only: index into the seeded slot array (null = later round). */
+  homeSlot: number | null;
+  awaySlot: number | null;
+}
+
+export interface BracketPlan {
+  bracketSize: number;
+  rounds: BracketRound[];
+  matches: PlannedMatch[];
+}
+
+/**
+ * The full bracket as data: every match, its number, and where its winner
+ * goes. Numbering is sequential across rounds in bracket order, with Third
+ * Round (when present) sitting before Finals.
+ */
+export function buildBracketPlan(
+  bracketSize: number,
+  hasThirdPlace: boolean
+): BracketPlan {
+  const rounds = buildBracketRounds(bracketSize, hasThirdPlace);
+
+  let counter = 1;
+  const roundMatchNumbers = rounds.map((round) =>
+    Array.from({ length: round.matchCount }, () => counter++)
+  );
+
+  // Winner linkage skips Third Round — it receives losers, not winners.
+  const linkage: Record<
+    number,
+    { nextMatchNumber: number; winnerSlot: 'home' | 'away' }
+  > = {};
+  const nonThirdRounds = rounds
+    .map((round, index) => ({ round, index }))
+    .filter(({ round }) => round.name !== 'Third Round');
+
+  for (let ri = 0; ri < nonThirdRounds.length - 1; ri++) {
+    const currentNums = roundMatchNumbers[nonThirdRounds[ri].index];
+    const nextNums = roundMatchNumbers[nonThirdRounds[ri + 1].index];
+
+    currentNums.forEach((num, mi) => {
+      linkage[num] = {
+        nextMatchNumber: nextNums[Math.floor(mi / 2)],
+        winnerSlot: mi % 2 === 0 ? 'home' : 'away',
+      };
+    });
+  }
+
+  const matches: PlannedMatch[] = [];
+  rounds.forEach((round, ri) => {
+    roundMatchNumbers[ri].forEach((num, mi) => {
+      const link = linkage[num] ?? { nextMatchNumber: null, winnerSlot: null };
+      matches.push({
+        round: round.name,
+        matchNumber: num,
+        nextMatchNumber: link.nextMatchNumber,
+        winnerSlot: link.winnerSlot,
+        homeSlot: ri === 0 ? mi * 2 : null,
+        awaySlot: ri === 0 ? mi * 2 + 1 : null,
+      });
+    });
+  });
+
+  return { bracketSize, rounds, matches };
+}

package/src/contracts/index.ts

@@ -0,0 +1,158 @@
+/**
+ * Hand-written contract primitives.
+ *
+ * Everything here is maintained by hand — the generated models in
+ * `src/generated` import from this module, so keep the names stable.
+ */
+
+/** Strapi 5 returns flat documents: no `attributes` envelope. */
+export interface StrapiDocument {
+  id: number;
+  documentId: string;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+  publishedAt?: string | null;
+  locale?: string | null;
+}
+
+/** A single size variant produced by the upload plugin. */
+export interface StrapiMediaFormat {
+  name: string;
+  hash: string;
+  ext: string;
+  mime: string;
+  width: number;
+  height: number;
+  size: number;
+  url: string;
+  path?: string | null;
+}
+
+/**
+ * Size variants the upload plugin generates. The four named breakpoints are
+ * Strapi's defaults; the index signature covers custom ones.
+ */
+export interface StrapiMediaFormats {
+  thumbnail?: StrapiMediaFormat;
+  small?: StrapiMediaFormat;
+  medium?: StrapiMediaFormat;
+  large?: StrapiMediaFormat;
+  [breakpoint: string]: StrapiMediaFormat | undefined;
+}
+
+/** `plugin::upload.file` */
+export interface StrapiMedia {
+  id: number;
+  documentId?: string;
+  name: string;
+  alternativeText?: string | null;
+  caption?: string | null;
+  width?: number | null;
+  height?: number | null;
+  formats?: StrapiMediaFormats | null;
+  hash: string;
+  ext?: string | null;
+  mime: string;
+  size: number;
+  url: string;
+  previewUrl?: string | null;
+  provider?: string;
+  provider_metadata?: unknown;
+  folderPath?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  publishedAt?: string;
+  locale?: string | null;
+}
+
+/** Rich-text `blocks` payload; shape is defined by the blocks renderer. */
+export type BlocksContent = unknown[];
+
+// ── write payloads ─────────────────────────────────────────────────────────
+
+/**
+ * How a relation is sent on create/update. Strapi accepts a bare documentId,
+ * a numeric id, or the connect/set/disconnect long form.
+ */
+export type RelationInput =
+  | string
+  | number
+  | { id: number }
+  | { documentId: string }
+  | { connect?: Array<string | number>; disconnect?: Array<string | number> }
+  | { set: Array<string | number> };
+
+/** Media is written as the uploaded file's numeric id. */
+export type MediaInput = number | number[] | null;
+
+// ── responses ──────────────────────────────────────────────────────────────
+
+export interface Pagination {
+  page: number;
+  pageSize: number;
+  pageCount: number;
+  total: number;
+}
+
+export interface Meta {
+  pagination?: Pagination;
+  [key: string]: unknown;
+}
+
+/** Single-entity response. Strapi still sends `meta`, usually `{}`. */
+export interface StrapiResponse<T> {
+  data: T;
+  meta?: Meta;
+}
+
+/** Collection response. */
+export interface StrapiCollectionResponse<T> {
+  data: T[];
+  meta?: Meta;
+}
+
+export interface StrapiError {
+  status: number;
+  name: string;
+  message: string;
+  details?: unknown;
+}
+
+export interface StrapiErrorResponse {
+  data: null;
+  error: StrapiError;
+}
+
+// ── populate awareness ─────────────────────────────────────────────────────
+
+/**
+ * Marks relations as present.
+ *
+ * Generated models leave every relation optional, because whether one comes
+ * back depends entirely on the query's `populate`. Use this at a call site to
+ * record what that particular query actually asked for:
+ *
+ * ```ts
+ * type WithGame = Populated<Tournament, 'game' | 'prizes'>;
+ * ```
+ *
+ * This is the type-level counterpart to remembering to populate — if the query
+ * and the annotation disagree, that is a bug the reader can see.
+ */
+export type Populated<T, K extends keyof T> = T & {
+  [P in K]-?: NonNullable<T[P]>;
+};
+
+/** Recursively marks every relation on `T` as optional (the default shape). */
+export type Unpopulated<T> = {
+  [P in keyof T]?: T[P];
+};
+
+/** `plugin::users-permissions.role` */
+export interface UserRole {
+  id: number;
+  documentId?: string;
+  name: string;
+  description?: string | null;
+  type?: string | null;
+}