extwee 2.2.0 → 2.2.2

package/docs/_sidebar.md

@@ -17,3 +17,4 @@
 - Examples
   - [Dynamically Generating Passages](/examples/dynamicPassages.md)
   - [Converting Twine 2 JSON into Twee 3](/examples/jsonToTwee.md)
+  - [Converting Twine 1 TWS into Twee 3](/examples/twsToTwee.md)

package/docs/examples/dynamicPassages.md

@@ -16,7 +16,7 @@ import { writeFileSync } from 'node:fs';
 const example = new Story( 'Example' );
 
 // Generate 20 passages and add them to the story.
-for(let i = 0; i < 20; i++;) {
+for(let i = 0; i < 20; i++) {
     example.addPassage( new Passage( `Passage ${i}`, 'Some Text') );
 }
 

package/docs/examples/twsToTwee.md

@@ -1,6 +1,6 @@
 # TWS To Twee
 
-Converting from TWS to Twee 3 is similar to many other conversion processes:
+Converting from TWS to Twee 3 is similar to many other conversion processes with one small difference. TWS conversion needs to be begin from the [**Buffer** data type in JavaScript](https://nodejs.org/api/buffer.html).
 
 1. Read the binary file.
 2. Convert the binary files into a Buffer.

package/docs/objects/story.md

@@ -12,7 +12,7 @@ Depending on the incoming format or creation method, many possible properties ca
 - format ( string ) Name of the story format for Twine 2 HTML.
 - formatVersion ( string ) Semantic version of the named story format for Twine 2 HTML or Twee 3.
 - zoom ( float ) Zoom level for Twine 2 HTML or Twee 3.
-- passages ( array(Passage) ) **[Read-only]** Collection of internal passages.
+- passages ( array(Passage) ) Collection of internal passages.
 - creator ( string ) Name of story creation tool. (Defaults to "Extwee").
 - creatorVersion ( string ) Semantic version of named creation tool.
 - metadata ( object ) Key-value pairs of metadata values.
@@ -41,7 +41,6 @@ As collections of passages, each **Story** has multiple methods for accessing an
 - `getPassagesByTags(string)`: Returns an array of any passages containing a particular tag value.
 - `getPassageByName(string)`: Returns either `null`` or the named passage.
 - `size()`: Returns the number of passages in the collection.
-- `forEachPassage(callback)`: Allows for iterating over the passage collection.
 
 ## Passage Creation Example
 

package/index.js

@@ -8,7 +8,8 @@ import { parse as parseTWS } from './src/TWS/parse.js';
 import { compile as compileTwine1HTML } from './src/Twine1HTML/compile.js';
 import { compile as compileTwine2HTML } from './src/Twine2HTML/compile.js';
 import { compile as compileTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/compile.js';
-import Story from './src/Story.js';
+import { generate as generateIFID } from './src/IFID/generate.js';
+import { Story } from './src/Story.js';
 import Passage from './src/Passage.js';
 import StoryFormat from './src/StoryFormat.js';
 
@@ -23,6 +24,7 @@ export {
     compileTwine1HTML,
     compileTwine2HTML,
     compileTwine2ArchiveHTML,
+    generateIFID,
     Story,
     Passage,
     StoryFormat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -8,7 +8,7 @@
     "extwee": "src/extwee.js"
   },
   "scripts": {
-    "test": "jest --silent --runInBand --coverage --colors",
+    "test": "jest --runInBand --coverage --colors",
     "lint": "eslint ./src/**/*.js --fix",
     "lint:test": "eslint ./test/**/*.test.js --fix",
     "build:web": "webpack",
@@ -23,43 +23,46 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "commander": "^11.1.0",
-    "node-html-parser": "^6.1.11",
+    "commander": "^12.0.0",
+    "html-entities": "^2.5.2",
+    "node-html-parser": "^6.1.12",
     "pickleparser": "^0.2.1",
-    "semver": "^7.3.7",
+    "semver": "^7.6.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
     "@babel/cli": "^7.23.4",
-    "@babel/core": "^7.23.6",
-    "@babel/eslint-parser": "^7.23.3",
+    "@babel/core": "^7.24.0",
+    "@babel/eslint-parser": "^7.23.10",
     "@babel/eslint-plugin": "^7.23.5",
-    "@babel/preset-env": "^7.23.6",
+    "@babel/preset-env": "^7.24.0",
+    "@types/uuid": "^9.0.7",
     "babel-loader": "^9.1.3",
     "clean-jsdoc-theme": "^4.2.17",
-    "core-js": "^3.34.0",
-    "docsify-cli": "^4.4.4",
-    "esbuild": "0.19.10",
-    "eslint": "^8.56.0",
+    "core-js": "^3.36.0",
+    "esbuild": "^0.20.1",
+    "eslint": "^8.57.0",
     "eslint-config-standard": "^17.1.0",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jest": "^27.6.0",
-    "eslint-plugin-jsdoc": "^46.9.1",
-    "eslint-plugin-node": "^11.0.0",
+    "eslint-plugin-jest": "^27.9.0",
+    "eslint-plugin-jsdoc": "^48.2.0",
+    "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^6.1.1",
     "jest": "^29.7.0",
     "pkg": "^5.8.1",
     "regenerator-runtime": "^0.14.1",
-    "shelljs": "^0.8.4",
-    "webpack": "^5.89.0",
+    "shelljs": "^0.8.5",
+    "typescript": "^5.4.2",
+    "webpack": "^5.90.3",
     "webpack-cli": "^5.1.4"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/videlais/extwee"
+    "url": "git+https://github.com/videlais/extwee.git"
   },
   "bugs": {
     "url": "https://github.com/videlais/extwee/issues"
   },
-  "type": "module"
+  "type": "module",
+  "types": "./types/index.d.ts"
 }

package/src/IFID/generate.js

@@ -0,0 +1,20 @@
+import { v4 } from 'uuid';
+
+/**
+ * Generates an Interactive Fiction Identification (IFID) based the Treaty of Babel.
+ *
+ * For Twine works, the IFID is a UUID (v4) in uppercase.
+ * @see Treaty of Babel ({@link https://babel.ifarchive.org/babel_rev11.html#the-ifid-for-an-html-story-file})
+ * @function generate
+ * @description Generates a new IFID.
+ * @returns {string} IFID
+ * @example
+ * const ifid = generate();
+ * console.log(ifid);
+ * // => 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6'
+ */
+function generate () {
+  return v4().toUpperCase();
+}
+
+export { generate };

package/src/JSON/parse.js

@@ -1,11 +1,54 @@
-import Story from '../Story.js';
+import { Story } from '../Story.js';
 import Passage from '../Passage.js';
 
 /**
  * Parse JSON representation into Story.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md Twine 2 JSON Specification}
  * @function parse
  * @param {string} jsonString - JSON string to convert to Story.
+ * @throws {Error} - Invalid JSON!
  * @returns {Story} Story object.
+ * @example
+ * const jsonString = `{
+ *  "name": "My Story",
+ *  "start": "First Passage",
+ *  "ifid": "A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6",
+ *  "format": "SugarCube",
+ *  "formatVersion": "2.31.0",
+ *  "creator": "Twine",
+ *  "creatorVersion": "2.3.9",
+ *  "zoom": 1,
+ *  "passages": [
+ *   {
+ *    "name": "First Passage",
+ *    "tags": "",
+ *    "metadata": "",
+ *    "text": "This is the first passage."
+ *   },
+ *  ]
+ * }`;
+ * const story = parse(jsonString);
+ * console.log(story);
+ * // => Story {
+ * //      name: 'My Story',
+ * //      start: 'First Passage',
+ * //      IFID: 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6',
+ * //      format: 'SugarCube',
+ * //      formatVersion: '2.31.0',
+ * //      creator: 'Twine',
+ * //      creatorVersion: '2.3.9',
+ * //      zoom: 1,
+ * //      tagColors: {},
+ * //      metadata: {},
+ * //      passages: [
+ * //        Passage {
+ * //          name: 'First Passage',
+ * //          tags: '',
+ * //          metadata: '',
+ * //          text: 'This is the first passage.'
+ * //        }
+ * //      ]
+ * //    }
  */
 function parse (jsonString) {
   // Create future object.

package/src/Passage.js

@@ -1,28 +1,68 @@
+import { encode } from 'html-entities';
+
 /**
- * A passage is the smallest unit of a Twine story.
- */
+  * Passage class.
+  * @class
+  * @classdesc Represents a passage in a Twine story.
+  * @property {string} name - Name of the passage.
+  * @property {Array} tags - Tags for the passage.
+  * @property {object} metadata - Metadata for the passage.
+  * @property {string} text - Text content of the passage.
+  * @method {string} toTwee - Return a Twee representation.
+  * @method {string} toJSON - Return JSON representation.
+  * @method {string} toTwine2HTML - Return Twine 2 HTML representation.
+  * @method {string} toTwine1HTML - Return Twine 1 HTML representation.
+  * @example
+  * const p = new Passage('Start', 'This is the start of the story.');
+  * console.log(p.toTwee());
+  * // :: Start
+  * // This is the start of the story.
+  * //
+  * console.log(p.toJSON());
+  * // {"name":"Start","tags":[],"metadata":{},"text":"This is the start of the story."}
+  * console.log(p.toTwine2HTML());
+  * // <tw-passagedata pid="1" name="Start" tags="" >This is the start of the story.</tw-passagedata>
+  * console.log(p.toTwine1HTML());
+  * // <div tiddler="Start" tags="" modifier="extwee" twine-position="10,10">This is the start of the story.</div>
+  * @example
+  * const p = new Passage('Start', 'This is the start of the story.', ['start', 'beginning'], {position: '10,10', size: '100,100'});
+  * console.log(p.toTwee());
+  * // :: Start [start beginning] {"position":"10,10","size":"100,100"}
+  * // This is the start of the story.
+  * //
+  * console.log(p.toJSON());
+  * // {"name":"Start","tags":["start","beginning"],"metadata":{"position":"10,10","size":"100,100"},"text":"This is the start of the story."}
+  * console.log(p.toTwine2HTML());
+  * // <tw-passagedata pid="1" name="Start" tags="start beginning" position="10,10" size="100,100">This is the start of the story.</tw-passagedata>
+  * console.log(p.toTwine1HTML());
+  * // <div tiddler="Start" tags="start beginning" modifier="extwee" twine-position="10,10">This is the start of the story.</div>
+  */ 
 export default class Passage {
   /**
    * Name of the Passage
    * @private
+   * @type {string}
    */
-  #_name = null;
+  #_name = '';
 
   /**
    * Internal array of tags
    * @private
+   * @type {Array}
    */
   #_tags = [];
 
   /**
    * Internal metadata of passage
    * @private
+   * @type {object}
    */
   #_metadata = {};
 
   /**
    * Internal text of the passage
    * @private
+   * @type {string}
    */
   #_text = '';
 
@@ -55,6 +95,7 @@ export default class Passage {
 
   /**
    * @param {string} s - Name to replace
+   * @throws {Error} Name must be a String!
    */
   set name (s) {
     if (typeof s === 'string') {
@@ -72,10 +113,12 @@ export default class Passage {
 
   /**
    * @param {Array} t - Replacement array
+   * @throws {Error} Tags must be an array!
    */
   set tags (t) {
     // Test if tags is an array
     if (Array.isArray(t)) {
+      // Set the tags.
       this.#_tags = t;
     } else {
       throw new Error('Tags must be an array!');
@@ -90,6 +133,7 @@ export default class Passage {
 
   /**
    * @param {object} m - Replacement object
+   * @throws {Error} Metadata must be an object literal!
    */
   set metadata (m) {
     // Test if metadata was an object
@@ -108,6 +152,7 @@ export default class Passage {
 
   /**
    * @param {string} t - Replacement text
+   * @throws {Error} Text should be a String!
    */
   set text (t) {
     // Test if text is a String
@@ -120,6 +165,10 @@ export default class Passage {
 
   /**
    * Return a Twee representation.
+   * 
+   * See: https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md
+   * 
+   * @method toTwee
    * @returns {string} String form of passage.
    */
   toTwee () {
@@ -150,6 +199,7 @@ export default class Passage {
 
   /**
    * Return JSON representation.
+   * @method toJSON
    * @returns {string} JSON string.
    */
   toJSON () {
@@ -168,6 +218,7 @@ export default class Passage {
   /**
    * Return Twine 2 HTML representation.
    * (Default Passage ID is 1.)
+   * @method toTwine2HTML
    * @param {number} pid - Passage ID (PID) to record in HTML.
    * @returns {string} Twine 2 HTML string.
    */
@@ -185,13 +236,13 @@ export default class Passage {
      * name: (string) Required.
      *   The name of the passage.
      */
-    passageData += ` name="${this.name}"`;
+    passageData += ` name="${ encode( this.name ) }"`;
 
     /**
      * tags: (string) Optional.
      *   Any tags for the passage separated by spaces.
      */
-    passageData += ` tags="${this.#_tags.join(' ')}" `;
+    passageData += ` tags="${ encode( this.#_tags.join(' ') ) }" `;
 
     /**
      * position: (string) Optional.
@@ -211,30 +262,8 @@ export default class Passage {
       passageData += `size="${this.#_metadata.size}" `;
     }
 
-    /**
-     * Escape passage Twine 2 passage text.
-     * @param {string} text - Text to escape.
-     * @returns {string} Escaped text.
-     */
-    const escape = function (text) {
-      const rules = [
-        ['&', '&amp;'],
-        ['<', '&lt;'],
-        ['>', '&gt;'],
-        ['"', '&quot;'],
-        ["'", '&#x27;'],
-        ['`', '&#x60;']
-      ];
-
-      rules.forEach(([rule, template]) => {
-        text = text.replaceAll(rule, template);
-      });
-
-      return text;
-    };
-
     // Add the text and close the element.
-    passageData += `>${escape(this.text)}</tw-passagedata>\n`;
+    passageData += `>${ encode( this.text ) }</tw-passagedata>\n`;
 
     // Return the Twine 2 HTML element.
     return passageData;
@@ -242,6 +271,7 @@ export default class Passage {
 
   /**
    * Return Twine 1 HTML representation.
+   * @method toTwine1HTML
    * @returns {string} Twine 1 HTML string.
    */
   toTwine1HTML () {
@@ -258,13 +288,13 @@ export default class Passage {
      * tiddler: (string) Required.
      *   The name of the passage.
      */
-    passageData += ` tiddler="${this.name}"`;
+    passageData += ` tiddler="${ encode( this.name ) }"`;
 
     /**
      * tags: (string) Required.
      *   Any tags for the passage separated by spaces.
      */
-    passageData += ` tags="${this.#_tags.join(' ')}" `;
+    passageData += ` tags="${ encode( this.#_tags.join(' ') ) }" `;
 
     /**
      * modifier: (string) Optional.
@@ -290,7 +320,7 @@ export default class Passage {
      * text: (string) Required.
      * Text content of the passage.
      */
-    passageData += `>${this.#_text}</div>`;
+    passageData += `>${ encode( this.#_text ) }</div>`;
 
     // Return the HTML representation.
     return passageData;