extwee 2.2.2 → 2.2.3

package/jest.config.json

@@ -0,0 +1,5 @@
+{
+    "bail": 1,
+    "verbose": true,
+    "collectCoverage": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -8,12 +8,13 @@
     "extwee": "src/extwee.js"
   },
   "scripts": {
-    "test": "jest --runInBand --coverage --colors",
+    "test": "jest --runInBand",
     "lint": "eslint ./src/**/*.js --fix",
     "lint:test": "eslint ./test/**/*.test.js --fix",
     "build:web": "webpack",
     "build:bin": "esbuild ./src/extwee.js --bundle --platform=node --target=node12 --outfile=out.js && pkg -t node18-macos-x64 out.js --output ./build/extwee && rm out.js",
-    "all": "npm run lint && npm run lint:test && npm run test"
+    "gen-types": "npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types",
+    "all": "npm run lint && npm run lint:test && npm run test && npm run gen-types"
   },
   "keywords": [
     "twine",
@@ -24,36 +25,38 @@
   "license": "MIT",
   "dependencies": {
     "commander": "^12.0.0",
+    "graphemer": "^1.4.0",
     "html-entities": "^2.5.2",
-    "node-html-parser": "^6.1.12",
+    "node-html-parser": "^6.1.13",
     "pickleparser": "^0.2.1",
     "semver": "^7.6.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@babel/cli": "^7.23.4",
-    "@babel/core": "^7.24.0",
-    "@babel/eslint-parser": "^7.23.10",
+    "@babel/cli": "^7.24.1",
+    "@babel/core": "^7.24.4",
+    "@babel/eslint-parser": "^7.24.1",
     "@babel/eslint-plugin": "^7.23.5",
-    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-env": "^7.24.4",
     "@types/uuid": "^9.0.7",
     "babel-loader": "^9.1.3",
-    "clean-jsdoc-theme": "^4.2.17",
-    "core-js": "^3.36.0",
-    "esbuild": "^0.20.1",
+    "clean-jsdoc-theme": "^4.2.18",
+    "core-js": "^3.36.1",
+    "esbuild": "^0.20.2",
     "eslint": "^8.57.0",
     "eslint-config-standard": "^17.1.0",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jest": "^27.9.0",
-    "eslint-plugin-jsdoc": "^48.2.0",
+    "eslint-plugin-jest": "^28.2.0",
+    "eslint-plugin-jsdoc": "^48.2.3",
+    "eslint-plugin-n": "^16.6.2",
     "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.5",
-    "typescript": "^5.4.2",
-    "webpack": "^5.90.3",
+    "typescript": "^5.4.5",
+    "webpack": "^5.91.0",
     "webpack-cli": "^5.1.4"
   },
   "repository": {

package/src/Story.js

@@ -3,7 +3,7 @@ import { generate as generateIFID } from './IFID/generate.js';
 import { encode } from 'html-entities';
 
 const creatorName = 'extwee';
-const creatorVersion = '2.2.2';
+const creatorVersion = '2.2.3';
 
 /**
  * Story class.

package/test/{Passage.test.js → Objects/Passage.test.js}

@@ -1,4 +1,4 @@
-import Passage from '../src/Passage.js';
+import Passage from '../../src/Passage.js';
 import { parse as HTMLParser } from 'node-html-parser';
 
 describe('Passage', () => {
@@ -218,8 +218,8 @@ describe('Passage', () => {
     });
 
     it('Should escape meta-characters safely in Twee header', function () {
-      const p = new Passage('Where do tags begin? [well',  '', ['hmm']);
-      expect(p.toTwee().includes('Where do tags begin? \[well [hmm]')).toBe(true);
+      const p = new Passage('Where do tags begin? [well', '', ['hmm']);
+      expect(p.toTwee().includes('Where do tags begin? [well [hmm]')).toBe(true);
     });
 
     it('Should produce valid HTML attributes', function () {
@@ -232,7 +232,7 @@ describe('Passage', () => {
       expect(d.querySelector('tw-passagedata').getAttribute('tags')).toBe('&tag "bad"');
       expect(d.querySelector('tw-passagedata').getAttribute('position')).toBe('100,100');
       // Use Twine 2 result.
-      const s = `<tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="100,100" size="100,100"></tw-passagedata>`;
+      const s = '<tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="100,100" size="100,100"></tw-passagedata>';
       // Parse HTML.
       const t = new HTMLParser(s);
       // Test Twine 2 attributes.

package/test/{Story.test.js → Objects/Story.test.js}

@@ -1,9 +1,9 @@
-import { Story, creatorName, creatorVersion } from '../src/Story.js';
-import Passage from '../src/Passage';
-import { parse as parseTwee } from '../src/Twee/parse.js';
+import { Story, creatorName, creatorVersion } from '../../src/Story.js';
+import Passage from '../../src/Passage.js';
+import { parse as parseTwee } from '../../src/Twee/parse.js';
 import { readFileSync } from 'node:fs';
 import { parse as HTMLParser } from 'node-html-parser';
-import { generate as generateIFID } from '../src/IFID/generate.js';
+import { generate as generateIFID } from '../../src/IFID/generate.js';
 
 // Pull the name and version of this project from package.json.
 // These are used as the 'creator' and 'creator-version'.
@@ -444,7 +444,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for format in metadata, should not exist.
-      expect(t.includes(`"'format":`)).not.toBe(true);
+      expect(t.includes('"\'format":')).not.toBe(true);
     });
 
     it('Should not generate formatVersion if empty', function () {
@@ -461,7 +461,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for formatVersion in metadata, should not exist.
-      expect(t.includes(`"'format-version":`)).not.toBe(true);
+      expect(t.includes('"\'format-version":')).not.toBe(true);
     });
 
     it('Should not generate zoom if zero', function () {
@@ -478,7 +478,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for zoom in metadata, should not exist.
-      expect(t.includes(`"'zoom":`)).not.toBe(true);
+      expect(t.includes('"\'zoom":')).not.toBe(true);
     });
 
     it('Should not generate start if empty', function () {
@@ -495,7 +495,7 @@ describe('Story', () => {
       const t = s.toTwee();
 
       // Test for start in metadata, should not exist.
-      expect(t.includes(`"'start":`)).not.toBe(true);
+      expect(t.includes('"\'start":')).not.toBe(true);
     });
 
     it('Should detect StoryTitle text', function () {
@@ -781,7 +781,7 @@ describe('Story', () => {
       expect(result.includes(`creator-version="${creatorVersion}"`)).not.toBe(true);
     });
 
-   it('Should not encode creator if not set', () => {
+    it('Should not encode creator if not set', () => {
       // Add passage.
       s.addPassage(new Passage('Start', 'Word'));
       // Set start.
@@ -793,7 +793,6 @@ describe('Story', () => {
       // Expect the creator to be encoded.
       expect(result.includes(`creator="${creatorName}"`)).not.toBe(true);
     });
-
   });
 
   describe('toTwine1HTML()', function () {
@@ -828,7 +827,7 @@ describe('Story', () => {
       // Expect correct name attribute for tw-passagedata.
       expect(root.querySelector('tw-passagedata').getAttribute('name')).toBe('"Test"');
       // Use Twine 2 result.
-      const s2 = `<tw-storydata name="&quot;Abuse&quot; &amp;test" startnode="1" creator="Twine" creator-version="2.8.1" format="Harlowe" format-version="3.3.8" ifid="452A9D80-C759-42C5-B001-5B861A2410C5" options="" tags="" zoom="1" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="300,100" size="100,100"></tw-passagedata></tw-storydata>`;
+      const s2 = '<tw-storydata name="&quot;Abuse&quot; &amp;test" startnode="1" creator="Twine" creator-version="2.8.1" format="Harlowe" format-version="3.3.8" ifid="452A9D80-C759-42C5-B001-5B861A2410C5" options="" tags="" zoom="1" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="300,100" size="100,100"></tw-passagedata></tw-storydata>';
       // Parse HTML.
       const root2 = HTMLParser(s2);
       // Expect correct name attribute for tw-storydata.

package/test/{StoryFormat.test.js → Objects/StoryFormat.test.js}

@@ -1,4 +1,4 @@
-import StoryFormat from '../src/StoryFormat.js';
+import StoryFormat from '../../src/StoryFormat.js';
 
 describe('StoryFormat', () => {
   describe('Default values', () => {
@@ -153,7 +153,7 @@ describe('StoryFormat', () => {
   describe('toString', () => {
     it('Should return string representation', () => {
       const sf = new StoryFormat();
-      expect(sf.toString()).toBe(JSON.stringify(sf, null, "\t"));
+      expect(sf.toString()).toBe(JSON.stringify(sf, null, '\t'));
     });
   });
 });

package/types/IFID/generate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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'
+ */
+export function generate(): string;

package/types/JSON/parse.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.'
+ * //        }
+ * //      ]
+ * //    }
+ */
+export function parse(jsonString: string): Story;
+import { Story } from '../Story.js';

package/types/Passage.d.ts

@@ -0,0 +1,117 @@
+/**
+  * 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 {
+    /**
+     * Create a passage.
+     * @param {string} name - Name
+     * @param {string} text - Content
+     * @param {Array} tags - Tags
+     * @param {object} metadata - Metadata
+     */
+    constructor(name?: string, text?: string, tags?: any[], metadata?: object);
+    /**
+     * @param {string} s - Name to replace
+     * @throws {Error} Name must be a String!
+     */
+    set name(s: string);
+    /**
+     * Name
+     * @returns {string} Name
+     */
+    get name(): string;
+    /**
+     * @param {Array} t - Replacement array
+     * @throws {Error} Tags must be an array!
+     */
+    set tags(t: any[]);
+    /**
+     * Tags
+     * @returns {Array} Tags
+     */
+    get tags(): any[];
+    /**
+     * @param {object} m - Replacement object
+     * @throws {Error} Metadata must be an object literal!
+     */
+    set metadata(m: any);
+    /**
+     * Metadata
+     * @returns {object} Metadata
+     */
+    get metadata(): any;
+    /**
+     * @param {string} t - Replacement text
+     * @throws {Error} Text should be a String!
+     */
+    set text(t: string);
+    /**
+     * Text
+     * @returns {string} Text
+     */
+    get text(): string;
+    /**
+     * 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(): string;
+    /**
+     * Return JSON representation.
+     * @method toJSON
+     * @returns {string} JSON string.
+     */
+    toJSON(): string;
+    /**
+     * 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.
+     */
+    toTwine2HTML(pid?: number): string;
+    /**
+     * Return Twine 1 HTML representation.
+     * @method toTwine1HTML
+     * @returns {string} Twine 1 HTML string.
+     */
+    toTwine1HTML(): string;
+    #private;
+}

package/types/Story.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Story class.
+ * @class
+ * @classdesc Represents a Twine story.
+ * @property {string} name - Name of the story.
+ * @property {string} IFID - Interactive Fiction ID (IFID) of Story.
+ * @property {string} start - Name of start passage.
+ * @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 {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
+ * @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.
+ * @example
+ * const story = new Story('My Story');
+ * story.IFID = '12345678-1234-5678-1234-567812345678';
+ * story.start = 'Start';
+ * story.format = 'SugarCube';
+ * story.formatVersion = '2.31.0';
+ * story.zoom = 1;
+ * story.creator = 'extwee';
+ * story.creatorVersion = '2.2.1';
+ */
+export class Story {
+    /**
+     * Creates a story.
+     * @param {string} name - Name of the story.
+     */
+    constructor(name?: string);
+    /**
+     * @param {string} a - Replacement story name
+     */
+    set name(a: string);
+    /**
+     * Each story has a name
+     * @returns {string} Name
+     */
+    get name(): string;
+    /**
+     * @param {object} a - Replacement tag colors
+     */
+    set tagColors(a: any);
+    /**
+     * Tag Colors object (each property is a tag and its color)
+     * @returns {object} tag colors array
+     */
+    get tagColors(): any;
+    /**
+     * @param {string} i - Replacement IFID.
+     */
+    set IFID(i: string);
+    /**
+     * Interactive Fiction ID (IFID) of Story.
+     * @returns {string} IFID
+     */
+    get IFID(): string;
+    /**
+     * @param {string} s - Replacement start
+     */
+    set start(s: string);
+    /**
+     * Name of start passage.
+     * @returns {string} start
+     */
+    get start(): string;
+    /**
+     * @param {string} f - Replacement format version
+     */
+    set formatVersion(f: string);
+    /**
+     * Story format version of Story.
+     * @returns {string} story format version
+     */
+    get formatVersion(): string;
+    /**
+     * @param {object} o - Replacement metadata
+     */
+    set metadata(o: any);
+    /**
+     * Metadata of Story.
+     * @returns {object} metadata of story
+     */
+    get metadata(): any;
+    /**
+     * @param {string} f - Replacement format
+     */
+    set format(f: string);
+    /**
+     * Story format of Story.
+     * @returns {string} format
+     */
+    get format(): string;
+    /**
+     * @param {string} c - Creator Program of Story
+     */
+    set creator(c: string);
+    /**
+     * Program used to create Story.
+     * @returns {string} Creator Program
+     */
+    get creator(): string;
+    /**
+     * @param {string} c - Version of creator program
+     */
+    set creatorVersion(c: string);
+    /**
+     * Version used to create Story.
+     * @returns {string} Version
+     */
+    get creatorVersion(): string;
+    /**
+     * @param {number} n - Replacement zoom level
+     */
+    set zoom(n: number);
+    /**
+     * Zoom level.
+     * @returns {number} Zoom level
+     */
+    get zoom(): number;
+    /**
+     * Set passages in Story.
+     * @param {Array} p - Replacement passages
+     * @property {Array} passages - Passages
+     * @throws {Error} Passages must be an Array!
+     * @throws {Error} Passages must be an Array of Passage objects!
+     */
+    set passages(p: any[]);
+    /**
+     * Passages in Story.
+     * @returns {Array} Passages
+     * @property {Array} passages - Passages
+    */
+    get passages(): any[];
+    /**
+     * Add a passage to the story.
+     * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
+     * @method addPassage
+     * @param {Passage} p - Passage to add to Story.
+     * @returns {number} Return new length of passages array.
+     */
+    addPassage(p: Passage): number;
+    /**
+     * Remove a passage from the story by name.
+     * @method removePassageByName
+     * @param {string} name - Passage name to remove.
+     * @returns {number} Return new length of passages array.
+     */
+    removePassageByName(name: string): number;
+    /**
+     * Find passages by tag.
+     * @method getPassagesByTag
+     * @param {string} t - Passage name to search for
+     * @returns {Array} Return array of passages
+     */
+    getPassagesByTag(t: string): any[];
+    /**
+     * Find passage by name.
+     * @method getPassageByName
+     * @param {string} name - Passage name to search for
+     * @returns {Passage | null} Return passage or null
+     */
+    getPassageByName(name: string): Passage | null;
+    /**
+     * Size (number of passages).
+     * @method size
+     * @returns {number} Return number of passages
+     */
+    size(): number;
+    /**
+     * Export Story as JSON representation.
+     * @method toJSON
+     * @returns {string} JSON string.
+     */
+    toJSON(): string;
+    /**
+     * Return Twee representation.
+     *
+     * See: Twee 3 Specification
+     * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
+     *
+     * @method toTwee
+     * @returns {string} Twee String
+     */
+    toTwee(): string;
+    /**
+     * Return Twine 2 HTML.
+     *
+     * See: Twine 2 HTML Output
+     * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md)
+     *
+     *  The only required attributes are `name` and `ifid` of the `<tw-storydata>` element. All others are optional.
+     *
+     * The `<tw-storydata>` element may have any number of optional attributes, which are:
+     * - `startnode`: (integer) Optional. The PID of the starting passage.
+     * - `creator`: (string) Optional. The name of the program that created the story.
+     * - `creator-version`: (string) Optional. The version of the program that created the story.
+     * - `zoom`: (decimal) Optional. The zoom level of the story.
+     * - `format`: (string) Optional. The format of the story.
+     * - `format-version`: (string) Optional. The version of the format of the story.
+     *
+     * @method toTwine2HTML
+     * @returns {string} Twine 2 HTML string
+     */
+    toTwine2HTML(): string;
+    /**
+     * Return Twine 1 HTML.
+     *
+     * See: Twine 1 HTML Output
+     * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
+     *
+     * @method toTwine1HTML
+     * @returns {string} Twine 1 HTML string.
+     */
+    toTwine1HTML(): string;
+    #private;
+}
+export const creatorName: "extwee";
+export const creatorVersion: "2.2.3";
+import Passage from './Passage.js';

package/types/StoryFormat/parse.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Parses story format content into a {@link StoryFormat} object.
+ *
+ * Story formats are generally JSONP files containing a JSON object with the following properties:
+ * - name: (string) Optional. (Omitting the name will lead to an Untitled Story Format.)
+ * - version: (string) Required, and semantic version-style formatting (x.y.z, e.g., 1.2.1) of the version is also required.
+ * - author: (string) Optional.
+ * - description: (string) Optional.
+ * - image: (string) Optional.
+ * - url: (string) Optional.
+ * - license: (string) Optional.
+ * - proofing: (boolean) Optional (defaults to false).
+ * - source: (string) Required.
+ *
+ * If existing properties do not match their expected type, a warning will be produced and incoming value will be ignored.
+ *
+ * This function does "soft parsing." It will not throw an error if a specific property is missing or malformed.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
+ * @function parse
+ * @param {string} contents - JSONP content.
+ * @throws {Error} - Unable to find Twine 2 JSON chunk!
+ * @throws {Error} - Unable to parse Twine 2 JSON chunk!
+ * @returns {StoryFormat} StoryFormat object.
+ * @example
+ * const contents = `{
+ * "name": "My Story Format",
+ * "version": "1.0.0",
+ * "author": "Twine",
+ * "description": "A story format.",
+ * "image": "icon.svg",
+ * "url": "https://example.com",
+ * "license": "MIT",
+ * "proofing": false,
+ * "source": "<html></html>"
+ * }`;
+ * const storyFormat = parse(contents);
+ * console.log(storyFormat);
+ * // => StoryFormat {
+ * //      name: 'My Story Format',
+ * //      version: '1.0.0',
+ * //      description: 'A story format.',
+ * //      image: 'icon.svg',
+ * //      url: 'https://example.com',
+ * //      license: 'MIT',
+ * //      proofing: false,
+ * //      source: '<html></html>'
+ * //    }
+ */
+export function parse(contents: string): StoryFormat;
+import StoryFormat from '../StoryFormat.js';