Atom and all repositories under Atom will be archived on December 15, 2022. Learn more in our official announcement

service-hub

A semantically versioned provider/consumer system for global application services.

The order-pizza library wants to provide a global service for use by other modules in the application. It calls provide on a global ServiceHub instance with the name of the service and the current semantic version of the API:

# Provider

global.services.provide "order-pizza", "1.0.0",
  placeOrder: (size, topping) -> # ...

Then two other libraries consume this service, ensuring they are compatible with its API by specifying a version range:

# Consumer 1

workingLate: ->
  global.services.consume "order-pizza", "^1.0.0", (orderPizza) ->
    orderPizza.placeOrder("medium", "four cheese")

# Consumer 2

burntDinner: ->
  global.services.consume "order-pizza", "^1.0.0", (orderPizza) ->
    orderPizza.placeOrder("large", "pepperoni")

Now the author of the order-pizza makes a breaking change to the API. They start providing another instance of the service associated with the next major version number, converting the old service to a shim for compatibility:

# Provider

placeOrder = ({size, toppings}) -> # ...

# Providing the new API
global.services.provide "order-pizza", "2.0.0", {placeOrder}

# Shimming the old API
global.services.provide "order-pizza", "1.0.0",
  placeOrder: (size, topping) ->
    placeOrder({size, toppings: [topping]})

If at some point the API changed so drastically that it wasn't possible to shim previous versions, at least the outdated consumers wouldn't use the new API incorrectly. They would just fail to discover the service.