Content-recommender NPM

content-recommender

A content recommendation system for Node.js based on Pearson correlation.

Creates unique UUIDs for each user visiting a website and stores in in localStorage
Keeps a log of each users page visits in a database. Currently supports fs and MongoDB
Calculates recommendations for paths to recommend new users based on similar users' visits

Installation

npm install content-recommender

Importing

Server

const contentRecommender = require('content-recommender/server');

Client

import contentRecommender from 'content-recommender/client';

Setup examples

Server

Client (Coming soon..)

Pure JavaScript
React.js
Next.js

API

client.setId(localStorageKey)

Creates a random UUID for the current user, stores it to localStorage and returns it. If there already is a UUID, it is not changed.

Parameters

Parameter	Description	isRequired	Default value
localStorageKey: string	Key to be used to store user IDs in localStorage	false	'cr-id'

Return value

A string containing the user ID, e.g. '653d4b67-7aca-4ceb-ae1a-9f1d73573e01'

client.addPageVisit(options)

Sends an HTTP request to the server with all the required information to store the page visit. Meant to point to an endpoint utilizing server.addPageVisitFs(options) or server.addPageVisitMongo(options)

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.baseUrl: string	Base of the server URL, e.g. 'http://myapi.com'	true	undefined
options.currentPath: string	Pathname of the current page	false	window.location.pathname
options.localStorageKey: string	Key that was used to store used IDs in localStorage	false	'cr-id'
options.apiEndPoint: string	The server endpoint that receives to HTTP request	false	'/pageVisit'
options.userIdParameterName: string	Key to be used in query parameters for the user ID	false	'userId'
options.pathParameterName: string	Key to be used in query parameters for the current path	false	'path'
options.fetchOptions: object	Options that will be directly passed to fetch()*	false	{ method: 'GET' }

* = content-recommender internally uses the fetch API options.fetchOptions is passed directly to fetch function call: fetch(url, fetchOptions)

Return value

Response object directly from await fetch()

client.getRecommendation(options)

Gets a content recommendation for the current user from the server. Meant to point to an endpoint utilizing server.getRecommendationFs(options) or server.getRecommendationMongo(options)

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.baseUrl: string	Base of the server URL, e.g. 'http://myapi.com'	true	undefined
options.currentPath: string	Pathname of the current page. Used to filter out current path from recommendations	false	window.location.pathname
options.localStorageKey: string	Key was is used to store used IDs in localStorage	false	'cr-id'
options.apiEndPoint: string	The server endpoint that receives to HTTP request	false	'/getRecommendation'
options.userIdParameterName: string	Key to be used in query parameters for the user ID	false	'userId'
options.pathParameterName: string	Key to be used in query parameters for the current path	false	'currentPath'
options.fetchOptions: object	Options that will be directly passed to fetch()*	false	{ method: 'GET' }

* = content-recommender internally uses the fetch API options.fetchOptions is passed directly to fetch function call: fetch(url, fetchOptions)

Return value

An object containing pathnames and scores for each path:

{
  "/blog/somePost": 0.92212312,
  "/blog/otherPost": 0.12227173,
  "/blog/yetAnotherPost": -0.28388191
}

The score is a value between -1 and 1. The larger the score is, the more recommendation system thinks that path is a good recommendation for the user.

If the database is empty, has less than 3 users, or none of the users have visited paths that are not the user's current path, an empty object is returned

server.addPageVisitFs(options)

Reads the database, adds an entry for a page visit and writes it back to the database.

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.userId: string	The user ID of the current user	true	undefined
options.path: string	The current path of the user to be stored to database	true	undefined
options.readFromDatabase: function	A function that returns the entire database containing page visits for all users	true	undefined
options.writeToDatabase: function	A function that writes the entire to the database	true	undefined

Return value

An object containing the updated database:

{
  "user1": {
    "/blog/somePost": 2,
    "/blog/otherPost": 21,
    "/blog/yetAnotherPost": 2
  },
  "user2": {
    "/blog/somePost": 12,
    "/blog/otherPost": 1,
    "/blog/yetAnotherPost": 212
  }
}

server.getRecommendationFs(options)

Calculates the confidence scores based on how much the system thinks a specific path should be recommended to the current user

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.userId: string	The user ID of the current user	true	undefined
options.readFromDatabase: function	A function that returns the entire database containing page visits for all users	true	undefined
options.currentPath: string	The current path of the user. Is provided, gets filtered out from the recommendation	false	undefined
options.amount: number	Amount of paths the recommendation should contain	false	10

Return value

An object containing pathnames and scores for each path:

{
  "/blog/somePost": 0.92212312,
  "/blog/otherPost": 0.12227173,
  "/blog/yetAnotherPost": -0.28388191
}

The score is a value between -1 and 1. The larger the score is, the more recommendation system thinks that path is a good recommendation for the user.

server.addPageVisitMongo(options)

Writes an entry for a page visit for a user to the database.

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.userId: string	The user ID of the current user	true	undefined
options.path: string	The current path of the user to be stored to database	true	undefined
options.UserModel: function	The mongoose model for a User in database	true	undefined

Return value

Newly updated user as an object

server.getRecommendationMongo(options)

Calculates the confidence scores based on how much the system thinks a specific path should be recommended to the current user

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.userId: string	The user ID of the current user	true	undefined
options.UserModel: function	The mongoose model for a User in database	true	undefined
options.currentPath: string	The current path of the user. Is provided, gets filtered out from the recommendation	false	undefined
options.amount: number	Amount of paths the recommendation should contain	false	10

Return value

An object containing pathnames and scores for each path:

{
  "/blog/somePost": 0.92212312,
  "/blog/otherPost": 0.12227173,
  "/blog/yetAnotherPost": -0.28388191
}

server.calculateRecommendationsMongo(options)

Calculates the recommendations for each user in the database at once and stores them in the database

Parameters

Parameter	Description	isRequired	Default value
options: object		true	undefined
options.UserModel: function	The mongoose model for a User in database	true	undefined
options.amount: number	Amount of paths the recommendations should contain	false	10