🤖 Merge PR DefinitelyTyped#73784 [chrome] update sessions namespace by @erwanjugand

Author: erwanjugand

types/chrome/index.d.ts

@@ -9729,25 +9729,16 @@ declare namespace chrome {
      */
     export namespace sessions {
         export interface Filter {
-            /**
-             * Optional.
-             * The maximum number of entries to be fetched in the requested list. Omit this parameter to fetch the maximum number of entries (sessions.MAX_SESSION_RESULTS).
-             */
+            /** The maximum number of entries to be fetched in the requested list. Omit this parameter to fetch the maximum number of entries ({@link sessions.MAX_SESSION_RESULTS}). */
             maxResults?: number | undefined;
         }
 
         export interface Session {
             /** The time when the window or tab was closed or modified, represented in seconds since the epoch. */
             lastModified: number;
-            /**
-             * Optional.
-             * The tabs.Tab, if this entry describes a tab. Either this or sessions.Session.window will be set.
-             */
+            /** The {@link tabs.Tab}, if this entry describes a tab. Either this or {@link sessions.Session.window} will be set. */
             tab?: tabs.Tab | undefined;
-            /**
-             * Optional.
-             * The windows.Window, if this entry describes a window. Either this or sessions.Session.tab will be set.
-             */
+            /** The {@link windows.Window}, if this entry describes a window. Either this or {@link sessions.Session.tab} will be set. */
             window?: windows.Window | undefined;
         }
 
@@ -9758,69 +9749,39 @@ declare namespace chrome {
             sessions: Session[];
         }
 
-        export interface SessionChangedEvent extends chrome.events.Event<() => void> {}
-
-        /** The maximum number of sessions.Session that will be included in a requested list. */
-        export var MAX_SESSION_RESULTS: number;
+        /** The maximum number of {@link sessions.Session} that will be included in a requested list. */
+        export const MAX_SESSION_RESULTS: 25;
 
         /**
          * Gets the list of recently closed tabs and/or windows.
-         * @return The `getRecentlyClosed` method provides its result via callback or returned as a `Promise` (MV3 only).
+         *
+         * Can return its result via Promise in Manifest V3 or later since Chrome 96.
          */
         export function getRecentlyClosed(filter?: Filter): Promise<Session[]>;
-        /**
-         * Gets the list of recently closed tabs and/or windows.
-         * @param callback
-         * Parameter sessions: The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index 0). The entries may contain either tabs or windows.
-         */
-        export function getRecentlyClosed(filter: Filter, callback: (sessions: Session[]) => void): void;
-        /**
-         * Gets the list of recently closed tabs and/or windows.
-         * @param callback
-         * Parameter sessions: The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index 0). The entries may contain either tabs or windows.
-         */
         export function getRecentlyClosed(callback: (sessions: Session[]) => void): void;
+        export function getRecentlyClosed(filter: Filter | undefined, callback: (sessions: Session[]) => void): void;
+
         /**
          * Retrieves all devices with synced sessions.
-         * @return The `getDevices` method provides its result via callback or returned as a `Promise` (MV3 only).
+         *
+         * Can return its result via Promise in Manifest V3 or later since Chrome 96.
          */
         export function getDevices(filter?: Filter): Promise<Device[]>;
-        /**
-         * Retrieves all devices with synced sessions.
-         * @param callback
-         * Parameter devices: The list of sessions.Device objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session. tabs.Tab objects are sorted by recency in the windows.Window of the sessions.Session objects.
-         */
-        export function getDevices(filter: Filter, callback: (devices: Device[]) => void): void;
-        /**
-         * Retrieves all devices with synced sessions.
-         * @param callback
-         * Parameter devices: The list of sessions.Device objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session. tabs.Tab objects are sorted by recency in the windows.Window of the sessions.Session objects.
-         */
         export function getDevices(callback: (devices: Device[]) => void): void;
+        export function getDevices(filter: Filter | undefined, callback: (devices: Device[]) => void): void;
+
         /**
-         * Reopens a windows.Window or tabs.Tab.
-         * @param sessionId Optional.
-         * The windows.Window.sessionId, or tabs.Tab.sessionId to restore. If this parameter is not specified, the most recently closed session is restored.
-         * @return The `restore` method provides its result via callback or returned as a `Promise` (MV3 only).
+         * Reopens a {@link windows.Window} or {@link tabs.Tab}, with an optional callback to run when the entry has been restored.
+         *
+         * Can return its result via Promise in Manifest V3 or later since Chrome 96.
+         * @param sessionId The {@link windows.Window.sessionId}, or {@link tabs.Tab.sessionId} to restore. If this parameter is not specified, the most recently closed session is restored.
          */
         export function restore(sessionId?: string): Promise<Session>;
-        /**
-         * Reopens a windows.Window or tabs.Tab, with an optional callback to run when the entry has been restored.
-         * @param sessionId Optional.
-         * The windows.Window.sessionId, or tabs.Tab.sessionId to restore. If this parameter is not specified, the most recently closed session is restored.
-         * @param callback Optional.
-         * Parameter restoredSession: A sessions.Session containing the restored windows.Window or tabs.Tab object.
-         */
-        export function restore(sessionId: string, callback: (restoredSession: Session) => void): void;
-        /**
-         * Reopens a windows.Window or tabs.Tab, with an optional callback to run when the entry has been restored.
-         * @param callback Optional.
-         * Parameter restoredSession: A sessions.Session containing the restored windows.Window or tabs.Tab object.
-         */
         export function restore(callback: (restoredSession: Session) => void): void;
+        export function restore(sessionId: string | undefined, callback: (restoredSession: Session) => void): void;
 
         /** Fired when recently closed tabs and/or windows are changed. This event does not monitor synced sessions changes. */
-        export var onChanged: SessionChangedEvent;
+        export const onChanged: events.Event<() => void>;
     }
 
     ////////////////////

types/chrome/test/index.ts

@@ -5547,31 +5547,48 @@ function testFileSystemProvider() {
     });
 }
 
-// https://developer.chrome.com/docs/extensions/reference/sessions/
+// https://developer.chrome.com/docs/extensions/reference/api/sessions
 function testSessions() {
-    const myMax = { maxResults: 1 };
-    chrome.sessions.getDevices(devices => {});
-    chrome.sessions.getDevices({}, devices => {});
-    chrome.sessions.getDevices(myMax, devices => {});
-    chrome.sessions.getRecentlyClosed(sessions => {});
-    chrome.sessions.getRecentlyClosed({}, sessions => {});
-    chrome.sessions.getRecentlyClosed(myMax, sessions => {});
-    chrome.sessions.restore(restoredSession => {});
-    chrome.sessions.restore("myString", restoredSession => {});
-    chrome.sessions.onChanged.addListener(() => {});
-}
+    chrome.sessions.MAX_SESSION_RESULTS === 25;
+
+    const filter: chrome.sessions.Filter = { maxResults: 1 };
+
+    chrome.sessions.getDevices(); // $ExpectType Promise<Device[]>
+    chrome.sessions.getDevices(filter); // $ExpectType Promise<Device[]>
+    chrome.sessions.getDevices(([device]) => { // $ExpectType void
+        device.deviceName; // $ExpectType string
+        device.sessions; // $ExpectType Session[]
+    });
+    chrome.sessions.getDevices(filter, devices => { // $ExpectType void
+        devices; // $ExpectType Device[]
+    });
+    // @ts-expect-error
+    chrome.sessions.getDevices(() => {}).then(() => {});
+
+    chrome.sessions.getRecentlyClosed(); // $ExpectType Promise<Session[]>
+    chrome.sessions.getRecentlyClosed(filter); // $ExpectType Promise<Session[]>
+    chrome.sessions.getRecentlyClosed((sessions) => { // $ExpectType void
+        sessions; // $ExpectType Session[]
+    });
+    chrome.sessions.getRecentlyClosed(filter, sessions => { // $ExpectType void
+        sessions; // $ExpectType Session[]
+    });
+    // @ts-expect-error
+    chrome.sessions.getRecentlyClosed(() => {}).then(() => {});
+
+    const sessionId = "id";
+    chrome.sessions.restore(); // $ExpectType Promise<Session>
+    chrome.sessions.restore(sessionId); // $ExpectType Promise<Session>
+    chrome.sessions.restore((restoredSession) => { // $ExpectType void
+        restoredSession.lastModified; // $ExpectType number
+        restoredSession.tab; // $ExpectType Tab | undefined
+        restoredSession.window; // $ExpectType Window | undefined
+    });
+    chrome.sessions.restore(sessionId, (restoredSession) => { // $ExpectType void
+        restoredSession; // $ExpectType Session
+    });
 
-// https://developer.chrome.com/docs/extensions/reference/sessions/
-async function testSessionsForPromise() {
-    const myMax = { maxResults: 1 };
-    await chrome.sessions.getDevices();
-    await chrome.sessions.getDevices({});
-    await chrome.sessions.getDevices(myMax);
-    await chrome.sessions.getRecentlyClosed();
-    await chrome.sessions.getRecentlyClosed({});
-    await chrome.sessions.getRecentlyClosed(myMax);
-    await chrome.sessions.restore();
-    await chrome.sessions.restore("myString");
+    checkChromeEvent(chrome.sessions.onChanged, () => void 0);
 }
 
 // https://developer.chrome.com/docs/extensions/reference/api/sidePanel