synthetic-factorio 0.0.1

package/dist/ModManager.js

@@ -0,0 +1,181 @@
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { exec } from 'node:child_process';
+import { cpSync, createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import fetch from 'node-fetch';
+import { glob } from 'glob';
+import semverCompare from 'semver-compare';
+import { pipeline } from 'node:stream';
+import extractZip from 'extract-zip';
+import { getDependencies, getModInfo } from "./modInfoUtil.js";
+import { modDir, workingDir } from "./defaultValues.js";
+const vanillaMods = ['core', 'base', 'quality', 'recycler', 'elevated-rails', 'space-age'];
+/**
+ * Utility class to download/install mods so they can be found by FactorioEngine
+ */
+export class ModManager {
+    modDir;
+    workingDir;
+    constructor(options) {
+        this.modDir = options?.modDir || modDir();
+        this.workingDir = options?.workingDir || workingDir();
+    }
+    /**
+     * Download all vanilla "mod" data from https://github.com/wube/factorio-data
+     * Requires git to be available at the command line
+     * @param options Mod Installation options
+     */
+    async installVanillaMods(options) {
+        const run = promisify(exec);
+        const gitDir = path.join(this.workingDir, 'factorio-data');
+        if (existsSync(gitDir) && options?.clearDownload) {
+            rmSync(gitDir, { recursive: true });
+        }
+        if (existsSync(gitDir) && options?.checkLatest) {
+            await run('git pull', { cwd: gitDir });
+        }
+        if (!existsSync(gitDir)) {
+            mkdirSync(this.workingDir, { recursive: true });
+            await run('git clone --depth=1 https://github.com/wube/factorio-data.git', { cwd: this.workingDir });
+        }
+        for (let mod of vanillaMods) {
+            this.installDirectoryMod(mod, path.join(gitDir, mod), options);
+        }
+    }
+    /**
+     * Install mod from a directory - essentially a directory copy to the correct location
+     * @param modName Name of the mod
+     * @param sourcePath Path to copy from
+     * @param options Mod Installation Options
+     */
+    installDirectoryMod(modName, sourcePath, options) {
+        const targetPath = this.getModPath(modName);
+        if (existsSync(targetPath) && options?.clearCache) {
+            rmSync(targetPath, { recursive: true });
+        }
+        if (!existsSync(targetPath)) {
+            cpSync(sourcePath, targetPath, { recursive: true });
+        }
+    }
+    /**
+     * Downloads and installs a mod from Factorio's mod portal.
+     * Requires the environment variables FACTORIO_USERNAME and FACTORIO_TOKEN to be set
+     * @param modName Name of the mod
+     * @param options Mod Installation Optiions
+     */
+    async installPortalMod(modName, options) {
+        let modInfo = undefined;
+        let targetVersion = undefined;
+        const downloadDir = path.join(this.workingDir, 'downloads');
+        mkdirSync(downloadDir, { recursive: true });
+        if (options?.version) {
+            targetVersion = options?.version;
+        }
+        else if (options?.checkLatest) {
+            modInfo = await this.getModInfo(modName);
+            targetVersion = modInfo.releases.slice(-1)[0].version;
+        }
+        let zipPath = undefined;
+        if (targetVersion) {
+            zipPath = path.join(downloadDir, `${modName}_${targetVersion}.zip`);
+        }
+        else {
+            const modFiles = await glob(`${modName}_*.zip`, { cwd: downloadDir });
+            if (modFiles.length) {
+                let latest = '0.0.0';
+                for (const file of modFiles) {
+                    const version = file.replace(/\.zip$/, '').split('_').slice(-1)[0];
+                    if (semverCompare(latest, version) < 0) {
+                        latest = version;
+                    }
+                }
+                zipPath = path.join(downloadDir, `${modName}_${latest}.zip`);
+            }
+        }
+        if (zipPath && options?.clearDownload) {
+            rmSync(zipPath);
+        }
+        if (!zipPath) {
+            if (!modInfo) {
+                modInfo = await this.getModInfo(modName);
+            }
+            targetVersion = modInfo.releases.slice(-1)[0].version;
+            zipPath = path.join(downloadDir, `${modName}_${targetVersion}.zip`);
+        }
+        if (!existsSync(zipPath)) {
+            if (!modInfo) {
+                modInfo = await this.getModInfo(modName);
+            }
+            let modDownloadUrl;
+            if (targetVersion) {
+                let url = modInfo.releases.find(r => r.version === targetVersion)?.download_url;
+                if (url) {
+                    modDownloadUrl = url;
+                }
+                else {
+                    throw new Error(`Cannot find version ${targetVersion} of mod ${modName}`);
+                }
+            }
+            else {
+                modDownloadUrl = modInfo.releases.slice(-1)[0].download_url;
+            }
+            if (!process.env.FACTORIO_USERNAME) {
+                throw new Error('Cannot download mod, env variable FACTORIO_USERNAME is not set');
+            }
+            if (!process.env.FACTORIO_TOKEN) {
+                throw new Error('Cannot download mod, env variable FACTORIO_TOKEN is not set');
+            }
+            const apiDownloadUrl = `https://mods.factorio.com/${modDownloadUrl}?username=${process.env.FACTORIO_USERNAME}&token=${process.env.FACTORIO_TOKEN}`;
+            const streamPipeline = promisify(pipeline);
+            const response = await fetch(apiDownloadUrl);
+            if (!response.ok || !response.body) {
+                throw new Error(`Failed to download mod ${modName}: ${response.statusText}`);
+            }
+            await streamPipeline(response.body, createWriteStream(zipPath));
+        }
+        let isOutdated = false;
+        const targetPath = this.getModPath(modName);
+        if (existsSync(targetPath) && targetVersion) {
+            const modInfo = getModInfo(targetPath);
+            if (modInfo.version != targetVersion) {
+                isOutdated = true;
+            }
+        }
+        await this.installZipMod(modName, zipPath, { ...options, clearCache: isOutdated ? true : options?.clearCache });
+        if (!options?.skipDependencies) {
+            const dependencies = getDependencies(this.getModPath(modName));
+            for (let dependency of dependencies.required) {
+                if (!vanillaMods.includes(dependency) && !options?.omitDependencies?.includes(dependency)) {
+                    await this.installPortalMod(dependency, { ...options, version: undefined });
+                }
+            }
+        }
+    }
+    async getModInfo(modName) {
+        const response = await fetch(`https://mods.factorio.com/api/mods/${modName}`);
+        return (await response.json());
+    }
+    /**
+     * Install a mod from a zip file
+     * @param modName Name of the mod
+     * @param sourcePath Path to the zip file
+     * @param options Mod Installation Options
+     */
+    async installZipMod(modName, sourcePath, options) {
+        const targetPath = this.getModPath(modName);
+        if (existsSync(targetPath) && options?.clearCache) {
+            rmSync(targetPath, { recursive: true });
+        }
+        if (!existsSync(targetPath)) {
+            const unzipDir = path.join(this.workingDir, 'unzip');
+            mkdirSync(unzipDir, { recursive: true });
+            await extractZip(sourcePath, { dir: unzipDir });
+            // Mod contents are in a single dir inside the zip file, and the dir can have any name so we need to handle that
+            let dirs = readdirSync(unzipDir);
+            renameSync(path.join(unzipDir, dirs[0]), targetPath);
+        }
+    }
+    getModPath(modName) {
+        return path.join(this.modDir, `__${modName}__`);
+    }
+}

package/dist/defaultValues.d.ts

@@ -0,0 +1,3 @@
+export declare const libName = "synthetic-factorio";
+export declare const modDir: () => string;
+export declare const workingDir: () => string;

package/dist/defaultValues.js

@@ -0,0 +1,5 @@
+import envPaths from 'env-paths';
+import path from 'path';
+export const libName = 'synthetic-factorio';
+export const modDir = () => path.join(envPaths(libName).cache, 'mods');
+export const workingDir = () => path.join(envPaths(libName).cache, 'working');

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FactorioEngine, FactorioEngineOptions } from './FactorioEngine.ts';
+export { ModManager, ModManagerOptions, ModDownloadOptions, ModInstallOptions, ModPortalDownloadOptions } from './ModManager.ts';
+export { tableToArray } from './utils.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FactorioEngine } from "./FactorioEngine.js";
+export { ModManager } from "./ModManager.js";
+export { tableToArray } from "./utils.js";

package/dist/modInfoUtil.d.ts

@@ -0,0 +1,18 @@
+export interface ModInfo {
+    name: string;
+    version: string;
+    title: string;
+    author: string;
+    contact: string;
+    homepage: string;
+    factorio_version: string;
+    description: string;
+    dependencies: string[];
+}
+export interface Dependencies {
+    required: string[];
+    optional: string[];
+    incompatible: string[];
+}
+export declare function getModInfo(modDir: string): ModInfo;
+export declare function getDependencies(modDir: string): Dependencies;

package/dist/modInfoUtil.js

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+export function getModInfo(modDir) {
+    const filePath = path.join(modDir, 'info.json');
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+export function getDependencies(modDir) {
+    const modInfo = getModInfo(modDir);
+    const deps = {
+        required: [],
+        optional: [],
+        incompatible: [],
+    };
+    // https://lua-api.factorio.com/latest/auxiliary/mod-structure.html#Dependency
+    for (let dependency of modInfo.dependencies) {
+        let parts = dependency.split(' ');
+        if (parts[0] === '!') {
+            deps.incompatible.push(parts[1]);
+        }
+        // Hidden or non-hidden optional deps are equivalent here as they're only a mod portal concept
+        // Recommended optional is also functionally equivalent to optional for our purposes
+        else if (parts[0] === '?' || parts[0] === '(?)' || parts[0] === '+') {
+            deps.optional.push(parts[1]);
+        }
+        // For now ignoring ~ dependencies (dependency that doesn't affect load order)
+        // I'm unsure of the use case and haven't encountered one, and mostly the engine needs dependencies for load order concerns
+        else if (parts[0] !== '~') {
+            deps.required.push(parts[0]);
+        }
+    }
+    return deps;
+}

package/dist/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Many parts of the Factorio API return tables for array/list-like data
+ * i.e. { 1: 'some-value', 2: 'some-other-value' } instead of ['some-value', 'some-other-value']
+ * This function will convert them to a proper array
+ * @param table Array-like table from lua
+ * @returns Input table converted to a proper array
+ */
+export declare function tableToArray<T>(table: {
+    [key: number]: T;
+}): T[];

package/dist/utils.js

@@ -0,0 +1,21 @@
+/**
+ * Many parts of the Factorio API return tables for array/list-like data
+ * i.e. { 1: 'some-value', 2: 'some-other-value' } instead of ['some-value', 'some-other-value']
+ * This function will convert them to a proper array
+ * @param table Array-like table from lua
+ * @returns Input table converted to a proper array
+ */
+export function tableToArray(table) {
+    const result = [];
+    for (const key in table) {
+        const index = parseInt(key) - 1;
+        if (isNaN(index)) {
+            throw new Error(`Failed to convert table to array, found non-numeric key ${key}`);
+        }
+        if (index < 0) {
+            throw new Error(`Failed to convert table to array, found key ${key} less than 1`);
+        }
+        result[index] = table[key];
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "synthetic-factorio",
+  "version": "0.0.1",
+  "description": "Synthetic Factorio runtime for unit testing",
+  "license": "ISC",
+  "author": "Spencer Guest",
+  "type": "module",
+  "scripts": {
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "build": "tsc"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "util_scripts/**/*.lua"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "env-paths": "^4.0.0",
+    "extract-zip": "^2.0.1",
+    "glob": "^13.0.6",
+    "lua-state": "^1.2.0",
+    "node-fetch": "^3.3.2",
+    "semver-compare": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/semver-compare": "^1.0.3",
+    "factorio-types": "^1.2.69",
+    "vitest": "^5.0.0"
+  }
+}

package/util_scripts/data_setup.lua

@@ -0,0 +1,18 @@
+-- define data and its extend and raw methods in lua, JS will later read this global to extract it
+-- and may inject into data.raw to pre-populate the table
+-- this is handled in lua instead of a JS callback for performance reasons
+-- thousands of data.extend calls doing interop into JS is unusably slow
+
+data = data or {}
+data.raw = data.raw or {}
+
+function data.extend(self, values)
+    for i, value in ipairs(values) do
+        -- space-age tries to extend on the string "./data/__space-age__/sound/ambient/space/interlude-6/interlude-6.lua" 
+        -- (i.e. not a valid prototype object, just that string) so we need to gracefully handle invalid objects
+        if(value.name ~= nil and value.type ~= nil) then
+            data.raw[value.type] = data.raw[value.type] or {}
+            data.raw[value.type][value.name] = value
+        end
+    end
+end