@loopback/context 4.0.0-alpha.7 → 4.0.1

package/dist/binding-inspector.d.ts

@@ -0,0 +1,150 @@
+import { MetadataAccessor } from '@loopback/metadata';
+import { Binding, BindingScope, BindingTag, BindingTemplate, DynamicValueProviderClass } from './binding';
+import { BindingAddress } from './binding-key';
+import { Provider } from './provider';
+import { Constructor } from './value-promise';
+/**
+ * Binding metadata from `@injectable`
+ *
+ * @typeParam T - Value type
+ */
+export declare type BindingMetadata<T = unknown> = {
+    /**
+     * An array of template functions to configure a binding
+     */
+    templates: BindingTemplate<T>[];
+    /**
+     * The target class where binding metadata is decorated
+     */
+    target: Constructor<T>;
+};
+/**
+ * Metadata key for binding metadata
+ */
+export declare const BINDING_METADATA_KEY: MetadataAccessor<BindingMetadata<unknown>, ClassDecorator>;
+/**
+ * An object to configure binding scope and tags
+ */
+export declare type BindingScopeAndTags = {
+    scope?: BindingScope;
+    tags?: BindingTag | BindingTag[];
+};
+/**
+ * Specification of parameters for `@injectable()`
+ */
+export declare type BindingSpec<T = unknown> = BindingTemplate<T> | BindingScopeAndTags;
+/**
+ * Check if a class implements `Provider` interface
+ * @param cls - A class
+ *
+ * @typeParam T - Value type
+ */
+export declare function isProviderClass<T>(cls: unknown): cls is Constructor<Provider<T>>;
+/**
+ * A factory function to create a template function to bind the target class
+ * as a `Provider`.
+ * @param target - Target provider class
+ *
+ * @typeParam T - Value type
+ */
+export declare function asProvider<T>(target: Constructor<Provider<T>>): BindingTemplate<T>;
+/**
+ * A factory function to create a template function to bind the target class
+ * as a class or `Provider`.
+ * @param target - Target class, which can be an implementation of `Provider`
+ * or `DynamicValueProviderClass`
+ *
+ * @typeParam T - Value type
+ */
+export declare function asClassOrProvider<T>(target: Constructor<T | Provider<T>> | DynamicValueProviderClass<T>): BindingTemplate<T>;
+/**
+ * Convert binding scope and tags as a template function
+ * @param scopeAndTags - Binding scope and tags
+ *
+ * @typeParam T - Value type
+ */
+export declare function asBindingTemplate<T = unknown>(scopeAndTags: BindingScopeAndTags): BindingTemplate<T>;
+/**
+ * Get binding metadata for a class
+ * @param target - The target class
+ *
+ * @typeParam T - Value type
+ */
+export declare function getBindingMetadata<T = unknown>(target: Function): BindingMetadata<T> | undefined;
+/**
+ * A binding template function to delete `name` and `key` tags
+ */
+export declare function removeNameAndKeyTags(binding: Binding<unknown>): void;
+/**
+ * Get the binding template for a class with binding metadata
+ *
+ * @param cls - A class with optional `@injectable`
+ *
+ * @typeParam T - Value type
+ */
+export declare function bindingTemplateFor<T>(cls: Constructor<T | Provider<T>> | DynamicValueProviderClass<T>, options?: BindingFromClassOptions): BindingTemplate<T>;
+/**
+ * Mapping artifact types to binding key namespaces (prefixes).
+ *
+ * @example
+ * ```ts
+ * {
+ *   repository: 'repositories'
+ * }
+ * ```
+ */
+export declare type TypeNamespaceMapping = {
+    [name: string]: string;
+};
+export declare const DEFAULT_TYPE_NAMESPACES: TypeNamespaceMapping;
+/**
+ * Options to customize the binding created from a class
+ */
+export declare type BindingFromClassOptions = {
+    /**
+     * Binding key
+     */
+    key?: BindingAddress;
+    /**
+     * Artifact type, such as `server`, `controller`, `repository` or `service`
+     */
+    type?: string;
+    /**
+     * Artifact name, such as `my-rest-server` and `my-controller`. It
+     * overrides the name tag
+     */
+    name?: string;
+    /**
+     * Namespace for the binding key, such as `servers` and `controllers`. It
+     * overrides the default namespace or namespace tag
+     */
+    namespace?: string;
+    /**
+     * Mapping artifact type to binding key namespaces
+     */
+    typeNamespaceMapping?: TypeNamespaceMapping;
+    /**
+     * Default namespace if the binding does not have an explicit namespace
+     */
+    defaultNamespace?: string;
+    /**
+     * Default scope if the binding does not have an explicit scope
+     */
+    defaultScope?: BindingScope;
+};
+/**
+ * Create a binding from a class with decorated metadata. The class is attached
+ * to the binding as follows:
+ * - `binding.toClass(cls)`: if `cls` is a plain class such as `MyController`
+ * - `binding.toProvider(cls)`: if `cls` is a value provider class with a
+ * prototype method `value()`
+ * - `binding.toDynamicValue(cls)`: if `cls` is a dynamic value provider class
+ * with a static method `value()`
+ *
+ * @param cls - A class. It can be either a plain class, a value provider class,
+ * or a dynamic value provider class
+ * @param options - Options to customize the binding key
+ *
+ * @typeParam T - Value type
+ */
+export declare function createBindingFromClass<T>(cls: Constructor<T | Provider<T>> | DynamicValueProviderClass<T>, options?: BindingFromClassOptions): Binding<T>;

package/dist/binding-inspector.js

@@ -0,0 +1,249 @@
+"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.createBindingFromClass = exports.DEFAULT_TYPE_NAMESPACES = exports.bindingTemplateFor = exports.removeNameAndKeyTags = exports.getBindingMetadata = exports.asBindingTemplate = exports.asClassOrProvider = exports.asProvider = exports.isProviderClass = exports.BINDING_METADATA_KEY = void 0;
+const tslib_1 = require("tslib");
+const metadata_1 = require("@loopback/metadata");
+const debug_1 = (0, tslib_1.__importDefault)(require("debug"));
+const binding_1 = require("./binding");
+const keys_1 = require("./keys");
+const debug = (0, debug_1.default)('loopback:context:binding-inspector');
+/**
+ * Metadata key for binding metadata
+ */
+exports.BINDING_METADATA_KEY = metadata_1.MetadataAccessor.create('binding.metadata');
+/**
+ * Check if a class implements `Provider` interface
+ * @param cls - A class
+ *
+ * @typeParam T - Value type
+ */
+function isProviderClass(cls) {
+    var _a;
+    return (typeof cls === 'function' && typeof ((_a = cls.prototype) === null || _a === void 0 ? void 0 : _a.value) === 'function');
+}
+exports.isProviderClass = isProviderClass;
+/**
+ * A factory function to create a template function to bind the target class
+ * as a `Provider`.
+ * @param target - Target provider class
+ *
+ * @typeParam T - Value type
+ */
+function asProvider(target) {
+    return function bindAsProvider(binding) {
+        binding.toProvider(target).tag(keys_1.ContextTags.PROVIDER, {
+            [keys_1.ContextTags.TYPE]: keys_1.ContextTags.PROVIDER,
+        });
+    };
+}
+exports.asProvider = asProvider;
+/**
+ * A factory function to create a template function to bind the target class
+ * as a class or `Provider`.
+ * @param target - Target class, which can be an implementation of `Provider`
+ * or `DynamicValueProviderClass`
+ *
+ * @typeParam T - Value type
+ */
+function asClassOrProvider(target) {
+    // Add a template to bind to a class or provider
+    return function bindAsClassOrProvider(binding) {
+        if (isProviderClass(target)) {
+            asProvider(target)(binding);
+        }
+        else if ((0, binding_1.isDynamicValueProviderClass)(target)) {
+            binding.toDynamicValue(target).tag(keys_1.ContextTags.DYNAMIC_VALUE_PROVIDER, {
+                [keys_1.ContextTags.TYPE]: keys_1.ContextTags.DYNAMIC_VALUE_PROVIDER,
+            });
+        }
+        else {
+            binding.toClass(target);
+        }
+    };
+}
+exports.asClassOrProvider = asClassOrProvider;
+/**
+ * Convert binding scope and tags as a template function
+ * @param scopeAndTags - Binding scope and tags
+ *
+ * @typeParam T - Value type
+ */
+function asBindingTemplate(scopeAndTags) {
+    return function applyBindingScopeAndTag(binding) {
+        if (scopeAndTags.scope) {
+            binding.inScope(scopeAndTags.scope);
+        }
+        if (scopeAndTags.tags) {
+            if (Array.isArray(scopeAndTags.tags)) {
+                binding.tag(...scopeAndTags.tags);
+            }
+            else {
+                binding.tag(scopeAndTags.tags);
+            }
+        }
+    };
+}
+exports.asBindingTemplate = asBindingTemplate;
+/**
+ * Get binding metadata for a class
+ * @param target - The target class
+ *
+ * @typeParam T - Value type
+ */
+function getBindingMetadata(target) {
+    return metadata_1.MetadataInspector.getClassMetadata(exports.BINDING_METADATA_KEY, target);
+}
+exports.getBindingMetadata = getBindingMetadata;
+/**
+ * A binding template function to delete `name` and `key` tags
+ */
+function removeNameAndKeyTags(binding) {
+    if (binding.tagMap) {
+        delete binding.tagMap.name;
+        delete binding.tagMap.key;
+    }
+}
+exports.removeNameAndKeyTags = removeNameAndKeyTags;
+/**
+ * Get the binding template for a class with binding metadata
+ *
+ * @param cls - A class with optional `@injectable`
+ *
+ * @typeParam T - Value type
+ */
+function bindingTemplateFor(cls, options) {
+    var _a;
+    const spec = getBindingMetadata(cls);
+    debug('class %s has binding metadata', cls.name, spec);
+    const templateFunctions = (_a = spec === null || spec === void 0 ? void 0 : spec.templates) !== null && _a !== void 0 ? _a : [];
+    if ((spec === null || spec === void 0 ? void 0 : spec.target) !== cls) {
+        // Make sure the subclass is used as the binding source
+        templateFunctions.push(asClassOrProvider(cls));
+    }
+    return function applyBindingTemplatesFromMetadata(binding) {
+        for (const t of templateFunctions) {
+            binding.apply(t);
+        }
+        if ((spec === null || spec === void 0 ? void 0 : spec.target) !== cls) {
+            // Remove name/key tags inherited from base classes
+            binding.apply(removeNameAndKeyTags);
+        }
+        if (options != null) {
+            applyClassBindingOptions(binding, options);
+        }
+    };
+}
+exports.bindingTemplateFor = bindingTemplateFor;
+exports.DEFAULT_TYPE_NAMESPACES = {
+    class: 'classes',
+    provider: 'providers',
+    dynamicValueProvider: 'dynamicValueProviders',
+};
+/**
+ * Create a binding from a class with decorated metadata. The class is attached
+ * to the binding as follows:
+ * - `binding.toClass(cls)`: if `cls` is a plain class such as `MyController`
+ * - `binding.toProvider(cls)`: if `cls` is a value provider class with a
+ * prototype method `value()`
+ * - `binding.toDynamicValue(cls)`: if `cls` is a dynamic value provider class
+ * with a static method `value()`
+ *
+ * @param cls - A class. It can be either a plain class, a value provider class,
+ * or a dynamic value provider class
+ * @param options - Options to customize the binding key
+ *
+ * @typeParam T - Value type
+ */
+function createBindingFromClass(cls, options = {}) {
+    debug('create binding from class %s with options', cls.name, options);
+    try {
+        const templateFn = bindingTemplateFor(cls, options);
+        const key = buildBindingKey(cls, options);
+        const binding = binding_1.Binding.bind(key).apply(templateFn);
+        return binding;
+    }
+    catch (err) {
+        err.message += ` (while building binding for class ${cls.name})`;
+        throw err;
+    }
+}
+exports.createBindingFromClass = createBindingFromClass;
+function applyClassBindingOptions(binding, options) {
+    if (options.name) {
+        binding.tag({ name: options.name });
+    }
+    if (options.type) {
+        binding.tag({ type: options.type }, options.type);
+    }
+    if (options.defaultScope) {
+        binding.applyDefaultScope(options.defaultScope);
+    }
+}
+/**
+ * Find/infer binding key namespace for a type
+ * @param type - Artifact type, such as `controller`, `datasource`, or `server`
+ * @param typeNamespaces - An object mapping type names to namespaces
+ */
+function getNamespace(type, typeNamespaces = exports.DEFAULT_TYPE_NAMESPACES) {
+    if (type in typeNamespaces) {
+        return typeNamespaces[type];
+    }
+    else {
+        // Return the plural form
+        return `${type}s`;
+    }
+}
+/**
+ * Build the binding key for a class with optional binding metadata.
+ * The binding key is resolved in the following steps:
+ *
+ * 1. Check `options.key`, if it exists, return it
+ * 2. Check if the binding metadata has `key` tag, if yes, return its tag value
+ * 3. Identify `namespace` and `name` to form the binding key as
+ * `<namespace>.<name>`.
+ *   - namespace
+ *     - `options.namespace`
+ *     - `namespace` tag value
+ *     - Map `options.type` or `type` tag value to a namespace, for example,
+ *       'controller` to 'controller'.
+ *   - name
+ *     - `options.name`
+ *     - `name` tag value
+ *     - the class name
+ *
+ * @param cls - A class to be bound
+ * @param options - Options to customize how to build the key
+ *
+ * @typeParam T - Value type
+ */
+function buildBindingKey(cls, options = {}) {
+    var _a, _b, _c, _d, _e;
+    if (options.key)
+        return options.key;
+    const templateFn = bindingTemplateFor(cls);
+    // Create a temporary binding
+    const bindingTemplate = new binding_1.Binding('template').apply(templateFn);
+    // Is there a `key` tag?
+    let key = bindingTemplate.tagMap[keys_1.ContextTags.KEY];
+    if (key)
+        return key;
+    let namespace = (_b = (_a = options.namespace) !== null && _a !== void 0 ? _a : bindingTemplate.tagMap[keys_1.ContextTags.NAMESPACE]) !== null && _b !== void 0 ? _b : options.defaultNamespace;
+    if (!namespace) {
+        const namespaces = Object.assign({}, exports.DEFAULT_TYPE_NAMESPACES, options.typeNamespaceMapping);
+        // Derive the key from type + name
+        let type = (_c = options.type) !== null && _c !== void 0 ? _c : bindingTemplate.tagMap[keys_1.ContextTags.TYPE];
+        if (!type) {
+            type =
+                (_d = bindingTemplate.tagNames.find(t => namespaces[t] != null)) !== null && _d !== void 0 ? _d : keys_1.ContextTags.CLASS;
+        }
+        namespace = getNamespace(type, namespaces);
+    }
+    const name = (_e = options.name) !== null && _e !== void 0 ? _e : (bindingTemplate.tagMap[keys_1.ContextTags.NAME] || cls.name);
+    key = `${namespace}.${name}`;
+    return key;
+}
+//# sourceMappingURL=binding-inspector.js.map

package/dist/binding-inspector.js.map

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

package/dist/binding-key.d.ts

@@ -0,0 +1,66 @@
+export declare type BindingAddress<T = unknown> = string | BindingKey<T>;
+export declare class BindingKey<ValueType> {
+    readonly key: string;
+    readonly propertyPath?: string | undefined;
+    static readonly PROPERTY_SEPARATOR = "#";
+    /**
+     * Create a new key for a binding bound to a value of type `ValueType`.
+     *
+     * @example
+     *
+     * ```ts
+     * BindingKey.create<string>('application.name');
+     * BindingKey.create<number>('config', 'rest.port);
+     * BindingKey.create<number>('config#rest.port');
+     * ```
+     *
+     * @param key - The binding key. When propertyPath is not provided, the key
+     *   is allowed to contain propertyPath as encoded via `BindingKey#toString()`
+     * @param propertyPath - Optional path to a deep property of the bound value.
+     */
+    static create<V>(key: string, propertyPath?: string): BindingKey<V>;
+    private constructor();
+    toString(): string;
+    /**
+     * Get a binding address for retrieving a deep property of the object
+     * bound to the current binding key.
+     *
+     * @param propertyPath - A dot-separated path to a (deep) property, e.g. "server.port".
+     */
+    deepProperty<PropertyValueType>(propertyPath: string): BindingKey<PropertyValueType>;
+    /**
+     * Validate the binding key format. Please note that `#` is reserved.
+     * Returns a string representation of the binding key.
+     *
+     * @param key - Binding key, such as `a`, `a.b`, `a:b`, or `a/b`
+     */
+    static validate<T>(key: BindingAddress<T>): string;
+    /**
+     * Parse a string containing both the binding key and the path to the deeply
+     * nested property to retrieve.
+     *
+     * @param keyWithPath - The key with an optional path,
+     *  e.g. "application.instance" or "config#rest.port".
+     */
+    static parseKeyWithPath<T>(keyWithPath: BindingAddress<T>): BindingKey<T>;
+    /**
+     * Name space for configuration binding keys
+     */
+    static CONFIG_NAMESPACE: string;
+    /**
+     * Build a binding key for the configuration of the given binding.
+     * The format is `<key>:$config`
+     *
+     * @param key - Key of the target binding to be configured
+     */
+    static buildKeyForConfig<T>(key?: BindingAddress): BindingAddress<T>;
+    /**
+     * Generate a universally unique binding key.
+     *
+     * Please note the format of they generated key is not specified, you must
+     * not rely on any specific formatting (e.g. UUID style).
+     *
+     * @param namespace - Namespace for the binding
+     */
+    static generate<T>(namespace?: string): BindingKey<T>;
+}

package/dist/binding-key.js

@@ -0,0 +1,121 @@
+"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.BindingKey = void 0;
+const unique_id_1 = require("./unique-id");
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+class BindingKey {
+    constructor(key, propertyPath) {
+        this.key = key;
+        this.propertyPath = propertyPath;
+    }
+    /**
+     * Create a new key for a binding bound to a value of type `ValueType`.
+     *
+     * @example
+     *
+     * ```ts
+     * BindingKey.create<string>('application.name');
+     * BindingKey.create<number>('config', 'rest.port);
+     * BindingKey.create<number>('config#rest.port');
+     * ```
+     *
+     * @param key - The binding key. When propertyPath is not provided, the key
+     *   is allowed to contain propertyPath as encoded via `BindingKey#toString()`
+     * @param propertyPath - Optional path to a deep property of the bound value.
+     */
+    static create(key, propertyPath) {
+        // TODO(bajtos) allow chaining of propertyPaths, e.g.
+        //   BindingKey.create('config#rest', 'port')
+        // should create {key: 'config', path: 'rest.port'}
+        if (propertyPath) {
+            BindingKey.validate(key);
+            return new BindingKey(key, propertyPath);
+        }
+        return BindingKey.parseKeyWithPath(key);
+    }
+    toString() {
+        return this.propertyPath
+            ? `${this.key}${BindingKey.PROPERTY_SEPARATOR}${this.propertyPath}`
+            : this.key;
+    }
+    /**
+     * Get a binding address for retrieving a deep property of the object
+     * bound to the current binding key.
+     *
+     * @param propertyPath - A dot-separated path to a (deep) property, e.g. "server.port".
+     */
+    deepProperty(propertyPath) {
+        // TODO(bajtos) allow chaining of propertyPaths, e.g.
+        //   BindingKey.create('config', 'rest').deepProperty('port')
+        // should create {key: 'config', path: 'rest.port'}
+        return BindingKey.create(this.key, propertyPath);
+    }
+    /**
+     * Validate the binding key format. Please note that `#` is reserved.
+     * Returns a string representation of the binding key.
+     *
+     * @param key - Binding key, such as `a`, `a.b`, `a:b`, or `a/b`
+     */
+    static validate(key) {
+        if (!key)
+            throw new Error('Binding key must be provided.');
+        key = key.toString();
+        if (key.includes(BindingKey.PROPERTY_SEPARATOR)) {
+            throw new Error(`Binding key ${key} cannot contain` +
+                ` '${BindingKey.PROPERTY_SEPARATOR}'.`);
+        }
+        return key;
+    }
+    /**
+     * Parse a string containing both the binding key and the path to the deeply
+     * nested property to retrieve.
+     *
+     * @param keyWithPath - The key with an optional path,
+     *  e.g. "application.instance" or "config#rest.port".
+     */
+    static parseKeyWithPath(keyWithPath) {
+        if (typeof keyWithPath !== 'string') {
+            return BindingKey.create(keyWithPath.key, keyWithPath.propertyPath);
+        }
+        const index = keyWithPath.indexOf(BindingKey.PROPERTY_SEPARATOR);
+        if (index === -1) {
+            return new BindingKey(keyWithPath);
+        }
+        return BindingKey.create(keyWithPath.substr(0, index).trim(), keyWithPath.substr(index + 1));
+    }
+    /**
+     * Build a binding key for the configuration of the given binding.
+     * The format is `<key>:$config`
+     *
+     * @param key - Key of the target binding to be configured
+     */
+    static buildKeyForConfig(key = '') {
+        const suffix = BindingKey.CONFIG_NAMESPACE;
+        const bindingKey = key ? `${key}:${suffix}` : suffix;
+        return bindingKey;
+    }
+    /**
+     * Generate a universally unique binding key.
+     *
+     * Please note the format of they generated key is not specified, you must
+     * not rely on any specific formatting (e.g. UUID style).
+     *
+     * @param namespace - Namespace for the binding
+     */
+    static generate(namespace = '') {
+        const prefix = namespace ? `${namespace}.` : '';
+        const name = (0, unique_id_1.generateUniqueId)();
+        return BindingKey.create(`${prefix}${name}`);
+    }
+}
+exports.BindingKey = BindingKey;
+BindingKey.PROPERTY_SEPARATOR = '#';
+/**
+ * Name space for configuration binding keys
+ */
+BindingKey.CONFIG_NAMESPACE = '$config';
+//# sourceMappingURL=binding-key.js.map

package/dist/binding-key.js.map

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

package/dist/binding-sorter.d.ts

@@ -0,0 +1,71 @@
+import { Binding } from './binding';
+/**
+ * Compare function to sort an array of bindings.
+ * It is used by `Array.prototype.sort()`.
+ *
+ * @example
+ * ```ts
+ * const compareByKey: BindingComparator = (a, b) => a.key.localeCompare(b.key);
+ * ```
+ */
+export interface BindingComparator {
+    /**
+     * Compare two bindings
+     * @param bindingA - First binding
+     * @param bindingB - Second binding
+     * @returns A number to determine order of bindingA and bindingB
+     * - 0 leaves bindingA and bindingB unchanged
+     * - <0 bindingA comes before bindingB
+     * - >0 bindingA comes after bindingB
+     */
+    (bindingA: Readonly<Binding<unknown>>, bindingB: Readonly<Binding<unknown>>): number;
+}
+/**
+ * Creates a binding compare function to sort bindings by tagged phase name.
+ *
+ * @remarks
+ * Two bindings are compared as follows:
+ *
+ * 1. Get values for the given tag as `phase` for bindings, if the tag is not
+ * present, default `phase` to `''`.
+ * 2. If both bindings have `phase` value in `orderOfPhases`, honor the order
+ * specified by `orderOfPhases`.
+ * 3. If a binding's `phase` does not exist in `orderOfPhases`, it comes before
+ * the one with `phase` exists in `orderOfPhases`.
+ * 4. If both bindings have `phase` value outside of `orderOfPhases`, they are
+ * ordered by phase names alphabetically and symbol values come before string
+ * values.
+ *
+ * @param phaseTagName - Name of the binding tag for phase
+ * @param orderOfPhases - An array of phase names as the predefined order
+ */
+export declare function compareBindingsByTag(phaseTagName?: string, orderOfPhases?: (string | symbol)[]): BindingComparator;
+/**
+ * Compare two values by the predefined order
+ *
+ * @remarks
+ *
+ * The comparison is performed as follows:
+ *
+ * 1. If both values are included in `order`, they are sorted by their indexes in
+ * `order`.
+ * 2. The value included in `order` comes after the value not included in `order`.
+ * 3. If neither values are included in `order`, they are sorted:
+ *   - symbol values come before string values
+ *   - alphabetical order for two symbols or two strings
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @param order - An array of values as the predefined order
+ */
+export declare function compareByOrder(a: string | symbol | undefined | null, b: string | symbol | undefined | null, order?: (string | symbol)[]): number;
+/**
+ * Sort bindings by phase names denoted by a tag and the predefined order
+ *
+ * @param bindings - An array of bindings
+ * @param phaseTagName - Tag name for phase, for example, we can use the value
+ * `'a'` of tag `order` as the phase name for `binding.tag({order: 'a'})`.
+ *
+ * @param orderOfPhases - An array of phase names as the predefined order
+ */
+export declare function sortBindingsByPhase<T = unknown>(bindings: Readonly<Binding<T>>[], phaseTagName?: string, orderOfPhases?: (string | symbol)[]): Readonly<Binding<T>>[];