What should the API look like?

[christianbundy]

I've experienced lots of confusion working with SSB-Validate, and have often found myself wondering how it should be build.

For example, some methods mutate state but others don't, forcing you to read the API docs and sometimes mutate state... or be careful because SSB-Validate is going to mutate state without your permission.

Before

const validate = require("ssb-validate");
let state = validate.initial()
validate.append(state, hmacKey, message); // Mutates state
validate.append(state, hmacKey, message2); // Mutates state
validate.append(state, hmacKey, message3); // Mutates state

writeToDatabase(state).then(() => {
  state.queue = []
});

After

Maybe something like:

const validate = require("ssb-validate");

// Internally managed `state` and `hmacKey`.
const validator = validate.createValidator({ state: previousState, hmacKey });

// Simple append.
validator.append(message);

// Simple batch support.
validate.append(message2, message3);

// Internally managed `state.queue`.
validator.flush((messages) => {
  return writeToDatabase(messages);
});

[davegomez]

@christianbundy, when I first read the ssb-validate API, my first thought was, why is it a responsibility of the validator to append and write to the database the validated messages?

Shouldn't it be the user's responsibility to determine how to gather and store the messages?

[arj03]

Looks good @christianbundy. I've also noticed that the state.queue = [] feels really icky.