coh-content-db 2.0.0-rc.9 → 2.0.0

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

@@ -11,28 +11,6 @@ type AlignmentExtended = Alignment
  | 'all';
 declare function compareAlignment(a?: Alignment, b?: Alignment): number;
 
-declare const SEX: readonly ["M", "F"];
-type Sex = typeof SEX[number];
-declare function compareSex(a?: Sex, b?: Sex): number;
-
-/**
- * Some badge values differ based on the alignment or sex of the character.
- */
-interface AlternateData<V> {
-    /**
-     * The character alignment this alternate applies to.
-     */
-    readonly alignment?: Alignment;
-    /**
-     * The character sex this alternate applies to.
-     */
-    readonly sex?: Sex;
-    /**
-     * The value for this combination.
-     */
-    readonly value: V;
-}
-
 interface ArchetypeData {
     readonly key: string;
     readonly name: string;
@@ -131,37 +109,41 @@ interface BadgeRequirementData {
 declare const BADGE_TYPE: readonly ["exploration", "history", "accomplishment", "achievement", "accolade", "gladiator", "veteran", "pvp", "invention", "defeat", "event", "ouroboros", "consignment", "day-job", "architect-entertainment"];
 type BadgeType = typeof BADGE_TYPE[number];
 
-declare const MORALITY: readonly ["hero", "vigilante", "villain", "rogue", "resistance", "loyalist"];
-type Morality = typeof MORALITY[number];
-type MoralityExtended = Morality
-/**
- * Any of the Primal Earth moralities - Hero, Vigilante, Villain, Rogue.
- */
- | 'primal'
-/**
- * Either of the Praetorian Earth moralities - Resistance or Loyalist.
- */
- | 'praetorian'
-/**
- * The moralities that roll up to the Hero {@link Alignment} - Hero and Vigilante.
- */
- | 'heroic'
-/**
- * The moralities that roll up to the Villain {@link Alignment} - Villain and Rogue.
- */
- | 'villainous'
+declare const SEX: readonly ["M", "F"];
+type Sex = typeof SEX[number];
+declare function compareSex(a?: Sex, b?: Sex): number;
+
 /**
- * Moralities with access to Paragon City - Hero, Vigilante and Rogue.
+ * Some badge values differ based on the alignment or sex of a character.
  */
- | 'paragon-city-access'
+interface VariantData<V> {
+    /**
+     * The character alignment this variant applies to.
+     */
+    readonly alignment?: Alignment;
+    /**
+     * The character sex this variant applies to.
+     */
+    readonly sex?: Sex;
+    /**
+     * The value for this combination.
+     */
+    readonly value: V;
+}
+
+declare const MORALITY: readonly ["hero", "vigilante", "villain", "rogue", "resistance", "loyalist"];
+declare const MORALITY_EXTENDED: readonly ["hero", "vigilante", "villain", "rogue", "resistance", "loyalist", "primal", "praetorian", "heroic", "villainous", "paragon-city-access", "rogue-isles-access", "all"];
+type Morality = typeof MORALITY[number];
+type MoralityExtended = typeof MORALITY_EXTENDED[number];
 /**
- * Moralities with access to the Rogue Isles - Villain, Rogue and Vigilante.
+ * Maps a morality to the underlying alignment
  */
- | 'rogue-isles-access'
+declare const MoralityMap: Record<Morality | Alignment, Alignment>;
+
 /**
- * All the moralities.
+ * The id, or a pair of ids [primal, praetorian] that are used with the /settitle command to set a badge
  */
- | 'all';
+type SetTitleData = [number, number?];
 
 interface BadgeData {
     /**
@@ -177,9 +159,13 @@ interface BadgeData {
     /**
      * The name of this badge.
      *
-     * If the value differs by sex or alignment, include an {@link AlternateData} for each variant.
+     * If the value differs by sex or alignment, include an {@link VariantData} for each variant.
      */
-    readonly name: string | AlternateData<string>[];
+    readonly name: string | VariantData<string>[];
+    /**
+     * The date that the badge was added to the game.
+     */
+    readonly releaseDate: string;
     /**
      * The {@link MoralityExtended|moralities} that this badge is available to. If undefined then all moralities will be assumed.
      */
@@ -187,7 +173,7 @@ interface BadgeData {
     /**
      * The badge text as it appears in-game. May vary by character sex or alignment.
      */
-    readonly badgeText?: AlternateData<MarkdownString>[] | MarkdownString;
+    readonly badgeText?: VariantData<MarkdownString>[] | MarkdownString;
     /**
      * Short description of how to acquire the badge. Detailed instructions should go in the notes field.
      */
@@ -195,9 +181,9 @@ interface BadgeData {
     /**
      * List of absolute URLs for this badge's icons.
      *
-     * If the value differs by sex or alignment, include an {@link AlternateData} for each variant.
+     * If the value differs by sex or alignment, include an {@link VariantData} for each variant.
      */
-    readonly icon?: string | AlternateData<string>[];
+    readonly icon?: string | VariantData<string>[];
     /**
      * Freeform notes or tips about the badge.
      */
@@ -210,7 +196,7 @@ interface BadgeData {
      * The id used with the in-game `/settitle` command to apply the badge.
      * The first value is the id for primal characters and the (optional) second number is the id for praetorian characters.
      */
-    readonly setTitleId?: [number, number?];
+    readonly setTitleId?: SetTitleData;
     /**
      * A description of the effect the badge will have, such as a buff or granting a temporary power.
      */
@@ -225,6 +211,14 @@ interface BadgeData {
     readonly ignoreInTotals?: boolean;
 }
 
+declare const ZONE_TYPE: readonly ["city", "echo", "tutorial", "trial", "hazard", "mayhem", "safeguard", "mission", "incarnate", "co-op", "pvp", "arena", "building", "other"];
+type ZoneType = typeof ZONE_TYPE[number];
+
+/**
+ * Can be an array of [min, max], just the [min], or a number representing the minimum value
+ */
+type LevelRangeData = [number, number?] | number;
+
 interface ZoneData {
     /**
      * Unique key used to reference this zone.
@@ -236,6 +230,22 @@ interface ZoneData {
      * The name of the zone as it appears in-game.
      */
     readonly name: string;
+    /**
+     * The type of zone.
+     */
+    readonly type: ZoneType;
+    /**
+     * The character moralities that this zone is accessible by.
+     */
+    readonly morality?: MoralityExtended | MoralityExtended[];
+    /**
+     * The level range this zone is recommended for.
+     */
+    readonly levelRange?: LevelRangeData;
+    /**
+     * Freeform notes or tips about the zone.
+     */
+    readonly notes?: MarkdownString;
     /**
      * List of external links. Wiki, forums, etc.
      */
@@ -268,7 +278,7 @@ interface ContactData {
     /**
      * The level range this contact will offer missions for.
      */
-    readonly levelRange?: [number, number?];
+    readonly levelRange?: LevelRangeData;
     /**
      * Freeform notes or tips about the contact.
      */
@@ -282,6 +292,29 @@ interface ContactData {
 declare const MISSION_TYPE: readonly ["story-arc", "mission", "task-force", "strike-force", "trial", "personal-story"];
 type MissionType = typeof MISSION_TYPE[number];
 
+interface MissionFlashbackData {
+    /**
+     * The id of the mission as seen in the Flashback menu, i.e. '14.01'.
+     */
+    readonly id: string;
+    /**
+     * The level range this mission appears under as a Flashback.
+     */
+    readonly levelRange?: LevelRangeData;
+    /**
+     * The name as it appears in the Flashback list. Leave undefined if the same as the base mission.
+     */
+    readonly name?: string;
+    /**
+     * The character moralities that the mission will appear for in the Flashback list. Leave undefined if the same as the base mission.
+     */
+    readonly morality?: MoralityExtended | MoralityExtended[];
+    /**
+     * Freeform notes or tips about the Flashback version of the mission.
+     */
+    readonly notes?: MarkdownString;
+}
+
 interface MissionData {
     /**
      * Unique key used to reference this mission.
@@ -310,7 +343,7 @@ interface MissionData {
     /**
      * The level range this mission is available for.
      */
-    readonly levelRange?: [number, number?];
+    readonly levelRange?: LevelRangeData;
     /**
      * Freeform notes or tips about the mission.
      */
@@ -324,28 +357,6 @@ interface MissionData {
      */
     readonly flashback?: MissionFlashbackData;
 }
-interface MissionFlashbackData {
-    /**
-     * The id of the mission as seen in the Flashback menu, i.e. '14.01'.
-     */
-    readonly id: string;
-    /**
-     * The level range this mission appears under as a Flashback. Leave undefined if the same as the base mission.
-     */
-    readonly levelRange?: [number, number?];
-    /**
-     * The name as it appears in the Flashback list. Leave undefined if the same as the base mission.
-     */
-    readonly name?: string;
-    /**
-     * The character moralities that the mission will appear for in the Flashback list. Leave undefined if the same as the base mission.
-     */
-    readonly morality?: MoralityExtended | MoralityExtended[];
-    /**
-     * Freeform notes or tips about the Flashback version of the mission.
-     */
-    readonly notes?: MarkdownString;
-}
 
 /**
  * Metadata about a content bundle.
@@ -354,7 +365,17 @@ interface BundleHeaderData {
     /**
      * Name of the fork this bundle contains data for.
      */
-    readonly name?: string;
+    readonly name: string;
+    /**
+     * Version number for this data package.
+     */
+    readonly version: string;
+    /**
+     * The time this bundle was last updated.
+     *
+     * Must be an ISO-8601 string in UTC.
+     */
+    readonly lastUpdateTime: string;
     /**
      * Description of the fork.
      */
@@ -371,10 +392,6 @@ interface BundleHeaderData {
      * List of external links. Wiki, forums, etc.
      */
     readonly links?: Link[];
-    /**
-     * Version number for this data package.
-     */
-    readonly version?: string;
 }
 
 /**
@@ -384,7 +401,7 @@ interface BundleData {
     /**
      * Bundle header.
      */
-    readonly header?: BundleHeaderData;
+    readonly header: BundleHeaderData;
     /**
      * List of the game server names in this fork.
      * Torchbearer, Excelsior, etc.
@@ -412,6 +429,14 @@ interface BundleData {
     readonly badges?: BadgeData[];
 }
 
+/**
+ * For badges, aspects like the name, icon, or badge text can vary depending on context, such as the alignment or sex of the character.
+ */
+interface VariantContext {
+    readonly morality?: Morality | Alignment;
+    readonly sex?: Sex;
+}
+
 declare class AlignmentList {
     #private;
     readonly hero: boolean;
@@ -424,29 +449,6 @@ declare class AlignmentList {
     has(alignment?: AlignmentExtended): boolean;
 }
 
-declare class Alternates<T> {
-    #private;
-    /**
-     * Create an alternate set from either a list of categorized values, or a single value when there are no alternates.
-     * @param value List of alternates, or a single value.
-     */
-    constructor(value: AlternateData<T>[] | 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;
@@ -524,6 +526,38 @@ declare class BadgeRequirement {
     constructor(data: BadgeRequirementData);
 }
 
+declare class Variants<T> {
+    #private;
+    /**
+     * Create a variant set from either a list of categorized values, or a single value when there are no variants.
+     * @param value List of variants, or a single value.
+     */
+    constructor(value: VariantData<T>[] | T);
+    /**
+     * Get a variant by context
+     * @param context The context
+     */
+    getVariant(context?: VariantContext): VariantData<T> | undefined;
+    /**
+     * Get a value by variant context
+     * @param context The context
+     */
+    getValue(context?: VariantContext): T | undefined;
+    /**
+     * Get the default value for this list of variants, the value with the highest priority and lowest specificity.
+     */
+    get default(): VariantData<T> | undefined;
+    /**
+     * Get the list of variants sorted in canonical order (alignment then sex, low to high specificity).
+     */
+    get canonical(): VariantData<T>[];
+    /**
+     * Create a joined string from the variant values in canonical order.
+     * @param separator Separator to use. Default is ' / '
+     */
+    toString(separator: string): string;
+}
+
 declare class MoralityList {
     #private;
     readonly hero: boolean;
@@ -544,6 +578,12 @@ declare class MoralityList {
     has(morality?: MoralityExtended): boolean;
 }
 
+declare class SetTitleIds {
+    readonly primal: number;
+    readonly praetorian?: number;
+    constructor(value: SetTitleData);
+}
+
 declare class Badge {
     #private;
     /**
@@ -559,7 +599,11 @@ declare class Badge {
      *
      * May vary by character sex or alignment.
      */
-    readonly name: Alternates<string>;
+    readonly name: Variants<string>;
+    /**
+     * The date that the badge was added to the game.
+     */
+    readonly releaseDate: Date;
     /**
      * The character moralities that this badge is available to.
      */
@@ -567,7 +611,7 @@ declare class Badge {
     /**
      * The badge text as it appears in-game. May vary by character sex or alignment.
      */
-    readonly badgeText: Alternates<MarkdownString>;
+    readonly badgeText: Variants<MarkdownString>;
     /**
      * Short description of how to acquire the badge. Detailed instructions will be in the notes field.
      */
@@ -577,7 +621,7 @@ declare class Badge {
      *
      * May vary by character sex or alignment.
      */
-    readonly icon: Alternates<string>;
+    readonly icon: Variants<string>;
     /**
      * Freeform notes or tips about the badge.
      */
@@ -590,21 +634,21 @@ declare class Badge {
      * The id used with the in-game `/settitle` command to apply the badge.
      * The first value is the id for primal characters and the (optional) second number is the id for praetorian characters.
      */
-    readonly setTitleId?: [number, number?];
+    readonly setTitleId?: SetTitleIds;
     /**
      * A description of the effect the badge will have, such as a buff or granting a temporary power.
      */
     readonly effect?: MarkdownString;
-    /**
-     * Represents the requirements for badges with multiple fulfillment steps, such as visiting monuments for history badges, completing missions, or collecting other badges.
-     */
-    readonly requirements?: BadgeRequirement[];
     /**
      * 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(badgeData: BadgeData);
-    getRequirement(key: string): BadgeRequirement;
+    /**
+     * Represents the requirements for badges with multiple fulfillment steps, such as visiting monuments for history badges, completing missions, or collecting other badges.
+     */
+    get requirements(): BadgeRequirement[];
+    getRequirement(key: string): BadgeRequirement | undefined;
     /**
      * Return a list of all the zone keys referenced by this badge.
      */
@@ -614,9 +658,12 @@ declare class Badge {
      */
     get zoneKey(): string | undefined;
 }
-declare function compareByDefaultName(a?: Badge, b?: Badge): number;
+declare function compareByName(a?: Badge, b?: Badge, context?: VariantContext): number;
 declare function compareByZoneKey(a?: Badge, b?: Badge): number;
+declare function compareByReleaseDate(a?: Badge, b?: Badge): number;
 
+type BadgeQueryableField = 'name' | 'badge-text' | 'acquisition' | 'notes' | 'effect' | 'set-title-id';
+type BadgeSort = `${'canonical' | 'name' | 'zone-key' | 'release-date'}.${'asc' | 'desc'}`;
 interface BadgeSearchOptions {
     /**
      * Text-based search.
@@ -625,14 +672,7 @@ interface BadgeSearchOptions {
      */
     query?: {
         str?: string;
-        on?: {
-            name?: boolean;
-            badgeText?: boolean;
-            acquisition?: boolean;
-            notes?: boolean;
-            effect?: boolean;
-            setTitle?: boolean;
-        };
+        fields?: BadgeQueryableField[];
     };
     /**
      * Filter results matching the given values.
@@ -640,17 +680,19 @@ interface BadgeSearchOptions {
     filter?: {
         type?: BadgeType;
         zoneKey?: string;
-        morality?: MoralityExtended;
+        morality?: Morality;
+        predicate?: (badge: Badge) => boolean;
     };
+    /**
+     * Adjust search results based on a given variant context (morality or sex of a character).
+     */
+    context?: VariantContext;
     /**
      * 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' | 'zone-key';
-        dir?: 'asc' | 'desc';
-    };
+    sort?: BadgeSort;
     /**
      * The page (1-based)
      */
@@ -663,29 +705,30 @@ interface BadgeSearchOptions {
 
 interface Paged<T> {
     items: T[];
-    page: number;
+    matchedItemCount: number;
+    totalItemCount: number;
     pageSize?: number;
-    totalItems: number;
-    totalPages: number;
+    pageIndex: number;
+    pageNumber: number;
+    totalPageCount: number;
 }
 
 type KeysOfType<T, V> = {
     [P in keyof T]: T[P] extends V ? P : never;
 }[keyof T];
 declare class AbstractIndex<T> {
-    #private;
     protected _values: T[];
     protected _hashTable: Record<string, T>;
-    constructor(keyField: KeysOfType<T, string>);
     /**
-     * Return all indexed values
+     * Create a new index.
+     * @param keyField The field of the values that will act as the key.
+     * @param values Values to index.
      */
-    get values(): T[];
+    constructor(keyField: KeysOfType<T, string>, values: T[] | undefined);
     /**
-     * Load the given list of values into the index, replacing any existing data.
-     * @param values List of values.
+     * Return all indexed values
      */
-    load(values: T[] | undefined): void;
+    get values(): T[];
     /**
      * Get a value from the index
      * @param key Key string
@@ -695,15 +738,23 @@ declare class AbstractIndex<T> {
 
 declare class BadgeIndex extends AbstractIndex<Badge> {
     #private;
-    constructor();
+    constructor(values: Badge[] | undefined);
     search(options?: BadgeSearchOptions): Paged<Badge>;
 }
 
 declare class BundleHeader {
     /**
-     * Name of the content bundle.
+     * Name of the fork this bundle contains data for.
      */
-    readonly name?: string;
+    readonly name: string;
+    /**
+     * Version number for this data package.
+     */
+    readonly version: string;
+    /**
+     * The time this bundle was last updated.
+     */
+    readonly lastUpdateTime: Date;
     /**
      * Description of the fork.
      */
@@ -720,11 +771,13 @@ declare class BundleHeader {
      * List of external links. Wiki, forums, etc.
      */
     readonly links?: Link[];
-    /**
-     * The current version of the data package.
-     */
-    readonly version?: string;
-    constructor(data: BundleHeaderData | undefined);
+    constructor(data: BundleHeaderData);
+}
+
+declare class LevelRange {
+    readonly min: number;
+    readonly max?: number;
+    constructor(value: LevelRangeData);
 }
 
 declare class Zone {
@@ -738,6 +791,22 @@ declare class Zone {
      * The name of the zone as it appears in-game.
      */
     readonly name: string;
+    /**
+     * The type of zone.
+     */
+    readonly type: ZoneType;
+    /**
+     * The character moralities that this zone is accessible by.
+     */
+    readonly morality: MoralityList;
+    /**
+     * The level range this zone is recommended for.
+     */
+    readonly levelRange?: LevelRange;
+    /**
+     * Freeform notes or tips about the zone.
+     */
+    readonly notes?: MarkdownString;
     /**
      * List of external links. Wiki, forums, etc.
      */
@@ -763,7 +832,7 @@ declare class Contact {
     /**
      * The character moralities that this contact will interact with.
      */
-    readonly morality?: MoralityList;
+    readonly morality: MoralityList;
     /**
      * The location of this contact.
      */
@@ -771,7 +840,7 @@ declare class Contact {
     /**
      * The level range this contact will offer missions for.
      */
-    readonly levelRange?: [number, number?];
+    readonly levelRange?: LevelRange;
     /**
      * Freeform notes or tips about the contact.
      */
@@ -811,7 +880,7 @@ declare class Mission {
     /**
      * The level range this mission is available for.
      */
-    readonly levelRange?: [number, number?];
+    readonly levelRange?: LevelRange;
     /**
      * Freeform notes or tips about the mission.
      */
@@ -829,17 +898,17 @@ declare class Mission {
          */
         readonly id: string;
         /**
-         * The level range this mission appears under as a Flashback. Leave undefined if the same as the base mission.
+         * The level range this mission appears under as a Flashback.
          */
-        readonly levelRange?: [number, number?];
+        readonly levelRange?: LevelRange;
         /**
-         * The name as it appears in the Flashback list. Leave undefined if the same as the base mission.
+         * The name as it appears in the Flashback list.
          */
-        readonly name?: string;
+        readonly name: string;
         /**
-         * The character moralities that the mission will appear for in the Flashback list. Leave undefined if the same as the base mission.
+         * The character moralities that the mission will appear for in the Flashback list.
          */
-        readonly morality?: MoralityList;
+        readonly morality: MoralityList;
         /**
          * Freeform notes or tips about the Flashback version of the mission.
          */
@@ -851,14 +920,14 @@ declare class Mission {
 declare class CohContentDatabase {
     #private;
     /**
-     * Load the given content bundle, resetting the db if a bundle is already loaded.
+     * Create a db instance from the given content bundle.
      * @param bundle The bundle to load.
      */
-    load(bundle: BundleData): void;
+    constructor(bundle: BundleData);
     /**
      * Header information about the content bundle.
      */
-    get header(): BundleHeader | undefined;
+    get header(): BundleHeader;
     /**
      * List of the game server names.
      *
@@ -989,15 +1058,6 @@ declare function zoneUri(target: string | Zone | ZoneData): string;
  * @param target The {@link Zone} or zone key to target.
  */
 declare function zoneLink(target: string | Zone | ZoneData): string;
-/**
- * For fields that accept either an array of values or a single value, coalesces the value to an array.
- *
- * Arrays are returned as-is.
- * Single values are returned as a single-value array.
- * Undefined values are returned as undefined.
- *
- * @param value The value to coalesce.
- */
-declare function coalesceToArray<T>(value?: T | T[]): T[] | undefined;
 
-export { ALIGNMENT, type Alignment, type AlignmentExtended, AlignmentList, type AlternateData, Alternates, Archetype, type ArchetypeData, BADGE_REQUIREMENT_TYPE, BADGE_TYPE, Badge, type BadgeData, BadgeIndex, BadgeRequirement, type BadgeRequirementData, type BadgeRequirementType, type BadgeSearchOptions, type BadgeType, type BundleData, BundleHeader, type BundleHeaderData, CohContentDatabase, Contact, type ContactData, type Coords, ENHANCEMENT_CATEGORY, type EnhancementCategory, Key, type Link, Location, type LocationData, type LocationIcon, MISSION_TYPE, MORALITY, type MarkdownString, Mission, type MissionData, type MissionFlashbackData, type MissionType, type Morality, type MoralityExtended, MoralityList, type Paged, SEX, type Sex, Zone, type ZoneData, badgeLink, badgeUri, coalesceToArray, compareAlignment, compareByDefaultName, compareByZoneKey, compareSex, contactLink, contactUri, missionLink, missionUri, zoneLink, zoneUri };
+export { ALIGNMENT, AlignmentList, Archetype, BADGE_REQUIREMENT_TYPE, BADGE_TYPE, Badge, BadgeIndex, BadgeRequirement, BundleHeader, CohContentDatabase, Contact, ENHANCEMENT_CATEGORY, Key, LevelRange, Location, MISSION_TYPE, MORALITY, MORALITY_EXTENDED, Mission, MoralityList, MoralityMap, SEX, SetTitleIds, Variants, ZONE_TYPE, Zone, badgeLink, badgeUri, compareAlignment, compareByName, compareByReleaseDate, compareByZoneKey, compareSex, contactLink, contactUri, missionLink, missionUri, zoneLink, zoneUri };
+export type { Alignment, AlignmentExtended, ArchetypeData, BadgeData, BadgeQueryableField, BadgeRequirementData, BadgeRequirementType, BadgeSearchOptions, BadgeSort, BadgeType, BundleData, BundleHeaderData, ContactData, Coords, EnhancementCategory, LevelRangeData, Link, LocationData, LocationIcon, MarkdownString, MissionData, MissionFlashbackData, MissionType, Morality, MoralityExtended, Paged, SetTitleData, Sex, VariantContext, VariantData, ZoneData, ZoneType };