checklist-js

A simple checklist for when you need to keep track of things presistetly

Installation

npm install checklist-js

Usage

import Checklist from 'checklist-js'

const shoppingList = [ 
  '🥚 eggs', 
  '🥩 ham', 
  '🧀 cheese', 
  '🍎 apple', 
  '🥦 broccoli' 
];

// create a checklist
const checklist = new Checklist(shopping_lits);

let eggs = await fetch('https://emojipedia.org/egg/');
// check eggs
if(eggs) checklist.check('🥚 eggs');

let ham = await fetch('https://emojipedia.org/ham/');
// check ham
if(ham) checklist.check('🥩 ham');

checklist.next() // '🧀 cheese'

checklist.next() // '🍎 apple'

// uncheck 🥚 eggs
checklist.uncheck('🥚 eggs')

/* 🥚 eggs ? */
checklist.isChecked('🥚 eggs') // false

/* 🥩 ham ? */
checklist.isChecked('🥚 eggs') // true

/*[ 
  '🥚 eggs', 
  '🧀 cheese',
  '🍎 apple',
  '🥦 broccoli',
]*/
checklist.getMissingValues();
checklist.missingLeft(); // 4

/*[ 
  '🥩 ham',
]*/
checklist.getCheckedValues()
checklist.valuesDone() // 1

/* check if all the values have been checked */
checklist.isDone() // false
checklist.isNotDone() // true

/*
false : 🥚 eggs 
true : 🥩 ham
false : 🧀 cheese
false : 🍎 apple
false : 🥦 broccoli
*/
checklist.log()

// delete the checklist in the files system
checklist.delete()

while loop usage

while(checklist.isNotDone()){
  // get the next missing value on the checklist
  let value  = checklist.next()
  // perform some operation 
  let result = await fetch('https://emojipedia.org/');
  // check the value if successful
  if(result) checklist.check(value);
}

// delete the checklist in the files system
if(checklist.isDone())
  checklist.delete()

Permenance

you can recover the same checklist by creating it again with the same values

const checklist = new Checklist([ 
  '🥚 eggs', 
  '🥩 ham',  
  '🥦 broccoli' 
]);

// check
checklist.check('🥚 eggs');
checklist.check('🥩 ham');

/*
true : 🥚 eggs 
true : 🥩 ham
false : 🥦 broccoli
*/
checklist.log()

/* after crash or diffrent file*/
const checklist = new Checklist([ 
  '🥚 eggs', 
  '🥩 ham',  
  '🥦 broccoli' 
]);

/*
true : 🥚 eggs 
true : 🥩 ham
false : 🥦 broccoli
*/
checklist.log()

the order values does not matter when recovering the checklist

/* after crash or diffrent file*/
const checklist = new Checklist([ 
  '🥦 broccoli' 
  '🥩 ham',
  '🥚 eggs', 
]);

/*
false : 🥦 broccoli 
true : 🥩 ham
true : 🥚 eggs
*/
checklist.log()

pass the name options to make it the checklist unique

let shoppingList = [ 
  '🥦 broccoli' 
  '🥩 ham',
  '🥚 eggs', 
];

const bobs_checklist = new Checklist(
  shoppingList, { name: 'bobs shoppinglist' } 
);
bobs_checklist.check(['🥩 ham', '🥚 eggs'])

const alices_checklist = new Checklist(
  shoppingList, { name: 'alices shoppinglist' } 
);
alices_checklist.check('🥦 broccoli')

recover the checklist with the name option

/* after crash or diffrent file*/
const bobs_checklist = 
  new Checklist(null, { name: 'bobs shoppinglist' });
  
/*
false : 🥦 broccoli 
true : 🥩 ham
true : 🥚 eggs
*/
bobs_checklist.log()

const alices_checklist = 
  new Checklist(null, { name: 'alices shoppinglist' });
  
/*
false : 🥦 broccoli 
true : 🥩 ham
true : 🥚 eggs
*/
bobs_checklist.log()

pass the path where to make the filesystem

  new Checklist([], { 
    name: 'my_checklist',
    path: process.cwd()
  });
  

Recalculate missing values on Check

sometime when you are working with multiple concurrent processes you don't want the completion of one process to alter the order you would get the missing vlaue

this can lead to a missing values being drawn twice after a check.

There is also the senario where you have too many values and doing recalc on every check will take too long

For this senarios you can set the option recalc_on_check to false

pass the path where to make the filesystem

  new Checklist([], { 
    recalc_on_check: false
  });
  

Adding, Removing and Checking multiple values

// add 🥓 bacon
checklist.add('🥓 bacon')
// or 
checklist.add(['🍞 Bread', '🍆 Eggplant', '🥛 Milk'])

// remove 🥚 eggs
checklist.remove('🥚 eggs')
// or 
checklist.remove(['🥩 ham', '🥓 bacon', '🍞 Bread', '🥛 Milk'])

// check 🧀 cheese
checklist.check('🧀 cheese')
// or 
checklist.check([ '🍆 Eggplant', '🍎 apple' , '🥦 broccoli'])

// uncheck 🧀 cheese
checklist.unchek('🧀 cheese')
// or 
checklist.uncheck([ '🍆 Eggplant', '🍎 apple' , '🥦 broccoli'])

OPTIONS

All options

new Checklist( values, {
        name, // name of the checklist to save

        path, // path to save the checklist at (disk only)

        recalc_on_check, // recalculate the missing values on check

        save_every_check, // save the checklist every n checks

        enqueue, // if false, do not add missing values to the end of the list

        shuffle, // if true, shuffle the values before checking

        save // if false, Checklist has no persistence. Default true
        })

MongoDB storage

Requires mongodb ≥ 5: npm install mongodb

When to use disk vs MongoDB

| | Disk | MongoDB | |---|---|---| | Setup | Zero dependencies | Requires mongodb package + running MongoDB | | Persistence | JSON file per checklist | Document in MongoDB collection | | Scraping at scale | Good for single-process | Better for high-volume, multi-session retry | | I/O | Sync, blocks process | Async, non-blocking | | Disk usage | Accumulates .json files | No disk files |

Basic configuration

MongoDB storage requires the Checklist.create() static factory (the constructor cannot perform async I/O):

import Checklist from 'checklist-js';

const companies = [
  { ruc: '1790016919001', nombre: 'EMPRESA S.A.' },
  { ruc: '0990123456001', nombre: 'Cía. Ltda.' },
  // ...
];

// Create — loads existing state from MongoDB or starts fresh
const checklist = await Checklist.create(companies, {
  storage:       'mongo',
  mongoUri:      'mongodb://localhost:27017',
  mongoDatabase: 'scraping',
  // mongoCollection: 'checklists',  // optional, default: 'checklists'
  // mongoTimeout:    5000,           // optional, default: 5000 ms
});

// All existing methods work unchanged
while (checklist.isNotDone()) {
  const company = checklist.next();
  const result  = await scrapeCompany(company);
  if (result) checklist.check(company);  // persisted to MongoDB (fire-and-forget)
}

// Always close when done — flushes pending writes + releases connection
await checklist.close();

Retry scenario (process crash / restart)

The main benefit: re-running the script after a crash resumes from where it left off — companies already scraped are skipped automatically.

// First run (or after crash)
const cl = await Checklist.create(companies, {
  storage: 'mongo', mongoUri, mongoDatabase: 'scraping', name: 'batch-2024'
});
// ... process 200 of 570 companies, then crash ...

// Retry — the 200 completed companies are still marked as done in MongoDB
const cl2 = await Checklist.create(companies, {
  storage: 'mongo', mongoUri, mongoDatabase: 'scraping', name: 'batch-2024'
});
console.log(cl2.valuesDone());   // → 200  (no re-work)
console.log(cl2.missingLeft());  // → 370  (only remaining companies)

Shared MongoClient (reuse existing connection)

If your application already manages a MongoClient, pass it directly to avoid opening a second connection. In this case close() will NOT close the client — the caller remains responsible for its lifecycle.

import { MongoClient } from 'mongodb';

const client = new MongoClient('mongodb://localhost:27017');
await client.connect();

const checklist = await Checklist.create(items, {
  storage:       'mongo',
  mongoClient:   client,          // ← existing connection
  mongoDatabase: 'scraping',
  name:          'my-batch',
});

// ... work ...

await checklist.close();  // flushes writes; does NOT close `client`
await client.close();     // caller closes when done with the whole app

MongoDB document schema

Each checklist is stored as one document:

{
  "_id":       "ObjectId(...)",
  "name":      "my-batch",
  "items":     [
    { "k": "\"item-key-1\"",      "v": true  },
    { "k": "{\"ruc\":\"...\"}",   "v": false }
  ],
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:34:56.789Z"
}

• name — unique index, used as the checklist identifier
• items — array of {k, v} pairs (k = JSON-stringified key, v = mark value)
• Keys are stored as JSON strings to safely handle objects, dots, and special characters