@metamask-previews/sample-controllers 0.0.0-preview-37b05a4

package/dist/types/pet-names-controller.cjs

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PetNamesController = exports.getDefaultPetNamesControllerState = exports.controllerName = void 0;
+const base_controller_1 = require("@metamask/base-controller");
+const controller_utils_1 = require("@metamask/controller-utils");
+// === GENERAL ===
+/**
+ * The name of the {@link PetNamesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+exports.controllerName = 'PetNamesController';
+/**
+ * The metadata for each property in {@link PetNamesControllerState}.
+ */
+const petNamesControllerMetadata = {
+    namesByChainIdAndAddress: {
+        persist: true,
+        anonymous: false,
+    },
+};
+/**
+ * Constructs the default {@link PetNamesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link PetNamesController} state.
+ */
+function getDefaultPetNamesControllerState() {
+    return {
+        namesByChainIdAndAddress: {},
+    };
+}
+exports.getDefaultPetNamesControllerState = getDefaultPetNamesControllerState;
+// === CONTROLLER DEFINITION ===
+/**
+ * `PetNamesController` records user-provided nicknames for various addresses on
+ * various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import type {
+ *   PetNamesControllerActions,
+ *   PetNamesControllerEvents
+ * } from '@metamask/example-controllers';
+ *
+ * const rootMessenger = new Messenger<
+ *  PetNamesControllerActions,
+ *  PetNamesControllerEvents
+ * >();
+ * const petNamesMessenger = rootMessenger.getRestricted({
+ *   name: 'PetNamesController',
+ *   allowedActions: [],
+ *   allowedEvents: [],
+ * });
+ * const petNamesController = new GasPricesController({
+ *   messenger: petNamesMessenger,
+ * });
+ *
+ * petNamesController.assignPetName(
+ *   '0x1',
+ *   '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99',
+ *   'Primary Account'
+ * );
+ * petNamesController.state.namesByChainIdAndAddress
+ * // => { '0x1': { '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99': 'Primary Account' } }
+ * ```
+ */
+class PetNamesController extends base_controller_1.BaseController {
+    /**
+     * Constructs a new {@link PetNamesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     */
+    constructor({ messenger, state, }) {
+        super({
+            messenger,
+            metadata: petNamesControllerMetadata,
+            name: exports.controllerName,
+            state: {
+                ...getDefaultPetNamesControllerState(),
+                ...state,
+            },
+        });
+    }
+    /**
+     * Registers the given name with the given address (relative to the given
+     * chain).
+     *
+     * @param chainId - The chain ID that the address belongs to.
+     * @param address - The account address to name.
+     * @param name - The name to assign to the address.
+     */
+    assignPetName(chainId, address, name) {
+        if (!(0, controller_utils_1.isSafeDynamicKey)(chainId)) {
+            throw new Error('Invalid chain ID');
+        }
+        const normalizedAddress = address.toLowerCase();
+        this.update((state) => {
+            var _a;
+            (_a = state.namesByChainIdAndAddress)[chainId] ?? (_a[chainId] = {});
+            state.namesByChainIdAndAddress[chainId][normalizedAddress] = name;
+        });
+    }
+}
+exports.PetNamesController = PetNamesController;
+//# sourceMappingURL=pet-names-controller.cjs.map

package/dist/types/pet-names-controller.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pet-names-controller.cjs","sourceRoot":"","sources":["../../src/pet-names-controller.ts"],"names":[],"mappings":";;;AAMA,+DAA2D;AAC3D,iEAA8D;AAG9D,kBAAkB;AAElB;;;;GAIG;AACU,QAAA,cAAc,GAAG,oBAAoB,CAAC;AAmBnD;;GAEG;AACH,MAAM,0BAA0B,GAAG;IACjC,wBAAwB,EAAE;QACxB,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,KAAK;KACjB;CAC+C,CAAC;AAuDnD;;;;;;;GAOG;AACH,SAAgB,iCAAiC;IAC/C,OAAO;QACL,wBAAwB,EAAE,EAAE;KAC7B,CAAC;AACJ,CAAC;AAJD,8EAIC;AAED,gCAAgC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAa,kBAAmB,SAAQ,gCAIvC;IACC;;;;;;;OAOG;IACH,YAAY,EACV,SAAS,EACT,KAAK,GAIN;QACC,KAAK,CAAC;YACJ,SAAS;YACT,QAAQ,EAAE,0BAA0B;YACpC,IAAI,EAAE,sBAAc;YACpB,KAAK,EAAE;gBACL,GAAG,iCAAiC,EAAE;gBACtC,GAAG,KAAK;aACT;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,OAAY,EAAE,OAAY,EAAE,IAAY;QACpD,IAAI,CAAC,IAAA,mCAAgB,EAAC,OAAO,CAAC,EAAE;YAC9B,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;SACrC;QAED,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAS,CAAC;QAEvD,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;;YACpB,MAAA,KAAK,CAAC,wBAAwB,EAAC,OAAO,SAAP,OAAO,IAAM,EAAE,EAAC;YAC/C,KAAK,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;QACpE,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAnDD,gDAmDC","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  RestrictedMessenger,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport { isSafeDynamicKey } from '@metamask/controller-utils';\nimport type { Hex } from '@metamask/utils';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link PetNamesController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'PetNamesController';\n\n// === STATE ===\n\n/**\n * Describes the shape of the state object for {@link PetNamesController}.\n */\nexport type PetNamesControllerState = {\n  /**\n   * The registry of pet names, categorized by chain ID first and address\n   * second.\n   */\n  namesByChainIdAndAddress: {\n    [chainId: Hex]: {\n      [address: Hex]: string;\n    };\n  };\n};\n\n/**\n * The metadata for each property in {@link PetNamesControllerState}.\n */\nconst petNamesControllerMetadata = {\n  namesByChainIdAndAddress: {\n    persist: true,\n    anonymous: false,\n  },\n} satisfies StateMetadata<PetNamesControllerState>;\n\n// === MESSENGER ===\n\n/**\n * The action which can be used to retrieve the state of the\n * {@link PetNamesController}.\n */\nexport type PetNamesControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  PetNamesControllerState\n>;\n\n/**\n * All actions that {@link PetNamesController} registers, to be called\n * externally.\n */\nexport type PetNamesControllerActions = PetNamesControllerGetStateAction;\n\n/**\n * All actions that {@link PetNamesController} calls internally.\n */\ntype AllowedActions = never;\n\n/**\n * The event that {@link PetNamesController} publishes when updating state.\n */\nexport type PetNamesControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  PetNamesControllerState\n>;\n\n/**\n * All events that {@link PetNamesController} publishes, to be subscribed to\n * externally.\n */\nexport type PetNamesControllerEvents = PetNamesControllerStateChangeEvent;\n\n/**\n * All events that {@link PetNamesController} subscribes to internally.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger which is restricted to actions and events accessed by\n * {@link PetNamesController}.\n */\nexport type PetNamesControllerMessenger = RestrictedMessenger<\n  typeof controllerName,\n  PetNamesControllerActions | AllowedActions,\n  PetNamesControllerEvents | AllowedEvents,\n  AllowedActions['type'],\n  AllowedEvents['type']\n>;\n\n/**\n * Constructs the default {@link PetNamesController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link PetNamesController} state.\n */\nexport function getDefaultPetNamesControllerState(): PetNamesControllerState {\n  return {\n    namesByChainIdAndAddress: {},\n  };\n}\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * `PetNamesController` records user-provided nicknames for various addresses on\n * various chains.\n *\n * @example\n *\n * ``` ts\n * import { Messenger } from '@metamask/base-controller';\n * import type {\n *   PetNamesControllerActions,\n *   PetNamesControllerEvents\n * } from '@metamask/example-controllers';\n *\n * const rootMessenger = new Messenger<\n *  PetNamesControllerActions,\n *  PetNamesControllerEvents\n * >();\n * const petNamesMessenger = rootMessenger.getRestricted({\n *   name: 'PetNamesController',\n *   allowedActions: [],\n *   allowedEvents: [],\n * });\n * const petNamesController = new GasPricesController({\n *   messenger: petNamesMessenger,\n * });\n *\n * petNamesController.assignPetName(\n *   '0x1',\n *   '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99',\n *   'Primary Account'\n * );\n * petNamesController.state.namesByChainIdAndAddress\n * // => { '0x1': { '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99': 'Primary Account' } }\n * ```\n */\nexport class PetNamesController extends BaseController<\n  typeof controllerName,\n  PetNamesControllerState,\n  PetNamesControllerMessenger\n> {\n  /**\n   * Constructs a new {@link PetNamesController}.\n   *\n   * @param args - The arguments to the controller.\n   * @param args.messenger - The messenger suited for this controller.\n   * @param args.state - The desired state with which to initialize this\n   * controller. Missing properties will be filled in with defaults.\n   */\n  constructor({\n    messenger,\n    state,\n  }: {\n    messenger: PetNamesControllerMessenger;\n    state?: Partial<PetNamesControllerState>;\n  }) {\n    super({\n      messenger,\n      metadata: petNamesControllerMetadata,\n      name: controllerName,\n      state: {\n        ...getDefaultPetNamesControllerState(),\n        ...state,\n      },\n    });\n  }\n\n  /**\n   * Registers the given name with the given address (relative to the given\n   * chain).\n   *\n   * @param chainId - The chain ID that the address belongs to.\n   * @param address - The account address to name.\n   * @param name - The name to assign to the address.\n   */\n  assignPetName(chainId: Hex, address: Hex, name: string) {\n    if (!isSafeDynamicKey(chainId)) {\n      throw new Error('Invalid chain ID');\n    }\n\n    const normalizedAddress = address.toLowerCase() as Hex;\n\n    this.update((state) => {\n      state.namesByChainIdAndAddress[chainId] ??= {};\n      state.namesByChainIdAndAddress[chainId][normalizedAddress] = name;\n    });\n  }\n}\n"]}

package/dist/types/pet-names-controller.d.cts

@@ -0,0 +1,124 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent, RestrictedMessenger } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Hex } from "@metamask/utils";
+/**
+ * The name of the {@link PetNamesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export declare const controllerName = "PetNamesController";
+/**
+ * Describes the shape of the state object for {@link PetNamesController}.
+ */
+export type PetNamesControllerState = {
+    /**
+     * The registry of pet names, categorized by chain ID first and address
+     * second.
+     */
+    namesByChainIdAndAddress: {
+        [chainId: Hex]: {
+            [address: Hex]: string;
+        };
+    };
+};
+/**
+ * The action which can be used to retrieve the state of the
+ * {@link PetNamesController}.
+ */
+export type PetNamesControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PetNamesControllerState>;
+/**
+ * All actions that {@link PetNamesController} registers, to be called
+ * externally.
+ */
+export type PetNamesControllerActions = PetNamesControllerGetStateAction;
+/**
+ * All actions that {@link PetNamesController} calls internally.
+ */
+type AllowedActions = never;
+/**
+ * The event that {@link PetNamesController} publishes when updating state.
+ */
+export type PetNamesControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PetNamesControllerState>;
+/**
+ * All events that {@link PetNamesController} publishes, to be subscribed to
+ * externally.
+ */
+export type PetNamesControllerEvents = PetNamesControllerStateChangeEvent;
+/**
+ * All events that {@link PetNamesController} subscribes to internally.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger which is restricted to actions and events accessed by
+ * {@link PetNamesController}.
+ */
+export type PetNamesControllerMessenger = RestrictedMessenger<typeof controllerName, PetNamesControllerActions | AllowedActions, PetNamesControllerEvents | AllowedEvents, AllowedActions['type'], AllowedEvents['type']>;
+/**
+ * Constructs the default {@link PetNamesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link PetNamesController} state.
+ */
+export declare function getDefaultPetNamesControllerState(): PetNamesControllerState;
+/**
+ * `PetNamesController` records user-provided nicknames for various addresses on
+ * various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import type {
+ *   PetNamesControllerActions,
+ *   PetNamesControllerEvents
+ * } from '@metamask/example-controllers';
+ *
+ * const rootMessenger = new Messenger<
+ *  PetNamesControllerActions,
+ *  PetNamesControllerEvents
+ * >();
+ * const petNamesMessenger = rootMessenger.getRestricted({
+ *   name: 'PetNamesController',
+ *   allowedActions: [],
+ *   allowedEvents: [],
+ * });
+ * const petNamesController = new GasPricesController({
+ *   messenger: petNamesMessenger,
+ * });
+ *
+ * petNamesController.assignPetName(
+ *   '0x1',
+ *   '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99',
+ *   'Primary Account'
+ * );
+ * petNamesController.state.namesByChainIdAndAddress
+ * // => { '0x1': { '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99': 'Primary Account' } }
+ * ```
+ */
+export declare class PetNamesController extends BaseController<typeof controllerName, PetNamesControllerState, PetNamesControllerMessenger> {
+    /**
+     * Constructs a new {@link PetNamesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     */
+    constructor({ messenger, state, }: {
+        messenger: PetNamesControllerMessenger;
+        state?: Partial<PetNamesControllerState>;
+    });
+    /**
+     * Registers the given name with the given address (relative to the given
+     * chain).
+     *
+     * @param chainId - The chain ID that the address belongs to.
+     * @param address - The account address to name.
+     * @param name - The name to assign to the address.
+     */
+    assignPetName(chainId: Hex, address: Hex, name: string): void;
+}
+export {};
+//# sourceMappingURL=pet-names-controller.d.cts.map

package/dist/types/pet-names-controller.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pet-names-controller.d.cts","sourceRoot":"","sources":["../../src/pet-names-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EAEpB,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAE3D,OAAO,KAAK,EAAE,GAAG,EAAE,wBAAwB;AAI3C;;;;GAIG;AACH,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAInD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,wBAAwB,EAAE;QACxB,CAAC,OAAO,EAAE,GAAG,GAAG;YACd,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,CAAC;SACxB,CAAC;KACH,CAAC;CACH,CAAC;AAcF;;;GAGG;AACH,MAAM,MAAM,gCAAgC,GAAG,wBAAwB,CACrE,OAAO,cAAc,EACrB,uBAAuB,CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,gCAAgC,CAAC;AAEzE;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG,0BAA0B,CACzE,OAAO,cAAc,EACrB,uBAAuB,CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,kCAAkC,CAAC;AAE1E;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAC3D,OAAO,cAAc,EACrB,yBAAyB,GAAG,cAAc,EAC1C,wBAAwB,GAAG,aAAa,EACxC,cAAc,CAAC,MAAM,CAAC,EACtB,aAAa,CAAC,MAAM,CAAC,CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,IAAI,uBAAuB,CAI3E;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CACpD,OAAO,cAAc,EACrB,uBAAuB,EACvB,2BAA2B,CAC5B;IACC;;;;;;;OAOG;gBACS,EACV,SAAS,EACT,KAAK,GACN,EAAE;QACD,SAAS,EAAE,2BAA2B,CAAC;QACvC,KAAK,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;KAC1C;IAYD;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM;CAYvD"}

package/dist/types/pet-names-controller.d.mts

@@ -0,0 +1,124 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent, RestrictedMessenger } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Hex } from "@metamask/utils";
+/**
+ * The name of the {@link PetNamesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export declare const controllerName = "PetNamesController";
+/**
+ * Describes the shape of the state object for {@link PetNamesController}.
+ */
+export type PetNamesControllerState = {
+    /**
+     * The registry of pet names, categorized by chain ID first and address
+     * second.
+     */
+    namesByChainIdAndAddress: {
+        [chainId: Hex]: {
+            [address: Hex]: string;
+        };
+    };
+};
+/**
+ * The action which can be used to retrieve the state of the
+ * {@link PetNamesController}.
+ */
+export type PetNamesControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PetNamesControllerState>;
+/**
+ * All actions that {@link PetNamesController} registers, to be called
+ * externally.
+ */
+export type PetNamesControllerActions = PetNamesControllerGetStateAction;
+/**
+ * All actions that {@link PetNamesController} calls internally.
+ */
+type AllowedActions = never;
+/**
+ * The event that {@link PetNamesController} publishes when updating state.
+ */
+export type PetNamesControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PetNamesControllerState>;
+/**
+ * All events that {@link PetNamesController} publishes, to be subscribed to
+ * externally.
+ */
+export type PetNamesControllerEvents = PetNamesControllerStateChangeEvent;
+/**
+ * All events that {@link PetNamesController} subscribes to internally.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger which is restricted to actions and events accessed by
+ * {@link PetNamesController}.
+ */
+export type PetNamesControllerMessenger = RestrictedMessenger<typeof controllerName, PetNamesControllerActions | AllowedActions, PetNamesControllerEvents | AllowedEvents, AllowedActions['type'], AllowedEvents['type']>;
+/**
+ * Constructs the default {@link PetNamesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link PetNamesController} state.
+ */
+export declare function getDefaultPetNamesControllerState(): PetNamesControllerState;
+/**
+ * `PetNamesController` records user-provided nicknames for various addresses on
+ * various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import type {
+ *   PetNamesControllerActions,
+ *   PetNamesControllerEvents
+ * } from '@metamask/example-controllers';
+ *
+ * const rootMessenger = new Messenger<
+ *  PetNamesControllerActions,
+ *  PetNamesControllerEvents
+ * >();
+ * const petNamesMessenger = rootMessenger.getRestricted({
+ *   name: 'PetNamesController',
+ *   allowedActions: [],
+ *   allowedEvents: [],
+ * });
+ * const petNamesController = new GasPricesController({
+ *   messenger: petNamesMessenger,
+ * });
+ *
+ * petNamesController.assignPetName(
+ *   '0x1',
+ *   '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99',
+ *   'Primary Account'
+ * );
+ * petNamesController.state.namesByChainIdAndAddress
+ * // => { '0x1': { '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99': 'Primary Account' } }
+ * ```
+ */
+export declare class PetNamesController extends BaseController<typeof controllerName, PetNamesControllerState, PetNamesControllerMessenger> {
+    /**
+     * Constructs a new {@link PetNamesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     */
+    constructor({ messenger, state, }: {
+        messenger: PetNamesControllerMessenger;
+        state?: Partial<PetNamesControllerState>;
+    });
+    /**
+     * Registers the given name with the given address (relative to the given
+     * chain).
+     *
+     * @param chainId - The chain ID that the address belongs to.
+     * @param address - The account address to name.
+     * @param name - The name to assign to the address.
+     */
+    assignPetName(chainId: Hex, address: Hex, name: string): void;
+}
+export {};
+//# sourceMappingURL=pet-names-controller.d.mts.map

package/dist/types/pet-names-controller.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pet-names-controller.d.mts","sourceRoot":"","sources":["../../src/pet-names-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EAEpB,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAE3D,OAAO,KAAK,EAAE,GAAG,EAAE,wBAAwB;AAI3C;;;;GAIG;AACH,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAInD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,wBAAwB,EAAE;QACxB,CAAC,OAAO,EAAE,GAAG,GAAG;YACd,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,CAAC;SACxB,CAAC;KACH,CAAC;CACH,CAAC;AAcF;;;GAGG;AACH,MAAM,MAAM,gCAAgC,GAAG,wBAAwB,CACrE,OAAO,cAAc,EACrB,uBAAuB,CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,gCAAgC,CAAC;AAEzE;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG,0BAA0B,CACzE,OAAO,cAAc,EACrB,uBAAuB,CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,kCAAkC,CAAC;AAE1E;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAC3D,OAAO,cAAc,EACrB,yBAAyB,GAAG,cAAc,EAC1C,wBAAwB,GAAG,aAAa,EACxC,cAAc,CAAC,MAAM,CAAC,EACtB,aAAa,CAAC,MAAM,CAAC,CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,IAAI,uBAAuB,CAI3E;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CACpD,OAAO,cAAc,EACrB,uBAAuB,EACvB,2BAA2B,CAC5B;IACC;;;;;;;OAOG;gBACS,EACV,SAAS,EACT,KAAK,GACN,EAAE;QACD,SAAS,EAAE,2BAA2B,CAAC;QACvC,KAAK,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;KAC1C;IAYD;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM;CAYvD"}

package/dist/types/pet-names-controller.mjs

@@ -0,0 +1,108 @@
+import { BaseController } from "@metamask/base-controller";
+import { isSafeDynamicKey } from "@metamask/controller-utils";
+// === GENERAL ===
+/**
+ * The name of the {@link PetNamesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export const controllerName = 'PetNamesController';
+/**
+ * The metadata for each property in {@link PetNamesControllerState}.
+ */
+const petNamesControllerMetadata = {
+    namesByChainIdAndAddress: {
+        persist: true,
+        anonymous: false,
+    },
+};
+/**
+ * Constructs the default {@link PetNamesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link PetNamesController} state.
+ */
+export function getDefaultPetNamesControllerState() {
+    return {
+        namesByChainIdAndAddress: {},
+    };
+}
+// === CONTROLLER DEFINITION ===
+/**
+ * `PetNamesController` records user-provided nicknames for various addresses on
+ * various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import type {
+ *   PetNamesControllerActions,
+ *   PetNamesControllerEvents
+ * } from '@metamask/example-controllers';
+ *
+ * const rootMessenger = new Messenger<
+ *  PetNamesControllerActions,
+ *  PetNamesControllerEvents
+ * >();
+ * const petNamesMessenger = rootMessenger.getRestricted({
+ *   name: 'PetNamesController',
+ *   allowedActions: [],
+ *   allowedEvents: [],
+ * });
+ * const petNamesController = new GasPricesController({
+ *   messenger: petNamesMessenger,
+ * });
+ *
+ * petNamesController.assignPetName(
+ *   '0x1',
+ *   '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99',
+ *   'Primary Account'
+ * );
+ * petNamesController.state.namesByChainIdAndAddress
+ * // => { '0x1': { '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99': 'Primary Account' } }
+ * ```
+ */
+export class PetNamesController extends BaseController {
+    /**
+     * Constructs a new {@link PetNamesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     */
+    constructor({ messenger, state, }) {
+        super({
+            messenger,
+            metadata: petNamesControllerMetadata,
+            name: controllerName,
+            state: {
+                ...getDefaultPetNamesControllerState(),
+                ...state,
+            },
+        });
+    }
+    /**
+     * Registers the given name with the given address (relative to the given
+     * chain).
+     *
+     * @param chainId - The chain ID that the address belongs to.
+     * @param address - The account address to name.
+     * @param name - The name to assign to the address.
+     */
+    assignPetName(chainId, address, name) {
+        if (!isSafeDynamicKey(chainId)) {
+            throw new Error('Invalid chain ID');
+        }
+        const normalizedAddress = address.toLowerCase();
+        this.update((state) => {
+            var _a;
+            (_a = state.namesByChainIdAndAddress)[chainId] ?? (_a[chainId] = {});
+            state.namesByChainIdAndAddress[chainId][normalizedAddress] = name;
+        });
+    }
+}
+//# sourceMappingURL=pet-names-controller.mjs.map

package/dist/types/pet-names-controller.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pet-names-controller.mjs","sourceRoot":"","sources":["../../src/pet-names-controller.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,mCAAmC;AAG9D,kBAAkB;AAElB;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAC;AAmBnD;;GAEG;AACH,MAAM,0BAA0B,GAAG;IACjC,wBAAwB,EAAE;QACxB,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,KAAK;KACjB;CAC+C,CAAC;AAuDnD;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC;IAC/C,OAAO;QACL,wBAAwB,EAAE,EAAE;KAC7B,CAAC;AACJ,CAAC;AAED,gCAAgC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAO,kBAAmB,SAAQ,cAIvC;IACC;;;;;;;OAOG;IACH,YAAY,EACV,SAAS,EACT,KAAK,GAIN;QACC,KAAK,CAAC;YACJ,SAAS;YACT,QAAQ,EAAE,0BAA0B;YACpC,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE;gBACL,GAAG,iCAAiC,EAAE;gBACtC,GAAG,KAAK;aACT;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,OAAY,EAAE,OAAY,EAAE,IAAY;QACpD,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE;YAC9B,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;SACrC;QAED,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAS,CAAC;QAEvD,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;;YACpB,MAAA,KAAK,CAAC,wBAAwB,EAAC,OAAO,SAAP,OAAO,IAAM,EAAE,EAAC;YAC/C,KAAK,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;QACpE,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  RestrictedMessenger,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport { isSafeDynamicKey } from '@metamask/controller-utils';\nimport type { Hex } from '@metamask/utils';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link PetNamesController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'PetNamesController';\n\n// === STATE ===\n\n/**\n * Describes the shape of the state object for {@link PetNamesController}.\n */\nexport type PetNamesControllerState = {\n  /**\n   * The registry of pet names, categorized by chain ID first and address\n   * second.\n   */\n  namesByChainIdAndAddress: {\n    [chainId: Hex]: {\n      [address: Hex]: string;\n    };\n  };\n};\n\n/**\n * The metadata for each property in {@link PetNamesControllerState}.\n */\nconst petNamesControllerMetadata = {\n  namesByChainIdAndAddress: {\n    persist: true,\n    anonymous: false,\n  },\n} satisfies StateMetadata<PetNamesControllerState>;\n\n// === MESSENGER ===\n\n/**\n * The action which can be used to retrieve the state of the\n * {@link PetNamesController}.\n */\nexport type PetNamesControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  PetNamesControllerState\n>;\n\n/**\n * All actions that {@link PetNamesController} registers, to be called\n * externally.\n */\nexport type PetNamesControllerActions = PetNamesControllerGetStateAction;\n\n/**\n * All actions that {@link PetNamesController} calls internally.\n */\ntype AllowedActions = never;\n\n/**\n * The event that {@link PetNamesController} publishes when updating state.\n */\nexport type PetNamesControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  PetNamesControllerState\n>;\n\n/**\n * All events that {@link PetNamesController} publishes, to be subscribed to\n * externally.\n */\nexport type PetNamesControllerEvents = PetNamesControllerStateChangeEvent;\n\n/**\n * All events that {@link PetNamesController} subscribes to internally.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger which is restricted to actions and events accessed by\n * {@link PetNamesController}.\n */\nexport type PetNamesControllerMessenger = RestrictedMessenger<\n  typeof controllerName,\n  PetNamesControllerActions | AllowedActions,\n  PetNamesControllerEvents | AllowedEvents,\n  AllowedActions['type'],\n  AllowedEvents['type']\n>;\n\n/**\n * Constructs the default {@link PetNamesController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link PetNamesController} state.\n */\nexport function getDefaultPetNamesControllerState(): PetNamesControllerState {\n  return {\n    namesByChainIdAndAddress: {},\n  };\n}\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * `PetNamesController` records user-provided nicknames for various addresses on\n * various chains.\n *\n * @example\n *\n * ``` ts\n * import { Messenger } from '@metamask/base-controller';\n * import type {\n *   PetNamesControllerActions,\n *   PetNamesControllerEvents\n * } from '@metamask/example-controllers';\n *\n * const rootMessenger = new Messenger<\n *  PetNamesControllerActions,\n *  PetNamesControllerEvents\n * >();\n * const petNamesMessenger = rootMessenger.getRestricted({\n *   name: 'PetNamesController',\n *   allowedActions: [],\n *   allowedEvents: [],\n * });\n * const petNamesController = new GasPricesController({\n *   messenger: petNamesMessenger,\n * });\n *\n * petNamesController.assignPetName(\n *   '0x1',\n *   '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99',\n *   'Primary Account'\n * );\n * petNamesController.state.namesByChainIdAndAddress\n * // => { '0x1': { '0xF57F855e17483B1f09bFec62783C9d3b6c8b3A99': 'Primary Account' } }\n * ```\n */\nexport class PetNamesController extends BaseController<\n  typeof controllerName,\n  PetNamesControllerState,\n  PetNamesControllerMessenger\n> {\n  /**\n   * Constructs a new {@link PetNamesController}.\n   *\n   * @param args - The arguments to the controller.\n   * @param args.messenger - The messenger suited for this controller.\n   * @param args.state - The desired state with which to initialize this\n   * controller. Missing properties will be filled in with defaults.\n   */\n  constructor({\n    messenger,\n    state,\n  }: {\n    messenger: PetNamesControllerMessenger;\n    state?: Partial<PetNamesControllerState>;\n  }) {\n    super({\n      messenger,\n      metadata: petNamesControllerMetadata,\n      name: controllerName,\n      state: {\n        ...getDefaultPetNamesControllerState(),\n        ...state,\n      },\n    });\n  }\n\n  /**\n   * Registers the given name with the given address (relative to the given\n   * chain).\n   *\n   * @param chainId - The chain ID that the address belongs to.\n   * @param address - The account address to name.\n   * @param name - The name to assign to the address.\n   */\n  assignPetName(chainId: Hex, address: Hex, name: string) {\n    if (!isSafeDynamicKey(chainId)) {\n      throw new Error('Invalid chain ID');\n    }\n\n    const normalizedAddress = address.toLowerCase() as Hex;\n\n    this.update((state) => {\n      state.namesByChainIdAndAddress[chainId] ??= {};\n      state.namesByChainIdAndAddress[chainId][normalizedAddress] = name;\n    });\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@metamask-previews/sample-controllers",
+  "version": "0.0.0-preview-37b05a4",
+  "description": "Sample package to illustrate best practices for controllers",
+  "keywords": [
+    "MetaMask",
+    "Ethereum"
+  ],
+  "homepage": "https://github.com/MetaMask/core/tree/main/packages/sample-controllers#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/core/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/core.git"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
+    "build:docs": "typedoc",
+    "changelog:update": "../../scripts/update-changelog.sh @metamask/sample-controllers",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/sample-controllers",
+    "since-latest-release": "../../scripts/since-latest-release.sh",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
+    "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
+    "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+  },
+  "dependencies": {
+    "@metamask/base-controller": "^8.0.0",
+    "@metamask/utils": "^11.2.0"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^3.4.4",
+    "@metamask/controller-utils": "^11.5.0",
+    "@types/jest": "^27.4.1",
+    "deepmerge": "^4.2.2",
+    "jest": "^27.5.1",
+    "nock": "^13.3.1",
+    "ts-jest": "^27.1.4",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "~5.2.2"
+  },
+  "engines": {
+    "node": "^18.18 || >=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}