chore: Include basic parser and service

README.md

@@ -8,7 +8,7 @@ An article's front matter may include the `parser` attribute. If that is the cas
 
 ```yaml
 ---
-parser: character-origin
+extension: character-origin
 ---
 # ...
 ```

books/basic-rules/appendix-character-origin/ceres/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Ceres und der Asteroidengürtel

books/basic-rules/appendix-character-origin/codex-moons/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Silbernes Reich — Minenkolonien

books/basic-rules/appendix-character-origin/codex-triton/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Silbernes Reich — Triton

books/basic-rules/appendix-character-origin/earth-rural/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Erde — Abseits der Städte

books/basic-rules/appendix-character-origin/earth-urban/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Erde — Großstädte und Raumstationen

books/basic-rules/appendix-character-origin/europa/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Europa

books/basic-rules/appendix-character-origin/ganymede/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Ganymed

books/basic-rules/appendix-character-origin/mars/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Mars

books/basic-rules/appendix-character-origin/titan/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Titan

books/basic-rules/appendix-character-origin/venus/de.md

@@ -1,5 +1,5 @@
 ---
-parser: character-origin
+extension: character-origin
 ---
 
 ## Venus

lib/config/index.ts

@@ -0,0 +1,2 @@
+export * from './wiki.config';
+export * from './types';

lib/config/types.ts

@@ -0,0 +1,19 @@
+export const WikiLocale = {
+  de: 'de',
+} as const;
+export type WikiLocale = (typeof WikiLocale)[keyof typeof WikiLocale];
+
+export interface WikiConfig {
+  /**
+   * The base URL of the wiki.
+   */
+  BASE_URL: string;
+  /**
+   * The locale of the wiki.
+   */
+  LOCALE: WikiLocale;
+  /**
+   * The headers to use for outgoing HTTP requests.
+   */
+  HTTP_HEADERS?: Record<string, string>;
+}

lib/config/wiki.config.ts

@@ -0,0 +1,7 @@
+import { WikiLocale, type WikiConfig } from './types';
+
+export const wikiConfig: WikiConfig = {
+  BASE_URL: 'https://raw.githubusercontent.com/satellite-games/new-horizons-wiki/main/books',
+  LOCALE: WikiLocale.de,
+  HTTP_HEADERS: {},
+};

lib/main.ts

@@ -2,4 +2,8 @@
 // Make sure to re-export all data and objects through this file. Otherwise
 // they will not be included into the bundle.
 // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-export * from './parsers';
+// Config
+export * from './config';
+
+// Services
+export * from './services/wiki';

lib/parsers/index.ts

@@ -1,24 +1,18 @@
-import { characterOriginParser } from './character-origin.parser';
+// import { characterOriginParser } from '../services/parser/parsers/character-origin.parser';
 
-/**
- * This is the collection of parsers that can be used to enrich articles provided by
- * `newhorizons-wiki` with in-game information. Each parser is a function that takes
- * takes a Markdown string as input and returns a Markdown string with the parsed information.
- * For more information on the wiki, see: https://github.com/satellite-games/newhorizons-wiki
- */
-export const wikiArticleParsers: Record<string, WikiArticleParserFunction> = {
-  'character-origin': characterOriginParser,
-};
+// /**
+//  * This is the collection of parsers that can be used to enrich articles provided by
+//  * `newhorizons-wiki` with in-game information. Each parser is a function that takes
+//  * takes a Markdown string as input and returns a Markdown string with the parsed information.
+//  * For more information on the wiki, see: https://github.com/satellite-games/newhorizons-wiki
+//  */
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type WikiArticleParserFunction = (article: string, ...args: any[]) => Promise<string>;
-
-/**
- * Parses the given wiki article and returns the parsed article.
- * @param article The article to parse.
- */
-export function parseWikiArticle(article: string, parser: keyof typeof wikiArticleParsers) {
-  if (!wikiArticleParsers[parser]) return;
-  const parsedArticle = wikiArticleParsers[parser](article);
-  return parsedArticle;
-}
+// /**
+//  * Parses the given wiki article and returns the parsed article.
+//  * @param article The article to parse.
+//  */
+// export function parseWikiArticle(article: string, parser: keyof typeof wikiArticleParsers) {
+//   if (!wikiArticleParsers[parser]) return;
+//   const parsedArticle = wikiArticleParsers[parser](article);
+//   return parsedArticle;
+// }

lib/services/parser/index.ts

@@ -0,0 +1,2 @@
+export * from './parser.service';
+export * from './parser.registry';

lib/parsers/character-origin.parser.test.ts → lib/services/parser/parser-extensions/character-origin.pex.test.ts

@@ -1,7 +1,7 @@
+import type { CharacterOriginName } from '@newhorizons/core';
 import { characterOriginMocks } from '@newhorizons/core/mocks';
 import { beforeEach, expect, it, vi } from 'vitest';
-import { characterOriginParser } from './character-origin.parser';
-import type { CharacterOriginName } from '@newhorizons/core';
+import { characterOriginParser } from './character-origin.pex';
 
 beforeEach(() => {
   vi.mock('@/main', () => {

lib/services/parser/parser.registry.ts

@@ -0,0 +1,6 @@
+import type { ParserFunction } from '@/types/private-types';
+import { characterOriginParser } from './parser-extensions/character-origin.pex';
+
+export const parserRegistry: Record<string, ParserFunction> = {
+  'character-origin': characterOriginParser,
+};

lib/services/parser/parser.service.ts

@@ -0,0 +1,55 @@
+import { ServiceMixin } from '@spuxx/browser-utils';
+import { marked } from 'marked';
+import { sanitize } from 'isomorphic-dompurify';
+import yaml from 'js-yaml';
+import { WikiService } from '../wiki/wiki.service';
+
+export class WikiParser extends ServiceMixin<WikiParser>() {
+  frontmatterPattern = /^---\s*([\s\S]*?)\s*---/;
+
+  /**
+   * Parses the Markdown article and to HTML.
+   * @param markdown The Markdown to parse.
+   * @returns The parsed HTML.
+   */
+  public static async parse(article: string): Promise<string> {
+    // const frontmatter = this.extractFrontmatter(article);
+    let parsedArticle = this.removeFrontmatter(article);
+    parsedArticle = this.doSimpleReplacements(parsedArticle);
+    const html = await marked.parse(parsedArticle);
+    const sanitizedHtml = sanitize(html);
+    return sanitizedHtml;
+  }
+
+  /**
+   * Extracts the frontmatter from a markdown string.
+   * @param markdown The markdown string.
+   * @returns The frontmatter as a JavaScript object.
+   */
+  public static extractFrontmatter(markdown: string): Record<string, unknown> | undefined {
+    const match = markdown.match(new RegExp(this.instance.frontmatterPattern));
+    if (!match) return;
+    const frontmatter = yaml.load(match[1]);
+    return frontmatter as Record<string, unknown>;
+  }
+
+  /**
+   * Removes the frontmatter from a markdown string.
+   * @param markdown The markdown string.
+   * @returns The markdown string without the frontmatter.
+   */
+  private static removeFrontmatter(markdown: string): string {
+    return markdown.replace(new RegExp(this.instance.frontmatterPattern), '');
+  }
+
+  private static doSimpleReplacements(article: string) {
+    let parsedArticle = article;
+    // Replace partial image urls will full urls
+    const imageSrcPattern = /<img.*src=['"](\/books)/gi;
+    const imageSrcMatches = parsedArticle.matchAll(imageSrcPattern);
+    for (const match of imageSrcMatches) {
+      parsedArticle = parsedArticle.replace(match[1], WikiService.config.BASE_URL);
+    }
+    return parsedArticle;
+  }
+}

lib/services/wiki/index.ts

@@ -0,0 +1,2 @@
+export * from './wiki.service';
+export * from './types';

lib/services/wiki/types.ts

@@ -0,0 +1,20 @@
+export interface WikiBookHeader {
+  id: string;
+  title: Record<string, string>;
+  icon: string;
+  default: {
+    chapter: string;
+    article: string;
+  };
+}
+
+export interface WikiBookToc extends WikiBookHeader {
+  chapters?: {
+    id: string;
+    title: Record<string, string>;
+    articles?: {
+      id: string;
+      title: Record<string, string>;
+    }[];
+  }[];
+}

lib/services/wiki/wiki.service.ts

@@ -0,0 +1,77 @@
+import { wikiConfig, type WikiConfig } from '@/config';
+import { ServiceMixin } from '@spuxx/browser-utils';
+import yaml from 'js-yaml';
+import { WikiParser } from '../parser';
+import type { WikiBookHeader, WikiBookToc } from './types';
+
+/**
+ * Provides functionalities to interact with the wiki.
+ */
+export class WikiService extends ServiceMixin<WikiService>() {
+  private _config: WikiConfig = wikiConfig;
+
+  static get config() {
+    return this.instance._config;
+  }
+
+  /**
+   * Updates the configuration of the wiki. Will merge the given
+   * configuration wih the packages default configuration.
+   * @param config The new configuration.
+   */
+  static setConfig(config: Partial<WikiConfig>) {
+    this.instance._config = { ...wikiConfig, ...config };
+  }
+
+  /**
+   * Attempts to fetch an article and return it.
+   * @param book The book id.
+   * @param chapter The chapter id.
+   * @param article The article id.
+   * @returns The article.
+   */
+  public static async fetchArticle(book: string, chapter: string, article: string) {
+    const url = `${this.config.BASE_URL}/${book}/${chapter}/${article}/${this.config.LOCALE}.md`;
+    try {
+      const response = await fetch(url, { headers: this.config.HTTP_HEADERS });
+      const text = await response.text();
+      const html = await WikiParser.parse(text);
+      return html;
+    } catch (error) {
+      throw new Error(`Unable to retrieve article from '${url}'.`);
+    }
+  }
+
+  /**
+   * Attempts to fetch the list of all available books.
+   * @returns The list of books.
+   */
+  public static async fetchBooks(): Promise<WikiBookHeader[]> {
+    const url = `${this.config.BASE_URL}/books.yaml`;
+    try {
+      const response = await fetch(url);
+      const text = await response.text();
+      const books = yaml.load(text) as WikiBookHeader[];
+      return books;
+    } catch (error) {
+      throw new Error(`Unable to retrieve list of books.`);
+    }
+  }
+
+  /**
+   * Attempts to fetch the table of contents for the Stellarpedia.
+   * @param book The book id.
+   * @returns The table of contents.
+   */
+  public static async fetchToc(book: string): Promise<WikiBookToc> {
+    const url = `${this.config.BASE_URL}/${book}/toc.yaml`;
+    try {
+      const response = await fetch(url);
+      const text = await response.text();
+      const toc = yaml.load(text) as WikiBookToc;
+      return toc;
+    } catch (error) {
+      throw new Error(`Unable to retrieve table of contents for book '${book}'.`);
+    }
+  }
+}

lib/types/private-types.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ParserFunction = (article: string, ...args: any[]) => Promise<string>;

package.json

@@ -49,11 +49,17 @@
     "format": "prettier --write ."
   },
   "peerDependencies": {
-    "@newhorizons/core": "link:../newhorizons-core"
+    "@newhorizons/core": "link:../newhorizons-core",
+    "@spuxx/browser-utils": "^0.2.0"
+  },
+  "dependencies": {
+    "isomorphic-dompurify": "^2.11.0",
+    "js-yaml": "^4.1.0",
+    "marked": "^12.0.2"
   },
   "devDependencies": {
     "@modyfi/vite-plugin-yaml": "^1.1.0",
-    "@spuxx/browser-utils": "^0.2.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.12.10",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",