Clarifying the state API

[chrisvfritz]

I noticed this one line required a fair bit of explanation in the tutorial:

@props.app-state.get \state.query

I think part of the reason is the state. prefix is passed in as a parameter when it's really a mandatory part of the API for fetching state. It may be useful to have an additional function, get-state, which simply assumes the state. prefix. For example:

@props.app-state.get-state \query

This wouldn't replace the more general purpose get function, but would allow users of the framework to put off learning more about Arch's internals until they're doing non-trivial things with it.

Then there's one other change I'd like to request. I'm not sure if it's too far into Arch's development to change this, but what would you think about renaming app-state to just app?

@props.app.get-state \query

I believe I understand the reason for calling it app-state - it does contain state other than component state. At the same time though, state has become synonymous with component state in the React world, so I fear using the word (even appropriately) to describe other kinds of state will inevitably cause confusion for newcomers to the framework.

What are your thoughts?

[chrisvfritz]

Having now used this interface a little more and with nested cursors (this is also my first time playing with cursors), I don't like the suggestion for the get-state function anymore. However, I'm still not sure why the start function and route components wouldn't just be passed the app-state.get \state sub-trie. Are there cases I'm not thinking of when users of the framework would need to access routing state and other state handled by the framework?

[charypar]

The main reason is the application state is not alone in the app-state hash. There is also the route key the routing updates and when #40 gets done, there will be cookies too.

All of those are potentially useful to a route - writing cookies in response to a user action or a state-based redirect API we've talked about elsewhere (possibly outside Github, in which case I'm sorry). Going indirectly through state and then observing and updateing cookies or route seems unnecessary.

Hope that makes sense.

[chrisvfritz]

That does make sense. Thanks for the explanation! It still bugs me a little that there's a state within app-state that holds a specific kind of state, but the concern it's handling isn't explicitly, no pun intended, stated. 😃 No obvious alternative is occurring to me though, so I'll close this.

[charypar]

It bugs me too, quite a lot. It generally bugs me that we're dictating the top level schema of the app-state, but the benefits of having these things in there seem to outweigh the drawbacks.

Maybe we could think about a layer of API on top of the basic cursor one which would give aliases to the available things as you suggested. e.g.:

app-state.get-state '...'
app-state.get-cookie '...'
app-state.get-route '...'

[tabazevedo]

So.. potentially when defining an application i.e.

const Application = arch.application.create({
  getInitialState() {
    ...
  },

  routes() {
    ...
  },

  start() {
    // Maybe we can use a react-like API here?
    initObservers(this.state);
  }
});

So... in relevant places you could bind to an application object which would give you this.state, this.cookies and this.route which are currently the cursors in app-state.

Seems like a clean solution for here, and maybe your top-level route components can be passed that object as props so they can do this.props.state / this.props.cookies / this.props.route

[charypar]

@tabazevedo I kinda want to avoid adding too many props to the routes. If it all lives in one app-state, it should just be one prop (also reinforces the idea). But wouldn't mind some API sugar for getting to the relevant parts of app-state.

Not sure I like the idea of an Application global either. I always prefer injection over some global name.

[tabazevedo]

@charypar oh, i didn't mean anything with that application variable. It's just what app.js exports.

[charypar]

@tabazevedo oh sorry, I see, so you're arch = require('arch') and get access to the full state if you need to through arch.application.state?

[charypar]

Wait, no, confusing myself now :) We don't export the application instance from the module...

[tabazevedo]

no, my thought was that when arch calls (your application).start under the hood, instead of passing app-state which is confusing and ambiguous we just bind the this keyword of start to an object

{
  state: app-state.get('state'),
  route: app-state.get('route'),
  cookies: app-state.get('cookies')
}

The object itself isn't stored anywhere really. Maybe we could store it in arch.application but that seems a bit dirty.

[charypar]

Hmm... I don't know if that's helpful. Mostly the place where you want that syntax sugar is route components.

[chrisvfritz]

What's the downside to passing state, cookies, and route as props, instead of app-state? The only one I can think of is users would no longer be able to change the top level of the cursor - which would maybe be something good to enforce.

[charypar]

@chrisvfritz well first it doesn't scale that great - as we add new things we'll have more and more props, second it creates another contract - the props for every single route, not only for things touching app state and finally it hides the (fairly important and useful) fact that all of those things are indeed in the app state, in a single place you can observe (and record history of, instrument, sync with some persistence, etc...).

So even though none of those are particularly bad things (they are sort of "soft" disadvantages), there's quite a few for not too much benefit, which is why I'm reluctant to commit to that idea. Hope that makes sense.