Does it make sense to move this to state-flow.api now? That will probably save another deprecation.

Still looks inconsistent to me, return is part of the primitives.
Of course you could simulate (return v) with (state/gets (constantly v)), but that's not the point.

I would keep return and invoke exactly where they are and create a state-flow.api where we can export return, invoke, modify (or whatever name)

From the library development perspective it makes sense to keep state primitives in the state-flow.state namespace because they are the building blocks on top of which we build state-flow itself. There is a hierarchy of dependency. state-flow.core depends on state-flow.state. From the user perspective it makes sense to have all the user level api in a single namespace. Can we have our cake and eat it too?

@sovelten We're definitely interested in all forms of possessing and consuming 🍰!

There's a disconnect between your view of return and the one a few of us on test-pack have developed. You're saying it's part of the primitives, but we see it (and invoke) as fundamentally different from e.g. get and modify as it does not actually interact with state in any way:

That's because get and modify get and modify state, whereas return and invoke have nothing to do with state. If we leave them all in the same namespace, then they don't make as much sense:

flow/get    ;; get what?
flow/modify ;; modify what?
flow/return
flow/invoke

api/get    ;; get what?
api/modify ;; modify what?
api/return
api/invoke

We think this organization is more intention revealing:
nse (to us):

state/get    ;; oh! We're getting state!
state/modify ;; oh! We're getting state!
flow/return
flow/invoke

Is that clear?

We think this organization is more intention revealing:
nse (to us):

state/get    ;; oh! We're getting state!
state/modify ;; oh! We're getting state!
flow/return
flow/invoke

Is that clear?

That's quite clear, I'm just not sure I agree.

(state/return v) -> (State. (fn [s] [v s]))
(state/invoke f) -> (State. (fn [s] [(f) s]))

Even though they don't change the state, they deal directly with the state transition machinery and data structure defined in the state ns, one we don't want to expose the rest of the library to.

Let me say first of all that state monad is a terrible name for this monad (naming is still the most difficult thing in computer science (and monad is a terrible name for this kind of abstraction (oh well...))), because the data structure is not a state, it is a state transition function (that may or may not change the state) and that may be the reason for the apparent disconnection of return and invoke. It's not about changing state, it is about composing state aware functions.

That's why I propose to keep return and invoke where they are and create an api in which we can do:

(flow/invoke ...)
(flow/get-state ...) ; names may vary
(flow/swap-state ...)
(flow/return ...)

I believe this is having the cake and eating it.

That's why I propose to keep return and invoke where they are and create an api in which we can do:

(flow/invoke ...)
(flow/get-state ...) ; names may vary
(flow/swap-state ...)
(flow/return ...)

I believe this is having the cake and eating it.

That works for me, personally, but @philomates expressed a distaste for fns named get-xxx vs xxx/get. @philomates can you be convinced this is an astoundingly beautiful approach?

Let me say first of all that state monad is a terrible name for this monad (naming is still the most difficult thing in computer science (and monad is a terrible name for this kind of abstraction (oh well...))), because the data structure is not a state, it is a state transition function (that may or may not change the state) and that may be the reason for the apparent disconnection of return and invoke. It's not about changing state, it is about composing state aware functions.

I don't see this fully (though I'm trying). What is "state aware" about return and invoke? Are you saying they're state-aware, but just choose to ignore state (making them state-ignorant and state-aware at the same time!)?

Let me say first of all that state monad is a terrible name for this monad (naming is still the most difficult thing in computer science (and monad is a terrible name for this kind of abstraction (oh well...))), because the data structure is not a state, it is a state transition function (that may or may not change the state) and that may be the reason for the apparent disconnection of return and invoke. It's not about changing state, it is about composing state aware functions.

I don't see this fully (though I'm trying). What is "state aware" about return and invoke? Are you saying they're state-aware, but just choose to ignore state (making them state-ignorant and state-aware at the same time!)?

Yeah... I guess? 😅
Let's call this thing blorb. All that get, put, return, invoke do is create raw blorb. We don't want to deal with blorb directly because blorb is ugly and also it would be an abstraction leak, we want blorb contained, we don't want people ever to know that they can create blorb with (State. (fn [s] ...), not even state-flow.core, because if you don't use the api you might end up with a corrupted/useless blorb. So instead we use those functions as a blorb api to creating and composing blorb.

Now, the blorb api just happens to also be useful for composing flows (because flows deep down are just fancy blorbs). So we can expose part or all of the blorb api to the user. Hope that all makes sense now.

(after note: Some of the things we deal with are not even an api to blorb, they are an api to any wobble, which is a protocol that blorb implements. This is the case for fmap, sequence and possibly others. return is directly part of the implementation of the wobble protocol for blorb)

Now, the blorb api just happens to also be useful for composing flows (because flows deep down are just fancy blorbs). So we can expose part or all of the blorb api to the user. Hope that all makes sense now.

Not a bit, but thanks for trying ;)

That's why I propose to keep return and invoke where they are and create an api in which we can do:

(flow/invoke ...)
(flow/get-state ...) ; names may vary
(flow/swap-state ...)
(flow/return ...)

I believe this is having the cake and eating it.

@sovelten as ordens!

I think this is great now. Still need to update the README and walkthrough, but we're getting close.