Nonstop Pajama Models

    fs-persistent

    1.2.2 • Public • Published

    fs-Persistent

    A simple tool inspired in localStorage.

    Description

    Store anything quickly, retrieve it quickly. It will be there beyond runtime.

    Uses filesystem to store, not suitable for productive database but it does well for testing purposes.

    Simple usage

    Just require, instantiate and extract the methods you will use.

    const persistent = require("fs-persistent");
    const { setItem } = persistent();
     
    var user = {
      name: "Foo",
      email: "foo@bar.com",
    };
    setItem("aUser", user); // user object is stored persistently in the filesystem

    Two lines or many years later...

    const persistent = require("fs-persistent");
    const { getItem, removeItem } = persistent();
     
    // You can retrieve the stored item anytime later simply by using the same key
    var aCopyOfTheUser = getItem("aUser");

    or if you are not going to need it anymore...

    // You can delete the stored item
    removeItem("aUser");

    There is more

    You can use baseDir argument in persistent to acomplish data partition.

    const persistent = require("fs-persistent");
    const users = persistent("users");
     
    // This will be saved in ./users/
    users.setItem("current", { name: "Cipriano", lastname: "Reyes" });

    You can instantiate multiple persistent instances with different routes. They can be nested.

    const persistent = require("fs-persistent");
    const orders = persistent('orders');
    const orders.closed = persistent('orders/closed'); // You can nest
    const orders.open = persistent('orders/open'); // it can be very useful
     
    var myOrder = new Order();
     
    orders.setItem("myLast", myOrder);
    orders.open.setItem("myLast", myOrder);

    The above code generates this filesystem tree

    .
    +-- orders
    |   +-- closed
    |   +-- open
    |   |   +-- myLast.json
    |   +-- myLast.json
    

    Then...

    const persistent = require("fs-persistent");
    const orders = {
      closed: persistent('orders/closed'),
      open: persistent('orders/open')
    };
     
    // When order is closed
    orders.closed.setItem("myLast",orders.open.getItem("myLast");
    orders.open.removeItem("myLast");

    Methods

    setItem(key, data)

    • key String: Any name you want to give it.
    • data Any: The data to store.
    • async Bool: (Optional) When true the filesystem write operation is made async. Default false (sync write). Note: Async is better for example in a mass data storage process or when you need to speed up response time. But it will not work if used immediately before a getItem() call.

    Returns

    • data Any: The same data.

    getItem(key)

    • key String: The stored key.

    Returns

    • data Any: The retrieved data.

    removeItem(key)

    • key String: The stored key.

    Returns

    • null

    Using a Reviver

    A reviver is a type of callback function that can transform the values parsed by JSON engine. It is intended to "bring back to life" (revive) actual objects by giving you an instance to rejoin properties (data stored as JSON) with methods (alive at runtime).

    Use the reviver argument of persistent to pass the callback function.

    const persistent = require('fs-persistent')
    const persistentWithReviver = persistent('testReviver', (key, value) => {
        if (Number(value) === value) {      // You can apply conditions on *values* 
            return value * 2
        } else if (key === 'secretValue') { // or on *keys*
            return 'XXXXXX'
        } else if (key === 'revivedAt') {   // to transform the returning value
            return (new Date()).toISOString()
        }
        return value   // Or just return the original value
    })

    You can store any data, and it will pass trough the reviver when you retrieve it.

    // some dummy Object
    const testObject = {
        name: 'John',
        age: 34,
        heigth: 1.78,
        email: 'john@foos.com',
        secretValue: 'A1B2C3D4E5F6',
        revivedAt: null
    }
     
    // some dummy Array
    const testArray = [2, 3, 5, 8, 13, 'fooBar']
     
     
    persistentWithReviver.setItem('obj', testObject, true)
    persistentWithReviver.setItem('arr', testArray, true)
     

    let's see the result of getItem for "obj" compared with testObject

    const newObject = persistentWithReviver.getItem('obj')
    console.log(testObject);
    /* Outputs:
    {
        name: 'John',
        age: 34,
        heigth: 1.78,
        email: 'john@foos.com',
        secretValue: 'A1B2C3D4E5F6',
        revivedAt: null
    }
    */
    console.log(newObject);
    /* Outputs:
    {
        name: 'John',
        age: 68,
        heigth: 3.56,
        email: 'john@foos.com',
        secretValue: 'XXXXXX',
        revivedAt: '2020-10-29T12:47:27.831Z'
    }
    */

    let's see the result of getItem for "arr" compared with testArray

    const newArray = persistentWithReviver.getItem('arr')
    console.log(testArray);
    /* Outputs:
    [ 2, 3, 5, 8, 13, 'fooBar' ]
    */
    console.log(newArray);
    /* Outputs:
    [ 4, 6, 10, 16, 26, 'fooBar' ]
    */

    Author

    Lautaro Capella

    License

    MIT © Lautaro Capella

    Install

    npm i fs-persistent

    DownloadsWeekly Downloads

    9

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    9.28 kB

    Total Files

    4

    Last publish

    Collaborators

    • cape-