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

package/README.md

@@ -53,16 +53,40 @@ export const TEST_SERVER_GROUP: ContentBundle = {
 }
 ```
 
+### Markdown and Links
+
+Fields with long text values can typically accept [Markdown](https://www.markdownguide.org/) format. These fields will also be typed with the tag type [MarkdownString](src/main/api/markdown-string.ts).
+
+Within markdown, you can construct a link to a badge or map using the special `badge://` and `map://` protocol indicators that consumer apps can use to provide runtime links or tooltips.
+This replaces the custom `[badge:xyz]` format from v1 and data packages will need to update accordingly.
+
+To create a link, use the standard Markdown link format, with the url as following:
+
+```markdown
+This is a link to the [Ghoulish](badge://ghoulish) badge.
+```
+
+There are convenience functions also provided to construct the URI automatically that can be used as follows:
+
+```typescript
+import { badgeLink, badgeUri } from 'coh-content-db'
+
+const uri = `This is a link to the [Ghoulish](${badgeUri('ghoulish')}) badge.`
+// This is a link to the [Ghoulish](badge://ghoulish) badge.
+const link = `This is a link to the ${badgeLink('ghoulish')} badge.`
+// This is a link to the [ghoulish](badge://ghoulish) badge.
+```
+
 ## As a DB consumer
 
 Create a new database instance, then load a content bundle, such as [coh-content-db-homecoming](https://github.com/n15g/coh-content-db-homecoming):
 
 ```typescript
-import { CohContentDatabase } from 'coh-content-db';
-import { Homecoming } from 'coh-content-db-homecoming';
+import { CohContentDatabase } from 'coh-content-db'
+import { Homecoming } from 'coh-content-db-homecoming'
 
-const db = new CohContentDatabase();
-db.loadBundle(new Homecoming());
+const db = new CohContentDatabase()
+db.loadBundle(new Homecoming())
 ```
 
 #### Access the content

package/dist/coh-content-db.d.ts

@@ -11,11 +11,11 @@ interface AlternateData<V> {
     /**
      * The character alignment this alternate applies to.
      */
-    readonly alignment?: Alignment | string;
+    readonly alignment?: Alignment;
     /**
      * The character sex this alternate applies to.
      */
-    readonly sex?: Sex | string;
+    readonly sex?: Sex;
     /**
      * The value for this combination.
      */
@@ -37,6 +37,11 @@ type BadgePartialType = typeof BADGE_PARTIAL_TYPE[number];
 declare const PLAQUE_TYPE: string[];
 type PlaqueType = typeof PLAQUE_TYPE[number];
 
+/**
+ * Tage type to indicate that a string will accept {@link https://www.markdownguide.org/|Markdown} format.
+ */
+type MarkdownString = string;
+
 interface BadgePartialData {
     /**
      * Key.
@@ -45,7 +50,7 @@ interface BadgePartialData {
     /**
      * Type of partial.
      */
-    readonly type: BadgePartialType | string;
+    readonly type: BadgePartialType;
     /**
      * Map the partial is located on.
      */
@@ -57,11 +62,11 @@ interface BadgePartialData {
     /**
      * Is it a wall plaque or a physical monument?
      */
-    readonly plaqueType?: PlaqueType | string;
+    readonly plaqueType?: PlaqueType;
     /**
      * Plaque inscription.
      */
-    readonly inscription?: string;
+    readonly plaqueInscription?: string;
     /**
      * The number or letter the partial appears as on Vidiot Maps.
      */
@@ -77,7 +82,7 @@ interface BadgePartialData {
     /**
      * The types of enhancements required to be crafted.
      */
-    readonly inventionTypes?: (EnhancementCategory | string)[];
+    readonly inventionTypes?: EnhancementCategory[];
     /**
      * Number of invention crafts required.
      */
@@ -85,7 +90,7 @@ interface BadgePartialData {
     /**
      * Any additional notes.
      */
-    readonly notes?: string;
+    readonly notes?: MarkdownString;
 }
 
 interface Link {
@@ -106,7 +111,7 @@ interface BadgeData {
     /**
      * The type of badge.
      */
-    readonly type: BadgeType | string;
+    readonly type: BadgeType;
     /**
      * The name of this badge.
      *
@@ -123,10 +128,8 @@ interface BadgeData {
     readonly badgeText?: AlternateData<string>[];
     /**
      * Description of how to acquire the badge.
-     *
-     * Supports {@link https://www.markdownguide.org/|Markdown} format.
      */
-    readonly acquisition?: string;
+    readonly acquisition?: MarkdownString;
     /**
      * List of absolute URLs for this badge's icons.
      *
@@ -135,10 +138,8 @@ interface BadgeData {
     readonly icon?: AlternateData<string>[];
     /**
      * 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.
      */
@@ -170,10 +171,8 @@ interface BadgeData {
     };
     /**
      * 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.
      */
@@ -194,9 +193,9 @@ interface Change {
      */
     date: Date;
     /**
-     * Description of the change in {@link https://www.markdownguide.org/|Markdown} format.
+     * Description of the change.
      */
-    description: string;
+    description: MarkdownString;
 }
 
 interface VidiotMapPointOfInterestData {
@@ -208,10 +207,8 @@ interface VidiotMapPointOfInterestData {
     readonly pos?: [number, number];
     /**
      * 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.
      */
@@ -272,10 +269,8 @@ interface ContentBundle {
     readonly name: string;
     /**
      * Description of the fork.
-     *
-     * Supports {@link https://www.markdownguide.org/|Markdown} format.
      */
-    readonly description?: string;
+    readonly description?: MarkdownString;
     /**
      * Repository where the db content package is maintained.
      */
@@ -307,6 +302,34 @@ interface ContentBundle {
     readonly changelog?: Change[];
 }
 
+declare class Alignments {
+    readonly items: Alignment[];
+    readonly hero: boolean;
+    readonly villain: boolean;
+    readonly praetorian: boolean;
+    readonly primal: boolean;
+    constructor(raw: Alignment[]);
+}
+
+declare class Alternates<T> {
+    #private;
+    constructor(values: AlternateData<T>[]);
+    getValue(alignment?: Alignment, sex?: Sex): T | undefined;
+    /**
+     * Get the default value for this list of alternates, the value with the highest priority and lowest specificity.
+     */
+    get default(): AlternateData<T> | undefined;
+    /**
+     * Get the list of alternates sorted in canonical order (alignment then sex, low to high specificity).
+     */
+    get canonical(): AlternateData<T>[];
+    /**
+     * Create a joined string from the alternate values in canonical order.
+     * @param separator Separator to use. Default is ' / '
+     */
+    toString(separator: string): string;
+}
+
 declare class Archetype {
     readonly key: string;
     readonly name: string;
@@ -315,38 +338,55 @@ declare class Archetype {
 }
 
 declare 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)[];
-    readonly inventionCount?: number;
-    readonly notes?: string;
-    constructor(data: BadgePartialData);
-}
-
-declare class Alternates<T> {
-    #private;
-    constructor(values: AlternateData<T>[]);
-    getValue(alignment?: Alignment | string, sex?: Sex | string): T | undefined;
     /**
-     * Get the default value for this list of alternates, the value with the highest priority and lowest specificity.
+     * The types of enhancements required to be crafted.
      */
-    get default(): T | undefined;
+    readonly inventionTypes?: EnhancementCategory[];
     /**
-     * Get the list of alternates sorted in canonical order (alignment then sex, low to high specificity).
+     * Number of invention crafts required.
      */
-    get canonical(): AlternateData<T>[];
+    readonly inventionCount?: number;
     /**
-     * Create a joined string from the alternate values in canonical order.
-     * @param separator Separator to use. Default is ' / '
+     * Any additional notes.
      */
-    toString(separator: string): string;
+    readonly notes?: MarkdownString;
+    constructor(data: BadgePartialData);
 }
 
 declare class Badge {
@@ -358,7 +398,7 @@ declare class Badge {
     /**
      * The type of badge.
      */
-    readonly type: BadgeType | string;
+    readonly type: BadgeType;
     /**
      * The name of this badge.
      *
@@ -368,17 +408,15 @@ declare 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.
      */
     readonly badgeText: Alternates<string>;
     /**
      * 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.
      *
@@ -387,10 +425,8 @@ declare class Badge {
     readonly icon: Alternates<string>;
     /**
      * 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.
      */
@@ -422,10 +458,8 @@ declare 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.
      */
@@ -438,6 +472,50 @@ declare class Badge {
     getPartial(key: string): BadgePartial;
 }
 
+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;
+}
+
 declare class VidiotMapPointOfInterest {
     /**
      * The pixel-space position of the PoI on the map graphic.
@@ -447,10 +525,8 @@ declare class VidiotMapPointOfInterest {
     readonly pos?: [number, number];
     /**
      * 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.
      */
@@ -502,6 +578,21 @@ declare class GameMap {
     constructor(data: GameMapData);
 }
 
+interface Paged<T> {
+    items: T[];
+    page: number;
+    pageSize?: number;
+    totalItems: number;
+    totalPages: number;
+}
+
+declare class BadgeIndex {
+    #private;
+    constructor(badges: Badge[], maps?: GameMap[]);
+    getBadge(key: string): Badge;
+    searchBadges(options?: BadgeSearchOptions): Paged<Badge>;
+}
+
 declare class BundleMetadata {
     /**
      * Name of the server group.
@@ -509,10 +600,8 @@ declare class BundleMetadata {
     readonly name: string;
     /**
      * 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.
      */
@@ -559,7 +648,13 @@ declare class CohContentDatabase {
     getArchetype(key: string): Archetype;
     getMap(key: string): GameMap;
     getBadge(key: string): Badge;
-    searchBadges(query?: string): Badge[];
+    /**
+     * 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>;
 }
 
 declare class Key {
@@ -571,18 +666,44 @@ declare class Key {
 declare const CHANGELOG: Change[];
 
 /**
- * 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.
+ */
+declare function badgeUri(target: string | {
+    key: string;
+}): string;
+/**
+ * Returns a {@link MarkdownString} link to the given badge.
+ *
+ * Link format: `[<key>](badge://<key>)`
+ *
  * @param target The badge or badge key to target.
  */
-declare function createBadgeReference(target: string | {
+declare function badgeLink(target: string | {
     key: string;
 }): string;
 /**
- * Create a reference string that can be used in most text strings to display a link to the given map.
+ * 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.
  */
-declare function createMapReference(target: string | {
+declare function mapUri(target: string | {
+    key: string;
+}): string;
+/**
+ * Returns a {@link MarkdownString} link to the given map.
+ *
+ * Link format: `[<key>](map://<key>)`
+ *
+ * @param target The map or map key to target.
+ */
+declare function mapLink(target: string | {
     key: string;
 }): string;
 
-export { ALIGNMENT, type Alignment, type AlternateData, Archetype, type ArchetypeData, BADGE_PARTIAL_TYPE, BADGE_TYPE, Badge, type BadgeData, BadgePartial, type BadgePartialData, type BadgePartialType, type BadgeType, BundleMetadata, CHANGELOG, type Change, CohContentDatabase, type ContentBundle, ENHANCEMENT_CATEGORY, type EnhancementCategory, GameMap, type GameMapData, Key, type Link, PLAQUE_TYPE, type PlaqueType, SEX, type Sex, VidiotMap, type VidiotMapData, VidiotMapPointOfInterest, type VidiotMapPointOfInterestData, createBadgeReference, createMapReference };
+export { ALIGNMENT, type Alignment, Alignments, type AlternateData, Alternates, Archetype, type ArchetypeData, BADGE_PARTIAL_TYPE, BADGE_TYPE, Badge, type BadgeData, BadgeIndex, BadgePartial, type BadgePartialData, type BadgePartialType, type BadgeSearchOptions, type BadgeType, BundleMetadata, CHANGELOG, type Change, CohContentDatabase, type ContentBundle, ENHANCEMENT_CATEGORY, type EnhancementCategory, GameMap, type GameMapData, Key, type Link, type MarkdownString, PLAQUE_TYPE, type Paged, type PlaqueType, SEX, type Sex, VidiotMap, type VidiotMapData, VidiotMapPointOfInterest, type VidiotMapPointOfInterestData, badgeLink, badgeUri, mapLink, mapUri };