Skip to content

Commit 81cb1fb

Browse files
devcrustdevcrust
committed
- latest readme version
1 parent 5f7d69b commit 81cb1fb

1 file changed

Lines changed: 200 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 200 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,61 @@
1-
# Dips [![Build Status](https://api.travis-ci.org/devcrust/node-dips.png)](https://api.travis-ci.org/devcrust/node-dips.png)
1+
# Dips [![Build Status](https://travis-ci.org/devcrust/node-dips.png?branch=master)](https://travis-ci.org/devcrust/node-dips)
22

33
A simple yet powerfull dependency injection and entity (file) management framework for Node.js
44

55
---
66

77
## Features
88

9-
* Inject all types of dependencies (Function, Object/Instance, Array, Boolean, Number, ...)
9+
* Inject all types of dependencies (Function, Object/Instance, Array, Boolean, String, Number, etc.)
1010
* Support for Node.js core and NPM dependencies out of the box
11+
* File entity resolver (folder/subfolder/file.js becomes `Dips.$.folder.subfolder.file`)
1112
* Fast (lazy loading support)
1213
* Re-register dependencies
1314
* Supports multiple containers/scopes
1415
* Has no dependencies of its own
1516

1617
---
1718

19+
## Installation
20+
21+
To install the latest stable version:
22+
23+
```sh
24+
npm install dips
25+
```
26+
27+
---
28+
1829
## Examples
1930

2031
### Create a new instance
2132

22-
Create a new `Dips` container:
33+
Create a new `Dips` instance:
2334

2435
```js
2536
var Dips = require('dips'),
26-
dips = Dips();
37+
dips = Dips({
38+
39+
entities : {
40+
41+
files : {
42+
basePath : __dirname,
43+
paths : ['lib']
44+
}
45+
46+
},
47+
48+
dependencies : {
49+
core : true,
50+
npm : true
51+
}
52+
53+
});
2754
```
2855

2956
### Register dependencies
3057

31-
Register new dependencies by calling `dips.setDependency`:
58+
Register new dependencies by calling `Dips.setDependency`:
3259

3360
```js
3461
// Register "config" dependency
@@ -42,23 +69,186 @@ dips.setDependency('db_config', {
4269
});
4370

4471
// Register "db" dependency
45-
dips.setDependency('db', function($db_config)
72+
dips.setDependency('db', function($db_config, $mysql) // $mysql registered by the "npm" dependencies
4673
{
47-
return require('mysql').createConnection($db_config);
74+
return $mysql.createConnection($db_config);
4875
});
4976
```
5077

5178
### Resolve dependencies
5279

53-
Resolve a dependency by calling `dips.invoke`:
80+
Resolve a dependency by calling `Dips.invoke`:
5481

5582
```js
56-
// Invoke function
83+
// Example I: Invoke function
5784
dips.invoke(function($db, callback)
5885
{
5986
$db.query('SELECT * FROM sometable', function(error, rows)
6087
{
6188
// ...
6289
});
6390
});
64-
```
91+
92+
// Example II: Invoke function
93+
dips.invoke(function($fs, $path) // $fs and $path registred by the "core" dependencies
94+
{
95+
$fs.readdirSync($path.resolve(__dirname, '..'));
96+
});
97+
```
98+
99+
### Get (file) entities
100+
101+
Get (file) entities by using the object `Dips.$` or the function `Dips.resolve`:
102+
103+
```js
104+
// Useful if your IDE supports auto completion based on JSDOC (like PhpStorm)
105+
dips.$.lib.database.connection // equals: require('./lib/database/connection.js)
106+
107+
// Using just a string (for instance from configurations)
108+
dips.resolve('lib.database.connection') // equals: require('./lib/database/connection.js)
109+
110+
// Using the shortcut function
111+
dips.$('lib.database.connection') // equals: require('./lib/database/connection.js)
112+
113+
```
114+
115+
---
116+
117+
## API
118+
119+
### Dips
120+
121+
---
122+
123+
#### Options for `Dips()`
124+
125+
* `entities ([Object.<String, *>])` - the entities to register _(optional)_
126+
- `files ([Object.<String, *>])` - the file entities to register _(optional)_
127+
- `basePath (String)` - the absolute base path to use
128+
- `paths (String | Array.<String> | Object.<String, String>)` - the file paths to parse, relative to the given `basePath`
129+
- `prefix ([String=""])` - the prefix to use e.g. "app" -> "app\_myentity", etc. _(optional)_
130+
131+
* `dependencies ([Object.<String, *>])` - the dependencies to register for the default container (optional)
132+
- `core ([Object.<String, *> | *])` - if present (typically with the value of `true`), registers the Node.js core modules e.g. fs, path, http, etc. as dependencies _(optional)_
133+
- `prefix ([String=""])` - the optional prefix to use e.g. "core" -> "core\_fs", etc. _(optional)_
134+
- `npm ([Object.<String, *> | *])` - if present (typically with the value of `true`), registers the installed NPM modules (behaves like [module.require](http://nodejs.org/api/modules.html#modules_all_together)) as dependencies _(optional)_
135+
- `prefix ([String=""])` - the optional prefix to use e.g. "npm" -> "npm\_express", etc. _(optional)_
136+
- `...` - the custom dependencies to register, dependency id as key `String` _(optional)_
137+
* `containers ([Object.<String, Container>])` - the dependency containers to register _(optional)_
138+
139+
---
140+
141+
#### Properties
142+
143+
##### `Entities`
144+
145+
* `$ (Function)` - the entity resolver function and registry object (_alias for `Dips.resolve`_)
146+
147+
```js
148+
// Useful if your IDE supports auto completion based on JSDOC (like PhpStorm)
149+
dips.$.lib.database.connection // equals: require('./lib/database/connection.js)
150+
151+
// Using the shortcut function
152+
dips.$('lib.database.connection') // equals: require('./lib/database/connection.js)
153+
```
154+
155+
#### Methods
156+
157+
---
158+
159+
##### `Entities`
160+
161+
* `addEntities(Object.<String, *> values)` - adds the given custom entities
162+
163+
* `resolve(String value)` - resolves the entity with the given name e.g. "lib.database.connection", etc.
164+
165+
---
166+
167+
##### `Containers`
168+
169+
* `getContainers()` - returns the ids of the registered dependency containers
170+
171+
* `setContainers(Object.<String, *> values)` - sets and overrides the given dependency containers
172+
173+
* `hasContainer(String id)` - checks if the dependency container with given id does exist
174+
175+
* `getContainer(String id)` - returns the dependency container with the given id
176+
177+
* `setContainer(String id, Container value)` - sets the dependency container with the given id and value
178+
179+
#### `Dependencies`
180+
181+
_The following methods are inherited from `Container`_
182+
183+
* `getDependencies()` - returns the ids of the registered dependencies within the `defaultContainer`
184+
185+
* `setDependencies(Object.<String, *> values)` - sets and overrides the given dependencies within the `defaultContainer`
186+
187+
* `addDependencies(Object.<String, *> values)` - addes the given dependencies within the `defaultContainer`
188+
189+
* `hasDependency(String id)` - checks if the dependency with the given id does exist within the `defaultContainer`
190+
191+
* `getDependency(String id)` - returns the dependency with the given id from the `defaultContainer`
192+
193+
* `setDependency(String id, * value)` - sets the dependency with the given id and value within the `defaultContainer`
194+
195+
* `invoke(Function|Array|Object|String|* value)` - invokes the given value with the dependencies from the `defaultContainer` and the provided additional _(non dependency)_ arguments
196+
197+
---
198+
199+
### Invoke explained
200+
201+
##### Invoke with `Function`
202+
203+
All function parameters starting with `$` will be replaced with the value of the corresponding dependency, `undefined` otherwise.
204+
It is possible to pass additional function arguments (indicated without a leading `$`). The additional arguments must be passed in the corresponding order of the function parameters.
205+
206+
Consider the following function parameters: `foo, $db, bar, $fs`:
207+
The additional arguments must be passed in the following order: `'value of foo', 'value of bar'`
208+
209+
###### Example
210+
211+
```js
212+
// Invoke function
213+
dips.invoke(function($db)
214+
{
215+
// $db is equal to dips.getDependency('db')
216+
});
217+
218+
// Invoke function with additional arguments
219+
dips.invoke(function($db, query)
220+
{
221+
// $db is equal to dips.getDependency('db')
222+
// query is equal to the given argument
223+
}, 'SELECT * FROM sometable');
224+
```
225+
226+
##### Invoke with `Array`
227+
228+
By passing an array to `Dips.invoke()`, the array values will be iterated and all `String` values starting with `$` will be replaced with the value of the corresponding dependency, `undefined` otherwise.
229+
230+
###### Example
231+
232+
```js
233+
// Invoke array
234+
dips.invoke(['$fs', '$path', {}]); // $fs and $path will be replaced with the corresponding
235+
```
236+
237+
##### Invoke with `Object`
238+
239+
If an object is passed to `Dips.invoke()`, the object will be iterated and the value of the `keys` starting with `$` will be replaced with the corresponding dependency, `undefined` otherwise.
240+
241+
###### Example
242+
243+
```js
244+
// Invoke object
245+
dips.invoke({
246+
247+
$db_config : null, // value will be equal to dips.getDependency('db_config')
248+
$mysql : null, // value will be equal to dips.getDependency('mysql') or require('mysql')
249+
query : 'SELECT * FROM sometable'
250+
251+
});
252+
```
253+
254+
__Passing other types (`string`, `number`, `boolean`, `null`, `undefined`) as value of `Dips.invoke` will be returned as they are, without modification.__

0 commit comments

Comments
 (0)