Natural Preference for Minification

    @scispike/nodejs-support
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.4 • Public • Published

    nodejs-support

    This package contains various building blocks for use in Node.js-based applications.

    DEPRECATION NOTE: Since the time this package was created, SciSpike has been acquired by Northscaler, and this package has become too big. Consequently, each functional area is being rebranded under the @northscaler npm scope and released independently as its own module, as identified in issue https://github.com/SciSpike/nodejs-support/issues/3. There will be no further development on this module. See each section of this readme for more information about which @northscaler package to look for when you're upgrading. You can see all of Northscaler's public Node.js modules at https://www.npmjs.com/search?q=%40northscaler.

    Below is a list of the functional areas and their new module names. It will be updated as progress is made.

    Functional Area New Module Status
    services TBD incomplete
    entities TBD incomplete
    errors TBD @northscaler/error-support✝︎
    enums TBD incomplete
    logger TBD incomplete
    require TBD incomplete
    contexts @northscaler/continuation-local-storage complete

    ✝︎: Not all error classes are here. Those errors having to do with persistence (ObjectExistsError, ObjectNotFoundError, UnknownDiscriminatorError, NonuniqueCriteriaError) will be located in a different module. UnknownEnumError will be in the @northscaler/enum-support module.

    services

    This folder contains various classes to help you write well-behaved services.

    ServiceSupport

    This is a helper class that provides static methods to wrap functions in a try/catch in order to

    • ensure service methods always return success/failure information with payloads, and
    • prevent service methods from throwing.

    @returnsServiceResponse

    This is a decorator-based aspect, based on @scispike/aspectify & ServiceSupport, that allows you to simply decorate a service method in order to ensure that it behaves as described above. Simply ensure that you are returning plain, ol' values (including objects, if desired), from your service methods.

    This aspect will wrap the service method's return value (returnValue below) into an object of the form

    {
      data: returnValue,
      meta: {
        status: 'SUCCESS',
        elapsedMillis: ...
      }
    }

    If your method throws an Error, the aspect catches it and returns a response of the form

    {
      error: {
        name: ...,
        message: ...,
        code: ..., // if your error has a code property
        info: ..., // if your error has an info property
        cause: ..., // recursive cause(s) error here if your error has a `cause` property
        stack: ..., // if you used @returnsServiceResponse({ includeStacktrace: true})
      },
      meta: {
        status: 'FAILURE',
        elapsedMillis: ...
      }
    }

    entities

    Contains some convenient entities that are expected to be persisted into some datastore.

    Usage example:

    const moment = require('moment-timezone')
    const Period = require('@scispike/nodejs-support/entities/Period')
     
    const period = new Period(moment().utc(), moment.utc().add(1, 'day'))
    // now use period methods

    This folder contains

    • fundamental traits based on mutrait meant to be used by other classes,
    • fundamental classes that may be convenient in other parts of the stack.

    See the source for more information.

    enums

    This folder convenient enumerations using a pattern that builds on enumify.

    Usage example:

    const DayOfWeek = require('@scispike/nodejs-support').entities.DayOfWeek
    // ...use DayOfWeek.SUNDAY, etc

    errors

    DEPRECATION NOTE: This functionality has been rebranded and released as @northscaler/error-support.

    Usage example:

    const IllegalArgumentError = require('@scispike/nodejs-support').errors.IllegalArgumentError
    throw new IllegalArgumentError('foobar')

    This folder contains a base error class, CodedError, upon which are built many other convenient error classes. Here is an example of defining your own error classes using CodedError:

    const CodedError = require('@scispike/nodejs-support').errors.CodedError
     
    module.exports = CodedError({ code: 'E_SOMETHING_WICKED_THIS_WAY_COMES' })

    The logger function accepts two parameters:

    • name: required, the name of your application or module
    • opts: optional, default {}, any bunyan options you want to set

    See the source for more information.

    logger

    Usage example:

    // in your own file "index.js" in a directory called "log", "logger" or whatever
    const appLogger = require('@scispike/nodejs-support').logger('foobar')
    module.exports = appLogger // has methods info, warn, etc

    This folder exports a function that allows you to easily use bunyan & bunyaner in your own projects.

    See the source for more information.

    require

    Usage example:

    // in your own index.js file in some directory with lots of things you want to export
    const req = require('@scispike/nodejs-support').require
    module.exports = req.jsFilesExceptIndexIn(__dirname)

    This folder exports an object that makes it easy to export an entire directory of artifacts. Each file or directory in the given directory as an absolute path is added as a key on the returned object.

    The methods it offers are the following:

    • dirsIn(dir): given an absolute path of directory dir, returns an object where each key is the result of requireing each child directory of dir
    • jsFilesIn(dir): given an absolute path of directory dir, returns an object where each key is the result of requireing each file in dir that has a .js extension; each key name is the filename without the .js extension.
    • jsFilesExceptIndexIn(dir): same as jsFilesIn(dir), except that it skips the file index.js
    • jsonFilesIn(dir): given an absolute path of directory dir, returns an object where each key is the result of requireing each file in dir that has a .json extension; each key name is the filename without the .json extension.

    This module actually eats its own dog food, using this object to export directories and files contained under src/main. See src/main/index.js or src/main/entities/index.js for examples

    contexts

    DEPRECATION NOTE: This functionality has been rebranded and released as @northscaler/continuation-local-storage.

    Contexts allow you to place information in a continuation-local storage space (like Java's thread-local storage).

    There two flavors to choose from: one based on cls-hooked, and one based on zone.js. Use whichever one you want to; the Context API is the same:

    • Run code in a context: Context().run(() => { /* your code here */ }, { your: 'context', values: 'here')
    • Set a value in a context: Context().set('name', 'value')
    • Get a value from a context: Context().get('name')

    NOTE: If you are using ZoneJsContext, you must install zone.js and then require('zone.js/dist/zone-node') at the right time for your application. If you are using ClsHookedContext, you must install cls-hooked yourself. See this project's package.json devDependencies section for the versions of cls-hooked and zone.js was built against and try to install compatible ones.

    Usage example:

    const Context = require('@scispike/nodejs-support').context.ClsHookedContext // or ZoneJsContext
     
    Context().run(() => { // uses the default context; pass a string name for a custom context
      // Do whatever you want here.
      // Context values are accessible anywhere in the sync or async call stack:
      const foo = Context().get('foo') // returns 'bar'
      
      // You can set & get values with:
      Context().set('baz', 'snafu')
      const baz = Context().get('baz') // returns 'snafu'
    }, {
      foo: 'bar' // puts the value 'bar' into the context at key 'foo'
    })

    Enumeration

    TODO

    • TL;DR: const BooleanValue = Enumeration.new( { name: 'BooleanValue', values: ['TRUE', 'FALSE'] } )
    • Codification of pattern in Enumeration.new()
    • static $ERROR$ property
    • isEnumerationInstance, isEnumerationClass, isInstance & isClass
    • Document breaking changes: $ERROR$ replaces error()

    Install

    npm i @scispike/nodejs-support

    DownloadsWeekly Downloads

    49

    Version

    2.0.4

    License

    MIT

    Unpacked Size

    136 kB

    Total Files

    50

    Last publish

    Collaborators

    • npm_scispike