require-object

npm i require-object

require() and fs.readFileSync() local files using an object.

Normally when attempting to access local files and modules a relative file path is used:

const localModule = require('../../lib/local-module.js')

This breaks when the file is moved and doesn't have normalized path delimeters (slashes).

'require-object' provides modules and files, accessible by object, using an absolute, normalized path from the root of the project (defined by location of package.json).

This means you can do the following to access local modules robustly, wherever your file is located:

const root = require('require-object');
const localModule = root.lib.localModuleJs;
const calculatePi = root.lib.calculatePiJs;
const someOtherModule = root.someOtherModule;

This also removes the need for directory index files as you can already use dot notation to access the files in a directory.

require-object gets .js and .json files using require() and other files using fs.readFileSync(). file reading is syncronous so its not a pain in the ass to use, so only read files when the application starts. Do not use this for reading files repeatedly. Instead use fs.readFile() which is asyncronous and not supported by this module for simplicity.

Non-js/json files always return a Buffer So you can read files with a non-utf8 encoding. Use toString() to convert to a string.

All files and directories are aliased in camelCase unless there are conflicting names.

New in 2.0.0

Aliases are non-enumerable so a directory can be iterated over without seeing each file twice (once for the file and once for the alias).

Usage

Example directory structure:

+-- static
|   +-- css
|   |   +-- example.css
|   |   +-- index.html
|   +-- js
|   |   +-- example.js
|   +-- index.html
+-- index.js
+-- some-data.json
+-- package.json

Reading the project's directory structure:

const root = require('require-object');

//root is equivilant to:
{
	static: {
		css: {
			get 'example.css'() => fs.readFileSync('path/to/example.css'),
			get exampleCss() => fs.readFileSync('path/to/example.css')
		},
		js: {
			get 'example.js'() => require('path/to/example.js'),
			get exampleJs() => require('path/to/example.js')
		},
		get 'index.html'() => require('index.html'),
		get indexHtml() => require('index.html')
	},
	get 'index.js'() => fs.readFileSync('index.js'),
	get indexJs() => fs.readFileSync('index.js'),
	get 'some-data.json'() => require('some-data.json'),
	get someDataJson() => require('some-data.json'),
	get 'package.json'() => require('package.json'),
	get packageJson() => require('package.json'),
}
// Here you can see the non-enumerable aliases provided without punctuation and in camelCase

Or only get specific directories:

const { static } = require('require-object');
// or
const static = require('require-object').static;


// static is now equivilant to
{
	css: {
		get 'example.css'() => fs.readFileSync('path/to/example.css'),
		get exampleCss() => fs.readFileSync('path/to/example.css')
	},
	js: {
		get 'example.js'() => fs.readFileSync('path/to/example.js'),
		get exampleJs() => fs.readFileSync('path/to/example.js')
	}
}

Accessing files:

const root = require('require-object');

const data = root['some-data.json'];
// or
const data = root.someDataJson;
// data is now an object containg the cointents of some-data.json

// root.someDataJson is an alias for root['some-data.json']

const css = root.static.css['example.css'].toString();
// or
const css = root.static.css.exampleCss.toString();
/* css is now a buffer of the contents of example.css that has been converted
into a String with toString()'s default encoding ('utf8') */

Optimization

Both node_modules and .git directories are excluded from the object so projects with hundreds of dependencies arn't slowed down.

require-object uses getters, so every time a file is accessed it is syncronously read from file. As mentioned at the begining, it is not recomended to use this for repeatedly reading a file. Instead use fs.readFile() as it is asyncronous. It's built like this to reduce memory usage. Otherwise if you had a large file in your project, the file would be read into memory even if you weren't using it.

require-object relies on the caching of require() in order to avoid re-index the project every time it is required.

Testing

If you wish to test this module, clone the repository that includes the pseudo installation that is required for testing.

If you have any questions or suggestions feel free to contact me or submit a pull request. Contribution is welcome.