Fix: Adding script to generate TypeScript types

package.json

@@ -13,7 +13,8 @@
     "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",

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;

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';

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;
+}