Introduce JSDoc-based Type System with checkJs flag

package.json

@@ -21,7 +21,7 @@
         "eslint": "^8.20.0",
         "istanbul": "^0.4.5",
         "standard-version": "^9.3.2",
-        "typescript": "^4.7.4"
+        "typescript": "^5.2.2"
     },
     "mappings": {
         "ace": "."
@@ -45,7 +45,8 @@
         "lint": "eslint \"src/**/*.js\"",
         "fix": "eslint --fix \"src/**/*.js\"",
         "changelog": "standard-version",
-        "prepack": "node tool/esm_resolver_generator.js && node Makefile.dryice.js css --target build-styles && rm -rf styles && mv build-styles/css styles"
+        "prepack": "node tool/esm_resolver_generator.js && node Makefile.dryice.js css --target build-styles && rm -rf styles && mv build-styles/css styles",
+        "tsc": "rimraf types && tsc --project tsconfig.json"
     },
     "standard-version": {
         "skip": {

src/ace.js

@@ -1,17 +1,16 @@
 /**
  * The main class required to set up an Ace instance in the browser.
  *
- * @class Ace
+ * @namespace Ace
  **/
-
 "use strict";
 "include loader_build";
 
 var dom = require("./lib/dom");
 
 var Range = require("./range").Range;
-var Editor = require("./editor").Editor;
 var EditSession = require("./edit_session").EditSession;
+var Editor = require("./editor").Editor;
 var UndoManager = require("./undomanager").UndoManager;
 var Renderer = require("./virtual_renderer").VirtualRenderer;
 
@@ -29,9 +28,9 @@ exports.config = require("./config");
 
 /**
  * Embeds the Ace editor into the DOM, at the element provided by `el`.
- * @param {String | Element} el Either the id of an element, or the element itself
- * @param {Object } options Options for the editor
- *
+ * @param {String | HTMLElement & {env?, value?}} el Either the id of an element, or the element itself
+ * @param {Object } [options] Options for the editor
+ * @returns {Editor}
  **/
 exports.edit = function(el, options) {
     if (typeof el == "string") {
@@ -56,7 +55,6 @@ exports.edit = function(el, options) {
     }
 
     var doc = exports.createEditSession(value);
-
     var editor = new Editor(new Renderer(el), doc, options);
 
     var env = {
@@ -74,9 +72,9 @@ exports.edit = function(el, options) {
 
 /**
  * Creates a new [[EditSession]], and returns the associated [[Document]].
- * @param {Document | String} text {:textParam}
- * @param {TextMode} mode {:modeParam}
- *
+ * @param {import('./document').Document | String} text {:textParam}
+ * @param {import("../ace").Ace.SyntaxMode} [mode] {:modeParam}
+ * @returns {EditSession}
  **/
 exports.createEditSession = function(text, mode) {
     var doc = new EditSession(text, mode);

src/anchor.js

@@ -1,5 +1,8 @@
 "use strict";
-
+/**
+ * @typedef Document
+ * @type {import("./document").Document}
+ */
 var oop = require("./lib/oop");
 var EventEmitter = require("./lib/event_emitter").EventEmitter;
 
@@ -11,22 +14,22 @@ class Anchor {
      * Creates a new `Anchor` and associates it with a document.
      *
      * @param {Document} doc The document to associate with the anchor
-     * @param {Number} row The starting row position
-     * @param {Number} column The starting column position
+     * @param {Number|import("../ace").Ace.Point} row The starting row position
+     * @param {Number} [column] The starting column position
      **/
     constructor(doc, row, column) {
         this.$onChange = this.onChange.bind(this);
         this.attach(doc);
 
-        if (typeof column == "undefined")
+        if (typeof row != "number")
             this.setPosition(row.row, row.column);
         else
             this.setPosition(row, column);
     }
 
     /**
      * Returns an object identifying the `row` and `column` position of the current anchor.
-     * @returns {Ace.Point}
+     * @returns {import("../ace").Ace.Point}
      **/
     getPosition() {
         return this.$clipPositionToDocument(this.row, this.column);
@@ -41,22 +44,9 @@ class Anchor {
         return this.document;
     }
 
-    /**
-     * Fires whenever the anchor position changes.
-     *
-     * Both of these objects have a `row` and `column` property corresponding to the position.
-     *
-     * Events that can trigger this function include [[Anchor.setPosition `setPosition()`]].
-     *
-     * @event change
-     * @param {Object} e  An object containing information about the anchor position. It has two properties:
-     *  - `old`: An object describing the old Anchor position
-     *  - `value`: An object describing the new Anchor position
-     *
-     **/
     /**
      * Internal function called when `"change"` event fired.
-     * @param {Ace.Delta} delta
+     * @param {import("../ace").Ace.Delta} delta
      */
     onChange(delta) {
         if (delta.start.row == delta.end.row && delta.start.row != this.row)
@@ -73,8 +63,7 @@ class Anchor {
      * Sets the anchor position to the specified row and column. If `noClip` is `true`, the position is not clipped.
      * @param {Number} row The row index to move the anchor to
      * @param {Number} column The column index to move the anchor to
-     * @param {Boolean} noClip Identifies if you want the position to be clipped
-     *
+     * @param {Boolean} [noClip] Identifies if you want the position to be clipped
      **/
     setPosition(row, column, noClip) {
         var pos;
@@ -125,7 +114,7 @@ class Anchor {
      * Clips the anchor position to the specified row and column.
      * @param {Number} row The row index to clip the anchor to
      * @param {Number} column The column index to clip the anchor to
-     * @returns {Ace.Point}
+     * @returns {import("../ace").Ace.Point}
      *
      **/
     $clipPositionToDocument(row, column) {

src/apply_delta.js

@@ -10,7 +10,7 @@
            position.column >= 0 && position.column <= docLines[position.row].length;
 }
 
 function validateDelta(docLines, delta) {
     // Validate action string.
     if (delta.action != "insert" && delta.action != "remove")
         throwDeltaError(delta, "delta.action must be 'insert' or 'remove'");
@@ -40,6 +40,12 @@
         throwDeltaError(delta, "delta.range must match delta lines");
 }
 
+/**
+ * Applies a delta to a document.
+ * @param {string[]} docLines
+ * @param {import("../ace").Ace.Delta} delta
+ * @param [doNotValidate]
+ */
 exports.applyDelta = function(docLines, delta, doNotValidate) {
     // disabled validation since it breaks autocompletion popup
     // if (!doNotValidate)
@@ -54,6 +60,7 @@
             if (lines.length === 1) {
                 docLines[row] = line.substring(0, startColumn) + delta.lines[0] + line.substring(startColumn);
             } else {
+                // @ts-ignore
                 var args = [row, 1].concat(delta.lines);
                 docLines.splice.apply(docLines, args);
                 docLines[row] = line.substring(0, startColumn) + docLines[row];