Nifty Pony Merchandise


    0.10.0 • Public • Published

    Build Status


    jsTodoTxt is a library for working with todo.txt formatted files in JavaScript.


    jsTodoTxt attempts to match the todo.txt format exactly.

    To do so, I've written 50+ tests using the Jasmine library.


    There are two ways to work with jsTodoTxt (hint: they overlap)

    The TodoTxtItem Class

    The class TodoTxtItem encapsulates the core of the library.

    Data Members

    These are all the data members available on an item:

    text      // The core text of the item
    priority  // The priority level of the item as string [A-Z]
    complete  // Boolean
    completed // Date completed
    date      // Date attached to object, typically with a comlete item
    contexts  // Array, contexts for the object, e.g. @Home == "Home"
    projects  // Array, projects fot the object, e.g. +Chores == "Chores"


    Create a new item, protentially loading it from a string.

    // Fresh new item!
    var newItem = new TodoTxtItem();
    newItem.text = "Cool!";
    // Create an item from a string
    var existingItem = new TodoTxtItem( "(A) Try out jsTodoTxt" );
    console.log( existingItem.priority ); // Logs "A"


    Render the item back to a string.

    var item = new TodoTxtItem( "(B) Try out jsTodoTxt" );
    item.priority = 'A';
    item.text = 'Try out jsTodoTxt';
    item.contexts = [ 'Computer' ];
    console.log( item.toString() );
    // Logs: "(A) Try out jsTodoTxt @Computer"
    item.complete = true;
    item.completed = new Date();
    console.log( item.toString() );
    // Logs: "x 2011-07-24 (A) Try out jsTodoTxt @Computer"


    Parse a string into the item.

    var newItem = new TodoTxtItem();
    newItem.parse( "(A) Try out jsTodoTxt" );
    console.log( newItem.priority ); // Logs: "A"

    The TodoTxt Object Literal (Static Methods)

    TodoTxt provides four utility methods:


    This method takes a block of text and does it's best to return an array of tasks, as TodoTxtItem objects.

    var items = TodoTxt.parse( big_block_of_text );
    console.log( items[0].priority )


    This method takes a single line and parses it into a single TodoTxtItem. Really, you should use the constructor.

    var item = TodoTxt.parse( "(A) Try out jsTodoTxt" );
    console.log( item.priority ); // Logs: "A"


    This method renders an array of TodoTxtItem objects to a string.

    var string = TodoTxt.render( [ ... array of TodoTxtItem objects ... ] );


    This method renders a single TodoTxtItem to string. Really, you should just use toString.

    var item = new TodoTxtItem( "(A) Learn to use toString" );
    console.log( TodoTxt.renderItem( item ) ); // Logs:  "(A) Learn to use toString"

    Addons / Extensions

    The todo.txt format specifies a simple design for addons,

    Developers should use the format key:value to define additional metadata (e.g. due:2010-01-02 as a due date). Both key and value must consist of non-whitespace characters, which are not colons. Only one colon separates the key and value.

    We support this through a mechanism we call extensions. To use an extension, you must pass it to the TodoTxtItem when initializing it.

    var item = new TodoTxtItem("Do something. due:2010-01-02", [ new DueExtension() ]);
    console.log( item.due );  // Logs: "Tue Feb 02 2010 00:00:00 GMT-0600 (Central Standard Time)"

    Implementing Your Own

    Writing your own extension consists of a parsingFunction which extracts your addon, and setting a name.

    Here's an example one for an addon that sets a color for an item in hex, color:FFFFFF.

    function ColorExtension() {
      // Set the name, this will be the property name on the TodoTxtItem. = "color";
    ColorExtension.prototype = new TodoTxtExtension();
    ColorExtension.prototype.parsingFunction = function(line) {
      // We don't have to use a regex, but it's handy for extracting the content.
      var colorRegex = /\bcolor:([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/;
      var match = colorRegex.exec(line);
      if( match !== null ) {
        // The return format is [ <value of property>, <line with addon removed>, <string of the value> ]
        return ["#" + match[1], line.replace(colorRegex, ''), match[1]];
      // Return nulls if not found.
      return [null, null, null];


    Run npm test to run the suite.

    jsTodoTxt is tested with Jasmine, a BDD framework from Pivotal Labs.

    About todo.txt

    todo.txt is a format for storing todo lists in a future-proof format.




    npm i jstodotxt

    DownloadsWeekly Downloads






    Unpacked Size

    50.9 kB

    Total Files


    Last publish


    • jmhobbs