@loopback/context 4.0.0-alpha.6 → 4.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2017,2019.
+Node module: @loopback/context
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+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.

package/README.md

@@ -1 +1,117 @@
 # @loopback/context
+
+This module provides facilities to manage artifacts and their dependencies using
+`Context` in your Node.js applications. It can be used independent of the
+LoopBack framework.
+
+## Overview
+
+The `@loopback/context` package exposes TypeScript/JavaScript APIs and
+decorators to register artifacts, declare dependencies, and resolve artifacts by
+keys. The `Context` also serves as an
+[IoC container](https://en.wikipedia.org/wiki/Inversion_of_control) to support
+[dependency injection](https://en.wikipedia.org/wiki/Dependency_injection).
+
+`Context` and `Binding` are the two core concepts. A context is a registry of
+bindings and each binding represents a resolvable artifact by the key.
+
+- Bindings can be fulfilled by a constant, a factory function, a class, or a
+  provider.
+- Bindings can be grouped by tags and searched by tags.
+- Binding scopes can be used to control how a resolved binding value is shared.
+- Bindings can be resolved synchronously or asynchronously.
+- Provide `@inject` and other variants of decorators to express dependencies.
+- Support Constructor, property, and method injections.
+- Allow contexts to form a hierarchy to share or override bindings.
+- Track bindings and injections during resolution to detect circular
+  dependencies.
+
+## Installation
+
+```sh
+npm install --save @loopback/context
+```
+
+## Basic use
+
+### Locate an artifact by key
+
+```js
+const Context = require('@loopback/context').Context;
+const ctx = new Context();
+ctx.bind('hello').to('world'); // BindingKey='hello', BindingValue='world'
+const helloVal = ctx.getSync('hello');
+console.log(helloVal); // => 'world'
+```
+
+The binding can also be located asynchronously:
+
+```ts
+const helloVal = await ctx.get('hello');
+console.log(helloVal); // => 'world'
+```
+
+### Dependency injection using context
+
+```ts
+import {Context, inject} from '@loopback/context';
+const ctx = new Context();
+
+// bind 'greeting' to 'Hello' as the constant value
+ctx.bind('greeting').to('Hello');
+
+class HelloController {
+  constructor(
+    // injecting the value bound to `greeting` using context
+    @inject('greeting') private greeting: string,
+  ) {}
+
+  greet(name) {
+    return `${this.greeting}, ${name}`;
+  }
+}
+
+// Bind 'HelloController' to class HelloController
+ctx.bind('HelloController').toClass(HelloController);
+
+async function hello() {
+  // Get an instance of HelloController
+  const helloController = await ctx.get<HelloController>('HelloController');
+  // helloController now has the `greeting` property injected with `Hello`
+  console.log(helloController.greet('John')); // => Hello, John
+}
+
+hello();
+```
+
+For additional information, please refer to the
+[Context page](http://loopback.io/doc/en/lb4/Context.html).
+
+## Examples
+
+To learn more about advanced features, check out standalone examples at
+[`@loopback/example-context`](https://github.com/loopbackio/loopback-next/tree/master/examples/context).
+
+Use the following command to download the example project to try out:
+
+```sh
+lb4 example context
+```
+
+## Contributions
+
+- [Guidelines](https://github.com/loopbackio/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/loopbackio/loopback-next/issues/110)
+
+## Tests
+
+Run `npm test` from the root folder.
+
+## Contributors
+
+See
+[all contributors](https://github.com/loopbackio/loopback-next/graphs/contributors).
+
+## License
+
+MIT

package/dist/binding-config.d.ts

@@ -0,0 +1,40 @@
+import { BindingAddress, BindingKey } from './binding-key';
+import { Context } from './context';
+import { ResolutionOptions } from './resolution-session';
+import { ValueOrPromise } from './value-promise';
+/**
+ * Resolver for configuration of bindings. It's responsible for finding
+ * corresponding configuration for a given binding key.
+ *
+ * By default, `undefined` is expected if no configuration is provided. The
+ * behavior can be overridden by setting `optional` to `false` in resolution
+ * options.
+ */
+export interface ConfigurationResolver {
+    /**
+     * Resolve config for the binding key
+     *
+     * @param key - Binding key
+     * @param propertyPath - Property path for the option. For example, `x.y`
+     * requests for `<config>.x.y`. If not set, the `config` object will be
+     * returned.
+     * @param resolutionOptions - Options for the resolution.
+     * - optional: if not set or set to `true`, `undefined` will be returned if
+     * no corresponding value is found. Otherwise, an error will be thrown.
+     */
+    getConfigAsValueOrPromise<ConfigValueType>(key: BindingAddress<unknown>, propertyPath?: string, resolutionOptions?: ResolutionOptions): ValueOrPromise<ConfigValueType | undefined>;
+}
+/**
+ * Resolver for configurations of bindings
+ */
+export declare class DefaultConfigurationResolver implements ConfigurationResolver {
+    readonly context: Context;
+    constructor(context: Context);
+    getConfigAsValueOrPromise<ConfigValueType>(key: BindingAddress<unknown>, propertyPath?: string, resolutionOptions?: ResolutionOptions): ValueOrPromise<ConfigValueType | undefined>;
+}
+/**
+ * Create binding key for configuration of the binding
+ * @param key - Binding key for the target binding
+ * @param propertyPath - Property path for the configuration
+ */
+export declare function configBindingKeyFor<ConfigValueType = unknown>(key: BindingAddress, propertyPath?: string): BindingKey<ConfigValueType>;

package/dist/binding-config.js

@@ -0,0 +1,33 @@
+"use strict";
+// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Node module: @loopback/context
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configBindingKeyFor = exports.DefaultConfigurationResolver = void 0;
+const binding_key_1 = require("./binding-key");
+/**
+ * Resolver for configurations of bindings
+ */
+class DefaultConfigurationResolver {
+    constructor(context) {
+        this.context = context;
+    }
+    getConfigAsValueOrPromise(key, propertyPath, resolutionOptions) {
+        propertyPath = propertyPath !== null && propertyPath !== void 0 ? propertyPath : '';
+        const configKey = configBindingKeyFor(key, propertyPath);
+        const options = Object.assign({ optional: true }, resolutionOptions);
+        return this.context.getValueOrPromise(configKey, options);
+    }
+}
+exports.DefaultConfigurationResolver = DefaultConfigurationResolver;
+/**
+ * Create binding key for configuration of the binding
+ * @param key - Binding key for the target binding
+ * @param propertyPath - Property path for the configuration
+ */
+function configBindingKeyFor(key, propertyPath) {
+    return binding_key_1.BindingKey.create(binding_key_1.BindingKey.buildKeyForConfig(key).toString(), propertyPath);
+}
+exports.configBindingKeyFor = configBindingKeyFor;
+//# sourceMappingURL=binding-config.js.map

package/dist/binding-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-config.js","sourceRoot":"","sources":["../src/binding-config.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,iCAAiC;AACjC,+CAA+C;AAC/C,gEAAgE;;;AAEhE,+CAAyD;AAgCzD;;GAEG;AACH,MAAa,4BAA4B;IACvC,YAA4B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;IAEhD,yBAAyB,CACvB,GAA4B,EAC5B,YAAqB,EACrB,iBAAqC;QAErC,YAAY,GAAG,YAAY,aAAZ,YAAY,cAAZ,YAAY,GAAI,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QAEzD,MAAM,OAAO,GAAsB,MAAM,CAAC,MAAM,CAC9C,EAAC,QAAQ,EAAE,IAAI,EAAC,EAChB,iBAAiB,CAClB,CAAC;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAkB,SAAS,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;CACF;AAjBD,oEAiBC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CACjC,GAAmB,EACnB,YAAqB;IAErB,OAAO,wBAAU,CAAC,MAAM,CACtB,wBAAU,CAAC,iBAAiB,CAAkB,GAAG,CAAC,CAAC,QAAQ,EAAE,EAC7D,YAAY,CACb,CAAC;AACJ,CAAC;AARD,kDAQC"}

package/dist/binding-decorator.d.ts

@@ -0,0 +1,45 @@
+import { BindingSpec } from './binding-inspector';
+import { Constructor } from './value-promise';
+/**
+ * Decorate a class with binding configuration
+ *
+ * @example
+ * ```ts
+ * @injectable((binding) => {binding.inScope(BindingScope.SINGLETON).tag('controller')}
+ * )
+ * @injectable({scope: BindingScope.SINGLETON})
+ * export class MyController {
+ * }
+ * ```
+ *
+ * @param specs - A list of binding scope/tags or template functions to
+ * configure the binding
+ */
+export declare function injectable(...specs: BindingSpec[]): ClassDecorator;
+/**
+ * A namespace to host shortcuts for `@injectable`
+ */
+export declare namespace injectable {
+    /**
+     * `@injectable.provider` to denote a provider class
+     *
+     * A list of binding scope/tags or template functions to configure the binding
+     */
+    function provider(...specs: BindingSpec[]): (target: Constructor<unknown>) => void;
+}
+/**
+ * `@bind` is now an alias to {@link injectable} for backward compatibility
+ * {@inheritDoc injectable}
+ */
+export declare function bind(...specs: BindingSpec[]): ClassDecorator;
+/**
+ * Alias namespace `bind` to `injectable` for backward compatibility
+ *
+ * It should have the same members as `bind`.
+ */
+export declare namespace bind {
+    /**
+     * {@inheritDoc injectable.provider}
+     */
+    const provider: typeof injectable.provider;
+}

package/dist/binding-decorator.js

@@ -0,0 +1,118 @@
+"use strict";
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Node module: @loopback/context
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bind = exports.injectable = void 0;
+const metadata_1 = require("@loopback/metadata");
+const binding_inspector_1 = require("./binding-inspector");
+/**
+ * Decorator factory for `@injectable`
+ */
+class InjectableDecoratorFactory extends metadata_1.ClassDecoratorFactory {
+    mergeWithInherited(inherited, target) {
+        if (inherited) {
+            return {
+                templates: [
+                    ...inherited.templates,
+                    binding_inspector_1.removeNameAndKeyTags,
+                    ...this.spec.templates,
+                ],
+                target: this.spec.target,
+            };
+        }
+        else {
+            this.withTarget(this.spec, target);
+            return this.spec;
+        }
+    }
+    mergeWithOwn(ownMetadata) {
+        return {
+            templates: [...ownMetadata.templates, ...this.spec.templates],
+            target: this.spec.target,
+        };
+    }
+    withTarget(spec, target) {
+        spec.target = target;
+        return spec;
+    }
+}
+/**
+ * Decorate a class with binding configuration
+ *
+ * @example
+ * ```ts
+ * @injectable((binding) => {binding.inScope(BindingScope.SINGLETON).tag('controller')}
+ * )
+ * @injectable({scope: BindingScope.SINGLETON})
+ * export class MyController {
+ * }
+ * ```
+ *
+ * @param specs - A list of binding scope/tags or template functions to
+ * configure the binding
+ */
+function injectable(...specs) {
+    const templateFunctions = specs.map(t => {
+        if (typeof t === 'function') {
+            return t;
+        }
+        else {
+            return (0, binding_inspector_1.asBindingTemplate)(t);
+        }
+    });
+    return (target) => {
+        const cls = target;
+        const spec = {
+            templates: [(0, binding_inspector_1.asClassOrProvider)(cls), ...templateFunctions],
+            target: cls,
+        };
+        const decorator = InjectableDecoratorFactory.createDecorator(binding_inspector_1.BINDING_METADATA_KEY, spec, { decoratorName: '@injectable' });
+        decorator(target);
+    };
+}
+exports.injectable = injectable;
+/**
+ * A namespace to host shortcuts for `@injectable`
+ */
+(function (injectable) {
+    /**
+     * `@injectable.provider` to denote a provider class
+     *
+     * A list of binding scope/tags or template functions to configure the binding
+     */
+    function provider(...specs) {
+        return (target) => {
+            if (!(0, binding_inspector_1.isProviderClass)(target)) {
+                throw new Error(`Target ${target} is not a Provider`);
+            }
+            injectable(
+            // Set up the default for providers
+            (0, binding_inspector_1.asProvider)(target), 
+            // Call other template functions
+            ...specs)(target);
+        };
+    }
+    injectable.provider = provider;
+})(injectable = exports.injectable || (exports.injectable = {}));
+/**
+ * `@bind` is now an alias to {@link injectable} for backward compatibility
+ * {@inheritDoc injectable}
+ */
+function bind(...specs) {
+    return injectable(...specs);
+}
+exports.bind = bind;
+/**
+ * Alias namespace `bind` to `injectable` for backward compatibility
+ *
+ * It should have the same members as `bind`.
+ */
+(function (bind) {
+    /**
+     * {@inheritDoc injectable.provider}
+     */
+    bind.provider = injectable.provider;
+})(bind = exports.bind || (exports.bind = {}));
+//# sourceMappingURL=binding-decorator.js.map

package/dist/binding-decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-decorator.js","sourceRoot":"","sources":["../src/binding-decorator.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,iCAAiC;AACjC,+CAA+C;AAC/C,gEAAgE;;;AAEhE,iDAAyD;AACzD,2DAS6B;AAG7B;;GAEG;AACH,MAAM,0BAA2B,SAAQ,gCAAsC;IAC7E,kBAAkB,CAAC,SAA0B,EAAE,MAAgB;QAC7D,IAAI,SAAS,EAAE;YACb,OAAO;gBACL,SAAS,EAAE;oBACT,GAAG,SAAS,CAAC,SAAS;oBACtB,wCAAoB;oBACpB,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS;iBACvB;gBACD,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;aACzB,CAAC;SACH;aAAM;YACL,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,IAAI,CAAC;SAClB;IACH,CAAC;IAED,YAAY,CAAC,WAA4B;QACvC,OAAO;YACL,SAAS,EAAE,CAAC,GAAG,WAAW,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;YAC7D,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;SACzB,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,IAAqB,EAAE,MAAgB;QAChD,IAAI,CAAC,MAAM,GAAG,MAA8B,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,UAAU,CAAC,GAAG,KAAoB;IAChD,MAAM,iBAAiB,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QACtC,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE;YAC3B,OAAO,CAAC,CAAC;SACV;aAAM;YACL,OAAO,IAAA,qCAAiB,EAAC,CAAC,CAAC,CAAC;SAC7B;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,MAA8B,CAAC;QAC3C,MAAM,IAAI,GAAoB;YAC5B,SAAS,EAAE,CAAC,IAAA,qCAAiB,EAAC,GAAG,CAAC,EAAE,GAAG,iBAAiB,CAAC;YACzD,MAAM,EAAE,GAAG;SACZ,CAAC;QAEF,MAAM,SAAS,GAAG,0BAA0B,CAAC,eAAe,CAC1D,wCAAoB,EACpB,IAAI,EACJ,EAAC,aAAa,EAAE,aAAa,EAAC,CAC/B,CAAC;QACF,SAAS,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAvBD,gCAuBC;AAED;;GAEG;AACH,WAAiB,UAAU;IACzB;;;;OAIG;IACH,SAAgB,QAAQ,CACtB,GAAG,KAAoB;QAEvB,OAAO,CAAC,MAA4B,EAAE,EAAE;YACtC,IAAI,CAAC,IAAA,mCAAe,EAAC,MAAM,CAAC,EAAE;gBAC5B,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,oBAAoB,CAAC,CAAC;aACvD;YACD,UAAU;YACR,mCAAmC;YACnC,IAAA,8BAAU,EAAC,MAAM,CAAC;YAClB,gCAAgC;YAChC,GAAG,KAAK,CACT,CAAC,MAAM,CAAC,CAAC;QACZ,CAAC,CAAC;IACJ,CAAC;IAde,mBAAQ,WAcvB,CAAA;AACH,CAAC,EArBgB,UAAU,GAAV,kBAAU,KAAV,kBAAU,QAqB1B;AAED;;;GAGG;AACH,SAAgB,IAAI,CAAC,GAAG,KAAoB;IAC1C,OAAO,UAAU,CAAC,GAAG,KAAK,CAAC,CAAC;AAC9B,CAAC;AAFD,oBAEC;AAED;;;;GAIG;AACH,WAAiB,IAAI;IACnB;;OAEG;IACU,aAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;AAC9C,CAAC,EALgB,IAAI,GAAJ,YAAI,KAAJ,YAAI,QAKpB"}

package/dist/binding-filter.d.ts

@@ -0,0 +1,108 @@
+import { Binding, BindingTag } from './binding';
+import { BindingAddress } from './binding-key';
+import { MapObject } from './value-promise';
+/**
+ * A function that filters bindings. It returns `true` to select a given
+ * binding.
+ *
+ * @remarks
+ * Originally, we allowed filters to be tied with a single value type.
+ * This actually does not make much sense - the filter function is typically
+ * invoked on all bindings to find those ones matching the given criteria.
+ * Filters must be prepared to handle bindings of any value type. We learned
+ * about this problem after enabling TypeScript's `strictFunctionTypes` check.
+ * This aspect is resolved by typing the input argument as `Binding<unknown>`.
+ *
+ * Ideally, `BindingFilter` should be declared as a type guard as follows:
+ * ```ts
+ * export type BindingFilterGuard<ValueType = unknown> = (
+ *   binding: Readonly<Binding<unknown>>,
+ * ) => binding is Readonly<Binding<ValueType>>;
+ * ```
+ *
+ * But TypeScript treats the following types as incompatible and does not accept
+ * type 1 for type 2.
+ *
+ * 1. `(binding: Readonly<Binding<unknown>>) => boolean`
+ * 2. `(binding: Readonly<Binding<unknown>>) => binding is Readonly<Binding<ValueType>>`
+ *
+ * If we described BindingFilter as a type-guard, then all filter implementations
+ * would have to be explicitly typed as type-guards too, which would make it
+ * tedious to write quick filter functions like `b => b.key.startsWith('services')`.
+ *
+ * To keep things simple and easy to use, we use `boolean` as the return type
+ * of a binding filter function.
+ */
+export interface BindingFilter {
+    (binding: Readonly<Binding<unknown>>): boolean;
+}
+/**
+ * Select binding(s) by key or a filter function
+ */
+export declare type BindingSelector<ValueType = unknown> = BindingAddress<ValueType> | BindingFilter;
+/**
+ * Type guard for binding address
+ * @param bindingSelector - Binding key or filter function
+ */
+export declare function isBindingAddress(bindingSelector: BindingSelector): bindingSelector is BindingAddress;
+/**
+ * Binding filter function that holds a binding tag pattern. `Context.find()`
+ * uses the `bindingTagPattern` to optimize the matching of bindings by tag to
+ * avoid expensive check for all bindings.
+ */
+export interface BindingTagFilter extends BindingFilter {
+    /**
+     * A special property on the filter function to provide access to the binding
+     * tag pattern which can be utilized to optimize the matching of bindings by
+     * tag in a context.
+     */
+    bindingTagPattern: BindingTag | RegExp;
+}
+/**
+ * Type guard for BindingTagFilter
+ * @param filter - A BindingFilter function
+ */
+export declare function isBindingTagFilter(filter?: BindingFilter): filter is BindingTagFilter;
+/**
+ * A function to check if a given tag value is matched for `filterByTag`
+ */
+export interface TagValueMatcher {
+    /**
+     * Check if the given tag value matches the search criteria
+     * @param tagValue - Tag value from the binding
+     * @param tagName - Tag name
+     * @param tagMap - Tag map from the binding
+     */
+    (tagValue: unknown, tagName: string, tagMap: MapObject<unknown>): boolean;
+}
+/**
+ * A symbol that can be used to match binding tags by name regardless of the
+ * value.
+ *
+ * @example
+ *
+ * The following code matches bindings with tag `{controller: 'A'}` or
+ * `{controller: 'controller'}`. But if the tag name 'controller' does not
+ * exist for a binding, the binding will NOT be included.
+ *
+ * ```ts
+ * ctx.findByTag({controller: ANY_TAG_VALUE})
+ * ```
+ */
+export declare const ANY_TAG_VALUE: TagValueMatcher;
+/**
+ * Create a tag value matcher function that returns `true` if the target tag
+ * value equals to the item value or is an array that includes the item value.
+ * @param itemValues - A list of tag item value
+ */
+export declare function includesTagValue(...itemValues: unknown[]): TagValueMatcher;
+/**
+ * Create a binding filter for the tag pattern
+ * @param tagPattern - Binding tag name, regexp, or object
+ */
+export declare function filterByTag(tagPattern: BindingTag | RegExp): BindingTagFilter;
+/**
+ * Create a binding filter from key pattern
+ * @param keyPattern - Binding key/wildcard, regexp, or a filter function
+ */
+export declare function filterByKey(keyPattern?: string | RegExp | BindingFilter): BindingFilter;

package/dist/binding-filter.js

@@ -0,0 +1,162 @@
+"use strict";
+// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Node module: @loopback/context
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterByKey = exports.filterByTag = exports.includesTagValue = exports.ANY_TAG_VALUE = exports.isBindingTagFilter = exports.isBindingAddress = void 0;
+/**
+ * Check if an object is a `BindingKey` by duck typing
+ * @param selector Binding selector
+ */
+function isBindingKey(selector) {
+    if (selector == null || typeof selector !== 'object')
+        return false;
+    return (typeof selector.key === 'string' &&
+        typeof selector.deepProperty === 'function');
+}
+/**
+ * Type guard for binding address
+ * @param bindingSelector - Binding key or filter function
+ */
+function isBindingAddress(bindingSelector) {
+    return (typeof bindingSelector !== 'function' &&
+        (typeof bindingSelector === 'string' ||
+            // See https://github.com/loopbackio/loopback-next/issues/4570
+            // `bindingSelector instanceof BindingKey` is not always reliable as the
+            // `@loopback/context` module might be loaded from multiple locations if
+            // `npm install` does not dedupe or there are mixed versions in the tree
+            isBindingKey(bindingSelector)));
+}
+exports.isBindingAddress = isBindingAddress;
+/**
+ * Type guard for BindingTagFilter
+ * @param filter - A BindingFilter function
+ */
+function isBindingTagFilter(filter) {
+    if (filter == null || !('bindingTagPattern' in filter))
+        return false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tagPattern = filter.bindingTagPattern;
+    return (tagPattern instanceof RegExp ||
+        typeof tagPattern === 'string' ||
+        typeof tagPattern === 'object');
+}
+exports.isBindingTagFilter = isBindingTagFilter;
+/**
+ * A symbol that can be used to match binding tags by name regardless of the
+ * value.
+ *
+ * @example
+ *
+ * The following code matches bindings with tag `{controller: 'A'}` or
+ * `{controller: 'controller'}`. But if the tag name 'controller' does not
+ * exist for a binding, the binding will NOT be included.
+ *
+ * ```ts
+ * ctx.findByTag({controller: ANY_TAG_VALUE})
+ * ```
+ */
+const ANY_TAG_VALUE = (tagValue, tagName, tagMap) => tagName in tagMap;
+exports.ANY_TAG_VALUE = ANY_TAG_VALUE;
+/**
+ * Create a tag value matcher function that returns `true` if the target tag
+ * value equals to the item value or is an array that includes the item value.
+ * @param itemValues - A list of tag item value
+ */
+function includesTagValue(...itemValues) {
+    return tagValue => {
+        return itemValues.some(itemValue => 
+        // The tag value equals the item value
+        tagValue === itemValue ||
+            // The tag value contains the item value
+            (Array.isArray(tagValue) && tagValue.includes(itemValue)));
+    };
+}
+exports.includesTagValue = includesTagValue;
+/**
+ * Create a binding filter for the tag pattern
+ * @param tagPattern - Binding tag name, regexp, or object
+ */
+function filterByTag(tagPattern) {
+    let filter;
+    let regex = undefined;
+    if (tagPattern instanceof RegExp) {
+        // RegExp for tag names
+        regex = tagPattern;
+    }
+    if (typeof tagPattern === 'string' &&
+        (tagPattern.includes('*') || tagPattern.includes('?'))) {
+        // Wildcard tag name
+        regex = wildcardToRegExp(tagPattern);
+    }
+    if (regex != null) {
+        // RegExp or wildcard match
+        filter = b => b.tagNames.some(t => regex.test(t));
+    }
+    else if (typeof tagPattern === 'string') {
+        // Plain tag string match
+        filter = b => b.tagNames.includes(tagPattern);
+    }
+    else {
+        // Match tag name/value pairs
+        const tagMap = tagPattern;
+        filter = b => {
+            for (const t in tagMap) {
+                if (!matchTagValue(tagMap[t], t, b.tagMap))
+                    return false;
+            }
+            // All tag name/value pairs match
+            return true;
+        };
+    }
+    // Set up binding tag for the filter
+    const tagFilter = filter;
+    tagFilter.bindingTagPattern = regex !== null && regex !== void 0 ? regex : tagPattern;
+    return tagFilter;
+}
+exports.filterByTag = filterByTag;
+function matchTagValue(tagValueOrMatcher, tagName, tagMap) {
+    const tagValue = tagMap[tagName];
+    if (tagValue === tagValueOrMatcher)
+        return true;
+    if (typeof tagValueOrMatcher === 'function') {
+        return tagValueOrMatcher(tagValue, tagName, tagMap);
+    }
+    return false;
+}
+/**
+ * Create a binding filter from key pattern
+ * @param keyPattern - Binding key/wildcard, regexp, or a filter function
+ */
+function filterByKey(keyPattern) {
+    if (typeof keyPattern === 'string') {
+        const regex = wildcardToRegExp(keyPattern);
+        return binding => regex.test(binding.key);
+    }
+    else if (keyPattern instanceof RegExp) {
+        return binding => keyPattern.test(binding.key);
+    }
+    else if (typeof keyPattern === 'function') {
+        return keyPattern;
+    }
+    return () => true;
+}
+exports.filterByKey = filterByKey;
+/**
+ * Convert a wildcard pattern to RegExp
+ * @param pattern - A wildcard string with `*` and `?` as special characters.
+ * - `*` matches zero or more characters except `.` and `:`
+ * - `?` matches exactly one character except `.` and `:`
+ */
+function wildcardToRegExp(pattern) {
+    // Escape reserved chars for RegExp:
+    // `- \ ^ $ + . ( ) | { } [ ] :`
+    let regexp = pattern.replace(/[\-\[\]\/\{\}\(\)\+\.\\\^\$\|\:]/g, '\\$&');
+    // Replace wildcard chars `*` and `?`
+    // `*` matches zero or more characters except `.` and `:`
+    // `?` matches one character except `.` and `:`
+    regexp = regexp.replace(/\*/g, '[^.:]*').replace(/\?/g, '[^.:]');
+    return new RegExp(`^${regexp}$`);
+}
+//# sourceMappingURL=binding-filter.js.map

package/dist/binding-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-filter.js","sourceRoot":"","sources":["../src/binding-filter.ts"],"names":[],"mappings":"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"}