ninjs-lodash

Super util library that exports extended Lodash object (_) via _.mixin({...Super Util Methods....})

Warning: The design of this module goes against standard coding practices. However, we are lazy, tired of import statements, and desire one core dependency module rather than thousands, hundreds of thousands, millions of module dependencies (each with overhead)

Overview

This module includes common utility methods that fall into the following groupings:

• JavaScript Types -> String, Object, Array, Function, Number, Regx, Boolean, Date ....
• Child Processes
• Configuration/Settings -> Env, User, Local, Global, .Folders, .Files
• Classes
• OS
• Paths
• Urls
• Debug
• File System
• Async
• Terminal/CLI Helpers

This is the least dependent module (or most depended upon) module in the ninjs-* namespace.

The purpose of packaging all this functionality into one module was to make it easier/faster to create new modules and reduce code duplication/bloat

We tried to keep it as tiny as possible with as few dependencies as possible.

{
  "dependencies": {
    "async": "~2.1.2",
    "cli-color": "~1.1.0",
    "fs-extra": "~1.0.0",
    "glob": "~7.1.1",
    "lodash": "~4.16.6",
    "moment": "~2.15.2",
    "numeral": "~1.5.3"
  },
  "bundleDependencies": [],
  "peerDependencies": {},
  "devDependencies": {},
  "optionalDependencies": {}
}

Setup

Install

Install the module locally and add to ./package.json dependencies

npm install --save ninjs-lodash

Import

import 'ninjs-lodash' (instead of 'lodash')

Now you can use existing lodash utils AND/OR ninjs mixins

const _ = require('ninjs-lodash')

// ~~~~~ original lodash ~~~~~
_.each(['blah', 'item'], (item) => { ... })

// ~~~~~ ninjs-lodash mixins ~~~~~
_.async.waterfall([...], (err, result) { ... })

_.log(_.$('paths.root')) // prints path of dir containing package.json

$ettings

Override/Add your own $ettings

• Create a ./.ninjs/settings.js(json) file within a module cwd that exports an object
• You can now access that object (and nested props) via _.$()
• internally uses _.get(settings, 'keypath'))
• *Be careful not to override _.$() default settings

_.$('keypath.to.list[3]')

Scripts/Debugging

{
  "scripts": {
    "cli":        "set NODE_ENV=development && set DEBUG=* && node ./bin/cli.js",
    "cli-prod":   "set NODE_ENV=production && set DEBUG= && node ./bin/cli.js",
    "test":       "set NODE_ENV=development && set DEBUG=* && node ./test/index.js",
    "test-prod":  "set NODE_ENV=production && set DEBUG= && node ./test/index.js",
    "npm-config": "npm c ls -l"
  }
}

Be sure to add '--' before args/switches when running cli scriptsOtherwise switches will not be passed to the spawned process created by 'npm run script' command

npm run cli -- settings --key=paths

$ettings - Global Settings Cache

Override/Add your own $ettings

• Create a ./.ninjs/settings.js(json) file within a module cwd that exports an object
• You can now access that object (and nested props) via _.$()
• internally uses _.get(settings, 'keypath'))
• *Be careful not to override _.$() default settings

_.$('keypath.to.list[3]')

CLI Helper - _.cli(map)

Maps a terminal command to a Command Object and invokes its 'handler'

Command Object

{
  // command default options, args, switches
  "options": { key: '' },

  // command handler
  // options = _.merge(options, 'interpreted' options from command line args/switches)
  "handler": (options) => { /* Do Something -> run a command, invoke an api, .... */ },

  // command help (--help)
  "text": "This is printed when jav.key === settings && jav.isHelp",

  // command detailed help (--help -l)
  "body": "This is printed when jav.key === settings && jav.isHelp && jav.isLong.. If no body set -> obj.text is used instead"
}

Command Map

{
  "ams": {
    "module": {
      "publish": {
        "options": { "name": "" },
        "prop": (options, callback) => { return lib.publishModule(options, callback)  },
        "cb": (err, result) => { return err ? _.log(err) : _.jslog(result) }
      }
    }
  }
}

Example -> Invoke api.module.publish(options, cb) and print result

*** This is just an example api.module.publish does not exist ***

./package.json

{
  "bin": { "ninjs-lodash" : "./bin/cli.js" },
  "cli": "set NODE_ENV=development && set DEBUG=* && node ./bin/cli.js"
}

./bin/cli.js

exports = module.exports = { // Command Map
  "ams": {
    "module": {
      "publish": {
        "options": { "name": "" },
        "prop": (options, callback) => { return lib.publishModule(options, callback)  },
        "cb": (err, result) => { return err ? _.log(err) : _.jslog(result) },
        "text": "--help text",
        "body": "--help -l long text"
      }
    }
  }
}

_.cli(exports) // Run Interpreter

Terminal . (Local) -> npm run cli -- [keypath.something.method] --switches --k=v ...

> npm run cli -- api.module.publish --name=ninjs-lodash

Terminal * (Global) -> %cli-alias% keypath.something.method --switches --k=v ...

> ninjs-lodash api.module.publish --name=ninjs-lodash

NOTE: args/switches after '--' proxied to spawned npm run-script process

String

_.bytes(num)        // returns formatted byte string

Path

_.path[*]           // require('path') + extras
_.path.name(src)
_.path.dir(src)
_.path.base(src)
_.path.isAbsolute(src)

Url String

_.url[*]            // require('url') + extras

Plain Object

_.acopy(...args)    // _.assign with no mutation
_.mcopy(...args)    // _.merge with no mutation
_.deepExtend(o, ob) // deep merge

Array Object

_.args(...args)     // returns flattened array of args, args, string, ....

Async

_.async[*]          // require('async')
_.fail(err, cb)     // callback(err)
_.done(result, cb)  // callback(null, result)
_.cb(callback)      // callback || function noop() {}

File System

_[*fs]              // common fs-extra assigned to _
_.fs[*]             //  _.fs = require('fs-extra')