extwee 2.3.13 → 2.3.15

package/src/Story.js

@@ -7,7 +7,7 @@ import { encode } from 'html-entities';
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.3.13';
+const creatorVersion = '2.3.15';
 
 /**
  * Story class.
@@ -19,22 +19,22 @@ const creatorVersion = '2.3.13';
  * @property {string} format - Story format of Story.
  * @property {string} formatVersion - Story format version of Story.
  * @property {number} zoom - Zoom level.
- * @property {Array} passages - Array of Passage objects. @see {@link Passage}
+ * @property {Array} passages - Array of Passage objects. See {@link Passage}.
  * @property {string} creator - Program used to create Story.
  * @property {string} creatorVersion - Version used to create Story.
  * @property {object} metadata - Metadata of Story.
  * @property {object} tagColors - Tag Colors
  * @property {string} storyJavaScript - Story JavaScript
  * @property {string} storyStylesheet - Story Stylesheet
- * @method {number} addPassage - Add a passage to the story and returns the new length of the passages array.
- * @method {number} removePassageByName - Remove a passage from the story by name and returns the new length of the passages array.
- * @method {Array} getPassagesByTag - Find passages by tag.
- * @method {Array} getPassageByName - Find passage by name.
- * @method {number} size - Size (number of passages).
- * @method {string} toJSON - Export Story as JSON representation.
- * @method {string} toTwee - Return Twee representation.
- * @method {string} toTwine2HTML - Return Twine 2 HTML representation.
- * @method {string} toTwine1HTML - Return Twine 1 HTML representation.
+ * @function addPassage - Add a passage to the story and returns the new length of the passages array.
+ * @function removePassageByName - Remove a passage from the story by name and returns the new length of the passages array.
+ * @function getPassagesByTag - Find passages by tag.
+ * @function getPassageByName - Find passage by name.
+ * @function size - Size (number of passages).
+ * @function toJSON - Export Story as JSON representation.
+ * @function toTwee - Return Twee representation.
+ * @function toTwine2HTML - Return Twine 2 HTML representation.
+ * @function toTwine1HTML - Return Twine 1 HTML representation.
  * @example
  * const story = new Story('My Story');
  * story.IFID = '12345678-1234-5678-1234-567812345678';
@@ -148,6 +148,7 @@ class Story {
   get name () { return this.#_name; }
 
   /**
+   * Set story name.
    * @param {string} a - Replacement story name
    */
   set name (a) {
@@ -165,13 +166,14 @@ class Story {
   get tagColors () { return this.#_tagColors; }
 
   /**
+   * Set tag colors.
    * @param {object} a - Replacement tag colors
    */
   set tagColors (a) {
-    if (a instanceof Object) {
+    if (a !== null && typeof a === 'object' && !Array.isArray(a)) {
       this.#_tagColors = a;
     } else {
-      throw new Error('Tag colors must be an object!');
+      throw new Error('Tag colors must be a plain object!');
     }
   }
 
@@ -182,6 +184,7 @@ class Story {
   get IFID () { return this.#_IFID; }
 
   /**
+   * Set story IFID.
    * @param {string} i - Replacement IFID.
    */
   set IFID (i) {
@@ -199,6 +202,7 @@ class Story {
   get start () { return this.#_start; }
 
   /**
+   * Set start passage name.
    * @param {string} s - Replacement start
    */
   set start (s) {
@@ -216,6 +220,7 @@ class Story {
   get formatVersion () { return this.#_formatVersion; }
 
   /**
+   * Set story format version.
    * @param {string} f - Replacement format version
    */
   set formatVersion (f) {
@@ -233,13 +238,14 @@ class Story {
   get metadata () { return this.#_metadata; }
 
   /**
+   * Set story metadata.
    * @param {object} o - Replacement metadata
    */
   set metadata (o) {
-    if (typeof o === 'object') {
+    if (o !== null && typeof o === 'object') {
       this.#_metadata = o;
     } else {
-      throw new Error('Story metadata must be Object!');
+      throw new Error('Story metadata must be a non-null Object!');
     }
   }
 
@@ -250,6 +256,7 @@ class Story {
   get format () { return this.#_format; }
 
   /**
+   * Set story format.
    * @param {string} f - Replacement format
    */
   set format (f) {
@@ -267,6 +274,7 @@ class Story {
   get creator () { return this.#_creator; }
 
   /**
+   * Set creator program.
    * @param {string} c - Creator Program of Story
    */
   set creator (c) {
@@ -284,6 +292,7 @@ class Story {
   get creatorVersion () { return this.#_creatorVersion; }
 
   /**
+   * Set creator version.
    * @param {string} c - Version of creator program
    */
   set creatorVersion (c) {
@@ -301,14 +310,15 @@ class Story {
   get zoom () { return this.#_zoom; }
 
   /**
+   * Set zoom level.
    * @param {number} n - Replacement zoom level
    */
   set zoom (n) {
-    if (typeof n === 'number') {
+    if (typeof n === 'number' && Number.isFinite(n)) {
       // Parse float with a fixed length and then force into Number
       this.#_zoom = Number(Number.parseFloat(n).toFixed(2));
     } else {
-      throw new Error('Zoom level must be a Number!');
+      throw new Error('Zoom level must be a finite Number!');
     }
   }
 
@@ -316,7 +326,7 @@ class Story {
    * Passages in Story.
    * @returns {Array} Passages
    * @property {Array} passages - Passages
-  */
+   */
   get passages () { return this.#_passages; }
 
   /**
@@ -347,6 +357,7 @@ class Story {
   }
 
   /**
+   * Set story stylesheet.
    * @param {string} s - Replacement story stylesheet
    */
   set storyStylesheet (s) {
@@ -380,7 +391,7 @@ class Story {
   /**
    * Add a passage to the story.
    * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
-   * @method addPassage
+   * @function addPassage
    * @param {Passage} p - Passage to add to Story.
    * @returns {number} Return new length of passages array.
    */
@@ -492,7 +503,7 @@ class Story {
 
   /**
    * Remove a passage from the story by name.
-   * @method removePassageByName
+   * @function removePassageByName
    * @param {string} name - Passage name to remove.
    * @returns {number} Return new length of passages array.
    */
@@ -503,7 +514,7 @@ class Story {
 
   /**
    * Find passages by tag.
-   * @method getPassagesByTag
+   * @function getPassagesByTag
    * @param {string} t - Passage name to search for
    * @returns {Array} Return array of passages
    */
@@ -517,7 +528,7 @@ class Story {
 
   /**
    * Find passage by name.
-   * @method getPassageByName
+   * @function getPassageByName
    * @param {string} name - Passage name to search for
    * @returns {Passage | null} Return passage or null
    */
@@ -530,7 +541,7 @@ class Story {
 
   /**
    * Size (number of passages).
-   * @method size
+   * @function size
    * @returns {number} Return number of passages
    */
   size () {
@@ -539,7 +550,7 @@ class Story {
 
   /**
    * Export Story as JSON representation.
-   * @method toJSON
+   * @function toJSON
    * @returns {string} JSON string.
    */
   toJSON () {
@@ -579,8 +590,7 @@ class Story {
    *
    * See: Twee 3 Specification
    * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
-   * 
-   * @method toTwee
+   * @function toTwee
    * @returns {string} Twee String
    */
   toTwee () {
@@ -607,7 +617,7 @@ class Story {
 
     /**
      * format: (string) Optional. Maps to <tw-storydata format>.
-    */
+     */
     // Does format exist?
     if (this.format !== '') {
       // Write the existing format.
@@ -706,8 +716,7 @@ class Story {
    * Because story stylesheet data can be represented as a passage, property value, or both, all approaches are encoded.
    * 
    * Because story JavaScript can be represented as a passage, property value, or both, all approaches are encoded.
-   * 
-   * @method toTwine2HTML
+   * @function toTwine2HTML
    * @returns {string} Twine 2 HTML string
    */
   toTwine2HTML () {
@@ -852,9 +861,6 @@ class Story {
     // Filter out passages with tag of 'script'.
     const scriptPassages = passages.filter((passage) => passage.tags.includes('script'));
 
-    // Remove script passages from the main array.
-    passages = passages.filter(p => !p.tags.includes('script'));
-
     // Were there any script passages?
     if (scriptPassages.length > 0) {
       // Start the SCRIPT.
@@ -894,7 +900,7 @@ class Story {
     // For each tag, generate a <tw-tag> element.
     tagList.forEach((tag) => {
       // Add the <tw-tag> element.
-      storyData += `\t<tw-tag name="${tag}" color="${this.tagColors[tag]}"></tw-tag>\n`;
+      storyData += `\t<tw-tag name="${encode(tag)}" color="${encode(String(this.tagColors[tag]))}"></tw-tag>\n`;
     });
 
     // Close the HTML element.
@@ -909,8 +915,7 @@ class Story {
    *
    * See: Twine 1 HTML Output
    * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
-   * 
-   * @method toTwine1HTML
+   * @function toTwine1HTML
    * @returns {string} Twine 1 HTML string.
    */
   toTwine1HTML () {

package/src/StoryFormat/parse.js

@@ -85,13 +85,13 @@ function parse (contents) {
   }
 
   // Create an object literal
-  let jsonContent = {};
+  let jsonContent;
 
   // Attempt to parse the JSON.
   try {
     jsonContent = JSON.parse(contents);
   } catch (error) {
-    throw new Error(`Error: Unable to parse Twine 2 JSON chunk! ${error.message}`);
+    throw new Error(`Error: Unable to parse Twine 2 JSON chunk! ${error.message}`, { cause: error });
   }
 
   /**

package/src/StoryFormat.js

@@ -5,9 +5,7 @@ import { valid } from 'semver';
  * 
  * This class has type checking on all of its properties.
  * If a property is set to a value of the wrong type, a TypeError will be thrown.
- * 
  * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
- * 
  * @class
  * @classdesc A class representing a Twine 2 story format.
  * @property {string} name - The name of the story format.
@@ -107,6 +105,7 @@ export default class StoryFormat {
   get name () { return this.#_name; }
 
   /**
+   * Set name.
    * @param {string} n - Replacement name.
    */
   set name (n) {
@@ -124,6 +123,7 @@ export default class StoryFormat {
   get version () { return this.#_version; }
 
   /**
+   * Set version.
    * @param {string} n - Replacement version.
    */
   set version (n) {
@@ -141,6 +141,7 @@ export default class StoryFormat {
   get description () { return this.#_description; }
 
   /**
+   * Set description.
    * @param {string} d - Replacement description.
    */
   set description (d) {
@@ -158,6 +159,7 @@ export default class StoryFormat {
   get author () { return this.#_author; }
 
   /**
+   * Set author.
    * @param {string} a - Replacement author.
    */
   set author (a) {
@@ -175,6 +177,7 @@ export default class StoryFormat {
   get image () { return this.#_image; }
 
   /**
+   * Set image.
    * @param {string} i - Replacement image.
    */
   set image (i) {
@@ -192,6 +195,7 @@ export default class StoryFormat {
   get url () { return this.#_url; }
 
   /**
+   * Set URL.
    * @param {string} u - Replacement URL.
    */
   set url (u) {
@@ -209,6 +213,7 @@ export default class StoryFormat {
   get license () { return this.#_license; }
 
   /**
+   * Set license.
    * @param {string} l - Replacement license.
    */
   set license (l) {
@@ -226,6 +231,7 @@ export default class StoryFormat {
   get proofing () { return this.#_proofing; }
 
   /**
+   * Set proofing.
    * @param {boolean} p - Replacement proofing.
    */
   set proofing (p) {
@@ -243,6 +249,7 @@ export default class StoryFormat {
   get source () { return this.#_source; }
 
   /**
+   * Set source.
    * @param {string} s - Replacement source.
    */
   set source (s) {
@@ -255,7 +262,7 @@ export default class StoryFormat {
 
   /**
    * Produces a string representation of the story format object.
-   * @method toString
+   * @function toString
    * @returns {string} - A string representation of the story format.
    */
   toString() {
@@ -264,7 +271,7 @@ export default class StoryFormat {
 
   /**
    * Produces a JSON representation of the story format object.
-   * @method toJSON
+   * @function toJSON
    * @returns {object} - A JSON representation of the story format.
    */
   toJSON() {

package/src/TWS/parse.js

@@ -21,7 +21,7 @@ function parse (binaryFileContents) {
   const parser = new Parser();
 
   // Set default value.
-  let pythonObject = null;
+  let pythonObject;
 
   // Does the Buffer contain pickle data?
   try {
@@ -29,7 +29,7 @@ function parse (binaryFileContents) {
     pythonObject = parser.parse(binaryFileContents);
   } catch (error) {
     // This is a Buffer, but not pickle data.
-    throw new TypeError(`Error: Buffer does not contain Python pickle data! ${error}`);
+    throw new TypeError(`Error: Buffer does not contain Python pickle data! ${error}`, { cause: error });
   }
 
   // Create Story object.

package/src/Twee/parse.js

@@ -119,7 +119,7 @@ function parse (fileContents) {
     throw new Error('Contents not a String');
   }
 
-  let adjusted = '';
+  let adjusted;
 
   // Check if there are extra content in the files
   // If so, cut it all out for the parser
@@ -143,8 +143,8 @@ function parse (fileContents) {
     // Set default values
     let tags = '';
     let metadata = '';
-    let text = '';
-    let name = '';
+    let text;
+    let name;
 
     // Header is everything to the first newline
     let header = passage.slice(0, passage.indexOf('\n'));

package/src/Twine1HTML/compile.js

@@ -21,36 +21,36 @@ function compile (story, engine = '', header = '', name = '', codeJS = '', confi
   }
 
   // Replace the "VERSION" with story.creator.
-  header = header.replaceAll(/"VERSION"/gm, story.creator);
+  header = header.replaceAll(/"VERSION"/gm, () => story.creator);
 
   // Replace the "TIME" with new Date().
-  header = header.replaceAll(/"TIME"/gm, new Date());
+  header = header.replaceAll(/"TIME"/gm, () => String(new Date()));
 
   // Replace the ENGINE with `engine.js` code.
-  header = header.replaceAll(/"ENGINE"/gm, engine);
+  header = header.replaceAll(/"ENGINE"/gm, () => engine);
 
   // Replace the NAME (e.g. "JONAH") with `engine.js` code.
-  header = header.replaceAll(`"${name.toUpperCase()}"`, codeJS);
+  header = header.replaceAll(`"${name.toUpperCase()}"`, () => codeJS);
 
   // Replace "STORY_SIZE".
-  header = header.replaceAll(/"STORY_SIZE"/gm, `"${story.size()}"`);
+  header = header.replaceAll(/"STORY_SIZE"/gm, () => `"${story.size()}"`);
 
   // Replace "STORY" with Twine 1 HTML.
-  header = header.replaceAll(/"STORY"/gm, story.toTwine1HTML());
+  header = header.replaceAll(/"STORY"/gm, () => story.toTwine1HTML());
 
   // Replace START_AT with ''.
-  header = header.replaceAll(/"START_AT"/gm, '\'\'');
+  header = header.replaceAll(/"START_AT"/gm, () => '\'\'');
 
   // Does 'jquery' exist?
   if (Object.prototype.hasOwnProperty.call(config, 'jquery')) {
     // Replace JQUERY with jQuery.
-    header = header.replaceAll(/"JQUERY"/gm, config.jquery);
+    header = header.replaceAll(/"JQUERY"/gm, () => config.jquery);
   }
 
   // Does 'modernizr' exist?
   if (Object.prototype.hasOwnProperty.call(config, 'modernizr')) {
     // Replace "MODERNIZR" with Modernizr.
-    header = header.replaceAll(/"MODERNIZR"/gm, config.modernizr);
+    header = header.replaceAll(/"MODERNIZR"/gm, () => config.modernizr);
   }
 
   // Return code.

package/types/src/Passage.d.ts

@@ -1,40 +1,40 @@
 /**
-  * 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>
-  */
+ * 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.
+ * @function toTwee - Return a Twee representation.
+ * @function toJSON - Return JSON representation.
+ * @function toTwine2HTML - Return Twine 2 HTML representation.
+ * @function 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 {
     /**
      * Create a passage.
@@ -45,6 +45,7 @@ export default class Passage {
      */
     constructor(name?: string, text?: string, tags?: any[], metadata?: object);
     /**
+     * Set passage name.
      * @param {string} s - Name to replace
      * @throws {Error} Name must be a String!
      */
@@ -55,6 +56,7 @@ export default class Passage {
      */
     get name(): string;
     /**
+     * Set passage tags.
      * @param {Array} t - Replacement array
      * @throws {Error} Tags must be an array!
      */
@@ -65,6 +67,7 @@ export default class Passage {
      */
     get tags(): any[];
     /**
+     * Set passage metadata.
      * @param {object} m - Replacement object
      * @throws {Error} Metadata must be an object literal!
      */
@@ -75,6 +78,7 @@ export default class Passage {
      */
     get metadata(): object;
     /**
+     * Set passage text.
      * @param {string} t - Replacement text
      * @throws {Error} Text should be a String!
      */
@@ -88,28 +92,27 @@ export default class Passage {
      * Return a Twee representation.
      *
      * See: https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md
-     *
-     * @method toTwee
+     * @function toTwee
      * @returns {string} String form of passage.
      */
     toTwee(): string;
     /**
      * Return JSON representation.
-     * @method toJSON
+     * @function toJSON
      * @returns {string} JSON string.
      */
     toJSON(): string;
     /**
      * Return Twine 2 HTML representation.
      * (Default Passage ID is 1.)
-     * @method toTwine2HTML
+     * @function toTwine2HTML
      * @param {number} pid - Passage ID (PID) to record in HTML.
      * @returns {string} Twine 2 HTML string.
      */
     toTwine2HTML(pid?: number): string;
     /**
      * Return Twine 1 HTML representation.
-     * @method toTwine1HTML
+     * @function toTwine1HTML
      * @returns {string} Twine 1 HTML string.
      */
     toTwine1HTML(): string;