micro-components-js

Micro Components for NodeJS

Lightweight library to create components that can automagically be used as either CLI or as native classes in other programming languages

The same package is available for Python. Check it out if you want Node and Python components talking to each other!

Goals & Design

Often times, which programming language I pick is predetermined by technical requirements and the resources available in that language. In many cases I have to use a mixture of nodejs, Python, and bash scripts, and they all have to talk to each other.

The intent of this library is to provide a utility class turning Singleton classes into command line interfaces and providing an intuitive class interface between different programming languages. Since a lot of the code I produce is either Node or Python, I started by creating components for those two languages.

The beauty of this is that components have a simple JSON interface to talk to each other, irregardless of the programming language. Any other language implementing the Component interface can now be imported as if it were a native class.

Installation

In your terminal run:

$ npm i micro-components-js

To install the CLI, run:

$ npm link micro-components-js

Usage

To run a component from the terminal, you need the following structure at minimum:

const { Component } = require('micro-components-js');

const TaskRunner = Component({
	name: 'task_runner',

	run(task_id) {
		return { task_id, status: 'running' };
	}

}).export_as_cli();

To then be able to run one of the following commands from your terminal:

$ taskrunner.js run 95
# output: { "task_id": 95, "status": "running"  }

$ taskrunner.js run --task-id="hello world"
# output: { "task_id": "hello world", "status": "running"  }

$ taskrunner.js run --task-id="[5,9,true]"
# output: { "task_id": [5, 9, true], "status": "running"  }

Example of Python and Node components interacting:

Consider this Python component called task_logger.py:

from micro_components import Component

class TaskLogger(Component):
	name: 'task_logger',

	@staticmethod
	def log(infos):
		with open('log.json', 'w') as log_file:
			log_file.write(infos)

TaskLogger.export_to_cli()

We can now use TaskLogger from within our task_runner**.js** code:

const { Component } = require('micro-components-js');
const { TaskLogger } = Component.from_cli('./task_logger.py');

const TaskRunner = Component({
	name: 'task_runner',

	run(task_id) {
		const result = { task_id, status: 'running' };
		TaskLogger.log(result);
		return result;
	}

}).export_as_cli();

Creation from Terminal

You can use the micro-components CLI to create a component like so:

In your terminal:

$ micro-components create "My Component"

This will create a skeleton component file in your current directory.

Naming Convention

Components have a snake_cased filename and hold the same name as a property at minimum:

const { Component } = require('micro-components-js');

const SomeComponent = Component({
	name: 'some_component'
});

Class names follow usual conventions of StartCase.

const { IntentMatcher } = require('./components/intent_matcher');

Exporting

You can use one of two export methods to either import components as modules "inline" or call their methods from the command line.

As Modules

To turn a component into a requirable module in NodeJS, use:

SomeComponent.export_as_(module);

As CLI

To turn a component into a CLI, use the command export_as_cli():

SomeComponent.export_as_cli();

Manual Creation

If you create your component by hand, make sure your file is executable by adding a Shebang at the top of it…

#!/usr/bin/env node

…and by giving it execution permissions (in your terminal)…

$ chmod +x ./components/some_component.js

…to then run the methods:

$ ./components/some_component.js fetch_data "parameter" 15 "{ \"sub-param\": \"value\" }"

The Component class will automagically look at the parameter defaults of your component's methods and try to parse parameters passed through the CLI accordingly.

Consider the following example component:

const RecipeFetcher = new Component({
	name: 'recipe_fetcher',
	counts: 0,

	get_ingredients(ingredient_name, max_count=10, normalize=true, options={}) {
		...
	}
});

RecipeFetcher.export_as_cli();
RecipeFetcher.export_as_(module);

We pass the following arguments via CLI:

$ ./components/recipe_fetcher.js get_ingredients "Onion Soup" 15 false "{ \"pepper\": false }"

The component class will automatically parse 15, false, and the passed JSON string as JSON and use the true datatypes.

Named Arguments

You can pass named arguments by prefixing the parameter names with two hyphens instead:

$ /components/recipe_fetcher.js get_ingredients --ingredient_name "Mangosteen" --normalize=1

Properties for the component class can be passed the same way. Arguments that don't match method names will be applied as properties. Any hyphens will be replaced by underscores, meaning --user-id will be read as user_id.

$ /components/recipe_fetcher.js get_ingredients --user-id=1337 --ingredient_name="Capers"

Method Chaining

Methods can be chained using the chain notation (beware that spacing is crucial):

$ /components/recipe_fetcher.js [ load_ingredients "all" , get_ingredients "Pepper" 12 ]

will first run RecipeFetcher.load_ingredients("all"), then RecipeFetcher.get_ingredients("Pepper", 12) and return a dictionary of results for each execution.

Caching

Before using any of the built-in caching functionality, make sure you have a directory called data/caches to store those in. To cache individual methods, use the cached_methods property array:

	const RecipeFetcher = new Component({
		name: 'recipe_fetcher',
		cached_methods: ['heavy_computational_task'],
		...

A JSON cache will be auto-generated in /data/caches/<component_name>.cache.json.

API

Components provide the following interface:

Events

Components and utility classes all emit events that can be listened to. You can attach event listeners using the on method.

RecipeFetcher.on('spawn', (self) => console.log('RecipeFetcher loaded.'));

The following events are available on every component:

Event Name	Triggered …	passed arguments
spawn	once on initialization	self instance, needs to be returned back
init	every time the component is being updated using ComponentName.init(...)	self instance, options object
cache	every time a method's cache is being hit	key used to retrieve value from cache
call_from_cli	once upon calling the component from the command line	command is the called method, args the passed arguments, verbose to turn console output on/off

To trigger (e.g. your own) events, use the trigger method:

RecipeFetcher.trigger('recipe_outdated', ['some', 'arguments']);

If the event handler returned something, it will be passed through trigger as return value.

const new_recipe = RecipeFetcher.trigger('recipe_outdated', [old_recipe]);

---

Properties

You can access non-callable properties from the CLI using the component module's built-in get and set methods in your terminal:

$ ./components/recipe_fetcher.js get counts 	# returns 1

$ ./components/recipe_fetcher.js set counts 3

---

Shortcuts

All components automatically get a help method, so if uncertain about properties run ./components/recipe_fetcher.js help. All methods automatically get a --help directive, so if uncertain about parameters run ./components/recipe_fetcher.js get_ingredients --help.

Integration

You can call components written in Javascript from Python and vice-versa as if they were written in the same language using the Component module.

Our previous RecipeFetcher example was written in Javascript, but now we want to use it in Python. Here's how:

const { Component } = require('micro-components-js');

const { RecipeFetcher } = Component.from_cli('./components/recipe_fetcher.py');
let ingredients = RecipeFetcher.get_ingredients("Onion Soup", 15, false, { pepper: false });

To access properties, use the built-in property getters and setters (see "Properties"), like so:

const { Component } = require('micro-components-js');

RecipeFetcher = Component.from_cli('./components/recipe_fetcher.py');
const counts = RecipeFetcher.get("counts");

Testing

This package comes with a set of standard JEST tests located in [tests/micro-components.test.js][]

Run them using:

$ npm test

Examples

Checkout the components folder in the repo for some examples. The CLI used to create component templates for example is a component itself.

License

MIT License