api ideas

[SEAPUNK]

new PCB({
    resource: {} // resource object
}, {
    // options
})

api.call(name, data, meta) // meta is "extra" data 
                           // that isn't directly used for the API function

api.use(middleware)

[SEAPUNK]

Q: How will we know if a "route" has been handled? A: handled property and handle() function. See below.

[SEAPUNK]

Q: What do we pass to the middleware? A:

const ctx = {
  resource,
  path,
  originalPath, // read-only path, in case path gets changed
  params: {},
  data,
  meta,
  locals: {},
  response, // Whatever has been passed to handle()
  handled: Boolean, // read-only
  handle: Function // throws if handled = true
}

callMiddleware(ctx, next)

[SEAPUNK]

Q: From the "what do we pass to the middleware" question, should there be a separate property for middleware-only data? For example, we can call the API with .call(name, data, meta), but then the meta will be already initialized. Will the middleware pollute the meta property namespace? A: Yes, it will be called locals, name taken from expressjs's API.

[SEAPUNK]

Q: From last question, this won't work if meta is undefined (or null, or this, or that...). Do we initialize/overwrite non-object metas to objects? A: Invalid, see above question and answer.

[SEAPUNK]

Q: How will the handler functions be called? I know this isn't part of PCB, but rather, the router, but what should be the de-facto standard? A:

handler(ctx.data, ctx)

The handler will be wrapped in a promise, that resolves with Promise.resolve()

[SEAPUNK]

Q: What should call() return? A:

ctx

If you want to call the API function-style (that is, returns just ctx.response), you'll have to do it through an adapter. (pcb-direct adapter, which is basically a passthrough to pcb.call, with the exception of it returning ctx.response instead of just ctx.)

[SEAPUNK]

~~Q: Route parameters (rack/:name/edit)? A: Named parameters are required, and their name is applied to data.~~

[SEAPUNK]

Q: Express-style routes, or simpler routes? A: #3

[SEAPUNK]

Q: Names: Do they start with a /, or start with no /? A: They start with a slash. This is to provide compatibility with Koa libs.

Things to consider when deciding:

• Mounting PCB apps on top of PCB apps.
• Mounting routers on top of routers.