Enums For Everything & File Organization

.eslintrc.json

@@ -69,6 +69,7 @@
       "prefer-template": "off",
       "func-style": "off",
       "@typescript-eslint/no-this-alias": "off",
-      "github/array-foreach": "off"
+      "github/array-foreach": "off",
+      "no-explicit-any": "off"
   }
-}
+}

package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "fomod",
   "description": "A library for creating, parsing, editing, and validating XML-based Fomod installers, widely popularized in the Bethesda modding scene",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "main": "dist/index.js",
   "repository": "https://github.com/BellCubeDev/fomod-js/",
   "bugs": {

src/DomUtils.ts

@@ -1,3 +1,15 @@
+import { TagName } from "./definitions";
+
+/** Searches for an existing tag by the provided name. If one does not yet exist, create one instead.
+ *
+ * @param fromElement The parent element
+ * @param tagName The tag name to search for, restricted to members of the TagName enum
+ * @returns The first element by the provided tagname or a new one if it did not yet exist.
+ */
+export function getOrCreateElementByTagNameSafe(fromElement: Element, tagName: TagName): Element {
+    return getOrCreateElementByTagName(fromElement, tagName);
+}
+
 /** Searches for an existing tag by the provided name. If one does not yet exist, create one instead.
  *
  * @param fromElement The parent element

src/definitions/Enums.ts

@@ -0,0 +1,180 @@
+/** A valid tag for an XML-Based Fomod installer */
+export enum TagName {
+    Fomod = 'fomod',
+    Config = 'config',
+        ModuleName = 'moduleName',
+        ModuleImage = 'moduleImage',
+        ModuleDependencies = 'moduleDependencies',
+            Dependencies = 'dependencies',
+                // Dependencies = 'dependencies',
+                FileDependency = 'fileDependency',
+                FlagDependency = 'flagDependency',
+                GameDependency = 'gameDependency',
+                FOMMDependency = 'fommDependency',
+                FOSEDependency = 'foseDependency',
+        RequiredInstallFiles = 'requiredInstallFiles',
+            File = 'file',
+            Folder = 'folder',
+        InstallSteps = 'installSteps',
+            InstallStep = 'installStep',
+                Visible = 'visible',
+                    // Dependencies = 'dependencies',
+                        // Dependencies = 'dependencies',
+                        // FileDependency = 'fileDependency',
+                        // FlagDependency = 'flagDependency',
+                        // GameDependency = 'gameDependency',
+                        // FOMMDependency = 'fommDependency',
+                        // FOSEDependency = 'foseDependency',
+                OptionalFileGroups = 'optionalFileGroups',
+                    Group = 'group',
+                        Plugins = 'plugins',
+                            Plugin = 'plugin',
+                                Description = 'description',
+                                Image = 'image',
+                                ConditionFlags = 'conditionFlags',
+                                    Flag = 'flag',
+                                Files = 'files',
+                                    //File = 'file',
+                                    //Folder = 'folder',
+                                TypeDescriptor = 'typeDescriptor',
+                                    Type = 'type',
+                                    DependencyType = 'dependencyType',
+                                        DefaultType = 'defaultType',
+                                        Patterns = 'patterns',
+                                            Pattern = 'pattern',
+                                                // Dependencies = 'dependencies',
+                                                    // Dependencies = 'dependencies',
+                                                    // FileDependency = 'fileDependency',
+                                                    // FlagDependency = 'flagDependency',
+                                                    // GameDependency = 'gameDependency',
+                                                    // FOMMDependency = 'fommDependency',
+                                                    // FOSEDependency = 'foseDependency',
+                                                //Type = 'type',
+        ConditionalFileInstalls = 'conditionalFileInstalls',
+            // Patterns = 'patterns',
+                // Pattern = 'pattern',
+                    // Dependencies = 'dependencies',
+                        // Dependencies = 'dependencies',
+                        // FileDependency = 'fileDependency',
+                        // FlagDependency = 'flagDependency',
+                        // GameDependency = 'gameDependency',
+                        // FOMMDependency = 'fommDependency',
+                        // FOSEDependency = 'foseDependency',
+}
+
+/** A valid attribute for an XML-Based Fomod installer */
+export enum AttributeName {
+    // moduleName
+    Color = 'colour',
+    Colour = 'colour',
+
+    // moduleImage, image
+    Path = 'path',
+
+    // moduleImage
+    Position = 'position',
+    Height = 'height',
+    ShowFade = 'showFade',
+    ShowImage = 'showImage',
+
+    // moduleDependencies, dependencies, visible
+    Operator = 'operator',
+
+    // file, folder
+    Source = 'source',
+    Destination = 'destination',
+    Priority = 'priority',
+    AlwaysInstall = 'alwaysInstall',
+    InstallIfUsable = 'installIfUsable',
+
+    // installSteps, optionalFileGroups, plugins
+    Order = 'order',
+
+    // installStep, group, plugin, flag, type, defaultType
+    Name = 'name',
+
+    // group
+    Type = 'type',
+
+    // fileDependency
+    File = 'file',
+    State = 'state',
+
+    // flagDependency
+    Flag = 'flag',
+    Value = 'value',
+
+    // gameDependency, fommDependency, foseDependency
+    Version = 'version',
+}
+
+
+/** Describes how the group should behave when allowing users to select its options */
+export enum GroupBehaviorType {
+    /** Users may select or deselect any otherwise-selectable option within the group without restriction. */
+    SelectAny = 'SelectAny',
+    /** Users must select at least one otherwise-selectable option within the group. */
+    SelectAtLeastOne = 'SelectAtLeastOne',
+    /** Users may select no option or a single, otherwise-selectable option within the group. */
+    SelectAtMostOne = 'SelectAtMostOne',
+    /** Users must select exactly one otherwise-selectable option within the group; no more, no less. This is the default behavior. */
+    SelectExactlyOne = 'SelectExactlyOne',
+    /** All options in the group are forcibly selected and cannot be deselected. */
+    SelectAll = 'SelectAll'
+}
+
+/** Describes how an option should behave in regard to user selection */
+export enum OptionType {
+    /** The option will not be selected and cannot be selected. */
+    NotUsable = 'NotUsable',
+    /** Acts the same as `Optional`, except that mod managers may show a warning to the user when selecting this option. This is not universal, though, and the majority of mainstream mod managers at the moment forego this. */
+    CouldBeUsable = 'CouldBeUsable',
+    /** The option will be selectable. This is the default behavior. */
+    Optional = 'Optional',
+    /** The option will be selected by default but may be deselected. */
+    Recommended = 'Recommended',
+    /** The option will be selected by default and cannot be deselected. */
+    Required = 'Required',
+}
+
+/** Describes how the group should behave when allowing users to select its options */
+export enum SortingOrder {
+    /** Items are ordered alphabetically starting with A and ending with Z. This is the default behavior. */
+    Ascending = 'Ascending',
+    /** Items are ordered alphabetically starting with Z and ending with A. */
+    Descending = 'Descending',
+    /** Items are ordered precisely as they appear in the XML (and, consequently, the Set within JS) */
+    Explicit = 'Explicit',
+}
+
+/** A state which this FileDependency expects the file to be in to be satisfied */
+export enum FileDependencyState {
+    /** The file must not exist on the user's system */
+    Missing = 'Missing',
+    /** The file must be on the user's system but NOT loaded by the game */
+    Inactive = 'Inactive',
+    /** The file must be on the user's system and loaded by the game */
+    Active = 'Active',
+}
+
+/** An operator which determines the behavior of the dependency group */
+export enum DependencyGroupOperator {
+    /** The dependency group is satisfied if *any* of its children are satisfied */
+    Or = 'Or',
+    /** The dependency group is only satisfied if **all** of its children are satisfied */
+    And = 'And',
+}
+
+export enum ModuleNamePosition {
+    /** Positions the title on the left side of the form header. */
+    Left = 'Left',
+    /** Positions the title on the right side of the form header. */
+    Right = 'Right',
+    /** Positions the title on the right side of the image in the form header. */
+    RightOfImage = 'RightOfImage',
+}
+
+export enum BooleanString {
+    true = 'true',
+    false = 'false',
+}

src/definitions/Metadata.ts

@@ -1,5 +1,5 @@
-import { InvalidityReport } from "./InvalidityReporting";
-import { ElementObjectMap, Verifiable, XmlRepresentation } from "./_core";
+import { TagName } from "./Enums";
+import { ElementObjectMap, XmlRepresentation } from "./lib/_core";
 
 export interface FomodInfoData {
     [key: string]: string|undefined;
@@ -28,8 +28,8 @@ export const DefaultInfoSchema = 'https://fomod.bellcube.dev/schemas/info.xsd';
  * Explicit types are given for known values, however there are no explicit specifications given for what is allowed or expected in the file.
  */
 export class FomodInfo extends XmlRepresentation<boolean> {
-    static override readonly tagName = 'fomod';
-    readonly tagName = 'fomod';
+    static override readonly tagName = TagName.Fomod;
+    readonly tagName = TagName.Fomod;
 
     constructor(
         public data: FomodInfoData = {}

src/definitions/index.ts

@@ -1,10 +1,5 @@
-export * from './_core';
-export * from './Dependencies';
-export * from './FlagInstance';
-export * from './Fomod';
-export * from './Group';
-export * from './Install';
-export * from './InvalidityReporting';
+export * from './lib';
+export * from './module';
+
+export * from './Enums';
 export * from './Metadata';
-export * from './Option';
-export * from './Step';

src/definitions/FlagInstance.ts → src/definitions/lib/FlagInstance.ts

@@ -1,4 +1,4 @@
-import { Option } from './Option';
+import { Option } from '../module/Option';
 
 interface FlagInstances {
     all: Set<FlagInstance<boolean, boolean>>;

src/definitions/_core.ts → src/definitions/lib/_core.ts

@@ -1,5 +1,6 @@
-import { ensureXmlDoctype } from "../DomUtils";
-import { InvalidityReason, InvalidityReport } from "./InvalidityReporting";
+import { ensureXmlDoctype } from "../../DomUtils";
+import { TagName } from "../Enums";
+import { InvalidityReport } from "./InvalidityReporting";
 
 /** The foundation of a class that can be validated against a schema.
  *
@@ -24,8 +25,8 @@ export const ElementObjectMap = new WeakMap<Element, XmlRepresentation<boolean>>
  *
  */
 export abstract class XmlRepresentation<TStrict extends boolean> extends Verifiable<TStrict> {
-    static readonly tagName: string|string[];
-    abstract readonly tagName: string;
+    static readonly tagName: TagName|TagName[];
+    abstract readonly tagName: TagName;
 
     /** A [weak map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) of documents to this representation's associated element within that document.
      *

src/definitions/lib/index.ts

@@ -0,0 +1,3 @@
+export * from './_core';
+export * from './FlagInstance';
+export * from './InvalidityReporting';