‚̧Nagging Penguin Matriarchs
    Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    fully-storage

    1.5.4¬†‚Äʬ†Public¬†‚Äʬ†Published

    fully-storage

    fully-storage is a simple no-sql data store with an HTTP session manager implemented , generator fixtures and more...

    Node.js CI

    installtation

    You can local install fully-storage with your handler dependencies favorite

    npm install fully-storage --save

    or with yarn

    yarn add fully-storage

    example app

    manager session inside easy todolist app

    storage nosql inside easy articles app

    fixtures API inside easy articles app

    store

    The data store and stored in folders called collections and the entries are stored in JSON files called doc inside the fully-storage collections created one file per entry. For comparison to relational database management systems, collections are tables and docs are entries.

    store usage

     
    const fullyStorage = require('fully-storage');
     

    create collection

    A collection is a new list of docs ( entries ), you can made a collections for data game of: users, commentaries, articles...

     
    fullyStorage.addCollection('users');
    fullyStorage.addCollection('articles');
     

    If collections you attempts create already exists, she are not erase, you should explicit ask erase collection for execute this action, with: fullyStorage.deleteCollection( collectionName )

    create doc

    During the exec of your app you have need add docs ( entries ) inside your collection, during post of a new article, register of new users ect...

     
    const collectionName = "article";
     
    const doc = {
     
        contentText: "Excepteur elit esse irure laborum duis sint magna.",
        imageUrl: "https://i.picsum.photos/id/237/500/500.jpg",
        createAt: Date.now()
    };
     
    const docId = fullyStorage.addDoc(
        collectionName,
        doc
    );
     
    console.log( docId );

    You can see fully storage have attribute a uniq id for doc ( number auto increment ) but your entry article have not id, you can update the doc and add the docId, but more easy give third arg with true value for fully-storage auto add id key inside your doc with the value equal to the docId.

    const collectionName = "article";
     
    const doc = {
     
        contentText: "Excepteur elit esse irure laborum duis sint magna.",
        imageUrl: "https://i.picsum.photos/id/237/500/500.jpg",
        createAt: Date.now()
    };
     
    const docId = fullyStorage.addDoc(
        collectionName,
        doc,
        true // AUTO SAVE ID
    );
     
    console.log( docId );

    You can make reference to auto save id with the constant: fullyStorage.AUTO_SAVE_ID

    const docId = fullyStorage.addDoc(
        collectionName,
        doc,
        fullyStorage.AUTO_SAVE_ID
    );
     

    get doc

    For show data inside a user interface you have needs get a specific doc or a docs list, for get a specific, you have need of the collection name and the doc id auto generate.

    You can think during a request HTTP for get a specific article,

    exemple with HTTP router express:

     
    const express = require('express');
    const app = express();
    const server = require('http').Server( app );
     
    const fullyStorage = require('fully-storage');
     
    fullyStorage.addCollection('articles');
     
    app
        .get('/article/:id', ( request, response ) => {
     
            response.type('json');
     
            const {id} = request.params;
     
            const article = fullyStorage.getDoc('articles', id);
     
            if( article ) {
     
                response.status( 200 );
     
                response.json({
                    success: true,
                    statusCode:200,
                    statusText: "Success",
     
                    data: article
                })
     
            } else {
     
                response.status( 404 );
     
                response.json({
                    success: false,
                    statusCode: 404,
                    statusText: "Not found",
                });
            }
     
        } )
    ;
     
    server.listen( 3001, () => {
     
        console.log( 'server run...' )
     
    }  );

    The method fullyStorage.getDoc return null if not found doc.

    docs list

    You can have needs get all docs of any collection for your interface, API or any sorted of data.

     
    const articles = fullyStorage.get('articles');
     
    console.log( articles );
     

    The method: get return array objects docs of collection.

    before the version 1.5.4 for get docs of collection, you should use the method: getDocsList this method return array docsname and loop docsname for get doc by docname.

     
    const articles = [];
     
    const docsname = fullyStorage.getDocsList( 'articles' );
     
    docsname.forEach( docname => {
     
        articles.push(
            fullyStorage.getDocByDocname( docname )
        );
     
    } );
     
    console.log( articles );

    The method: fullyStorage.getDocByDocname is equal to fullyStorage.getDoc but await a docname in argument 1 while fullyStorage.getDoc await collectionName and docId.

    A docname is composed of: {collectionName}-{id}.json

    And its sorted inside:

    • /node_modules/
      • / fully-storage
        • / collections
          • / {collectionName}
            • {collectionName}-{id}.json

    update doc

    During the exec of your app you can have need update a doc

     
    const article = fullyStorage.getDoc( 'articles', 0 );
     
    article.text = "Nostrud labore nisi laborum mollit proident elit dolor tempor.";
    article.lastUpdate = Date.now();
     
    fullyStorage.updateDoc( 'articles', 0, article );
     

    you can ask a update with force, if the doc and/or the collection name not exists the collection name and/or the doc is create

     
    fullyStorage.updateDoc(
     
        'articles',
        0,
        {
            text: "Reprehenderit dolore exercitation ex elit ea esse."
        },
        fullyStorage.IS_FORCE
    );

    delete doc

    You can delete a specific doc with the collection name and the doc id

     
    fullyStorage.deleteDoc( 'articles', 0 );
     

    exists

    You can make existing test on doc and collection

    exists doc

    you can test if a specific doc exists with collection name and doc id

     
    const isExists = fullyStorage.isExistsDoc( 'articles', 0 );
     
    if( isExists === true ) {
     
        console.log('hi exists');
    } else {
     
        console.log( 'hi not exists');
    }

    exists collection

    you can test if a collection exists with collection name

     
    const isExists = fullyStorage.isExistsCollection( 'articles' );
     
    if( isExists === true ) {
     
        console.log('she exists');
    } else {
     
        console.log( 'she not exists');
    }

    stat doc

    The doc is stored inside file also you can ask stat of doc as file:

    create at, last update at ...

     
    const createAt = fullyStorage.getCreateAtDoc( 'articles', 0 );
     
    const lastUpdateAt = fullyStorage.gegetLastUpdateAtDoc('articles', 0 );
     

    The time is give with timestamp ms, you can get a full stats doc with: fullyStorage.getStatDoc( collectionName, docId )

    This method return a native fs.stats object.

    delete collection

    You can delete a collection with:

    fullyStorage.deleteCollection( collectionName )

    collection list

    You can get the list of collections with attribute:

    fullyStorage.collectionsList

    apis

    In more of basic usage of fully-storage you can use a handler for specific collections, the handler automate or reduce tasks standard of a collection.

    users

    If you stock users data with fully-storage you can use a API already implemented.

    users collection

    Create a new users collection use the method

    fullyStorage.addUsersCollection( config: object )

    you should give a object config for handler of users

     
    const config = {
     
        collectionName: "users", // default: "users"
     
        // default: null
        passwordHash: {
            // currently only bcrypt is support
            hash: "bcrypt",
            cost: 13, // default: 13
        },
     
        // list keys should be uniq
        // default: []
        uniqKeys: [
            'email'
        ]
     
        // key constraints for authorize authentication
        // default: null
        constraintsAuthentication: {
     
            isRemoveAccount: false,
            isLockAccount: false,
            isValidateAccount: true
        },
     
        // api can auto generate specific key for a new user
        // default: ['id','token']
        autoGenerate: [
            'id',
            'createAt',
            'token'
        ],
     
     
    };
     
    fullyStorage.addUsersCollection( config );
     
    add user

    You can use the method: fullyStorage.addUser( user: object ) for add a new user.

     
    const user = {
        username: 'Orivoir21',
        password: 'secret ^.^',
        email: 'unicorn@gmail.com'
    };
     
    const response = fullyStorage.addUser( user );
     
    console.log( response );

    If not uniq keys have reject add user, the user will added

    response add user {
     
        success: boolean,
     
        ?user: object,
     
        ?error: string,
     
        ?uniqKeysError: string[]
    }
    authentication

    you can automate authentication user with fullyStorage.authentication( credentials: object ) method:

     
    const credentials = {
        login: 'unicorn@gmail.com',
        password: 'secret ^.^'
    };
     
    const response = fullyStorage.authentication( credentials );
     

    The login key is used as email key, if you want logged a user with a other key you can replace the key login by the real key name.

    e.g:

     
    const credentials = {
        username: 'Orivoir21',
        password: 'secret ^.^'
    };
     
    const response = fullyStorage.authentication( credentials );

    The key password with the plain password should be exists, but you can choice the login key.

    If the login password matches with any user and constraints authentication not reject authentications, its success authentication.

    response authentication {
     
        success: boolean,
        isLoginExists: boolean,
     
        ?error: string,
        ?errorMuted: string
        ?constraintsAuthentication: object
    }
    get user

    You can easy get user.s with any schema use the method:

    fullyStorage.getUsersBy( schema: object )

     
    const users = fullyStorage.getUsersBy( {
        username: "Orivoir21"
    } );
     
    console.log( users );
     

    The method: getUserBy return a array of users if 0 users have found return empty array

    fixtures

    Fixtures is a API implemented from fully-storage-faker-api you can auto generate data fixtures and auto push docs inside your storage, easy create factory data for you'r dev env

    You can use CLI for automate work fixtures

    You can see a example usage fixtures API inside a easy app

    create faker

    For create a new faker you should call the method: fullyStorage.createFaker( ?locality: string ): GeneratorFixtures

     
    const locality = "en_US";
     
    const faker = fullyStorage.createFaker( locality );
     

    Arg 1 locality is optional because default value is en_US

    generate fixtures

    Before create fixtures, you should use attribute options for specified collection target of fixtures data

     
    faker.options.collectionName = "articles";
     

    if articles collection not exists she auto create

    Now you can generate fixtures data

     
    // number docs to create
    const manyTimes = 10;
     
    faker.forEach( manyTimes, function( generator ) {
     
        const article = {};
     
        article.title = generator.lorem.words( 5 );
     
        const sentenceCount = 4;
        const separator = ' ';
     
        article.contentText = generator.lorem.sentences( sentenceCount, separator );
     
        article.createAt = generator.date.betweeen( 'now', '-60days' );
     
        return article;
     
    }  );
     

    Arg 1 generator is a faker object based on faker package,

    This code should append 10 new articles inside articles collection

    for show this results you can use CLI implemented by fully-storage for dump collection

    You can generate a fixtures file base and automate load fixtures with the CLI implemented

    http session manager

    You can use fully-storage as manager HTTP session, very easy usage the recognize client is based on user-agent of the headers request, the storage structure is identical to storage outside manager session:

    • /node_modules
      • /fully-storages
        • /collections
          • /session-store{random-id}

    fully-storage create a collection for stock the session with the name session-store, you should not use this name for another collection the collection name: session-store is reserved by fully-storage

    session start

    you should call the method: fullyStorage.sessionStart, for start a new handler session HTTP

     
    const http = require('http');
     
    const fullyStorage = require('fully-storage');
     
    const onRequest = fullyStorage.sessionStart({
     
        // time in ms default 1hours
        expires: ( 1e3 * 60 * 60 ),
     
        autoSave: true,
     
        // if the session store is clear between 2 call to sessionStart for prod
        // should be true
        // for dev if you want persist your session data
        // between on/off app you can give false value
        clear: true,
     
    });
     
    const server = http.createServer( function( request, response ) {
     
        onRequest( request, response );
     
        if( !request.session.test ) {
     
            request.session.test = Math.random();
     
            // if you have not 'autoSave' with: true value
            // you should mannually call method save after update session
            // for persist new session data,
            // request.session.save();
        }
     
        res.end( `test session value is: ${request.session.test}` );
     
    } );
     

    session stop

    If you want manually destroy the manager session you can call: fullyStorage.sessionStop()

    usage as middleware

    you can use the manager session as middleware with Express

     
    const express = require('express');
     
    const app = express();
     
    const server = require('http').Server( app );
     
    const fullyStorage = require('fully-storage');
     
    const sessionMiddleware = fullyStorage.sessionStart( {
        expires: ( 1e3 * 60 * 60 ), // 1hours
        autoSave: true
    } ) ;
     
    app.use( sessionMiddleware );
     
    app.get('/', (request, response) => {
     
        if( !request.session.test ) {
     
            request.session.test = Math.random();
        }
     
        response.type('plain/text');
        response.status( 200 );
     
        response.send( `session test with: ${request.sesssion.test}` );
     
    } );
     
    server.listen( 3001 );

    You should call the synchrone method request.session.save for persists update session data, between HTTP request.

    cli usage

    fully-storage implement a CLI for have overview of data store and for can export data store from /node_modules/ to your project before remove/regenerate /node_modules/ and more up...

    from your package.json you can add scripts key

    {
        "scripts": {
            "storage": "storage"
        }
    }

    or you can access to cli with:

    > ./node_modules/.bin/storage

    workflow

    export

    This command export all collections from node_modules folders to root of your project

    with npm key script:

    > npm run store -- --export

    You should execute this command before remove/regenerate the node_modules, folder for not lost your store data.

    > ./node_modules/bin/storage --export

    import

    This command import all collections from ./collections folder to /node_modules/ folder

    with npm key script:

    > npm run store -- --import

    You should execute this command after have regenerate the node_modules folder.

    delete

    you delete collection or doc from CLI, Warning the cli do not ask confirm action.

    delete collection

    for delete a collection:

    with npm key script:

    > npm run store -- --delete articles
    > ./node_modules/bin/storage --delete articles

    delete doc

    for delete a doc use the format: {collectionName}.{docId}

    with npm key script:

    > npm run store -- --delete-doc articles.0
    > ./node_modules/bin/storage --delete-doc articles.0

    add collection

    You can create a new empty collection with add-collection command:

    > npm run store -- --add-collection users
    > ./node_modules/bin/storage --add-collection users

    if collection already exists command is reject.

    regenerate collection

    You can remove all docs from a collection with regenerate command:

    > npm run store -- --regenerate articles
    > ./node_modules/bin/storage --regenerate articles

    dump

    you can dump data from the CLI

    dump collections list

    for show the collections list:

    > npm run store -- --collections-dump
    > ./node_modules/bin/storage --collections-dump

    output should have this format:

     
        {number} collections found.s
     
            {collectionsName} have {number} docs
            {collectionsName} have {number} docs
            {collectionsName} have {number} docs

    if you have create 0 collection the command is reject.

    dump-docs-list

    > npm run store -- --dump articles
    > ./node_modules/bin/storage --dump articles

    output should have this format:

     
        {collectionName} have {number} docs
     
        {docname} ({numbers} keys) :
            {
                keyname: value,
                keyname: value
            }
     
        {docname} ({numbers} keys)
            {
                keyname: value,
                keyname: value
            }

    if collection name not exists the command is reject.

    cli fixtures

    The CLI can build base fixtures file for you and auto load fixtures files

    You can see a example usage fixtures from CLI inside a easy app

    make fixtures

    create a new fixtures file for a specific collection

    > npm run store -- --fixtures articles
    > ./node_modules/bin/storage --fixtures articles

    append a new folders fixtures at root of you'r project and add inside the fixtures folders a fixture file with this format: {collectionName}.js and a static file for autload fixture: load.js

    • /root

      • /fixtures
        • {collectionName}.js
        • load.js

    you can write your fixtures from the file: {collectionName}.js inside the onGenerate method

    fixture file:

     
    onGenerate( generator ) {
     
        const article = {};
     
        /**
        * @TODO use generator for create factory data
        *
        * generator is a faker object
        * reference: https://npmjs.com/package/faker
        */
     
        return article;
    }

    use the api faker for create you'r factory data,

    e.g:

     
    onGenerate( generator ) {
     
        const article = {};
     
        article.title = generator.lorem.words( 5 );
     
        const sentenceCount = 4;
        const separator = ' ';
     
        article.contentText = generator.lorem.sentences( sentenceCount, separator );
     
        article.createAt = generator.date.betweeen( 'now', '-15days' );
     
        return article;
    }

    load fixtures

    After write your body fixtures you can load files with one command:

    > npm run store -- --fixtures-load
    > ./node_modules/bin/storage --fixtures-load

    Install

    npm i fully-storage

    DownloadsWeekly Downloads

    4

    Version

    1.5.4

    License

    BSD-2-CLAUSE

    Unpacked Size

    119 kB

    Total Files

    41

    Last publish

    Collaborators

    • avatar