Notary Public Mystifier


    0.2.0 • Public • Published

    So Annoying

    Create annoying behaviors for sweet conversions. This library makes it easy to implement conditionally activated pop-ups, call-outs, etc.


    npm version Build Status


    npm install --save so-annoying

    Quick Guide

    1. Import

    Import the module.

    import { annoy } from 'so-annoying'

    2. Create an annoyance

    annoy('newsletter-signup-2018-02', async () => {
      const email = window.prompt('Give us your email address.')
      // Perform some async action.
      await sendEmailToServer(email)
      // The return value is saved with the cookie. If the function doesn't return,
      // the cookie is not set.
      return email

    3. That's it!

    By default, your annoyance will be run once until the cookie expires (14 days by default).

    Advanced Usage


    The shouldAnnoyIfCookiePresent option allows you to run the annoyance even if a cookie with the key is present. By default, this option always returns false (i.e. the annoyance should not be run if the cookie is present).

    If you want to conditionally run the annoyance, provide a function that returns a boolean. The function receives the existing cookie value set from the previous occurance.

      async existingEmail => {
        const message = existingEmail
          ? `Come back, ${existingEmail}!`
          : 'Give us your email address.'
        const email = window.prompt(message)
        await sendEmailToServer(email)
        return email
        shouldAnnoyIfCookiePresent: async email => await isUserSubscribed(email),

    Using the existing cookie value

    The existing cookie value is provided as the only argument to annoyance.

    // Example here...

    The existing cookie value is also provided to the shouldAnnoyIfCookiePresent option. This allows you to conditionally run the annoyance even if the cookie is present.

    // Example here...

    Using Promise (or async/await)

    The return value of the annoyance is used as the cookie value when it is set. If some type of async action needs to take place during the annoyance, you can utilize a Promise or async/await to control when the cookie is set.

    // Example here...


    annoy(key, annoyance, [options])

    Run an annoying function if the user is new.

    • key (string): Unique key to track the annoyance
    • annoyance (function): Function to conditionally run. Return value is saved with the cookie. Existing cookie is passed to the function. If the function returns a Promise, the cookie will not be set until the Promise resolves.
    • options (object): Includes all cookie options from RFC 6265
      • shouldAnnoyIfCookiePresent (function): Function to determine if the annoying function should be run even if the cookie is present. The cookie is passed as the first argument. If the function returns a Promise, the annoyance is not run until the Promise resolves.
      • path (string): Cookie path, use / as the path if you want your cookie to be accessible on all pages.
      • expires (Date): Absolute expiration date for the cookie.
      • maxAge (number): Relative max age of the cookie from when the client receives it in seconds.
      • domain (string): Domain for the cookie ( or
      • secure (boolean): Is only accessible through HTTPS?
      • httpOnly (boolean): Is only accessible by HTTP(S)?


    npm i so-annoying

    DownloadsWeekly Downloads






    Unpacked Size

    117 kB

    Total Files


    Last publish


    • angeloashmore