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

ablab

v0.0.5

Published

A simple library for enabling experimentation.

Downloads

12

Readme

ablab build-test-and-publish

A simple library for enabling experimentation.

This library primarily offers experiment bucketing and defines a schema for experiments using a JSON based config.

ablab sample gif

Usage

import { createExperimenter } from 'ablab';

const experimentConfig = {
    "changing the button color": {
        variations: {
            treatment: {
                traffic: 50,
                data: {
                    color: "yellow",
                    textColor: "black"
                }
            },
            control: {
                traffic: 50,
                data: {
                    color: "blue",
                    textColor: "white"
                }
            }
        }
    },
    "make the animation slower": {
        variations: {
            treatment: {
                traffic: 50
            },
            control: {
                traffic: 50
            }
        }
    }
};

const experimenter = createExperimenter(experimentConfig);
const buttonColorExperimentAssignment = experimenter.getVariationForExperiment('changing the button color', 'unique-id');
const uniqueIdVariationAssignments = experimenter.getVariationsForUniqueId('unique-id');

console.log(JSON.stringify(uniqueIdVariationAssignments, null, '\t'));
/**
{
	"changing the button color": {
		"variationName": "control",
		"variationData": {
			"color": "blue"
		}
	},
	"make the animation slower": {
		"variationName": "treatment",
		"variationData": {}
	}
}
*/

console.log(JSON.stringify(buttonColorExperimentAssignment, null, '\t'));
/**
{
	"variationName": "control",
	"variationData": {
		"color": "blue"
	}
}
*/

Integration Paths

CommonJS (CJS)

const ablab = require('ablab');

Example:
https://runkit.com/rcasto/60594414fd115c00131ebeee

ES

import { createExperimenter } from 'ablab';

or

    <script type="module">
        // may want to do dynamic import with this approach instead
        import { createExperimenter } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/es/ablab.js';
    </script>

type="module" script variant has same mechanics as IIFE or script tag example directly below.

IIFE / script tag

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/iife/ablab.min.js"></script>

Example:
https://codepen.io/rcasto/pen/oNBNdON?editors=0010

Note: Browser globabl is ablab

Experiment Schema

interface VariationData {
    [customKey: string]: any;
}

interface VariationSettingsObject {
    traffic: number;
    data?: VariationData;
}

declare type VariationSettings = number | VariationSettingsObject;

interface ExperimentSettings {
    inactive?: boolean;
    variations: {
        [variationName: string]: VariationSettings;
    };
}

export interface ExperimentConfig {
    [experimentName: string]: ExperimentSettings;
}

/**
 * Example experiment config */
/* 
{
    "changing the button color": {
        "variations": {
            "treatment": {
                "traffic": 50,
                "data": {
                    "color": "yellow"
                }
            },
            "control": {
                "traffic": 50,
                "data": {
                    "color": "blue"
                }
            }
        }
    },

    "make the animation slower": {
        "variations": {
            "treatment": 50,
            "control": 50
        }
    }
}
*/

API

declare type VariationAssignment = null | {
    variationName: string;
    variationData: VariationData;
};

interface VariationAssignmentMap {
    [variationName: string]: VariationAssignment;
}

interface Experimenter {
    getVariationForExperiment: (experimentName: string, uniqueId: string) => VariationAssignment;
    getVariationsForUniqueId: (uniqueId: string) => VariationAssignmentMap;
}

interface InvalidExperimentReasons {
    invalidReasons: string[];
    variations?: {
        [variationName: string]: string[];
    };
}

interface InvalidExperimentReasonsMap {
    [experimentName: string]: InvalidExperimentReasons;
}

export declare function validateExperimentConfig(experimentConfig: ExperimentConfig): InvalidExperimentReasonsMap;
export declare function createExperimenter(experimentConfig: ExperimentConfig): Experimenter | null;

Brief summary of concepts/thinking

Main concept of the API is that you have declared an experiment config that you store somewhere and this contains the truth representing your experiment configuration

The API for this libary then gives you the ability to validate this experiment config for errors and then if no errors exist create an "experimenter" from it.

An "experimenter" is simply an instance that retains your experiment config internally and allows you to then get the assigned variation for an experiment or all experiments tied to a particular unique id that you provide. This unique id can represent anything you want it to, such as a user id, or just completely random, whatever.

Note: You can view the complete raw typings at:
https://cdn.jsdelivr.net/npm/[email protected]/dist/index.d.ts

Scope of this project

Configuration should support:

  • Multiple experiments
    • Also, of course, multiple variations per experiment
  • Turn experiment on/off
    • Experiments are enabled by default
    • Experiments do support being inactivated though, or turned off
  • Specifying variations A/B/C/.... and their traffic allocation
    • Variations support custom naming
    • Variations support associated custom data
    • Traffic allocation is on a percentage scale or (0 -> 100)
    • Support to 2nd decimal precision, ex) 33.33

Not in scope for this project

  • Audience qualifcations
    • Integrator can select logic of when or the conditions of when to run experiment assignment
  • Supporting multiple environments (dev/staging/prod)
    • Integrator (at least for now) can make sure to use different experiment configs themselves or such
  • Supporting sticky (uniqueId, experimentName) => variatonName
    • Integrator can choose to maintain an external (uniqueId, experimentName) => variation name cache
  • Does not (at least currently) support auto reloading/fetching the experiment config
    • Integrator can select/schedule the cadence at which they want to update their experiment config