coh-content-db 1.4.1 → 2.0.0-rc.1

package/src/main/changelog.ts

@@ -0,0 +1,20 @@
+import { Change } from './api/change'
+
+export const CHANGELOG: Change[] = [
+  {
+    version: '2.0.0',
+    date: new Date('2025-03-12'),
+    description: ''
+      + '* Replaced redundant interfaces with their concrete equivalents.\n'
+      + '* Replaced enums with extensible union types; Server groups with new badge types, enhancement types, etc. can now extend them locally.\n'
+      + '* Removed the `serverGroup` property from entities to simplify the object tree; Server group context will need to be managed separately.\n'
+      + '* Standardized pluralization of some field names (name, icon).\n'
+      + '* Combined `settitle` ids into a single tuple field.\n'
+      + '* Change from GNU to The Unlicense.\n'
+      + '* Removed dependency on lodash. There are now no third-party runtime dependencies.\n'
+      + '* Moved from webpack to rollup for packaging.\n'
+      + '* Add eslint for linting.\n'
+      + '* Add jest for unit tests.\n'
+      + '* Added GitHub Actions for CI.\n',
+  },
+]

package/src/main/db/alternates.ts

@@ -0,0 +1,81 @@
+import { AlternateData } from '../api/alternate-data'
+import { Sex } from '../api/sex'
+import { Alignment } from '../api/alignment'
+
+const ALIGNMENT_SORT: Record<string, number> = { H: 2, V: 1, P: 0 }
+const SEX_SORT: Record<string, number> = { M: 1, F: 0 }
+
+export class Alternates<T> {
+  readonly #sortedValues: AlternateData<T>[] = []
+
+  constructor(values: AlternateData<T>[]) {
+    this.#sortedValues = values.sort()
+    this.#sortedValues.sort((a, b) => this.#compareAlternates(a, b))
+  }
+
+  getValue(alignment?: Alignment | string, sex?: Sex | string): T | undefined {
+    for (let index = this.#sortedValues.length; index--;) {
+      const entry = this.#sortedValues[index]
+      if ((entry.alignment === undefined || entry.alignment === alignment)
+        && (entry.sex === undefined || entry.sex === sex)
+      ) return entry.value
+    }
+    return undefined
+  }
+
+  /**
+   * Get the default value for this list of alternates, the value with the highest priority and lowest specificity.
+   */
+  get default(): T | undefined {
+    return this.#sortedValues[0]?.value
+  }
+
+  /**
+   * Get the list of alternates sorted in canonical order (alignment then sex, low to high specificity).
+   */
+  get canonical(): AlternateData<T>[] {
+    return this.#sortedValues
+  }
+
+  #compareAlternates(a: AlternateData<T>, b: AlternateData<T>): number {
+    const aSpecificity = (a.alignment ? 2 : 0) + (a.sex ? 1 : 0)
+    const bSpecificity = (b.alignment ? 2 : 0) + (b.sex ? 1 : 0)
+    if (aSpecificity !== bSpecificity) return aSpecificity - bSpecificity // Order first by least-specific
+
+    const alignmentComparison = this.#compareAlignment(a.alignment, b.alignment) // Next by alignment
+    if (alignmentComparison !== 0) return alignmentComparison
+
+    const sexComparison = this.#compareSex(a.sex, b.sex) // Last by sex
+    if (sexComparison !== 0) return sexComparison
+
+    return String(a.value).localeCompare(String(b.value))
+  }
+
+  #compareAlignment(a: Alignment | string | undefined, b: Alignment | string | undefined): number {
+    if (a === b) return 0
+    if (a === undefined && b !== undefined) return -1
+    if (b === undefined && a !== undefined) return 1
+
+    const aSort = a === undefined ? -1 : ALIGNMENT_SORT[a] ?? -1 // Unknown values get -1 priority
+    const bSort = b === undefined ? -1 : ALIGNMENT_SORT[b] ?? -1
+
+    if (aSort !== bSort) return bSort - aSort
+
+    // Unknown values (not in ALIGNMENT_SORT) are sorted alphabetically
+    return a?.localeCompare(b ?? '') ?? 0
+  }
+
+  #compareSex(a?: Sex | string | undefined, b?: Sex | string | undefined): number {
+    if (a === b) return 0
+    if (a === undefined && b !== undefined) return -1
+    if (b === undefined && a !== undefined) return 1
+
+    const aSort = SEX_SORT[a ?? -1] ?? -1 // Unknown values get -1 priority
+    const bSort = SEX_SORT[b ?? -1] ?? -1
+
+    if (aSort !== bSort) return bSort - aSort
+
+    // Unknown values (not in SEX_SORT) are sorted alphabetically
+    return a?.localeCompare(b ?? '') ?? 0
+  }
+}

package/src/main/db/archetype.ts

@@ -0,0 +1,14 @@
+import { Key } from './key'
+import { ArchetypeData } from '../api/archetype-data'
+
+export class Archetype {
+  readonly key: string
+  readonly name: string
+  readonly description?: string
+
+  constructor(data: ArchetypeData) {
+    this.key = new Key(data.key).value
+    this.name = data.name
+    this.description = data.description
+  }
+}

package/src/main/db/badge-partial.ts

@@ -0,0 +1,35 @@
+import { BadgePartialData } from '../api/badge-partial-data'
+import { PlaqueType } from '../api/plaque-type'
+import { BadgePartialType } from '../api/badge-partial-type'
+import { EnhancementCategory } from '../api/enhancement-category'
+import { Key } from './key'
+
+export class BadgePartial {
+  readonly key: string
+  readonly type: BadgePartialType | string
+  readonly mapKey?: string
+  readonly loc?: number[]
+  readonly plaqueType?: PlaqueType | string
+  readonly inscription?: string
+  readonly vidiotMapKey?: string
+  readonly badgeKey?: string
+  readonly inventionLevel?: number
+  readonly inventionTypes?: (EnhancementCategory | string)[]
+  readonly inventionCount?: number
+  readonly notes?: string
+
+  constructor(data: BadgePartialData) {
+    this.key = new Key(data.key).value
+    this.type = data.type
+    this.mapKey = data.mapKey
+    this.loc = data.loc
+    this.plaqueType = data.plaqueType
+    this.inscription = data.inscription
+    this.vidiotMapKey = data.vidiotMapKey
+    this.badgeKey = data.badgeKey
+    this.inventionLevel = data.inventionLevel
+    this.inventionTypes = data.inventionTypes
+    this.inventionCount = data.inventionCount
+    this.notes = data.notes
+  }
+}

package/src/main/db/badge.ts

@@ -0,0 +1,141 @@
+import { BadgeType } from '../api/badge-type'
+import { Alignment } from '../api/alignment'
+import { Link } from '../api/link'
+import { BadgeData } from '../api/badge-data'
+import { BadgePartial } from './badge-partial'
+import { Key } from './key'
+import { Alternates } from './alternates'
+
+export class Badge {
+  readonly #partialsIndex: Record<string, BadgePartial> = {}
+
+  /**
+   * The database key for this badge.
+   */
+  readonly key: string
+
+  /**
+   * The type of badge.
+   */
+  readonly type: BadgeType | string
+
+  /**
+   * The name of this badge.
+   *
+   * May vary by character sex or alignment.
+   */
+  readonly name: Alternates<string>
+
+  /**
+   * The character alignments that this badge is available to.
+   */
+  readonly alignment: Alignment[]
+
+  /**
+   * The badge text as it appears in-game. May vary by character sex or alignment.
+   */
+  readonly badgeText: Alternates<string>
+
+  /**
+   * Description of how to acquire the badge.
+   *
+   * Supports {@link https://www.markdownguide.org/|Markdown} format.
+   */
+  readonly acquisition?: string
+
+  /**
+   * Absolute URL to this badge's icon.
+   *
+   * May vary by character sex or alignment.
+   */
+  readonly icon: Alternates<string>
+
+  /**
+   * Freeform notes or tips about the badge.
+   *
+   * Supports {@link https://www.markdownguide.org/|Markdown} format.
+   */
+  readonly notes?: string
+
+  /**
+   * List of external links for this Badge. Wiki, forums, etc.
+   */
+  readonly links?: Link[]
+
+  /**
+   * For exploration badges, the key of the {@link GameMap} that this badge is found on.
+   */
+  readonly mapKey?: string
+
+  /**
+   * For exploration badges, the `/loc` coordinates of the badge on the in-game map.
+   */
+  readonly loc?: [number, number, number]
+
+  /**
+   * For badges that appear on a Vidiot Map, the number or letter the badge appears as.
+   */
+  readonly vidiotMapKey?: string
+
+  /**
+   * ID used with the in-game `/settitle` command to apply the badge.
+   */
+  readonly setTitle?: {
+    /**
+     * `/settitle` id.
+     */
+    id?: number
+    /**
+     * `/settitle` id if different for praetorian characters.
+     */
+    praetorianId?: number
+  }
+
+  /**
+   * A description of the effect the badge will have, such as a buff or granting a temporary power.
+   *
+   * Supports {@link https://www.markdownguide.org/|Markdown} format.
+   */
+  readonly effect?: string
+
+  /**
+   * A list of requirements for badges that have partial fulfilment steps, such as visiting plaques for history badges, or collecting other badges for meta-badges like accolades.
+   */
+  readonly partials?: BadgePartial[]
+
+  /**
+   * Some badges are not included in the badge total count... such as Flames of Prometheus, which can be removed by redeeming it for a Notice of the Well.
+   */
+  readonly ignoreInTotals: boolean
+
+  constructor(data: BadgeData) {
+    this.key = new Key(data.key).value
+    this.type = data.type
+    this.name = new Alternates(data.name)
+    this.alignment = data.alignment
+    this.badgeText = new Alternates(data.badgeText ?? [])
+    this.acquisition = data.acquisition
+    this.icon = new Alternates(data.icon ?? [])
+    this.notes = data.notes
+    this.links = data.links
+    this.mapKey = data.mapKey
+    this.loc = data.loc
+    this.effect = data.effect
+    this.vidiotMapKey = data.vidiotMapKey
+    this.setTitle = data.setTitle
+    this.ignoreInTotals = data.ignoreInTotals ?? false
+
+    this.partials = data.partials?.map((data) => {
+      if (this.#partialsIndex[data.key] !== undefined) throw new Error(`Duplicate badge partial key [${data.key}]`)
+      const badge = new BadgePartial(data)
+      this.#partialsIndex[badge.key] = badge
+      return badge
+    })
+  }
+
+  getPartial(key: string): BadgePartial {
+    const result = this.#partialsIndex[key]
+    if (result === undefined) throw new Error(`Unknown badge partial key [${key}]`)
+    return result
+  }
+}

package/src/main/db/coh-content-database.ts

@@ -0,0 +1,29 @@
+import { ServerGroup } from './server-group'
+import { ServerGroupData } from '../api/server-group-data'
+
+export class CohContentDatabase {
+  readonly #serverGroups: Record<string, ServerGroup> = {}
+
+  /**
+   * Load a server group data package into the database.
+   * @param data The data to load.
+   */
+  loadServerGroupData(data: ServerGroupData): void {
+    this.#serverGroups[data.key] = new ServerGroup(data)
+  }
+
+  /**
+   * Get all the server groups currently loaded in the database.
+   */
+  listServerGroups(): ServerGroup[] {
+    return Object.values(this.#serverGroups)
+  }
+
+  /**
+   * get a server group by key.
+   * @param serverGroupKey The key.
+   */
+  getServerGroup(serverGroupKey: string): ServerGroup | null {
+    return this.#serverGroups[serverGroupKey]
+  }
+}

package/src/main/db/game-map.ts

@@ -0,0 +1,33 @@
+import { VidiotMap } from './vidiot-map'
+import { Link } from '../api/link'
+import { GameMapData } from '../api/game-map-data'
+import { Key } from './key'
+
+export class GameMap {
+  /**
+   * The database key for this map.
+   */
+  readonly key: string
+
+  /**
+   * The name of the map as it appears in-game.
+   */
+  readonly name: string
+
+  /**
+   * List of external links for this Map. Wiki, forums, etc.
+   */
+  readonly links?: Link[]
+
+  /**
+   * List of Vidiot Map assets for this map.
+   */
+  readonly vidiotMaps?: VidiotMap[]
+
+  constructor(data: GameMapData) {
+    this.key = new Key(data.key).value
+    this.name = data.name
+    this.links = data.links
+    this.vidiotMaps = data.vidiotMaps?.map(data => new VidiotMap(data))
+  }
+}

package/src/main/db/key.ts

@@ -0,0 +1,18 @@
+const INVALID_KEY_PATTERN = /[^a-z0-9-]/
+
+export class Key {
+  readonly #value: string
+
+  constructor(value: string) {
+    this.#validateKey(value)
+    this.#value = value
+  }
+
+  get value(): string {
+    return this.#value
+  }
+
+  #validateKey(key: string): void {
+    if (INVALID_KEY_PATTERN.test(key)) throw new Error(`Invalid key: [${key}]; Keys can only contain lowercase characters, numbers and dashes.`)
+  }
+}

package/src/main/db/server-group.ts

@@ -0,0 +1,112 @@
+import { Archetype } from './archetype'
+import { Badge } from './badge'
+import { ServerGroupData } from '../api/server-group-data'
+import { Key } from './key'
+import { Change } from '../api/change'
+import { GameMap } from './game-map'
+import { Link } from '../api/link'
+
+export class ServerGroup {
+  readonly #archetypeIndex: Record<string, Archetype> = {}
+  readonly #mapIndex: Record<string, GameMap> = {}
+  readonly #badgeIndex: Record<string, Badge> = {}
+
+  /**
+   * The database key for this server group.
+   */
+  readonly key: string
+
+  /**
+   * Name of the server group.
+   */
+  readonly name: string
+
+  /**
+   * Description of the server group.
+   *
+   * Supports {@link https://www.markdownguide.org/|Markdown} format.
+   */
+  readonly description?: string
+
+  /**
+   * Repository where the db content package is maintained.
+   */
+  readonly repository?: string
+
+  /**
+   * List of external links for this Server Group. Wiki, forums, etc.
+   */
+  readonly links?: Link[]
+
+  /**
+   * List of the game server names in this server group.
+   * Torchbearer, Excelsior, etc.
+   */
+  readonly servers: string[]
+
+  /**
+   * List of archetypes available in this server group.
+   */
+  readonly archetypes: Archetype[]
+
+  /**
+   * List of game maps supported by this server group.
+   */
+  readonly maps: GameMap[]
+
+  /**
+   * List of badges available on this server group.
+   */
+  readonly badges: Badge[]
+
+  /**
+   * Change log for this data package.
+   */
+  readonly changelog?: Change[]
+
+  constructor(data: ServerGroupData) {
+    this.key = new Key(data.key).value
+    this.name = data.name
+    this.description = data.description
+    this.repository = data.repository
+    this.links = data.links
+    this.servers = data.servers ?? []
+    this.archetypes = data.archetypes?.map((data) => {
+      if (this.#archetypeIndex[data.key] !== undefined) throw new Error(`Duplicate archetype key [${data.key}]`)
+      const archetype = new Archetype(data)
+      this.#archetypeIndex[archetype.key] = archetype
+      return archetype
+    }) ?? []
+    this.maps = data.maps?.map((data) => {
+      if (this.#mapIndex[data.key] !== undefined) throw new Error(`Duplicate map key [${data.key}]`)
+      const map = new GameMap(data)
+      this.#mapIndex[map.key] = map
+      return map
+    }) ?? []
+    this.badges = data.badges?.map((data) => {
+      if (this.#badgeIndex[data.key] !== undefined) throw new Error(`Duplicate badge key [${data.key}]`)
+      const badge = new Badge(data)
+      this.#badgeIndex[badge.key] = badge
+      return badge
+    }) ?? []
+    this.changelog = data.changelog
+  }
+
+  getArchetype(key: string): Archetype {
+    const result = this.#archetypeIndex[key]
+    if (result === undefined) throw new Error(`Unknown archetype key [${key}]`)
+    return result
+  }
+
+  getMap(key: string): GameMap {
+    const result = this.#mapIndex[key]
+    if (result === undefined) throw new Error(`Unknown map key [${key}]`)
+    return result
+  }
+
+  getBadge(key: string): Badge {
+    const result = this.#badgeIndex[key]
+    if (result === undefined) throw new Error(`Unknown badge key [${key}]`)
+    return result
+  }
+}

package/src/main/db/vidiot-map-point-of-interest.ts

@@ -0,0 +1,40 @@
+import { VidiotMapPointOfInterestData } from '../api/vidiot-map-point-of-interest-data'
+
+export class VidiotMapPointOfInterest {
+  /**
+   * The pixel-space position of the PoI on the map graphic.
+   *
+   * Screen-space, pixels from top-left `[0, 0]`.
+   */
+  readonly pos?: [number, number]
+
+  /**
+   * Freeform notes about the PoI.
+   *
+   * Supports {@link https://www.markdownguide.org/|Markdown} format.
+   */
+  readonly notes?: string
+
+  /**
+   * If the POI is a zone transfer, the map it transfers to.
+   */
+  readonly mapKey?: string
+
+  /**
+   * If the POI is a badge, the badge.
+   */
+  readonly badgeKey?: string
+
+  /**
+   * If the POI is a partial for a badge, the partial key.
+   */
+  readonly badgePartialKey?: string
+
+  constructor(data: VidiotMapPointOfInterestData) {
+    this.pos = data.pos
+    this.notes = data.notes
+    this.mapKey = data.mapKey
+    this.badgeKey = data.badgeKey
+    this.badgePartialKey = data.badgePartialKey
+  }
+}

package/src/main/db/vidiot-map.ts

@@ -0,0 +1,25 @@
+import { VidiotMapData } from '../api/vidiot-map-data'
+import { VidiotMapPointOfInterest } from './vidiot-map-point-of-interest'
+
+export class VidiotMap {
+  /**
+   * URL of the map image.
+   */
+  readonly imageUrl: string
+
+  /**
+   * Name to display for the Vidiot map.
+   */
+  readonly name?: string
+
+  /**
+   * List of Points of Interest labelled on the image.
+   */
+  readonly pointsOfInterest?: VidiotMapPointOfInterest[]
+
+  constructor(data: VidiotMapData) {
+    this.imageUrl = data.imageUrl
+    this.name = data.name
+    this.pointsOfInterest = data.pointsOfInterest?.map(data => new VidiotMapPointOfInterest(data))
+  }
+}

package/src/main/index.ts

@@ -0,0 +1,33 @@
+// API
+export * from './api/alignment'
+export * from './api/alternate-data'
+export * from './api/archetype-data'
+export * from './api/badge-data'
+export * from './api/badge-partial-data'
+export * from './api/badge-partial-type'
+export * from './api/badge-type'
+export * from './api/change'
+export * from './api/enhancement-category'
+export * from './api/game-map-data'
+export * from './api/link'
+export * from './api/plaque-type'
+export * from './api/server-group-data'
+export * from './api/sex'
+export * from './api/vidiot-map-data'
+export * from './api/vidiot-map-point-of-interest-data'
+
+// DB
+export * from './db/archetype'
+export * from './db/badge'
+export * from './db/badge-partial'
+export * from './db/coh-content-database'
+export * from './db/game-map'
+export * from './db/key'
+export * from './db/server-group'
+export * from './db/vidiot-map'
+export * from './db/vidiot-map-point-of-interest'
+
+// ROOT
+export { CHANGELOG } from './changelog'
+
+export * from './util'

package/src/main/util.ts

@@ -0,0 +1,17 @@
+/**
+ * Create a reference string that can be used in most text strings to display a link to the given badge.
+ * @param target The badge or badge key to target.
+ */
+export function createBadgeReference(target: string | { key: string }): string {
+  const key = typeof target === 'string' ? target : target.key
+  return `[badge:${key}]`
+}
+
+/**
+ * Create a reference string that can be used in most text strings to display a link to the given map.
+ * @param target The {@link GameMap} or map key to target.
+ */
+export function createMapReference(target: string | { key: string }): string {
+  const key = typeof target === 'string' ? target : target.key
+  return `[map:${key}]`
+}

package/src/test/api/alignment.test.ts

@@ -0,0 +1,31 @@
+import { Alignment, ALIGNMENT } from '../../main'
+
+describe('ALIGNMENT', () => {
+  test('should be an array', () => {
+    expect(Array.isArray(ALIGNMENT)).toBeTruthy()
+  })
+
+  test('should not be empty', () => {
+    expect(ALIGNMENT).not.toHaveLength(0)
+  })
+
+  test('should contain only strings', () => {
+    for (const entry of ALIGNMENT) {
+      expect(typeof entry).toBe('string')
+    }
+  })
+
+  test('should contain all known alignments', () => {
+    const expected = ['H', 'V', 'P']
+    for (const category of expected) {
+      expect(ALIGNMENT).toContain(category)
+    }
+  })
+})
+
+describe('Alignment', () => {
+  test('should be a usable type', () => {
+    const field: Alignment = 'H'
+    expect(field).toBe('H')
+  })
+})

package/src/test/api/archetype-data.fixture.ts

@@ -0,0 +1,8 @@
+import { defineFixture } from 'efate'
+import { ArchetypeData } from '../../main'
+
+export const archetypeDataFixture = defineFixture<ArchetypeData>((t) => {
+  t.key.as(index => `archetype-${index}`)
+  t.name.as(index => `Archetype ${index}`)
+  t.description?.asLoremIpsum()
+})

package/src/test/api/badge-data.fixture.ts

@@ -0,0 +1,22 @@
+import { defineFixture } from 'efate'
+import { ALIGNMENT, BADGE_TYPE, BadgeData } from '../../main'
+import { badgePartialDataFixture } from './badge-partial-data.fixture'
+
+export const badgeDataFixture = defineFixture<BadgeData>((t) => {
+  t.key.as(index => `badge-${index}`)
+  t.type.pickFrom([...BADGE_TYPE])
+  t.name.as(index => [{ value: `Badge ${index}` }])
+  t.alignment.pickFrom([...ALIGNMENT])
+  t.badgeText?.as(index => [{ value: `This is badge ${index}` }])
+  t.acquisition?.asLoremIpsum()
+  t.icon?.asArray([{ value: 'https://nouri.org' }])
+  t.notes?.asLoremIpsum()
+  t.links?.asArray([{ href: 'https://nouri.org' }])
+  t.mapKey?.asString()
+  t.loc?.asArray()
+  t.vidiotMapKey?.asString()
+  t.setTitle?.asArray({ length: 2 })
+  t.effect?.asString()
+  t.partials?.arrayOfFixture({ fixture: badgePartialDataFixture })
+  t.ignoreInTotals?.asBoolean()
+})