nmsp

v2.0.0

Published

2 years ago

Create, manage and extend your namespaces in the browser and NodeJS.

Downloads

nmsp

Total downloads

The most valuable use case for nmsp is in a browser environment where the data required by your application is provided by various legacy/3rd party sources (via embedded <script> tags, asynchronous requests, etc.).

Creates namespace instances that provide helpful methods for easy management.
Provides static methods for managing non-nmsp objects.
Supports UMD for flexible module loading support.
Tiny. Only 513 bytes, gzipped.
Supports all modern browsers, IE, NodeJS and Nashorn.

The typical solution has been to store everything in top-level object literal. The object literal approach definitely works, but it can become very fragile due to the potential for naming conflicts and changes/updates to your data during the life of your application. Managing your namespace(s) with nmsp significantly reduces this pain.

In addition, these data sources may need to be handled before your application is even loaded (where you may have something like Lodash available). For example, when your application is loaded via a <script> tag at the end of the <body>, but various data sources may need to be embedded throughout the <body> and <head>. The tiny size of nmsp helps to minimize the downsides of loading it in <head> of your document.

Installation

CommonJS

Install the latest version from npm:

npm install nmsp

Add the nmsp package to your app:

const nmsp = require( 'nmsp' );

AMD

The API is exported as an anonymous module. If you're not familiar with AMD, RequireJS is a great place to start.

Browser Global

Download the latest development and production versions from UNPKG. Once the script is loaded, the nmsp function can be accessed globally.

<!-- When deploying, replace "nmsp.js" with "nmsp.min.js". -->
<script src="nmsp.js"></script>

Usage

Create and extend namespace:

// Supports a path (string or array) or an object
const ns = nmsp( 'a.b.c' );

// Add a `d` property into the `b` member
ns.extend( 'a.b', { d: 'd' } );

// Add an `e` property into the `a` member
ns.extend( 'a.e', { f: 'f' } );

// Add a top-level property
ns.extend( { g: 'g' } );

Result:

{
  a: {
    b: {
      c: {},
      d: 'd',
    },
    e: {
      f: 'f'
    }
  },
  g: 'g'
}

Properties

`nmsp`

Identifies object as an nmsp namespace.

Type: Boolean
Value: true

Static Methods

`nmsp.extend( dest, src )`

Assign (recursively) the properties of a source object to a destination object. This method mutates the dest object. Existing properties that resolve to objects will be extended, all other values are overwritten.

Arguments:

dest {Object}: The object to extend.
src {Object}: The object to merge into the destination.

Returns:

{Object}: The extended destination object.

Example:

const dest = {
  a: 1,
  b: {
    c: 1
  }
};

const src = {
  b: {
    d: 1
  }
};

nmsp.extend( dest, src );

Result:

{
  a: 1,
  b: {
    c: 1,
    d: 1
  }
}

`nmsp.atPath( path, src )`

Get the value at a path in a source object.

Arguments:

path {String|Array} The path to search in the object.
src {Object} The object to search.

Returns:

{*}: The value at the provided path.

Example:

const src = {
  a: {
    b: {
      c: {
        d: 'Come and get me!'
      }
    }
  }
};

const result = nmsp.atPath( 'a.b.c.d', src );

// or

const result = nmsp.atPath( [ 'a', 'b', 'c', 'd' ], src );

Result:

'Come and get me!'

`nmsp.fromPath( path )`

Create a nested object based on the provided path.

Arguments:

path {String|Array}: The path with which to model the object.

Returns:

{Object}: The object modeled after the provided path.

Example:

const result = nmsp.fromPath( 'a.b.c.d' );

// or

const result = nmsp.fromPath( [ 'a', 'b', 'c', 'd' ] );

Result:

{
  a: {
    b: {
      c: {
        d: {}
      }
    }
  }
}

`nmsp.plain( src )`

Create a plain object that consists of only the enumerable own properties of a source object.

Arguments:

src {Object}: The source object.

Returns:

{Object}: A plain object with all non-enumerable non-own properties removed.

Example

const props = {
    foo: {
        value: 'Foo',
        enumerable: true
    }
};

const src = Object.create({
    bar: 'Bar'
}, props );

const result = nmsp.plain( src );

Results:

assert.ok( 'foo' in src );
assert.ok( 'bar' in src );
assert.ok( 'foo' in result );
assert.ok( !( 'bar' in result ) );

Instance Methods

`nmsp( [initialValue] )`

Create a namespace object with an API that enables easy extension. This function mutates the object passed as initialValue.

Arguments:

[initialValue] {Object|String|Array}: Create a namespace with an existing object, or use a path (ex: 'a.b.c' or [ 'a', 'b', 'c' ] ) as the model from which to create the object.

Returns:

{Object}: A namespace object extended with the nmsp API.

Example with no initialValue:

const ns = nmsp();

Example with an object as the initialValue:

const ns = nmsp({
  foo: {
    bar: {
      baz: {}
    }
  }
});

Example with a path string as the initialValue:

const ns = nmsp( 'foo.bar.baz' );

Example with a path array as the initialValue:

const ns = nmsp( [ 'foo', 'bar', 'baz' ] );

`nmsp#extend( [path], src )`

Extend (recursively) the namespace object with a src value. A an optional path argument can be passed to extend the namespace object at a nested position.

If the value at the specified path resolves to:

an array, it is concatenated with the src value.
an object, it is recursively assigned with the properties of the src object.
a non-array or non-object, the value is overritten with the src value.

Arguments:

[path] {String|Array}: The position (ex: 'a.b.c' or [ 'a', 'b', 'c' ] ) to extend in the namespace object.
src {Mixed}: The value that will extend the namespace object. If no path argument is provided, src must be an object.

Returns:

{undefined}

Example:

const ns = nmsp( { a: {} } );

ns.extend( 'a.b', {
  c: 'c'
});

// or

ns.extend( [ 'a', 'b' ], {
  c: 'c'
});

Result:

{
  a: {
    b: {
      c: 'c'
    }
  }
}

`nmsp#atPath( path )`

Get the value at a path in the instance object.

Arguments:

path {String|Array} The path to search in the object.

Returns:

{*}: The value at the provided path.

Example:

const ns = {
  a: {
    b: {
      c: {
        d: 'Come and get me!'
      }
    }
  }
};

nmsp( ns );

const result = ns.atPath( 'a.b.c.d' );

// or

const result = ns.atPath( [ 'a', 'b', 'c', 'd' ] );

Result:

'Come and get me!'

`nmsp#plain()`

Create a plain object that consists of only the enumerable own properties of the instance object, removing the nmsp API.

Returns:

{Object}: A plain object with all non-enumerable non-own properties removed.

Example

const ns = {
    foo: 'Foo'
});

nmsp( ns );

const result = ns.plain();

Results:

assert.ok( 'foo' in ns );
assert.ok( 'nmsp' in ns );
assert.ok( 'foo' in result );
assert.ok( !( 'nmsp' in result ) );

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

nmsp

Installation

CommonJS

AMD

Browser Global

Usage

Properties

nmsp

Static Methods

nmsp.extend( dest, src )

nmsp.atPath( path, src )

nmsp.fromPath( path )

nmsp.plain( src )

Instance Methods

nmsp( [initialValue] )

nmsp#extend( [path], src )

nmsp#atPath( path )

nmsp#plain()

License

`nmsp`

`nmsp.extend( dest, src )`

`nmsp.atPath( path, src )`

`nmsp.fromPath( path )`

`nmsp.plain( src )`

`nmsp( [initialValue] )`

`nmsp#extend( [path], src )`

`nmsp#atPath( path )`

`nmsp#plain()`