Merge pull request #7465 from diyaayay/typescript-declarations

Typescript declaration files script

Author: davepagurek

.gitignore

@@ -10,6 +10,7 @@ docs/reference/*
 examples/3d/
 .idea
 dist/
+*.d.ts
 p5.zip
 bower-repo/
 p5-website/

contributor_docs/contributor_guidelines.md

@@ -194,7 +194,7 @@ When opening a discussion issue, you can use the "Labels" panel on the side pane
 
 ## Prerequisites
 
-To proceed you should be minimally familiar with working with the command line, git, node.js (at least v18 and up), and have a local development environment setup.
+To proceed you should be minimally familiar with working with the command line, git, node.js (at least v20 and up), and have a local development environment setup.
 
 
 ## Introduction

docs/parameterData.json

@@ -130,7 +130,7 @@
     "paletteLerp": {
       "overloads": [
         [
-          null,
+          "[p5.Color|String|Number|Number[], Number][]",
           "Number"
         ]
       ]

package.json

@@ -10,7 +10,8 @@
     "bench:report": "vitest bench --reporter=verbose",
     "test": "vitest",
     "lint": "eslint .",
-    "lint:fix": "eslint --fix ."
+    "lint:fix": "eslint --fix .",
+    "generate-types": "npm run docs && node utils/generate-types && node utils/patch"
   },
   "lint-staged": {
     "Gruntfile.js": "eslint",
@@ -86,7 +87,8 @@
     "lib/p5.min.js",
     "lib/p5.js",
     "lib/p5.esm.js",
-    "translations/**"
+    "translations/**",
+    "types/**"
   ],
   "description": "[![npm version](https://badge.fury.io/js/p5.svg)](https://www.npmjs.com/package/p5)",
   "bugs": {
@@ -105,5 +107,6 @@
     "workerDirectory": [
       "test"
     ]
-  }
+  },
+  "types": "./types/p5.d.ts"
 }

src/color/creating_reading.js

@@ -1589,8 +1589,8 @@ function creatingReading(p5, fn){
    * <a href="/reference/p5/colorMode/">colorMode()</a>.
    *
    * @method paletteLerp
-   * @param  {[p5.Color|String|Number|Number[], Number][]} colors_stops color stops to interpolate from
-   * @param  {Number} amt number to use to interpolate relative to color stops
+   * @param {Array<[(p5.Color|String|Number|Number[]), Number]>} colors_stops color stops to interpolate from
+   * @param {Number} amt number to use to interpolate relative to color stops
    * @return {p5.Color} interpolated color.
    *
    * @example

src/core/friendly_errors/param_validator.js

@@ -105,6 +105,19 @@ function validateParams(p5, fn, lifecycles) {
     return { funcName, funcClass };
   }
 
+  function validBracketNesting(type) {
+    let level = 0;
+    for (let i = 0; i < type.length; i++) {
+      if (type[i] === '[') {
+        level++;
+      } else if (type[i] === ']') {
+        level--;
+        if (level < 0) return false;
+      }
+    }
+    return level === 0;
+  }
+
   /**
    * This is a helper function that generates Zod schemas for a function based on
    * the parameter data from `docs/parameterData.json`.
@@ -139,11 +152,8 @@ function validateParams(p5, fn, lifecycles) {
     }
 
     // Returns a schema for a single type, i.e. z.boolean() for `boolean`.
-    const generateTypeSchema = type => {
-      if (!type) return z.any();
-
-      const isArray = type.endsWith('[]');
-      const baseType = isArray ? type.slice(0, -2) : type;
+    const generateTypeSchema = baseType => {
+      if (!baseType) return z.any();
 
       let typeSchema;
 
@@ -162,7 +172,7 @@ function validateParams(p5, fn, lifecycles) {
         typeSchema = z.function();
       }
       // All p5 objects start with `p5` in the documentation, i.e. `p5.Camera`.
-      else if (baseType.startsWith('p5')) {
+      else if (/^p5\.[a-zA-Z0-9]+$/.exec(baseType) || baseType === 'p5') {
         const className = baseType.substring(baseType.indexOf('.') + 1);
         typeSchema = z.instanceof(p5Constructors[className]);
       }
@@ -171,7 +181,11 @@ function validateParams(p5, fn, lifecycles) {
         typeSchema = schemaMap[baseType];
       }
       // Tuple types
-      else if (baseType.startsWith('[') && baseType.endsWith(']')) {
+      else if (
+        baseType.startsWith('[') &&
+        baseType.endsWith(']') &&
+        validBracketNesting(baseType.slice(1, -1))
+      ) {
         typeSchema = z.tuple(
           baseType
             .slice(1, -1)
@@ -182,21 +196,7 @@ function validateParams(p5, fn, lifecycles) {
       // JavaScript classes, e.g. Request
       else if (baseType.match(/^[A-Z]/) && baseType in window) {
         typeSchema = z.instanceof(window[baseType]);
-      } else {
-        throw new Error(`Unsupported type '${type}' in parameter validation. Please report this issue.`);
       }
-
-      return isArray ? z.array(typeSchema) : typeSchema;
-    };
-
-    // Generate a schema for a single parameter. In the case where a parameter can
-    // be of multiple types, `generateTypeSchema` is called for each type.
-    const generateParamSchema = param => {
-      const isOptional = param?.endsWith('?');
-      param = param?.replace(/\?$/, '');
-
-      let schema;
-
       // Generate a schema for a single parameter that can be of multiple
       // types / constants, i.e. `String|Number|Array`.
       //
@@ -206,15 +206,28 @@ function validateParams(p5, fn, lifecycles) {
       // our constants sometimes have numeric or non-primitive values.
       // 2) In some cases, the type can be constants or strings, making z.enum()
       // insufficient for the use case.
-      if (param?.includes('|')) {
-        const types = param.split('|');
-        schema = z.union(types
+      else if (baseType.includes('|') && baseType.split('|').every(t => validBracketNesting(t))) {
+        const types = baseType.split('|');
+        typeSchema = z.union(types
           .map(t => generateTypeSchema(t))
           .filter(s => s !== undefined));
+      } else if (baseType.endsWith('[]')) {
+        typeSchema = z.array(generateTypeSchema(baseType.slice(0, -2)));
       } else {
-        schema = generateTypeSchema(param);
+        throw new Error(`Unsupported type '${baseType}' in parameter validation. Please report this issue.`);
       }
 
+      return typeSchema;
+    };
+
+    // Generate a schema for a single parameter. In the case where a parameter can
+    // be of multiple types, `generateTypeSchema` is called for each type.
+    const generateParamSchema = param => {
+      const isOptional = param?.endsWith('?');
+      param = param?.replace(/\?$/, '');
+
+      let schema = generateTypeSchema(param);
+
       return isOptional ? schema.optional() : schema;
     };