npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

retention

v1.3.3

Published

Build retention matrix, render table or chart with data

Downloads

37

Readme

📉 Retention

Calculate user retention matrix and render table or chart with data

NpmVersion npm npm bundle size (minified + gzip)

What?

This library calculates retention metric, which answers the question: how many users1 that registered2 in a given week3 were active4 in the following weeks. In other words, how soon and how many users are abandoning you product/app or some specific feature.

1. or accounts, or instances; 2. or started trial, or enabled some feature; 3. or in any other time range; 4. or did some specific action

Why?

Some services (e.g. keen.io) don't have built in tool or API to calculate retention metric, so you have to do it on your own. Existing tools, like keen.io's cohort builder, are usually locked into specific provider and are not very flexible - for example I needed something where I can use multiple events to determine the "active" user.

How?

You have to provide two kinds of data sets. First, an Array of events that define your "registered" actions, i.e. initial events. Every event is an Object with date and id props:

[
  {
    id: 'b7f1181a',
    date: '2018-02-19T16:57:12.188Z'
  }
  // ...more events
];

The second data set is an Array of user IDs that were active in a given time range. You have to provide this for every time range you want to calulate, i.e. if you want retentnion for the last four weeks, you should provide four Arrays like this:

[
  '855fc7a1',
  '5c8325a9',
  '2a26adea',
  '6623141d',
  '269f7d39',
  '832c4038',
  'b7f1181a'
  // ...more IDs
];

And that's it. The buildMatrix function will return a retention matrix that looks like this:

[
  {
    range: {
      from: '2018-02-01T00:00:00.000Z',
      to: '2018-02-07T23:59:59.999Z'
    },
    cohort: [
      { id: 'b7f1181a', date: '2018-02-19T16:57:12.188Z' }
      // ...more IDs
    ],
    activity: [
      {
        activeCount: 757,
        percentage: 74,
        active: [
          {
            id: 'b7f1181a'
            // events: [ 'action-a', 'action-b ]
          }
          // ...more IDs
        ]
      }
      // ...more time ranges
    ]
  }
  // ...more time ranges
];

You can specify more than one Array of active users for every time range (e.g. for different actions they're performing, see below) and it will be included in every object in the active array in the events property.

Both renderTable and renderChart functions take this matrix plus some configuration options as input.

Regarding performance, it calculates and renders both table and chart in a reasonable time (<1s) on a Macbook Pro for up to ~20k unique user IDs (4 week retention). However, in such case I recommend to move the matrix calculation to some back-end service or pre-compute it offline. But let's be honest, if you have more than 20k unique users per month you wouldn't be using this simple library that I wrote over the weekend, would you? 🤔

Installation

$ npm i retention

D3 and C3 libraries are not included in the bundle, you have to install them separately.

ES6 modules

import { buildMatrix, renderTable, renderChart } from 'retention';

CommonJS

const { buildMatrix } = require('retention');

Notice: Because CJS modules are almost always used in NodeJS backend code (Webpack or Rollup should automatically use UMD or ESM version), this version includes only buildMatrix function, no rendering functions. If you want those you should probably explicitly include the UMD version:

const { buildMatrix, renderTable, renderChart } = require('retention/dist/retention.umd.js');

Browser

<script src="https://cdn.jsdelivr.net/npm/retention@latest"></script>
<script>
    const { buildMatrix, renderTable, renderChart } = Retention;
</script>

CSS

There's also a simple CSS file which adds some styling to the table:

<link href="https://cdn.jsdelivr.net/npm/retention@latest/dist/retention.min.css" rel="stylesheet" />

Sample

Clone the repo, install dependencies, build the bundle, and start a simple web server with these commands:

git clone https://github.com/marszall87/retention.git
cd retention
npm install
npm run build
npm run sample

Navigate to http://localhost:5000/sample and you should see a sample retention chart and table.

API

buildMatrix(opts)

Returns promise with retention matrix object.

opts.dateRanges - Array of { from, to } objects that defines date ranges for cohorts, if not specified it's 4 last weeks

opts.getInitialEvents - function that should return a promise with Array of objects with two props: date and id, date represents

opts.getActivity - function or object in form of { eventsA: () => {...}, eventsB: () => {...} }, functions take three args: start date, end date and index of a given cohort date range, should return an Array of ids that were active in that time

generateRanges(opts)

Helper function that generates cohor date ranges.

opts.endingDate - ending date of the last (most recent) cohort, end of the current day by default

opts.daysInRange - number of days in every date range, default is 7

opts.rangeCount - number of date ranges to generate, 4 by default

renderTable(opts)

opts.container - container in which the table will be rendered

opts.matrix - retention matrix as returned by buildMatrix()

renderChart(opts)

opts.container - container in which the chart will be rendered

opts.matrix - retention matrix as returned by buildMatrix()

opts.options - options passed directly to c3.generate function, can be used to modify the chart, full list of options available in C3 docs.

License

MIT © Michał Nykiel