diff --git a/types/mokapi/index.d.ts b/types/mokapi/index.d.ts index 6dd643bea6c88c..2d394a14b026dc 100644 --- a/types/mokapi/index.d.ts +++ b/types/mokapi/index.d.ts @@ -1,6 +1,12 @@ /** * Mokapi JavaScript API - * https://mokapi.io/docs/welcome + * + * This module exposes the core scripting API for Mokapi. + * It allows you to intercept and manipulate protocol events (HTTP, Kafka, LDAP, SMTP), + * schedule jobs, generate mock data, and share state between scripts. + * + * Documentation: + * https://mokapi.io/docs/javascript-api/overview */ import "./faker"; @@ -14,10 +20,14 @@ import "./file"; /** * Attaches an event handler for the given event. + * + * Event handlers are executed in priority order whenever the event occurs. + * Multiple handlers can be registered for the same event. + * * https://mokapi.io/docs/javascript-api/mokapi/on - * @param event Event type such as http - * @param handler An EventHandler to execute when the event is triggered - * @param args EventArgs object contains additional event arguments. + * @param event Event type such as `http`, `kafka`, `ldap`, or `smtp` + * @param handler Function executed when the event is triggered + * @param args Optional event configuration such as priority, tracking, or tags * @example * export default function() { * on('http', function(request, response) { @@ -30,7 +40,7 @@ import "./file"; * }) * } */ -export function on(event: T, handler: EventHandler[T], args?: EventArgs): void; +export function on(event: T, handler: EventHandler[T], args?: TypedEventArgs[T]): void; /** * Schedules a new periodic job with interval. @@ -110,16 +120,18 @@ export interface EventHandler { } /** - * HttpEventHandler is a function that is executed when an HTTP event is triggered. + * HttpEventHandler is invoked for every incoming HTTP request. + * + * Handlers may modify the response object to influence the outgoing response. + * The return value is ignored. + * * https://mokapi.io/docs/javascript-api/mokapi/eventhandler/httpeventhandler * @example * export default function() { * on('http', function(request, response) { * if (request.operationId === 'time') { * response.body = date() - * return true * } - * return false * }) * } */ @@ -189,19 +201,27 @@ export interface HttpResponse { data: any; /** - * Rebuilds the entire HTTP response using the OpenAPI response definition for the given status code and content type - * @example - * import { on } from 'mokapi' + * Rebuilds the entire HTTP response using the OpenAPI response definition. + * + * This resets the status code, headers, and response body/data + * based on the OpenAPI specification. + * + * - If `statusCode` is omitted, the OpenAPI `default` response is used. + * - If `contentType` is omitted, the first defined content type for the + * selected status code is used. + * + * Use this when switching to a different response (e.g. error handling) + * while keeping the response schema valid. + * + * @throws Error if the status code or content type is not defined in the OpenAPI spec * - * export default function() { - * on('http', (request, response) => { - * if (request.path.petId === 10) { - * // Switch to a different OpenAPI response. - * response.rebuild(404, 'application/json') - * response.data.message = 'Pet not found' - * } - * }) - * } + * @example + * on('http', (request, response) => { + * if (request.path.petId === 10) { + * response.rebuild(404) + * response.data.message = 'Pet not found' + * } + * }) */ rebuild: (statusCode?: number, contentType?: string) => void; } @@ -465,6 +485,55 @@ export interface EventArgs { */ tags?: { [key: string]: string }; + /** + * Defines the execution order of the event handler. + * + * Event handlers are executed in descending priority order. + * Handlers with the same priority are executed in registration order. + * + * Handlers with higher priority values run first. + * Handlers with lower priority values run later. + * + * Use negative priorities (e.g. -1) to run a handler after + * the response has been fully populated by other handlers, + * such as for logging or recording purposes. + */ + priority?: number; +} + +/** + * TypedEventArgs provides strongly typed argument objects + * for each supported event type. + * + * It is mainly used internally to map event names + * (e.g. `http`, `kafka`) to their corresponding argument types. + */ +export interface TypedEventArgs { + /** + * Arguments for HTTP event handlers. + */ + http: HttpEventArgs; + /** + * Arguments for Kafka event handlers. + */ + kafka: KafkaEventArgs; + /** + * Arguments for LDAP event handlers. + */ + ldap: LdapEventArgs; + /** + * Arguments for SMTP event handlers. + */ + smtp: SmtpEventArgs; +} + +/** + * Configuration options for HTTP event handlers. + * + * These arguments control execution behavior such as + * priority, tagging, and dashboard tracking. + */ +export interface HttpEventArgs extends EventArgs { /** * Controls whether this event handler is tracked in the dashboard. * @@ -473,19 +542,61 @@ export interface EventArgs { * - undefined: Mokapi determines tracking automatically based on * whether the response object was modified by the handler */ - track?: boolean; + track?: boolean | ((request: HttpRequest, response: HttpResponse) => boolean); +} +/** + * Configuration options for Kafka event handlers. + * + * These arguments control execution behavior such as + * priority, tagging, and dashboard tracking. + */ +export interface KafkaEventArgs extends EventArgs { /** - * Defines the execution order of the event handler. + * Controls whether this event handler is tracked in the dashboard. * - * Handlers with higher priority values run first. - * Handlers with lower priority values run later. + * - true: always track this handler + * - false: never track this handler + * - undefined: Mokapi determines tracking automatically based on + * whether the message was modified or acknowledged by the handler + */ + track?: boolean | ((message: KafkaEventMessage) => boolean); +} + +/** + * Configuration options for LDAP event handlers. + * + * These arguments control execution behavior such as + * priority, tagging, and dashboard tracking. + */ +export interface LdapEventArgs extends EventArgs { + /** + * Controls whether this event handler is tracked in the dashboard. * - * Use negative priorities (e.g. -1) to run a handler after - * the response has been fully populated by other handlers, - * such as for logging or recording purposes. + * - true: always track this handler + * - false: never track this handler + * - undefined: Mokapi determines tracking automatically based on + * whether the response object was modified by the handler */ - priority?: number; + track?: boolean | ((request: LdapSearchRequest, response: LdapSearchResponse) => boolean); +} + +/** + * Configuration options for SMTP event handlers. + * + * These arguments control execution behavior such as + * priority, tagging, and dashboard tracking. + */ +export interface SmtpEventArgs extends EventArgs { + /** + * Controls whether this event handler is tracked in the dashboard. + * + * - true: always track this handler + * - false: never track this handler + * - undefined: Mokapi determines tracking automatically based on + * whether the message was processed or modified by the handler + */ + track?: boolean | ((record: SmtpEventMessage) => boolean); } /** @@ -500,6 +611,10 @@ export interface EventArgs { */ export type ScheduledEventHandler = () => void | Promise; +/** + * Configuration options for scheduled event handlers + * created via `every` or `cron`. + */ export interface ScheduledEventArgs { /** * Adds or overrides existing tags used in dashboard @@ -663,7 +778,8 @@ export interface SharedMemory { * The `mokapi.shared` object provides a way to persist and share * data between multiple scripts running in the same Mokapi instance. * - * Values are stored in memory and shared across all scripts. + * Values are stored in memory and shared across all scripts + * within the same Mokapi process. * This allows you to coordinate state, cache data, or simulate * application-level variables without using global variables. * All values are persisted for the lifetime of the Mokapi process. diff --git a/types/mokapi/package.json b/types/mokapi/package.json index 0d9739dbd32640..c9b1e3c737e389 100644 --- a/types/mokapi/package.json +++ b/types/mokapi/package.json @@ -1,11 +1,11 @@ { "private": true, "name": "@types/mokapi", - "version": "0.34.9999", + "version": "0.35.9999", "nonNpm": true, "nonNpmDescription": "Mokapi", "projects": [ - "https://mokapi.io/docs/guides/get-started/welcome" + "https://mokapi.io/docs/welcome" ], "devDependencies": { "@types/mokapi": "workspace:." diff --git a/types/mokapi/test/mokapi-tests.ts b/types/mokapi/test/mokapi-tests.ts index fa557bd79ea5da..284cd1378a6344 100644 --- a/types/mokapi/test/mokapi-tests.ts +++ b/types/mokapi/test/mokapi-tests.ts @@ -70,6 +70,16 @@ on("http", (request, response) => { // @ts-expect-error response.rebuild(200, {}); }); +on("http", () => {}, { track: true }); +// @ts-expect-error +on("http", () => {}, { track: 123 }); +on("http", () => {}, { track: () => true }); +// @ts-expect-error +on("http", () => {}, { track: () => 123 }); +on("http", () => {}, { track: (req) => req.api === "foo" }); +on("http", () => {}, { track: (req, res) => res.body === "foo" }); +// @ts-expect-error +on("http", () => {}, { track: (req, res) => res.foo === "foo" }); // @ts-expect-error every(12, () => {}); @@ -198,6 +208,7 @@ kafka = (record: KafkaEventMessage) => { record.headers = null; record.headers = { foo: "bar" }; }; +on("kafka", () => {}, { track: (record) => record.key === "foo" }); let ldap: LdapEventHandler = () => {}; // @ts-expect-error @@ -226,6 +237,7 @@ ldap = (req: LdapSearchRequest, res: LdapSearchResponse) => { res.message = 12; res.message = ""; }; +on("ldap", () => {}, { track: (request) => request.baseDN === "foo" }); let smtp: SmtpEventHandler = () => {}; // @ts-expect-error @@ -325,6 +337,7 @@ smtp = (msg: SmtpEventMessage) => { data: new Uint8Array(2), }]; }; +on("smtp", () => {}, { track: (mail) => mail.subject === "foo" }); const i: number = patch(1, 2); patch({ x: 1 }, { y: 1 }); diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index ee1badb01edad6..fa8f8fc78baab0 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -434,50 +434,50 @@ declare namespace Office { /** * Return or set data as text (string). Data is returned or set as a one-dimensional run of characters. */ - Text, + Text = "text", /** * Return or set data as tabular data with no headers. Data is returned or set as an array of arrays containing one-dimensional runs of * characters. For example, three rows of string values in two columns would be: [["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]. * * **Note**: Only applies to data in Excel and Word. */ - Matrix, + Matrix = "matrix", /** * Return or set data as tabular data with optional headers. Data is returned or set as an array of arrays with optional headers. * * **Note**: Only applies to data in Excel and Word. */ - Table, + Table = "table", /** * Return or set data as HTML. * * **Note**: Only applies to data in add-ins for Word and Outlook add-ins for Outlook (compose mode). */ - Html, + Html = "html", /** * Return or set data as Office Open XML. * * **Note**: Only applies to data in Word. */ - Ooxml, + Ooxml = "ooxml", /** * Return a JSON object that contains an array of the IDs, titles, and indexes of the selected slides. For example, * `{"slides":[{"id":257,"title":"Slide 2","index":2},{"id":256,"title":"Slide 1","index":1}]}` for a selection of two slides. * - * **Note**: Only applies to data in PowerPoint when calling the {@link Office.Document | Document}.getSelectedData method to get the current + * **Note**: Only applies to data in PowerPoint when calling the {@link Office.Document | Document}.getSelectedDataAsync method to get the current * slide or selected range of slides. */ - SlideRange, + SlideRange = "slideRange", /** * Data is returned or set as an image stream. * **Note**: Only applies to data in Excel, Word, and PowerPoint. */ - Image, + Image = "image", /** * Data is returned or set as XML data containing an SVG image. * **Note**: Only applies to data in Excel, Word, and PowerPoint. */ - XmlSvg + XmlSvg = "xmlSvg" } /** * Specifies the type of the XML node. @@ -607,7 +607,7 @@ declare namespace Office { /** * Occurs when data within the binding is changed in Excel or Word. * - * To add an event handler for the BindingDataChanged event of a binding, use the addHandlerAsync method of the Binding object. + * To add an event handler for the `BindingDataChanged` event of a binding, use the `addHandlerAsync` method of the `Binding` object. * The event handler receives an argument of type {@link Office.BindingDataChangedEventArgs}. */ BindingDataChanged, @@ -3227,7 +3227,7 @@ declare namespace Office { * * - {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.1} * - * @returns A promise that resolves to an object of shortcuts, with keys being the IDs of the actions and values being the shortcut combinations. For example, `{"SetItalic": "Ctrl+1", "SetBold": "Ctrl+2", "SetUnderline": null}`. + * @returns A promise that resolves to an object of shortcuts, with keys being the IDs of the actions (as defined in a manifest) and values being the shortcut combinations. For example, `{"SetItalic": "Ctrl+1", "SetBold": "Ctrl+2", "SetUnderline": null}`. */ getShortcuts(): Promise<{[actionId: string]: string|null}>; /** @@ -3740,7 +3740,7 @@ declare namespace Office { forMSGraphAccess?: boolean; } /** - * Represents the user information which can be passed to msal.js. + * Represents the user information which can be passed to the Microsoft Authentication Library for JavaScript (MSAL.js). */ interface AuthContext { /** @@ -5934,7 +5934,7 @@ declare namespace Office { */ getFilePropertiesAsync(callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Text` coercion type. * * @remarks * @@ -5946,7 +5946,7 @@ declare namespace Office { * * **Supported applications**: Excel, PowerPoint, Project, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -5956,7 +5956,7 @@ declare namespace Office { * * * - * + * * * * @@ -5964,24 +5964,24 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data as a string. If the selection does not contain text, returns an empty string.Access the selected data as a string. If the selection doesn't contain text, returns an empty string.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Text`. * - * @param options Provides options for customizing what data is returned and how it is formatted. + * @param options Provides options for customizing what data is returned and how it's formatted. * - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string containing the selected text. */ getSelectedDataAsync(coercionType: Office.CoercionType.Text, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Table` coercion type. * * @remarks * @@ -5993,7 +5993,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6003,7 +6003,7 @@ declare namespace Office { * * * - * + * * * * @@ -6011,22 +6011,22 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data as a {@link Office.TableData} object. Returns null if no table is selected.Access the selected data as a {@link Office.TableData} object. Returns `null` if no table is selected.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Table`. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.TableData} object containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Table, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Matrix` coercion type. * * @remarks * @@ -6038,7 +6038,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6056,22 +6056,22 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Matrix`. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is an array of arrays containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Matrix, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `SlideRange` coercion type. * * @remarks * @@ -6079,7 +6079,7 @@ declare namespace Office { * * **Supported application**: PowerPoint * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6097,17 +6097,17 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.SlideRange`. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.SlideRange} object containing the selected slides. */ getSelectedDataAsync(coercionType: Office.CoercionType.SlideRange, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; @@ -6167,7 +6167,7 @@ declare namespace Office { * * * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6177,7 +6177,7 @@ declare namespace Office { * * * - * + * * * * @@ -6185,27 +6185,27 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data. The type depends on the coercionType parameter specified in the call.Access the selected data. The type depends on the coercionType parameter specified in the call.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* - * For other coercion types or when the coercion type is not known at compile time, use the generic version of this method + * For other coercion types or when the coercion type isn't known at compile time, use the generic version of this method * and specify the type parameter explicitly. * * @param coercionType The type of data structure to return. See the Remarks section for each application's supported coercion types. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the data in the current selection. - * This is returned in the data structure or format you specified with the coercionType parameter. + * This is returned in the data structure or format you specified with the `coercionType` parameter. * (See Remarks for more information about data coercion.) */ getSelectedDataAsync(coercionType: Office.CoercionType, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Text` coercion type. * * @remarks * @@ -6217,7 +6217,7 @@ declare namespace Office { * * **Supported applications**: Excel, PowerPoint, Project, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6235,21 +6235,21 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Text`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string containing the selected text. */ getSelectedDataAsync(coercionType: Office.CoercionType.Text, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Table` coercion type. * * @remarks * @@ -6261,7 +6261,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6271,7 +6271,7 @@ declare namespace Office { * * * - * + * * * * @@ -6279,21 +6279,21 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data as a {@link Office.TableData} object. Returns null if no table is selected.Access the selected data as a {@link Office.TableData} object. Returns `null` if no table is selected.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Table`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.TableData} object containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Table, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Matrix` coercion type. * * @remarks * @@ -6305,7 +6305,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6323,21 +6323,21 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Matrix`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is an array of arrays containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Matrix, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `SlideRange` coercion type. * * @remarks * @@ -6345,7 +6345,7 @@ declare namespace Office { * * **Supported application**: PowerPoint * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6363,16 +6363,16 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.SlideRange`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.SlideRange} object containing the selected slides. */ getSelectedDataAsync(coercionType: Office.CoercionType.SlideRange, callback?: (result: AsyncResult) => void): void; @@ -6432,7 +6432,7 @@ declare namespace Office { * * * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6442,7 +6442,7 @@ declare namespace Office { * * * - * + * * * * @@ -6450,11 +6450,11 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data. The type depends on the coercionType parameter specified in the call.Access the selected data. The type depends on the `coercionType` parameter specified in the call.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* @@ -6462,9 +6462,9 @@ declare namespace Office { * and specify the type parameter explicitly. * * @param coercionType The type of data structure to return. See the Remarks section for each application's supported coercion types. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the data in the current selection. - * This is returned in the data structure or format you specified with the coercionType parameter. + * This is returned in the data structure or format you specified with the `coercionType` parameter. * (See Remarks for more information about data coercion.) */ getSelectedDataAsync(coercionType: Office.CoercionType, callback?: (result: AsyncResult) => void): void; @@ -6590,7 +6590,7 @@ declare namespace Office { * * * - * If data is HTML, the specified HTML is inserted. (**Important**: If any of the HTML you insert is invalid, Word won't raise an error. Word will insert as much of the HTML as it can and omits any invalid data). + * If data is HTML, the specified HTML is inserted. (**Important**: If any of the HTML you insert is invalid, Word won't raise an error. Word will insert as much of the HTML as it can and omits any invalid data). * * * @@ -6773,7 +6773,7 @@ declare namespace Office { * * * Word - * If there's no selection and the insertion point is at a valid location, the specified `data` is inserted at the insertion point + * If there's no selection and the insertion point is at a valid location, the specified data is inserted at the insertion point * If data is a string, the specified text is inserted. * * @@ -6959,7 +6959,7 @@ declare namespace Office { getResourceFieldAsync(resourceId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get resource field for provided resource ID. (e.g., ResourceName) - * @param resourceId Either a string or value of the Resource ID. + * @param resourceId Either a string or value of the resource ID. * @param fieldId Resource Fields. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the GUID of the resource as a string. @@ -6990,7 +6990,7 @@ declare namespace Office { */ getSelectedTaskAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** - * Project documents only. Get the current selected Task's Id. + * Project documents only. Get the current selected Task's ID. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the GUID of the resource as a string. * @@ -7022,7 +7022,7 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result contains the following properties: * `taskName` - The name of the task. - * `wssTaskId` - The ID of the task in the synchronized SharePoint task list. If the project is not synchronized with a SharePoint task list, the value is 0. + * `wssTaskId` - The ID of the task in the synchronized SharePoint task list. If the project isn't synchronized with a SharePoint task list, the value is 0. * `resourceNames` - The comma-separated list of the names of resources that are assigned to the task. * */ @@ -7058,7 +7058,7 @@ declare namespace Office { */ getTaskFieldAsync(taskId: string, fieldId: number, callback?: (result: AsyncResult) => void): void; /** - * Project documents only. Get the WSS Url and list name for the Tasks List, the MPP is synced too. + * Project documents only. Get the WSS URL and list name for the Tasks List, the MPP is synced too. * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result contains the following properties: @@ -7182,7 +7182,7 @@ declare namespace Office { * * **Important**: This API works only in Project on Windows desktop. * - * @param resourceId Either a string or value of the Resource ID. + * @param resourceId Either a string or value of the resource ID. * @param fieldId Resource Fields. * @param fieldValue Value of the target field. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. @@ -7910,15 +7910,15 @@ declare namespace Office { * * **Applications**: Excel, PowerPoint, Word * - * The settings created by using the methods of the Settings object are saved per add-in and per document. + * The settings created by using the methods of the `Settings` object are saved per add-in and per document. * That is, they are available only to the add-in that created them, and only from the document in which they are saved. * * The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array. * - * The Settings object is automatically loaded as part of the Document object, and is available by calling the settings property of that object + * The `Settings` object is automatically loaded as part of the `Document` object, and is available by calling the settings property of that object * when the add-in is activated. * - * The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the document. + * The developer is responsible for calling the `saveAsync` method after adding or deleting settings to save the settings in the document. */ interface Settings { /** diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index c6f4e2b5f7e9e4..0fba69269f5689 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -434,50 +434,50 @@ declare namespace Office { /** * Return or set data as text (string). Data is returned or set as a one-dimensional run of characters. */ - Text, + Text = "text", /** * Return or set data as tabular data with no headers. Data is returned or set as an array of arrays containing one-dimensional runs of * characters. For example, three rows of string values in two columns would be: [["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]. * * **Note**: Only applies to data in Excel and Word. */ - Matrix, + Matrix = "matrix", /** * Return or set data as tabular data with optional headers. Data is returned or set as an array of arrays with optional headers. * * **Note**: Only applies to data in Excel and Word. */ - Table, + Table = "table", /** * Return or set data as HTML. * * **Note**: Only applies to data in add-ins for Word and Outlook add-ins for Outlook (compose mode). */ - Html, + Html = "html", /** * Return or set data as Office Open XML. * * **Note**: Only applies to data in Word. */ - Ooxml, + Ooxml = "ooxml", /** * Return a JSON object that contains an array of the IDs, titles, and indexes of the selected slides. For example, * `{"slides":[{"id":257,"title":"Slide 2","index":2},{"id":256,"title":"Slide 1","index":1}]}` for a selection of two slides. * - * **Note**: Only applies to data in PowerPoint when calling the {@link Office.Document | Document}.getSelectedData method to get the current + * **Note**: Only applies to data in PowerPoint when calling the {@link Office.Document | Document}.getSelectedDataAsync method to get the current * slide or selected range of slides. */ - SlideRange, + SlideRange = "slideRange", /** * Data is returned or set as an image stream. * **Note**: Only applies to data in Excel, Word, and PowerPoint. */ - Image, + Image = "image", /** * Data is returned or set as XML data containing an SVG image. * **Note**: Only applies to data in Excel, Word, and PowerPoint. */ - XmlSvg + XmlSvg = "xmlSvg" } /** * Specifies the type of the XML node. @@ -607,7 +607,7 @@ declare namespace Office { /** * Occurs when data within the binding is changed in Excel or Word. * - * To add an event handler for the `BindingDataChanged` event of a binding, use the `addHandlerAsync` method of the Binding object. + * To add an event handler for the `BindingDataChanged` event of a binding, use the `addHandlerAsync` method of the `Binding` object. * The event handler receives an argument of type {@link Office.BindingDataChangedEventArgs}. */ BindingDataChanged, @@ -615,7 +615,7 @@ declare namespace Office { * Occurs when the selection is changed within the binding in Excel or Word. * * To add an event handler for the `BindingSelectionChanged` event of a binding, use - * the `addHandlerAsync` method of the Binding object. The event handler receives an argument of type {@link Office.BindingSelectionChangedEventArgs}. + * the `addHandlerAsync` method of the `Binding` object. The event handler receives an argument of type {@link Office.BindingSelectionChangedEventArgs}. */ BindingSelectionChanged, /** @@ -3227,7 +3227,7 @@ declare namespace Office { * * - {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.1} * - * @returns A promise that resolves to an object of shortcuts, with keys being the IDs of the actions (as defined in an manifest) and values being the shortcut combinations. For example, `{"SetItalic": "Ctrl+1", "SetBold": "Ctrl+2", "SetUnderline": null}`. + * @returns A promise that resolves to an object of shortcuts, with keys being the IDs of the actions (as defined in a manifest) and values being the shortcut combinations. For example, `{"SetItalic": "Ctrl+1", "SetBold": "Ctrl+2", "SetUnderline": null}`. */ getShortcuts(): Promise<{[actionId: string]: string|null}>; /** @@ -3376,6 +3376,8 @@ declare namespace Office { * * [Api set: Mailbox 1.3] * + * See {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/add-in-commands-requirement-sets | Add-in commands requirement sets} for more support information. + * * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level (Outlook)}**: **restricted** * * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read @@ -3471,7 +3473,7 @@ declare namespace Office { * * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose */ - allowEvent: boolean; + allowEvent?: boolean; } /** * Encapsulates source data for add-in events. @@ -3485,6 +3487,8 @@ declare namespace Office { * * [Api set: Mailbox 1.3] * + * See {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/add-in-commands-requirement-sets | Add-in commands requirement sets} for more support information. + * * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level (Outlook)}**: **restricted** * * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read @@ -3583,7 +3587,7 @@ declare namespace Office { value: T; } /** - * The Office Auth namespace, `Office.auth`, provides a method that allows the Office client application to obtain an access token to the add-in's web application. + * The Office Auth namespace, `Office.auth`, provides methods for the Office client application to obtain access tokens to the add-in's web application. * Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time. */ interface Auth { @@ -4044,7 +4048,7 @@ declare namespace Office { * * * A string - * The specified text is inserted as the value of the first bound cell. You can also specify a valid formula to add that formula to the bound cell. For example, setting data to "=SUM(A1:A5)" will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added formula (or any pre-existing formula) from the bound cell. If you call the Binding.getDataAsync method on the bound cell to read its data, the method can return only the data displayed in the cell (the formula's result). + * The specified text is inserted as the value of the first bound cell. You can also specify a valid formula to add that formula to the bound cell. For example, setting data to "=SUM(A1:A5)" will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added formula (or any pre-existing formula) from the bound cell. If you call the Binding.getDataAsync method on the bound cell to read its data, the method can return only the data displayed in the cell (the formula's result). * * * An array of arrays ("matrix"), and the shape exactly matches the shape of the binding specified @@ -4096,7 +4100,7 @@ declare namespace Office { * * @param data The data to be set in the current selection. Possible data types by Office application: * - * string: Excel on the web and Windows, and Word on the web and on Windows only + * string: Excel on the web and on Windows, and Word on the web and on Windows only * * array of arrays: Excel and Word only * @@ -4191,7 +4195,7 @@ declare namespace Office { * * * A string - * The specified text is inserted as the value of the first bound cell. You can also specify a valid formula to add that formula to the bound cell. For example, setting data to "=SUM(A1:A5)" will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added formula (or any pre-existing formula) from the bound cell. If you call the Binding.getDataAsync method on the bound cell to read its data, the method can return only the data displayed in the cell (the formula's result). + * The specified text is inserted as the value of the first bound cell. You can also specify a valid formula to add that formula to the bound cell. For example, setting data to "=SUM(A1:A5)" will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added formula (or any pre-existing formula) from the bound cell. If you call the Binding.getDataAsync method on the bound cell to read its data, the method can return only the data displayed in the cell (the formula's result). * * * An array of arrays ("matrix"), and the shape exactly matches the shape of the binding specified @@ -4723,7 +4727,7 @@ declare namespace Office { */ license: object; /** - Provides access to the Microsoft Outlook add-in object model. + * Provides access to the Microsoft Outlook add-in object model. * * @remarks * @@ -5225,7 +5229,7 @@ declare namespace Office { getNodesAsync(xPath: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath. - / * + * * @remarks * * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/office-add-in-requirement-sets#customxmlparts | CustomXmlParts} @@ -5930,7 +5934,7 @@ declare namespace Office { */ getFilePropertiesAsync(callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Text` coercion type. * * @remarks * @@ -5942,7 +5946,7 @@ declare namespace Office { * * **Supported applications**: Excel, PowerPoint, Project, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -5952,7 +5956,7 @@ declare namespace Office { * * * - * + * * * * @@ -5960,24 +5964,24 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data as a string. If the selection does not contain text, returns an empty string.Access the selected data as a string. If the selection doesn't contain text, returns an empty string.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Text`. * - * @param options Provides options for customizing what data is returned and how it is formatted. + * @param options Provides options for customizing what data is returned and how it's formatted. * - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string containing the selected text. */ getSelectedDataAsync(coercionType: Office.CoercionType.Text, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Table` coercion type. * * @remarks * @@ -5989,7 +5993,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -5999,7 +6003,7 @@ declare namespace Office { * * * - * + * * * * @@ -6007,22 +6011,22 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data as a {@link Office.TableData} object. Returns null if no table is selected.Access the selected data as a {@link Office.TableData} object. Returns `null` if no table is selected.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Table`. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.TableData} object containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Table, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Matrix` coercion type. * * @remarks * @@ -6034,7 +6038,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6052,22 +6056,22 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Matrix`. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is an array of arrays containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Matrix, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `SlideRange` coercion type. * * @remarks * @@ -6075,7 +6079,7 @@ declare namespace Office { * * **Supported application**: PowerPoint * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6093,17 +6097,17 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.SlideRange`. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.SlideRange} object containing the selected slides. */ getSelectedDataAsync(coercionType: Office.CoercionType.SlideRange, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; @@ -6163,7 +6167,7 @@ declare namespace Office { * * * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6173,7 +6177,7 @@ declare namespace Office { * * * - * + * * * * @@ -6181,27 +6185,27 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data. The type depends on the coercionType parameter specified in the call.Access the selected data. The type depends on the coercionType parameter specified in the call.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* - * For other coercion types or when the coercion type is not known at compile time, use the generic version of this method + * For other coercion types or when the coercion type isn't known at compile time, use the generic version of this method * and specify the type parameter explicitly. * * @param coercionType The type of data structure to return. See the Remarks section for each application's supported coercion types. - * @param options Provides options for customizing what data is returned and how it is formatted. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param options Provides options for customizing what data is returned and how it's formatted. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the data in the current selection. - * This is returned in the data structure or format you specified with the coercionType parameter. + * This is returned in the data structure or format you specified with the `coercionType` parameter. * (See Remarks for more information about data coercion.) */ getSelectedDataAsync(coercionType: Office.CoercionType, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Text` coercion type. * * @remarks * @@ -6213,7 +6217,7 @@ declare namespace Office { * * **Supported applications**: Excel, PowerPoint, Project, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6231,21 +6235,21 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Text`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string containing the selected text. */ getSelectedDataAsync(coercionType: Office.CoercionType.Text, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Table` coercion type. * * @remarks * @@ -6257,7 +6261,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6267,7 +6271,7 @@ declare namespace Office { * * * - * + * * * * @@ -6275,21 +6279,21 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data as a {@link Office.TableData} object. Returns null if no table is selected.Access the selected data as a {@link Office.TableData} object. Returns `null` if no table is selected.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Table`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.TableData} object containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Table, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `Matrix` coercion type. * * @remarks * @@ -6301,7 +6305,7 @@ declare namespace Office { * * **Supported applications**: Excel, Word * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6319,21 +6323,21 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.Matrix`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is an array of arrays containing the data in the current selection. */ getSelectedDataAsync(coercionType: Office.CoercionType.Matrix, callback?: (result: AsyncResult) => void): void; /** - * Reads the data contained in the current selection in the document. + * Reads the data contained in the current selection in the document using the `SlideRange` coercion type. * * @remarks * @@ -6341,7 +6345,7 @@ declare namespace Office { * * **Supported application**: PowerPoint * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6359,16 +6363,16 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* * @param coercionType Must be `Office.CoercionType.SlideRange`. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a {@link Office.SlideRange} object containing the selected slides. */ getSelectedDataAsync(coercionType: Office.CoercionType.SlideRange, callback?: (result: AsyncResult) => void): void; @@ -6428,7 +6432,7 @@ declare namespace Office { * * * - * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * In the `callback` function that's passed to the `getSelectedDataAsync` method, you can use the properties of the `AsyncResult` object to return * the following information. * * @@ -6438,7 +6442,7 @@ declare namespace Office { * * * - * + * * * * @@ -6446,11 +6450,11 @@ declare namespace Office { * * * - * + * * * * - * + * * *
AsyncResult.valueAccess the selected data. The type depends on the coercionType parameter specified in the call.Access the selected data. The type depends on the `coercionType` parameter specified in the call.
AsyncResult.status
AsyncResult.errorAccess an Error object that provides error information if the operation failed.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextDefine an item of any type that's returned in the AsyncResult object without being altered.Define an item of any type that's returned in the AsyncResult object without being altered.
* @@ -6458,9 +6462,9 @@ declare namespace Office { * and specify the type parameter explicitly. * * @param coercionType The type of data structure to return. See the Remarks section for each application's supported coercion types. - * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * @param callback Optional. A function that's invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the data in the current selection. - * This is returned in the data structure or format you specified with the coercionType parameter. + * This is returned in the data structure or format you specified with the `coercionType` parameter. * (See Remarks for more information about data coercion.) */ getSelectedDataAsync(coercionType: Office.CoercionType, callback?: (result: AsyncResult) => void): void; @@ -7064,7 +7068,7 @@ declare namespace Office { */ getWSSUrlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; /** - * Project documents only. Get the WSS Url and list name for the Tasks List, the MPP is synced too. + * Project documents only. Get the WSS URL and list name for the Tasks List, the MPP is synced too. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result contains the following properties: * `listName` - the name of the synchronized SharePoint task list. @@ -7178,7 +7182,7 @@ declare namespace Office { * * **Important**: This API works only in Project on Windows desktop. * - * @param resourceId Either a string or value of the Resource Id. + * @param resourceId Either a string or value of the resource ID. * @param fieldId Resource Fields. * @param fieldValue Value of the target field. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. @@ -7190,7 +7194,7 @@ declare namespace Office { * * **Important**: This API works only in Project on Windows desktop. * - * @param taskId Either a string or value of the Task ID. + * @param taskId Either a string or value of the task ID. * @param fieldId Task Fields. * @param fieldValue Value of the target field. * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. @@ -7911,7 +7915,7 @@ declare namespace Office { * * The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array. * - * The Settings object is automatically loaded as part of the `Document` object, and is available by calling the settings property of that object + * The `Settings` object is automatically loaded as part of the `Document` object, and is available by calling the settings property of that object * when the add-in is activated. * * The developer is responsible for calling the `saveAsync` method after adding or deleting settings to save the settings in the document. diff --git a/types/office-runtime/index.d.ts b/types/office-runtime/index.d.ts index 776111a91ca03b..5d582329ca3296 100644 --- a/types/office-runtime/index.d.ts +++ b/types/office-runtime/index.d.ts @@ -343,6 +343,8 @@ declare namespace OfficeRuntime { * * **Applications**: Excel, Outlook, PowerPoint, Word * + * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/identity-api-requirement-sets | IdentityAPI 1.3} + * * **Important**: * * - In Outlook, this API isn't supported if you load an add-in in an Outlook.com or Gmail mailbox. diff --git a/types/supertest/index.d.ts b/types/supertest/index.d.ts index dc4991ae48ccb5..5383d2cec3a536 100644 --- a/types/supertest/index.d.ts +++ b/types/supertest/index.d.ts @@ -1,6 +1,7 @@ import superagent = require("superagent"); import stAgent = require("./lib/agent"); import STest = require("./lib/test"); +import cookies = require("./lib/cookies"); import { AgentOptions as STAgentOptions, App } from "./types"; declare const supertest: supertest.SuperTestStatic; @@ -28,10 +29,13 @@ declare namespace supertest { type SuperAgentTest = SuperTest; + type CustomAssertionCookie = cookies.CustomAssertionCookie; + interface SuperTestStatic { (app: App, options?: STAgentOptions): stAgent; Test: typeof STest; agent: typeof stAgent & ((app?: App, options?: STAgentOptions) => InstanceType); + cookies: typeof cookies; } } diff --git a/types/supertest/lib/cookies.d.ts b/types/supertest/lib/cookies.d.ts new file mode 100644 index 00000000000000..075bfae2045af9 --- /dev/null +++ b/types/supertest/lib/cookies.d.ts @@ -0,0 +1,82 @@ +declare const expectCookies: expectCookies.ExpectCookiesStatic; + +declare namespace expectCookies { + interface Assertion { + set(expects: SetMatcher | ReadonlyArray, assert?: boolean): this; + + reset(expects: ResetMatcher | ReadonlyArray, assert?: boolean): this; + + "new"(expects: ResetMatcher | ReadonlyArray, assert?: boolean): this; + + renew(expects: RenewMatcher | ReadonlyArray, assert?: boolean): this; + + contain(expects: ContainMatcher | ReadonlyArray, assert?: boolean): this; + + not>( + method: M, + expects: AssertionMatchers[M] | ReadonlyArray, + ): this; + } + + type CustomAssertion = ( + req: { cookies: CustomAssertionCookie[] }, + res: { cookies: CustomAssertionCookie[] }, + ) => boolean; + + interface CustomAssertionCookie { + name: string; + value: string; + options?: Record; + } + + interface AssertionMatchers { + readonly set: SetMatcher; + readonly reset: ResetMatcher; + readonly new: NewMatcher; + readonly renew: RenewMatcher; + readonly contain: ContainMatcher; + } + + interface SetMatcher { + readonly name: string; + readonly options?: Record; + } + + interface ResetMatcher { + readonly name: string; + } + + type NewMatcher = ResetMatcher; + + interface RenewMatcher { + readonly name: string; + + readonly options: + | { "max-age": number; expires?: never } + | { expires: Date; "max-age"?: never }; + } + + interface ContainMatcher { + readonly name: string; + + readonly value: string | boolean; + + readonly options?: { + readonly domain?: string; + readonly path?: string; + readonly expires?: string; // RFC 6265 sane-cookie-date (e.g. "Fri, 26 Sep 2025 04:26:52 GMT") + readonly secure?: boolean; + readonly httponly?: boolean; + readonly "max-age"?: string; + }; + } + + interface ExpectCookiesStatic extends Assertion { + ( + secret?: string | ReadonlyArray | null, + asserts?: CustomAssertion | ReadonlyArray, + ): Assertion; + } +} + +export = expectCookies; diff --git a/types/supertest/package.json b/types/supertest/package.json index ae48d2e40abd7e..d26b2805988c85 100644 --- a/types/supertest/package.json +++ b/types/supertest/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/supertest", - "version": "6.0.9999", + "version": "7.2.9999", "projects": [ "https://github.com/visionmedia/supertest" ], diff --git a/types/supertest/supertest-cookie-tests.ts b/types/supertest/supertest-cookie-tests.ts new file mode 100644 index 00000000000000..ab871a36657881 --- /dev/null +++ b/types/supertest/supertest-cookie-tests.ts @@ -0,0 +1,493 @@ +import request, { cookies, CustomAssertionCookie } from "supertest"; +import type { App } from "supertest/types"; + +function customAssertion( + req: { cookies: CustomAssertionCookie[] }, + res: { cookies: CustomAssertionCookie[] }, +): boolean { + throw new Error("not implemented"); +} + +// single custom assertion +async function singleCustomAssertion() { + const agent = request.agent(app); + await agent.get("/set-aoeu").expect(200); + // $ExpectType Response + await agent.get("/set-snth").expect(200).expect(cookies(null, customAssertion)); +} + +// empty custom assertions array +// $ExpectType Test +request(app()).get("/"); + +// non-empty custom assertions array +// $ExpectType Test +request(app()) + .get("/") + .expect(cookies(null, [customAssertion, customAssertion])); + +// chainable without arguments +// $ExpectType Test +request(app()) + .get("/") + .expect(cookies().set({ name: "aoeu" })); + +// chainable with secret +// $ExpectType Test +request(app()) + .get("/") + .expect(cookies("secret").set({ name: "aoeu" })); + +// chainable with custom assertion +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies(null, customAssertion) + .set({ name: "test" }), + ); + +// secret string +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies("secret", customAssertion)); + +// secret array +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies(["secret1", "secret2"], customAssertion)); + +// minimal set +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.set({ + name: "aoeu", + }), + ); + +// set does not accept a value +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.set({ + name: "aoeu", + // @ts-expect-error + value: "fqcn", + }), + ); + +// set with options +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.set({ + name: "aoeu", + options: { + secure: true, + path: "/abcd", + }, + }), + ); + +// set with empty array +// $ExpectType Test +request(app()).get("/").expect(cookies.set([])); + +// set with non-empty array +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.set([ + { + name: "aoeu", + }, + { + name: "snth", + }, + ]), + ); + +// chained set +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.set({ + name: "aoeu", + }).set({ + name: "aoeu", + }), + ); + +// set with assert=false +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.set({ + name: "aoeu", + }, false), + ); + +// reset +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.reset({ + name: "aoeu", + }), + ); + +// reset with array +// $ExpectType Test +request(app()) + .get("/") + .expect([ + cookies.reset({ + name: "aoeu", + }), + cookies.reset({ + name: "snth", + }), + ]); + +// reset with chaining +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.reset({ + name: "aoeu", + }).set({ + name: "snth", + }), + ); + +// reset with assert=false +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.reset({ + name: "aoeu", + }, false), + ); + +// reset doesn't support values +request(app()) + .get("/") + .expect( + cookies.reset({ + name: "aoeu", + // @ts-expect-error + value: "snth", + }), + ); + +// reset doesn't support options +request(app()) + .get("/") + .expect( + cookies.reset({ + name: "aoeu", + // @ts-expect-error + options: { + maxAge: 10, + }, + }), + ); + +// new +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.new({ + name: "aoeu", + }), + ); + +// new doesn't support values +request(app()) + .get("/") + .expect( + cookies.new({ + name: "aoeu", + // @ts-expect-error + value: "snth", + }), + ); + +// new with array +// $ExpectType Test +request(app()) + .get("/") + .expect([ + cookies.new({ + name: "aoeu", + }), + cookies.new({ + name: "snth", + }), + ]); + +// new with chaining +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.new({ + name: "aoeu", + }).set({ + name: "snth", + }), + ); + +// new with assert=false +// $ExpectType Test +request(app()) + .get("/") + .expect( + cookies.new({ + name: "aoeu", + }, false), + ); + +// new doesn't support options +request(app()) + .get("/") + .expect( + cookies.new({ + name: "aoeu", + // @ts-expect-error + options: { + maxAge: 10, + }, + }), + ); + +// renew, with expires +const now = new Date(); +const expiresAgent = request.agent( + app(), +); + +expiresAgent.get("/").then(() => { + // $ExpectType Test + expiresAgent.get("/").expect( + cookies.renew({ + name: "aoeu", + options: { + expires: now, + }, + }), + ); +}); + +// renew, with max-age +const ArrayAgent = request.agent( + app(), +); + +ArrayAgent.get("/").then(() => { + // $ExpectType Test + ArrayAgent.get("/").expect( + cookies.renew({ + name: "aoeu", + options: { + "max-age": 1000, + }, + }), + ); +}); + +// renew array +const arrayAgent = request.agent( + app(), +); + +ArrayAgent.get("/").then(() => { + // $ExpectType Test + ArrayAgent.get("/").expect( + cookies.renew([ + { + name: "aoeu", + options: { + "max-age": 1000, + }, + }, + { + name: "snth", + options: { + expires: now, + }, + }, + ]), + ); +}); + +// renew allows only one option +const multiAgent = request.agent( + app(), +); + +ArrayAgent.get("/").then(() => { + ArrayAgent.get("/").expect( + cookies.renew({ + name: "aoeu", + // @ts-expect-error + options: { + "max-age": 1000, + expires: now, + }, + }), + ); +}); + +const expiresStr = "Thu, 27 Mar 2025 02:01:11 GMT"; +const expectEverything = { + name: "aoeu", + value: "snth", + options: { + domain: "example.com", + path: "/hello", + expires: expiresStr, // Note the different value type + secure: true, + httponly: true, // Note the different field name + }, +}; + +// contain accepts all allowed options except 'max-age' +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies.contain(expectEverything)); + +// [FAILING] contain.value should be optional +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + // @ts-expect-error (this should be valid but expect-cookies doesn't like it) + .expect(cookies.contain({ name: "aoeu" })); + +// contain.options should be optional +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies.contain({ name: "aoeu", value: "snth" })); + +// [FAILING] contain.options.max-age should be allowed +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect( + cookies.contain({ + name: "aoeu", + value: "snth", + // @ts-expect-error (max-age is bugged and never works properly; types should be adjusted once the bug is fixed) + options: { "max-age": 100 }, + }), + ); + +// all members of contain.options should be optional +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies.contain({ + name: "aoeu", + value: "snth", + options: {}, + })); + +// contain should take expectation array +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies.contain([])); + +// contain should take asserts +// $ExpectType Test +request(app()) + .get("/") + .expect(cookies.contain(expectEverything, false)); + +// not should support set +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect( + cookies.not("set", { + name: "aoeu", + }), + ); + +// not should support reset +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect( + cookies.not("reset", { + name: "aoeu", + }), + ); + +// not should support new +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect( + cookies.not("new", { + name: "aoeu", + }), + ); + +// not should support renew +const notContainAgent = request.agent(app()); +notContainAgent.get("/").expect(200).then(() => { + // $ExpectType Test + notContainAgent.get("/").expect( + cookies.not("renew", { + name: "aoeu", + options: { + expires: new Date(now.getTime() + 2000), + }, + }), + ); +}); + +// not should support contain +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies.not("contain", expectEverything)); + +// not should accept expectation array +// $ExpectType Test +request(app()) + .get("/") + .expect(200) + .expect(cookies.not("set", [])); + +function app(): App { + throw new Error("Not implemented"); +} diff --git a/types/supertest/supertest-tests.ts b/types/supertest/supertest-tests.ts index 8923af6a5ff4c0..a1a368f8507a80 100644 --- a/types/supertest/supertest-tests.ts +++ b/types/supertest/supertest-tests.ts @@ -2,6 +2,7 @@ /* eslint @typescript-eslint/no-misused-promises: "error" */ import supertest = require("supertest"); import express = require("express"); +import "./supertest-cookie-tests"; import { Server as HttpServer } from "http"; import type { Http2SecureServer, Http2Server, Http2ServerRequest, Http2ServerResponse } from "http2";