@metamask-previews/base-controller 3.2.0-preview.d32a7cc

package/dist/BaseControllerV2.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPersistentState = exports.getAnonymizedState = exports.BaseController = void 0;
+const immer_1 = require("immer");
+(0, immer_1.enablePatches)();
+/**
+ * Controller class that provides state management, subscriptions, and state metadata
+ */
+class BaseController {
+    /**
+     * Creates a BaseController instance.
+     *
+     * @param options - Controller options.
+     * @param options.messenger - Controller messaging system.
+     * @param options.metadata - State metadata, describing how to "anonymize" the state, and which
+     * parts should be persisted.
+     * @param options.name - The name of the controller, used as a namespace for events and actions.
+     * @param options.state - Initial controller state.
+     */
+    constructor({ messenger, metadata, name, state, }) {
+        this.messagingSystem = messenger;
+        this.name = name;
+        this.internalState = state;
+        this.metadata = metadata;
+        this.messagingSystem.registerActionHandler(`${name}:getState`, () => this.state);
+    }
+    /**
+     * Retrieves current controller state.
+     *
+     * @returns The current state.
+     */
+    get state() {
+        return this.internalState;
+    }
+    set state(_) {
+        throw new Error(`Controller state cannot be directly mutated; use 'update' method instead.`);
+    }
+    /**
+     * Updates controller state. Accepts a callback that is passed a draft copy
+     * of the controller state. If a value is returned, it is set as the new
+     * state. Otherwise, any changes made within that callback to the draft are
+     * applied to the controller state.
+     *
+     * @param callback - Callback for updating state, passed a draft state
+     * object. Return a new state object or mutate the draft to update state.
+     * @returns An object that has the next state, patches applied in the update and inverse patches to
+     * rollback the update.
+     */
+    update(callback) {
+        // We run into ts2589, "infinite type depth", if we don't cast
+        // produceWithPatches here.
+        const [nextState, patches, inversePatches] = immer_1.produceWithPatches(this.internalState, callback);
+        this.internalState = nextState;
+        this.messagingSystem.publish(`${this.name}:stateChange`, nextState, patches);
+        return { nextState, patches, inversePatches };
+    }
+    /**
+     * Applies immer patches to the current state. The patches come from the
+     * update function itself and can either be normal or inverse patches.
+     *
+     * @param patches - An array of immer patches that are to be applied to make
+     * or undo changes.
+     */
+    applyPatches(patches) {
+        const nextState = (0, immer_1.applyPatches)(this.internalState, patches);
+        this.internalState = nextState;
+        this.messagingSystem.publish(`${this.name}:stateChange`, nextState, patches);
+    }
+    /**
+     * Prepares the controller for garbage collection. This should be extended
+     * by any subclasses to clean up any additional connections or events.
+     *
+     * The only cleanup performed here is to remove listeners. While technically
+     * this is not required to ensure this instance is garbage collected, it at
+     * least ensures this instance won't be responsible for preventing the
+     * listeners from being garbage collected.
+     */
+    destroy() {
+        this.messagingSystem.clearEventSubscriptions(`${this.name}:stateChange`);
+    }
+}
+exports.BaseController = BaseController;
+/**
+ * Returns an anonymized representation of the controller state.
+ *
+ * By "anonymized" we mean that it should not contain any information that could be personally
+ * identifiable.
+ *
+ * @param state - The controller state.
+ * @param metadata - The controller state metadata, which describes how to derive the
+ * anonymized state.
+ * @returns The anonymized controller state.
+ */
+function getAnonymizedState(state, metadata) {
+    return deriveStateFromMetadata(state, metadata, 'anonymous');
+}
+exports.getAnonymizedState = getAnonymizedState;
+/**
+ * Returns the subset of state that should be persisted.
+ *
+ * @param state - The controller state.
+ * @param metadata - The controller state metadata, which describes which pieces of state should be persisted.
+ * @returns The subset of controller state that should be persisted.
+ */
+function getPersistentState(state, metadata) {
+    return deriveStateFromMetadata(state, metadata, 'persist');
+}
+exports.getPersistentState = getPersistentState;
+/**
+ * Use the metadata to derive state according to the given metadata property.
+ *
+ * @param state - The full controller state.
+ * @param metadata - The controller metadata.
+ * @param metadataProperty - The metadata property to use to derive state.
+ * @returns The metadata-derived controller state.
+ */
+function deriveStateFromMetadata(state, metadata, metadataProperty) {
+    return Object.keys(state).reduce((persistedState, key) => {
+        try {
+            const stateMetadata = metadata[key];
+            if (!stateMetadata) {
+                throw new Error(`No metadata found for '${key}'`);
+            }
+            const propertyMetadata = stateMetadata[metadataProperty];
+            const stateProperty = state[key];
+            if (typeof propertyMetadata === 'function') {
+                persistedState[key] = propertyMetadata(stateProperty);
+            }
+            else if (propertyMetadata) {
+                persistedState[key] = stateProperty;
+            }
+            return persistedState;
+        }
+        catch (error) {
+            // Throw error after timeout so that it is captured as a console error
+            // (and by Sentry) without interrupting state-related operations
+            setTimeout(() => {
+                throw error;
+            });
+            return persistedState;
+        }
+    }, {});
+}
+//# sourceMappingURL=BaseControllerV2.js.map

package/dist/BaseControllerV2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseControllerV2.js","sourceRoot":"","sources":["../src/BaseControllerV2.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Json } from '@metamask/utils';\nimport { enablePatches, produceWithPatches, applyPatches } from 'immer';\nimport type { Draft, Patch } from 'immer';\n\nimport type {\n  RestrictedControllerMessenger,\n  Namespaced,\n} from './ControllerMessenger';\n\nenablePatches();\n\n/**\n * A state change listener.\n *\n * This function will get called for each state change, and is given a copy of\n * the new state along with a set of patches describing the changes since the\n * last update.\n *\n * @param state - The new controller state.\n * @param patches - A list of patches describing any changes (see here for more\n * information: https://immerjs.github.io/immer/docs/patches)\n */\nexport type Listener<T> = (state: T, patches: Patch[]) => void;\n\n/**\n * An function to derive state.\n *\n * This function will accept one piece of the controller state (one property),\n * and will return some derivation of that state.\n *\n * @param value - A piece of controller state.\n * @returns Something derived from controller state.\n */\nexport type StateDeriver<T extends Json> = (value: T) => Json;\n\n/**\n * State metadata.\n *\n * This metadata describes which parts of state should be persisted, and how to\n * get an anonymized representation of the state.\n */\nexport type StateMetadata<T extends Record<string, Json>> = {\n  [P in keyof T]: StatePropertyMetadata<T[P]>;\n};\n\n/**\n * Metadata for a single state property\n *\n * @property persist - Indicates whether this property should be persisted\n * (`true` for persistent, `false` for transient), or is set to a function\n * that derives the persistent state from the state.\n * @property anonymous - Indicates whether this property is already anonymous,\n * (`true` for anonymous, `false` if it has potential to be personally\n * identifiable), or is set to a function that returns an anonymized\n * representation of this state.\n */\nexport interface StatePropertyMetadata<T extends Json> {\n  persist: boolean | StateDeriver<T>;\n  anonymous: boolean | StateDeriver<T>;\n}\n\n/**\n * Controller class that provides state management, subscriptions, and state metadata\n */\nexport class BaseController<\n  N extends string,\n  S extends Record<string, Json>,\n  messenger extends RestrictedControllerMessenger<N, any, any, string, string>,\n> {\n  private internalState: S;\n\n  protected messagingSystem: messenger;\n\n  /**\n   * The name of the controller.\n   *\n   * This is used by the ComposableController to construct a composed application state.\n   */\n  public readonly name: N;\n\n  public readonly metadata: StateMetadata<S>;\n\n  /**\n   * The existence of the `subscribe` property is how the ComposableController detects whether a\n   * controller extends the old BaseController or the new one. We set it to `undefined` here to\n   * ensure the ComposableController never mistakes them for an older style controller.\n   */\n  public readonly subscribe: undefined;\n\n  /**\n   * Creates a BaseController instance.\n   *\n   * @param options - Controller options.\n   * @param options.messenger - Controller messaging system.\n   * @param options.metadata - State metadata, describing how to \"anonymize\" the state, and which\n   * parts should be persisted.\n   * @param options.name - The name of the controller, used as a namespace for events and actions.\n   * @param options.state - Initial controller state.\n   */\n  constructor({\n    messenger,\n    metadata,\n    name,\n    state,\n  }: {\n    messenger: messenger;\n    metadata: StateMetadata<S>;\n    name: N;\n    state: S;\n  }) {\n    this.messagingSystem = messenger;\n    this.name = name;\n    this.internalState = state;\n    this.metadata = metadata;\n\n    this.messagingSystem.registerActionHandler(\n      `${name}:getState`,\n      () => this.state,\n    );\n  }\n\n  /**\n   * Retrieves current controller state.\n   *\n   * @returns The current state.\n   */\n  get state() {\n    return this.internalState;\n  }\n\n  set state(_) {\n    throw new Error(\n      `Controller state cannot be directly mutated; use 'update' method instead.`,\n    );\n  }\n\n  /**\n   * Updates controller state. Accepts a callback that is passed a draft copy\n   * of the controller state. If a value is returned, it is set as the new\n   * state. Otherwise, any changes made within that callback to the draft are\n   * applied to the controller state.\n   *\n   * @param callback - Callback for updating state, passed a draft state\n   * object. Return a new state object or mutate the draft to update state.\n   * @returns An object that has the next state, patches applied in the update and inverse patches to\n   * rollback the update.\n   */\n  protected update(callback: (state: Draft<S>) => void | S): {\n    nextState: S;\n    patches: Patch[];\n    inversePatches: Patch[];\n  } {\n    // We run into ts2589, \"infinite type depth\", if we don't cast\n    // produceWithPatches here.\n    const [nextState, patches, inversePatches] = (\n      produceWithPatches as unknown as (\n        state: S,\n        cb: typeof callback,\n      ) => [S, Patch[], Patch[]]\n    )(this.internalState, callback);\n\n    this.internalState = nextState;\n    this.messagingSystem.publish(\n      `${this.name}:stateChange` as Namespaced<N, any>,\n      nextState,\n      patches,\n    );\n\n    return { nextState, patches, inversePatches };\n  }\n\n  /**\n   * Applies immer patches to the current state. The patches come from the\n   * update function itself and can either be normal or inverse patches.\n   *\n   * @param patches - An array of immer patches that are to be applied to make\n   * or undo changes.\n   */\n  protected applyPatches(patches: Patch[]) {\n    const nextState = applyPatches(this.internalState, patches);\n    this.internalState = nextState;\n    this.messagingSystem.publish(\n      `${this.name}:stateChange` as Namespaced<N, any>,\n      nextState,\n      patches,\n    );\n  }\n\n  /**\n   * Prepares the controller for garbage collection. This should be extended\n   * by any subclasses to clean up any additional connections or events.\n   *\n   * The only cleanup performed here is to remove listeners. While technically\n   * this is not required to ensure this instance is garbage collected, it at\n   * least ensures this instance won't be responsible for preventing the\n   * listeners from being garbage collected.\n   */\n  protected destroy() {\n    this.messagingSystem.clearEventSubscriptions(\n      `${this.name}:stateChange` as Namespaced<N, any>,\n    );\n  }\n}\n\n/**\n * Returns an anonymized representation of the controller state.\n *\n * By \"anonymized\" we mean that it should not contain any information that could be personally\n * identifiable.\n *\n * @param state - The controller state.\n * @param metadata - The controller state metadata, which describes how to derive the\n * anonymized state.\n * @returns The anonymized controller state.\n */\nexport function getAnonymizedState<S extends Record<string, Json>>(\n  state: S,\n  metadata: StateMetadata<S>,\n): Record<string, Json> {\n  return deriveStateFromMetadata(state, metadata, 'anonymous');\n}\n\n/**\n * Returns the subset of state that should be persisted.\n *\n * @param state - The controller state.\n * @param metadata - The controller state metadata, which describes which pieces of state should be persisted.\n * @returns The subset of controller state that should be persisted.\n */\nexport function getPersistentState<S extends Record<string, Json>>(\n  state: S,\n  metadata: StateMetadata<S>,\n): Record<string, Json> {\n  return deriveStateFromMetadata(state, metadata, 'persist');\n}\n\n/**\n * Use the metadata to derive state according to the given metadata property.\n *\n * @param state - The full controller state.\n * @param metadata - The controller metadata.\n * @param metadataProperty - The metadata property to use to derive state.\n * @returns The metadata-derived controller state.\n */\nfunction deriveStateFromMetadata<S extends Record<string, Json>>(\n  state: S,\n  metadata: StateMetadata<S>,\n  metadataProperty: 'anonymous' | 'persist',\n): Record<string, Json> {\n  return Object.keys(state).reduce((persistedState, key) => {\n    try {\n      const stateMetadata = metadata[key as keyof S];\n      if (!stateMetadata) {\n        throw new Error(`No metadata found for '${key}'`);\n      }\n      const propertyMetadata = stateMetadata[metadataProperty];\n      const stateProperty = state[key];\n      if (typeof propertyMetadata === 'function') {\n        persistedState[key as string] = propertyMetadata(\n          stateProperty as S[keyof S],\n        );\n      } else if (propertyMetadata) {\n        persistedState[key as string] = stateProperty;\n      }\n      return persistedState;\n    } catch (error) {\n      // Throw error after timeout so that it is captured as a console error\n      // (and by Sentry) without interrupting state-related operations\n      setTimeout(() => {\n        throw error;\n      });\n      return persistedState;\n    }\n  }, {} as Record<string, Json>);\n}\n"]}

package/dist/ControllerMessenger.d.ts

@@ -0,0 +1,357 @@
+export declare type ActionHandler<Action, ActionType> = (...args: ExtractActionParameters<Action, ActionType>) => ExtractActionResponse<Action, ActionType>;
+export declare type ExtractActionParameters<Action, T> = Action extends {
+    type: T;
+    handler: (...args: infer H) => any;
+} ? H : never;
+export declare type ExtractActionResponse<Action, T> = Action extends {
+    type: T;
+    handler: (...args: any) => infer H;
+} ? H : never;
+export declare type ExtractEventHandler<Event, T> = Event extends {
+    type: T;
+    payload: infer P;
+} ? P extends unknown[] ? (...payload: P) => void : never : never;
+export declare type ExtractEventPayload<Event, T> = Event extends {
+    type: T;
+    payload: infer P;
+} ? P : never;
+export declare type GenericEventHandler = (...args: unknown[]) => void;
+export declare type SelectorFunction<Args extends unknown[], ReturnValue> = (...args: Args) => ReturnValue;
+export declare type SelectorEventHandler<SelectorReturnValue> = (newValue: SelectorReturnValue, previousValue: SelectorReturnValue | undefined) => void;
+export declare type ActionConstraint = {
+    type: string;
+    handler: (...args: any) => unknown;
+};
+export declare type EventConstraint = {
+    type: string;
+    payload: unknown[];
+};
+/**
+ * A namespaced string
+ *
+ * This type verifies that the string T is prefixed by the string Name followed by a colon.
+ *
+ * @template Name - The namespace we're checking for.
+ * @template T - The full string, including the namespace.
+ */
+export declare type Namespaced<Name extends string, T> = T extends `${Name}:${string}` ? T : never;
+declare type NarrowToNamespace<T, Namespace extends string> = T extends {
+    type: `${Namespace}:${string}`;
+} ? T : never;
+declare type NarrowToAllowed<T, Allowed extends string> = T extends {
+    type: Allowed;
+} ? T : never;
+/**
+ * A restricted controller messenger.
+ *
+ * This acts as a wrapper around the controller messenger instance that restricts access to actions
+ * and events.
+ *
+ * @template N - The namespace for this messenger. Typically this is the name of the controller or
+ * module that this messenger has been created for. The authority to publish events and register
+ * actions under this namespace is granted to this restricted messenger instance.
+ * @template Action - A type union of all Action types.
+ * @template Event - A type union of all Event types.
+ * @template AllowedAction - A type union of the 'type' string for any allowed actions.
+ * @template AllowedEvent - A type union of the 'type' string for any allowed events.
+ */
+export declare class RestrictedControllerMessenger<N extends string, Action extends ActionConstraint, Event extends EventConstraint, AllowedAction extends string, AllowedEvent extends string> {
+    private readonly controllerMessenger;
+    private readonly controllerName;
+    private readonly allowedActions;
+    private readonly allowedEvents;
+    /**
+     * Constructs a restricted controller messenger
+     *
+     * The provided allowlists grant the ability to call the listed actions and subscribe to the
+     * listed events. The "name" provided grants ownership of any actions and events under that
+     * namespace. Ownership allows registering actions and publishing events, as well as
+     * unregistering actions and clearing event subscriptions.
+     *
+     * @param options - The controller options.
+     * @param options.controllerMessenger - The controller messenger instance that is being wrapped.
+     * @param options.name - The name of the thing this messenger will be handed to (e.g. the
+     * controller name). This grants "ownership" of actions and events under this namespace to the
+     * restricted controller messenger returned.
+     * @param options.allowedActions - The list of actions that this restricted controller messenger
+     * should be alowed to call.
+     * @param options.allowedEvents - The list of events that this restricted controller messenger
+     * should be allowed to subscribe to.
+     */
+    constructor({ controllerMessenger, name, allowedActions, allowedEvents, }: {
+        controllerMessenger: ControllerMessenger<ActionConstraint, EventConstraint>;
+        name: N;
+        allowedActions?: AllowedAction[];
+        allowedEvents?: AllowedEvent[];
+    });
+    /**
+     * Register an action handler.
+     *
+     * This will make the registered function available to call via the `call` method.
+     *
+     * The action type this handler is registered under *must* be in the current namespace.
+     *
+     * @param action - The action type. This is a unqiue identifier for this action.
+     * @param handler - The action handler. This function gets called when the `call` method is
+     * invoked with the given action type.
+     * @throws Will throw when a handler has been registered for this action type already.
+     * @template T - A type union of Action type strings that are namespaced by N.
+     */
+    registerActionHandler<T extends Namespaced<N, Action['type']>>(action: T, handler: ActionHandler<Action, T>): void;
+    /**
+     * Unregister an action handler.
+     *
+     * This will prevent this action from being called.
+     *
+     * The action type being unregistered *must* be in the current namespace.
+     *
+     * @param action - The action type. This is a unqiue identifier for this action.
+     * @template T - A type union of Action type strings that are namespaced by N.
+     */
+    unregisterActionHandler<T extends Namespaced<N, Action['type']>>(action: T): void;
+    /**
+     * Call an action.
+     *
+     * This function will call the action handler corresponding to the given action type, passing
+     * along any parameters given.
+     *
+     * The action type being called must be on the action allowlist.
+     *
+     * @param action - The action type. This is a unqiue identifier for this action.
+     * @param params - The action parameters. These must match the type of the parameters of the
+     * registered action handler.
+     * @throws Will throw when no handler has been registered for the given type.
+     * @template T - A type union of allowed Action type strings.
+     * @returns The action return value.
+     */
+    call<T extends AllowedAction & string>(action: T, ...params: ExtractActionParameters<Action, T>): ExtractActionResponse<Action, T>;
+    /**
+     * Publish an event.
+     *
+     * Publishes the given payload to all subscribers of the given event type.
+     *
+     * The event type being published *must* be in the current namespace.
+     *
+     * @param event - The event type. This is a unique identifier for this event.
+     * @param payload - The event payload. The type of the parameters for each event handler must
+     * match the type of this payload.
+     * @template E - A type union of Event type strings that are namespaced by N.
+     */
+    publish<E extends Namespaced<N, Event['type']>>(event: E, ...payload: ExtractEventPayload<Event, E>): void;
+    /**
+     * Subscribe to an event.
+     *
+     * Registers the given function as an event handler for the given event type.
+     *
+     * The event type being subscribed to must be on the event allowlist.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @param handler - The event handler. The type of the parameters for this event handler must
+     * match the type of the payload for this event type.
+     * @template E - A type union of Event type strings.
+     */
+    subscribe<E extends AllowedEvent & string>(eventType: E, handler: ExtractEventHandler<Event, E>): void;
+    /**
+     * Subscribe to an event, with a selector.
+     *
+     * Registers the given handler function as an event handler for the given
+     * event type. When an event is published, its payload is first passed to the
+     * selector. The event handler is only called if the selector's return value
+     * differs from its last known return value.
+     *
+     * The event type being subscribed to must be on the event allowlist.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @param handler - The event handler. The type of the parameters for this event
+     * handler must match the return type of the selector.
+     * @param selector - The selector function used to select relevant data from
+     * the event payload. The type of the parameters for this selector must match
+     * the type of the payload for this event type.
+     * @template E - A type union of Event type strings.
+     * @template V - The selector return value.
+     */
+    subscribe<E extends AllowedEvent & string, V>(eventType: E, handler: SelectorEventHandler<V>, selector: SelectorFunction<ExtractEventPayload<Event, E>, V>): void;
+    /**
+     * Unsubscribe from an event.
+     *
+     * Unregisters the given function as an event handler for the given event.
+     *
+     * The event type being unsubscribed to must be on the event allowlist.
+     *
+     * @param event - The event type. This is a unique identifier for this event.
+     * @param handler - The event handler to unregister.
+     * @throws Will throw when the given event handler is not registered for this event.
+     * @template T - A type union of allowed Event type strings.
+     */
+    unsubscribe<E extends AllowedEvent & string>(event: E, handler: ExtractEventHandler<Event, E>): void;
+    /**
+     * Clear subscriptions for a specific event.
+     *
+     * This will remove all subscribed handlers for this event.
+     *
+     * The event type being cleared *must* be in the current namespace.
+     *
+     * @param event - The event type. This is a unique identifier for this event.
+     * @template E - A type union of Event type strings that are namespaced by N.
+     */
+    clearEventSubscriptions<E extends Namespaced<N, Event['type']>>(event: E): void;
+}
+/**
+ * A messaging system for controllers.
+ *
+ * The controller messenger allows registering functions as 'actions' that can be called elsewhere,
+ * and it allows publishing and subscribing to events. Both actions and events are identified by
+ * unique strings.
+ *
+ * @template Action - A type union of all Action types.
+ * @template Event - A type union of all Event types.
+ */
+export declare class ControllerMessenger<Action extends ActionConstraint, Event extends EventConstraint> {
+    private readonly actions;
+    private readonly events;
+    /**
+     * A cache of selector return values for their respective handlers.
+     */
+    private readonly eventPayloadCache;
+    /**
+     * Register an action handler.
+     *
+     * This will make the registered function available to call via the `call` method.
+     *
+     * @param actionType - The action type. This is a unqiue identifier for this action.
+     * @param handler - The action handler. This function gets called when the `call` method is
+     * invoked with the given action type.
+     * @throws Will throw when a handler has been registered for this action type already.
+     * @template T - A type union of Action type strings.
+     */
+    registerActionHandler<T extends Action['type']>(actionType: T, handler: ActionHandler<Action, T>): void;
+    /**
+     * Unregister an action handler.
+     *
+     * This will prevent this action from being called.
+     *
+     * @param actionType - The action type. This is a unqiue identifier for this action.
+     * @template T - A type union of Action type strings.
+     */
+    unregisterActionHandler<T extends Action['type']>(actionType: T): void;
+    /**
+     * Unregister all action handlers.
+     *
+     * This prevents all actions from being called.
+     */
+    clearActions(): void;
+    /**
+     * Call an action.
+     *
+     * This function will call the action handler corresponding to the given action type, passing
+     * along any parameters given.
+     *
+     * @param actionType - The action type. This is a unqiue identifier for this action.
+     * @param params - The action parameters. These must match the type of the parameters of the
+     * registered action handler.
+     * @throws Will throw when no handler has been registered for the given type.
+     * @template T - A type union of Action type strings.
+     * @returns The action return value.
+     */
+    call<T extends Action['type']>(actionType: T, ...params: ExtractActionParameters<Action, T>): ExtractActionResponse<Action, T>;
+    /**
+     * Publish an event.
+     *
+     * Publishes the given payload to all subscribers of the given event type.
+     *
+     * Note that this method should never throw directly. Any errors from
+     * subscribers are captured and re-thrown in a timeout handler.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @param payload - The event payload. The type of the parameters for each event handler must
+     * match the type of this payload.
+     * @template E - A type union of Event type strings.
+     */
+    publish<E extends Event['type']>(eventType: E, ...payload: ExtractEventPayload<Event, E>): void;
+    /**
+     * Subscribe to an event.
+     *
+     * Registers the given function as an event handler for the given event type.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @param handler - The event handler. The type of the parameters for this event handler must
+     * match the type of the payload for this event type.
+     * @template E - A type union of Event type strings.
+     */
+    subscribe<E extends Event['type']>(eventType: E, handler: ExtractEventHandler<Event, E>): void;
+    /**
+     * Subscribe to an event, with a selector.
+     *
+     * Registers the given handler function as an event handler for the given
+     * event type. When an event is published, its payload is first passed to the
+     * selector. The event handler is only called if the selector's return value
+     * differs from its last known return value.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @param handler - The event handler. The type of the parameters for this event
+     * handler must match the return type of the selector.
+     * @param selector - The selector function used to select relevant data from
+     * the event payload. The type of the parameters for this selector must match
+     * the type of the payload for this event type.
+     * @template E - A type union of Event type strings.
+     * @template V - The selector return value.
+     */
+    subscribe<E extends Event['type'], V>(eventType: E, handler: SelectorEventHandler<V>, selector: SelectorFunction<ExtractEventPayload<Event, E>, V>): void;
+    /**
+     * Unsubscribe from an event.
+     *
+     * Unregisters the given function as an event handler for the given event.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @param handler - The event handler to unregister.
+     * @throws Will throw when the given event handler is not registered for this event.
+     * @template E - A type union of Event type strings.
+     */
+    unsubscribe<E extends Event['type']>(eventType: E, handler: ExtractEventHandler<Event, E>): void;
+    /**
+     * Clear subscriptions for a specific event.
+     *
+     * This will remove all subscribed handlers for this event.
+     *
+     * @param eventType - The event type. This is a unique identifier for this event.
+     * @template E - A type union of Event type strings.
+     */
+    clearEventSubscriptions<E extends Event['type']>(eventType: E): void;
+    /**
+     * Clear all subscriptions.
+     *
+     * This will remove all subscribed handlers for all events.
+     */
+    clearSubscriptions(): void;
+    /**
+     * Get a restricted controller messenger
+     *
+     * Returns a wrapper around the controller messenger instance that restricts access to actions
+     * and events. The provided allowlists grant the ability to call the listed actions and subscribe
+     * to the listed events. The "name" provided grants ownership of any actions and events under
+     * that namespace. Ownership allows registering actions and publishing events, as well as
+     * unregistering actions and clearing event subscriptions.
+     *
+     * @param options - Controller messenger options.
+     * @param options.name - The name of the thing this messenger will be handed to (e.g. the
+     * controller name). This grants "ownership" of actions and events under this namespace to the
+     * restricted controller messenger returned.
+     * @param options.allowedActions - The list of actions that this restricted controller messenger
+     * should be alowed to call.
+     * @param options.allowedEvents - The list of events that this restricted controller messenger
+     * should be allowed to subscribe to.
+     * @template N - The namespace for this messenger. Typically this is the name of the controller or
+     * module that this messenger has been created for. The authority to publish events and register
+     * actions under this namespace is granted to this restricted messenger instance.
+     * @template AllowedAction - A type union of the 'type' string for any allowed actions.
+     * @template AllowedEvent - A type union of the 'type' string for any allowed events.
+     * @returns The restricted controller messenger.
+     */
+    getRestricted<N extends string, AllowedAction extends string, AllowedEvent extends string>({ name, allowedActions, allowedEvents, }: {
+        name: N;
+        allowedActions?: Extract<Action['type'], AllowedAction>[];
+        allowedEvents?: Extract<Event['type'], AllowedEvent>[];
+    }): RestrictedControllerMessenger<N, NarrowToNamespace<Action, N> | NarrowToAllowed<Action, AllowedAction>, NarrowToNamespace<Event, N> | NarrowToAllowed<Event, AllowedEvent>, AllowedAction, AllowedEvent>;
+}
+export {};
+//# sourceMappingURL=ControllerMessenger.d.ts.map

package/dist/ControllerMessenger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ControllerMessenger.d.ts","sourceRoot":"","sources":["../src/ControllerMessenger.ts"],"names":[],"mappings":"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"}