Declarations for engine and controller scripting API

.eslintrc.json

@@ -1,13 +1,17 @@
 {
-  "extends": [ "eslint:recommended", "plugin:jsdoc/recommended" ],
+  "extends": [ "eslint:recommended",
+               "plugin:jsdoc/recommended",
+               "plugin:@typescript-eslint/recommended" ],
+
+  "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaVersion": 7,
     "sourceType": "script"
   },
   "env": {
     "es6": true
   },
-  "plugins": [ "jsdoc" ],
+  "plugins": [ "jsdoc", "@typescript-eslint" ],
   "settings": {
     "jsdoc": {
       "preferredTypes": {
@@ -93,6 +97,12 @@
     "console": "readonly"
   },
   "overrides": [
+   {
+       "files": [ "res/controllers/*.d.ts" ],
+       "rules": {
+         "no-unused-vars": "off"
+       }
+    },
     {
       "files": [ "**/*.mjs" ],
       "parserOptions": {

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
       - id: trailing-whitespace
-        exclude: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|mm|proto|vert)$
+        exclude: \.(c|cc|cxx|cpp|d.ts|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|mm|proto|vert)$
       - id: no-commit-to-branch
         # protect main and any branch that has a semver-like name
         args: [-b, main, -p, '^\d+\.\d+(?:\.\d+)?$']
@@ -62,20 +62,22 @@ repos:
             --ignore-regex,
             "\\W(?:m_p*(?=[A-Z])|m_(?=\\w)|pp*(?=[A-Z])|k(?=[A-Z])|s_(?=\\w))",
           ]
-        exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|ts|wxl|svg))$
+        exclude: ^(packaging/wix/LICENSE.rtf|src/dialog/dlgabout\.cpp|.*\.(?:pot?|(?<!d\.)ts|wxl|svg))$
   - repo: https://github.com/pre-commit/mirrors-eslint
     rev: v8.25.0
     hooks:
       - id: eslint
         args: [--fix, --report-unused-disable-directives]
-        files: \.m?js$
+        files: \.m?[jt]s$
         types: [file]
         stages:
           - commit
           - manual
         additional_dependencies:
           - eslint@^v8.6.0
           - eslint-plugin-jsdoc@^v37.5.0
+          - "@typescript-eslint/eslint-plugin"
+          - "@typescript-eslint/parser"
   - repo: local
     hooks:
       - id: clang-format

res/controllers/color-mapper-api.d.ts

@@ -0,0 +1,29 @@
+
+/** ColorMapperJSProxy */
+
+declare class ColorMapper {
+    /**
+     * Constructs a ColorMapper object which maps RGB colors to device specific color codes
+     *
+     * @param availableColors List of number pairs (e.g. {0xFF0000: 1, 0x00FF00: 2} )
+     */
+    constructor (availableColors: { [rgbColor: number]: number });
+
+    /**
+     * For a given RGB color code (e.g. 0xFF0000), this finds the nearest
+     * available color and returns a JS object with properties "red", "green",
+     * "blue" (each with value range 0-255).
+     *
+     * @param colorCode Device specific color code
+     */
+    getNearestColor(colorCode: number): {[rgb: number]: number};
+
+    /**
+     * For a given RGB color code (e.g. 0xFF0000), this finds the nearest
+     * available color, then returns the value associated with that color
+     * (which could be a MIDI byte value for example).
+     *
+     * @param rgbColor RGB color (e.g. 0xFF00CC)
+     */
+    getValueForNearestColor(rgbColor: number): number;
+}

res/controllers/console-api.d.ts

@@ -0,0 +1,138 @@
+
+/**
+     Mixxx installs the QJSEngine::ConsoleExtension for the use in controller mapping scripts.
+    See also:
+      https://doc.qt.io/qt-5/qtquick-debugging.html#console-api
+      https://developer.mozilla.org/en-US/docs/Web/API/console
+      https://console.spec.whatwg.org/
+ */
+
+declare namespace console {
+    /**
+     * Prints debugging information to the console, when
+     * QT_LOGGING_RULES="js.debug=true;" or
+     * Mixxx is started with --controller-debug
+     * This function is identical to console.debug
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function log(...data: any[]): void;
+
+    /**
+     * Prints debugging information to the console, when
+     * QT_LOGGING_RULES="js.debug=true;" or
+     * Mixxx is started with --controller-debug
+     * This function is identical to console.log
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function debug(...data: any[]): void;
+
+    /**
+     * Prints information to the console, when
+     * QT_LOGGING_RULES="js.info=true;" or
+     * Mixxx is started with --controller-debug
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function info(...data: any[]): void;
+
+    /**
+     * Prints a warning message to the console, when
+     * QT_LOGGING_RULES="js.warning=true;" or
+     * Mixxx is started with --controller-debug
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function warn(...data: any[]): void;
+
+    /**
+     * Prints an error message to the console, when
+     * QT_LOGGING_RULES="js.critical=true;" or
+     * Mixxx is started with --controller-debug
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function error(...data: any[]): void;
+
+    /**
+     * Tests that a boolean expression is true,
+     * if not, it writes an (optional) message to the console and prints the stack trace.
+     *
+     * @param condition If the condition is false, it prints message and stack trace
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function assert(condition: boolean, ...data: any[]): void;
+
+    /**
+     * Starts the time measurement, which will be printed by timeEnd
+     *
+     * @param label string argument that identifies the measurement.
+     */
+    function time(label?: string): void;
+    /**
+     * Logs the time (in milliseconds) that was spent since the call of the time method.
+     *
+     * @param label string argument that identifies the measurement.
+     */
+    function timeEnd(label?: string): void;
+
+    /**
+     * Prints the stack trace of the JavaScript execution at the point where it was called.
+     * This stack trace information contains the function name, file name, line number, and column number.
+     * The stack trace is limited to last 10 stack frames.
+     *
+     * Unfortunately this function does use the wrong logging category "default" instead of "js",
+     * which is set when you start Mixxx with --controller-debug. Without setting logging category
+     * "default" manually, you will not see any output.
+     * [see QTBUG-108673]{@link https://bugreports.qt.io/browse/QTBUG-108673}
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function trace(...data: any[]): void;
+
+    /**
+     * Prints the current number of times a particular piece of code has run, along with a message.
+     *
+     * @param label
+     */
+    function count(label?: string): void;
+
+    /**
+     *  Turns on the JavaScript profiler.
+     *
+     *  @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419}
+     */
+     function profile(label?: string): void;
+
+    /**
+     *  Turns off the JavaScript profiler.
+     *
+     *  @deprecated Not usable for controller mappings for now [see QTBUG-65419]{@link https://bugreports.qt.io/browse/QTBUG-65419}
+     */
+    function profileEnd(label?: string): void;
+
+    /**
+     * Prints an error message together with the stack trace of JavaScript execution at the point where it is called.
+     *
+     * @param data Message to print
+     *    - Either a list of objects whose string representations get concatenated into the message string
+     *    - Or a string containing zero or more substitution strings followed by a list of objects to replace them
+     */
+    function exception(...data: any[]): void;
+
+}