@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/di/syntax/binding_when_on_syntax.js

@@ -0,0 +1,64 @@
+import { BindingOnSyntax } from "./binding_on_syntax.js";
+import { BindingWhenSyntax } from "./binding_when_syntax.js";
+class BindingWhenOnSyntax {
+    _bindingWhenSyntax;
+    _bindingOnSyntax;
+    _binding;
+    constructor(binding) {
+        this._binding = binding;
+        this._bindingWhenSyntax = new BindingWhenSyntax(this._binding);
+        this._bindingOnSyntax = new BindingOnSyntax(this._binding);
+    }
+    when(constraint) {
+        return this._bindingWhenSyntax.when(constraint);
+    }
+    whenTargetNamed(name) {
+        return this._bindingWhenSyntax.whenTargetNamed(name);
+    }
+    whenTargetIsDefault() {
+        return this._bindingWhenSyntax.whenTargetIsDefault();
+    }
+    whenTargetTagged(tag, value) {
+        return this._bindingWhenSyntax.whenTargetTagged(tag, value);
+    }
+    whenInjectedInto(parent) {
+        return this._bindingWhenSyntax.whenInjectedInto(parent);
+    }
+    whenParentNamed(name) {
+        return this._bindingWhenSyntax.whenParentNamed(name);
+    }
+    whenParentTagged(tag, value) {
+        return this._bindingWhenSyntax.whenParentTagged(tag, value);
+    }
+    whenAnyAncestorIs(ancestor) {
+        return this._bindingWhenSyntax.whenAnyAncestorIs(ancestor);
+    }
+    whenNoAncestorIs(ancestor) {
+        return this._bindingWhenSyntax.whenNoAncestorIs(ancestor);
+    }
+    whenAnyAncestorNamed(name) {
+        return this._bindingWhenSyntax.whenAnyAncestorNamed(name);
+    }
+    whenAnyAncestorTagged(tag, value) {
+        return this._bindingWhenSyntax.whenAnyAncestorTagged(tag, value);
+    }
+    whenNoAncestorNamed(name) {
+        return this._bindingWhenSyntax.whenNoAncestorNamed(name);
+    }
+    whenNoAncestorTagged(tag, value) {
+        return this._bindingWhenSyntax.whenNoAncestorTagged(tag, value);
+    }
+    whenAnyAncestorMatches(constraint) {
+        return this._bindingWhenSyntax.whenAnyAncestorMatches(constraint);
+    }
+    whenNoAncestorMatches(constraint) {
+        return this._bindingWhenSyntax.whenNoAncestorMatches(constraint);
+    }
+    onActivation(handler) {
+        return this._bindingOnSyntax.onActivation(handler);
+    }
+    onDeactivation(handler) {
+        return this._bindingOnSyntax.onDeactivation(handler);
+    }
+}
+export { BindingWhenOnSyntax };

package/lib/esm/di/syntax/binding_when_syntax.js

@@ -0,0 +1,82 @@
+import { BindingOnSyntax } from "./binding_on_syntax.js";
+import { namedConstraint, taggedConstraint, traverseAncerstors, typeConstraint, } from "./constraint_helpers.js";
+class BindingWhenSyntax {
+    _binding;
+    constructor(binding) {
+        this._binding = binding;
+    }
+    when(constraint) {
+        this._binding.constraint = constraint;
+        return new BindingOnSyntax(this._binding);
+    }
+    whenTargetNamed(name) {
+        this._binding.constraint = namedConstraint(name);
+        return new BindingOnSyntax(this._binding);
+    }
+    whenTargetIsDefault() {
+        this._binding.constraint = (request) => {
+            if (request === null) {
+                return false;
+            }
+            const targetIsDefault = request.target !== null &&
+                !request.target.isNamed() &&
+                !request.target.isTagged();
+            return targetIsDefault;
+        };
+        return new BindingOnSyntax(this._binding);
+    }
+    whenTargetTagged(tag, value) {
+        this._binding.constraint = taggedConstraint(tag)(value);
+        return new BindingOnSyntax(this._binding);
+    }
+    whenInjectedInto(parent) {
+        this._binding.constraint = (request) => request !== null && typeConstraint(parent)(request.parentRequest);
+        return new BindingOnSyntax(this._binding);
+    }
+    whenParentNamed(name) {
+        this._binding.constraint = (request) => request !== null && namedConstraint(name)(request.parentRequest);
+        return new BindingOnSyntax(this._binding);
+    }
+    whenParentTagged(tag, value) {
+        this._binding.constraint = (request) => request !== null && taggedConstraint(tag)(value)(request.parentRequest);
+        return new BindingOnSyntax(this._binding);
+    }
+    whenAnyAncestorIs(ancestor) {
+        this._binding.constraint = (request) => request !== null && traverseAncerstors(request, typeConstraint(ancestor));
+        return new BindingOnSyntax(this._binding);
+    }
+    whenNoAncestorIs(ancestor) {
+        this._binding.constraint = (request) => request !== null &&
+            !traverseAncerstors(request, typeConstraint(ancestor));
+        return new BindingOnSyntax(this._binding);
+    }
+    whenAnyAncestorNamed(name) {
+        this._binding.constraint = (request) => request !== null && traverseAncerstors(request, namedConstraint(name));
+        return new BindingOnSyntax(this._binding);
+    }
+    whenNoAncestorNamed(name) {
+        this._binding.constraint = (request) => request !== null && !traverseAncerstors(request, namedConstraint(name));
+        return new BindingOnSyntax(this._binding);
+    }
+    whenAnyAncestorTagged(tag, value) {
+        this._binding.constraint = (request) => request !== null &&
+            traverseAncerstors(request, taggedConstraint(tag)(value));
+        return new BindingOnSyntax(this._binding);
+    }
+    whenNoAncestorTagged(tag, value) {
+        this._binding.constraint = (request) => request !== null &&
+            !traverseAncerstors(request, taggedConstraint(tag)(value));
+        return new BindingOnSyntax(this._binding);
+    }
+    whenAnyAncestorMatches(constraint) {
+        this._binding.constraint = (request) => request !== null &&
+            traverseAncerstors(request, constraint);
+        return new BindingOnSyntax(this._binding);
+    }
+    whenNoAncestorMatches(constraint) {
+        this._binding.constraint = (request) => request !== null &&
+            !traverseAncerstors(request, constraint);
+        return new BindingOnSyntax(this._binding);
+    }
+}
+export { BindingWhenSyntax };

package/lib/esm/di/syntax/constraint_helpers.js

@@ -0,0 +1,39 @@
+import * as METADATA_KEY from "../constants/metadata_keys.js";
+import { Metadata } from "../planning/metadata.js";
+const traverseAncerstors = (request, constraint) => {
+    const parent = request.parentRequest;
+    if (parent !== null) {
+        return constraint(parent) ? true : traverseAncerstors(parent, constraint);
+    }
+    else {
+        return false;
+    }
+};
+// This helpers use currying to help you to generate constraints
+const taggedConstraint = (key) => (value) => {
+    const constraint = (request) => request !== null &&
+        request.target !== null &&
+        request.target.matchesTag(key)(value);
+    constraint.metaData = new Metadata(key, value);
+    return constraint;
+};
+const namedConstraint = taggedConstraint(METADATA_KEY.NAMED_TAG);
+const typeConstraint = (type) => (request) => {
+    // Using index 0 because constraints are applied
+    // to one binding at a time (see Planner class)
+    let binding = null;
+    if (request !== null) {
+        binding = request.bindings[0];
+        if (typeof type === "string") {
+            const serviceIdentifier = binding.serviceIdentifier;
+            return serviceIdentifier === type;
+        }
+        else {
+            const constructor = request.bindings[0]
+                .implementationType;
+            return type === constructor;
+        }
+    }
+    return false;
+};
+export { traverseAncerstors, taggedConstraint, namedConstraint, typeConstraint, };

package/lib/esm/di/utils/async.js

@@ -0,0 +1,12 @@
+function isPromise(object) {
+    const isObjectOrFunction = (typeof object === "object" && object !== null) ||
+        typeof object === "function";
+    return (isObjectOrFunction && typeof object.then === "function");
+}
+function isPromiseOrContainsPromise(object) {
+    if (isPromise(object)) {
+        return true;
+    }
+    return Array.isArray(object) && object.some(isPromise);
+}
+export { isPromise, isPromiseOrContainsPromise };

package/lib/esm/di/utils/binding_utils.js

@@ -0,0 +1,48 @@
+import { getServiceIdentifierAsString } from "../utils/serialization.js";
+import * as ERROR_MSGS from "../constants/error_msgs.js";
+import { BindingTypeEnum } from "../constants/literal_types.js";
+import { FactoryType } from "./factory_type.js";
+export const multiBindToService = (container) => (service) => (...types) => types.forEach((t) => container.bind(t).toService(service));
+export const ensureFullyBound = (binding) => {
+    let boundValue = null;
+    switch (binding.type) {
+        case BindingTypeEnum.ConstantValue:
+        case BindingTypeEnum.Function:
+            boundValue = binding.cache;
+            break;
+        case BindingTypeEnum.Constructor:
+        case BindingTypeEnum.Instance:
+            boundValue = binding.implementationType;
+            break;
+        case BindingTypeEnum.DynamicValue:
+            boundValue = binding.dynamicValue;
+            break;
+        case BindingTypeEnum.Provider:
+            boundValue = binding.provider;
+            break;
+        case BindingTypeEnum.Factory:
+            boundValue = binding.factory;
+            break;
+    }
+    if (boundValue === null) {
+        // The user probably created a binding but didn't finish it
+        // e.g. container.bind<T>('Something'); missing BindingToSyntax
+        const serviceIdentifierAsString = getServiceIdentifierAsString(binding.serviceIdentifier);
+        throw new Error(`${ERROR_MSGS.INVALID_BINDING_TYPE} ${serviceIdentifierAsString}`);
+    }
+};
+export const getFactoryDetails = (binding) => {
+    switch (binding.type) {
+        case BindingTypeEnum.Factory:
+            return { factory: binding.factory, factoryType: FactoryType.Factory };
+        case BindingTypeEnum.Provider:
+            return { factory: binding.provider, factoryType: FactoryType.Provider };
+        case BindingTypeEnum.DynamicValue:
+            return {
+                factory: binding.dynamicValue,
+                factoryType: FactoryType.DynamicValue,
+            };
+        default:
+            throw new Error(`Unexpected factory type ${binding.type}`);
+    }
+};

package/lib/esm/di/utils/clonable.js

@@ -0,0 +1,7 @@
+function isClonable(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        "clone" in obj &&
+        typeof obj.clone === "function");
+}
+export { isClonable };

package/lib/esm/di/utils/exceptions.js

@@ -0,0 +1,18 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import * as ERROR_MSGS from "../constants/error_msgs.js";
+export function isStackOverflowExeption(error) {
+    return (error instanceof RangeError ||
+        error.message === ERROR_MSGS.STACK_OVERFLOW);
+}
+export const tryAndThrowErrorIfStackOverflow = (fn, errorCallback) => {
+    try {
+        return fn();
+    }
+    catch (error) {
+        if (isStackOverflowExeption(error)) {
+            // eslint-disable-next-line no-ex-assign
+            error = errorCallback();
+        }
+        throw error;
+    }
+};

package/lib/esm/di/utils/factory_type.js

@@ -0,0 +1,6 @@
+export var FactoryType;
+(function (FactoryType) {
+    FactoryType["DynamicValue"] = "toDynamicValue";
+    FactoryType["Factory"] = "toFactory";
+    FactoryType["Provider"] = "toProvider";
+})(FactoryType || (FactoryType = {}));

package/lib/esm/di/utils/id.js

@@ -0,0 +1,5 @@
+let idCounter = 0;
+function id() {
+    return idCounter++;
+}
+export { id };

package/lib/esm/di/utils/js.js

@@ -0,0 +1,12 @@
+export function getFirstArrayDuplicate(array) {
+    const seenValues = new Set();
+    for (const entry of array) {
+        if (seenValues.has(entry)) {
+            return entry;
+        }
+        else {
+            seenValues.add(entry);
+        }
+    }
+    return undefined;
+}

package/lib/esm/di/utils/serialization.js

@@ -0,0 +1,102 @@
+import * as ERROR_MSGS from "../constants/error_msgs.js";
+function getServiceIdentifierAsString(serviceIdentifier) {
+    if (typeof serviceIdentifier === "function") {
+        const _serviceIdentifier = serviceIdentifier;
+        return _serviceIdentifier.name;
+    }
+    else if (typeof serviceIdentifier === "symbol") {
+        return serviceIdentifier.toString();
+    }
+    else {
+        // string
+        const _serviceIdentifier = serviceIdentifier;
+        return _serviceIdentifier;
+    }
+}
+function listRegisteredBindingsForServiceIdentifier(container, serviceIdentifier, getBindings) {
+    let registeredBindingsList = "";
+    const registeredBindings = getBindings(container, serviceIdentifier);
+    if (registeredBindings.length !== 0) {
+        registeredBindingsList = "\nRegistered bindings:";
+        registeredBindings.forEach((binding) => {
+            // Use 'Object as name of constant value injections'
+            let name = "Object";
+            // Use function name if available
+            if (binding.implementationType !== null) {
+                name = getFunctionName(binding.implementationType);
+            }
+            registeredBindingsList = `${registeredBindingsList}\n ${name}`;
+            if (binding.constraint.metaData) {
+                registeredBindingsList = `${registeredBindingsList} - ${binding.constraint.metaData}`;
+            }
+        });
+    }
+    return registeredBindingsList;
+}
+function alreadyDependencyChain(request, serviceIdentifier) {
+    if (request.parentRequest === null) {
+        return false;
+    }
+    else if (request.parentRequest.serviceIdentifier === serviceIdentifier) {
+        return true;
+    }
+    else {
+        return alreadyDependencyChain(request.parentRequest, serviceIdentifier);
+    }
+}
+function dependencyChainToString(request) {
+    function _createStringArr(req, result = []) {
+        const serviceIdentifier = getServiceIdentifierAsString(req.serviceIdentifier);
+        result.push(serviceIdentifier);
+        if (req.parentRequest !== null) {
+            return _createStringArr(req.parentRequest, result);
+        }
+        return result;
+    }
+    const stringArr = _createStringArr(request);
+    return stringArr.reverse().join(" --> ");
+}
+function circularDependencyToException(request) {
+    request.childRequests.forEach((childRequest) => {
+        if (alreadyDependencyChain(childRequest, childRequest.serviceIdentifier)) {
+            const services = dependencyChainToString(childRequest);
+            throw new Error(`${ERROR_MSGS.CIRCULAR_DEPENDENCY} ${services}`);
+        }
+        else {
+            circularDependencyToException(childRequest);
+        }
+    });
+}
+function listMetadataForTarget(serviceIdentifierString, target) {
+    if (target.isTagged() || target.isNamed()) {
+        let m = "";
+        const namedTag = target.getNamedTag();
+        const otherTags = target.getCustomTags();
+        if (namedTag !== null) {
+            m += namedTag.toString() + "\n";
+        }
+        if (otherTags !== null) {
+            otherTags.forEach((tag) => {
+                m += tag.toString() + "\n";
+            });
+        }
+        return ` ${serviceIdentifierString}\n ${serviceIdentifierString} - ${m}`;
+    }
+    else {
+        return ` ${serviceIdentifierString}`;
+    }
+}
+function getFunctionName(func) {
+    if (func.name) {
+        return func.name;
+    }
+    else {
+        const name = func.toString();
+        const match = name.match(/^function\s*([^\s(]+)/);
+        return match ? match[1] : `Anonymous function: ${name}`;
+    }
+}
+function getSymbolDescription(symbol) {
+    return symbol.toString().slice(7, -1);
+}
+export { getFunctionName, getServiceIdentifierAsString, listRegisteredBindingsForServiceIdentifier, listMetadataForTarget, circularDependencyToException, getSymbolDescription, };

package/lib/esm/error/app-error.js

@@ -0,0 +1,209 @@
+import { StatusCode } from "./status-code.js";
+/**
+ * Application error class with RFC 7807 Problem Details support.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept error-handling
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Create application errors with HTTP status codes and rich metadata.
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * throw new AppError("User not found", 404);
+ *
+ * // With helper methods
+ * throw AppError.notFound("User", "123");
+ * throw AppError.badRequest("Invalid input", { field: "email" });
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * AppError extends Error with:
+ * - HTTP status code mapping
+ * - RFC 7807 Problem Details format
+ * - Rich metadata (errorCode, details, validationErrors)
+ * - Request correlation (requestId)
+ * - Timestamp tracking
+ *
+ * **Design Decisions**
+ * - Extends native Error for stack traces
+ * - RFC 7807 compliance for API consistency
+ * - Helper methods for common HTTP errors
+ * - Validation error support
+ *
+ * @see {@link StatusCode} for HTTP status codes
+ * @see {@link Report} for error reporting utility
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * With validation errors:
+ * ```typescript
+ * throw AppError.validationFailed([
+ *   { property: "email", messages: ["Invalid email format"] },
+ *   { property: "age", messages: ["Must be 18 or older"] }
+ * ]);
+ * ```
+ *
+ * With custom metadata:
+ * ```typescript
+ * throw new AppError("Custom error", 400, "MyService", {
+ *   errorCode: "CUSTOM_ERROR",
+ *   details: { userId: 123 },
+ *   requestId: "req-123"
+ * });
+ * ```
+ *
+ * @public API
+ */
+class AppError extends Error {
+    /**
+     * The HTTP status code associated with the error.
+     * Commonly used to define the HTTP response status code.
+     */
+    statusCode;
+    /**
+     * The service identifier associated with the error.
+     * This property can be used to trace the origin of the error in the application.
+     * It is optional and can be left undefined.
+     */
+    service;
+    /**
+     * Application-specific error code for programmatic error handling
+     */
+    errorCode;
+    /**
+     * Additional error context and details
+     */
+    details;
+    /**
+     * URI reference that identifies the specific occurrence of the problem (RFC 7807)
+     */
+    instance;
+    /**
+     * A URI reference that identifies the problem type (RFC 7807)
+     */
+    type;
+    /**
+     * Timestamp when the error occurred
+     */
+    timestamp;
+    /**
+     * Request correlation ID for tracing
+     */
+    requestId;
+    /**
+     * Validation errors for validation failures
+     */
+    validationErrors;
+    /**
+     * @param {string} message - The error message to be displayed.
+     * @param {number} [statusCode=500] - The HTTP status code associated with the error (default: 500).
+     * @param {string} [service] - The service identifier associated with the error.
+     * @param {AppErrorOptions} [options] - Additional error metadata options.
+     */
+    constructor(message, statusCode, service, options) {
+        super(message);
+        this.statusCode = statusCode || StatusCode.InternalServerError;
+        if (message === null) {
+            this.message = "";
+        }
+        this.service = service !== undefined ? service : undefined;
+        this.errorCode = options?.errorCode;
+        this.details = options?.details;
+        this.instance = options?.instance;
+        this.type =
+            options?.type || `https://expressots.dev/errors/${this.statusCode}`;
+        this.timestamp = new Date();
+        this.requestId = options?.requestId;
+        this.validationErrors = options?.validationErrors;
+        Error.captureStackTrace(this, this.constructor);
+    }
+    /**
+     * Creates a BadRequest (400) error
+     */
+    static badRequest(message, details) {
+        return new AppError(message, StatusCode.BadRequest, undefined, {
+            type: "https://expressots.dev/errors/bad-request",
+            details,
+        });
+    }
+    /**
+     * Creates a NotFound (404) error
+     */
+    static notFound(resource, id) {
+        return new AppError(`${resource}${id ? ` with id ${id}` : ""} not found`, StatusCode.NotFound, undefined, {
+            type: "https://expressots.dev/errors/not-found",
+            details: { resource, id },
+        });
+    }
+    /**
+     * Creates an Unauthorized (401) error
+     */
+    static unauthorized(message = "Unauthorized") {
+        return new AppError(message, StatusCode.Unauthorized, undefined, {
+            type: "https://expressots.dev/errors/unauthorized",
+        });
+    }
+    /**
+     * Creates a Forbidden (403) error
+     */
+    static forbidden(message = "Forbidden") {
+        return new AppError(message, StatusCode.Forbidden, undefined, {
+            type: "https://expressots.dev/errors/forbidden",
+        });
+    }
+    /**
+     * Creates an UnprocessableEntity (422) validation error
+     */
+    static validationFailed(errors) {
+        return new AppError("Validation failed", StatusCode.UnprocessableEntity, undefined, {
+            type: "https://expressots.dev/errors/validation-failed",
+            validationErrors: errors,
+        });
+    }
+    /**
+     * Creates a Conflict (409) error
+     */
+    static conflict(message, details) {
+        return new AppError(message, StatusCode.Conflict, undefined, {
+            type: "https://expressots.dev/errors/conflict",
+            details,
+        });
+    }
+    /**
+     * Converts the error to RFC 7807 Problem Details format
+     */
+    toProblemDetails() {
+        const problem = {
+            type: this.type,
+            title: this.message,
+            status: this.statusCode,
+            instance: this.instance,
+            timestamp: this.timestamp.toISOString(),
+        };
+        if (this.errorCode) {
+            problem.errorCode = this.errorCode;
+        }
+        if (this.service) {
+            problem.service = this.service;
+        }
+        if (this.details) {
+            problem.detail = this.details;
+        }
+        if (this.validationErrors) {
+            problem.validationErrors = this.validationErrors;
+        }
+        return problem;
+    }
+}
+export { AppError };