weenie-base v1.0.2

Weenie Base

NOTE: As of version 0.4.0, weenie is now a project of Wymp. Please use @wymp/weenie-base for future versions of this package.

Wymp publishes its packages to github package repository. To set your project up to use github package repository for the @wymp/weenie-base package, follow instructions here.

TL;DR

1. Generate a github personal auth token
2. Create an ~/.npmrc file if one doesn't already exist and add //npm.pkg.github.com/:_authToken=YOUR_AUTH_TOKEN to it, substituting the token you just created for YOUR_AUTH_TOKEN.
3. Create an .npmrc file in your repo root if you don't already have one and add this to it: @wymp:registry=https://npm.pkg.github.com/wymp.

Overview

This is the base package for the Weenie framework. See https://github.com/wymp/weenie-framework for a more full-bodied explanation of the weenie framework itself.

Weenie is a Typescript microservices framework. (Sort of.)

It attempts to provide a much simpler and easier solution to building microservices than other frameworks such as NestJS. In reality, while Weenie is called a microservices framework, it is nothing more than an easy and elegant way to create a strongly-typed dependency injection container.

This package provides a very minimal set of tools geared toward building that container. It is centered around a small function, Weenie, that allows you to build the DI container from the ground up, declaratively including and exposing only the dependencies you want, rather than relying on a big and/or opinionated framework for everything.

(For the full Weenie Framework, see https://github.com/wymp/weenie-framework, which provides several pre-built dependencies such as mysql, rabbitMQ, and a configurator to get you up and running quickly.)

The function definition of Weenie is as follows:

declare function Weenie<Deps = Obj>(deps: Deps): Extensible<Deps>;
declare type Obj = Record<string | number | symbol, unknown>;

declare type Extensible<Deps = Obj> = Deps & {
  and: <NextDeps extends Obj>(next: (deps: Deps) => NextDeps) => Extensible<Deps & NextDeps>;
  done: <FinalDeps extends Obj | Promise<Obj>>(fin: (deps: Deps) => FinalDeps) => FinalDeps;
};

In human language, all this says is:

For any given object, the Weenie function returns the object with two additional methods, and and done.

The and method takes a function, next, whose argument is the given object (or a subset of it, or nothing) and which returns an arbitrary new object. The and method returns a combination of the given object, the object returned by next, and an updated set of and and done methods.

The done method takes a function, final, whose argument is the given object (or a subset of it, or nothing) and which returns an arbitrary new object (optionally through a promise). The done method returns the value returned by final.

Here's a very minimal example of what that looks like in practice (see src/example.ts for a much more involved example):

type A = { a: string };
type B = { b: boolean };
type C = { c: number };
type Answer = { answer: string };

const a: A & Extensible<A> = Weenie({ a: "a" });
const b: A & B & Extensible<A & B> = a.and(() => ({ b: true }));
const c: A & B & C & Extensible<A & B & C> = b.and(() => ({ c: 3 }));
const full: A & B & C & Answer & Extensible<A & B & C & Answer> = c.and((deps: B) => ({
  answer: deps.b ? "D is the way" : "D is not the way",
}));
const final: Answer = full.done(deps => ({
  answer:
    `If A is ${a}, B is ${deps.b ? "true" : "false"} and C is ${deps.c}, then the answer ` +
    `is ${deps.answer}`,
}));

Note that each line adds a little bit to the total dependency container. The last call to the done method simply returns a type which is implied by whatever is returned by the function that is its argument. This allows you to encapsulate dependencies that should not be exposed publicly.

You can also build and run example.ts by cloning this repo and running npm i && npx tsc && nodejs ./dist/example.js.

Additional Exports

In addition to the core Weenie function, this library also exports a deepmerge function that it uses to perform object merging. This is simply for convenience for downstream libraries, since it seems deepmerge is an oft-wanted function. (It only implements a native deepmerge function to avoid a dependency, since Weenie is proudly dependency-free.)

Examples for Uses

Here's the simplest case: You like the way Weenie handles config and you want to use that to build a little script that just does some one-off task.

import { Weenie } from "weenie-base";

const app = new Weenie({
  config: { myVar: "abc" }
})
.and((d: { config: { myVar: string } }) => {
  return {
    output: d.config.myVar === "123" ? "We're in 123 mode" : "We're not in 123 mode",
  }
});

console.log(`My var: '${app.myVar}'`);
console.log(`Final output: ${app.output}`);
console.log("Yay, we did it!");
process.exit();

This example is almost uselessly simple, but it does demonstrate the value that Weenie offers: that you can chain together abstractions that declaratively build up a dependency container, then use that dependency container with total type safety.

In other words, in the above example, we created a Weenie with one initial property, config. Then we used the myVar property of the config object to add the output key to the container, and finally we used the finished container to output the message. If the config object had not defined myVar, Typescript would have thrown an error at compile time saying that myVar doesn't exist on the given object; if we had not returned an object with a string output value, Typescript would have thrown en error about that. Everything that we return from an and function gets tacked onto the dependency container, types included.

Thus, the result of using Weenie is easy-to-read dependency structuring with strict typing throughout.

See Weenie Framework for more complex examples.