Consolidation ideas

[sthielen]

One of the big projects early next year, as we renew focus on community & developer experience, will be to consolidate and refactor all the packages used in Koji templates.

In the beginning, our goal was to introduce as few requirements as possible for template developers so as not to constrain the work they might do, and to minimize the overhead of learning to "adopt" Koji. This led to the low-level, unopinionated fragmentation we see today.

We are now in a different place, where we have a more defined and stable understanding of the interfaces between the Koji platform/player and the template. It feels, to me, like now is the right time to look holistically across all the developer-facing packages in our ecosystem and create a "v2" that gets everything nice and clean and provides a foundation for future work.

The purpose of this issue is to generally collect ideas, pain points, preferences, etc. relating to the packages in our developer ecosystem. My feeling at the moment is that this will precipitate a single @withkoji/core package, for both browser and node and with named exports for different scopes. We can then deprecate all the individual packages and have everything in one place. Some packages, like database and dispatch, might make sense as separate packages.

The lay of the land today is:

• @withkoji/vcc
  • FeedSdk
  • InstantRemixing
  • Keystore
  • VccMiddleware
  • bin script for compiling VCC json into a single file + file watcher
• @withkoji/iap
• @withkoji/auth
• @withkoji/analytics
• @withkoji/database
• @withkoji/custom-vcc-sdk
• @withkoji/dispatch

All ideas welcome!

[sthielen]

A few to start:

• Typescript + exported interfaces for everything
• All methods with callbacks should be async/promises (await iap.getToken(), etc.)
• Auth/IAP/dispatch authentication should all use a single callback token (right now iap uses its own user callback token, and everyone else uses the one from auth)
• InstantRemixing should have batch getters and setters for dealing with multiple values at once
• Keystore should support batch requests
• We might consider renaming InstantRemixing class to "Remix," and all the feed methods to "Player"
• We should figure out what to do with the file watcher/json compiler in wk/vcc, as the current implementation feels like overkill
• Better CI/test strategy for package deployment (database has nice tests, but publishing new versions of packages is still funky across the board)
• Better debugging support/logging/tracing would help a ton

[arist0tl3]

This is great!

Some ideas off the top of my head:

• Callbacks for io tasks (e.g., instant remixing setters)
• Any listener should return an unsubscribe function
• Should packages be scoped by client/server
• Can we find a non-watcher pattern that's backwards compatible for json vcc values
• How would one large package translate into usable documentation
• Helpful error messages instead of just 500s for API-related calls
• Debug "modes" that are configurable during instantiation of the classes that could offer different log levels, etc
• A more robust communication with the platform (message lifecycle so that the dev knows if the message has been accepted)
• Revisit nomenclature for scopes/methods

[rasienko]

It would be a good time to revisit auto-generating the reference docs as well. We can leverage jsdoc tags and build an output that can be consumed as a source node in Gatsby to integrate it with the site. Some initial dev/devops work to do it, but it will give us more scalability in the future. It also allows us to do things like generate deep links from the docs to the package source.