feat: Reactive Queries/JS

website/docs/connect-data/reference/query-settings.md

@@ -1,47 +1,222 @@
 # Query Settings
 
-This page is a reference guide that provides a description of all the settings available for configuring your queries.
+This page is a reference guide that provides a description of all the settings available for configuring your queries. You can find the following settings by clicking the **⚙️ gear icon**  in the top-right corner of the query editor for an API or database query.
+
+### Run behavior
+
+The Run behavior property determines when your query executes. 
+
+
+<img
+  src="/img/query-settings.png"
+  alt="Query Settings"
+  style={{
+    maxHeight: "600px",
+    width: "auto",
+    display: "block",
+    margin: "0 auto"
+  }}
+/>
+<p style={{ textAlign: "center", fontSize: "0.9rem", color: "#666" }}>
+  Query Settings
+</p>
+
+
+
+#### Manual
+
+<dd>
+
+Queries execute only when explicitly triggered. They do not run automatically on page load or when any variables change.
+
+You can trigger the query using:
+
+- Widget events (e.g., **onClick**, **onOptionChange**).
+- JavaScript function calls using `.run()`.
+- The **Run** button in the query editor.
+
+This mode provides full control over when and how the query is executed.
+
+*Example:* If you want to execute a query when a button is clicked:
+
+```js
+{{getUsers.run()}}
+```
+
+
+</dd>
+
+#### On page load
+
+<dd>
+
+Queries with On page load behavior execute automatically once whenever the application or page is loaded. This is useful for fetching data needed immediately when the app starts, without requiring any user interaction.
+
+The query runs each time:
+
+- The page is loaded or reloaded
+- The app is opened or refreshed
+
+You do not need to configure any widget actions or write custom JavaScript to trigger the query.
+
+
+*Example:* If you have a query that fetches user data and you want to display it whenever the app is opened, you can set the run behavior to **On page load**.
+
+</dd>
+
+
+#### Automatic
+
+<dd>
+
+Queries with Automatic behavior execute whenever a variable they depend on changes. This includes values from:
+
+- Widget properties (e.g., `{{Input1.text}}`, `{{Select1.selectedOptionValue}}`).
+- JavaScript object variables or function outputs (e.g., `{{JSObject1.value}}`, `{{JSObject1.function.data}}`).
+
+When any of these values change, the query re-executes automatically. You do not need to use event handlers like **onTextChanged** or **onOptionChanged**.
+
+This mode is useful for building dynamic, responsive apps where data needs to stay updated based on user input or state changes.
+
+*Example:* If you have a query that filters a customer list based on user input, and you want the results to update automatically as the user types, you can bind the input value directly and set the run behavior to Automatic:
+
+```js
+SELECT * FROM customers WHERE name ILIKE '%{{SearchInput.text}}%';
+```
+
+Each time the value of` SearchInput.text` changes, the query runs automatically and updates the data shown in the UI.
+
+:::note
+If a query is configured with Automatic run behavior and is also manually triggered through a widget event (such as **onTextChanged**), the query will be executed twice—once due to the reactive binding, and once from the event handler.
+To avoid unintended duplicate executions, it is recommended to use either the automatic behavior or an explicit trigger, but not both.
+:::
+
+:::info
+Changes to values in the [Appsmith global object](/write-code/reference) do not trigger automatic re-execution of queries or JavaScript actions. For example, updates to `appsmith.store` will not cause a query to re-run unless combined with a reactive property or explicitly triggered.
+:::
+
+</dd>
 
-You can find the following settings in the **Settings** tab of the query editor for an API or database query:
 
 #### Encode query params
 
-<dd>Toggles whether Appsmith converts parameters' special characters into their <a href="https://en.wikipedia.org/wiki/URL_encoding">URL-encoded</a> equivalents. It also encodes the form body when the <b>Content-Type</b> header is set to <code>FORM_URLENCODED</code>. This setting is available for API queries.</dd>
+<dd>
+
+
+When enabled, Appsmith automatically encodes special characters in query parameters to ensure they are transmitted correctly over the network.
+
+- All API query parameters are URL-encoded based on [RFC 3986](https://en.wikipedia.org/wiki/Percent-encoding).
+- If the Content-Type header is set to `application/x-www-form-urlencoded`, the request body is also encoded.
+
+This setting is useful for APIs that expect properly encoded input, especially when sending form data or special characters like spaces, ampersands, or slashes. This setting is only available for API queries.
+
+</dd>
 
 #### Use Prepared Statements
 
-<dd>Toggles whether Appsmith uses pre-compiled and parameterized SQL statements to construct and execute database queries. This method improves the security of your SQL queries. This setting is turned on by default, and available for SQL database queries. For more details, see <a href="/connect-data/concepts/how-to-use-prepared-statements">Prepared Statements</a>.</dd>
+<dd>
+
+When enabled, Appsmith constructs and executes SQL queries using pre-compiled and parameterized statements. This improves both performance and security by separating query logic from user input.
+
+- Helps protect against SQL injection attacks by preventing direct injection of unescaped input.
+- Improves query execution efficiency in certain database engines by allowing query plan reuse.
+
+This setting is enabled by default and is only available for SQL database queries. For more information, see [Prepared Statements](/connect-data/concepts/how-to-use-prepared-statements).
+
+
+
+</dd>
 
 #### Query timeout
 
 <dd>
 
-Sets the time duration in milliseconds that the Appsmith server waits for the query to finish before it closes the connection. If your query takes longer than this duration, Appsmith throws a [timeout-error](/help-and-support/troubleshooting-guide/action-errors#timeout-error). This setting defaults to 10000 ms with a maximum of 60000 ms.
 
-The Appsmith server has a default internal timeout of 60 seconds. If your queries take longer than this, you can set a value greater than 60 seconds. For self-hosted instances, you can set the `APPSMITH_SERVER_TIMEOUT` environment variable to a value greater than 60 seconds. For example, if you want a timeout of 80 seconds, use- `APPSMITH_SERVER_TIMEOUT=80`.
+Defines the maximum time (in milliseconds) that Appsmith waits for a query to complete before terminating the request.
+
+- If the query does not respond within the specified timeout, Appsmith throws a [timeout error](/help-and-support/troubleshooting-guide/action-errors#timeout-error).
+
+- The default timeout is `10000` milliseconds (10 seconds), with a maximum configurable limit of `60000` milliseconds (60 seconds).
+
+For self-hosted instances, you can increase the server-level timeout beyond `60` seconds by setting the `APPSMITH_SERVER_TIMEOUT` environment variable. For example:
+
+```js
+APPSMITH_SERVER_TIMEOUT=80
+```
+
+This setting is available for both API and database queries.
+
+
+</dd>
+
+#### Request confirmation before running query/API
+
+<dd>
+
+When enabled, Appsmith prompts the user for confirmation each time the API / query is about to run. This is useful for critical operations such as deleting records, sending emails, or triggering external workflows, where unintentional execution may have significant consequences.
+
 
 </dd>
 
-#### Request confirmation before running query
 
-<dd>When turned on, Appsmith asks the user for permission to run the query before each execution.</dd>
+#### Protocol
 
-#### Request confirmation before running API
+<dd>
+
+
+Specifies the HTTP protocol version to use when making an API request. Choosing the correct version ensures compatibility with the target server and may improve performance depending on the API's infrastructure.
+
+*Available options:*
+
+**HTTP/1.1 (Default)** The most widely supported version of HTTP.
+
+- Uses a new connection for each request-response pair.
+- Supported by nearly all web servers and APIs.
+- Ideal for general-purpose APIs with no specific protocol requirements.
 
-<dd>When turned on, Appsmith asks the user for permission to run the query before each execution.</dd>
 
-#### Run API on page load
+**HTTP/2 (h2):** A modern version of HTTP that enables multiplexing multiple requests over a single connection.
 
-<dd>When turned on, your query is executed every time the page loads or refreshes. This is automatically turned on when you bind the query's data to be displayed in a widget, though you can choose to turn it off</dd>
+- Reduces latency by allowing multiple streams on one connection.
+- Improves performance for APIs that support it.
+- Requires server support for HTTP/2 over TLS (HTTPS).
 
-#### Run query on page load
+**HTTP/2 Cleartext (h2c)**: A variant of HTTP/2 that operates over non-encrypted (HTTP) connections.
 
-<dd>When turned on, your query is executed every time the page loads or refreshes. This is automatically turned on when you bind the query's data to be displayed in a widget, though you can choose to turn it off.</dd>
+- Less common and generally used in controlled environments or internal networks.
+- Requires explicit support from the target server.
+- Not recommended for public or production APIs due to lack of encryption.
+
+This setting is only available for API queries.
+
+</dd>
 
 #### Smart JSON substitution
 
-<dd>JavaScript objects and JSON objects are formatted similarly, however they have different rules for where quotation marks are required. When this setting is turned on, Appsmith intelligently adds or removes quotation marks from your JavaScript data as necessary to correctly cast them into JSON. This setting is turned on by default, however it may need to be turned off for some tasks such as sending raw binary data to an API. This setting is available for API queries. For a video guide on using this feature, see <a href="https://www.youtube.com/watch?v=-Z3y-pdNhXc">How to Use Smart JSON Substitution</a>.</dd>
+<dd>
+
+When enabled, Appsmith intelligently formats and escapes JavaScript expressions to produce valid JSON output. This helps prevent syntax errors when passing dynamic values in API requests.
+
+- Automatically adds or removes quotation marks as needed to ensure proper JSON structure.
+- Allows you to write JavaScript directly in bindings without manually formatting the resulting JSON.
+
+This setting is enabled by default and is useful when sending structured data in API request bodies, headers, or parameters. In advanced cases—such as sending raw binary data or pre-formatted payloads—you may need to disable this setting to avoid unwanted formatting.
+
+This option is only available for API queries. For a walkthrough, see How to Use [Smart JSON Substitution](https://www.youtube.com/watch?v=-Z3y-pdNhXc).
+
+
+</dd>
 
 #### Smart BSON substitution
 
-<dd>JavaScript objects and Binary JSON (BSON) objects are formatted similarly, however they have different rules for where quotation marks are required. When turned on, the query intelligently adds or removes quotation marks from your JavaScript data as necessary to correctly cast them into BSON. This setting is turned on by default, and available for <a href="/connect-data/reference/querying-mongodb">MongoDB</a> queries.</dd>
+<dd>
+
+When enabled, Appsmith automatically formats and escapes JavaScript expressions to produce valid BSON (Binary JSON) output, which is required when interacting with MongoDB.
+
+- Dynamically adds or removes quotation marks as needed to ensure correct BSON structure.
+- Allows you to use JavaScript bindings directly in MongoDB queries and commands without manually formatting them.
+
+This setting is enabled by default and is available only for MongoDB queries. It helps avoid common syntax issues when constructing dynamic queries, filters, or update commands in MongoDB.
+
+
+</dd>

website/docs/reference/js-settings.md

@@ -0,0 +1,111 @@
+# JavaScript Settings
+This page provides information on the settings available for JS Objects and their functions in Appsmith. You can access these settings by clicking the **⚙️ gear icon** in the top-right corner of the JS Object editor and selecting a function from the dropdown list.
+
+### Choose function run behavior
+
+Each JavaScript function supports one of the following Run behavior modes:
+
+<img
+  src="/img/js-settings-mode.png"
+  alt="JavaScript Settings Mode"
+  style={{
+    maxHeight: "600px",
+    width: "auto",
+    display: "block",
+    margin: "0 auto"
+  }}
+/>
+<p style={{ textAlign: "center", fontSize: "0.9rem", color: "#666" }}>
+  JavaScript Settings
+</p>
+
+#### Manual
+
+<dd>
+
+
+The function executes only when explicitly invoked. It will not run on page load or when any variables it references change.
+
+You can trigger the function using:
+
+- Widget events (e.g., **onClick**).
+- JavaScript calls using `.run()`.
+- The **Run** button in the editor.
+
+This mode provides full control over execution timing and is best suited for user-driven actions.
+
+*Example:* If you want to execute a function only when a user clicks a button, you can set the button's **onClick** event to:
+
+```javascript
+{{CustomerActions.createCustomer()}}
+```
+
+</dd>
+
+
+
+#### On page load
+
+<dd>
+
+Functions configured with On page load run behavior execute automatically once when the page is loaded. This is useful for initializing state, setting default values, or triggering background logic without requiring user interaction.
+
+The function runs each time:
+
+- The page is loaded or reloaded
+- The app is opened or refreshed
+
+This mode is ideal for setup tasks that should occur during the initial load of the application.
+
+*Example:* If you want to initialize session data when the app loads, you can define a function like `initializeSession` and set its run behavior to On page load:
+
+```js
+initializeSession: () => {
+  storeValue("sessionStartedAt", moment().format());
+}
+```
+
+</dd>
+
+
+#### Automatic
+
+<dd>
+
+Functions configured with Automatic run behavior execute whenever a variable or input they depend on changes. Appsmith automatically tracks all references used inside the function and re-runs the function when any of those values are updated.
+
+This eliminates the need to manually bind the function to widget events such as **onTextChanged** or **onOptionChanged**.
+
+The function runs each time:
+
+- A referenced widget value changes (e.g., `{{Input1.text}}`, `{{Select1.selectedOptionValue}}`).
+- A dependent JavaScript object or function result is updated.
+- A function has a default parameter set to a reactive value (like `Input1.text`), and that value changes.
+
+This mode is ideal for reactive logic where the output should always reflect the latest application state or user input. 
+
+*Example:* If you want to filter a product list based on a search input and selected category, you can define a function like `filterProducts`:
+
+```javascript
+filterProducts: () => {
+  return ProductQuery.run({
+    search: SearchInput.text,
+    category: CategoryDropdown.selectedOptionValue
+  });
+}
+```
+
+When `SearchInput.text` or `CategoryDropdown.selectedOptionValue` changes, the `filterProducts` function will run automatically.
+
+:::note
+- If a function is set to run automatically and is also invoked manually (for example, through a widget’s event handler), it can execute twice, once due to the dependency change and once from the manual trigger. To prevent this, use either automatic behavior or manual invocation, not both.
+
+- If a JavaScript object function triggers a query, and the query’s result is bound to a widget (such as a Table), both the function and the query become reactive. Any change in their shared dependencies, such as `Input1`.text—can cause both the function and the query to execute automatically.
+:::
+
+
+:::info
+Changes to values in the Appsmith global object do not trigger automatic re-execution of queries or JavaScript actions. For example, updates to appsmith.store will not cause a function or query to re-run unless combined with a reactive property or triggered explicitly.
+:::
+
+</dd>

website/sidebars.js

@@ -621,7 +621,8 @@ const sidebars = {
           },
             'write-code/reference/Built-in-JS-Libraries',
             'write-code/reference/Fetch-API',
-            'write-code/reference/transform-data'
+            'write-code/reference/transform-data',
+            'reference/js-settings'
           ],
         }, //Reference End
         {