ssube/noicejs

extremely thin async dependency injection

noicejs

Extremely thin, async dependency injection, now with a getting started guide.

Inspired by Google's Guice library and written in Typescript.

Features

• async dependency resolution
• constructor and property injection
• modular containers with inheritance
• named dependencies using strings or unique symbols
• typed errors
• typescript typedefs
• zero runtime dependencies, bundled or otherwise
• extensive test coverage

Contents

• noicejs
  • Features
  • Contents
  • Status
  • Releases
  • Usage
  • Build
  • License

Status

Releases

• 3.x versions are compatible with Node 12+
• 4.x versions are compatible with Node 16+

Usage

Consider a Server class that needs to fetch data from the Cache and Filesystem, but doesn't know (or need to know) how those are implemented. The following example is also part of the unit tests.

import { LocalModule } from './local';
import { NetworkModule } from './network';

class Cache {
  public get(path: string, ttl: number, fallback: () => Promise<string>): Promise<string> {
    /* ... */
  }
}

class Filesystem {
  public get(path: string): Promise<string> {
    /* ... */
  }
}

/**
 * Constructors, strings, and symbols are supported. Symbols are
 * preferred, as the most unique, but names can be convenient.
 */
@Inject(Cache.name.toLowerCase(), Filesystem.name.toLowerCase())
class Server {
  protected readonly cache: Cache;
  protected readonly filesystem: Filesystem;
  protected readonly ttl: number;

  constructor(options) {
    this.cache = options.cache;
    this.filesystem = options.filesystem;
    this.ttl = defaultTo(options.ttl, 0);
  }

  get(path: string) {
    return options.cache.get(path, this.ttl, () => options.filesystem.get(path));
  }
}

const TEST_TTL = 60;

function module() {
  if (process.env['DEBUG'] === 'TRUE') {
    return new LocalModule();
  } else {
    return new NetworkModule();
  }
}

async function main() {
  const container = Container.from(module());
  await container.configure();

  const server = await container.create(Server, {
    /* cache and filesystem are found and injected by container */
    ttl: TEST_TTL,
  });

  /* server.cache.get and server.filesystem.get will be called in order */
  const result = await server.get('some/file');
}

noicejs will collect dependencies from the decorated constructor and any superclasses, find a provider for each injected dependency, and asynchronously resolve them before calling the constructor. Any extra parameters are passed on to the original constructor, along with the container and resolved dependencies.

Build

To build a bundle and run tests:

> make

yarn
yarn install v1.17.3
[1/4] Resolving packages...
success Already up-to-date.
Done in 0.20s.
/home/ssube/code/ssube/noicejs//node_modules/.bin/rollup --config /home/ssube/code/ssube/noicejs//config/rollup.js

src/index.ts, test/harness.ts, test/**/Test*.ts → out/...
...
created out/ in 3.3s
/home/ssube/code/ssube/noicejs//node_modules/.bin/api-extractor run --config /home/ssube/code/ssube/noicejs//config/api-extractor.json --local -v

api-extractor 7.3.8  - https://api-extractor.com/
...

API Extractor completed successfully
Success!

License

noicejs's Issues

shrink the bundle

The main-bundle.js file is much too large. According to the bundle report, it contains some dependencies. Remove them, minify it, and make sure things still work.

• named deps after minification
• lodash, etc outside of bundle

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

test logger compatibility

Summary

The Logger interface matches and interoperates with bunyan, which is good enough for isolex but may not be for general use. Ensure the logging is compatible with winston, at least.

Write an adapter, if necessary, and tests that get as close as possible to the bunyan and winston interfaces. Perhaps install them as devdeps and register a fake output stream.

make runnable notebook of examples

Summary

The readme, getting started guide, and docs/examples folders all have roughly the same examples, but no way to keep them in sync or run them.

Scope

• include code snippets from docs/examples, ideally
• make examples runnable, links or inline

fix doc pages

Summary

The current markdown docs don't translate perfectly into the GH pages site.

Details

• links in getting-started are not links (add titles)
• no index page causes a 404

update build

Update dependencies, lint config, and webpack config to roughly match isolex.

replace webpack with rollup

Webpack is very slow, requires 6-8GB of memory, and regularly produces incorrect output. Replace it with rollup.

add running examples/end-to-end tests

I want to add some working example scripts that show various common use cases and run as tests.

Use cases are:

• shared config file
• use with tests

update readme

The readme is out of date:

• pipeline badge (replace travis with gitlab)
• turn off travis entirely
• async examples

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on Greenkeeper branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please click the 'fix repo' button on account.greenkeeper.io.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on Greenkeeper branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please click the 'fix repo' button on account.greenkeeper.io.

make container implement module

Summary

To keep the module-tree consistent and allow container inheritance, make Container implement Module a proxy to its own modules and pass has/get through. This may help reduce logic in Container.create for lint.

Scope

• Container implements Module
  • has
  • get
• Container.create lint cleanup

Use Case

This will allow Container.from(container, ...modules) and tree inheritance.

Questions

Container.create currently has a cognitive complexity warning and is doing too much logic in one place. This is the first change to the container's API in some time, and a good chance to fix that.

This will be complicated by Module being an abstract base class, rather than the interface it should be. That will be a breaking change since consumers would have to extend BaseModule instead of extend Module. Introducing an interface with a different name would work, and may be otherwise beneficial since the current Module API contains a variety of bind/bindTo methods that Container shouldn't implement.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on Greenkeeper branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please click the 'fix repo' button on account.greenkeeper.io.

publish to npm

I need to start publishing a package of noice, so folks can actually use it.

support React views

I need to add support for injecting properties into React views. This will rely on object(/named) injection, #3.

support object injection

I need to add support for injecting parameters as an object with named fields, so we can provide names for the dependencies and either provide an object or merge them with an existing object. This is required for #2.

ensure extra parameters are typed correctly

Summary

Constructors and factories should enforce the first parameter (a subclass of BaseOptions), but allow anything for the remaining parameters. The current type is a ReadonlyArray<unknown> (https://github.com/ssube/noicejs/blob/master/src/Container.ts#L20). Write some tests and ensure that isn't too strict and is passed on correctly.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

---

Warning

Renovate failed to look up the following dependencies: Failed to look up npm package @istanbuljs/schema, Failed to look up npm package @microsoft/api-documenter, Failed to look up npm package @microsoft/api-extractor, Failed to look up npm package @types/chai, Failed to look up npm package @types/chai-as-promised, Failed to look up npm package @types/mocha, Failed to look up npm package @types/node, Failed to look up npm package @types/sinon-chai, Failed to look up npm package @types/source-map-support, Failed to look up npm package @typescript-eslint/eslint-plugin, Failed to look up npm package @typescript-eslint/parser, Failed to look up npm package c8, Failed to look up npm package chai, Failed to look up npm package chai-as-promised, Failed to look up npm package eslint, Failed to look up npm package eslint-plugin-chai, Failed to look up npm package eslint-plugin-chai-expect, Failed to look up npm package eslint-plugin-chai-expect-keywords, Failed to look up npm package eslint-plugin-import, Failed to look up npm package eslint-plugin-mocha, Failed to look up npm package eslint-plugin-no-null, Failed to look up npm package eslint-plugin-sonarjs, Failed to look up npm package mocha, Failed to look up npm package sinon, Failed to look up npm package sinon-chai, Failed to look up npm package source-map-support, Failed to look up npm package standard-version, Failed to look up npm package tslib, Failed to look up npm package typescript.

Files affected: package.json

---

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• update: update node.js to v20

Detected dependencies

dockerfile

Dockerfile.alpine

• node 17-alpine

Dockerfile.stretch

• node 17-stretch

gitlabci

.gitlab/ci-tools.yml

• docker.artifacts.apextoaster.com/apextoaster/base 1.5
• docker.artifacts.apextoaster.com/apextoaster/code-climate 0.6
• docker.artifacts.apextoaster.com/apextoaster/docker 20.10
• docker.artifacts.apextoaster.com/apextoaster/docker-dind 20.10
• docker.artifacts.apextoaster.com/apextoaster/node 16.19
• docker.artifacts.apextoaster.com/apextoaster/sonar-scanner 4.4

npm

package.json

• @istanbuljs/schema 0.1.3
• @microsoft/api-documenter 7.22.8
• @microsoft/api-extractor 7.35.1
• @types/chai 4.3.5
• @types/chai-as-promised 7.1.5
• @types/mocha 10.0.1
• @types/node 18.15.3
• @types/sinon-chai 3.2.9
• @types/source-map-support 0.5.6
• @typescript-eslint/eslint-plugin 5.59.11
• @typescript-eslint/parser 5.59.11
• c8 7.14.0
• chai 4.3.7
• chai-as-promised 7.1.1
• eslint 8.42.0
• eslint-plugin-chai 0.0.1
• eslint-plugin-chai-expect 3.0.0
• eslint-plugin-chai-expect-keywords 2.1.0
• eslint-plugin-import 2.27.5
• eslint-plugin-mocha 10.1.0
• eslint-plugin-no-null 1.0.2
• eslint-plugin-sonarjs 0.19.0
• mocha 10.2.0
• sinon 15.1.0
• sinon-chai 3.7.0
• source-map-support 0.5.21
• standard-version 9.5.0
• tslib 2.5.3
• typescript 4.9.5

---

• Check this box to trigger a request for Renovate to run again on this repository

log level should be an enum

Summary

The LogLevel type cannot be used, so logger definitions have to be written as { level: 'info' } despite the error message saying:

(property) BotData.logger: {
    level: LogLevel;
    name: string;
}
Property 'level' is missing in type '{ name: string; }' but required in type '{ level: LogLevel; name: string; }'.ts(2741)

ensure signature omit containers correctly

Summary

Wrapped constructors, factories, and other signature may not require a container property in their options, even if they did before. Luckily, mapped types offer Omit to handle this, so Omit<BaseOptions, 'container'> works for any options type that extends BaseOptions: that is, all of them.

Scope

• review typedefs for signatures with options, base or generic
• replace them with container-omitted options as appropriate

Use Case

Better typedefs.

update dependencies

Some of the dev dependencies are out of date. Update them and make everything green.

add dict module

Feature

Add a reference/example module that takes a dict or map of dependencies and registers them all as providers.

Summary

This will help keep the examples concise and should suffice for most simple uses of the library, saving folks the trouble of writing their own modules for very short programs.

Scope

• dict module
• map module

They might be the same module taking a MapLike and iterating over entries.