@opndev/racecontrol 0.0.1

package/Changes

@@ -0,0 +1,5 @@
+Revision history for @opndev/racecontrol
+
+0.0.1       2026-05-09 20:48:20Z
+
+    * First release to an unsuspecting world

package/README.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+
+SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+-->
+
+# Welcome to @opndev/racecontrol
+
+Race control package
+
+This package it tightly related to a project that is not open to the world. You
+may use it at your own discretion.
+
+### License
+
+Please be aware that this package is GPL-3.0-or-later with exceptions. Please
+refer to the LICENSES directory for more on this.
+
+### Code contributions
+
+This project does not accept pull, merge or patches from others.
+
+Due to the license and how copyright law works, this module will not accept
+code written by people who are not employed by opndev.io.
+
+### jsdoc
+
+You can build the documentation by running `npm run jsdoc`.
+
+### Semver
+
+This project does not adhere to semver and one should not rely on the version
+x.y.z notation to infer stability or reliability. Read the Changes file to see
+any updates a version may bring. The fact that this module sits currently at
+0.x.z ranges does not indicate alpha or beta or even unstable associations. It
+is just a number and we started at 0.0.1.
+
+In general the following hard guarantee will be given: We will not break your
+code. In case we do happen to cause breakage: we will fix it accordingly.
+
+In case we foresee breaking changes we'll add deprecation warnings. Giving you
+time to fix things before a breaking change will be introduced. When a change
+will be introduced is communicated in the Changes file. Security fixes may
+cause breakage at any given time without notice.
+
+This package is released by `@opndev/rzilla`, changes to `package.json` will be
+overridden. In addition to a little bit of promotion, this also means that
+version numbers are autoincremented at release time and bumped in all relevant
+files: Versioning for humans, not machines.

package/lib/index.mjs

@@ -0,0 +1,294 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+
+const VERSION = "0.0.1"
+
+/**
+ * Check whether a participant matches a subdivision.
+ *
+ * Gender `x` acts as open. Age `0` means unbounded.
+ *
+ * @param {Object} participant Event participant data
+ * @param {Object} subdivision Subdivision configuration
+ * @returns {Boolean} true when the participant fits the subdivision
+ */
+export function participantMatchesSubdivision(participant, subdivision) {
+  if (!participant || !subdivision) {
+    return false
+  }
+
+  if (!subdivision.active) {
+    return false
+  }
+
+  if (
+    subdivision.gender
+    && subdivision.gender !== 'x'
+    && participant.gender !== subdivision.gender
+  ) {
+    return false
+  }
+
+  const age = Number(participant.age || 0)
+  const minAge = Number(subdivision.min_age || subdivision.age_min || 0)
+  const maxAge = Number(subdivision.max_age || subdivision.age_max || 0)
+
+  if (minAge > 0 && age < minAge) {
+    return false
+  }
+
+  if (maxAge > 0 && age > maxAge) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Create empty assignment buckets for subdivisions.
+ *
+ * @param {Object[]} subdivisions Subdivision configuration records
+ * @returns {Object[]} assignment buckets
+ */
+export function createBuckets(subdivisions) {
+  return subdivisions
+    .filter(subdivision => subdivision.active !== false)
+    .sort((a, b) => Number(a.sort_order || 0) - Number(b.sort_order || 0))
+    .map(subdivision => ({
+      subdivision_id: subdivision.id,
+      subdivision,
+      participants: [],
+      warnings: [],
+    }))
+}
+
+/**
+ * Assign participants to the first matching subdivision.
+ *
+ * @param {Object[]} participants Event participants
+ * @param {Object[]} subdivisions Subdivision configuration records
+ * @returns {Object} buckets and unassigned participants
+ */
+export function assignParticipants(participants, subdivisions) {
+  const buckets = createBuckets(subdivisions)
+  const unassigned = []
+
+  for (const participant of participants) {
+    const bucket = buckets.find(candidate => {
+      return participantMatchesSubdivision(
+        participant,
+        candidate.subdivision
+      )
+    })
+
+    if (bucket) {
+      bucket.participants.push(participant)
+    }
+    else {
+      unassigned.push(participant)
+    }
+  }
+
+  return {
+    buckets,
+    unassigned,
+  }
+}
+
+/**
+ * Apply configured frontend rules to assignment buckets.
+ *
+ * Currently supported:
+ * - merge_if_below_min
+ *
+ * @param {Object[]} buckets Assignment buckets
+ * @param {Object[]} rules Rule configuration records
+ * @returns {Object[]} updated assignment buckets
+ */
+export function applyRules(buckets, rules) {
+  const orderedRules = [...rules]
+    .filter(rule => rule.active !== false)
+    .sort((a, b) => Number(a.sort_order || 0) - Number(b.sort_order || 0))
+
+  for (const rule of orderedRules) {
+    if (rule.rule_type !== 'merge_if_below_min') {
+      continue
+    }
+
+    applyMergeIfBelowMin(buckets, rule)
+  }
+
+  return buckets
+}
+
+/**
+ * Apply one merge_if_below_min rule.
+ *
+ * @param {Object[]} buckets Assignment buckets
+ * @param {Object} rule Rule configuration record
+ * @returns {Object[]} updated assignment buckets
+ */
+export function applyMergeIfBelowMin(buckets, rule) {
+  const sourceIds = rule.source_subdivision_ids || []
+  const targetId = rule.target_subdivision_id
+  const minParticipants = Number(rule.min_participants || 0)
+
+  const target = buckets.find(bucket => bucket.subdivision_id === targetId)
+
+  if (!target) {
+    return buckets
+  }
+
+  for (const sourceId of sourceIds) {
+    const source = buckets.find(bucket => bucket.subdivision_id === sourceId)
+
+    if (!source || source.subdivision_id === target.subdivision_id) {
+      continue
+    }
+
+    if (source.participants.length >= minParticipants) {
+      continue
+    }
+
+    target.participants.push(...source.participants)
+    source.participants = []
+    source.warnings.push({
+      type: 'merged',
+      target_subdivision_id: target.subdivision_id,
+      rule_id: rule.id || null,
+    })
+  }
+
+  return buckets
+}
+
+/**
+ * Add min participant warnings to buckets.
+ *
+ * @param {Object[]} buckets Assignment buckets
+ * @returns {Object[]} buckets with warnings
+ */
+export function addWarnings(buckets) {
+  for (const bucket of buckets) {
+    const minParticipants = Number(
+      bucket.subdivision.min_participants || 0
+    )
+
+    if (
+      minParticipants > 0
+      && bucket.participants.length > 0
+      && bucket.participants.length < minParticipants
+    ) {
+      bucket.warnings.push({
+        type: 'below_min_participants',
+        min_participants: minParticipants,
+        count: bucket.participants.length,
+      })
+    }
+  }
+
+  return buckets
+}
+
+/**
+ * Generate bibs for assigned participants.
+ *
+ * If a subdivision or division uses sail numbers, the participant sailnumber is
+ * used as bib. Otherwise the subdivision or division prefix is used with a
+ * sequential number.
+ *
+ * @param {Object[]} buckets Assignment buckets
+ * @param {Object} options Bib options
+ * @returns {Object[]} buckets with participant bib values
+ */
+export function generateBibs(buckets, options = {}) {
+  const counters = {}
+  const division = options.division || {}
+  const competition = options.competition || {}
+  const usesSailnumber = Boolean(
+    competition.sailnumber || division.sailnumber
+  )
+
+  for (const bucket of buckets) {
+    const prefix = bucket.subdivision.bib_prefix || division.bib_prefix || ''
+
+    if (counters[prefix] === undefined) {
+      counters[prefix] = 1
+    }
+
+    bucket.participants = bucket.participants.map(participant => {
+      if (usesSailnumber) {
+        return {
+          ...participant,
+          bib: participant.sailnumber || null,
+        }
+      }
+
+      const bib = `${prefix}${counters[prefix]}`
+      counters[prefix] += 1
+
+      return {
+        ...participant,
+        bib,
+      }
+    })
+  }
+
+  return buckets
+}
+
+/**
+ * Convert buckets to the API save payload.
+ *
+ * @param {Object[]} buckets Assignment buckets
+ * @returns {Object[]} payload for race control save endpoint
+ */
+export function toSavePayload(buckets) {
+  return buckets.map(bucket => ({
+    subdivision_id: bucket.subdivision_id,
+    participants: bucket.participants.map(participant => ({
+      id: participant.id,
+      bib: participant.bib || null,
+    })),
+  }))
+}
+
+/**
+ * Build the full race control state.
+ *
+ * @param {Object} input Race control input
+ * @returns {Object} computed race control state
+ */
+export function buildRaceControl(input) {
+  const assigned = assignParticipants(
+    input.participants || [],
+    input.subdivisions || []
+  )
+
+  applyRules(assigned.buckets, input.rules || [])
+  addWarnings(assigned.buckets)
+  generateBibs(assigned.buckets, {
+    competition: input.competition || {},
+    division: input.division || {},
+  })
+
+  return assigned
+}
+
+export {
+  VERSION,
+}
+
+export default {
+  addWarnings,
+  applyMergeIfBelowMin,
+  applyRules,
+  assignParticipants,
+  buildRaceControl,
+  createBuckets,
+  generateBibs,
+  participantMatchesSubdivision,
+  toSavePayload,
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "author": {
+    "email": "wesley@opndev.io",
+    "name": "Wesley Schwengle"
+  },
+  "description": "Race control package",
+  "devDependencies": {
+    "jsdoc": "latest",
+    "tap": "latest"
+  },
+  "exports": {
+    ".": "./lib/index.mjs"
+  },
+  "keywords": [
+    "racecontrol"
+  ],
+  "license": "GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions",
+  "name": "@opndev/racecontrol",
+  "private": false,
+  "scripts": {
+    "build": "rzil build",
+    "jsdoc": "jsdoc -c .jsdoc.json",
+    "pkg": "rzil pkg",
+    "release": "rzil release",
+    "test": "tap"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.0.1"
+}