mediawiki-file-url 0.1.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# mediawiki-file-url
+Convert MediaWiki filenames into its hashed upload URLs on wikis with `$wgHashedUploadDirectory` enabled.
+
+## Install
+```
+npm i mediawiki-file-url
+```
+
+## Usage
+```js
+import {
+  mwFileUrl,
+  mwWikiFileUrl,
+  mwSetBaseUrl,
+  mwWithBaseUrl,
+} from "mediawiki-file-url";
+
+// From a plain filename (default base URL is set to the TDS Wiki images root)
+const url1 = mwFileUrl("WarlockLevel1.png");
+
+// Set a module-wide default base URL once (used when you omit baseUrl)
+mwSetBaseUrl("https://wiki.archlinux.org/images");
+const url2 = mwFileUrl("Tango-edit-clear.svg");
+const url3 = mwWikiFileUrl("File:Tango-edit-clear.svg");
+
+// Or create bound converters for one base URL (recommended if you need multiple wikis)
+const lol = mwWithBaseUrl("https://wiki.leagueoflegends.com/en-us/images");
+const url4 = lol.mwFileUrl("Champions_Mesh_concept_03.jpg");
+const url5 = lol.mwWikiFileUrl("  Image:   Champions_Mesh_concept_02.jpg   ");
+```
+
+## API
+### `mwFileUrl(filename, [baseUrl])`
+
+- `filename` (string) - e.g. `"My Image.png"`
+- `baseUrl` (string, optional) — if omitted, uses the configured default base URL (which is the Tower Defense Simulator Wiki)
+
+Returns the hashed upload URL.
+
+### `mwWikiFileUrl(wikiSyntax, [baseUrl])`
+- `wikiSyntax` (string) - must start with `File:` or `Image:` (whitespace is trimmed)
+- `baseUrl` (string, optional) — if omitted, uses the configured default base URL
+
+Extracts the filename and calls `mwFileUrl`.
+
+### `mwSetBaseUrl(baseUrl)`
+Sets the module-wide default base URL used by `mwFileUrl` / `mwWikiFileUrl` when `baseUrl` is omitted.
+
+### `mwWithBaseUrl(baseUrl)`
+Returns `{ mwFileUrl, mwWikiFileUrl }` functions bound to a specific `baseUrl`, so you don’t have to pass it each call.
+
+## Notes
+- ESM only.
+- If a wiki uses a custom hashed layout, it won't work.

package/index.js

@@ -0,0 +1,261 @@
+/**
+ * Itsy bitsy MD5 implementation since browsers don't support MD5.
+ * Based on the public domain implementation by Joseph Myers.
+ */
+function md5(message) {
+  function safe_add(x, y) {
+    var lsw = (x & 0xffff) + (y & 0xffff);
+    var msw = (x >> 16) + (y >> 16) + (lsw >> 16);
+    return (msw << 16) | (lsw & 0xffff);
+  }
+
+  function bit_rol(num, cnt) {
+    return (num << cnt) | (num >>> (32 - cnt));
+  }
+
+  function md5_cmn(q, a, b, x, s, t) {
+    return safe_add(bit_rol(safe_add(safe_add(a, q), safe_add(x, t)), s), b);
+  }
+  function md5_ff(a, b, c, d, x, s, t) {
+    return md5_cmn((b & c) | (~b & d), a, b, x, s, t);
+  }
+  function md5_gg(a, b, c, d, x, s, t) {
+    return md5_cmn((b & d) | (c & ~d), a, b, x, s, t);
+  }
+  function md5_hh(a, b, c, d, x, s, t) {
+    return md5_cmn(b ^ c ^ d, a, b, x, s, t);
+  }
+  function md5_ii(a, b, c, d, x, s, t) {
+    return md5_cmn(c ^ (b | ~d), a, b, x, s, t);
+  }
+
+  function str2binl(str) {
+    var nblk = ((str.length + 8) >> 6) + 1;
+    var blks = Array(nblk * 16);
+    for (var i = 0; i < nblk * 16; i++) blks[i] = 0;
+    for (var i = 0; i < str.length; i++)
+      blks[i >> 2] |= str.charCodeAt(i) << ((i % 4) * 8);
+    blks[i >> 2] |= 0x80 << ((i % 4) * 8);
+    blks[nblk * 16 - 2] = str.length * 8;
+    return blks;
+  }
+
+  function binl2hex(binarray) {
+    var hex_tab = "0123456789abcdef";
+    var str = "";
+    for (var i = 0; i < binarray.length * 4; i++) {
+      str +=
+        hex_tab.charAt((binarray[i >> 2] >> ((i % 4) * 8 + 4)) & 0xf) +
+        hex_tab.charAt((binarray[i >> 2] >> ((i % 4) * 8)) & 0xf);
+    }
+    return str;
+  }
+
+  var x = str2binl(message);
+  var a = 1732584193;
+  var b = -271733879;
+  var c = -1732584194;
+  var d = 271733878;
+
+  for (var i = 0; i < x.length; i += 16) {
+    var olda = a;
+    var oldb = b;
+    var oldc = c;
+    var oldd = d;
+
+    a = md5_ff(a, b, c, d, x[i + 0], 7, -680876936);
+    d = md5_ff(d, a, b, c, x[i + 1], 12, -389564586);
+    c = md5_ff(c, d, a, b, x[i + 2], 17, 606105819);
+    b = md5_ff(b, c, d, a, x[i + 3], 22, -1044525330);
+    a = md5_ff(a, b, c, d, x[i + 4], 7, -176418897);
+    d = md5_ff(d, a, b, c, x[i + 5], 12, 1200080426);
+    c = md5_ff(c, d, a, b, x[i + 6], 17, -1473231341);
+    b = md5_ff(b, c, d, a, x[i + 7], 22, -45705983);
+    a = md5_ff(a, b, c, d, x[i + 8], 7, 1770035416);
+    d = md5_ff(d, a, b, c, x[i + 9], 12, -1958414417);
+    c = md5_ff(c, d, a, b, x[i + 10], 17, -42063);
+    b = md5_ff(b, c, d, a, x[i + 11], 22, -1990404162);
+    a = md5_ff(a, b, c, d, x[i + 12], 7, 1804603682);
+    d = md5_ff(d, a, b, c, x[i + 13], 12, -40341101);
+    c = md5_ff(c, d, a, b, x[i + 14], 17, -1502002290);
+    b = md5_ff(b, c, d, a, x[i + 15], 22, 1236535329);
+
+    a = md5_gg(a, b, c, d, x[i + 1], 5, -165796510);
+    d = md5_gg(d, a, b, c, x[i + 6], 9, -1069501632);
+    c = md5_gg(c, d, a, b, x[i + 11], 14, 643717713);
+    b = md5_gg(b, c, d, a, x[i + 0], 20, -373897302);
+    a = md5_gg(a, b, c, d, x[i + 5], 5, -701558691);
+    d = md5_gg(d, a, b, c, x[i + 10], 9, 38016083);
+    c = md5_gg(c, d, a, b, x[i + 15], 14, -660478335);
+    b = md5_gg(b, c, d, a, x[i + 4], 20, -405537848);
+    a = md5_gg(a, b, c, d, x[i + 9], 5, 568446438);
+    d = md5_gg(d, a, b, c, x[i + 14], 9, -1019803690);
+    c = md5_gg(c, d, a, b, x[i + 3], 14, -187363961);
+    b = md5_gg(b, c, d, a, x[i + 8], 20, 1163531501);
+    a = md5_gg(a, b, c, d, x[i + 13], 5, -1444681467);
+    d = md5_gg(d, a, b, c, x[i + 2], 9, -51403784);
+    c = md5_gg(c, d, a, b, x[i + 7], 14, 1735328473);
+    b = md5_gg(b, c, d, a, x[i + 12], 20, -1926607734);
+
+    a = md5_hh(a, b, c, d, x[i + 5], 4, -378558);
+    d = md5_hh(d, a, b, c, x[i + 8], 11, -2022574463);
+    c = md5_hh(c, d, a, b, x[i + 11], 16, 1839030562);
+    b = md5_hh(b, c, d, a, x[i + 14], 23, -35309556);
+    a = md5_hh(a, b, c, d, x[i + 1], 4, -1530992060);
+    d = md5_hh(d, a, b, c, x[i + 4], 11, 1272893353);
+    c = md5_hh(c, d, a, b, x[i + 7], 16, -155497632);
+    b = md5_hh(b, c, d, a, x[i + 10], 23, -1094730640);
+    a = md5_hh(a, b, c, d, x[i + 13], 4, 681279174);
+    d = md5_hh(d, a, b, c, x[i + 0], 11, -358537222);
+    c = md5_hh(c, d, a, b, x[i + 3], 16, -722521979);
+    b = md5_hh(b, c, d, a, x[i + 6], 23, 76029189);
+    a = md5_hh(a, b, c, d, x[i + 9], 4, -640364487);
+    d = md5_hh(d, a, b, c, x[i + 12], 11, -421815835);
+    c = md5_hh(c, d, a, b, x[i + 15], 16, 530742520);
+    b = md5_hh(b, c, d, a, x[i + 2], 23, -995338651);
+
+    a = md5_ii(a, b, c, d, x[i + 0], 6, -198630844);
+    d = md5_ii(d, a, b, c, x[i + 7], 10, 1126891415);
+    c = md5_ii(c, d, a, b, x[i + 14], 15, -1416354905);
+    b = md5_ii(b, c, d, a, x[i + 5], 21, -57434055);
+    a = md5_ii(a, b, c, d, x[i + 12], 6, 1700485571);
+    d = md5_ii(d, a, b, c, x[i + 3], 10, -1894986606);
+    c = md5_ii(c, d, a, b, x[i + 10], 15, -1051523);
+    b = md5_ii(b, c, d, a, x[i + 1], 21, -2054922799);
+    a = md5_ii(a, b, c, d, x[i + 8], 6, 1873313359);
+    d = md5_ii(d, a, b, c, x[i + 15], 10, -30611744);
+    c = md5_ii(c, d, a, b, x[i + 6], 15, -1560198380);
+    b = md5_ii(b, c, d, a, x[i + 13], 21, 1309151649);
+    a = md5_ii(a, b, c, d, x[i + 4], 6, -145523070);
+    d = md5_ii(d, a, b, c, x[i + 11], 10, -1120210379);
+    c = md5_ii(c, d, a, b, x[i + 2], 15, 718787259);
+    b = md5_ii(b, c, d, a, x[i + 9], 21, -343485551);
+
+    a = safe_add(a, olda);
+    b = safe_add(b, oldb);
+    c = safe_add(c, oldc);
+    d = safe_add(d, oldd);
+  }
+  return binl2hex([a, b, c, d]);
+}
+
+/**
+ * Default base URL used by mwFileUrl/mwWikiFileUrl when no baseUrl argument is provided.
+ * This can be changed at runtime via mwSetBaseUrl().
+ */
+const DEFAULT_BASE_URL =
+  "https://static.wikia.nocookie.net/tower-defense-sim/images";
+let defaultBaseUrl = DEFAULT_BASE_URL;
+
+/**
+ * Set the module-wide default base URL used by mwFileUrl/mwWikiFileUrl
+ * when no baseUrl argument is provided.
+ *
+ * @param {string} baseUrl
+ */
+export function mwSetBaseUrl(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== "string") {
+    throw new Error("Base URL must be a non-empty string");
+  }
+  defaultBaseUrl = baseUrl;
+}
+
+/**
+ * Get the current module-wide default base URL.
+ * @returns {string}
+ */
+export function getDefaultBaseUrl() {
+  return defaultBaseUrl;
+}
+
+/**
+ * Converts a wiki filename to a MediaWiki file URL.
+ * Should work for any MediaWiki instance that uses
+ * any unmodified $wgHashedUploadDirectory implementation.
+ *
+ * @param {string} filename - The filename (for example, "WarlockLevel1.png")
+ * @param {string} [baseUrl] - The base URL for images (defaults to configured defaultBaseUrl)
+ * @returns {string} The full MediaWiki URL
+ * @throws {Error} If filename is invalid or hashing fails
+ */
+export function mwFileUrl(filename, baseUrl) {
+  if (!filename || typeof filename !== "string") {
+    throw new Error("Filename must be a non-empty string");
+  }
+
+  const effectiveBaseUrl = baseUrl ?? defaultBaseUrl;
+
+  try {
+    // Normalize spaces to underscores (cuz MediaWiki does that)
+    const normalizedFilename = filename.replace(/ /g, "_");
+
+    // Yada yada give me the md5
+    const md5Hash = md5(normalizedFilename);
+    const firstChar = md5Hash.charAt(0);
+    const firstTwoChars = md5Hash.substring(0, 2);
+    const cleanBaseUrl = effectiveBaseUrl.endsWith("/")
+      ? effectiveBaseUrl.slice(0, -1)
+      : effectiveBaseUrl;
+
+    // baseUrl/a/ab/Filename.png
+    const finalUrl = `${cleanBaseUrl}/${firstChar}/${firstTwoChars}/${encodeURIComponent(normalizedFilename)}`;
+
+    return finalUrl;
+  } catch (error) {
+    throw new Error(
+      `Error converting filename to MediaWiki URL: ${error.message}`,
+    );
+  }
+}
+
+/**
+ * Create converters bound to a baseUrl so one does not have to pass it each time.
+ *
+ * @param {string} baseUrl
+ * @returns {{ mwFileUrl: (filename: string) => string, mwWikiFileUrl: (wikiSyntax: string) => string }}
+ */
+export function mwWithBaseUrl(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== "string") {
+    throw new Error("Base URL must be a non-empty string");
+  }
+
+  return {
+    mwFileUrl: (filename) => mwFileUrl(filename, baseUrl),
+    mwWikiFileUrl: (wikiSyntax) => mwWikiFileUrl(wikiSyntax, baseUrl),
+  };
+}
+
+/**
+ * Converts a File:/Image: syntax to a MediaWiki URL
+ * @param {string} wikiSyntax - The wiki syntax (for example, "File:WarlockLevel1.png")
+ * @param {string} [baseUrl] - The base URL for images
+ * @returns {string} The full MediaWiki URL
+ * @throws {Error} If syntax is invalid or conversion fails
+ */
+export function mwWikiFileUrl(wikiSyntax, baseUrl) {
+  if (!wikiSyntax || typeof wikiSyntax !== "string") {
+    throw new Error("Wiki syntax must be a non-empty string");
+  }
+
+  const trimmed = wikiSyntax.trim();
+
+  if (trimmed.startsWith("File:")) {
+    const filename = trimmed.substring(5).trim();
+    return mwFileUrl(filename, baseUrl);
+  }
+
+  if (trimmed.startsWith("Image:")) {
+    const filename = trimmed.substring(6).trim();
+    return mwFileUrl(filename, baseUrl);
+  }
+
+  throw new Error('Wiki syntax must start with "File:" or "Image:"');
+}
+
+export default {
+  mwFileUrl,
+  mwWikiFileUrl,
+  mwSetBaseUrl,
+  getDefaultBaseUrl,
+  mwWithBaseUrl,
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mediawiki-file-url",
+  "version": "0.1.0",
+  "description": "Convert MediaWiki filenames into hashed upload URLs",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "mediawiki",
+    "md5"
+  ],
+  "author": "t7ru",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t7ru/mediawiki-file-url.git"
+  }
+}