Req
A package manager to eliminate the need for recursive dependencies, and allow for flexibility with dependencies
Installation
$ npm install @firecubez/req
Usage
const Req = require("@firecubez/req");
Req.module("hello", null, $$ => {
return {string: "Hello, world!\n"};
})
Req.module("helloname", $$ =>
$$.depend(
"hello",
"a module which provides 'Hello, world!'"
),
$$ => {
const hello = $$.get("hello", {});
return {
withname: name => hello.string + name
}
})
const main = Req.module("main", $$ =>
$$.depend(
"helloname",
"a module which puts names next to 'Hello, world!'",
{
withname: f => typeof f === "function"
}
),
$$ => {
// ...
}
)
Here's where it gets interesting. For the function:
$$ => {
const helloname = $$.get("helloname", {})
helloname.withname("Req")
}
// ...
main()
// > Hello, world!
// Req
As expected, but:
$$ => {
const helloname = $$.get("helloname", {
hello: {
string: "Hey there "
}
})
helloname.withname("Req")
}
// ...
main()
// > Hey there Req
What happened?
We have overridden the hello
dependency of helloname
in the second example with a "mock" dependency. This can be useful when creating tests.
API
Req
The Req
object exposes 4 methods:
-
get(name)
: Get a module by its name using the following procedure:- Check the internal module storage for the module.
- If not found, check if the module exists using Node's
require
. Returns: The found module Throws: If the module isn't found.
-
module(name, definerFunc, runner)
: Create a named module and save it in the internal module storage. Parameters:-
name
: The module name -
definerFunc
: A function which takes aDefiner
and calls it'sdepend
method. -
runner
: A function which takes aGiver
and runs the module code, returning the exports Returns: The newly created module
-
-
anonymousModule(definerFunc, runner)
: Same asmodule
, but does not save in internal storage since no name is provided -
deprecate(mod, func[, repl])
: Deprecate a module Parameters:-
mod
: The module to deprecate -
func
: A function which is called when it is attempted to use the deprecated method. It should return a warning message to be printed by Req (configurable by settingReq.warn
function) -
repl
: The module to use instead of this module (can be a name or the module itself)
-
Definer
A definer object is passed to Req.module
/ req.anonymousModule
for modules to declare dependencies
-
depend(name[, desc[, interface[, def]]])
: Declares a dependency. Parameters:-
name
: The dependency name to be referenced inGiver.get
-
desc
: A description method for detail in error messages -
interface
: Asserts, atGiver.get
time, that the dependency exposes certain properties. For each property ininterface
:- It must be a function
- If the dependency doesn't expose a property of the same name, an error is thrown
- The function is run on the dependency's property of the same name. If it returns false, an error is thrown
-
def
: A fallback dependency to be used if a dependency of the specified name isn't found. The dependency is still accessible withGiver.get
under the same name as specified in the first argument. Returns:this
(for chaining)
-
Giver
A giver object is passed to Req.module
/ req.anonymousModule
for modules to use their dependencies
-
get(name)
: Get a dependency module using the following procedure:- Check if the module
get
ing this module overwrote the specified name - If not, check the current module's dependencies
- If not there, check the dependencies for the default module name specified in
Definer.depend
- If not there, check the internal module storage for the specified and default name
- If not there, check with Node's
require
for both the specified and default name - If not there, throw an error
Returns: The actual module with the specified name (NOT the object it returns). Will always be a function with
__Is_Req_Module__ === true
Throws: If the dependency doesn't exist
- Check if the module
-
get(name, impl)
: Get a dependency's exposed properties / return value Returns: The dependency's return value withimpl
containing overridden dependencies. Throws: If the dependency with the specified name doesn't exist orimpl
does not pass the tests described inDefiner.depend
Alias for:get(name)(impl)
Module
A module is a function with the __Is_Req_Module__
property set to true
.
A module exposes the following properties:
-
internal __Is_Req_Module__
:true
. Can be used to detect whether a function is a module or not -
internal __Req_Deprecate__
: A function that is called when this module is used. Most of the time you don't want to touch this -
internal __Req_Deprecate_Target__
: The new version of this module that isn't deprecated. You also don't want to touch this -
moduleName
: The name of the module,null
if it is an anonymous module