https://github.com/ecowden/pluto-path
Create a Pluto dependency injection module from files in a path or paths
https://github.com/ecowden/pluto-path
dependency-injection javascript javascript-dependency-injection pluto testing
Last synced: about 1 month ago
JSON representation
Create a Pluto dependency injection module from files in a path or paths
- Host: GitHub
- URL: https://github.com/ecowden/pluto-path
- Owner: ecowden
- License: mit
- Created: 2015-04-19T21:35:12.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2023-03-13T18:14:04.000Z (almost 3 years ago)
- Last Synced: 2025-09-20T13:27:09.522Z (5 months ago)
- Topics: dependency-injection, javascript, javascript-dependency-injection, pluto, testing
- Language: JavaScript
- Size: 440 KB
- Stars: 6
- Watchers: 1
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# pluto-path
Create and bootstrap an app from files in a path or paths using the [Pluto](https://github.com/ecowden/pluto.js) dependency injection package.
| Branch | Status |
| ------------- |:------------- |
| Master | [](https://travis-ci.org/ecowden/pluto-path) [](https://coveralls.io/github/ecowden/pluto-path?branch=master) [](https://nodesecurity.io/orgs/ecowden/projects/5cff7ae1-a34a-49f7-bf18-f2b816180930) |
| All | [](https://travis-ci.org/ecowden/pluto-path) |
**Why?**
This package aims to solve two problems:
1. **Bootstrapping**. There are many example Express/Hapi/etc. applications where a chain of `index.js` files require a bunch of routes and other bits. I find this annoying. When I create a new part of my app, I want it to Just Work without extra boilerplate.
1. **Testing**. The key to good testing isn't writing tests: it's writing good, testable code. When unit testing, in particular, we want to test one thing at a time. But what about when our one thing uses other things? By injecting those other things, often called _collaborators_, we can pass mocks or fakes to our code under test.
## Usage
### Simplified Options
```js
'use strict'
const path = require('path')
const plutoPath = require('pluto-path')
plutoPath(path.join(__dirname, 'my-directory')) // you can pass a single search path or array of them
.then(function (app) {
// `app` holds a Map from filenames to their components.
// It's created by calling pluto's `bootstrap(...)` function.
// Use it if you want to do interact with components after they're
// wired together.
})
// Don't forget about errors!
.catch(err => {
console.error(err.stack) // eslint-disable-line no-console
process.exitCode = 1
})
```
### Binding Types
This module will instantiate components in different ways:
| Binding | Used When | Meaning |
| ---------------- | --------- | ------- |
| Factory Function | File exports a `function`, and starts with a lower-case letter. | The module's export will be called as a regular function, and the result will be bound to the file name. |
| Constructor | File exports a `function`, and starts with a capital letter | The module's export will be bound as a constructor with `new`, and the result will be bound to the file name. |
| Instance | File does not export a `function` | The module's export will be used as-is. |
See the [Pluto Documentation](https://github.com/ecowden/pluto.js) for more details.
### Full Options
Since the default include and exclude options work for most projects and the path is often the only meaningful property, you can pass a `string` or `array` of strings for the path property instead of a full options object, as above. Alternately
| Property | Description |
| -------- | ----------- |
| path | _string_ or _array_ of absolute paths to search for files. Default: `.`. |
| include | _string_ or _array_ of [minimatch](https://github.com/isaacs/minimatch) patterns. A file in the path(s) that match at least one pattern will be `require(...)`'d unless the file also matches an exclusion pattern. Default: `['**/*.js', '**/*.json']`.|
| exclude | _string_ or _array_ of [minimatch](https://github.com/isaacs/minimatch) patterns. Files in the path(s) that match at least one pattern will be excluded. Default: `['**/*Spec.js']`. |
| extraBindings | A function given the standard pluto `bind` object. Use when
you'd like to specify additional options beyond what pluto-path can find on the
filesystem. |
```js
'use strict'
const path = require('path')
const plutoPath = require('pluto-path')
plutoPath({
path: path.join(__dirname, 'my-directory'),
include: ['**/*.js', '**/*.json'],
exclude: ['**/*Spec.js'],
extraBindings: (bind) => {
bind('meaningOfLife').toInstance(42)
}
})
.then(function (app) {
// `app` holds a Map from filenames to their components.
// It's created by calling pluto's `bootstrap(...)` function.
})
// Don't forget about errors!
.catch(err => {
console.error(err.stack) // eslint-disable-line no-console
process.exitCode = 1
})
```
## Humble Opinionated Recommendations
### Project Organization
There's usually two different kinds of files in an app:
1. Long-lived components, like route handlers and server configuration. These need to be run exactly once and become a part of your app. Place these in an `app` folder.
1. Utilities and such that don't have a life of their own, and which you don't want subject to dependency injection. Place these in a `lib` folder.
```
/
/app Bootstrap long-lived components
/lib Utilities and such you don't want to dependency-inject
index.js `main` file with initial bootstrapping
```
Instruct `pluto-path` to bootstrap the `app` folder and leave the `lib` folder alone. If you're not doing any fancy startup stuff and you're fine with other defaults, your `index.js` file might look like:
```js
'use strict'
const path = require('path')
const plutoPath = require('pluto-path')
plutoPath(path.join(__dirname, 'app'))
// Don't forget about errors!
.catch(err => {
console.error(err.stack) // eslint-disable-line no-console
process.exitCode = 1
})
```
### Tests
You might notice that there's not test path, event though one of the main motivations for dependency injection is testability. Rather than use a separate `test` tree, I like to put my tests right next to the thing they're testing, with a `Spec` suffix, like:
```
/
/app
myThing.js
myThingSpec.js
```
I am highly influenced by Uncle Bob's [Principles of Object Oriented Design](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod). In this case:
* **Common Closure Principle**: Things that change together should be packaged together.
When it comes to unit testing, a test and the thing it tests unsurprisingly tend to change together, so I like to put them next to each other. Stepping back, this makes logical sense, too: why hunt deep down through two separate directory trees just to get to the two files you want to change? Putting tests next to the code they test reduces friction when writing tests and just makes life easier.
The default arguments to `pluto-path` assume this kind of organization. If you want to do something else, change the `include` and `exclude` options as you see fit.