Capsule

Small container implementation allowing automatic property resolving. This opens up for things like autoloading and configuration sharing.

Motivation

Before anything else; the Capsule module may prove to be a bad idea™.

The main reason to start experimenting with it was to figure out whether the concept of autoloading would be viable compared to elaborate exports and/or require (import) of deeply nested files.

Among other possible benefits, the way a Capsule allows for overrides could make some scenario's easier to implement, such as overriding functionality by simply assigning alternative values.

At the core the Capsule is merely a simple Proxy trap

Installation

@konfirm/capsule is a scoped package, which means the scope must be provided for both installation and usage.

Using npm

$ npm install --save @konfirm/capsule

Using yarn

$ yarn add @konfirm/capsule

Exports

The Capsule package exports a ready to use class, as well as some components it'll need to operate.

| name | purpose | | --------------------------- | -------------------------------------------------------------------------------------------------------------- | | * (default) | The default export is the Capsule class, but proxied in order provide a smooth out-of-the-box experience. | | Capsule | The real Capsule class (unproxied) | | Resolver | All of the resolvers provided by the Resolver package as object | | Resolver.AbstractResolver | The AbstractResolver, useful for implementing your own Resolvers | | Resolver.VirtualResolver | The VirtualResolver, a very eager Resolver, allowing everything | | Resolver.RequireResolver | The RequireResolver, a Resolver handling directories and every type of file require has to offer |

Usage

The main Capsule export should suffice for most use-cases, the initial set-up could look like:

const Path = require('path');
const Capsule = require('@konfirm/capsule');
const { VirtualResolver, RequireResolver } = Capsule;
const capsule = new Capsule(
	new RequireResolver(Path.join(__dirname, 'path', 'to', 'files')),
	new VirtualResolver()
);

Using this setup, the capsule variable will try to resolve any accessed property as directory or file (RequireResolver) or as anything else (VirtualResolver).

const One = capsule.One; // equivalent to require(`${__dirname}/path/to/files/One.js`);

As capsule is an object, it also allows for destructuring.

const { One, Two } = capsule;

// equivalent to
// const One = require(`${__dirname}/path/to/files/One.js`);
// const Two = require(`${__dirname}/path/to/files/Two.js`);

This has the potential to make loading files simple (linking in your favorite editor probably not so much).

API

The main Capsule export is a Proxy around the actual Capsule class. It allows for the addition of the Capsule and Resolver properties on it as well as providing the means to use a more consice syntax for the common use-case.

const Capsule = require('@konfirm/capsule');

Capsule

While the main export is a Proxy around the Capsule class itself, it can be accesed as property of the main export.

const { Capsule } = require('@konfirm/capsule');

or

const Capsule = require('@konfirm/capsule').Capsule;

Instances of the Capsule class are designed to work as [Proxy handler], for which it will trap the following operations

| trap | example | purpose | | ---------------------- | ---------------------------- | --------------------------------------------------- | | has | 'key' in capsule | trap for the in operator | | get | capsule.key | trap for getting a property value | | set | capsule.key = true | trap for setting a property value | | getPrototypeOf | capsule instanceof Capsule | trap for the [[GetPrototypeOf]] internal method |

Additionally the Capsule provides the encapsulated property, which provided a the Capsule as Proxied object, thus allowing the traps to be used transparently.

has

Using the 'key' in capsule syntax, the operation will be trapped by the has method, and it will determine whether the requested key is already available. Any key becomes becomes available if is has been added to the internal list of values, either by getting (implicit) or setting (explicit) the key.

Even if the key would be resolvable, the in operation would say no as the Capsule does not know of it yet.

const Capsule = require('@konfirm/capsule');
const { VirtualResolver } = Capsule;
const capsule = new Capsule(new VirtualResolver());

console.log('foo' in capsule); // false
console.log('bar' in capsule.foo); // false
console.log('foo' in capsule); // true, as it was resolved using a getter by stating capsule.foo

get

Any use of a property on a capsule will be trapped by the get method, if it has been assigned a value that value will be used. If no value has yet been assigned, Capsule will ask all Resolvers (in order) whether the key can be resolved. The first Resolver capable of resolving the requested property will do so and that value is then assigned for further use internally.

It depends on the Resolver implementation on what the return value will be, for a VirtualResolver it will always be a new (proxied) Capsule, while for a RequireResolver it depends on whether it resolved a directory (in which case the return value is a new (proxied) Capsule) or a (resolvable) file (in which case the value will be the files' contents).

const Capsule = require('@konfirm/capsule');
const { VirtualResolver } = Capsule;
const capsule = new Capsule(new RequireResolver(`${__dirname}/test/sample`));

const {
	Core: { One, Two }
} = capsule;
// equivalent to
// const One = require(`${__dirname}/test/sample/Core/One.js`);
// const Two = require(`${__dirname}/test/sample/Core/Two.js`);

set

Setting a property on a capsule will be trapped by the set method, no matter if it already contained a value it will always be reassigned the provided value.

const Capsule = require('@konfirm/capsule');
const { VirtualResolver } = Capsule;
const capsule = new Capsule(new VirtualResolver());

capsule.foo.bar.baz = 'qux';
capsule.foo = 'bar'; // while the bar.baz = 'qux' will still exist, they've now become unreachable

getPrototypeOf

Any means to determine the type of a Capsule instance will be trapped by the getPrototypeOf method, this trap mainly exists to allow for verification whether an instance is actually a Capsule. As the main export also implements this trap, there is not need to explicitly obtain the real Capsule class.

const Capsule = require('@konfirm/capsule');
const { VirtualResolver, Capsule: CapsuleClass } = Capsule;
const capsule = new Capsule(new VirtualResolver());

console.log(capsule.foo.bar instanceof Capsule); //  true
console.log(capsule.foo.bar instanceof CapsuleClass); //  true

License

MIT License Copyright (c) 2019 Rogier Spieker (Konfirm)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.