@nearform/commentami-backend-core

    1.0.5 • Public • Published

    @nearform/commentami-backend-core

    @nearform/commentami-backend-core is the low level library used by @nearform/commentami-backend-hapi-plugin. This library manages the CRUD actions for comments.

    Install

    To install via npm:

    npm install @nearform/commentami-backend-core
    

    Model

    In @nearform/commentami-backend-core a comment is an obejct with the following properties

    Comment {
      id, // int
      resource, // long string
      reference, // string
      content, // text
      author, // optional, Object {username: string}
      mentions, // array of identifiers found in the comment content (@<identifier>) returned by default with the format [{username: string}]
      createdAt // date
    }
    

    The main idea is that a comment belongs to a resource (ie: a web page) and to a reference (ie: paragraph, subsection of the page).

    The resource and the reference are loosly defined to accomodate different interpretations, but a comment needs both to be specified.

    Last but not least, the mentions property is a list of mentions (@<identifier>) found in the comment content when it is added or updated.

    Usage

    To access the CRUD functions you need to initialize the module with an object that has the same interface of a Pool from node-postgres.

    const { config, buildPool, buildCommentsService } = require('@nearform/commentami-backend-core')
     
    const commentService = buildCommentsService(buildPool(config.pg))

    To configure the postgres connection parameters you can user the following env variables

    NF_COMMENTS_PGHOST
    NF_COMMENTS_PGUSER
    NF_COMMENTS_PGDATABASE
    NF_COMMENTS_PGPASSWORD
    NF_COMMENTS_PGPORT
    

    or if you already have a pool object or anything else that exposes the same interface, you can pass it directly

    const { buildCommentsService } = require('@nearform/commentami-backend-core')
    const myDbClient = //...
     
    const commentService = buildCommentsService(myDbClient)

    commentService exposes the following functions

    commentService.add
    commentService.get
    commentService.update
    commentService.delete
    commentService.list
    commentService.listOnlyReferences
    commentService.getInvolvedUsers

    and provide events for when a comment is added, updated or deleted.

    To add a listener to any of this events follow this example:

    // build your commentService object
     
    const { buildCommentsService } = require('@nearform/commentami-backend-core')
    const myDbClient = //...
     
    const commentService = buildCommentsService(myDbClient)
     
    // add listeners
     
    commentService.on('add', (comment) => { // do something })
    commentService.on('update', (comment) => { // do something })
    commentService.on('delete', (comment) => { // do something })

    commentService interface

    commentService.list

    The list function accepts the following parameters:

    • resource: it is mandatory and if not provided will result in a response with an empty list of comments.
    • reference: this parameter can be null or omitted.
    • options: this parameter can be omitted, if not, it can contain limit (defaults to 100) and offset (defaults to 0).

    The list will filter the comments based on resource and reference (if provided) and implements a pagination system based on the limit and offset parameters.

    async function myFn () => {
      // ...
      const list = await commentsService.list(resource, reference, { limit: 50, offset: 15 })
     
      // list object
      //
      // {
      //   comments: [ ... ],
      //   total: 10,
      //   limit: 50, <== defaults to 100
      //   offset: 15 <== defaults to 0
      // }
    }

    commentService.listOnlyReferences

    The listOnlyReferences function accepts only one parameter: a resource.

    This function will return the list of references (strings) for the specified resource.

    async function myFn () => {
      // ...
      const list = await commentsService.listOnlyReferences(resource)
     
      // list object
      //
      // {
      //   resource: '...',
      //   references: ['ref1', 'ref2', ...]
      // }
    }

    commentService.add

    async function myFn () => {
      // ...
      const comment = {
        resource: 'some-resource',
        reference: 'some-reference',
        content: 'some content, notify @test!',
        author: 'author' // optional
      }
      const created = await commentsService.add(comment)
     
      // ...
    }

    commentService.get

    async function myFn () => {
      // ...
      const comment = await commentsService.get(id)
      // ...
    }

    commentService.update

    The only field that will be updated is the content, no other field can be modiefied.

    async function myFn () => {
      // ...
      const comment = await commentsService.update(id, {
        content: 'some new content'
      })
      // ...
    }

    commentService.delete

    When deleting a comment, the result will be either null (id not valid, comment not found) or the deleted comment object

    async function myFn () => {
      // ...
      const deletedComment = await commentsService.delete(id)
      // ...
    }

    commentService.getInvolvedUsers

    To have a list of usernamens that have written a comment on the same resource/reference

    const involvedUsers = await commentsService.getInvolvedUsers(comment)

    Hooks

    When the application fetches one or more comments or involved users, you can hook into the process to add domain specific data to them.

    To do so, you can specify 3 optional functions when initializing the commentService.

    const commentService = buildCommentsService(dbConn, {
      fetchedComment: [async] (comment) => {
        // add your data to the comment ...
     
        return comment // or a promise that will yield the enached comment
      },
      fetchedComments: [async] (commentsList) => {
        // add your data to the commentsList ...
     
        return commentsList // or a promise that will yield the enached commentsList
      },
      involvedUsers: [async] users => {
        // add your data to the involved users ...
        return users // or a promise that will yield the enached involved users
      }
    })

    Development

    Initializing the db

    To initialize the db you can run:

    npm run pg:test:init
    

    This will drop the comments_test database if it exists. Re-create it and migrate it to the latest schema.

    For local development there should be sensible defaults in config/index.js.

    Postgres on Docker?

    If you want to run postgres on docker, install docker and run the following command

    docker-compose up postgres
    

    Run tests

    Once the db is up and initialized, run

    npm test
    

    To run a single test you can use the following command

    npx lab <test/to/run.js> // (ie: npx lab test/lib/comments.test.js)
    

    License

    Copyright nearForm Ltd 2018. Licensed under Apache 2.0 license.

    Keywords

    none

    Install

    npm i @nearform/commentami-backend-core

    DownloadsWeekly Downloads

    2

    Version

    1.0.5

    License

    Apache-2.0

    Unpacked Size

    50 kB

    Total Files

    20

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar