akkadu/styleguide

Developer styleguide for contributing to Akkadu repositories

styleguide's Issues

[PROP]: Use node-fetch as standard server-side request module

Why node-fetch?

• API-consistent with client fetch
• Lightweight
• Active development
• 0 dependencies

Why Not ____?

• request is deprecated
• isomorphic fetch uses node-fetch under the hood, acting more like a client polyfill with ss support
• axios is a good module as well, but it would need to be implemented on client (11kb) to be API-consistent with client request module

[PROP]: Use request.js as our default way for any requests on the client side

Is your feature request related to a problem? Please describe.

Request.js is an Axios powered module written some time ago to normalise our request patterns on the client side.
Things that the request.js provides:

• Progress events as callback (back to requester)
• A global page-level progress event inside a navbar container by passing only one boolean "globalProgress:true"
• Validation of all the parameters passed into it
• In-built API versioning support
• In-built content and response type handling
• Normalised response status handling
• Normalised authorisation handling (this was the original motivation)

In addition if we at any point want to extend this further, we can always split it into for instance sub classes.
Also if we want to for whatever reason change axios to another module, we can do that without a major refactor.

Describe the solution you'd like

• Add a section to styleguide to enforce this as the de-facto request module
• Add examples of usage

[FEAT]: Make "Oneline JSDoc Comments" rule as optional

Is your feature request related to a problem? Please describe.

According to the "Oneline JSDoc Comments" rule at style guide, developers seems to be forced to use single line style comment rather than multiple detailed lines style comments. It may simplify the comments wirtng process and reduce the timing for managing comments, however, it may not provide that much benefit in the long run.

Describe the solution you'd like

I would like to suggest making the "Oneline JSDoc Comments" as an optional rule when coding, and possibly making multiple detailed lines style (JSDoc proposed) comments as a prefered option for developers.

With the multiple lines style comments, it could gain potential benefits, such as:

• Easily noticeable parameters' types to avoid unnecessary errors at coding;
• Documentable detailed information about the objects/functions that commented, which can be beneficial for new developer to get to know those items; (For example, the generated Swagger API doc provides a huge assistance to developers that need to get to know the APIs, with functions/utils document which can be generated via JSDoc, it may provide similar benefits as well.)
• Richer IntelliSense that developers could interact with;
• Better understandable code, even developers without extra IntelliSense feature, they could easily unstandand the code;
• Rising awareness of the types being used to reduce potential issues (especially for weak-typed programming languages like js);
  etc.

However, there're drawbacks, for example, it may increase the complicity of managing comments, expand developing time, making the comments a bit verbose sometimes, etc.

Additional context

References:

• https://jsdoc.app/
• Type safe with javascript
• Code documentation for JavaScript with JSDoc
• Create JSDoc Comments for JavaScript IntelliSense

[PROP]: Add "dayjs" to recommended date parser

For client date parsing, dayjs is suitable for all our current needs.

• Tiny (3kb) compared to moment (70kb) and date-fns (18kb)
• Fast popularity, since it was released only 2 years ago (moment > 9 yrs, date-fns > 6 yrs) it's already at > 2M monthly downloads
• Active development with multiple contributions weekly and a release every 10 days, while moment is in passive maintenance
• Excellent browser support
• Immutable, chainable, and simple (api-similar to the long-standing moment.js)
• Optional i18n support

How to test Vue components?

It's clear that there are different practices and utilities from testing "pure" components, and large page-level components, however apart from general rules of thumb, it's not clear how we want to handle everything inbetween.

We could have page-level components that carry little-to-no business logic in them other than importing other components that can be covered in e2e testing frameworks, but what about other complex components that import many other components yet contain some business logic of their own? Is this a question of testing strategies or component design?

I would like to have a framework for which all business logic (methods, reactivity, and async functions especially) are testable as units, whereas integrations are only tested once per page. Maximizing test coverage while minimizing complexity is important to consider.

[PROP]: Make @akkadu/validator our default frontend validator

Is your feature request related to a problem? Please describe.
We have decided to use validate.js in the past for all frontend request validation, but it is not documented anywhere.
in addition after that decision we've extended it's features inside @akkadu/validator to which we can add extra functionality when needed.

Describe the solution you'd like

• Start using @akkadu/validator as our front-end validator
• Write documentation with examples and links to validate.js inside the module, and link to this in the style guide

[FEAT]: Prefer Async/Await

do

const request = async(params) => {
  const options = filterParams()
  const res = await fetch(options)
  const someInfo = await res.getSomeInfo()
  const json = await res.json()
  const data = mapMyData()
  return { ...data, ...someInfo }
}

don't

const request = (params) => new Promise((resolve, reject) => {
  const options = filterParams()
  let response
  let data = {}
  return fetch(options)
    .then(res => 
      response = res
      return res.getSomeInfo()
    )
    .then(someInfo =>
      data.someInfo = someInfo
      return response
    )
    .then(res => res.json())
    .then(json => { ...data, ...json })
})

[PROP]: Add "seeding" section to tests

Should outline

• What should/shouldn't be seeded
• Seeding patterns and strategies
• Utilities available and how they work