@ondoher/enigma 1.0.12 → 1.0.14

package/README.md

@@ -20,16 +20,7 @@
 
 # Getting Started
 
-The Enigma toolkit is released as a nodejs ESM module. ESM is a relatively new
-standard for importing modules, and can present challenges to developers who
-need to mix the two. Using CJS modules in an ESM project is pretty straight
-forward, but the opposite is not true. Here is a good page that covers this
-issue [Mixing ESM and CJS](https://adamcoster.com/blog/commonjs-and-esm-importexport-compatibility-examples).
-To work with this code, your best bet is to create your own project also as ESM,
-by either renaming your files with the extension mjs, or adding
-```"type": "module"``` to your package.js file.
-
-To install the module, use the command:
+To install the toolkit, use the command:
 
 ```npm install @ondoher/enigma```
 
@@ -38,7 +29,7 @@ You can then import this into your code like this:
 ```JavaScript
 import {Enigma} from '@ondoher/enigma';
 
-var enigma = new Enigma("I", {reflector: 'B'});
+let enigma = new Enigma("I", {reflector: 'B'});
 ```
 
 In addition to this api, there is also [documentation](https://github.com/Ondoher/enigma/blob/main/docs/enigma.md)
@@ -47,7 +38,6 @@ about its operation. Following that is a detailed breakdown of how to go about
 writing a simulation and all of the small details and quirks that will need to
 be accounted for. And there are many.
 
-
 The API is broken into two main parts, the simulator and the message generator.
 With the simulator you can construct an entire Enigma, or just create instances
 of the individual components. This API is provided as a working reference that
@@ -411,7 +401,7 @@ encoding the letter.
 undefined or the encoded character.
 
 ---
-`encode(start, text)`
+`translate(start, text)`
 
 Call this method to encode a whole string.
 
@@ -446,16 +436,16 @@ An array of the installed rotors
 ```javascript
 import {Enigma} from '@ondoher/enigma';
 
-var enigma = new Enigma("I", {reflector: 'B'});
+let enigma = new Enigma("I", {reflector: 'B'});
 
 enigma.configure({
     rotors: ['III', 'VI', 'VIII'],
-    ringSetting: [1, 8, 13],
+    ringSettings: [1, 8, 13],
     plugs: 'AN EZ HK IJ LR MQ OT PV SW UX'
 });
 
-var message = 'YKAENZAPMSCHZBFOCUVMRMDPYCOFHADZIZMEFXTHFLOLPZLFGGBOTGOXGRETDWTJIQHLMXVJWKZUASTR'
-var decoded = enigma.encode('UZV', message)
+let message = 'YKAENZAPMSCHZBFOCUVMRMDPYCOFHADZIZMEFXTHFLOLPZLFGGBOTGOXGRETDWTJIQHLMXVJWKZUASTR'
+let decoded = enigma.translate('UZV', message)
 
 console.log(decoded)
 

package/bin/config.js

@@ -0,0 +1,11 @@
+
+/** @type {EnigmaConfig} */
+export const CONFIG = {
+	enigma: {
+		name: "I",
+		reflector: 'B',
+		rotors: ['III', 'VI', 'VIII'],
+		ringSettings: [1, 8, 13],
+		plugs: 'AN EZ HK IJ LR MQ OT PV SW UX'
+	}
+}

package/bin/enigma.js

@@ -0,0 +1,125 @@
+import parseArgs  from 'minimist';
+import { getOptions } from '../lib/utils/options.js';
+import { access, constants, readFile, writeFile } from 'node:fs/promises';
+import { CONFIG } from './config.js';
+import Enigma from 'enigma/Enigma';
+
+let argv = parseArgs(process.argv.slice(2));
+let params = argv._;
+let instructionText = '';
+
+/** @type {Options} */
+let defaultOptions = {
+	file: './enigma.json',
+	overwrite: false,
+	events: '',
+	step: false
+}
+
+/** @type {OptionsNameMap} */
+let nameMap = {
+	file: 'f',
+	overwrite: 'o',
+	events: 'e',
+	step: 's'
+}
+
+
+/** @type {Options} */
+let options = getOptions(defaultOptions, argv, nameMap);
+let command = params[0];
+
+/**
+ * Call this function to check if a file exists
+ *
+ * @param {String} name
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(name) {
+	try {
+		await access(name, constants.R_OK | constants.W_OK);
+		return true;
+	} catch (e) {
+		return false;
+	}
+}
+
+/**
+ * Call this method to see if the config file exists
+ * @returns
+ */
+async function configExists() {
+	return await fileExists(options.file)
+}
+
+/**
+ *
+ * @returns {Promise<EnigmaConfig>}
+ */
+async function readConfig() {
+	if (!configExists) {
+		return CONFIG;
+	}
+
+	return JSON.parse(await readFile( options.file, 'utf-8'));
+
+}
+
+function instructions() {
+	console.log(instructionText);
+}
+
+/**
+ *
+ * @param {string} str
+ */
+function error(str) {
+	console.log(str);
+}
+
+async function init() {
+	if (await configExists() && !options.overwrite) {
+		error("cannot overwrite config file")
+		instructions();
+		return;
+	}
+
+	await writeFile(options.file, JSON.stringify(CONFIG, null, "    "), 'utf-8');
+}
+
+async function runEnigma() {
+	let config = await readConfig();
+	if (params.length > 1) {
+		config.encode = params[1];
+	}
+	let enigmaConfig = config.enigma;
+	if (!config.encode) {
+		error('no string to encode');
+		instructions();
+		return;
+	}
+	let { name, rotors, ringSettings, reflector, plugs} = enigmaConfig;
+	let enigma = new Enigma(name, {reflector});
+	enigma.configure({rotors, ringSettings, plugs})
+	let decoded = enigma.translate("", config.encode)
+}
+
+async function main() {
+	instructionText = await readFile('./instructions.txt', 'utf-8');
+	if (!command) {
+		instructions();
+		return;
+	}
+
+	switch (command) {
+		case "init":
+			await init();
+ 			break;
+
+		default:
+			instructions();
+			break;
+	}
+}
+
+await main();

package/bin/enigma.json

@@ -0,0 +1,17 @@
+{
+    "enigma": {
+        "name": "I",
+        "reflector": "B",
+        "rotors": [
+            "III",
+            "VI",
+            "VIII"
+        ],
+        "ringSettings": [
+            1,
+            8,
+            13
+        ],
+        "plugs": "AN EZ HK IJ LR MQ OT PV SW UX"
+    }
+}

package/bin/instructions.txt

@@ -0,0 +1 @@
+silly boy

package/bin/types.d.ts

@@ -0,0 +1,21 @@
+
+
+type Options = {
+	file?: string;
+	overwrite?: boolean;
+	events?: string;
+	step?: boolean;
+}
+
+type EnigmaConfig = {
+	enigma: {
+		name: string;
+		reflector: string;
+		rotors: string[],
+		ringSettings: number[] | string;
+		plugs: string | string[];
+	},
+	rotor?: string,
+	options?: Options,
+	encode?: string,
+}

package/jsconfig.json

@@ -1,8 +1,12 @@
 {
   "compilerOptions": {
-    "target": "es2020", // Or a newer version like "es2020"
-    "module": "commonjs",
-  },
+    "target": "es2022", // Or a newer version like "es2020"
+    "module": "es2022",
+    "checkJs": true,
+    "baseUrl": "./",
+    "paths": {
+      "*": ["node_modules/@types/*", "*"]
+    }  },
   "exclude": [
     "node_modules"
   ],

package/lib/enigma/Encoder.js

@@ -7,11 +7,12 @@ import { STANDARD_ALPHABET } from "./consts.js";
  */
 export default class Encoder {
 	/**
-	 * Constructor for the base encoder
+	 * Constructor for the base encoder. This will the parent class for all
+	 * components
 	 *
-	 * @param {string} name
-	 * @param {ComponentType} type
-	 * @param {EncoderSetup} settings
+	 * @param {string} name - the name of the encoder
+	 * @param {ComponentType} type - the type of component
+	 * @param {EncoderSetup} settings - the base settings for the encoder
 	 */
 	constructor(name, type, settings) {
 		let {cb, alphabet = STANDARD_ALPHABET} = settings;
@@ -19,6 +20,7 @@ export default class Encoder {
 		this.type = type;
 		this.alphabet = alphabet;
 		this.contactCount = alphabet.length;
+
 		/** @type {{[name: string]: Listener}} */
 		this.listeners = {}
 
@@ -30,8 +32,9 @@ export default class Encoder {
 	/**
 	 * given a connector number, normalize it to be between 0 and 25 inclusive.
 	 *
-	 * @param {Number} connector the connector being normalized
+	 * @protected
 	 *
+	 * @param {Number} connector - the connector being normalized
 	 * @returns {Number} value between 0 and 25
 	 */
 	normalize(connector) {
@@ -39,10 +42,14 @@ export default class Encoder {
 	}
 
 	/**
+	 * Call this method to check if the given character is a valid character in
+	 * the setup alphabet. Any unexpected character except for a space will
+	 * output warning to the console.
 	 *
-	 * @param {string} letter
+	 * @public
 	 *
-	 * @returns {boolean}
+	 * @param {string} letter - the character to check
+	 * @returns {boolean} true if it is false otherwise
 	 */
 	verifyLetter(letter) {
 		if (letter.length !== 1 || this.alphabet.indexOf(letter) === -1) {
@@ -56,9 +63,12 @@ export default class Encoder {
 	}
 
 	/**
-	 * Call this method to convert a letter to a connector value
+	 * Call this method to convert a letter to a connector value.
+	 *
+	 * @public
 	 *
-	 * @param {string} letter
+	 * @param {string} letter - the character to convert. If it is not a valid
+	 * letter then this function will return undefined
 	 * @returns {number | undefined}
 	 */
 	letterToConnector(letter) {
@@ -72,7 +82,9 @@ export default class Encoder {
 	/**
 	 * Call this method to turn a connector to a letter value
 	 *
-	 * @param {number} connector
+	 * @public
+	 *
+	 * @param {number} connector - connector number to convert
 	 * @returns {string | undefined}
 	 */
 	connectorToLetter(connector) {
@@ -89,11 +101,13 @@ export default class Encoder {
 	 * numbers. The index into the array or string is the input connector, and
 	 * the value at that position is the output connector
 	 *
-	 * @param {String} map connections map.
+	 * @protected
+	 *
+	 * @param {String} map - connections map.
 	 * @returns {Array.<Number>} the numerical map
 	 */
 	makeMap(map) {
-		var letters = [...map];
+		let letters = [...map];
 		return letters.map(function(letter) {
 			return this.alphabet.indexOf(letter);
 		}, this)
@@ -103,11 +117,13 @@ export default class Encoder {
 	 * given an existing connection map from input to out put, create a new map
 	 * that has the connections going in the other direction, output to input.
 	 *
-	 * @param {Array.<Number>} map connection map
+	 * @protected
+	 *
+	 * @param {Array.<Number>} map - connection map
 	 * @returns {Array.<Number>} the reversed map
 	 */
 	makeReverseMap(map) {
-		var reverseMap = new Array(map.length);
+		let reverseMap = new Array(map.length);
 
 		map.forEach(function(input, idx) {
 			reverseMap[input] = idx;
@@ -121,9 +137,11 @@ export default class Encoder {
 	 * the given direction The default encode method just passes the input value
 	 * through
 	 *
-	 * @param {Direction} _direction either right for moving towards the reflector
+	 * @public
+	 *
+	 * @param {Direction} _direction - either right for moving towards the reflector
 	 * 	or left if moving back
-	 * @param {Number} input the specific connection receiving an input
+	 * @param {Number} input - the specific connection receiving an input
 	 *
 	 * @returns {Number} The translated output connector number
 	 */
@@ -132,9 +150,13 @@ export default class Encoder {
 	}
 
 	/**
+	 * Call this method to fire an `input` event
+	 *
+	 * @protected
 	 *
-	 * @param {number | string} input
-	 * @param {Direction} direction
+	 * @param {number | string} input - the input value as either a letter or
+	 * a number
+	 * @param {Direction} direction - the direction the signal is heading
 	 */
 	fireInput(input, direction) {
 		if (typeof input === 'number') input = this.connectorToLetter(input)
@@ -153,9 +175,13 @@ export default class Encoder {
 	}
 
 	/**
+	 * Call this method to fire an `output` even
 	 *
-	 * @param {number | string} output
-	 * @param {Direction} direction
+	 * @protected
+	 *
+	 * @param {number | string} output - the output value as either a letter or
+	 * a number
+	 * @param {Direction} direction - the direction the signal is heading
 	 */
 	fireOutput(output, direction) {
 		if (typeof output === 'number') output = this.connectorToLetter(output)
@@ -173,10 +199,15 @@ export default class Encoder {
 	}
 
 	/**
+	 * Call this method to fire a `translate` event
+	 *
+	 * @protected
 	 *
-	 * @param {number | string} input
-	 * @param {number | string} output
-	 * @param {Direction} direction
+	 * @param {number | string} input - the input value as either a letter or
+	 * a number
+	 * @param {number | string} output - the output value as either a letter or
+	 * a number
+	 * @param {Direction} direction - the direction the signal is heading
 	 */
 	fireTranslate(input, output, direction) {
 		if (typeof input === 'number') input = this.connectorToLetter(input)
@@ -195,10 +226,15 @@ export default class Encoder {
 	}
 
 	/**
+	 * Call this method to fire the `input`, `output` and `translate` events.
+	 *
+	 * @protected
 	 *
-	 * @param {number | string} input
-	 * @param {number | string} output
-	 * @param {Direction} direction
+	 * @param {number | string} input - the input value as either a letter or
+	 * a number
+	 * @param {number | string} output - the output value as either a letter or
+	 * a number
+	 * @param {Direction} direction - the direction the signal is heading
 	 */
 	fireEncodeSet(input, output, direction) {
 		this.fireInput(input, direction);
@@ -210,6 +246,8 @@ export default class Encoder {
 	 * Call this method to add a function to be called when important events
 	 * happen to a component. The name can be used to later remove the listener
 	 *
+	 * @public
+	 *
 	 * @param {string} name - the name of the listener
 	 * @param {Listener} cb - the function to be called.
 	 */
@@ -218,7 +256,9 @@ export default class Encoder {
 	}
 
 	/**
-	 * Call this method to remove a listener
+	 * Call this method to remove a listener.
+	 *
+	 * @public
 	 *
 	 * @param {string} name - the name of the listener
 	 */
@@ -229,6 +269,8 @@ export default class Encoder {
 	/**
 	 * Call this method to call any event listeners
 	 *
+	 * @protected
+	 *
 	 * @param {EventName} event - the event being fired
 	 * @param {String} name - the name of the component firing the event
 	 * @param {EventData} data - the event data

package/lib/enigma/Enigma.js

@@ -16,8 +16,8 @@ export default class Enigma extends Encoder {
 	 * The constructor for the Enigma. This represents the unconfigurable
 	 * settings of the device.
 	 *
-	 * @param {string} name
-	 * @param {EnigmaSetup} settings
+	 * @param {string} name - the name of the enigma
+	 * @param {EnigmaSetup} settings - the setup options
 	 */
 	constructor(name,  settings) {
 		super(name, "Enigma", settings)
@@ -43,6 +43,8 @@ export default class Enigma extends Encoder {
 	/**
 	 * the configured rotors
 	 *
+	 * @public
+	 *
 	 * @return {Rotor[]}
 	 */
 	get rotors() {
@@ -50,6 +52,10 @@ export default class Enigma extends Encoder {
 	}
 
 	/**
+	 * The configuration and setup options
+	 *
+	 * @public
+	 *
 	 * @returns {SimplifiedConfiguration & {reflector: string}}
 	 */
 	get configuration() {
@@ -59,6 +65,8 @@ export default class Enigma extends Encoder {
 	/**
 	 * Configure the Enigma for encoding.
 	 *
+	 * @public
+	 *
 	 * @param {EnigmaConfiguration} settings - the configuration of the Enigma.
 	 * These settings represent the aspects of the Enigma that can can change for daily
 	 * configuration.
@@ -115,14 +123,39 @@ export default class Enigma extends Encoder {
 	/**
 	 * Call this method to "step" the rotors one time. This method will manage the
 	 * stepping between all rotors
+	 *
+	 * @public
 	 */
 	step() {
+		// Only the notches on the first two rotors effect stepping. One rotor's
+		// alphabet ring prevents the next rotor from turning unless the first
+		// rotor's notch is exposed. When a rotor does step, so does the
+		// previous  rotor  because they are attached by the notch in the
+		// previous rotor's  ring
+
+		// precalculate if and why a rotor should step, the first rotor is
+		// always engaged
+		/** @type {{engaged:boolean, nextEngaged: boolean}[]} */
+		let step = []
+
+		step[0] = {engaged: true, nextEngaged: false};
+
+		for (let idx = 1; idx < 3; idx++) {
+			let engaged = this._rotors[idx - 1].atTurnover();
+			let nextEngaged = idx < 2 && this._rotors[idx].atTurnover();
+
+			step[idx] = {engaged, nextEngaged};
+		}
+
 		this._rotors.forEach((rotor, idx) => {
 			if (rotor.isFixed()) return;
 
-			// This is the double stepping. Only do this for the middle rotor
-			if (rotor.willTurnover() && idx === 1) {
-				this.pending[idx] = true
+			if (step[idx].engaged || step[idx].nextEngaged) {
+				rotor.step();
+			}
+
+			// the double-step is caused by the the next rotor stepping
+			if (step[idx].nextEngaged) {
 				/** @type {EventData} */
 				let eventData = {
 					name: rotor.name,
@@ -131,23 +164,16 @@ export default class Enigma extends Encoder {
 					event: "double-step",
 					offset: rotor.offset,
 				}
-
 				this.fire('double-step', rotor.name, eventData);
-			};
-
-			if (this.pending[idx]) {
-				this.pending[idx] = false;
-				if (rotor.step()) this.pending[idx + 1] = true;
 			}
 		});
-
-		// The first rotor is always stepping
-		this.pending[0] = true;
 	}
 
 	/**
 	 * Call this method to set the starting rotation for the messages to encrypt
 	 *
+	 * @public
+	 *
 	 * @param {number[]|string} setup - length of the string or the array
 	 * 	should match the number of rotors and are given left to right. If start
 	 * 	is a string then the letters of the string specify the start value seen
@@ -180,7 +206,9 @@ export default class Enigma extends Encoder {
 	 * Call this method to simulate a keypress on the Enigma. This will output
 	 * the encoded letter
 	 *
-	 * @param {String} letter the key pressed
+	 * @public
+	 *
+	 * @param {String} letter - the key pressed
 	 * @returns {String | undefined} the encoded letter
 	 */
 	keyPress(letter) {
@@ -218,8 +246,10 @@ export default class Enigma extends Encoder {
 	/**
 	 * Call this shortcut method to encode a whole string
 	 *
-	 * @param {String} start the starting position for the rotors
-	 * @param {String} text the text to encode
+	 * @public
+	 *
+	 * @param {String} start - the starting position for the rotors
+	 * @param {String} text - the text to encode
 	 *
 	 * @returns {String} the encoded string.
 	 */
@@ -234,9 +264,14 @@ export default class Enigma extends Encoder {
 	}
 
 	/**
+	 * Call this method to add a function to be called when important events
+	 * happen to a component. This listener will be propagated to all installed
+	 * components. The name can be used to later remove the listener
+	 *
+	 * @public
 	 *
-	 * @param {string} name
-	 * @param {Listener} cb
+	 * @param {string} name - the name of the listener
+	 * @param {Listener} cb - the function to be called.
 	 */
 	listen(name, cb) {
 		super.listen(name, cb);
@@ -247,4 +282,22 @@ export default class Enigma extends Encoder {
 
 		this.reflector.listen(name, cb);
 	}
+
+	/**
+	 * Call this method to unregister a listener. The listener will also be
+	 * removed from all components
+	 *
+	 * @public
+	 *
+	 * @param {string} name - the name of the listener
+	 */
+
+	unlisten(name) {
+		super.unlisten(name);
+
+		for (let encoder of this.encoders) {
+			encoder.unlisten(name)
+		}
+	}
+
 }

package/lib/enigma/EnigmaTypes.d.ts

@@ -90,6 +90,7 @@ interface RotorSetup extends EncoderSetup {
  * - **left** - the signal is moving from left to right
  * - **turn-around** - the signal is transitioning between directions, this is
  * sent from the reflector
+ * - **end-to-end** - this is the direction used for the Enigma object
  */
 type Direction = ("right" | "left" | "turn-around" | "end-to-end");
 
@@ -146,7 +147,7 @@ type StepData = {
 	/** the ending rotor position */
 	stop: number;
 
-	/** the locations of the turnover points for this rotor */
+	/** true if the rotor has rotated to its turnover location */
 	turnover: boolean;
 }