[discussion] api naming

[lzfee0227]

TL;DR

See conclusion in https://github.com/qiniu/formstate-x/issues/20#issuecomment-1035840020

---

for formstate-x-next

• validators -> addValidators
  • + @huangbinjie
• $
  • $ looks like a hack
  • $ should not have multiple meanings in different contexts
• _value -> rawValue or sth else?
  • _ should actually be private, but have to be accessed outside formstate-x (for bind** not included & should not included)

[nighca]

• validators -> addValidators

I don't think it's necessary 🤔

• $ should not have multiple meanings in different contexts

IMO we should just remove $ on FieldState

• _ should actually be private, but have to be accessed outside formstate-x

Ideally, It should be private in module scope, not class scope. We have no module level public / private in Javascript, that's the point.

Or, maybe we can achieve that by putting bindInput on FieldState - so we can use class level private - but I don't like the API.

[lzfee0227]

我觉得既然隔壁的 issue 里写了中文 那这里用中文也无所谓了… = =

[nighca]

It's OK, when using English introduces additional cost.

[nighca]

• $ should not have multiple meanings in different contexts

IMO we should just remove $ on FieldState

If we can also remove $ on FormState, as we assumed in #40. All $s will be gone 🎆

[huangbinjie]

I don't think it's necessary 🤔

It's realy matters that Function name ought start with a verb, such as getByXxx, isXxx, hasXxx

Ideally, It should be private in module scope, not class scope. We have no module level public / private in Javascript, that's the point.

Maybe index.ts can be treated as the public module, the others can be private module?

[nighca]

Validatable & ComposibleValidatable -> State

[nighca]

• FieldState
• FormState -> StructState
• ArrayFormState(see #54 ) -> ListState
• ProxyState

[lzfee0227]

• FieldState
• FormState -> StructState
• ArrayFormState(see onChange() for FormState #54 ) -> ListState
• ProxyState

FYI: Fields Input etc 另外 Proxy 通常跟 Decorator 类似，输入输出类型不变？

[nighca]

另外 Proxy 通常跟 Decorator 类似，输入输出类型不变？

名字可以商量，有建议吗？

[nighca]

• _value -> rawValue or sth else?

Maybe instantValue

[nighca]

• _value -> rawValue or sth else?

Maybe instantValue

_value is removed in #63

[nighca]

Conclusion

content below may change

• [x] Remove _value
• [x] Remove $ of FieldState (maybe later back as safeValue, see details in #58)
• [x] Validatable & ComposibleValidatable -> IState
• [x] validators -> withValidator
• [x] ProxyState -> TransformedState
• [x] disableValidationWhen -> disableWhen See #17 for details

[nighca]

Consider that most of the time we append validators like this:

const state = new FieldState('').validators(...)

const formState = new FormState({
  foo: new FieldState('').validators(...)
  // ...
}).validators(...)

withValidator will be better than addValidator, if you compare

const state = new FieldState('').addValidator(...)

with

const state = new FieldState('').withValidator(...)

[huangbinjie]

withValidator will be better than addValidator

介词 with 当动词用好吗，那下面这种情况看起来就不舒服了

const state = new FieldState('')
state.withValidator
// state.addValidator

另外 add 的反义词也好找点，当需要对成的接口的时候

[nighca]

介词 with 当动词用好吗

@huangbinjie 不是把 with 当动词，而是这里就不用动词来命名了

那下面这种情况看起来就不舒服了

const state = new FieldState('')
state.withValidator
// state.addValidator

这种情况可以写成

state = state.withValidator(...)

虽然确实会麻烦一点；但是对比：

1. 消费 validators() 的返回值

   const state = new FieldState('').validators(...)
   // 或者
   return new FormState().validators(...) 

2. 不消费 validators() 的返回值

   const state = new FieldState('')
   state.validators(...)

显然 1 对应的场景更多，因此场景 1 下的自然程度要比场景 2 下的自然程度更重要

另外 add 的反义词也好找点，当需要对成的接口的时候

with 也好找，without 就是了..