[docs] [cli] Add createFunction deprecation notices (#2334)

docs/data/toolpad/concepts/connecting-to-data.md

@@ -123,7 +123,7 @@ To be really useful, you need to connect these queries with data present on your
 
 - ### Custom Functions
 
-  All function arguments will be available in the query editor to bind state to. Make sure to annotate them correctly with their typescript types. Toolpad uses this information to present you with correctly type databinding controls. For example:
+  All function arguments will be available in the query editor to bind state to. Make sure to annotate them correctly with their typescript types. Toolpad uses this information to present you with correctly typed databinding controls. For example:
 
   ```jsx
   export async function getAnimals(
@@ -142,7 +142,7 @@ To be really useful, you need to connect these queries with data present on your
 {{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/concepts/connecting-to-data/custom-function-params.png", "alt": "Controls for custom function parameters", "caption": "Controls for custom function parameters", "indent": 1, "zoom": false, "width": 639}}
 
 :::info
-Toolpad also provides a `createFunction` API to be able to define your parameters when creating custom functions. This API is now deprecated:
+Toolpad also provides a `createFunction` API to be able to define your parameters when creating custom functions:
 
 ```jsx
 import { createFunction } from '@mui/toolpad/server';
@@ -165,7 +165,7 @@ export const example = createFunction(
 
 This will make the `value` property available in the query editor. You can pass a value, or bind this to the page state:
 
-See the `createFunction` [reference](/toolpad/reference/api/create-function/) section for complete details on this API
+This API is now deprecated, and will be removed from a future version of Toolpad. Find more details in the `createFunction` [reference](/toolpad/reference/api/create-function/) section.
 :::
 
 ## Mode
@@ -232,33 +232,24 @@ Toolpad has access to the environment variables defined in the `.env` file at th
   ```ts
   import { Configuration, OpenAIApi } from 'openai';
 
-  export const askGPT = createFunction(
-    async function open4({ parameters }) {
-      const configuration = new Configuration({
-        apiKey: process.env.OPENAI_API_KEY,
-      });
+  export async function askGPT(messages: string[]) {
+    const configuration = new Configuration({
+      apiKey: process.env.OPENAI_API_KEY,
+    });
 
-      const openai = new OpenAIApi(configuration);
-      const completion = await openai.createChatCompletion({
-        model: 'gpt-3.5-turbo',
-        messages: parameters.messages,
-      });
+    const openai = new OpenAIApi(configuration);
+    const completion = await openai.createChatCompletion({
+      model: 'gpt-3.5-turbo',
+      messages: messages,
+    });
 
-      const response = completion.data?.choices[0].message ?? {
-        role: 'assistant',
-        content: 'No response',
-      };
+    const response = completion.data?.choices[0].message ?? {
+      role: 'assistant',
+      content: 'No response',
+    };
 
-      return response;
-    },
-    {
-      parameters: {
-        messages: {
-          type: 'array',
-        },
-      },
-    },
-  );
+    return response;
+  }
   ```
 
   You can then use this function on your page:

docs/data/toolpad/how-to-guides/connect-to-databases.md

@@ -8,10 +8,9 @@ We can write a custom function to connect to any database that we need to. We ca
 
 ### Custom function
 
-Inside `/resources/functions.ts`, we can create a custom function using Toolpad's `createFunction` API:
+Inside `/resources/functions.ts`, we can create a custom function:
 
 ```ts
-import { createFunction } from '@mui/toolpad/server';
 import mysql from 'mysql2/promise';
 import fs from 'fs';
 
@@ -26,32 +25,26 @@ async connectionFn () {
    return connection;
 }
 
-export const getData = createFunction(async function getData() {
-   const query = `SELECT * FROM table WHERE order_id=${parameters.order_id}`;
+export async function getData(order_id: number) {
+   const query = `SELECT * FROM table WHERE order_id=${order_id}`;
    const connection = await connectionFn();
    const [rows] = await connection.execute(sql);
    connection.end();
    return rows;
-}, {
-   parameters: {
-      order_id: {
-         type: 'number'
-      }
-   }
-});
+};
 
 ```
 
 If our queries don't rely on parameters, we may even use a `.sql` file stored in the file system so that we can keep them organised:
 
 ```ts
-export const getData = createFunction(async function getData() {
+export async function getData() {
   const query = fs.readFileSync('./toolpad/resources/getData.sql');
   const connection = await connectionFn();
   const [rows] = await connection.execute(sql);
   connection.end();
   return rows;
-});
+}
 ```
 
 Keep in mind that we can run any SQL query on our database through these custom functions.
@@ -61,7 +54,6 @@ Keep in mind that we can run any SQL query on our database through these custom
 Instead of connecting directly, we may want to create an SSH tunnel to connect to our database. We can modify our function a bit to make this happen:
 
 ```ts
-import { createFunction } from '@mui/toolpad/server';
 import mysql from 'mysql2/promise';
 import SSH2Promise from 'ssh2-promise';
 import fs from 'fs';

docs/data/toolpad/reference/api/create-function.md

@@ -2,6 +2,10 @@
 
 <p class="description">Provide backend function that loads data on the page.</p>
 
+:::warning
+The `createFunction` API is deprecated and will be removed from Toolpad `v0.1.23` onwards. You can now use functions directly without needing to wrap them inside `createFunction` - See [custom functions](/toolpad/concepts/connecting-to-data/#custom-functions) for examples.
+:::
+
 ## Import
 
 ```jsx

packages/toolpad-app/src/server/functionsTypesWorker.ts

@@ -401,6 +401,8 @@ export interface ExtractTypesParams {
   resourcesFolder: string;
 }
 
+let createFunctionWarningShown = false;
+
 export default async function extractTypes({
   resourcesFolder,
 }: ExtractTypesParams): Promise<IntrospectionResult> {
@@ -412,6 +414,8 @@ export default async function extractTypes({
 
   const checker = program.getTypeChecker();
 
+  const usingCreateFunction = [];
+
   const files: FileIntrospectionResult[] = entryPoints
     .map((entrypoint) => {
       const sourceFile = program.getSourceFile(entrypoint);
@@ -445,6 +449,9 @@ export default async function extractTypes({
           }
 
           const isCreateFunction = isToolpadCreateFunction(exportType);
+          if (isCreateFunction) {
+            usingCreateFunction.push(symbol.name);
+          }
           return {
             name: symbol.name,
             isCreateFunction,
@@ -470,5 +477,18 @@ export default async function extractTypes({
     .filter(Boolean)
     .sort((a, b) => a.name.localeCompare(b.name));
 
+  if (usingCreateFunction.length > 0 && !createFunctionWarningShown) {
+    console.warn(
+      `${chalk.yellow('warn')} - ${chalk.bold(usingCreateFunction.length)} function${
+        usingCreateFunction.length === 1 ? ' is' : 's are'
+      } using the deprecated ${chalk.red(
+        'createFunction',
+      )} API. This will be removed from Toolpad in a future release. Please see ${chalk.underline(
+        chalk.blue('https://mui.com/toolpad/reference/api/create-function/'),
+      )} for migration information and updates.`,
+    );
+    createFunctionWarningShown = true;
+  }
+
   return { files };
 }

packages/toolpad-core/src/server.ts

@@ -45,6 +45,8 @@ type MaybeLegacyParametersDefinition = PropValueType & {
 };
 
 /**
+ * @deprecated Directly export a function instead. This will be removed in a future release.
+ * See: https://mui.com/toolpad/reference/api/create-function/
  * Use this to define a function that will load the data for a Toolpad query.
  * You can define parameters for the function in the configuration object.
  * These parameters will be available in the Toolpad editor when creating a query and can be bound to page state.