@wallet-standard/app - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

lib/cjs/wallets.js

@@ -20,3 +20,19 @@ "use strict";
 /**
- * TODO: docs
+ * Get an API for {@link Wallets.get | getting}, {@link Wallets.on | listening for}, and
+ * {@link Wallets.register | registering} {@link "@wallet-standard/base".Wallet | Wallets}.
+ *
+ * When called for the first time --
+ *
+ * This dispatches a {@link "@wallet-standard/base".WindowAppReadyEvent} to notify each Wallet that the app is ready
+ * to register it.
+ *
+ * This also adds a listener for {@link "@wallet-standard/base".WindowRegisterWalletEvent} to listen for a notification
+ * from each Wallet that the Wallet is ready to be registered by the app.
+ *
+ * This combination of event dispatch and listener guarantees that each Wallet will be registered synchronously as soon
+ * as the app is ready whether the app loads before or after each Wallet.
+ *
+ * @return API for getting, listening for, and registering Wallets.
+ *
+ * @group App
  */
@@ -114,3 +130,7 @@ function getWallets() {
 _AppReadyEvent_detail = new WeakMap();
-/** @deprecated */
+/**
+ * @deprecated Use {@link getWallets} instead.
+ *
+ * @group Deprecated
+ */
 function DEPRECATED_getWallets() {
@@ -117,0 +137,0 @@ if (wallets)

lib/esm/wallets.js

@@ -17,3 +17,19 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
 /**
- * TODO: docs
+ * Get an API for {@link Wallets.get | getting}, {@link Wallets.on | listening for}, and
+ * {@link Wallets.register | registering} {@link "@wallet-standard/base".Wallet | Wallets}.
+ *
+ * When called for the first time --
+ *
+ * This dispatches a {@link "@wallet-standard/base".WindowAppReadyEvent} to notify each Wallet that the app is ready
+ * to register it.
+ *
+ * This also adds a listener for {@link "@wallet-standard/base".WindowRegisterWalletEvent} to listen for a notification
+ * from each Wallet that the Wallet is ready to be registered by the app.
+ *
+ * This combination of event dispatch and listener guarantees that each Wallet will be registered synchronously as soon
+ * as the app is ready whether the app loads before or after each Wallet.
+ *
+ * @return API for getting, listening for, and registering Wallets.
+ *
+ * @group App
  */
@@ -106,3 +122,7 @@ export function getWallets() {
 _AppReadyEvent_detail = new WeakMap();
-/** @deprecated */
+/**
+ * @deprecated Use {@link getWallets} instead.
+ *
+ * @group Deprecated
+ */
 export function DEPRECATED_getWallets() {
@@ -109,0 +129,0 @@ if (wallets)

lib/types/wallets.d.ts

 import type { Wallet } from '@wallet-standard/base';
-/** TODO: docs */
+/**
+ * Get an API for {@link Wallets.get | getting}, {@link Wallets.on | listening for}, and
+ * {@link Wallets.register | registering} {@link "@wallet-standard/base".Wallet | Wallets}.
+ *
+ * When called for the first time --
+ *
+ * This dispatches a {@link "@wallet-standard/base".WindowAppReadyEvent} to notify each Wallet that the app is ready
+ * to register it.
+ *
+ * This also adds a listener for {@link "@wallet-standard/base".WindowRegisterWalletEvent} to listen for a notification
+ * from each Wallet that the Wallet is ready to be registered by the app.
+ *
+ * This combination of event dispatch and listener guarantees that each Wallet will be registered synchronously as soon
+ * as the app is ready whether the app loads before or after each Wallet.
+ *
+ * @return API for getting, listening for, and registering Wallets.
+ *
+ * @group App
+ */
+export declare function getWallets(): Wallets;
+/**
+ * API for {@link Wallets.get | getting}, {@link Wallets.on | listening for}, and
+ * {@link Wallets.register | registering} {@link "@wallet-standard/base".Wallet | Wallets}.
+ *
+ * @group App
+ */
 export interface Wallets {
     /**
-     * TODO: docs
+     * Get all Wallets that have been registered.
+     *
+     * @return Registered Wallets.
      */
-    register(...wallets: Wallet[]): () => void;
+    get(): readonly Wallet[];
     /**
-     * TODO: docs
+     * Add an event listener and subscribe to events for Wallets that are
+     * {@link WalletsEventsListeners.register | registered} and
+     * {@link WalletsEventsListeners.unregister | unregistered}.
+     *
+     * @param event    Event type to listen for. {@link WalletsEventsListeners.register | `register`} and
+     * {@link WalletsEventsListeners.unregister | `unregister`} are the only event types.
+     * @param listener Function that will be called when an event of the type is emitted.
+     *
+     * @return
+     * `off` function which may be called to remove the event listener and unsubscribe from events.
+     *
+     * As with all event listeners, be careful to avoid memory leaks.
      */
-    get(): ReadonlyArray<Wallet>;
+    on<E extends WalletsEventNames>(event: E, listener: WalletsEventsListeners[E]): () => void;
     /**
-     * TODO: docs
+     * Register Wallets. This can be used to programmatically wrap non-standard wallets as Standard Wallets.
+     *
+     * Apps generally do not need to, and should not, call this.
+     *
+     * @param wallets Wallets to register.
+     *
+     * @return
+     * `unregister` function which may be called to programmatically unregister the registered Wallets.
+     *
+     * Apps generally do not need to, and should not, call this.
      */
-    on<E extends WalletsEventNames = WalletsEventNames>(event: E, listener: WalletsEvents[E]): () => void;
+    register(...wallets: Wallet[]): () => void;
 }
-/** TODO: docs */
-export interface WalletsEvents {
+/**
+ * Types of event listeners of the {@link Wallets} API.
+ *
+ * @group App
+ */
+export interface WalletsEventsListeners {
     /**
-     * Emitted when wallets are registered.
+     * Emitted when Wallets are registered.
      *
@@ -26,3 +77,3 @@ * @param wallets Wallets that were registered.
     /**
-     * Emitted when wallets are unregistered.
+     * Emitted when Wallets are unregistered.
      *
@@ -33,10 +84,20 @@ * @param wallets Wallets that were unregistered.
 }
-/** TODO: docs */
-export declare type WalletsEventNames = keyof WalletsEvents;
 /**
- * TODO: docs
+ * Names of {@link WalletsEventsListeners} that can be listened for.
+ *
+ * @group App
  */
-export declare function getWallets(): Wallets;
-/** @deprecated */
+export declare type WalletsEventNames = keyof WalletsEventsListeners;
+/**
+ * @deprecated Use {@link WalletsEventsListeners} instead.
+ *
+ * @group Deprecated
+ */
+export declare type WalletsEvents = WalletsEventsListeners;
+/**
+ * @deprecated Use {@link getWallets} instead.
+ *
+ * @group Deprecated
+ */
 export declare function DEPRECATED_getWallets(): Wallets;
 //# sourceMappingURL=wallets.d.ts.map

package.json

 {
   "name": "@wallet-standard/app",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "author": "Solana Maintainers <[e-mail]>",
@@ -29,3 +29,3 @@ "repository": "https://github.com/wallet-standard/wallet-standard",
   "dependencies": {
-    "@wallet-standard/base": "^1.0.0"
+    "@wallet-standard/base": "^1.0.1"
   },
@@ -32,0 +32,0 @@ "devDependencies": {

src/wallets.ts

@@ -10,24 +10,100 @@ import type {
 
-/** TODO: docs */
+let wallets: Wallets | undefined = undefined;
+const registered = new Set<Wallet>();
+const listeners: { [E in WalletsEventNames]?: WalletsEventsListeners[E][] } = {};
+
+/**
+ * Get an API for {@link Wallets.get | getting}, {@link Wallets.on | listening for}, and
+ * {@link Wallets.register | registering} {@link "@wallet-standard/base".Wallet | Wallets}.
+ *
+ * When called for the first time --
+ *
+ * This dispatches a {@link "@wallet-standard/base".WindowAppReadyEvent} to notify each Wallet that the app is ready
+ * to register it.
+ *
+ * This also adds a listener for {@link "@wallet-standard/base".WindowRegisterWalletEvent} to listen for a notification
+ * from each Wallet that the Wallet is ready to be registered by the app.
+ *
+ * This combination of event dispatch and listener guarantees that each Wallet will be registered synchronously as soon
+ * as the app is ready whether the app loads before or after each Wallet.
+ *
+ * @return API for getting, listening for, and registering Wallets.
+ *
+ * @group App
+ */
+export function getWallets(): Wallets {
+    if (wallets) return wallets;
+    wallets = Object.freeze({ register, get, on });
+    if (typeof window === 'undefined') return wallets;
+
+    const api = Object.freeze({ register });
+    try {
+        (window as WalletEventsWindow).addEventListener('wallet-standard:register-wallet', ({ detail: callback }) =>
+            callback(api)
+        );
+    } catch (error) {
+        console.error('wallet-standard:register-wallet event listener could not be added\n', error);
+    }
+    try {
+        (window as WalletEventsWindow).dispatchEvent(new AppReadyEvent(api));
+    } catch (error) {
+        console.error('wallet-standard:app-ready event could not be dispatched\n', error);
+    }
+
+    return wallets;
+}
+
+/**
+ * API for {@link Wallets.get | getting}, {@link Wallets.on | listening for}, and
+ * {@link Wallets.register | registering} {@link "@wallet-standard/base".Wallet | Wallets}.
+ *
+ * @group App
+ */
 export interface Wallets {
     /**
-     * TODO: docs
+     * Get all Wallets that have been registered.
+     *
+     * @return Registered Wallets.
      */
-    register(...wallets: Wallet[]): () => void;
+    get(): readonly Wallet[];
 
     /**
-     * TODO: docs
+     * Add an event listener and subscribe to events for Wallets that are
+     * {@link WalletsEventsListeners.register | registered} and
+     * {@link WalletsEventsListeners.unregister | unregistered}.
+     *
+     * @param event    Event type to listen for. {@link WalletsEventsListeners.register | `register`} and
+     * {@link WalletsEventsListeners.unregister | `unregister`} are the only event types.
+     * @param listener Function that will be called when an event of the type is emitted.
+     *
+     * @return
+     * `off` function which may be called to remove the event listener and unsubscribe from events.
+     *
+     * As with all event listeners, be careful to avoid memory leaks.
      */
-    get(): ReadonlyArray<Wallet>;
+    on<E extends WalletsEventNames>(event: E, listener: WalletsEventsListeners[E]): () => void;
 
     /**
-     * TODO: docs
+     * Register Wallets. This can be used to programmatically wrap non-standard wallets as Standard Wallets.
+     *
+     * Apps generally do not need to, and should not, call this.
+     *
+     * @param wallets Wallets to register.
+     *
+     * @return
+     * `unregister` function which may be called to programmatically unregister the registered Wallets.
+     *
+     * Apps generally do not need to, and should not, call this.
      */
-    on<E extends WalletsEventNames = WalletsEventNames>(event: E, listener: WalletsEvents[E]): () => void;
+    register(...wallets: Wallet[]): () => void;
 }
 
-/** TODO: docs */
-export interface WalletsEvents {
+/**
+ * Types of event listeners of the {@link Wallets} API.
+ *
+ * @group App
+ */
+export interface WalletsEventsListeners {
     /**
-     * Emitted when wallets are registered.
+     * Emitted when Wallets are registered.
      *
@@ -39,3 +115,3 @@ * @param wallets Wallets that were registered.
     /**
-     * Emitted when wallets are unregistered.
+     * Emitted when Wallets are unregistered.
      *
@@ -47,34 +123,16 @@ * @param wallets Wallets that were unregistered.
 
-/** TODO: docs */
-export type WalletsEventNames = keyof WalletsEvents;
+/**
+ * Names of {@link WalletsEventsListeners} that can be listened for.
+ *
+ * @group App
+ */
+export type WalletsEventNames = keyof WalletsEventsListeners;
 
-let wallets: Wallets | undefined = undefined;
-const registered = new Set<Wallet>();
-const listeners: { [E in WalletsEventNames]?: WalletsEvents[E][] } = {};
-
 /**
- * TODO: docs
+ * @deprecated Use {@link WalletsEventsListeners} instead.
+ *
+ * @group Deprecated
  */
-export function getWallets(): Wallets {
-    if (wallets) return wallets;
-    wallets = Object.freeze({ register, get, on });
-    if (typeof window === 'undefined') return wallets;
+export type WalletsEvents = WalletsEventsListeners;
 
-    const api = Object.freeze({ register });
-    try {
-        (window as WalletEventsWindow).addEventListener('wallet-standard:register-wallet', ({ detail: callback }) =>
-            callback(api)
-        );
-    } catch (error) {
-        console.error('wallet-standard:register-wallet event listener could not be added\n', error);
-    }
-    try {
-        (window as WalletEventsWindow).dispatchEvent(new AppReadyEvent(api));
-    } catch (error) {
-        console.error('wallet-standard:app-ready event could not be dispatched\n', error);
-    }
-
-    return wallets;
-}
-
 function register(...wallets: Wallet[]): () => void {
@@ -98,7 +156,7 @@ // Filter out wallets that have already been registered.
 
-function get(): ReadonlyArray<Wallet> {
+function get(): readonly Wallet[] {
     return [...registered];
 }
 
-function on<E extends WalletsEventNames>(event: E, listener: WalletsEvents[E]): () => void {
+function on<E extends WalletsEventNames>(event: E, listener: WalletsEventsListeners[E]): () => void {
     listeners[event]?.push(listener) || (listeners[event] = [listener]);
@@ -155,3 +213,7 @@ // Return a function that removes the event listener.
 
-/** @deprecated */
+/**
+ * @deprecated Use {@link getWallets} instead.
+ *
+ * @group Deprecated
+ */
 export function DEPRECATED_getWallets(): Wallets {
@@ -158,0 +220,0 @@ if (wallets) return wallets;

No alert changes

Improved metrics

Total package byte prevSize

45770

increased by18.47%

Lines of code

641

increased by33.82%

Number of lines in readme file

6

increased by500%

Dependency changes

• Updated@wallet-standard/base@^1.0.1