nmsp
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-
nmspobjects. - 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 nmspAdd the nmsp package to your app:
const 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". -->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 thenmspAPI.
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
srcvalue. - an object, it is recursively assigned with the properties of the
srcobject. - a non-array or non-object, the value is overritten with the
srcvalue.
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 nopathargument is provided,srcmust 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 ) );
License
Copyright © 2016, Ryan Fitzer. Released under the MIT license.