@lakutata/core 1.0.59 → 3.0.0-beta.0

package/dist/cjs/components/ConsoleLogger.js

@@ -0,0 +1,99 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleLogger = void 0;
+const node_util_1 = require("node:util");
+const Component_js_1 = require("../lib/core/Component.js");
+const Lifetime_js_1 = require("../decorators/di/Lifetime.js");
+const Configurable_js_1 = require("../decorators/di/Configurable.js");
+const DTO_js_1 = require("../lib/dto/DTO.js");
+const BasicInfo_js_1 = require("../lib/foundation/BasicInfo.js");
+const LEVELS = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, silent: Infinity };
+/**
+ * The logger of a core-only application, writing plain lines to the console:
+ * `[<ISO time>] <LEVEL> (<application name>): <message>`, formatted as `util.format()` (an object given before its
+ * message is written after it); the warnings and errors to stderr, the other levels to stdout. The application uses it
+ * when it has no `log` component; register it as `log` to configure its level. The `lakutata` package replaces it with
+ * its Logger component.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {ConsoleLogger} from '@lakutata/core/com/logger'
+ *
+ * Application.run({
+ *     id: 'tool.app',
+ *     name: 'Tool',
+ *     components: {
+ *         log: {class: ConsoleLogger, level: 'debug'}
+ *     }
+ * }).onLaunched((app, logger): void => logger.debug({pid: process.pid}, 'Launched'))
+ * ```
+ */
+let ConsoleLogger = class ConsoleLogger extends Component_js_1.Component {
+    /**
+     * Write a log line, unless its level is below the configured one.
+     * @param level The level of the line (`trace`, `debug`, `info`, `warn`, `error`).
+     * @param args An object (or error) and its message, or a message and its format arguments.
+     * @protected
+     */
+    write(level, args) {
+        if (LEVELS[level] < LEVELS[this.level])
+            return;
+        const [first, ...rest] = args;
+        //An object comes before its message, as in the structured loggers
+        const parts = typeof first === 'object' && first !== null && typeof rest[0] === 'string' ? [...rest, first] : args;
+        const line = `[${new Date().toISOString()}] ${level.toUpperCase()} (${(0, BasicInfo_js_1.getAppName)()}): ${(0, node_util_1.formatWithOptions)({ colors: false }, ...parts)}\n`;
+        LEVELS[level] >= LEVELS.warn ? process.stderr.write(line) : process.stdout.write(line);
+    }
+    /**
+     * Log an error to stderr.
+     * @param args An object (or error) and its message, or a message and its format arguments.
+     */
+    error(...args) {
+        this.write('error', args);
+    }
+    /**
+     * Log a warning to stderr.
+     * @param args An object (or error) and its message, or a message and its format arguments.
+     */
+    warn(...args) {
+        this.write('warn', args);
+    }
+    /**
+     * Log an information to stdout.
+     * @param args An object (or error) and its message, or a message and its format arguments.
+     */
+    info(...args) {
+        this.write('info', args);
+    }
+    /**
+     * Log a debugging detail to stdout (written when the level is `debug` or `trace`).
+     * @param args An object (or error) and its message, or a message and its format arguments.
+     */
+    debug(...args) {
+        this.write('debug', args);
+    }
+    /**
+     * Log a tracing detail to stdout (written when the level is `trace`).
+     * @param args An object (or error) and its message, or a message and its format arguments.
+     */
+    trace(...args) {
+        this.write('trace', args);
+    }
+};
+exports.ConsoleLogger = ConsoleLogger;
+__decorate([
+    (0, Configurable_js_1.Configurable)(DTO_js_1.DTO.String().valid(...Object.keys(LEVELS)).optional().default('info')),
+    __metadata("design:type", String)
+], ConsoleLogger.prototype, "level", void 0);
+exports.ConsoleLogger = ConsoleLogger = __decorate([
+    (0, Lifetime_js_1.Singleton)()
+], ConsoleLogger);

package/dist/cjs/constants/DIMetadataKey.d.ts

@@ -0,0 +1,10 @@
+import 'reflect-metadata';
+export declare const DI_CONTAINER_INJECT_PROPERTIES: symbol;
+export declare const DI_TARGET_CONSTRUCTOR_LIFETIME: symbol;
+export declare const DI_TARGET_CONSTRUCTOR_LIFETIME_LOCK: symbol;
+export declare const DI_TARGET_CONSTRUCTOR_INJECTS: symbol;
+export declare const DI_TARGET_CONSTRUCTOR_CONFIGURABLE_PROPERTIES: symbol;
+export declare const DI_TARGET_CONSTRUCTOR_SYMBOL: symbol;
+export declare const DI_TARGET_CONSTRUCTOR_AUTOLOAD: symbol;
+export declare const DI_TARGET_CONTAINER: symbol;
+export declare const DI_TARGET_ID: symbol;

package/dist/cjs/constants/DIMetadataKey.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DI_TARGET_ID = exports.DI_TARGET_CONTAINER = exports.DI_TARGET_CONSTRUCTOR_AUTOLOAD = exports.DI_TARGET_CONSTRUCTOR_SYMBOL = exports.DI_TARGET_CONSTRUCTOR_CONFIGURABLE_PROPERTIES = exports.DI_TARGET_CONSTRUCTOR_INJECTS = exports.DI_TARGET_CONSTRUCTOR_LIFETIME_LOCK = exports.DI_TARGET_CONSTRUCTOR_LIFETIME = exports.DI_CONTAINER_INJECT_PROPERTIES = void 0;
+require("reflect-metadata");
+exports.DI_CONTAINER_INJECT_PROPERTIES = Symbol('LAKUTATA.DI.CONTAINER.INJECT.PROPERTIES');
+exports.DI_TARGET_CONSTRUCTOR_LIFETIME = Symbol('LAKUTATA.DI.TARGET.CONSTRUCTOR.LIFETIME');
+exports.DI_TARGET_CONSTRUCTOR_LIFETIME_LOCK = Symbol('LAKUTATA.DI.TARGET.CONSTRUCTOR.LIFETIME.LOCK');
+exports.DI_TARGET_CONSTRUCTOR_INJECTS = Symbol('LAKUTATA.DI.TARGET.CONSTRUCTOR.INJECTS');
+exports.DI_TARGET_CONSTRUCTOR_CONFIGURABLE_PROPERTIES = Symbol('LAKUTATA.DI.TARGET.CONSTRUCTOR.CONFIGURABLE.PROPERTIES');
+exports.DI_TARGET_CONSTRUCTOR_SYMBOL = Symbol('LAKUTATA.DI.TARGET.CONSTRUCTOR.SYMBOL');
+exports.DI_TARGET_CONSTRUCTOR_AUTOLOAD = Symbol('LAKUTATA.DI.TARGET.CONSTRUCTOR.AUTOLOAD');
+exports.DI_TARGET_CONTAINER = Symbol('LAKUTATA.DI.TARGET.CONTAINER');
+exports.DI_TARGET_ID = Symbol('LAKUTATA.DI.TARGET.ID');

package/dist/cjs/constants/DTOMetadataKey.d.ts

@@ -0,0 +1,5 @@
+import 'reflect-metadata';
+export declare const DTO_CONSTRUCTOR: symbol;
+export declare const DTO_INDEX_SIGNATURE_SCHEMA: symbol;
+export declare const DTO_PROPERTY_SCHEMAS: symbol;
+export declare const DTO_OBJECT_REFINEMENT: symbol;

package/dist/cjs/constants/DTOMetadataKey.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DTO_OBJECT_REFINEMENT = exports.DTO_PROPERTY_SCHEMAS = exports.DTO_INDEX_SIGNATURE_SCHEMA = exports.DTO_CONSTRUCTOR = void 0;
+require("reflect-metadata");
+exports.DTO_CONSTRUCTOR = Symbol('LAKUTATA.DTO.CONSTRUCTOR');
+exports.DTO_INDEX_SIGNATURE_SCHEMA = Symbol('LAKUTATA.DTO.INDEX.SIGNATURE.SCHEMA');
+exports.DTO_PROPERTY_SCHEMAS = Symbol('LAKUTATA.DTO.PROPERTY.SCHEMAS');
+exports.DTO_OBJECT_REFINEMENT = Symbol('LAKUTATA.DTO.OBJECT.REFINEMENT');

package/dist/cjs/decorators/asst/After.d.ts

@@ -0,0 +1,29 @@
+import { MethodDecorator } from '../../types/MethodDecorator.js';
+import { AfterFunction } from '../../lib/base/internal/MethodAssistantFunction.js';
+/**
+ * Run a function after each call of the decorated method, with its result. The function is called with the instance as
+ * `this`; a value it returns other than `undefined` replaces the result, `undefined` keeps it. Several `@After` on a
+ * method run in turn, each one receiving the result left by the previous one; an error thrown by the function is thrown
+ * by the call.
+ * @param afterFunc The function receiving the method's result (awaited when the method is async), and returning a
+ * value of the method's return type (a promise for an async method). It may be async only when the method is async.
+ * @returns The method decorator.
+ * @throws {InvalidAssistantFunctionTypeException} When the class is defined, if `afterFunc` is async and the method is
+ * not, or if the decorated member is not a method.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {After} from 'lakutata/decorator/asst'
+ *
+ * class Prices extends Component {
+ *     //The prices are rounded to cents, whatever their computation
+ *     @After(async function (this: Prices, price: number): Promise<number> {
+ *         return Math.round(price * 100) / 100
+ *     })
+ *     public async withTax(price: number): Promise<number> {
+ *         return price * 1.196
+ *     }
+ * }
+ * ```
+ */
+export declare function After<ClassPrototype extends Object, Method extends (...args: any[]) => unknown>(afterFunc: AfterFunction<ClassPrototype, Method>): MethodDecorator<ClassPrototype, Method>;

package/dist/cjs/decorators/asst/After.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.After = After;
+const MethodAssistantFunction_js_1 = require("../../lib/base/internal/MethodAssistantFunction.js");
+/**
+ * Run a function after each call of the decorated method, with its result. The function is called with the instance as
+ * `this`; a value it returns other than `undefined` replaces the result, `undefined` keeps it. Several `@After` on a
+ * method run in turn, each one receiving the result left by the previous one; an error thrown by the function is thrown
+ * by the call.
+ * @param afterFunc The function receiving the method's result (awaited when the method is async), and returning a
+ * value of the method's return type (a promise for an async method). It may be async only when the method is async.
+ * @returns The method decorator.
+ * @throws {InvalidAssistantFunctionTypeException} When the class is defined, if `afterFunc` is async and the method is
+ * not, or if the decorated member is not a method.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {After} from 'lakutata/decorator/asst'
+ *
+ * class Prices extends Component {
+ *     //The prices are rounded to cents, whatever their computation
+ *     @After(async function (this: Prices, price: number): Promise<number> {
+ *         return Math.round(price * 100) / 100
+ *     })
+ *     public async withTax(price: number): Promise<number> {
+ *         return price * 1.196
+ *     }
+ * }
+ * ```
+ */
+function After(afterFunc) {
+    return (target, propertyKey, descriptor) => (0, MethodAssistantFunction_js_1.registerAfterFunction)(target, propertyKey, descriptor, afterFunc);
+}

package/dist/cjs/decorators/asst/Before.d.ts

@@ -0,0 +1,28 @@
+import { MethodDecorator } from '../../types/MethodDecorator.js';
+import { BeforeFunction } from '../../lib/base/internal/MethodAssistantFunction.js';
+/**
+ * Run a function before each call of the decorated method, with its arguments. The function is called with the
+ * instance as `this`; an array it returns replaces the arguments passed to the method, `undefined` keeps them. Several
+ * `@Before` on a method run in turn, each one receiving the arguments left by the previous one; an error thrown by the
+ * function is thrown by the call, and the method does not run.
+ * @param beforeFunc The function receiving the method's arguments. It may be async only when the method is async.
+ * @returns The method decorator.
+ * @throws {InvalidAssistantFunctionTypeException} When the class is defined, if `beforeFunc` is async and the method is
+ * not, or if the decorated member is not a method.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {Before} from 'lakutata/decorator/asst'
+ *
+ * class Users extends Component {
+ *     //The names are looked up trimmed and in lower case
+ *     @Before(function (this: Users, name: string): [string] {
+ *         return [name.trim().toLowerCase()]
+ *     })
+ *     public async find(name: string): Promise<string | undefined> {
+ *         return name === 'ada' ? 'Ada Lovelace' : undefined
+ *     }
+ * }
+ * ```
+ */
+export declare function Before<ClassPrototype extends Object, Method extends (...args: any[]) => unknown>(beforeFunc: BeforeFunction<ClassPrototype, Method>): MethodDecorator<ClassPrototype, Method>;

package/dist/cjs/decorators/asst/Before.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Before = Before;
+const MethodAssistantFunction_js_1 = require("../../lib/base/internal/MethodAssistantFunction.js");
+/**
+ * Run a function before each call of the decorated method, with its arguments. The function is called with the
+ * instance as `this`; an array it returns replaces the arguments passed to the method, `undefined` keeps them. Several
+ * `@Before` on a method run in turn, each one receiving the arguments left by the previous one; an error thrown by the
+ * function is thrown by the call, and the method does not run.
+ * @param beforeFunc The function receiving the method's arguments. It may be async only when the method is async.
+ * @returns The method decorator.
+ * @throws {InvalidAssistantFunctionTypeException} When the class is defined, if `beforeFunc` is async and the method is
+ * not, or if the decorated member is not a method.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {Before} from 'lakutata/decorator/asst'
+ *
+ * class Users extends Component {
+ *     //The names are looked up trimmed and in lower case
+ *     @Before(function (this: Users, name: string): [string] {
+ *         return [name.trim().toLowerCase()]
+ *     })
+ *     public async find(name: string): Promise<string | undefined> {
+ *         return name === 'ada' ? 'Ada Lovelace' : undefined
+ *     }
+ * }
+ * ```
+ */
+function Before(beforeFunc) {
+    return (target, propertyKey, descriptor) => (0, MethodAssistantFunction_js_1.registerBeforeFunction)(target, propertyKey, descriptor, beforeFunc);
+}

package/dist/cjs/decorators/di/Autoload.d.ts

@@ -0,0 +1,33 @@
+import { BaseObject } from '../../lib/base/BaseObject.js';
+import { ClassDecorator } from '../../types/ClassDecorator.js';
+/**
+ * Let the container register the class on first use: when the class is requested (by `getObject(TheClass)` or
+ * `@Inject(TheClass)`) and is not registered, it is registered, then resolved, instead of failing. A singleton is
+ * registered in the root container (shared by the whole application), a scoped class in the nearest scope (shared
+ * within the request), a transient class in the requesting container. The registration has no options: the
+ * `@Configurable` properties take the options given to `getObject()`, else their initializers or their schema
+ * defaults. The mark is not inherited by subclasses.
+ * @returns The class decorator.
+ * @example
+ * ```typescript
+ * import {Component, Provider} from 'lakutata'
+ * import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+ *
+ * //Not declared in the application: registered the first time it is injected
+ * @Autoload()
+ * @Scoped()
+ * class RequestClock extends Provider {
+ *     public readonly startedAt: number = Date.now()
+ * }
+ *
+ * class Reports extends Component {
+ *     @Inject(RequestClock)
+ *     protected readonly clock!: RequestClock
+ *
+ *     public elapsed(): number {
+ *         return Date.now() - this.clock.startedAt
+ *     }
+ * }
+ * ```
+ */
+export declare function Autoload<ClassConstructor extends typeof BaseObject>(): ClassDecorator<ClassConstructor>;

package/dist/cjs/decorators/di/Autoload.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Autoload = Autoload;
+const ObjectInjection_js_1 = require("../../lib/base/internal/ObjectInjection.js");
+/**
+ * Let the container register the class on first use: when the class is requested (by `getObject(TheClass)` or
+ * `@Inject(TheClass)`) and is not registered, it is registered, then resolved, instead of failing. A singleton is
+ * registered in the root container (shared by the whole application), a scoped class in the nearest scope (shared
+ * within the request), a transient class in the requesting container. The registration has no options: the
+ * `@Configurable` properties take the options given to `getObject()`, else their initializers or their schema
+ * defaults. The mark is not inherited by subclasses.
+ * @returns The class decorator.
+ * @example
+ * ```typescript
+ * import {Component, Provider} from 'lakutata'
+ * import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+ *
+ * //Not declared in the application: registered the first time it is injected
+ * @Autoload()
+ * @Scoped()
+ * class RequestClock extends Provider {
+ *     public readonly startedAt: number = Date.now()
+ * }
+ *
+ * class Reports extends Component {
+ *     @Inject(RequestClock)
+ *     protected readonly clock!: RequestClock
+ *
+ *     public elapsed(): number {
+ *         return Date.now() - this.clock.startedAt
+ *     }
+ * }
+ * ```
+ */
+function Autoload() {
+    return (target) => (0, ObjectInjection_js_1.markObjectAsAutoload)(target);
+}

package/dist/cjs/decorators/di/Configurable.d.ts

@@ -0,0 +1,51 @@
+import { PropertyDecorator } from '../../types/PropertyDecorator.js';
+import { BaseObject } from '../../lib/base/BaseObject.js';
+import { Schema } from '../../lib/validation/types/Schema.js';
+/**
+ * Make the property an option of the object: its value is the option given in the object's declaration (`{class:
+ * MyComponent, port: 80}`) or to `getObject()`, else the property's initializer, else the default of its schema. The
+ * value is validated against the schema, then passed to `fn`, when the object is created: after its injections, before
+ * its `init()` runs. The declaration replaces an `@Inject` or `@Configurable` declaration of the property in a parent
+ * class. A module also checks the options of the objects it declares when it initializes, before creating them.
+ * @param schema The schema validating the value (it may convert it or give its default). Default `DTO.Any()`: any
+ * value, `undefined` included.
+ * @param fn A function called with the instance as `this` and the validated value, returning the value set to the
+ * property, of the same type (it may be async). Default: the validated value as it is.
+ * @returns The property decorator.
+ * @throws {InvalidObjectOptionsException} When a module initializes, if an option it declares for the object does not
+ * match the schema (all the invalid options are listed).
+ * @throws {InvalidValueException} When the object is created, if its value does not match the schema (the creation of
+ * the object rejects).
+ * @example
+ * ```typescript
+ * import {Application, Component, DTO} from 'lakutata'
+ * import {Configurable} from 'lakutata/decorator/di'
+ *
+ * class Server extends Component {
+ *     //80 unless the declaration gives a port
+ *     @Configurable(DTO.Number().integer().min(1).max(65535).optional().default(80))
+ *     protected readonly port!: number
+ *
+ *     //The initializer is the default, validated like a configured value
+ *     @Configurable(DTO.String().required())
+ *     protected readonly host: string = '127.0.0.1'
+ *
+ *     //The base URL is kept without its trailing slash
+ *     @Configurable(DTO.String().uri().optional().default('http://localhost'), (value: string): string => value.replace(/\/+$/, ''))
+ *     protected readonly baseURL!: string
+ *
+ *     protected async init(): Promise<void> {
+ *         console.log(`Listening on ${this.host}:${this.port} for ${this.baseURL}`)
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'server.app',
+ *     name: 'Server',
+ *     components: {
+ *         server: {class: Server, port: 8080, baseURL: 'https://example.com/'}
+ *     }
+ * }))
+ * ```
+ */
+export declare function Configurable<ClassPrototype extends BaseObject, DataType>(schema?: Schema<DataType>, fn?: (this: ClassPrototype, value: DataType) => DataType | Promise<DataType>): PropertyDecorator<ClassPrototype>;

package/dist/cjs/decorators/di/Configurable.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Configurable = Configurable;
+const ObjectConfiguration_js_1 = require("../../lib/base/internal/ObjectConfiguration.js");
+const DTO_js_1 = require("../../lib/dto/DTO.js");
+const ObjectInjection_js_1 = require("../../lib/base/internal/ObjectInjection.js");
+/**
+ * Make the property an option of the object: its value is the option given in the object's declaration (`{class:
+ * MyComponent, port: 80}`) or to `getObject()`, else the property's initializer, else the default of its schema. The
+ * value is validated against the schema, then passed to `fn`, when the object is created: after its injections, before
+ * its `init()` runs. The declaration replaces an `@Inject` or `@Configurable` declaration of the property in a parent
+ * class. A module also checks the options of the objects it declares when it initializes, before creating them.
+ * @param schema The schema validating the value (it may convert it or give its default). Default `DTO.Any()`: any
+ * value, `undefined` included.
+ * @param fn A function called with the instance as `this` and the validated value, returning the value set to the
+ * property, of the same type (it may be async). Default: the validated value as it is.
+ * @returns The property decorator.
+ * @throws {InvalidObjectOptionsException} When a module initializes, if an option it declares for the object does not
+ * match the schema (all the invalid options are listed).
+ * @throws {InvalidValueException} When the object is created, if its value does not match the schema (the creation of
+ * the object rejects).
+ * @example
+ * ```typescript
+ * import {Application, Component, DTO} from 'lakutata'
+ * import {Configurable} from 'lakutata/decorator/di'
+ *
+ * class Server extends Component {
+ *     //80 unless the declaration gives a port
+ *     @Configurable(DTO.Number().integer().min(1).max(65535).optional().default(80))
+ *     protected readonly port!: number
+ *
+ *     //The initializer is the default, validated like a configured value
+ *     @Configurable(DTO.String().required())
+ *     protected readonly host: string = '127.0.0.1'
+ *
+ *     //The base URL is kept without its trailing slash
+ *     @Configurable(DTO.String().uri().optional().default('http://localhost'), (value: string): string => value.replace(/\/+$/, ''))
+ *     protected readonly baseURL!: string
+ *
+ *     protected async init(): Promise<void> {
+ *         console.log(`Listening on ${this.host}:${this.port} for ${this.baseURL}`)
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'server.app',
+ *     name: 'Server',
+ *     components: {
+ *         server: {class: Server, port: 8080, baseURL: 'https://example.com/'}
+ *     }
+ * }))
+ * ```
+ */
+function Configurable(schema = DTO_js_1.DTO.Any(), fn) {
+    return (target, propertyKey) => {
+        (0, ObjectConfiguration_js_1.setObjectConfigurableProperty)(target, propertyKey, schema, fn);
+        //The property is configured, not injected: an injection of the parents is removed
+        (0, ObjectInjection_js_1.removeObjectInjectItem)(target, propertyKey);
+    };
+}

package/dist/cjs/decorators/di/Inject.d.ts

@@ -0,0 +1,85 @@
+import { PropertyDecorator } from '../../types/PropertyDecorator.js';
+import { BaseObject } from '../../lib/base/BaseObject.js';
+import { InjectionName, InjectionTransformFunction } from '../../lib/base/internal/ObjectInjection.js';
+/**
+ * Inject into the property the object registered in the container under the property's name.
+ * The injection happens when the object is created, before its `@Configurable` properties are set and before its
+ * `init()` runs; it replaces a `@Configurable` declaration of the property in a parent class.
+ * @returns The property decorator.
+ * @throws {DependencyInjectionException} When the object is created, if the registration cannot be resolved (the creation
+ * of the object rejects).
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ *
+ * class Mailer extends Component {
+ *     public async send(to: string, text: string): Promise<void> {
+ *         console.log(to, text)
+ *     }
+ * }
+ *
+ * class Signup extends Component {
+ *     //The component registered as "mailer"
+ *     @Inject()
+ *     protected readonly mailer!: Mailer
+ *
+ *     //The object registered for the class (a class marked with @Autoload is registered on first use)
+ *     @Inject(Application)
+ *     protected readonly app!: Application
+ *
+ *     //The component registered as "mailer", transformed: its send function bound to it
+ *     @Inject('mailer', (mailer: Mailer) => mailer.send.bind(mailer))
+ *     protected readonly send!: (to: string, text: string) => Promise<void>
+ *
+ *     public async register(email: string): Promise<void> {
+ *         await this.mailer.send(email, `Welcome to ${this.app.appName}`)
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'signup.app',
+ *     name: 'Signup',
+ *     components: {
+ *         mailer: {class: Mailer},
+ *         signup: {class: Signup}
+ *     }
+ * }))
+ * ```
+ */
+export declare function Inject<ClassPrototype extends BaseObject>(): PropertyDecorator<ClassPrototype>;
+/**
+ * Inject into the property the object registered in the container under a name, or for a class.
+ * The injection happens when the object is created, before its `@Configurable` properties are set and before its
+ * `init()` runs; it replaces a `@Configurable` declaration of the property in a parent class.
+ * @param name The registration name (a string or a symbol), or a class: the object registered for the class, which is
+ * registered on first use when the class is marked with `@Autoload()`.
+ * @returns The property decorator.
+ * @throws {DependencyInjectionException} When the object is created, if the registration cannot be resolved (the creation
+ * of the object rejects).
+ */
+export declare function Inject<ClassPrototype extends BaseObject>(name: InjectionName): PropertyDecorator<ClassPrototype>;
+/**
+ * Inject into the property a value derived from the object registered in the container under the property's name.
+ * The injection happens when the object is created, before its `@Configurable` properties are set and before its
+ * `init()` runs; it replaces a `@Configurable` declaration of the property in a parent class.
+ * @param transform A function (not a class) receiving the registered object and returning the value set to the
+ * property; it may be async, the property then receives the value it resolves to.
+ * @returns The property decorator.
+ * @throws {DependencyInjectionException} When the object is created, if the registration cannot be resolved (the creation
+ * of the object rejects); an error of `transform` rejects the creation as it is.
+ */
+export declare function Inject<ClassPrototype extends BaseObject>(transform: InjectionTransformFunction): PropertyDecorator<ClassPrototype>;
+/**
+ * Inject into the property a value derived from the object registered in the container under a name, or for a class.
+ * The injection happens when the object is created, before its `@Configurable` properties are set and before its
+ * `init()` runs; it replaces a `@Configurable` declaration of the property in a parent class.
+ * @param name The registration name (a string or a symbol), or a class: the object registered for the class, which is
+ * registered on first use when the class is marked with `@Autoload()`.
+ * @param transform A function receiving the registered object and returning the value set to the property; it may be
+ * async, the property then receives the value it resolves to.
+ * @returns The property decorator.
+ * @throws {DependencyInjectionException} When the object is created, if the registration cannot be resolved (the creation
+ * of the object rejects); an error of `transform` rejects the creation as it is.
+ */
+export declare function Inject<ClassPrototype extends BaseObject>(name: InjectionName, transform: InjectionTransformFunction): PropertyDecorator<ClassPrototype>;

package/dist/cjs/decorators/di/Inject.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Inject = Inject;
+const ObjectInjection_js_1 = require("../../lib/base/internal/ObjectInjection.js");
+const Utils_js_1 = require("../../lib/ioc/Utils.js");
+const As_1 = require("@lakutata/utils/As");
+const ObjectConfiguration_js_1 = require("../../lib/base/internal/ObjectConfiguration.js");
+function Inject(nameOrTransform, transform) {
+    return (target, propertyKey) => {
+        let injectionName = propertyKey;
+        let injectionTransform = (injection) => injection;
+        if (nameOrTransform || transform) {
+            if (transform) {
+                injectionName = (0, As_1.As)(nameOrTransform);
+                injectionTransform = transform;
+            }
+            else {
+                if (typeof nameOrTransform === 'function') {
+                    if ((0, Utils_js_1.isClass)(nameOrTransform)) {
+                        injectionName = (0, As_1.As)(nameOrTransform);
+                    }
+                    else {
+                        injectionTransform = (0, As_1.As)(nameOrTransform);
+                    }
+                }
+                else {
+                    injectionName = (0, As_1.As)(nameOrTransform);
+                }
+            }
+        }
+        //A class is kept as it is: the container resolves it by its constructor symbol, and autoloads it when it is marked so
+        (0, ObjectInjection_js_1.setObjectInjectItem)(target, propertyKey, injectionName, injectionTransform);
+        //The property is injected, not configured: a configurable property of the parents is removed
+        (0, ObjectConfiguration_js_1.removeObjectConfigurableProperty)(target, propertyKey);
+    };
+}