Stateless atoms for exports and side effects aka "services"

[edongashi]

Hi. I'm playing with this library (v2) and I can say that so far I am fascinated!

I tried to make my own abstractions over Jotai for some common patterns but ended up frustrated by the lack of imperative access outside of react components. In Zedux I found that everything I wanted is already possible out of the box!

The toy project I am trying to use Zedux in is a personal Obsidian plugin. What immediately struck me that I was able to refactor a good chunk of the logic to be more expressive even before touching any views. Being independent from a react tree makes life so much simpler.

One idea I really liked was the atom exports. This allows exposing higher level wrappers for mutating the state graph. I imagine sometimes I would want the exports part only, without caring about the mutable state itself. The exports being stable references is too good to pass. However, importing exports is a little verbose:

const { addTodo } = injectAtomInstance(myService).exports

Could we have simpler hook/injectors for direcly accessing the exports? E.g.:

const { addTodo } = injectAtomExports(myService)
const { addTodo } = useAtomExports(myService)

With tree shaking this hook would be entirely optional, no?

Another thing for these "services" is that declaring them feels hacky (pardon the idiotic example):

const todosService = ion("todosService", ({ getNode }) => {
    const todosNode = getNode(todosAtom)
    return api().setExports({
        addTodo(label) {
            todosNode.set(todos => ([...todos, label]))
        }
    })
})

Could we have a factory simplified for declaring "export-only" atoms?

const todosService = service("todosService", ({ getNode }) => {
    const todosNode = getNode(todosAtom)
    return {
        addTodo(label) {
            todosNode.set(todos => ([...todos, label]))
        }
    }
})

The downside here is that it won't be obvious to users that the returned object does not re-evaluate. Note that one can write these in userland, but it would be interesting to see if there can be an official acknowledgment of this use case.

Beside the exports, I found that I ran some initialization code inside the ecosystem via injectEffect, say registering event handlers and some commands etc. I found that this also requires a context where I don't care about state, I simply want to run this as a background daemon. Something like a service would make sense in this case as well:

const viewService = service("viewService", ({ get }) => {
    const plugin = get(pluginAtom);
    const settings = get(settingsAtom);
   // or a selector (I forgot the syntax): get(({ get }) => get(settingsAtom).someParameter);

    injectEffect(() => {
        plugin.registerView(...)

        return () => plugin.detachView(...)
    }, [plugin, settings.someParameter])

    // no return means undefined, which means no exports?
})

Am I crazy for finding injectors extremely attractive for non-UI use cases like this?

To mount the services and make sure they live as long as the plugin I had to do a trick by instantiating a top level atom set to ttl: -1. On plugin unload I reset the ecosystem to make sure we run the unmount callbacks on the services. Nothing wrong, just felt a bit low level and perhaps there is room to have some convenience helpers.

Lastly, for DI: I think overrides works only for state, right? This would mean that to be able to shim a service in testing it wouldn't be so easy with exports. Would it therefore be better if the "exports" are the atom's state itself? If the service exports are in the state itself, then I suppose the responsibility would be upon you to keep them stable? In that case the "service" factory would have to take care of auto batching.

I am torn between the two approaches: state service vs exports service. What are your thoughts?

Thanks and keep up the excellent work! 👍

[edongashi]

I think it makes more sense for the returns to live in the state slot. I get two benefits from doing that:

1. I can now get the exports with a simple get(myService), removing the need for more hooks.
2. I can override the values for testing.

So far I came up with this factory:

export function service<Params extends any[] = [], State extends Record<string, any> | void = void>(
  key: string,
  value: (ecosystem: Ecosystem, ...params: Params) => State,
  config?: AtomConfig<State>
): IonTemplateRecursive<{ State: State; Params: Params; Events: None; Exports: None; Promise: undefined }> {
  return ion(
    key,
    (...args) => {
      const exports = value(...args);
      return injectMemo(() => api().setExports(exports ?? {}).exports, []) as State;
    },
    config
  );
}

The choice between atom and ion is an implementation detail. I just need to verify that I don't get unnecessary re-evaluations if the service code re-renders - the result is stable so it should not bubble any re evaluations up...

[bowheart]

Cool. api().setExports(exports ?? {}).exports is the same as just exports. And point number 2 is moot as I explained below, though overriding is possibly easier if it's state.

I think I like exactly this implementation.

[edongashi]

Cool. api().setExports(exports ?? {}).exports is the same as just exports.

Are you sure? Note that I do this trick to wrap the funcs in batches, because the wrapper utility is not public API.

[bowheart]

Oh you're right. I sent that after midnight, I was tired 😅. Yeah makes sense. In a way api().setExports is how the wrapping algorithm is exposed.

[edongashi]

My general rule is: If it can change, it's state. If it's stable, it's usually an export. I use exports for these myself.

You are right. After some more thought I think I will go back to atom+exports+injectService combo. Reasons being:

1. We are abusing the state slot. Maybe in the future I want to convert the service into a stateful atom.
2. The state is non serializable which might mess with dehydration/rehydration.
3. get(myService) registers a dynamic dependency which is misleading and might be less performant.
4. I am abusing ions. They should be used for their intended purpose.
5. Nothing wrong with injectService(myService). It is also more self-documenting and I can immediately tell what is an effect dependency and what is not.

injectService/injectAtomExports are interchangeable but I would use the former name in my code.

[bowheart]

Hello @edongashi! Thanks for these ideas. I've been on the fence for a while on some of these things. And that fence still has a solid hold on me for one or two of them. Maybe you can finally talk me down from here.

Could we have simpler hook/injectors for directly accessing the exports?

Yes. And they would be tree-shakeable. We discussed adding these to Zedux core probably 4 years ago and I said no then. That was because I felt like people were shying away from using atom instances themselves - they were too magical/mysterious. So I wanted our devs to use instance.exports directly. But we then went and added lots of these helpers in our codebase - useAtomExports, useAtomContextExports, etc.

So I've pivoted and am probably ready to add some helpers like this.

Could we have a factory simplified for declaring "export-only" atoms?

This is probably a candidate for the utils package (#143). I've played with a few variations of this. For example, extending AtomInstance itself would be trivial to support:

class MyController extends AtomInstance {
  // define methods directly on the class:
  async example() {
    // can access the ecosystem via `this.e` (would make this more user-friendly if we did this)
  }
}

ecosystem.getNode(MyController).example() // no need for `.exports` or `.get()`, we extended AtomInstance itself

But back to the fence: I can't decide what this API should look like (I definitely wouldn't do it like this example). Your service implementation is excellent and Zedux-y, I think. I don't see it getting better than that.

Beside the exports, I found that I ran some initialization code inside the ecosystem via injectEffect, say registering event handlers and some commands etc. I found that this also requires a context where I don't care about state, I simply want to run this as a background daemon

So this is what most signals libs would call an effect. Zedux has injectEffect, but I have considered adding a top-level effect primitive. That would look like this in your example:

const viewEffect = effect("viewEffect", ({ get }) => {
  const plugin = get(pluginAtom); // reactive
  const someParameter = get(() => get(settingsAtom).someParameter); // reactive selector

  plugin.registerView(...)

  return () => plugin.detachView(...)
})

// you can then
const effectNode = ecosystem.getNode(viewEffect)
effectNode.destroy() // run cleanup

I can't decide if this is useful enough for its own API. What do you think? This is probably yet another util. Although ions made it to the core package... Idk but here's a summary from this discussion (mostly for my reference):

• ion - an atom with ttl: 0
• service - an atom with only exports
• effect - an atom with just an injectEffect

Interestingly, all these exotic atom ideas take the ecosystem as their first parameter.

Lastly, for DI: I think overrides works only for state, right?

Overrides override everything. An atom override is an entirely different atom with its own state, promise, exports, ttl, etc. When calling myAtom.override TypeScript ensures the override's state, promise, and exports types match the overridden atom's. But as long as the types match, the values can be anything.

Would it therefore be better if the "exports" are the atom's state itself?

Yeah I understand this dilemma. My general rule is: If it can change, it's state. If it's stable, it's usually an export. I use exports for these myself. But I think I'm alone in that - looks like most of our "controller"/"builder"/"service" atoms put these functions in state. And I agree with your first argument in favor of using state - get(myService).myExport() is clean.

It isn't what I do, but maybe I'm wrong. I think I have to say that the prevailing wisdom seems to be to put these in state.

[edongashi]

Thanks @bowheart for the detailed response! I will share my comments as soon as I'm near a keyboard.

[edongashi]

But we then went and added lots of these helpers in our codebase - useAtomExports, useAtomContextExports, etc.

These are all 2-3 lines and I wouldn't mind writing them in the user side. The only hurdle is getting the types right and up to date.

But back to the fence: I can't decide what this API should look like (I definitely wouldn't do it like this example).

Everyone will have different tastes and you will always find someone complaining. Since you already provide the primitives, you can let users decide, perhaps listing the various approaches as recipes in docs which can be used as starting points. But an opinionated utility library is also fine. Keeping the core as slim as possible lowers the entry barrier.

Your service implementation is excellent and Zedux-y, I think.

Thanks! The typings might need some refining though. To make it even more Zeduxy I should call it photon (because it's massless 😅)

but I have considered adding a top-level effect primitive. That would look like this in your example: ... I can't decide if this is useful enough for its own API. What do you think?

I would be against a top level effect as it conflicts with injectEffect. It would confuse people who might think they need to injectEffect(viewEffect) - then you tell them you actually have to injectAtomInstance(viewEffect) which is even more confusing!

The example is also not immediately obvious when the effect will re-run. injectEffect gives explicit control and sometimes you might want to intentionally skip reactivity for some particular value. Also people coming from react will understand the interface in <10 seconds.

To me, a service serves one or both of the following functions:

1. A daemon process that reacts and acts on the universe.
2. An abstracted interface for actions and mutations.

Point 1 already covers effects functionality and more. Sometimes I would want multiple related effects within the same service but with different conditions. Sure it might be a little more verbose but like I said above anyone coming from react will immediately know what's going on. Also if I later decide I can expose an API to this service - to me this is way more powerful. This is only my opinion though and that's why I think it should live in my codebase and not in the library. Also keep in mind that my experience with this library is limited to just a few hours of browsing the docs and messing around!

Interestingly, all these exotic atom ideas take the ecosystem as their first parameter.

Again this is an opinion and won't be the same for everyone. I like how get is shorter and nicer than injectAtomValue, but on the other hand it's bad that it looks different from the other injectors. I also have to be careful about the call context, while for injectAtomX I immediately know that I must follow the rules of hooks. I'm still not sure whether I should make my service an atom vs an ion.

The redundancy between get and injectAtomValue slightly triggers my OCD! Also useAtomInstance and getNode doing the same thing is not immediately obvious. But I think get wins in the end simply because it looks cleaner.

Overrides override everything.

That's good to know, thanks!

To summarize: if unsure, these specialized helpers should live in userland. It's a shame that it's cumbersome to write the typings though.

[edongashi]

Also useAtomInstance and getNode doing the same thing is not immediately obvious.

Are there any plans to rename useAtomInstance to useNode for consistency?

[edongashi]

It's a shame that it's cumbersome to write the typings though.

I just discovered TypeScript Tips which will come in very handy!

[bowheart]

I am absolutely planning on renaming `useAtomInstance` and `injectAtomInstance`, but not in v2; it had too many breaking changes already. V3 will be a much more relaxed major version and can include things like that. FYI I won't have consistent internet access till Monday. Will reply to the rest of this then

…

On Sat, Apr 26, 2025, 4:01 PM Edon Gashi ***@***.***> wrote: Also useAtomInstance and getNode doing the same thing is not immediately obvious. Are there any plans to rename useAtomInstance to useNode for consistency? — Reply to this email directly, view it on GitHub <#245 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADEXCU2O7GUWZWOD3E6CLML23PQ2JAVCNFSM6AAAAAB34TLS4WVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTEOJVGY4TKMQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[edongashi]

No rush, I am changing my mind every 2 hours - now I am back to vanilla atoms and just using the Service suffix to denote services. I don't think the core needs any additions because the wrappers are 2-3 lines anyway. The primitives are so ridiculously powerful I find that I can emulate almost all other state libraries with a few lines of glue. The fact that you can do atom+computed+bunshi+effects+composition+reusability+immer under a minimal API is just unreal 👏👏👏