New Interactivity store() API proposal

[luisherranz]

When we started with the idea that eventually became the Interactivity API, we didn’t pay much attention to the Store’s API because it wasn’t part of the problem we were trying to solve, so there was no need to spend more time on it than necessary. At that time, we simply adopted the Frontity framework model because we knew it worked fine and it allowed us to keep testing the rest of the things.

Now that the proposal is out and there's a chance that the Interactivity API will get merged in WordPress Core, it’s time to reconsider every part of the system, specifically the Store’s API because the requirements of the Interactivity API are not the same than the ones that Frontity framework had. I’ve been thinking about it for the past few weeks. Last week the pieces finally started to fit together in my head, and I believe there’s a promising alternative API that fits better the Interactivity API requirements than the current API. Last Thursday, I explained it to @DAreRodz and after a thorough review, we believe it can work.

Requirements

These are some of the requirements I had in mind.

• There should be as little boilerplate as possible

• TypeScript: Typed stores should be as easy as writing plain JavaScript objects

• TypeScript: Using stores from external namespaces should automatically import their types

• Still, stores should be able to be divided into different parts and each block should load only the parts that it is interested in

• Stores should be able to dynamically import logic when that logic might not be needed at startup

• Consumers should not be able to distinguish between derived state and non-derived state to make refactorings of public APIs easier

• Private stores should be easily isolated from other stores

Proposal

This proposal is written from the perspective of the existing Store's API, highlighting what changes are necessary. Please bear in mind when reading.

The default namespace is stored in data-wp-interactive

We can use data-wp-interactive to store the default namespace of a block.

<div data-wp-interactive='{ "namespace": "myPlugin" }'>
  <div data-wp-context='{ "isOpen": false }'>
    <span data-wp-bind--hidden="context.isOpen">Hi there 👋</span>
  </div>
</div>

In this example, both wp-context and wp-bind point to a namespace called myPlugin.

The namespace could be defined in the block.json:

{
  "supports": {
    "interactivity": {
      "namespace": "myPlugin"
    }
  }
}

If it's not present, we can infer the namespace from the block type:

{
  "name": "myPlugin/myBlock" // namespace -> "myPlugin"
}

In the server:

• For simplicity, we could use the value definied in the block.json for the entire block.
• Or we could replicate the runtime behavior and create a stack of data-wp-interactive directives to keep track of the current default namespace.

As of today, I'm more in favor of using the block.json value for the entire block, and preventing people from populating data-wp-interactive manually.

The namespace is passed as a string during store creation

Instead of using the namespace inside the object, namespaces are passed as strings to the store() call:

store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction: () => {
      // ...
    },
  },
});

Stores return stable references to their properties

On store creation, stores return themselves, generating stable references that can be used to interact with the store, and therefore not require the store injection via arguments.

const { state, actions } = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    action1: (/* nothing is injected */) => {
      // Read state using the `state` reference returned by `store()`.
      state.someValue;
    },
    action2: (/* nothing is injected */) => {
      // Call action1 using the `actions` reference returned by `store()`.
      actions.action1();
    },
  },
});

External stores can be accessed using the same API

When you need to access a different store, you can use the same API to get stable references to the properties of that store.

const otherPlugin = store("otherPlugin");

const { state, actions } = store("myPlugin", {
  state: {
    // ...
  },
  actions: {
    someAction: (/* nothing is injected */) => {
      // Call an action or read/mutate state from another store.
      otherPlugin.state.someValue;
      otherPlugin.actions.someAction();
    },
  },
});

You could also destructure the store, but usually you'll have to change the names of the properties to avoid collisions with your own store.

const { state: otherState, actions: otherActions } = store("otherPlugin");

const { state, actions } = store("myPlugin", {
  state: {
    // ...
  },
  actions: {
    someAction: (/* nothing is injected */) => {
      // Call an action or read/mutate state from another store.
      otherState.someValue;
      otherActions.someAction();
    },
  },
});

Multiple parts of the same store can be defined in different files

Stores can still be merged together from different files/parts.

const { state, actions } = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction: () => {
      // `state` and `actions` contain the full store added to "myPlugin" so far.
      state.otherValue === "other value"; // true
      actions.otherAction();
    },
  },
});

const { state, actions } = store("myPlugin", {
  state: {
    otherValue: "other value",
  },
  actions: {
    otherAction: () => {
      // ...
    },
  },
});

Objects returned by store() are typed

In TypeScript, we can make functions that return the same type that was passed. That means that the store returned by store() can be typed with the same type that you inject, even if it's an inferred type.

const { state, actions } = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    action1: () => {
      // TypeScript knows about `state.someValue`
      state.someValue; // inferred type: string
    },
    action2: () => {
      // TypeScript knows about `actions.action1` and `actions.action2`
      actions.action1(); // inferred type: () => void
    },
  },
});

Unfortunately, there's no way in TypeScript to merge and return the types of different calls to store().

store("myPlugin", {
  state: {
    otherValue: "other value",
  },
  actions: {
    otherAction: () => {
      // ...
    },
  },
});

const { state, actions } = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction: () => {
      // TypeScript knows about `state.someValue`, but it doesn't know about `state.otherValue`
      state.otherValue; // type: undefined
    },
  },
});

So whenever more than one store part is used, types need to be defined separately and passed manually.

import type { StorePart2 } from "./store-part2";

const storePart1 = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction: () => {
      state.otherValue; // type: string
      actions.otherAction(); // type: () => void
    },
  },
});

const { state, actions } = store<StorePart1 & StorePart2>("myPlugin");

// Export the inferred type to use it in other parts.
export type StorePart1 = typeof storePart1;

import type { StorePart1 } from "./store-part1";

const storePart2 = store("myPlugin", {
  state: {
    otherValue: "some value",
  },
  actions: {
    otherAction: () => {
      state.someValue; // type: string
      actions.someAction(); // type: () => void
    },
  },
});

const { state, actions } = store<StorePart1 & StorePart2>("myPlugin");

// Export the inferred type to use it in other parts.
export type StorePart2 = typeof storePart2;

For convenience, types can be combined in a centralized file.

// types.ts
import type { StorePart1 } from "./store-part1";
import type { StorePart2 } from "./store-part2";

type Store = StorePart1 & StorePart2;

export default Store;

import type { Store } from "./types";

const storePart1 = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction: () => {
      state.otherValue; // type: string
      actions.otherAction(); // type: () => void
    },
  },
});

const { state, actions } = store<Store>("myPlugin");

// Export the inferred type to use it in other parts.
export type StorePart1 = typeof storePart1;

If external store parts might not always be imported when another part is loaded, they can be made optional:

const storePart1 = store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction: () => {
      state.otherValue; // type: string | undefined
      actions.otherAction?.(); // type: () => void | undefined
    },
  },
});

const { state, actions } = store<StorePart1 & Optional<StorePart2>>("myPlugin");

Optional would be a TS utility like this.

type Optional<T> = T extends Function
  ? T
  : T extends object
  ? { [P in keyof T]?: Optional<T[P]> }
  : T;

Full examples of these types in action in Stackblitz and the TypeScript playground (with optional parts)

External consumers can import a typed store

When you want to expose your store to third-party developers, they should import it with types and ready to be used, just like any other JavaScript library.

Instead of using store("otherPlugin") like this:

const { state: otherState, actions: otherActions } = store("otherPlugin");

const { actions } = store("myPlugin", {
  actions: {
    someAction: () => {
      otherState.otherValue; // This is not typed
      otherActions.otherAction(); // This is not typed
    },
  },
});

They should be able to use import and get the store directly from another module.

// This is assumming "other-plugin" is the WP handle used by the external plugin
// and we use a system like import maps to manage the imports.
import { state as otherState, actions as otherActions } from "other-plugin";

const { actions } = store("myPlugin", {
  actions: {
    someAction: () => {
      otherState.otherValue; // This is properly typed
      otherActions.otherAction(); // This is properly typed
    },
  },
});

To make this work, the exporter needs to export its own store with the correct types.

// File enqueued by the "other-plugin" handle.
import Store from "./types";

// Import the different parts.
import "./store-part-1.ts";
import "./store-part-2.ts";

// The injection of types happens here, so the consumers don't need to do it themselves.
export default store<Store>("otherPlugin");

That's it. As long as the export is typed and the tsconfig.json configuration is correct, other plugins should be able to import the store already typed and ready to be used.

Contextual values like context or ref should be accessed inside the functions

In order to avoid the need to inject anything into actions or selectors (derived state), contextual values (those that depend on where in the HTML tree the logic is executed) should be able to be accessed inside functions.

Instead of this:

store({
  actions: {
    someAction: ({ ref }) => {
      ref.focus();
    },
  },
});

We could do this:

store("myPlugin", {
  actions: {
    someAction: () => {
      const ref = getRef();
      ref.focus();
    },
  },
});

Same API for context:

store("myPlugin", {
  actions: {
    someAction: () => {
      const context = getContext();
      context.someValue;
    },
  },
});

Or even:

store("myPlugin", {
  actions: {
    someAction: () => {
      const { someValue } = getContext();
    },
  },
});

In a way, I think that it'll be easy to make a mental connection of getRef or getContext with the use of useRef and useContext hooks, so I think they should not be hard to learn. Also, implicitly calling getContext might help us remove some unnecessary calls to useContext on some of the directives.

Actions are just regular JavaScript functions

Liberating actions from store or contextual value injections enables a few things:

• Actions can now be called directly (like actions.someAction()) without having to worry about passing the store or the context to them.

• The type of those actions will usually be inferred automatically by TypeScript.

• It's easier to add regular arguments to the functions, for example:

  const { state, actions } = store("myPlugin", {
    actions: {
      selectItem: (id?: number) => {
        const context = getContext();
        // `id` is optional here, so this action can be used in a directive.
        state.selected = id || context.id;
      }
      otherAction: () => {
        // but it can also be called from other actions.
        actions.selectItem(123); // it works and type is correct
      }
    }
  })

Derived state (selectors) can use getters

In the same way that liberating actions has benefits, liberating selectors from store or contextual value injections enables a few things. First, they can start using getters.

Instead of this:

store({
  state: {
    someNumber: 1,
  },
  selectors: {
    sumNumbers: ({ state, context }) => {
      return state.someNumber + context.someNumber;
    },
  },
  actions: {
    someAction: (store) => {
      const { selectors } = store;
      selectors.sumNumbers(store);
    },
  },
});

We can do this:

const { selectors } = store("myPlugin", {
  state: {
    someNumber: 1,
  },
  selectors: {
    get sumNumbers(): number {
      const { someNumber } = getContext();
      return state.someNumber + someNumber;
    },
  },
  actions: {
    someAction: () => {
      selectors.sumNumbers; // type: number
    },
  },
});

Also, by adopting getters, deepsignal will convert them to computed signals, with the added reactivity benefits (vDOM bypass, correct execution order to avoid instable states…).

Derived state (selectors) can be moved back to state

But we can also merge selectors back into state. Refactorings of state -> selectors can be problematic in public stores, so we should aim to make state and derived state indistinguishable from each other.

For example, imagine that in this store:

store("myPlugin", {
  state: {
    someValue: "some value",
  },
});

state.someValue needs to be refactored into a derived state:

const { state } = store("myPlugin", {
  state: {
    some: "some",
    value: "value",
  },
  selectors: {
    get someValue() {
      return `${state.some} ${state.value}`;
    },
  },
});

The public API would change from state.someValue to selectors.someValue.

For that reason, I think we should promote the use of state also for derived state:

const { state } = store("myPlugin", {
  state: {
    some: "some",
    value: "value",
    get someValue() {
      return `${state.some} ${state.value}`;
    },
  },
});

The public API was state.someValue and continues being state.someValue even if the value is now derived.

• Previously this didn't make sense because we could not use getters and therefore there was another change from real values to derived -> state.someValue (real) state.someValue(store) (derived).
• A similar thing happens for refactorings between context -> selectors, but I'm less sure that this pattern will be adopted because it would mean one extra getter for each context property. For plugins with very sensitive public APIs, it might make sense. But for small plugins maybe the extra boilerplate is not worth the effort.

Defining the initial state in the server

If we move the derived state to the state property, there's no need to use the long wp_store format anymore: the state property can be absorbed in the function name (wp_initial_state) and the namespace can be passed as a string.

Instead of this:

wp_store( array(
  'state' => array(
    'myPlugin' => array(
      'someValue'  => 'some value',
      'someNumber' => 123,
    ),
  ),
  'selectors' => array(
    'myPlugin' => array(
      'someDerivedValue' => 'some derived value',
    ),
  ),
) );

We can write this and it will have the same information:

wp_initial_state( 'myPlugin', array(
  'someValue'        => 'some value',
  'someNumber'       => 123,
  'someDerivedValue' => 'some derived value',
) );

Types from the initial server state

The types of the state defined in the server can't be inferred in TypeScript because they are defined in PHP. For that case, they can be added to the Store definition manually:

wp_initial_state( 'myPlugin', array(
  'someValue'        => 'some value',
  'someNumber'       => 123,
  'someDerivedValue' => 'some derived value',
) );

import type { StorePart1 } from "./store-part1";
import type { StorePart2 } from "./store-part2";

type InitialState = {
  state: {
    someValue: string;
    someNumber: number;
  };
};

type Store = StorePart1 & StorePart2 & InitialState;

export default Store;

Types are not required for the derived state because it already has a representation in the client and therefore it should be already typed.

Accessing other namespaces in the directives

Accessing other namespaces is also possible when using directives. My proposal is to use the following syntax:

<div data-wp-interactive='{ "namespace": "myPlugin" }'>
  <span data-wp-bind--hidden="state.isOpen">
    I'm using the default namespace ("myPlugin")
  </span>
  <span data-wp-bind--hidden="otherPlugin::state.isOpen">
    I'm using the "otherPlugin" namespace
  </span>
</div>

I also like the idea that deviating a little bit from the illusion that what people write in the attribute value is regular JavaScript will help decrease confusion and misunderstandings, but still keeping a syntax familiar enough that is still easy to learn.

Creating and accessing context from other namespaces in the directives

Creating and accessing context from other namespaces would use the same "namespace::" syntax:

<div data-wp-interactive='{ "namespace": "myPlugin" }'>
  <span
    data-wp-context='{ "isOpen": true }'
    data-wp-bind--hidden="context.isOpen"
  >
    I'm using the default namespace ("myPlugin")
  </span>
  <span
    data-wp-context='otherPlugin::{ "isOpen": true }'
    data-wp-bind--hidden="otherPlugin::context.isOpen"
  >
    I'm using the "otherPlugin" namespace
  </span>
</div>

Accessing context from other namespaces in the store

The getContext method used inside the store is hooked to the default namespace of that store.

store("myPlugin", {
  state: {
    get someValue() {
      const context = getContext(); // Hooked to "myPlugin"
      return context.someValue;
    }
  }
  actions: {
    someAction: () => {
      const context = getContext(); // Hooked to "myPlugin"
    }
  }
});

If you call that action or state from another store, it will still access the namespace of the original store:

const myPlugin = store("myPlugin");

store("otherPlugin", {
  actions: {
    otherAction: () => {
      myPlugin.state.someValue; // runs using "myPlugin" context internally
      myPlugin.action.someAction(); // runs using "myPlugin" context internally
    },
  },
});

It's important to differentiate between:

• Default namespace: it depends on the store you are running.
• Scope: it depends on where in the HTML tree is the directive that started the execution located.

Scope influences the element that is returned by getRef, or the specific merge of context objects returned by getContext. It doesn't change in respect of how it works today.

You can access the context of another namespace in a store by passing the namespace to the getContext function.

store("myPlugin", {
  actions: {
    someAction: () => {
      const myContext = getContext();
      const otherContext = getContext("otherPlugin");
    },
  },
});

Typing contexts

As context is defined in PHP, manual typing is required.

Plugins can export the type to be applied manually to getContext.

<div data-wp-context='{ "isOpen": true }'>
  ...
</div>

// types.ts
export type SomeContext = {
  isOpen: boolean;
};

import type { SomeContext } from "./types";

store("myPlugin", {
  actions: {
    someAction: () => {
      const context = getContext<SomeContext>(); // typed
    },
  },
});

Or they could export a typed custom getContext function, whatever they prefer.

// contexts.ts
export const getSomeContext = getContext<{ isOpen: boolean }>;

import { getSomeContext } from "./contexts";

store("myPlugin", {
  actions: {
    someAction: () => {
      const context = getSomeContext(); // typed
    },
  },
});

TS playground example

Async Actions should use generators instead of async/await

To liberate actions and selectors from store injection, there's one caveat: actions should use generators instead of async/await.

In the past, I've fought a lot against ditching async/await and we were able to create an API for Frontity framework that worked with async/await beautifully. But here the gains of liberating actions and selectors from store injection outweigh the cost of writing function* instead of async () and yield instead of await.

The problem is that, in async functions, the control is passed to the function itself. The caller of the function has no way to know if the function is awaiting, and more importantly, if the await is resolved and the function has resumed execution. We need that information to be able to restore the scope.

Imagine a block that has two buttons. One lives inside a context that has isOpen: true and the other isOpen: false:

<div data-wp-context='{ "isOpen": true }'>
  <button data-wp-on--click="actions.someAction">Click</button>
</div>

<div data-wp-context='{ "isOpen": false }'>
  <button data-wp-on--click="actions.someAction">Click</button>
</div>

The action is async and needs to await a long delay.

store("myPlugin", {
  state: {
    get isOpen() {
      return getContext().isOpen;
    },
  },
  actions: {
    someAction: async () => {
      state.isOpen; // This context is always correct because it's synchronous.
      await longDelay();
      state.isOpen; // This may not get the proper context unless we "restore" it.
    },
  },
});

• The user clicks the first button.
• The scope points to the first context, where isOpen: true.
• The first access to state.isOpen is correct because getContext returns the current scope.
• The action starts awaiting a long delay.
• Before the action resumes, the user clicks the second button.
• The scope is changed to the second context, where isOpen: false.
• The first access to state.isOpen is correct because getContext returns the current scope.
• The second action starts awaiting a long delay.
• The first action finishes awaiting and resumes its execution.
• The second access to state.isOpen of the first action is incorrect, because getContext now returns the wrong scope.

We need to be able to know when async actions start awaiting and resume operations, so we can restore the proper scope, and that's what generators do. The previous store would work fine if it'd have been written like this:

store("myPlugin", {
  state: {
    get isOpen() {
      return getContext().isOpen;
    },
  },
  actions: {
    someAction: function* () {
      state.isOpen; // This context is correct because it's synchronous.
      yield longDelay(); // With generators, the caller controls when to resume this function.
      state.isOpen; // This context is correct because we restored the proper scope before we resumed the function.
    },
  },
});

In a way, it's the same problem that prevents (P)React/Vue components to support async/await because if they would do, they won't be able to recover the state of their hooks after an await.

There's an alternative API, which would be to wrap all the await calls in a utility function, like this:

store("myPlugin", {
  state: {
    get isOpen() {
      return getContext().isOpen;
    },
  },
  actions: {
    someAction: async () => {
      state.isOpen; // This context is correct because it's synchronous.
      await resume(longDelay());
      state.isOpen; // This context is correct because we restored the proper scope when longDelay resolved.
    },
  },
});

But I think it's easier to forget to use resume() in all your await calls than to use generators on all your async methods.

Stores should be able to import logic dynamically

When store parts are imported asynchronously, they are also added to the same store references and can be accessed normally. That means that stores can import other parts that they need.

// This file is not loaded at the beginning.
store("otherPlugin", {
  state: {
    otherValue: "other value",
  },
  actions: {
    otherAction: () => {
      // ...
    },
  },
});

const { state, actions } = store("myPlugin", {
  actions: {
    someAction: function* () {
      // This is assumming "other-plugin" is the WP handle used by the external
      // plugin and we use a system like import maps to manage the imports.
      yield import("other-store");
      // It can access their part now.
      state.otherValue === "other value"; // true
      actions.otherAction();
    },
  },
});

This method works great because import() won't do anything if "other-store" has already been imported, no matter if it was from a previous call to this action, another action, or from a block of other-store that required it. It just ensures that it is loaded at the time the action wants to access the other store.

Stores should be able to build façades of their public APIs

This method can also be useful to expose a public façade that contains the skeleton of the full public API, but it doesn't need to contain all the code of the full store.

Imagine a store with these two parts:

// store-part-1.ts
store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction1: () => {
      // ...
    },
  },
});

// store-part-2.ts
store("myPlugin", {
  state: {
    someValue: "some value",
  },
  actions: {
    someAction2: () => {
      // ...
    },
  },
});

If this plugin wants to expose a public API that other plugins can use, but it doesn't know how many actions the plugins will use, it can build a façade that only contains the skeleton of the store and imports the actions on demand.

// exported as "my-plugin" handle
const { actions } = store("myPlugin", {
  actions: {
    someAction1: function* (...args) {
      // First import the real action.
      yield import("./store-part-1.ts");
      // Then, call itself again.
      return action.someAction1(...args);
    },
    someAction2: function* (...args) {
      // First import the real action.
      yield import("./store-part-2.ts");
      // Then, call itself again.
      return action.someAction2(...args);
    },
  },
});

import { actions as myPluginActions } from "my-plugin";

store("otherPlugin", {
  actions: {
    otherAction: function* () {
      yield myPluginActions.someAction1();
      state.someValue;
    },
  },
});

Calling the action for the first time will be slightly slower, but this way only actions that are actually used (and their required store parts) are downloaded and executed.

The only requirement for this method is that all actions should be asynchronous by default, and plugins need to await (yield) when they call them if they need to access any modified state from that store after the action execution.

The same method can be applied to derived state, only that derived state needs to be asynchronous so the first time will need to return some temporary value.

store("myPlugin", {
  state: {
    get someDynamicValue() {
      import("./store-dyamic-part.ts");
      return "temporary value until the dynamic state is loaded";
    },
  },
});

Once the store-dynamic-part.ts file is loaded, their call to store() will replace state.someDynamicValue with the real logic, and the directives/effects that depend on it will be reloaded again.

// some-dynamic-part.ts
store("myPlugin", {
  state: {
    get someDynamicValue() {
      // Run some very complex logic.
      return "final value";
    },
  },
});

Private stores

This new API also works better with my last idea for private stores because each store is its own object and therefore it's easy to be protected with a Proxy, like the method used in the private-apis package.

For plugins with single file stores, its usage is very straightforward because the private store returns the store references:

const { state, actions } = privateStore("myPrivatePlugin", {
  state: {
    somePrivateValue: "some private value",
  },
  actions: {
    somePrivateAction: () => {
      state.somePrivateValue;
    },
  },
});

However, the protection is that privateStore() can only be called once for the same private namespace or it will throw. Plugins with multiple store parts can get a hash that allows executing privateStore multiple times for the same store.

// private-store.ts
export const { unlock } = privateStore("myPrivatePlugin");

// store-part-1.ts
import { unlock } from "./private-store.ts";

const { state, actions } = privateStore(
  "myPrivatePlugin",
  {
    // state, actions of this part...
  },
  { unlock }
);

// store-part-2.ts
import { unlock } from "./private-store.ts";

const { state, actions } = privateStore(
  "myPrivatePlugin",
  {
    // state, actions of this part...
  },
  { unlock }
);

Passing the unlock hash prevents privateStore from throwing and the hash cannot be accessed externally, so it's safe.

If an external plugin wants to access the "myPrivatePlugin" store, it needs to sign the call to privateStore to prevent it from throwing:

const myPrivatePlugin = store("myPrivatePlugin", null, {
  unlock:
    "I know using a private store means my plugin will inevitably break on the next store release.",
});

store("otherPlugin", {
  actions: {
    otherAction: () => {
      myPrivatePlugin.state.someValue; // unlocked
      myPrivatePlugin.actions.someAction(); // unlocked
    },
  },
});

Private stores should not be accessed unless people are testing/experimenting so not having the option to import them already typed using import should not be a problem.

For discussions about this API, please refer to the original discussion.

---

My next step is to try to build a prototype with this new API and see if all the pieces work fine or if I'm still missing something.

[juanmaguitar]

I think these changes provide a better Developer Experience with the Interactivity API 👍
The only part that I think is not smooth in terms of Developer Experience is the part that "forces" the developer to use generators instead of async/await for async actions. But it seems this has performance and error-proof advantages so this change is justified and if properly explained developers will come on board with this IMHO.

[luisherranz]

Thanks for the review, Juanma 🙂

Yeah, I think people will complain about that one. But there's no other way around it if we want to be able to recover the scope between asynchronous calls. Well, there's the await resume(); trick, but I think it's worse in terms of UX. We can release both APIs, but treat the resume() one as an exception when using generators is not possible.

[gigitux]

Great work!

I think these changes provide a better Developer Experience with the Interactivity API 👍
The only part that I think is not smooth in terms of Developer Experience is the part that "forces" the developer to use generators instead of async/await for async actions. But it seems this has performance and error-proof advantages so this change is justified and if properly explained developers will come on board with this IMHO.

I had the same thought. For newcomers, it could be tricky use generators instead of async/await. I agree that we should support both approaches (await resume() trick). Regarding:

But I think it's easier to forget to use resume() in all your await calls than to use generators on all your async methods.

I think that we could write a ESLint rule to catch this and improve the DX!

[luisherranz]

For newcomers, it could be tricky to use generators instead of async/await.

Yeah. I think the most critical point we should make is that there is no difference between them except for the syntax. That is, the Interactivity API converts them into asynchronous functions, so you don't need to learn how to use generators at all.

[SantosGuillamot]

Thanks a lot for the highly detailed explanation 🙂 It's easier to understand the implications with its pros and cons.

I'm in favor of something like this. I agree that the developer experience looks better. There seem to be fewer concepts, and repeating the namespace for all the directives is a bit tiresome. Actually, I usually miss it while working on new blocks 😅 . I also agree that the most confusing part for me would be not using async/await, but maybe it is just because it is what I'm used to.

I still have to process all the information, but I have some initial questions:

As of today, I'm more in favor of using the block.json value for the entire block, and preventing people from populating data-wp-interactive manually.

When you say this, you mean that block developers would just use data-wp-interactive instead of data-wp-interactive='{ "namespace": "myPlugin" }', and the namespace would be populated using the block.json?

---

In the past, it was discussed the possibility of exposing some parts, like state.router.url, in the store: link. I assume that could be possible with this approach, right? Would they be under a core namespace (for example) and be used as any other namespace?

---

One thing I was wondering is how does this affect extensions that modify the HTML. Imagine I have this HTML:

<div
  data-wp-interactive='{ "namespace": "myPlugin" }'
  data-wp-context='{ "isOpen": true }'
>
  <span data-wp-bind--hidden="context.isOpen">
    I'm using the default namespace ("myPlugin")
  </span>
</div>

And another plugin (extension) change it to be something like this:

<div
  data-wp-interactive='{ "namespace": "myPlugin" }'
  data-wp-context='{ "isOpen": true }'
>
  <div
    data-wp-interactive='{ "namespace": "myExtension" }'
    data-wp-context='{ "extensionText": "Text with extension namespace" }'
  >
    <span data-wp-bind--hidden="context.isOpen">
      Hello world!
    </span>
    <span data-wp-text="context.extensionText></span>
  </div>
</div>

Would context.extensionText and context.myPlugin work as expected? If context.myPlugin is not part of the most immediate namespace (myExtension), is it smart enough to look in the parent one?

[luisherranz]

Thanks, Mario. Great points.

When you say this, you mean that block developers would just use data-wp-interactive instead of data-wp-interactive='{ "namespace": "myPlugin" }', and the namespace would be populated using the block.json?

No. If we have to populate it anyway, it'd be better to add data-wp-interactive automatically ourselves and discourage people from adding it manually altogether.

In the past, it was discussed the possibility of exposing some parts, like state.router.url, in the store: link. I assume that could be possible with this approach, right? Would they be under a core namespace (for example) and be used as any other namespace?

Ohhh, I forgot to include that namespaces could include / so there can be substores in a namespace. Like "core/router", "core/image" or "core/navigation".

The import syntax would be:

import {
  actions as routerActions,
  state as routerState,
} from "@wordpress/interactivity/router";

store("myPlugin", {
  state: {
    get url() {
      return routerState.location.pathname + routerState.location.search;
    },
  },
  actions: {
    navigate: function* () {
      yield routerActions.navigate(state.url);
    },
  },
});

In this case, the router won't be downloaded unless a block wants to use it, so I guess that just relying on store("core/router") is not enough, at least you should do the import first:

const { state: routerState, actions: routerActions } = store("core/counter");

store("myPlugin", {
  state: {
    get url() {
      import("@wordpress/interactivity/router"); // Start downloading the router.
      return (
        (routerState.location &&
          routerState.location.pathname + routerState.location.search) ||
        null // Return something temporarily until the router downloads.
      );
    },
  },
  actions: {
    navigate: function* () {
      yield import("@wordpress/interactivity/router"); // Ensure that the router has been downloaded.
      yield routerActions.navigate(state.url);
    },
  },
});

This syntax doesn't make much sense to me. So maybe we should teach people to always use import? Even if they want to download it dynamically (although that doesn't work for getters because they can't yield/await an import, even if it has already resolved):

store("myPlugin", {
  actions: {
    navigate: function* () {
      const { actions } = yield import("@wordpress/interactivity/router");
      yield actions.navigate(state.url);
    },
  },
});

To ensure that code is code-splitted even if extenders use static imports, actions.navigate can be code-splitted further to download only the implementation that is required for that particular page (full page vs inner content, for example).

// @wordpress/interactivity/router
const getNavigate = async () => {
  if (state.clientSideNavigation === "full page")
    return await import("./full-page-router.ts");
  else return await import("./inner-content-router.ts");
};

const { state, actions } = store("core/router", {
  state: {
    // url, location and such
  },
  actions: {
    prefetch: function* (url) {
      getNavigate(); // Download the correct navigate version. It doesn't need it, but it does the prefetching.
      // Do the prefetch of `url`…
    },
    navigate: function* (url, options) {
      const navigate = yield fetchNavigate(); // Download the correct navigate version.
      return yield navigate(url, options); // Perform the navigation.
    },
  },
});

Would context.extensionText and context.myPlugin work as expected? If context.myPlugin is not part of the most immediate namespace (myExtension), is it smart enough to look in the parent one?

In that case, context.isOpen points to myExtension::context.isOpen instead of myPlugin::context.isOpen. So, no, it won't work.

But as I said, I think we should disregard the namespace property of data-wp-interactive during the SSR (and use the one in block.json), and discourage people from adding their own data-wp-interactive directives.

[michalczaplinski]

Wow, that's brilliant, Luis. So much great stuff here: code splitting, type safety and a simplified API 👏👏👏

I only have some qualms about the use of generators over async/await.

People will complain because they're not as nice and familiar as async/await, of course, but the main problem is that they are not composable in the same way as Promises are. There is no built-in equivalent of Promise.all() or Promise.any(). So, either we leave that for users to figure out by themselves or we have to add those helpers to the API which is not ideal either.

If wrapping an awaited expression in resume() is all that is needed, I wonder if introducing a lint rule to @wordpress/create-block (interactive template) could alleviate some of that.

Alternatively, perhaps we could go even further and create a babel plugin that injects the resume() calls for each awaited expression and include it in @wordpress/create-block. But maybe that kind of "magic" opens another can of worms... I'm not sure.

[luisherranz]

Good points, Michal 🙂

we could go even further and create a babel plugin

We also thought briefly about that option but quickly discarded it because why introduce a bundling utility when JavaScript already supports what we need? It doesn't feel right…

There is no built-in equivalent of Promise.all() or Promise.any(). So, either we leave that for users to figure out by themselves or we have to add those helpers to the API which is not ideal either.

There's no need for any extra API because you can yield any promise. Actually, I haven't explained this implementation detail in the opening post, but actions.someAction() is an async function, not a generator. It will return a promise.

So, in practical terms, all you need to do is to replace async function with function* and await with yield. The rest of the things remain as they are.

const { actions } = store("myPlugin", {
  actions: {
    someAction: function* () {
      // This works fine.
      yield Promise.all([fetch(url1), fetch(url2), fetch(url3)]);
    },
  },
});

const externalCallback = async () => {
  // This works fine.
  await actions.someAction();
};

[michalczaplinski]

I see. Yeah, I don't think the babel plugin is a great idea either, but it's "just an idea" 🙂 .

There's no need for any extra API because you can yield any promise. Actually, I haven't explained this implementation detail in the opening post, but actions.someAction() is an async function, not a generator. It will return a promise.

Oh, I see. So internally, actions will be wrapped in a promise so that you can await them, is that correct?

[luisherranz]

That is correct, yes. Both actions themselves and whatever you pass to yield 🙂

[luisherranz]

With this API, we could use getters for the pattern to persist the client state between client-side navigations (explained here):

• Merge new SSR state on client-side navigation #53056 (comment)

wp_initial_state([
  "initialNumberOfItems" => 3
]);

const { state } = store("myPlugin", {
  state: {
    get numberOfItems() {
      return state.initialNumberOfItems;
    },
  },
  actions: {
    addOneItem: () => {
      state.numberOfItems += 1;
    },
  },
});

Thanks to the use of getters, the signature of state.numberOfItems doesn't change between the moment where it's a getter that points to state.initialNumberOfItems and the moment where it starts holding the real value.

[luisherranz]

It doesn't seem like this is possible. Regular JavaScript doesn't let you override a property that has a getter without using defineProperty:

const a = {
  get b() {
    return 1;
  },
};

a.b = 2; // does nothing

Object.defineProperty(a, "b", {
  value: 2,
});

So instead of this:

wp_initial_state([
  "initialNumberOfItems" => 3
]);

const { state } = store("myPlugin", {
  state: {
    get numberOfItems() {
      return state.initialNumberOfItems;
    },
  },
  actions: {
    addOneItem: () => {
      state.numberOfItems += 1;
    },
  },
});

people would need to do this:

wp_initial_state([
  "initialNumberOfItems" => 3
]);

const { state } = store("myPlugin", {
  state: {
    currentNumberOfItems: null,
    get numberOfItems() {
      return state.currentNumberOfItems ?? state.initialNumberOfItems;
    },
    set numberOfItems(value) {
      state.currentNumberOfItems = value;
    }
  },
  actions: {
    addOneItem: () => {
      state.numberOfItems += 1;
    },
  },
});

A bit worse, but not terrible, I guess.

[luisherranz]

Here are a few more ideas about this.

Sometimes we've been using the ref to store values that are used as arguments in actions or derived state (previously selectors).

For example, imagine a selector that checks if a div is selected. Each div has its own unique id and the id of the selected is stored in the state:

<div data-some-id="1" data-wp-class--is-selected="state.isSelected">...</div>
<div data-some-id="2" data-wp-class--is-selected="state.isSelected">...</div>

The derived state could be something like this:

const { state } = store("myPlugin", {
  state: {
    get isSelected() {
      const ref = getRef();
      return state.selected === ref.dataset.someId;
    },
  },
});

But sometimes ref will be null because the element has not yet been created, like when it's behind a wp-show, a new element of wp-each or client-side navigation. That may cause errors and flashes of content.

@DAreRodz mentioned that we should expose the props of the underneath element (vnode) because those are always defined.

Instead of naming them just props, which may be confusing if we ever release a components system that also includes props, I think we should name them "Element Props".

The previous example would be like this instead:

const { state } = store("myPlugin", {
  state: {
    get isSelected() {
      const { "data-some-id": id } = getElementProps();
      return state.selected === id;
    },
  },
});

Those props are always defined, so this will always work without problems.

We still need to experiment with this, because people may try to modify the Element Props and we need to think if we want to allow that and what would happen, but I think that exposing them to see what happens is a good idea.

If we name those Element Props, I think we should also use the same for the ref:

• getElementRef()
• getElementProps()

Another idea we've been tinkering with is to expose another reactive state that is local to the element. This may come in handy when the state element is contained in a single element and creating a context doesn't make much sense.

We still need to experiment with this, but if we do, I think we could name it Element State. Then, we will have three element-related APIs:

• getElementRef()
• getElementProps()
• getElementState()

Using it will behave exactly as context behaves:

<div
  data-wp-element-state='{ "isOpen": true }'
  data-wp-on--click="actions.open"
  data-wp-bind--hidden="!elementState.isOpen"
>
  Open by default
</div>

store("myPlugin", {
  actions: {
    open: () => {
      const elementState = getElementState();
      elementState.isOpen = !elementState.isOpen;
    },
  },
});

If you don't need to populate initial values, you can omit the directive because the object is always defined:

<div
  data-wp-on--click="actions.open"
  data-wp-bind--hidden="!elementState.isOpen"
>
  Closed by default
</div>

store("myPlugin", {
  actions: {
    open: () => {
      const elementState = getElementState();
      elementState.isOpen = !elementState.isOpen;
    },
  },
});

The part that convinces me the least about these names is using elementState in the data-wp-bind--hidden="!elementState.isOpen" reference, but I like that all three start with Element because I think it makes it easy to know what they are referring to.

And last but not least, now that with this syntax the namespaces are gone, I think we could experiment with the idea of defining the property name as the suffix of the context or element-state directives.

Instead of this:

<div data-wp-context='{ "isOpen": true }'></div>
<div data-wp-element-state='{ "isOpen": true }'></div>

you could write this:

<div data-wp-context--is-open="true"></div>
<div data-wp-element-state--is-open="true"></div>

That would only work for the default namespace and it will be converted to camelCase following the same logic as the dataset (data- attributes). For simple cases, I think it could be nice.

[luisherranz]

Cool. Let's try it out then 😄

[DAreRodz]

Luis and I were talking a bit more about this.

The Element scope depends on the element in which you are executing the directives. However, you can specify a different namespace for the context you are consuming, and you would have to pass it to getElement(), e.g.:

const { context } = getElement( 'some/namespace' );

It can be confusing, as the namespace would only affect the retrieved context.

// Only `context` changes.
const { context, ref, props } = getElement( 'some/namespace' );

// These are equivalent.
const { ref, props } = getElement();
const { ref, props } = getElement( 'some/namespace' );

So, we will keep it apart for now.

const { ref, props, state } = getElement();
const { myProp } = getContext( 'some/namespace' );

This also has the advantage of destructuring props from the context more easily. 🙂

[luisherranz]

Two thoughts:

1. Attributes need to be valid HTML attributes and props can be anything. So maybe instead of props, we should use attributes here because they are actually valid HTML attributes.

store("myPlugin", {
  actions: {
    select: () => {
      const { attributes } = getElement();
      attributes["data-some-id"]; // ...
    },
  },
});

2. I don't like that element state needs to become elementState in the reference. That could create confusion.

store("myPlugin", {
  actions: {
    select: () => {
      const { state } = getElement();
      state.selected = !state.selected;
    },
  },
});

<button
  data-wp-class--selected="elementState.selected"
  data-wp-on--click="actions.select"
>
  Select me
</button>

What about being able to reference element directly?

<button
  data-wp-class--selected="element.state.selected"
  data-wp-on--click="actions.select"
>
  Select me
</button>

It doesn't make much sense except for the syntax, because you don't need to reference element.attributes or element.ref, but I don't have any other ideas, and I don't like any other name…

Thoughts?

[SantosGuillamot]

So maybe instead of props, we should use attributes here because they are actually valid HTML attributes.

This makes sense to me 🙂

I don't like that element state needs to become elementState in the reference. That could create confusion.

I agree having elementState could be confusing. And I prefer element.state.selected a bit more but I am not convinced either. However, I don't have any good suggestion 😅 I believe we have to keep thinking about it. The whole global state, local state, element state distinction seems to be one of the main challenges so far.

I was considering reusing the namespace syntax for the element, but I couldn't come up with a better syntax. I was thinking something like _element::selected or _element::state.selected, but I can imagine it being confusing as well.

[samueljseay]

👋🏻 I thought I'd add my 2 cents here, as I've recently been getting familiarized with the interactivity API.

1. I would add a +1 that I think "props" should be "attributes" to align with the concept of HTML attributes

2. @luisherranz suggested to me there has been consideration of adding a shortcut for accessing the dataset in getElement. I just wanted to mention I liked this idea, making things like dataset immediately reachable in this way would (imo) nudge users towards this as the "blessed" approach when you need the data in context of the element.

[luisherranz]

While testing this out in WooCommerce, we detected two small TypeScript caveats. I don't think they are blockers, but I wanted to document them for future reference.

1. Getters that return other parts of the state need to be manually cast.

   const { state } = store("myPlugin", {
     state: {
       someValue: "this is a string",
       get someDerivedValue() {
         return state.someValue;
       },
     },
   });

   In this situation, TypeScript cannot correctly infer the type of state because to infer that type, it needs the type of state.someDerivedValue and to know that type, it needs the know the type of state.someValue, which is not available until state is available.

   To break this infinite loop, you have to manually cast the return of state.someDerivedValue:

   const { state } = store("myPlugin", {
     state: {
       someValue: "this is a string",
       get someDerivedValue(): string {
         return state.someValue;
       },
     },
   });

   Now, TypeScript doesn't need to resolve the type of state to know the type of state.someDerivedValue, and everything works fine.

2. Generators act as async functions, but the inferred type is still a generator.

   const { actions } = store("myPlugin", {
     actions: {
       *asyncAction() {
         yield fetchSometing();
       },
     },
   });

   Here, the inferred type of actions.asyncAction is () => Generator instead of () => Promise<void>.

   This works fine when they are used in other async functions (generators) because yield will take any value:

   const { actions } = store("myPlugin", {
     actions: {
       *asyncAction() {
         yield fetchSometing();
       },
       *otherAsyncAction() {
         yield actions.asyncAction(); // This works fine because `yield` will take any value.
       },
     },
   });

   But they could cause problems when used outside of the store in async functions.

   const externalAsyncFunction = async () => {
     await actions.asyncAction(); // TS will say: 'await' has no effect on the type of this expression.
   };

   However, when an async function (generator) is meant to be used outside of the store, it should not rely on scoped functions (getContext or getElement), so people should be able to use async functions instead of generators.

[bph]

The new store() API was merged

• Interactivity API: migration to the new store() API #55459

17 of 25 tasks are completed from the tracking issue

• Tracking Issue: More core blocks and new store() API #53740

[sethrubenstein]

@luisherranz Having some trouble with the latest V3 of the api and RC of Gutenberg 17.2

At first I thought it was our current implementation of the api in our block library, but when I created an interactive block using the @wordpress/create-block interactivity template it also did not work.

Seeing these errors:

Signaling that the store script isn't there... but it's definitely getting enqueued. Any thoughts on what I might be doing wrong?

[luisherranz]

That error is because, starting from 17.2, the Interactivity API is served a native module (import { store } from "@wordpress/interactivity") instead of a wp global (const { store } = wp.interactivity).

The PR that introduced this change was:

• Interactivity API: Use modules instead of scripts in the frontend #56143

when I created an interactive block using the @wordpress/create-block interactivity template it also did not work

That's unexpected, sorry about that 😄

This PR was supposed to switch the create-block template from a script to a module. I don't know what went wrong, but we will investigate:

• Start using modules in the interactive create-block template  #56694

---

I'll publish a migration guide for GB 17.2 with instructions for both the new store() API and modules in the changelog discussion, but it might take me a few days.

If you want to go ahead on your own and update to GB 17.2 before I publish the migration guide, I suggest you take a look at this PR to see what API changes are needed to switch from scripts to modules:

• Start using modules in the interactive create-block template  #56694

If you need to bundle/minimize the new module files, I suggest you use esbuild until we add support for modules in wp-scripts. Esbuild should mostly work out of the box, but use bundle: true 🙂

[sethrubenstein]

@luisherranz Ah that would do it. Added in the gutenberg_register_module and gutenberg_enqueue_module functions and now the interactivity api is working.

I'm still seeing this emanating from view.js but the api is working.

Getting caught up on the modules and import maps work now and lemme just say I throw my support behind a viewModule and editModule addition to block.json.

Really liking the api changes thus far 👍

[sethrubenstein]

Oh I see, thats the bundler problem. Disregard!

[luisherranz]

I throw my support behind a viewModule and editModule addition to block.json

Yeah, I think that's the first obvious change, although for editorModule we need to figure out how to expose all the @wordpress packages as modules first 🙂

[luisherranz]

I'll publish a migration guide for GB 17.2 with instructions for both the new store() API and modules in the changelog discussion, but it might take me a few days.

@sethrubenstein:

• Changelog - Tracking Breaking Changes in the Interactivity API #52906 (comment)

[luisherranz]

I've published the migration guide for the new store() API, that also includes the renaming of data-wp-effect to data-wp-watch and the new modules:

• Changelog - Tracking Breaking Changes in the Interactivity API #52906 (comment)

[sirreal]

Async Actions should use generators instead of async/await

It would be nice to support async functions, and if they're not supported a lint rule is a good idea. I know some folks are already working on or thinking about this.

@gziolo, @jsnajdr, @fullofcaffeine, and myself spent some time looking for an alternative that would work with async functions. @jsnajdr proposed binding this in the async functions to expose state and context. I put together #61098 to explore this idea, and it does work nicely for state and context within an async function, unfortunately when getters are used in the store that use getContext(), we still have the problem of the wrong context once the async function returns (before the first step in the promise chain).

import {
  getContext,
  getElement,
  store,
} from "@wordpress/interactivity";

const { state } = store("ns", {
  state: {
    get text() {
      return `Clicks: ${JSON.stringify(getContext()?.clicks)}`;
    },
  },
  actions: {
    // <button data-wp-on--click="actions.clickHandler" data-wp-context='{"clicks":0}' type="button">Click me</button>
    async clickHandler() {
      // Fine here:
      console.log(this.state.text);
      // Clicks: 0
      console.log(this.context.clicks);
      // 0
      console.log(this.element.ref);
      // <button…

      console.log(state.text);
      // Clicks: 0
      console.log(getContext().clicks);
      // 0
      console.log(getElement().ref);
      // <button…

      this.context.clicks += 1;
      await new Promise((r) => setTimeout(() => r(), 1));

      // The getContext in the state getter is broken here
      console.log(this.state.text);
      // Clicks: undefined

      // The context on `this` is still correct:
      console.log(this.context.clicks);
      // 1
      console.log(this.element.ref);
      // <button…

      console.log(state.text);
      // Clicks: undefined
      console.log(getContext()?.clicks);
      // undefined

      // getElement errors at this point because scope is lost.
      // console.log(getElement().ref);
    },
  },
});

[luisherranz]

unfortunately when getters are used in the store that use getContext(), we still have the problem of the wrong context once the async function returns

That's the reason we went with generators. At the moment, there's no way to recover the scope after an await, unless you wrap it in a function that you control. You can actually do that today, by the way:

await withScope(new Promise((r) => setTimeout(() => r(), 1)));

Take into account that this bounds to the object (store) and stores are already stable references, so they work fine after an await. On the other hand, scope (context, element) is bound to the HTML element that triggered the interaction and therefore can't be bound to any object reference. In other words, things like this or proxies are not useful here.