coh-content-db 2.0.0-rc.3 → 2.0.0-rc.5

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

@@ -3,20 +3,68 @@ import { PlaqueType } from '../api/plaque-type'
 import { BadgePartialType } from '../api/badge-partial-type'
 import { EnhancementCategory } from '../api/enhancement-category'
 import { Key } from './key'
+import { MarkdownString } from '../api/markdown-string'
 
 export class BadgePartial {
+  /**
+   * Key.
+   */
   readonly key: string
-  readonly type: BadgePartialType | string
+
+  /**
+   * Type of partial.
+   */
+  readonly type: BadgePartialType
+
+  /**
+   * Map the partial is located on.
+   */
   readonly mapKey?: string
+
+  /**
+   * /loc coordinates.
+   */
   readonly loc?: number[]
-  readonly plaqueType?: PlaqueType | string
-  readonly inscription?: string
+
+  /**
+   * Is it a wall plaque or a physical monument?
+   */
+  readonly plaqueType?: PlaqueType
+
+  /**
+   * Plaque inscription.
+   */
+  readonly plaqueInscription?: string
+
+  /**
+   * The number or letter the partial appears as on Vidiot Maps.
+   */
   readonly vidiotMapKey?: string
+
+  /**
+   * The badge required for this partial.
+   */
   readonly badgeKey?: string
+
+  /**
+   * Level of the invention required.
+   */
   readonly inventionLevel?: number
-  readonly inventionTypes?: (EnhancementCategory | string)[]
+
+  /**
+   * The types of enhancements required to be crafted.
+   */
+  readonly inventionTypes?: EnhancementCategory[]
+
+  /**
+   * Number of invention crafts required.
+   */
   readonly inventionCount?: number
-  readonly notes?: string
+
+  /**
+   * Any additional notes.
+   */
+  readonly notes?: MarkdownString
 
   constructor(data: BadgePartialData) {
     this.key = new Key(data.key).value
@@ -24,7 +72,7 @@ export class BadgePartial {
     this.mapKey = data.mapKey
     this.loc = data.loc
     this.plaqueType = data.plaqueType
-    this.inscription = data.inscription
+    this.plaqueInscription = data.plaqueInscription
     this.vidiotMapKey = data.vidiotMapKey
     this.badgeKey = data.badgeKey
     this.inventionLevel = data.inventionLevel

package/src/main/db/badge-search-options.ts

@@ -0,0 +1,51 @@
+import { BadgeType } from '../api/badge-type'
+import { Alignment } from '../api/alignment'
+
+export interface BadgeSearchOptions {
+
+  /**
+   * Text-based search.
+   *
+   * Case-insensitive. Defaults to searching on name only.
+   */
+  query?: {
+    str?: string
+    on?: {
+      name?: boolean
+      badgeText?: boolean
+      acquisition?: boolean
+      notes?: boolean
+      effect?: boolean
+      setTitle?: boolean
+    }
+  }
+
+  /**
+   * Filter results matching the given values.
+   */
+  filter?: {
+    type?: BadgeType
+    mapKey?: string
+    alignment?: Alignment
+  }
+
+  /**
+   * Sort results.
+   *
+   * Badges are assumed to be in canonical order in the content bundle, and should match the in-game display order.
+   */
+  sort?: {
+    by?: 'CANONICAL' | 'BADGE_NAME' | 'MAP_NAME'
+    dir?: 'ASC' | 'DESC'
+  }
+
+  /**
+   * The page (1-based)
+   */
+  page?: number
+
+  /**
+   * How many results per page
+   */
+  pageSize?: number
+}

package/src/main/db/badge.ts

@@ -1,10 +1,11 @@
 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'
+import { Alignments } from './alignments'
+import { MarkdownString } from '../api/markdown-string'
 
 export class Badge {
   readonly #partialsIndex: Record<string, BadgePartial> = {}
@@ -17,7 +18,7 @@ export class Badge {
   /**
    * The type of badge.
    */
-  readonly type: BadgeType | string
+  readonly type: BadgeType
 
   /**
    * The name of this badge.
@@ -29,7 +30,7 @@ export class Badge {
   /**
    * The character alignments that this badge is available to.
    */
-  readonly alignment: Alignment[]
+  readonly alignment: Alignments
 
   /**
    * The badge text as it appears in-game. May vary by character sex or alignment.
@@ -38,10 +39,8 @@ export class Badge {
 
   /**
    * Description of how to acquire the badge.
-   *
-   * Supports {@link https://www.markdownguide.org/|Markdown} format.
    */
-  readonly acquisition?: string
+  readonly acquisition?: MarkdownString
 
   /**
    * Absolute URL to this badge's icon.
@@ -52,10 +51,8 @@ export class Badge {
 
   /**
    * Freeform notes or tips about the badge.
-   *
-   * Supports {@link https://www.markdownguide.org/|Markdown} format.
    */
-  readonly notes?: string
+  readonly notes?: MarkdownString
 
   /**
    * List of external links for this Badge. Wiki, forums, etc.
@@ -93,10 +90,8 @@ export class Badge {
 
   /**
    * 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
+  readonly effect?: MarkdownString
 
   /**
    * 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.
@@ -112,7 +107,7 @@ export class Badge {
     this.key = new Key(data.key).value
     this.type = data.type
     this.name = new Alternates(data.name)
-    this.alignment = data.alignment
+    this.alignment = new Alignments(data.alignment)
     this.badgeText = new Alternates(data.badgeText ?? [])
     this.acquisition = data.acquisition
     this.icon = new Alternates(data.icon ?? [])

package/src/main/db/bundle-metadata.ts

@@ -1,6 +1,7 @@
 import { ContentBundle } from '../api/content-bundle'
 import { Change } from '../api/change'
 import { Link } from '../api/link'
+import { MarkdownString } from '../api/markdown-string'
 
 export class BundleMetadata {
   /**
@@ -10,10 +11,8 @@ export class BundleMetadata {
 
   /**
    * Description of the server group.
-   *
-   * Supports {@link https://www.markdownguide.org/|Markdown} format.
    */
-  readonly description?: string
+  readonly description?: MarkdownString
 
   /**
    * Repository where the db content package is maintained.

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

@@ -3,11 +3,14 @@ import { Archetype } from './archetype'
 import { GameMap } from './game-map'
 import { Badge } from './badge'
 import { BundleMetadata } from './bundle-metadata'
+import { BadgeIndex } from './badge-index'
+import { BadgeSearchOptions } from './badge-search-options'
+import { Paged } from './paged'
 
 export class CohContentDatabase {
   readonly #archetypeIndex: Record<string, Archetype> = {}
   readonly #mapIndex: Record<string, GameMap> = {}
-  readonly #badgeIndex: Record<string, Badge> = {}
+  readonly #badgeIndex: BadgeIndex
 
   /**
    * Metadata about the content bundle.
@@ -42,24 +45,23 @@ export class CohContentDatabase {
   constructor(bundle: ContentBundle) {
     this.metadata = new BundleMetadata(bundle)
     this.servers = bundle.servers ?? []
+
     this.archetypes = bundle.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 = bundle.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 = bundle.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.badges = bundle.badges?.map(data => new Badge(data)) ?? []
+    this.#badgeIndex = new BadgeIndex(this.badges, this.maps)
   }
 
   getArchetype(key: string): Archetype {
@@ -75,8 +77,16 @@ export class CohContentDatabase {
   }
 
   getBadge(key: string): Badge {
-    const result = this.#badgeIndex[key]
-    if (result === undefined) throw new Error(`Unknown badge key [${key}]`)
-    return result
+    return this.#badgeIndex.getBadge(key)
+  }
+
+  /**
+   * Search, sort and filter the badge list.
+   * This is a fairly brute-forced approach and will not be as performant as loading the badge data into a traditional
+   * database engine, but is sufficient for most operations.
+   * @param options {@link BadgeSearchOptions}
+   */
+  searchBadges(options?: BadgeSearchOptions): Paged<Badge> {
+    return this.#badgeIndex.searchBadges(options)
   }
 }

package/src/main/db/paged.ts

@@ -0,0 +1,7 @@
+export interface Paged<T> {
+  items: T[]
+  page: number
+  pageSize?: number
+  totalItems: number
+  totalPages: number
+}

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

@@ -1,4 +1,5 @@
 import { VidiotMapPointOfInterestData } from '../api/vidiot-map-point-of-interest-data'
+import { MarkdownString } from '../api/markdown-string'
 
 export class VidiotMapPointOfInterest {
   /**
@@ -10,10 +11,8 @@ export class VidiotMapPointOfInterest {
 
   /**
    * Freeform notes about the PoI.
-   *
-   * Supports {@link https://www.markdownguide.org/|Markdown} format.
    */
-  readonly notes?: string
+  readonly notes?: MarkdownString
 
   /**
    * If the POI is a zone transfer, the map it transfers to.

package/src/main/index.ts

@@ -10,6 +10,7 @@ export * from './api/change'
 export * from './api/enhancement-category'
 export * from './api/game-map-data'
 export * from './api/link'
+export * from './api/markdown-string'
 export * from './api/plaque-type'
 export * from './api/content-bundle'
 export * from './api/sex'
@@ -17,13 +18,18 @@ export * from './api/vidiot-map-data'
 export * from './api/vidiot-map-point-of-interest-data'
 
 // DB
+export * from './db/alignments'
+export * from './db/alternates'
 export * from './db/archetype'
 export * from './db/badge'
+export * from './db/badge-index'
 export * from './db/badge-partial'
+export * from './db/badge-search-options'
+export * from './db/bundle-metadata'
 export * from './db/coh-content-database'
 export * from './db/game-map'
 export * from './db/key'
-export * from './db/bundle-metadata'
+export * from './db/paged'
 export * from './db/vidiot-map'
 export * from './db/vidiot-map-point-of-interest'
 

package/src/main/util.ts

@@ -1,17 +1,47 @@
 /**
- * Create a reference string that can be used in most text strings to display a link to the given badge.
+ * Returns the URI of the given badge that can be used in {@link MarkdownString} links.
+ *
+ * URI format: `badge://<key>`
+ *
  * @param target The badge or badge key to target.
  */
-export function createBadgeReference(target: string | { key: string }): string {
+export function badgeUri(target: string | { key: string }): string {
   const key = typeof target === 'string' ? target : target.key
-  return `[badge:${key}]`
+  return `badge://${key}`
 }
 
 /**
- * Create a reference string that can be used in most text strings to display a link to the given map.
+ * Returns a {@link MarkdownString} link to the given badge.
+ *
+ * Link format: `[<key>](badge://<key>)`
+ *
+ * @param target The badge or badge key to target.
+ */
+export function badgeLink(target: string | { key: string }): string {
+  const key = typeof target === 'string' ? target : target.key
+  return `[${key}](${badgeUri(target)})`
+}
+
+/**
+ * Returns the URI of the given map that can be used in {@link MarkdownString} links.
+ *
+ * URI format: `map://<key>`
+ *
  * @param target The {@link GameMap} or map key to target.
  */
-export function createMapReference(target: string | { key: string }): string {
+export function mapUri(target: string | { key: string }): string {
+  const key = typeof target === 'string' ? target : target.key
+  return `map://${key}`
+}
+
+/**
+ * Returns a {@link MarkdownString} link to the given map.
+ *
+ * Link format: `[<key>](map://<key>)`
+ *
+ * @param target The map or map key to target.
+ */
+export function mapLink(target: string | { key: string }): string {
   const key = typeof target === 'string' ? target : target.key
-  return `[map:${key}]`
+  return `[${key}](${mapUri(target)})`
 }

package/src/test/api/alignments.test.ts

@@ -0,0 +1,40 @@
+import { Alignments } from '../../main'
+
+describe(Alignments.name, () => {
+  test('should return the raw array', () => {
+    expect(new Alignments(['H', 'V']).items).toStrictEqual(['H', 'V'])
+  })
+
+  test('should detect a hero', () => {
+    expect(new Alignments(['H', 'V']).hero).toBeTruthy()
+  })
+
+  test('should detect a villain', () => {
+    expect(new Alignments(['H', 'V']).villain).toBeTruthy()
+  })
+
+  test('should detect a praetorian', () => {
+    expect(new Alignments(['H', 'V', 'P']).praetorian).toBeTruthy()
+  })
+
+  test('should detect a primal', () => {
+    expect(new Alignments(['H', 'V']).primal).toBeTruthy()
+  })
+
+  test('should not falsely detect a hero', () => {
+    expect(new Alignments(['V']).hero).toBeFalsy()
+  })
+
+  test('should not falsely detect a villain', () => {
+    expect(new Alignments(['H']).villain).toBeFalsy()
+  })
+
+  test('should not falsely detect a praetorian', () => {
+    expect(new Alignments(['V']).praetorian).toBeFalsy()
+  })
+
+  test('should falsely detect a primal', () => {
+    expect(new Alignments(['H', 'V', 'P']).primal).toBeFalsy()
+    expect(new Alignments(['P']).primal).toBeFalsy()
+  })
+})

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

@@ -7,7 +7,7 @@ export const badgePartialDataFixture = defineFixture<BadgePartialData>((t) => {
   t.mapKey?.asString()
   t.loc?.asArray()
   t.plaqueType?.pickFrom([...PLAQUE_TYPE])
-  t.inscription?.asLoremIpsum()
+  t.plaqueInscription?.asLoremIpsum()
   t.vidiotMapKey?.asString()
   t.badgeKey?.as(index => `badge-${index}`)
   t.inventionLevel?.asNumber()

package/src/test/db/alternates.test.ts

@@ -1,4 +1,4 @@
-import { Alternates } from '../../main/db/alternates'
+import { Alternates } from '../../main'
 
 describe(Alternates.name, () => {
   describe('Constructor', () => {
@@ -89,7 +89,7 @@ describe(Alternates.name, () => {
         { alignment: 'H', value: 'Hero' },
         { alignment: 'V', sex: 'M', value: 'Male Villain' },
         { alignment: 'P', sex: 'F', value: 'Praetorian Female' },
-      ]).default).toBe('Default')
+      ]).default?.value).toBe('Default')
 
       expect(new Alternates([
         { alignment: 'V', sex: 'M', value: 'Male Villain' },
@@ -97,14 +97,14 @@ describe(Alternates.name, () => {
         { sex: 'M', value: 'Male' },
         { value: 'Default' },
         { alignment: 'H', value: 'Hero' },
-      ]).default).toBe('Default')
+      ]).default?.value).toBe('Default')
 
       expect(new Alternates([
         { alignment: 'V', sex: 'M', value: 'Male Villain' },
         { alignment: 'P', sex: 'F', value: 'Praetorian Female' },
         { sex: 'M', value: 'Male' },
         { alignment: 'H', value: 'Hero' },
-      ]).default).toBe('Male')
+      ]).default?.value).toBe('Male')
     })
   })
 
@@ -118,64 +118,30 @@ describe(Alternates.name, () => {
         { alignment: 'H', sex: 'F', value: 'Female Hero' },
         { alignment: 'P', value: 'Praetorian' },
         { sex: 'F', value: 'Female' },
-        { alignment: 'H', sex: 'A', value: 'A Hero' },
-        { alignment: 'Y', sex: 'A', value: 'A Y' },
         { alignment: 'V', sex: 'M', value: 'Male Villain' },
-        { alignment: 'V', sex: 'B', value: 'B Villain' },
         { alignment: 'P', sex: 'M', value: 'Male Praetorian' },
         { alignment: 'H', value: 'Hero' },
-        { alignment: 'V', sex: 'A', value: 'A Villain' },
-        { sex: 'A', value: 'A Sex' },
-        { alignment: 'X', sex: 'F', value: 'Female X' },
         { alignment: 'H', sex: 'M', value: 'Male Hero' },
-        { alignment: 'X', value: 'X' },
-        { alignment: 'P', sex: 'B', value: 'B Praetorian' },
-        { alignment: 'P', sex: 'A', value: 'A Praetorian' },
-        { alignment: 'X', sex: 'M', value: 'Male X' },
         { sex: 'M', value: 'Male' },
-        { alignment: 'X', sex: 'B', value: 'B X' },
-        { alignment: 'H', sex: 'B', value: 'B Hero' },
         { alignment: 'V', value: 'Villain' },
-        { alignment: 'Y', sex: 'M', value: 'Male Y' },
         { alignment: 'V', sex: 'F', value: 'Female Villain' },
-        { sex: 'B', value: 'B Sex' },
-        { alignment: 'Y', sex: 'B', value: 'B Y' },
         { alignment: 'P', sex: 'F', value: 'Female Praetorian' },
-        { alignment: 'X', sex: 'A', value: 'A X' },
         { value: 'Default' },
-        { alignment: 'Y', sex: 'F', value: 'Female Y' },
       ]).canonical
 
       expect(result).toStrictEqual([
         { value: 'Default' },
         { sex: 'M', value: 'Male' },
         { sex: 'F', value: 'Female' },
-        { sex: 'A', value: 'A Sex' },
-        { sex: 'B', value: 'B Sex' },
         { alignment: 'H', value: 'Hero' },
         { alignment: 'V', value: 'Villain' },
         { alignment: 'P', value: 'Praetorian' },
-        { alignment: 'X', value: 'X' },
         { alignment: 'H', sex: 'M', value: 'Male Hero' },
         { alignment: 'H', sex: 'F', value: 'Female Hero' },
-        { alignment: 'H', sex: 'A', value: 'A Hero' },
-        { alignment: 'H', sex: 'B', value: 'B Hero' },
         { alignment: 'V', sex: 'M', value: 'Male Villain' },
         { alignment: 'V', sex: 'F', value: 'Female Villain' },
-        { alignment: 'V', sex: 'A', value: 'A Villain' },
-        { alignment: 'V', sex: 'B', value: 'B Villain' },
         { alignment: 'P', sex: 'M', value: 'Male Praetorian' },
         { alignment: 'P', sex: 'F', value: 'Female Praetorian' },
-        { alignment: 'P', sex: 'A', value: 'A Praetorian' },
-        { alignment: 'P', sex: 'B', value: 'B Praetorian' },
-        { alignment: 'X', sex: 'M', value: 'Male X' },
-        { alignment: 'X', sex: 'F', value: 'Female X' },
-        { alignment: 'X', sex: 'A', value: 'A X' },
-        { alignment: 'X', sex: 'B', value: 'B X' },
-        { alignment: 'Y', sex: 'M', value: 'Male Y' },
-        { alignment: 'Y', sex: 'F', value: 'Female Y' },
-        { alignment: 'Y', sex: 'A', value: 'A Y' },
-        { alignment: 'Y', sex: 'B', value: 'B Y' },
       ])
     })
 
@@ -191,41 +157,17 @@ describe(Alternates.name, () => {
       ])
     })
 
-    test('should sort identical values similarly', () => {
+    test('should sort identical values by value alpha', () => {
       expect(new Alternates([
-        { value: 'A' },
-        { value: 'B' },
-        { value: 'C' },
-        { value: 'B' },
-      ]).canonical).toStrictEqual([
-        { value: 'A' },
-        { value: 'B' },
-        { value: 'B' },
-        { value: 'C' },
-      ])
-    })
-
-    test('should sort unknown alignments by alpha', () => {
-      expect(new Alternates([
-        { alignment: 'A', value: 'A' },
-        { alignment: 'C', value: 'C' },
-        { alignment: 'B', value: 'B' },
-      ]).canonical).toStrictEqual([
-        { alignment: 'A', value: 'A' },
-        { alignment: 'B', value: 'B' },
-        { alignment: 'C', value: 'C' },
-      ])
-    })
-
-    test('should sort unknown sex by alpha', () => {
-      expect(new Alternates([
-        { sex: 'A', value: 'A' },
-        { sex: 'C', value: 'C' },
-        { sex: 'B', value: 'B' },
+        { alignment: 'V', value: 'B' },
+        { sex: 'M', value: 'D' },
+        { alignment: 'V', value: 'A' },
+        { sex: 'M', value: 'C' },
       ]).canonical).toStrictEqual([
-        { sex: 'A', value: 'A' },
-        { sex: 'B', value: 'B' },
-        { sex: 'C', value: 'C' },
+        { sex: 'M', value: 'C' },
+        { sex: 'M', value: 'D' },
+        { alignment: 'V', value: 'A' },
+        { alignment: 'V', value: 'B' },
       ])
     })
   })
@@ -233,9 +175,9 @@ describe(Alternates.name, () => {
   describe('toString', () => {
     test('should create a string separated by the separator', () => {
       expect(new Alternates([
-        { sex: 'A', value: 'A' },
-        { sex: 'B', value: 'B' },
-        { sex: 'C', value: 'C' },
+        { sex: 'M', value: 'A' },
+        { sex: 'F', value: 'B' },
+        { alignment: 'H', value: 'C' },
       ]).toString(', ')).toBe('A, B, C')
     })
   })