@seneca/vote
A voting plugin for Seneca.js
Contents:
Requirements
The following Seneca plugins must be plugged in before this plugin can be used:
- seneca-entity
- seneca-promisify
Normally, your code would look like this:
const Seneca = require('seneca')
const Entities = require('seneca-entity')
const SenecaPromisify = require('seneca-promisify')
const VotePlugin = require('@seneca/vote')
Seneca()
.use(Entities)
.use(SenecaPromisify)
.use(VotePlugin)Message Handlers
Action Descriptions
Upvote Action
Pattern
sys:vote,vote:up
Params
- fields.poll_id_ : ID!
The ID of the poll to upvote on.
- fields.voter_id_ : ID!
The ID of the voter.
- fields.voter_type_ : "sys/user"!
The type of the voter. Currently only "sys/user" is supported.
- fields.save_poll_rating_to_ : { [k : EntityName!] => ID! }?
Specifies the entity name and the id to denormalize the new poll rating to. Used
in tandem with the dependents plugin option.
Description
Creates an upvote for a poll. If the voter has already downvoted on the poll,
the downvote will be replaced by an upvote. On success, the number of upvotes
and downvotes are counted and included in the response.
If the dependents plugin option is used, the new poll rating will be saved to
the entity with the given id in the save_poll_rating_to argument.
Responses
Upon successful upvote:
{ ok: true, data: { num_upvotes: Int!, num_downvotes: Int! } }Upon failed validation of the request params:
{
ok: false,
why: String,
details?: { path: Array<Any>?, why_exactly: String? }
}When the poll does not exist:
{ ok: false, why: String, details?: { what: String? } }Downvote Action
Pattern
sys:vote,vote:down
Params
- fields.poll_id_ : ID!
The ID of the poll to upvote on.
- fields.voter_id_ : ID!
The ID of the voter.
- fields.voter_type_ : "sys/user"!
The type of the voter. Currently only "sys/user" is supported.
- fields.save_poll_rating_to_ : { [k : EntityName!] => ID! }?
Specifies the entity name and the id to denormalize the new poll rating to. Used
in tandem with the dependents plugin option.
Description
Creates an downvote for a poll. If the voter has already upvoted on the poll,
the upvote will be replaced by a downvote. On success, the number of upvotes
and downvotes are counted and included in the response.
If the dependents plugin option is used, the new poll rating will be saved to
the entity with the given id in the save_poll_rating_to argument.
Responses
Upon successful downvote:
{ status: "success", data: { num_upvotes: Int!, num_downvotes: Int! } }Upon failed validation of the request params:
{
ok: false,
why: String,
details?: { path: Array<Any>?, why_exactly: String? }
}When the poll does not exist:
{ ok: false, why: String, details?: { what: String? } }Open Poll Action
Pattern
sys:vote,open:poll
Params
- fields.title_ : string!
The title of the poll.
Description
Creates a new poll with the given title. If a poll with the given title already
exists, then action will nontheless succeed, but a new poll will not be created.
On success, the poll data is returned.
Responses
Upon success:
{
status: "success",
data: {
poll: {
id: ID!,
title: String!,
created_at: Date!,
updated_at: Date?
}
}
}Upon failed validation of the request params:
{
ok: false,
why: String,
details?: { path: Array<Any>?, why_exactly: String? }
}Get Poll Action
Pattern
sys:vote,get:poll
Params
- poll_id_ : ID!
The ID of the poll to get.
Description
Upon success, returns the poll data. Returns an error message if the poll with
the given ID does not exist.
Responses
Upon success:
{
status: "success",
data: {
poll: {
id: ID!,
title: String!,
created_at: Date!,
updated_at: Date?
}
}
}Upon failed validation of the request params:
{
ok: false,
why: String,
details?: { path: Array<Any>?, why_exactly: String? }
}When the poll does not exist:
{ ok: false, why: String, details?: { what: String? } }Plugin Options
dependents - By default, this option is not set. An example of the set option
would look like this:
seneca.use(SenecaVote, {
dependents: {
'red': { // <-- this value represents a `kind` of a vote
'mars': { // <-- this value represents a `code` of a vote
totals: {
'sys/poll': { // <-- this is the the entity to save the poll rating to
field: 'rating' // <-- this is the field of the entity to save the poll rating to
}
}
}
}
}
})When the option is set, certain message handlers, when receiving a vote
submission with the kind and code in the message matching those specified
in the plugin options, will denormalize (i.e. save) the poll rating. The poll
rating will be denormalized (i.e. saved) to the field of the entity - both the
field and the entity specified in the plugin options. The id of the entity that
the rating will be denormalized to, will have to be passed via the message,
along with the kind and code.
For more information on message handlers that support such denormalization,
please consult the documentation on the message handlers.
Dev Scripts
$ npm test
Runs the automated tests.
$ npm run check-coverage
Generates a test coverage report.
$ npm run reset
Sometimes when the project starts acting weird, the first go-to solution may be
to go ahead and refresh (i.e. reinstall) the packages used in the project. This
command does just that.
$ npm run clean
Normally this command is not meant to be invoked explicitly, and is generally
meant for consumption by other scripts in the project.