ts-ioc-container 72.1.0 → 72.2.0

package/AGENTS.md

@@ -0,0 +1,179 @@
+# ts-ioc-container — guide for AI coding agents
+
+This file ships inside the npm package, so it matches the version installed in
+`node_modules`. **Trust it over what you remember**: the API changed a lot
+between major versions, and code written for an older version usually compiles
+badly or not at all. Every recipe below is executed by the package's test suite
+(`__tests__/readme/agentRecipes.spec.ts`).
+
+More detail: `README.md` next to this file. Types with JSDoc: `typings/`.
+Source: `lib/`.
+
+## Setup
+
+```shell
+npm install ts-ioc-container reflect-metadata
+```
+
+```typescript
+import 'reflect-metadata'; // first line of the entrypoint
+```
+
+```json
+{ "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } }
+```
+
+## Recipes
+
+### Register a class and inject it by token
+
+```typescript
+import { bindTo, by, Container, inject, register, Registration as R, scope, singleton, SingleToken } from 'ts-ioc-container';
+
+interface ILogger {
+  log(message: string): void;
+}
+const ILoggerToken = new SingleToken<ILogger>('ILogger');
+
+@register(bindTo(ILoggerToken), scope((s) => s.hasTag('application')), singleton())
+class Logger implements ILogger {
+  log(message: string) {}
+}
+
+class App {
+  constructor(@inject(by(ILoggerToken)) private logger: ILogger) {}
+}
+
+const container = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
+const app = container.resolve(App); // an unregistered class is constructed by the injector
+```
+
+### Request-scoped service depending on an application singleton
+
+```typescript
+const IRepositoryToken = new SingleToken<Repository>('IRepository');
+
+@register(bindTo(IRepositoryToken), scope((s) => s.hasTag('request')), singleton())
+class Repository {
+  constructor(@inject(by(ILoggerToken)) readonly logger: ILogger) {}
+}
+
+const app = new Container({ tags: ['application'] })
+  .addRegistration(R.fromClass(Logger))
+  .addRegistration(R.fromClass(Repository));
+
+const request = app.createScope({ tags: ['request'] }); // one per request
+const repo = IRepositoryToken.resolve(request);
+request.dispose(); // when the request ends; child scopes are not disposed automatically
+```
+
+Use tags `application` / `request` / `transaction` on a backend and
+`application` / `page` / `widget` on a frontend.
+
+### Values and factories
+
+```typescript
+container
+  .addRegistration(R.fromValue('https://api.example.com').bindTo('API_URL'))
+  .addRegistration(R.fromFn(({ scope }) => `${scope.resolve<string>('API_URL')}/v1`).bindTo('API_V1'));
+```
+
+Use the fluent `.bindTo(...)` only for `fromValue` / `fromFn` and for classes
+you don't own. For your own classes, use `@register(bindTo(...))`.
+
+### Runtime arguments
+
+```typescript
+@register(bindTo(IClientToken))
+class Client {
+  constructor(@inject(arg(0)) readonly baseUrl: string) {}
+}
+
+IClientToken.args('https://a.example.com').resolve(container);
+IClientToken.resolve(container, { args: ['https://b.example.com'] });
+container.resolve<Client>('IClient', { args: ['https://c.example.com'] });
+```
+
+`token.args(...)`, `token.argsFn(...)` and `token.lazy()` return a **new**
+token; the original is never changed.
+
+### Lifecycle hooks (you run them)
+
+The library only **collects** hooks. It ships no hook names, no hook modules and
+no runner. Define the hook name, collect on an event, and run the actions:
+
+```typescript
+import { hook, HookCollector, type HookType, runInOrder, toTask } from 'ts-ioc-container';
+
+const onInit = (fn: HookType) => hook('onInit', fn);
+const onInitHooks = new HookCollector({ key: 'onInit' });
+
+class Service {
+  @onInit((ctx) => {
+    ctx.invokeMethod({ args: ctx.resolveArgs() }); // hook functions return void
+  })
+  init() {}
+}
+
+container.getInjector().onConstructed((instance, scope) => {
+  void runInOrder(onInitHooks.getActions(instance, { scope }).map(toTask));
+});
+```
+
+Other events to collect on: `container.scopeDisposed.subscribe(...)`,
+`container.registered.subscribe((provider) => provider.onResolved(...))`, or the
+`onResolve(...)` registration pipe for a single registration. Combine several
+hooks on one member with `sequential(...)`, `parallel(...)` or
+`oncePerInstance(...)`. Decorating one member twice with the same key replaces
+the first hook.
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Constructor param is `undefined` | Params without `@inject` are never injected | Annotate every param: `@inject(by(Token))` |
+| TS error on `@inject(Token)` | `inject` takes one `InjectFn` | `@inject(by(Token))`, `@inject(by('Key'))`, `@inject(by(Class))` |
+| TS error on `container.resolve(Token)` | `container.resolve` takes a key or a class | `Token.resolve(container)` |
+| A "singleton" differs per request | A registration without `scope(...)` is copied into every child scope | Add `scope((s) => s.hasTag('application'))` |
+| `DependencyNotFoundError` from an outer scope | Outer scopes cannot resolve inner-scope-only dependencies | Register the dependency in the outer scope too, or move the consumer inward |
+| Registration missing in an existing child scope | Scopes copy registrations when `createScope()` runs | Register before creating the scope, or add it to the child |
+| Constructor receives a token object instead of an instance | Args are passed as-is, never resolved | `Token.argsFn((scope) => [Other.resolve(scope)])` |
+| Hook method never runs | Nothing runs hooks for you | Collect with `HookCollector` and run the actions (see above) |
+| TS error on a hook arrow function | `HookFn` must return `void` or `Promise<void>` | Use a block body: `(ctx) => { ... }` |
+| `@inject` metadata missing at runtime | `reflect-metadata` not imported first | `import 'reflect-metadata'` at the top of the entrypoint |
+
+## Removed APIs (do not use)
+
+| Removed | Use instead |
+| --- | --- |
+| `@inject(Token)`, `@inject('Key')`, `@inject(Token, ...mappers)` | `@inject(by(Token))`, `@inject(pipe(by(Token), mapFn))` |
+| `toMappedToken` | `pipe(by(Token), ...mappers)` |
+| `InjectFn` as `(scope, options)` | `({ scope, args }) => ...` — the scope is inside the options object |
+| `onConstruct`, `onDispose`, `onResolved` decorators from the library | Define your own: `const onConstruct = (fn: HookType) => hook('onConstruct', fn)` |
+| `OnConstructModule`, `OnDisposeModule`, `OnResolvedModule`, `resolved(...)` | Subscribe to `getInjector().onConstructed`, `scopeDisposed`, `registered` yourself |
+| Hook execution strategies, `onError` options | Run the collected actions yourself (`runInOrder`, `runAtOnce`, `toTask`) |
+| `Async`-suffixed hooks and modules | Hooks are async-capable by default |
+| `onceResolved`, `onceResolvedAsync` | `oncePerInstance(hook)` |
+| Several hooks passed to one `@hook(...)` | `@hook(key, sequential(a, b))` or `parallel(a, b)` |
+| `container.onScopeCreated(...)` and similar methods | `container.scopeCreated.subscribe(...)` (events return an unsubscribe fn) |
+| `args(index)` injector helper | `arg(index)`; `args` now injects the whole args array |
+| `InjectionToken.getKey()` | Tokens are `Serializable` |
+| Args that are tokens being auto-resolved | `token.argsFn((scope) => [Other.resolve(scope)])` |
+| `isProxy`, `getProxyTarget` | `unwrapProxy` |
+
+## Errors
+
+All errors extend `ContainerError` and carry a stable `code`:
+
+| Code | Error | Usually means |
+| --- | --- | --- |
+| `IOC_DEPENDENCY_NOT_FOUND` | `DependencyNotFoundError` | Key not registered in this scope chain, or excluded by `scope(...)` / `scopeAccess(...)` |
+| `IOC_DEPENDENCY_MISSING_KEY` | `DependencyMissingKeyError` | A registration has no key: add `bindTo(...)` |
+| `IOC_CONTAINER_DISPOSED` | `ContainerDisposedError` | Using a scope after `dispose()` |
+| `IOC_PROVIDER_DISPOSED` | `ProviderDisposedError` | Using a provider after its scope was disposed |
+| `IOC_EVENT_DISPOSED` | `TypedEventDisposedError` | Subscribing to an event of a disposed scope |
+| `IOC_SINGLETON_APPLIED_TWICE` | `CannotApplySingletonTwiceError` | `singleton()` appears twice in one registration |
+| `IOC_UNSUPPORTED_TOKEN_TYPE` | `UnsupportedTokenTypeError` | `toToken(...)` got a value that is not a key, class or token |
+| `IOC_ARGUMENT_NOT_FOUND` | `ArgumentNotFoundError` | `findOrFail` / `argsFn` predicate matched nothing |
+| `IOC_CONTAINER_NOT_FOUND` | `ContainerNotFoundError` | No container is associated with the target |
+| `IOC_METHOD_NOT_IMPLEMENTED` | `MethodNotImplementedError` | Called a method the object does not support (e.g. on `EmptyContainer`) |

package/cjm/container/Container.js

@@ -164,12 +164,12 @@ class Container {
     }
     validateContainer() {
         if (this.isDisposed) {
-            throw new ContainerDisposedError_1.ContainerDisposedError('Container is already disposed');
+            throw new ContainerDisposedError_1.ContainerDisposedError('Container is already disposed: a scope cannot be used after dispose(). Create a new scope.');
         }
     }
     findProviderByKeyOrFail(key) {
         if (!this.providers.has(key)) {
-            throw new DependencyNotFoundError_1.DependencyNotFoundError(`Provider ${key.toString()} does not exist`);
+            throw new DependencyNotFoundError_1.DependencyNotFoundError(`Provider ${key.toString()} does not exist: an alias points at a key with no provider in this scope.`);
         }
         return this.providers.get(key);
     }

package/cjm/container/EmptyContainer.js

@@ -5,7 +5,7 @@ const MethodNotImplementedError_1 = require("../errors/MethodNotImplementedError
 const DependencyNotFoundError_1 = require("../errors/DependencyNotFoundError");
 class EmptyContainer {
     get isDisposed() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.isDisposed is not implemented');
     }
     addInstance(instance) { }
     getParent() {
@@ -21,25 +21,25 @@ class EmptyContainer {
         return false;
     }
     createScope() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.createScope is not implemented');
     }
     getInjector() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.getInjector is not implemented');
     }
     autoResolve(options) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.autoResolve is not implemented');
     }
     dispose() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.dispose is not implemented');
     }
     register(key, value) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.register is not implemented');
     }
     hasTag(tag) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.hasTag is not implemented');
     }
     addTags(...tags) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.addTags is not implemented');
     }
     getRegistrations() {
         return [];
@@ -49,28 +49,30 @@ class EmptyContainer {
     }
     removeScope() { }
     useModule(module) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.useModule is not implemented');
     }
     addRegistration(registration) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.addRegistration is not implemented');
     }
     resolve(key, options) {
-        throw new DependencyNotFoundError_1.DependencyNotFoundError(`Cannot find ${key.toString()}`);
+        throw new DependencyNotFoundError_1.DependencyNotFoundError(`Cannot find ${key.toString()}: no provider for this key in the resolving scope or any parent. ` +
+            'Check that it is registered, that its scope(...) rule matches this scope, that its scopeAccess(...) rule allows it, ' +
+            'and that it was registered before createScope() (existing child scopes are not updated).');
     }
     resolveByAlias(alias, options) {
         return [];
     }
     resolveOneByAlias(alias, options) {
-        throw new DependencyNotFoundError_1.DependencyNotFoundError(`Cannot find alias ${alias.toString()}`);
+        throw new DependencyNotFoundError_1.DependencyNotFoundError(`Cannot find alias ${alias.toString()}: no accessible registration carries this alias in the resolving scope or any parent.`);
     }
     get scopeCreated() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.scopeCreated is not implemented');
     }
     get scopeDisposed() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.scopeDisposed is not implemented');
     }
     get registered() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError();
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.registered is not implemented');
     }
 }
 exports.EmptyContainer = EmptyContainer;

package/cjm/errors/ArgumentNotFoundError.js

@@ -4,6 +4,7 @@ exports.ArgumentNotFoundError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class ArgumentNotFoundError extends ContainerError_1.ContainerError {
     name = 'ArgumentNotFoundError';
+    code = 'IOC_ARGUMENT_NOT_FOUND';
     constructor(message = 'Argument not found') {
         super(message);
         Object.setPrototypeOf(this, ArgumentNotFoundError.prototype);

package/cjm/errors/CannonSingletonApplyTwiceError.js

@@ -1,17 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CannonSingletonApplyTwiceError = void 0;
-const ContainerError_1 = require("./ContainerError");
-class CannonSingletonApplyTwiceError extends ContainerError_1.ContainerError {
-    name = 'CannonSingletonApplyTwiceError';
-    constructor(message) {
-        super(message);
-        Object.setPrototypeOf(this, CannonSingletonApplyTwiceError.prototype);
-    }
-    static assert(isTrue, failMessage) {
-        if (!isTrue) {
-            throw new CannonSingletonApplyTwiceError(failMessage);
-        }
-    }
-}
-exports.CannonSingletonApplyTwiceError = CannonSingletonApplyTwiceError;
+const CannotApplySingletonTwiceError_1 = require("./CannotApplySingletonTwiceError");
+exports.CannonSingletonApplyTwiceError = CannotApplySingletonTwiceError_1.CannotApplySingletonTwiceError;

package/cjm/errors/CannotApplySingletonTwiceError.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CannotApplySingletonTwiceError = void 0;
+const ContainerError_1 = require("./ContainerError");
+class CannotApplySingletonTwiceError extends ContainerError_1.ContainerError {
+    name = 'CannotApplySingletonTwiceError';
+    code = 'IOC_SINGLETON_APPLIED_TWICE';
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, CannotApplySingletonTwiceError.prototype);
+    }
+    static assert(isTrue, failMessage) {
+        if (!isTrue) {
+            throw new CannotApplySingletonTwiceError(failMessage);
+        }
+    }
+}
+exports.CannotApplySingletonTwiceError = CannotApplySingletonTwiceError;

package/cjm/errors/ContainerDisposedError.js

@@ -4,6 +4,7 @@ exports.ContainerDisposedError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class ContainerDisposedError extends ContainerError_1.ContainerError {
     name = 'ContainerDisposedError';
+    code = 'IOC_CONTAINER_DISPOSED';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, ContainerDisposedError.prototype);

package/cjm/errors/ContainerError.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContainerError = void 0;
 class ContainerError extends Error {
     name = 'ContainerError';
+    code = 'IOC_CONTAINER_ERROR';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, ContainerError.prototype);

package/cjm/errors/ContainerNotFoundError.js

@@ -4,6 +4,7 @@ exports.ContainerNotFoundError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class ContainerNotFoundError extends ContainerError_1.ContainerError {
     name = 'ContainerNotFoundError';
+    code = 'IOC_CONTAINER_NOT_FOUND';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, ContainerNotFoundError.prototype);

package/cjm/errors/DependencyMissingKeyError.js

@@ -4,6 +4,7 @@ exports.DependencyMissingKeyError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class DependencyMissingKeyError extends ContainerError_1.ContainerError {
     name = 'DependencyMissingKeyError';
+    code = 'IOC_DEPENDENCY_MISSING_KEY';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, DependencyMissingKeyError.prototype);

package/cjm/errors/DependencyNotFoundError.js

@@ -4,6 +4,7 @@ exports.DependencyNotFoundError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class DependencyNotFoundError extends ContainerError_1.ContainerError {
     name = 'DependencyNotFoundError';
+    code = 'IOC_DEPENDENCY_NOT_FOUND';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, DependencyNotFoundError.prototype);

package/cjm/errors/MethodNotImplementedError.js

@@ -4,6 +4,7 @@ exports.MethodNotImplementedError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class MethodNotImplementedError extends ContainerError_1.ContainerError {
     name = 'MethodNotImplementedError';
+    code = 'IOC_METHOD_NOT_IMPLEMENTED';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, MethodNotImplementedError.prototype);

package/cjm/errors/ProviderDisposedError.js

@@ -4,6 +4,7 @@ exports.ProviderDisposedError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class ProviderDisposedError extends ContainerError_1.ContainerError {
     name = 'ProviderDisposedError';
+    code = 'IOC_PROVIDER_DISPOSED';
     static assert(isTrue, failMessage) {
         if (!isTrue) {
             throw new ProviderDisposedError(failMessage);

package/cjm/errors/TypedEventDisposedError.js

@@ -4,6 +4,7 @@ exports.TypedEventDisposedError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class TypedEventDisposedError extends ContainerError_1.ContainerError {
     name = 'TypedEventDisposedError';
+    code = 'IOC_EVENT_DISPOSED';
     static assert(isTrue, failMessage) {
         if (!isTrue) {
             throw new TypedEventDisposedError(failMessage);

package/cjm/errors/UnsupportedTokenTypeError.js

@@ -4,6 +4,7 @@ exports.UnsupportedTokenTypeError = void 0;
 const ContainerError_1 = require("./ContainerError");
 class UnsupportedTokenTypeError extends ContainerError_1.ContainerError {
     name = 'UnsupportedTokenTypeError';
+    code = 'IOC_UNSUPPORTED_TOKEN_TYPE';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, UnsupportedTokenTypeError.prototype);

package/cjm/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createHookExecutionContext = exports.createHookContextFactory = exports.HookContext = exports.toHookFn = exports.hasHooks = exports.hook = exports.getHooks = exports.ArgumentNotFoundError = exports.TypedEventDisposedError = exports.UnsupportedTokenTypeError = exports.CannonSingletonApplyTwiceError = exports.ProviderDisposedError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.ContainerNotFoundError = exports.DependencyNotFoundError = exports.ContainerError = exports.Registration = exports.onResolve = exports.appendArgsFn = exports.appendArgs = exports.decorate = exports.singleton = exports.autoResolve = exports.lazy = exports.scopeAccess = exports.scope = exports.bindTo = exports.register = exports.toRegistrationFn = exports.toProviderFn = exports.toBindToken = exports.registerPipe = exports.isProviderPipe = exports.Provider = exports.ProxyInjector = exports.SimpleInjector = exports.resolveArgs = exports.by = exports.argsFn = exports.args = exports.arg = exports.inject = exports.MetadataInjector = exports.Injector = exports.EmptyContainer = exports.AutoResolveModule = exports.Container = exports.isDependencyKey = void 0;
-exports.once = exports.shallowCache = exports.debounce = exports.throttle = exports.runAtOnce = exports.runInOrder = exports.handleAsyncError = exports.handleError = exports.createComposeMethodDecorator = exports.getMethodTags = exports.addMethodTag = exports.getMethodLabels = exports.addMethodLabel = exports.getMethodMeta = exports.addMethodMeta = exports.createComposeParameterDecorator = exports.getParamTags = exports.addParamTag = exports.getParamLabels = exports.addParamLabel = exports.getParamMeta = exports.addParamMeta = exports.createComposeClassDecorator = exports.getClassTags = exports.addClassTag = exports.getClassLabels = exports.addClassLabel = exports.getClassMeta = exports.addClassMeta = exports.resolveConstructor = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.ClassToken = exports.toSingleAlias = exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.argToToken = exports.toToken = exports.forwardArgs = exports.isInjectionToken = exports.InjectionToken = exports.toTask = exports.HookCollector = exports.oncePerInstance = exports.parallel = exports.sequential = exports.injectProp = void 0;
-exports.isSerializable = exports.Is = exports.unwrapProxy = exports.ProxyRegistry = exports.findOrFail = exports.pipe = exports.select = exports.TypedEvent = exports.getConstructorChain = exports.memoize = void 0;
+exports.createHookContextFactory = exports.HookContext = exports.toHookFn = exports.hasHooks = exports.hook = exports.getHooks = exports.ArgumentNotFoundError = exports.TypedEventDisposedError = exports.UnsupportedTokenTypeError = exports.CannonSingletonApplyTwiceError = exports.CannotApplySingletonTwiceError = exports.ProviderDisposedError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.ContainerNotFoundError = exports.DependencyNotFoundError = exports.ContainerError = exports.Registration = exports.onResolve = exports.appendArgsFn = exports.appendArgs = exports.decorate = exports.singleton = exports.autoResolve = exports.lazy = exports.scopeAccess = exports.scope = exports.bindTo = exports.register = exports.toRegistrationFn = exports.toProviderFn = exports.toBindToken = exports.registerPipe = exports.isProviderPipe = exports.Provider = exports.ProxyInjector = exports.SimpleInjector = exports.resolveArgs = exports.by = exports.argsFn = exports.args = exports.arg = exports.inject = exports.MetadataInjector = exports.Injector = exports.EmptyContainer = exports.AutoResolveModule = exports.Container = exports.isDependencyKey = void 0;
+exports.shallowCache = exports.debounce = exports.throttle = exports.runAtOnce = exports.runInOrder = exports.handleAsyncError = exports.handleError = exports.createComposeMethodDecorator = exports.getMethodTags = exports.addMethodTag = exports.getMethodLabels = exports.addMethodLabel = exports.getMethodMeta = exports.addMethodMeta = exports.createComposeParameterDecorator = exports.getParamTags = exports.addParamTag = exports.getParamLabels = exports.addParamLabel = exports.getParamMeta = exports.addParamMeta = exports.createComposeClassDecorator = exports.getClassTags = exports.addClassTag = exports.getClassLabels = exports.addClassLabel = exports.getClassMeta = exports.addClassMeta = exports.resolveConstructor = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.ClassToken = exports.toSingleAlias = exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.argToToken = exports.toToken = exports.forwardArgs = exports.isInjectionToken = exports.InjectionToken = exports.toTask = exports.HookCollector = exports.oncePerInstance = exports.parallel = exports.sequential = exports.injectProp = exports.createHookExecutionContext = void 0;
+exports.isSerializable = exports.Is = exports.unwrapProxy = exports.ProxyRegistry = exports.findOrFail = exports.pipe = exports.select = exports.TypedEvent = exports.getConstructorChain = exports.memoize = exports.once = void 0;
 var IContainer_1 = require("./container/IContainer");
 Object.defineProperty(exports, "isDependencyKey", { enumerable: true, get: function () { return IContainer_1.isDependencyKey; } });
 var Container_1 = require("./container/Container");
@@ -60,6 +60,8 @@ var ContainerDisposedError_1 = require("./errors/ContainerDisposedError");
 Object.defineProperty(exports, "ContainerDisposedError", { enumerable: true, get: function () { return ContainerDisposedError_1.ContainerDisposedError; } });
 var ProviderDisposedError_1 = require("./errors/ProviderDisposedError");
 Object.defineProperty(exports, "ProviderDisposedError", { enumerable: true, get: function () { return ProviderDisposedError_1.ProviderDisposedError; } });
+var CannotApplySingletonTwiceError_1 = require("./errors/CannotApplySingletonTwiceError");
+Object.defineProperty(exports, "CannotApplySingletonTwiceError", { enumerable: true, get: function () { return CannotApplySingletonTwiceError_1.CannotApplySingletonTwiceError; } });
 var CannonSingletonApplyTwiceError_1 = require("./errors/CannonSingletonApplyTwiceError");
 Object.defineProperty(exports, "CannonSingletonApplyTwiceError", { enumerable: true, get: function () { return CannonSingletonApplyTwiceError_1.CannonSingletonApplyTwiceError; } });
 var UnsupportedTokenTypeError_1 = require("./errors/UnsupportedTokenTypeError");

package/cjm/provider/Provider.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Provider = void 0;
 const basic_1 = require("../utils/basic");
-const CannonSingletonApplyTwiceError_1 = require("../errors/CannonSingletonApplyTwiceError");
+const CannotApplySingletonTwiceError_1 = require("../errors/CannotApplySingletonTwiceError");
 const ProviderDisposedError_1 = require("../errors/ProviderDisposedError");
 class Provider {
     resolveDependency;
@@ -28,7 +28,7 @@ class Provider {
         this.resolveDependency = resolveDependency;
     }
     resolve(options) {
-        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         if (!this.getKey) {
             return this.resolveDep(options);
         }
@@ -67,7 +67,7 @@ class Provider {
         return this;
     }
     isAutoResolvable() {
-        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         return this.isAutoResolve;
     }
     addArgsFn(...fns) {
@@ -75,11 +75,11 @@ class Provider {
         return this;
     }
     hasAccess(options) {
-        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         return this.accessRules.reduce((acc, rule) => rule(options, acc), true);
     }
     singleton(getCacheKey = () => '1') {
-        CannonSingletonApplyTwiceError_1.CannonSingletonApplyTwiceError.assert(!this.getKey, 'Provider is already singleton');
+        CannotApplySingletonTwiceError_1.CannotApplySingletonTwiceError.assert(!this.getKey, 'Provider is already singleton: singleton() was applied twice to the same provider. Remove the duplicate singleton().');
         this.getKey = getCacheKey;
         return this;
     }
@@ -88,7 +88,7 @@ class Provider {
         return this;
     }
     dispose() {
-        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError_1.ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         this.isDisposed = true;
         this.isAutoResolve = false;
         this.getKey = undefined;

package/cjm/registration/Registration.js

@@ -62,14 +62,14 @@ class Registration {
             return;
         }
         if (!this.key) {
-            throw new DependencyMissingKeyError_1.DependencyMissingKeyError('No key provided for registration');
+            throw new DependencyMissingKeyError_1.DependencyMissingKeyError('No key provided for registration: bind it with @register(bindTo(...)) or .bindTo(...).');
         }
         const provider = this.mappers.reduce((p, m) => m(p), this.createProvider());
         container.register(this.key, provider, { aliases: [...this.aliases] });
     }
     getKeyOrFail() {
         if (!this.key) {
-            throw new DependencyMissingKeyError_1.DependencyMissingKeyError('No key provided for registration');
+            throw new DependencyMissingKeyError_1.DependencyMissingKeyError('No key provided for registration: bind it with @register(bindTo(...)) or .bindTo(...).');
         }
         return this.key;
     }

package/cjm/token/ConstantToken.js

@@ -13,19 +13,19 @@ class ConstantToken extends InjectionToken_1.InjectionToken {
         return this.token;
     }
     args(...deps) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('ConstantToken.args is not implemented');
     }
     argsFn(getArgsFn) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('ConstantToken.argsFn is not implemented');
     }
     lazy() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('ConstantToken.lazy is not implemented');
     }
     addTags(...tags) {
         return new ConstantToken(this.token, { tags: [...this.getTags(), ...tags] });
     }
     toString() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('ConstantToken.toString is not implemented');
     }
 }
 exports.ConstantToken = ConstantToken;

package/cjm/token/FunctionToken.js

@@ -51,7 +51,7 @@ class FunctionToken extends InjectionToken_1.InjectionToken {
         });
     }
     toString() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('FunctionToken.toString is not implemented');
     }
 }
 exports.FunctionToken = FunctionToken;

package/cjm/token/GroupInstanceToken.js

@@ -15,13 +15,13 @@ class GroupInstanceToken extends InjectionToken_1.InjectionToken {
         return (s) => this.resolve(s).map(fn);
     }
     args(...deps) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('GroupInstanceToken.args is not implemented');
     }
     argsFn(getArgsFn) {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('GroupInstanceToken.argsFn is not implemented');
     }
     lazy() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('GroupInstanceToken.lazy is not implemented');
     }
     cascade(isTrue) {
         this.isCascade = isTrue;
@@ -34,7 +34,7 @@ class GroupInstanceToken extends InjectionToken_1.InjectionToken {
         return new GroupInstanceToken(this.predicate, { tags: [...this.getTags(), ...tags], isCascade: this.isCascade });
     }
     toString() {
-        throw new MethodNotImplementedError_1.MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError_1.MethodNotImplementedError('GroupInstanceToken.toString is not implemented');
     }
 }
 exports.GroupInstanceToken = GroupInstanceToken;

package/cjm/token/toToken.js

@@ -22,7 +22,7 @@ const toToken = (token) => {
     if (typeof token === 'function') {
         return new FunctionToken_1.FunctionToken(token);
     }
-    throw new UnsupportedTokenTypeError_1.UnsupportedTokenTypeError(`Unknown token ${token}`);
+    throw new UnsupportedTokenTypeError_1.UnsupportedTokenTypeError(`Unknown token ${token}: expected an InjectionToken, a DependencyKey (string | symbol), a class or a function.`);
 };
 exports.toToken = toToken;
 const argToToken = (v) => ((0, InjectionToken_1.isInjectionToken)(v) ? v : new ConstantToken_1.ConstantToken(v));

package/cjm/utils/TypedEvent.js

@@ -29,7 +29,7 @@ class TypedEvent {
         this.isDisposed = true;
     }
     validate() {
-        TypedEventDisposedError_1.TypedEventDisposedError.assert(!this.isDisposed, 'TypedEvent is already disposed');
+        TypedEventDisposedError_1.TypedEventDisposedError.assert(!this.isDisposed, 'TypedEvent is already disposed: its scope was disposed, so it accepts no new listeners.');
     }
 }
 exports.TypedEvent = TypedEvent;

package/cjm/utils/array.js

@@ -11,7 +11,7 @@ exports.Filter = {
 const findOrFail = (predicate) => (args = []) => {
     const index = args.findIndex((arg) => predicate(arg));
     if (index === -1) {
-        throw new ArgumentNotFoundError_1.ArgumentNotFoundError();
+        throw new ArgumentNotFoundError_1.ArgumentNotFoundError(`No argument matches the predicate (received ${args.length} args).`);
     }
     return args[index];
 };

package/esm/container/Container.js

@@ -161,12 +161,12 @@ export class Container {
     }
     validateContainer() {
         if (this.isDisposed) {
-            throw new ContainerDisposedError('Container is already disposed');
+            throw new ContainerDisposedError('Container is already disposed: a scope cannot be used after dispose(). Create a new scope.');
         }
     }
     findProviderByKeyOrFail(key) {
         if (!this.providers.has(key)) {
-            throw new DependencyNotFoundError(`Provider ${key.toString()} does not exist`);
+            throw new DependencyNotFoundError(`Provider ${key.toString()} does not exist: an alias points at a key with no provider in this scope.`);
         }
         return this.providers.get(key);
     }