Foundry/taf
1
0
Fork 0
Code Issues 5 Pull requests Releases 1 Wiki Activity Actions
Page: Query Manager
Pages
Dialog Manager Query Manager
4 Query Manager
Oliver edited this page 2026-01-11 13:25:35 -07:00
Table of Contents

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, "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, options: QueryOptions): Promise<QueryResponse|null>

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, 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.

Warning

You should safely stop execution when the returned Promise resolves to null, as that means the request was cancelled or there was one already waiting with the provided ID.

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<void>

Resends the request for the users specified. The users parameter is expected to be a non-empty list of user IDs.

This uses the cached request data associated with requestID which cannot be changed, in order to get differnet / followup information you must create a new query.

QueryManager.notify

QueryManager.notify(requestID: string, userID: string, content: string, options: NotifyOptions): Promise<void>

This is a helper function used to send a notification to a requestee when confirming that the data that they submitted went through successfully. The content parameter can be any HTML supported within chat messages.

QueryManager.finish

QueryManager.finish(requestID: string): Promise<void>

Closes a data request early, preventing any users from submitting responses. This resolves the Promise the original data request with the responses that have been submitted so far, and closing all of the in-progress forms on all connected clients.

QueryManager.cancel

QueryManager.cancel(requestID: string): Promise<void>

This method is identical to QueryManager.finish, however this resolves the Promise with null instead of the responses.

QueryManager.setApplication

QueryManager.cancel(requestID: string, app: QueryStatus): Promise<void>

This method is used in order to add a QueryStatus application to a request when it was originally created with showStatusApp=false, this will not overwrite a status application that was already assigned to the request.

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 The status of each user.
request 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 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, 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.

NotifyOptions

Property Type Description
includeRequestor boolean? Whether or not the notification should include when creating the chat message with the notification. If not specified, it is treated as false.