feat(arcgis-rest-request): add serialization and deserialization for all auth managers

Author: patrickarlt

packages/arcgis-rest-request/src/ApiKeyManager.ts

@@ -33,7 +33,10 @@ export class ApiKeyManager
    */
   public readonly portal: string = "https://www.arcgis.com/sharing/rest";
 
-  private key: string;
+  /**
+   * The original API Key used to create this instance.
+   */
+  private readonly key: string;
 
   /**
    * The preferred method for creating an instance of `ApiKeyManager`.
@@ -52,11 +55,77 @@ export class ApiKeyManager
   }
 
   /**
-   * Gets a token (the API Key).
+   * Gets the current access token (the API Key).
+   */
+  get token() {
+    return this.key;
+  }
+
+  /**
+   * Gets the current access token (the API Key).
    */
   public getToken(url: string) {
     return Promise.resolve(this.key);
   }
+
+  /**
+   * Converts the `ApiKeyManager` instance to a JSON object. This is called when the instance is serialized to JSON with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+   *
+   * ```js
+   * import { ApiKeyManager } from '@esri/arcgis-rest-request';
+   *
+   * const apiKey = new ApiKeyManager.fromKey("...")
+   *
+   * const json = JSON.stringify(session);
+   * ```
+   *
+   * @returns A plain object representation of the instance.
+   */
+  toJSON() {
+    return {
+      type: "ApiKeyManager",
+      token: this.key,
+      username: this.username,
+      portal: this.portal
+    };
+  }
+
+  /**
+   * Serializes the ApiKeyManager instance to a JSON string.
+   *
+   * ```js
+   * import { ApiKeyManager } from '@esri/arcgis-rest-request';
+   *
+   * const apiKey = new ApiKeyManager.fromKey("...")
+   *
+   * localStorage.setItem("apiKey", apiKey.serialize());
+   * ```
+   * @returns {string} The serialized JSON string.
+   */
+  serialize() {
+    return JSON.stringify(this);
+  }
+
+  /**
+   * Deserializes a JSON string previously created with {@linkcode ApiKeyManager.deserialize} to an {@linkcode ApiKeyManager} instance.
+   *
+   * ```js
+   * import { ApiKeyManager } from '@esri/arcgis-rest-request';
+   *
+   * const apiKey = ApiKeyManager.deserialize(localStorage.getItem("apiKey"));
+   * ```
+   * @param {string} serialized - The serialized JSON string.
+   * @returns {ApiKeyManager} The deserialized ApiKeyManager instance.
+   */
+  static deserialize(serialized: string) {
+    const data = JSON.parse(serialized);
+
+    return new ApiKeyManager({
+      key: data.token,
+      username: data.username,
+      portal: data.portal
+    });
+  }
 }
 
 /**

packages/arcgis-rest-request/src/ApplicationCredentialsManager.ts

@@ -10,6 +10,7 @@ import {
 } from "./utils/ArcGISTokenRequestError.js";
 import { ArcGISRequestError } from "./utils/ArcGISRequestError.js";
 import { AuthenticationManagerBase } from "./AuthenticationManagerBase.js";
+import { Writable } from "./utils/writable.js";
 
 export interface IApplicationCredentialsManagerOptions {
   /**
@@ -63,12 +64,12 @@ export class ApplicationCredentialsManager
   extends AuthenticationManagerBase
   implements IAuthenticationManager
 {
-  public portal: string;
-  private clientId: string;
-  private clientSecret: string;
-  private token: string;
-  private expires: Date;
-  private duration: number;
+  public readonly portal: string;
+  public readonly token: string;
+  public readonly clientId: string;
+  public readonly clientSecret: string;
+  public readonly expires: Date;
+  public readonly duration: number;
 
   /**
    * Preferred method for creating an `ApplicationCredentialsManager`
@@ -127,8 +128,8 @@ export class ApplicationCredentialsManager
     return fetchToken(`${this.portal}/oauth2/token/`, options)
       .then((response) => {
         this._pendingTokenRequest = null;
-        this.token = response.token;
-        this.expires = response.expires;
+        this.setToken(response.token);
+        this.setExpires(response.expires);
         return response.token;
       })
       .catch((e: ArcGISRequestError) => {
@@ -146,6 +147,78 @@ export class ApplicationCredentialsManager
     this.clearCachedUserInfo();
     return this.refreshToken().then(() => this);
   }
+
+  /**
+   * Converts the `ApplicationCredentialsManager` instance to a JSON object. This is called when the instance is serialized to JSON with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+   *
+   * ```js
+   * import { ApplicationCredentialsManager } from '@esri/arcgis-rest-request';
+   *
+   * const session = ApplicationCredentialsManager.fromCredentials({
+   *   clientId: "abc123",
+   *   clientSecret: "••••••"
+   * })
+   *
+   * const json = JSON.stringify(session);
+   * ```
+   *
+   * @returns A plain object representation of the instance.
+   */
+  public toJSON() {
+    return {
+      type: "ApplicationCredentialsManager",
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      token: this.token,
+      expires: this.expires,
+      portal: this.portal,
+      duration: this.duration
+    };
+  }
+
+  /**
+   * Serializes the `ApplicationCredentialsManager` instance to a JSON string.
+   * @returns The serialized JSON string.
+   */
+  public serialize(): string {
+    return JSON.stringify(this.toJSON());
+  }
+
+  /**
+   * Deserializes a JSON string previously created with {@linkcode ApplicationCredentialsManager.serialize} to an {@linkcode ApplicationCredentialsManager} instance.
+   * @param serialized - The serialized JSON string.
+   * @returns An instance of `ApplicationCredentialsManager`.
+   */
+  public static deserialize(serialized: string): ApplicationCredentialsManager {
+    const data: IApplicationCredentialsManagerOptions = JSON.parse(serialized);
+
+    return new ApplicationCredentialsManager({
+      clientId: data.clientId,
+      clientSecret: data.clientSecret,
+      token: data.token,
+      expires: new Date(data.expires),
+      portal: data.portal,
+      duration: data.duration
+    });
+  }
+
+  /*
+   * Used to update the token when the session is refreshed.
+   * @param newToken - Sets the token for the session.
+   * @internal
+   */
+  private setToken(newToken: string) {
+    (this as Writable<ApplicationCredentialsManager>).token = newToken;
+  }
+
+  /*
+   * Used to update the expiration date when the session is refreshed.
+   * @param newExpires - Sets the expiration date for the session.
+   * @internal
+   */
+  private setExpires(newExpires: Date) {
+    (this as Writable<ApplicationCredentialsManager>).expires = newExpires;
+  }
 }
 
 /**

packages/arcgis-rest-request/src/ArcGISIdentityManager.ts

@@ -837,6 +837,21 @@ export class ArcGISIdentityManager
       });
   }
 
+  /**
+   * Deserializes a JSON string previously created with {@linkcode ArcGISIdentityManager.serialize} to an {@linkcode ArcGISIdentityManager} instance.
+   *
+   * ```js
+   * // create an ArcGISIdentityManager instance
+   * const serializedString = manager.serialize();
+   * localStorage.setItem("arcgis-identity-manager", serializedString);
+   *
+   * // later, you can retrieve the manager from localStorage
+   * const serializedString = localStorage.getItem("arcgis-identity-manager");
+   * const manager = ArcGISIdentityManager.deserialize(serializedString);
+   * ```
+   *
+   * @param str A JSON string representing an instance of `ArcGISIdentityManager`. This can be created with {@linkcode ArcGISIdentityManager.serialize}.
+   */
   public static deserialize(str: string) {
     const options = JSON.parse(str);
     return new ArcGISIdentityManager({
@@ -1188,8 +1203,25 @@ export class ArcGISIdentityManager
     });
   }
 
-  public toJSON(): IArcGISIdentityManagerOptions {
+  /**
+   * Converts the `ArcGISIdentityManager` instance to a JSON object. This is called when the instance is serialized to JSON with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+   *
+   * ```js
+   * import { ArcGISIdentityManager } from '@esri/arcgis-rest-request';
+   *
+   * const session = ArcGISIdentityManager.fromCredentials({
+   *   clientId: "abc123",
+   *   clientSecret: "••••••"
+   * })
+   *
+   * const json = JSON.stringify(session);
+   * ```
+   *
+   * @returns A plain object representation of the instance.
+   */
+  public toJSON(): IArcGISIdentityManagerOptions & { type: string } {
     return {
+      type: "ArcGISIdentityManager",
       clientId: this.clientId,
       refreshToken: this.refreshToken,
       refreshTokenExpires: this.refreshTokenExpires || undefined,
@@ -1205,9 +1237,25 @@ export class ArcGISIdentityManager
     };
   }
 
+  /**
+   * Serializes the `ArcGISIdentityManager` instance to a JSON string.
+   *
+   * ```js
+   * // create an ArcGISIdentityManager instance
+   * const serializedString = manager.serialize();
+   * localStorage.setItem("arcgis-identity-manager", serializedString);
+   *
+   * // later, you can retrieve the manager from localStorage
+   * const serializedString = localStorage.getItem("arcgis-identity-manager");
+   * const manager = ArcGISIdentityManager.deserialize(serializedString);
+   * ```
+   *
+   * @returns The serialized JSON string.
+   */
   public serialize() {
     return JSON.stringify(this);
   }
+
   /**
    * For a "Host" app that embeds other platform apps via iframes, after authenticating the user
    * and creating a ArcGISIdentityManager, the app can then enable "post message" style authentication by calling

packages/arcgis-rest-request/src/utils/writable.ts

@@ -0,0 +1,3 @@
+// Allows stripping readonly from types, making them writable.
+// From https://stackoverflow.com/questions/46634876/how-can-i-change-a-readonly-property-in-typescript#comment101446253_57485043
+export type Writable<T> = { -readonly [K in keyof T]: T[K] };

packages/arcgis-rest-request/test/ApiKey.test.ts

@@ -8,6 +8,7 @@ describe("ApiKeyManager", () => {
   afterEach(() => {
     fetchMock.restore();
   });
+
   describe(".getToken()", () => {
     it("should return the Api Key", (done) => {
       const session = new ApiKeyManager({
@@ -133,4 +134,39 @@ describe("ApiKeyManager", () => {
         });
     });
   });
+
+  describe(".serialize() and .deserialize()", () => {
+    it("should serialize to a string", () => {
+      const session = new ApiKeyManager({
+        key: "123456",
+        username: "c@sey"
+      });
+
+      const serialized = session.serialize();
+      expect(serialized).toBe(
+        JSON.stringify({
+          type: "ApiKeyManager",
+          token: "123456",
+          username: "c@sey",
+          portal: "https://www.arcgis.com/sharing/rest"
+        })
+      );
+    });
+
+    it("should deserialize to an object", () => {
+      const session = new ApiKeyManager({
+        key: "123456",
+        username: "c@sey"
+      });
+
+      const serialized = session.serialize();
+      const deserialized = ApiKeyManager.deserialize(serialized);
+      expect(deserialized.token).toEqual("123456");
+      expect(deserialized.username).toEqual("c@sey");
+      expect(deserialized.portal).toEqual(
+        "https://www.arcgis.com/sharing/rest"
+      );
+      expect(deserialized instanceof ApiKeyManager).toBeTruthy();
+    });
+  });
 });

packages/arcgis-rest-request/test/ApplicationCredentialsManager.test.ts

@@ -175,4 +175,53 @@ describe("ApplicationCredentialsManager", () => {
       );
     });
   });
+
+  describe(".serialize() and .deserialize()", () => {
+    it("should serialize to a string", () => {
+      const session = new ApplicationCredentialsManager({
+        clientId: "id",
+        clientSecret: "secret",
+        token: "token",
+        expires: YESTERDAY
+      });
+
+      const serialized = session.serialize();
+
+      expect(serialized).toBe(
+        JSON.stringify({
+          type: "ApplicationCredentialsManager",
+          clientId: "id",
+          clientSecret: "secret",
+          token: "token",
+          expires: YESTERDAY,
+          portal: "https://www.arcgis.com/sharing/rest",
+          duration: 7200
+        })
+      );
+    });
+
+    it("should deserialize to an object", () => {
+      const session = new ApplicationCredentialsManager({
+        token: "token",
+        clientId: "id",
+        clientSecret: "secret",
+        expires: YESTERDAY,
+        portal: "https://www.arcgis.com/sharing/rest"
+      });
+
+      const serialized = session.serialize();
+      const deserialized =
+        ApplicationCredentialsManager.deserialize(serialized);
+      expect(deserialized.token).toEqual("token");
+      expect(deserialized.clientId).toEqual("id");
+      expect(deserialized.clientSecret).toEqual("secret");
+      expect(deserialized.expires).toEqual(YESTERDAY);
+      expect(deserialized.portal).toEqual(
+        "https://www.arcgis.com/sharing/rest"
+      );
+      expect(
+        deserialized instanceof ApplicationCredentialsManager
+      ).toBeTruthy();
+    });
+  });
 });