@lppedd/di-wise-neo 0.3.1 → 0.3.2

package/README.md

@@ -2,7 +2,13 @@
 <div align="center">
   <h1>di-wise-neo</h1>
   <p>Lightweight, type-safe, flexible dependency injection library for TypeScript and JavaScript</p>
-  <img src="./.github/images/neo-wall.jpg" title="di-wise-neo" alt="di-wise-neo" style="border: 3px solid black; border-radius: 15px;" />
+
+[![test](https://img.shields.io/github/actions/workflow/status/lppedd/di-wise-neo/test.yml.svg?branch=main)](https://github.com/lppedd/di-wise-neo/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/@lppedd/di-wise-neo?color=%23de1f1f&logo=npm)](https://www.npmjs.com/package/@lppedd/di-wise-neo)
+[![npm gzipped size](https://img.shields.io/bundlejs/size/@lppedd/di-wise-neo)](https://bundlejs.com/?q=@lppedd/di-wise-neo)
+[![license](https://img.shields.io/github/license/lppedd/di-wise-neo?color=blue)](https://github.com/lppedd/di-wise-neo/blob/main/LICENSE)
+
+  <img src="./.github/images/neo-wall.jpg" alt="di-wise-neo" style="border: 3px solid black; border-radius: 15px;" />
   <div><sub>yes, I like The Matrix</sub></div>
 </div>
 
@@ -16,12 +22,14 @@
 
 - [Why yet another library](#why-yet-another-library)
 - [Installation](#installation)
+- [API reference](#api-reference)
 - [Ergonomics](#ergonomics)
 - [Quickstart](#quickstart)
 - [Container scopes](#container-scopes)
 - [Token registration](#token-registration)
 - [Function-based injection](#function-based-injection)
 - [Decorator-based injection](#decorator-based-injection)
+- [Behavioral decorators](#behavioral-decorators)
 - [Testing support](#testing-support)
 
 ## Why yet another library
@@ -75,7 +83,7 @@ production needs.
 ## Installation
 
 ```sh
-npm install @lppedd/di-wise-neo
+npm i @lppedd/di-wise-neo
 ```
 
 ```sh
@@ -85,6 +93,9 @@ pnpm add @lppedd/di-wise-neo
 ```sh
 yarn add @lppedd/di-wise-neo
 ```
+## API reference
+
+You can find the complete API reference at https://lppedd.github.io/di-wise-neo
 
 ## Ergonomics
 
@@ -139,7 +150,7 @@ const container = createContainer({
   defaultScope: Scope.Container,
 });
 
-// Register our managed dependencies into the container
+// Register our managed dependencies in the container
 container.register(ExtensionContext)
          .register(SecretStore)
          .register(ContributionRegistrar);
@@ -209,7 +220,7 @@ Alternatively, use an explicit `ClassProvider` object - useful when registering
 an interface or abstract type:
 
 ```ts
-const Store = Type<Store>("Store");
+const Store = createType<Store>("Store");
 container.register(Store, {
   useClass: SecretStore, // class SecretStore implements Store
 });
@@ -223,7 +234,7 @@ caching it according to the configured scope.
 A lazily computed value can be registered using a factory function:
 
 ```ts
-const Env = Type<string>("Env")
+const Env = createType<string>("Env")
 container.register(Env, {
   useFactory: () => isNode() ? "Node.js" : "browser",
 });
@@ -237,7 +248,7 @@ according to the configured scope.
 A static value - always taken as-is and unaffected by scopes - can be registered using:
 
 ```ts
-const PID = Type<number>("PID");
+const PID = createType<number>("PID");
 const processId = spawnProcess();
 container.register(PID, {
   useValue: processId,
@@ -253,7 +264,7 @@ Registers an alias to another token, allowing multiple identifiers to resolve to
 Using the previous `PID` example, we can register a `TaskID` alias:
 
 ```ts
-const TaskID = Type<number>("TaskID");
+const TaskID = createType<number>("TaskID");
 container.register(TaskID, {
   useExisting: PID,
 });
@@ -424,10 +435,55 @@ export class ExtensionContext {
 }
 ```
 
+## Behavioral decorators
+
+The library includes two behavioral decorators that influence how classes are registered in the container.
+These decorators attach metadata to the class type, which is then interpreted by the container during registration.
+
+### `@Scoped`
+
+Specifies a default scope for the decorated class:
+
+```ts
+@Scoped(Scope.Container)
+export class ExtensionContext {
+  /* ... */
+}
+```
+
+Applying `@Scoped(Scope.Container)` to the `ExtensionContext` class instructs the DI container
+to register it with the **Container** scope by default.
+
+This default can be overridden by explicitly providing registration options:
+
+```ts
+container.register(
+  ExtensionContext,
+  { useClass: ExtensionContext },
+  { scope: Scope.Resolution },
+);
+```
+
+In this example, `ExtensionContext` will be registered with **Resolution** scope instead.
+
+### `@AutoRegister`
+
+Enables automatic registration of the decorated class if it has not been registered explicitly.
+
+```ts
+@AutoRegister()
+export class ExtensionContext {
+  /* ... */
+}
+
+// Resolve the class without prior registration. It works!
+container.resolve(ExtensionContext);
+```
+
 ## Testing support
 
 Testing is an important part of software development, and dependency injection is meant to make it easier.  
-The **di-wise-neo** container API exposes methods to more easily integrate with testing scenarios.
+The container API exposes methods to more easily integrate with testing scenarios.
 
 ### `resetRegistry`
 

package/dist/cjs/index.d.ts

@@ -1,19 +1,3 @@
-/**
- * Constructor type.
- */
-interface Constructor<Instance extends object> {
-    new (...args: any[]): Instance;
-    readonly name: string;
-    readonly length: number;
-}
-/**
- * Token type.
- */
-type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value> : Type<Value>;
-/**
- * Describes a {@link Token} array with at least one element.
- */
-type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
 /**
  * Type API.
  */
@@ -27,8 +11,8 @@ interface Type<A> {
      *
      * @example
      * ```ts
-     * const A = Type<A>("A");
-     * const B = Type<B>("B");
+     * const A = createType<A>("A");
+     * const B = createType<B>("B");
      *
      * A.inter("I", B); // => Type<A & B>
      * ```
@@ -39,25 +23,41 @@ interface Type<A> {
      *
      * @example
      * ```ts
-     * const A = Type<A>("A");
-     * const B = Type<B>("B");
+     * const A = createType<A>("A");
+     * const B = createType<B>("B");
      *
      * A.union("U", B); // => Type<A | B>
      * ```
      */
     union<B>(typeName: string, B: Type<B>): Type<A | B>;
 }
+/**
+ * Constructor type.
+ */
+interface Constructor<Instance extends object> {
+    new (...args: any[]): Instance;
+    readonly name: string;
+    readonly length: number;
+}
+/**
+ * Token type.
+ */
+type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value> : Type<Value>;
+/**
+ * Describes a {@link Token} array with at least one element.
+ */
+type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
 /**
  * Create a type token.
  *
  * @example
  * ```ts
- * const Spell = Type<Spell>("Spell");
+ * const Spell = createType<Spell>("Spell");
  * ```
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Type<T>(typeName: string): Type<T>;
+declare function createType<T>(typeName: string): Type<T>;
 
 /**
  * Provides a class instance for a token via a class constructor.
@@ -115,7 +115,7 @@ interface RegistrationOptions {
  * ```ts
  * class Wizard {
  *   wand = inject(
- *     Build(() => {
+ *     build(() => {
  *       const wand = inject(Wand);
  *       wand.owner = this;
  *       // ...
@@ -127,7 +127,7 @@ interface RegistrationOptions {
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Build<Value>(factory: (...args: []) => Value): Type<Value>;
+declare function build<Value>(factory: (...args: []) => Value): Type<Value>;
 
 /**
  * Container creation options.
@@ -768,5 +768,5 @@ interface Middleware {
  */
 declare function applyMiddleware(container: Container, middlewares: Middleware[]): Container;
 
-export { AutoRegister, Build, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, Type, applyMiddleware, createContainer, forwardRef, inject, injectAll, injectBy };
-export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, ValueProvider };
+export { AutoRegister, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy };
+export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };

package/dist/cjs/index.js

@@ -235,15 +235,15 @@ const Scope = {
  *
  * @example
  * ```ts
- * const Spell = Type<Spell>("Spell");
+ * const Spell = createType<Spell>("Spell");
  * ```
  *
  * @__NO_SIDE_EFFECTS__
- */ function Type(typeName) {
+ */ function createType(typeName) {
     const type = {
         name: `Type<${typeName}>`,
-        inter: Type,
-        union: Type,
+        inter: createType,
+        union: createType,
         toString () {
             return type.name;
         }
@@ -349,7 +349,7 @@ function isBuilder(provider) {
  * ```ts
  * class Wizard {
  *   wand = inject(
- *     Build(() => {
+ *     build(() => {
  *       const wand = inject(Wand);
  *       wand.owner = this;
  *       // ...
@@ -360,8 +360,8 @@ function isBuilder(provider) {
  * ```
  *
  * @__NO_SIDE_EFFECTS__
- */ function Build(factory) {
-    const token = Type(`Build<${getTypeName(factory)}>`);
+ */ function build(factory) {
+    const token = createType(`Build<${getTypeName(factory)}>`);
     const provider = {
         useFactory: factory
     };
@@ -961,7 +961,7 @@ function OptionalAll(token) {
  * const wizard = container.resolve(Wizard);
  * wizard.getWand(); // => Wand
  * ```
- */ const Injector = /*@__PURE__*/ Build(function Injector() {
+ */ const Injector = /*@__PURE__*/ build(function Injector() {
     const context = ensureInjectionContext(Injector);
     const resolution = context.resolution;
     const dependentFrame = resolution.stack.peek();
@@ -1036,7 +1036,6 @@ function OptionalAll(token) {
 }
 
 exports.AutoRegister = AutoRegister;
-exports.Build = Build;
 exports.Inject = Inject;
 exports.InjectAll = InjectAll;
 exports.Injectable = Injectable;
@@ -1045,9 +1044,10 @@ exports.Optional = Optional;
 exports.OptionalAll = OptionalAll;
 exports.Scope = Scope;
 exports.Scoped = Scoped;
-exports.Type = Type;
 exports.applyMiddleware = applyMiddleware;
+exports.build = build;
 exports.createContainer = createContainer;
+exports.createType = createType;
 exports.forwardRef = forwardRef;
 exports.inject = inject;
 exports.injectAll = injectAll;