Foundry/taf
1
0
Fork 0
Code Issues 5 Pull requests Releases 1 Wiki Activity Actions

Begin working on the Query Manager documentation

Oliver 2025-11-28 22:45:54 -07:00
parent 17baa476e3
commit 02c9c501f6
1 changed files with 86 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

86
Query-Manager.md Normal file

@ -0,0 +1,86 @@
The Query Manager is an API exposed by the module to help make
retrieving rolls from players easier through the use of a common API and
allowing per-player tracking and data submission. This API is available
globally by accessing `taf.QueryManager`.
## Interface
### `QueryManager.has`
> QueryManager.has(queryID: string): boolean
Indicates whether this client was the originating client for the query
with the provided ID.
### `QueryManager.get`
> QueryManager.get(queryID: string): Omit<[QueryData](#querydata), "resolve"|"onSubmit"|"app">
This is used to retrieve most of the query data in a read-only state.
The `resolve`, `onSubmit`, and `app` properties are removed from the
query data prior to being returned.
### `QueryManager.query`
> QueryManager.query(request: [AskConfig](/Dialog-Manager.md#askconfig), options: [QueryOptions](#queryoptions)): Promise<[QueryResponse](#queryresponse)>
This is the powerhouse of the Query Manager API, this is how you actually
prompt other users for information and do stuff with that information.
The `request` parameter utilizes the same type as the [Dialog Manager's AskConfig](/Dialog-Manager.md#askconfig), please consult that documentation for further information.
If you want to perform some operation on the data returned on a per-user basis as it arrives, you should provide the `options` an `onSubmit` event listener which will be called with each user's submitted data.
> [!NOTE]
> You can disable the status application by providing `showStatusApp: false` as an option. However, by doing so, will change when the Promise returned from this method is resolved.
### `QueryManager.requery`
> QueryManager.requery(requestID: string, users: string[]): Promise&lt;void&gt;
### `QueryManager.notify`
> QueryManager.notify(requestID: string, userID: string, content: string, options: [NotifyOptions](#notifyoptions)): Promise&lt;void&gt;
### `QueryManager.finish`
> QueryManager.finish(requestID: string): Promise&lt;void&gt;
### `QueryManager.cancel`
> QueryManager.cancel(requestID: string): Promise&lt;void&gt;
### `QueryManager.setApplication`
> QueryManager.cancel(requestID: string, app: QueryStatus): Promise&lt;void&gt;
## Types
### QueryData
| Property | Type | Description
| -------- | ---- | -----------
| `users` | `string[]` | The list of user IDs that this request is for.
| `resolve` | `Function` | The function to resolve the original method call's promise.
| `responses` | `Record<string, object>` | Each user's individual responses as returned from the DialogManager.ask function.
| `onSubmit` | `((requestID: string, userID: string, answers: object) => Promise<void>)?` | An event listener that processes each user's answers as they come in, this should send the user a notification with the confirmed result of the submission.
| `app` | `QueryStatus?` | The application that is presenting the current status of each requestee, and allowing the requestor to rerequest the data if the user disconnected or closed the dialog without submitting data.
| `status` | [UserStatus](#userstatus) | The status of each user.
| `request` | [AskConfig](/Dialog-Manager.md#askconfig) | The initial request data used to create the query. This is stored in order to be able to requery users when required.
| `config` | [AskOptions](/Dialog-Manager.md#askoptions) | The initial config used to create the query. This is stored in order to be able to requery users when required.
### UserStatus
This is an object typing where the keys are user IDs and the values are one of the following values:
| Value | Description
| ----- | -----------
| `finished` | The user has submitted data.
| `waiting` | The dialog has been displayed to the user and they have it open.
| `disconnected` | The user is currently not connected to the game and cannot receive any queries.
| `unprompted` | The user is connected to the game and is available to receive queries, however they may not have the dialog visible on the screen due reconnecting after a disconnect or for some other reason.
### QueryOptions
This type extends [AskOptions](/Dialog-Manager.md#askoptions), consult that documentation for more properties that can be used here.
| Property | Type | Description
| -------- | ---- | -----------
| `onSubmit` | `((requestID: string, userID: string, answers: object) => Promise<void>)?` | The callback handler that handles each user's individual form submission, this option defaults to a function that will send a chat notification just to the user to indicate that their data submission was successful.
| `users` | `string[]?` | A list of user IDs to send the request to. If not provided this defaults to all currently-online users.
| `showStatusApp` | `boolean?` | Whether or not to show the query status in a popup window for the requestor. If not provided, this defaults to true.
### QueryResponse
This is an object representing every user's queried data, this may or may not have all of the requested users within it, and should be treated as such. For the users that it does have data from, the value will be an object containing the same key-value pairs if you had provided the query to [`DialogManager.ask`](/Dialog-Manager.md#dialogmanagerask).
### NotifyOptions