@lakutata/core 1.0.60 → 3.0.0-beta.0

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

@@ -0,0 +1,29 @@
+import { registerBeforeFunction } 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 function Before(beforeFunc) {
+    return (target, propertyKey, descriptor) => registerBeforeFunction(target, propertyKey, descriptor, beforeFunc);
+}

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

@@ -0,0 +1,34 @@
+import { markObjectAsAutoload } from '../../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
+ *     }
+ * }
+ * ```
+ */
+export function Autoload() {
+    return (target) => markObjectAsAutoload(target);
+}

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

@@ -0,0 +1,57 @@
+import { setObjectConfigurableProperty } from '../../lib/base/internal/ObjectConfiguration.js';
+import { DTO } from '../../lib/dto/DTO.js';
+import { removeObjectInjectItem } from '../../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/'}
+ *     }
+ * }))
+ * ```
+ */
+export function Configurable(schema = DTO.Any(), fn) {
+    return (target, propertyKey) => {
+        setObjectConfigurableProperty(target, propertyKey, schema, fn);
+        //The property is configured, not injected: an injection of the parents is removed
+        removeObjectInjectItem(target, propertyKey);
+    };
+}

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

@@ -0,0 +1,33 @@
+import { setObjectInjectItem } from '../../lib/base/internal/ObjectInjection.js';
+import { isClass } from '../../lib/ioc/Utils.js';
+import { As } from '@lakutata/utils/As';
+import { removeObjectConfigurableProperty } from '../../lib/base/internal/ObjectConfiguration.js';
+export function Inject(nameOrTransform, transform) {
+    return (target, propertyKey) => {
+        let injectionName = propertyKey;
+        let injectionTransform = (injection) => injection;
+        if (nameOrTransform || transform) {
+            if (transform) {
+                injectionName = As(nameOrTransform);
+                injectionTransform = transform;
+            }
+            else {
+                if (typeof nameOrTransform === 'function') {
+                    if (isClass(nameOrTransform)) {
+                        injectionName = As(nameOrTransform);
+                    }
+                    else {
+                        injectionTransform = As(nameOrTransform);
+                    }
+                }
+                else {
+                    injectionName = 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
+        setObjectInjectItem(target, propertyKey, injectionName, injectionTransform);
+        //The property is injected, not configured: a configurable property of the parents is removed
+        removeObjectConfigurableProperty(target, propertyKey);
+    };
+}

package/dist/esm/decorators/di/Lifetime.js

@@ -0,0 +1,100 @@
+import { setObjectLifetime } from '../../lib/ioc/ObjectLifetime.js';
+/**
+ * Set how the container shares the instances of a class: `SINGLETON` (one instance, created once by the container
+ * registering the class and shared by all its users), `SCOPED` (one instance per scope, a request of an entrypoint), or
+ * `TRANSIENT` (a new instance on each request, never cached). Subclasses inherit the lifetime. `BaseObject` is
+ * transient, `Provider` scoped (a provider may be a singleton, scoped or transient), `Component` and `Module` are
+ * locked singletons. Prefer the shorthands `@Singleton()`,
+ * `@Scoped()` and `@Transient()`.
+ * @param lifetime The lifetime: `'SINGLETON'`, `'SCOPED'` or `'TRANSIENT'`.
+ * @param lock Whether the subclasses are forbidden to change the lifetime (they may still declare the same one).
+ * Default `false`.
+ * @returns The class decorator.
+ * @throws {LifetimeLockedException} When the class is defined, if a parent class locked another lifetime.
+ * @example
+ * ```typescript
+ * import {BaseObject} from 'lakutata'
+ * import {Lifetime} from 'lakutata/decorator/di'
+ *
+ * //A new counter for each object requesting it
+ * @Lifetime('TRANSIENT')
+ * export class Counter extends BaseObject {
+ *     public value: number = 0
+ * }
+ * ```
+ */
+export function Lifetime(lifetime, lock = false) {
+    return (target) => setObjectLifetime(target, lifetime, lock);
+}
+/**
+ * Make the class a singleton: the container registering it creates one instance, on first request, and shares it with
+ * all its users (the scopes included) until the container is destroyed. Shorthand of `@Lifetime('SINGLETON', lock)`.
+ * @param lock Whether the subclasses are forbidden to change the lifetime (they may still declare the same one).
+ * Default `false`.
+ * @returns The class decorator.
+ * @throws {LifetimeLockedException} When the class is defined, if a parent class locked another lifetime.
+ * @example
+ * ```typescript
+ * import {BaseObject} from 'lakutata'
+ * import {Singleton} from 'lakutata/decorator/di'
+ *
+ * //One cache shared by the whole application
+ * @Singleton()
+ * export class Cache extends BaseObject {
+ *     public readonly entries: Map<string, unknown> = new Map()
+ * }
+ * ```
+ */
+export function Singleton(lock = false) {
+    return Lifetime('SINGLETON', lock);
+}
+/**
+ * Make the class transient: the container creates a new instance on each request (each `getObject()` and each
+ * injection), never cached. Shorthand of `@Lifetime('TRANSIENT', lock)`; the default of `BaseObject`.
+ * @param lock Whether the subclasses are forbidden to change the lifetime (they may still declare the same one).
+ * Default `false`.
+ * @returns The class decorator.
+ * @throws {LifetimeLockedException} When the class is defined, if a parent class locked another lifetime.
+ * @example
+ * ```typescript
+ * import {Provider} from 'lakutata'
+ * import {Transient} from 'lakutata/decorator/di'
+ *
+ * //Each user of the builder gets its own, with its own state
+ * @Transient()
+ * export class QueryBuilder extends Provider {
+ *     protected readonly clauses: string[] = []
+ *
+ *     public where(clause: string): this {
+ *         this.clauses.push(clause)
+ *         return this
+ *     }
+ * }
+ * ```
+ */
+export function Transient(lock = false) {
+    return Lifetime('TRANSIENT', lock);
+}
+/**
+ * Make the class scoped: the container creates one instance per scope (an entrypoint creates a scope for each
+ * request), shared by the objects of that scope and destroyed with it; outside a scope, the container registering the
+ * class shares one instance. Shorthand of `@Lifetime('SCOPED', lock)`; the default of `Provider`.
+ * @param lock Whether the subclasses are forbidden to change the lifetime (they may still declare the same one).
+ * Default `false`.
+ * @returns The class decorator.
+ * @throws {LifetimeLockedException} When the class is defined, if a parent class locked another lifetime.
+ * @example
+ * ```typescript
+ * import {Provider} from 'lakutata'
+ * import {Scoped} from 'lakutata/decorator/di'
+ *
+ * //The objects handling the same request share its transaction
+ * @Scoped()
+ * export class RequestTransaction extends Provider {
+ *     public readonly startedAt: number = Date.now()
+ * }
+ * ```
+ */
+export function Scoped(lock = false) {
+    return Lifetime('SCOPED', lock);
+}

package/dist/esm/decorators/dto/Accept.js

@@ -0,0 +1,38 @@
+import { setMethodAcceptArgumentsValidator } from '../../lib/dto/MethodValidation.js';
+/**
+ * Validate the arguments of each call of the method, in order, against the schemas given; the method then receives the
+ * validated values (defaults applied, the keys without schema removed). A DTO class validates its argument against its
+ * schema: the method receives a plain object, not an instance of the class. The arguments beyond the schemas given are
+ * passed unchecked. An async method is validated asynchronously (its call rejects on failure), another method
+ * synchronously.
+ * @remarks A missing argument is accepted unless its schema is required (`MyDTO.required()`,
+ * `DTO.String().required()`), whether it is omitted or passed as `undefined` (its default then applied).
+ * @param defs The schemas of the arguments, by position: DTO classes or schemas (`DTO.String()`).
+ * @returns The method decorator; the decorated method cannot be reassigned.
+ * @throws {InvalidMethodAcceptException} From a call, when an argument does not match its schema (its cause is the
+ * `InvalidValueException` of the validation).
+ * @example
+ * ```typescript
+ * import {Component, DTO} from 'lakutata'
+ * import {Accept, Expect} from 'lakutata/decorator/dto'
+ *
+ * class TransferDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public to!: string
+ *
+ *     @Expect(DTO.Number().positive().required())
+ *     public amount!: number
+ * }
+ *
+ * class Bank extends Component {
+ *     //The transfer is required, the note optional
+ *     @Accept(TransferDTO.required(), DTO.String().max(140).optional())
+ *     public async transfer(transfer: TransferDTO, note?: string): Promise<void> {
+ *         console.log(`${transfer.amount} to ${transfer.to}`, note)
+ *     }
+ * }
+ * ```
+ */
+export function Accept(...defs) {
+    return (target, propertyKey, descriptor) => setMethodAcceptArgumentsValidator(target, propertyKey, descriptor, defs);
+}

package/dist/esm/decorators/dto/Expect.js

@@ -0,0 +1,38 @@
+import { setObjectPropertySchema } from '../../lib/dto/ObjectSchemaValidation.js';
+/**
+ * Declare the schema of a property of a DTO class. The DTO validates the property against it when it is constructed
+ * (the whole object at once: defaults applied, the keys without schema removed unless the class has an
+ * `@IndexSignature`), and each time the property, or a value nested in it, is changed afterwards (the change is undone
+ * when invalid). The schema is also part of the class schema (`MyDTO.Schema()`) used by `@Accept`, `@Return` and the
+ * actions' input validation. Subclasses inherit the property schemas, and may declare a property again to replace its
+ * schema. Ignored on a symbol property or on a class which is not a DTO.
+ * @param schema The schema of the property, built with the static methods of `DTO` (`DTO.String().required()`); a
+ * property is optional unless its schema is marked `required()`.
+ * @returns The property decorator.
+ * @throws {InvalidValueException} From the DTO constructor, or from an assignment to the property, when the value does
+ * not match the schema.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Expect} from 'lakutata/decorator/dto'
+ *
+ * class CreateUserDTO extends DTO {
+ *     @Expect(DTO.String().min(2).max(50).required())
+ *     public name!: string
+ *
+ *     @Expect(DTO.String().email().required())
+ *     public email!: string
+ *
+ *     @Expect(DTO.Number().integer().min(0).optional().default(0))
+ *     public credits?: number
+ * }
+ *
+ * //Validated when constructed: credits is 0, an invalid email throws an InvalidValueException
+ * const user: CreateUserDTO = new CreateUserDTO({name: 'Ada', email: 'ada@example.com'})
+ * //Validated when changed: throws an InvalidValueException, the name is unchanged
+ * user.name = 'A'
+ * ```
+ */
+export function Expect(schema) {
+    return (target, propertyKey) => setObjectPropertySchema(target, propertyKey, schema);
+}

package/dist/esm/decorators/dto/IndexSignature.js

@@ -0,0 +1,30 @@
+import { setObjectIndexSignatureSchema } from '../../lib/dto/ObjectSchemaValidation.js';
+/**
+ * Accept in a DTO the string keys without an `@Expect` schema, validated against a schema: they are kept instead of
+ * removed, and an invalid one fails the validation (on construction, on assignment, and in the class schema). Without
+ * it, the keys without schema are removed. Subclasses inherit it. `FlexibleDTO` is a DTO accepting any key.
+ * @param schema The schema of the value of each key without its own schema (`DTO.Any()` for any value).
+ * @returns The class decorator.
+ * @throws {InvalidValueException} From the DTO constructor, or from an assignment, when the value of a key without schema
+ * does not match the schema.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Expect, IndexSignature} from 'lakutata/decorator/dto'
+ *
+ * //A device and its numeric readings, named freely
+ * @IndexSignature(DTO.Number())
+ * class ReadingsDTO extends DTO {
+ *     [sensor: string]: any
+ *
+ *     @Expect(DTO.String().required())
+ *     public device!: string
+ * }
+ *
+ * const readings: ReadingsDTO = new ReadingsDTO({device: 'boiler', temperature: 61.5, pressure: 1.8})
+ * console.log(readings.temperature)
+ * ```
+ */
+export function IndexSignature(schema) {
+    return (target) => setObjectIndexSignatureSchema(target, schema);
+}

package/dist/esm/decorators/dto/Return.js

@@ -0,0 +1,39 @@
+import { setMethodReturnValueValidator } from '../../lib/dto/MethodValidation.js';
+/**
+ * Validate the result of each call of the method (awaited for an async method) against a schema; the caller then
+ * receives the validated value (defaults applied, the keys without schema removed). A DTO class validates the result
+ * against its schema: the caller receives a plain object. The schema is also published for the entrypoints describing
+ * the results of their actions (see `getMethodReturnSchema`).
+ * @param def The schema of the result: a DTO class or a schema (`DTO.Number()`).
+ * @returns The method decorator; the decorated method cannot be reassigned.
+ * @throws {InvalidMethodReturnException} From a call, when the method returns `undefined` (whatever the schema), or a
+ * value which does not match the schema (its cause is the `InvalidValueException` of the validation).
+ * @example
+ * ```typescript
+ * import {Component, DTO} from 'lakutata'
+ * import {Expect, Return} from 'lakutata/decorator/dto'
+ *
+ * class UserDTO extends DTO {
+ *     @Expect(DTO.Number().integer().required())
+ *     public id!: number
+ *
+ *     @Expect(DTO.String().required())
+ *     public name!: string
+ * }
+ *
+ * declare const db: {
+ *     findUser(id: number): Promise<{id: number, name: string, passwordHash: string}>
+ * }
+ *
+ * class Users extends Component {
+ *     //The password hash is removed from the result: UserDTO has no schema for it
+ *     @Return(UserDTO)
+ *     public async find(id: number): Promise<{id: number, name: string}> {
+ *         return await db.findUser(id)
+ *     }
+ * }
+ * ```
+ */
+export function Return(def) {
+    return (target, propertyKey, descriptor) => setMethodReturnValueValidator(target, propertyKey, descriptor, def);
+}

package/dist/esm/dto/PaginationResultDTO.js

@@ -0,0 +1,46 @@
+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);
+};
+import { DTO } from '../lib/dto/DTO.js';
+import { Expect } from '../decorators/dto/Expect.js';
+/**
+ * The result of a paginated search: the items of the page, and where the page is in the whole result. `paginator()`
+ * builds it; use it with `@Return` to validate the result of a paginated action.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {Return} from 'lakutata/decorator/dto'
+ * import {PaginationResultDTO} from 'lakutata/dtos'
+ *
+ * class Tags extends Component {
+ *     protected readonly tags: string[] = ['red', 'green', 'blue']
+ *
+ *     @Return(PaginationResultDTO)
+ *     public async list(limit: number, offset: number): Promise<PaginationResultDTO<string>> {
+ *         const items: string[] = this.tags.slice(offset, offset + limit)
+ *         return {items: items, meta: {count: items.length, total: this.tags.length, limit: limit, offset: offset}}
+ *     }
+ * }
+ * ```
+ */
+export class PaginationResultDTO extends DTO {
+}
+__decorate([
+    Expect(DTO.Array(DTO.Any()).required()),
+    __metadata("design:type", Object)
+], PaginationResultDTO.prototype, "items", void 0);
+__decorate([
+    Expect(DTO.Object({
+        count: DTO.Number().integer().positive().allow(0).required(),
+        total: DTO.Number().integer().positive().allow(0).required(),
+        limit: DTO.Number().integer().positive().allow(0).required(),
+        offset: DTO.Number().integer().positive().allow(0).required()
+    }).required()),
+    __metadata("design:type", Object)
+], PaginationResultDTO.prototype, "meta", void 0);

package/dist/esm/dto/PaginationSearchDTO.js

@@ -0,0 +1,41 @@
+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);
+};
+import { DTO } from '../lib/dto/DTO.js';
+import { Expect } from '../decorators/dto/Expect.js';
+/**
+ * The input of a paginated search: how many items to return and how many to skip. Extend it with the search criteria,
+ * and pass the validated input to `paginator()`.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {PaginationSearchDTO} from 'lakutata/dtos'
+ *
+ * //Searching the users by name, a page at a time
+ * export class UserSearchDTO extends PaginationSearchDTO {
+ *     @Expect(DTO.String().optional())
+ *     public name?: string
+ * }
+ *
+ * //limit 10 and offset 0 by default
+ * const search: UserSearchDTO = new UserSearchDTO({name: 'ada'})
+ * console.log(search.limit, search.offset)
+ * ```
+ */
+export class PaginationSearchDTO extends DTO {
+}
+__decorate([
+    Expect(DTO.Number().integer().positive().allow(0).optional().default(10)),
+    __metadata("design:type", Number)
+], PaginationSearchDTO.prototype, "limit", void 0);
+__decorate([
+    Expect(DTO.Number().integer().positive().allow(0).optional().default(0)),
+    __metadata("design:type", Number)
+], PaginationSearchDTO.prototype, "offset", void 0);

package/dist/esm/dto/Paginator.js

@@ -0,0 +1,50 @@
+/**
+ * Fetch a page of items with a handler, and build the paginated result: the items, with the page metadata (`count`
+ * the number of items returned, `total` the handler's total, and the `limit` and `offset` of the search). It does not
+ * validate the search: pass a validated `PaginationSearchDTO` (the input of an action, or a constructed DTO), whose
+ * `limit` and `offset` have their defaults (10 and 0).
+ * @param options The search, a `PaginationSearchDTO` or a subclass carrying the search criteria.
+ * @param handler A function receiving the limit, the offset and the whole search, and resolving to the page of items
+ * and the total; its rejection rejects the paginator.
+ * @returns A promise of the paginated result (a plain object shaped as `PaginationResultDTO`).
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {PaginationResultDTO, PaginationSearchDTO, paginator} from 'lakutata/dtos'
+ *
+ * class UserSearchDTO extends PaginationSearchDTO {
+ *     @Expect(DTO.String().optional())
+ *     public name?: string
+ * }
+ *
+ * interface User {
+ *     id: number
+ *     name: string
+ * }
+ *
+ * declare const db: {
+ *     countUsers(name?: string): Promise<number>
+ *     findUsers(name: string | undefined, limit: number, offset: number): Promise<User[]>
+ * }
+ *
+ * export async function SearchUsers(input: Record<string, unknown>): Promise<PaginationResultDTO<User>> {
+ *     return await paginator(new UserSearchDTO(input), async (limit: number, offset: number, search: UserSearchDTO) => ({
+ *         total: await db.countUsers(search.name),
+ *         items: await db.findUsers(search.name, limit, offset)
+ *     }))
+ * }
+ * ```
+ */
+export async function paginator(options, handler) {
+    const result = await handler(options.limit, options.offset, options);
+    return {
+        items: result.items,
+        meta: {
+            count: result.items.length,
+            total: result.total,
+            limit: options.limit,
+            offset: options.offset
+        }
+    };
+}

package/dist/esm/exceptions/DestroyRuntimeContainerException.js

@@ -0,0 +1,13 @@
+import { Exception } from '../lib/foundation/Exception.js';
+/**
+ * A failure to destroy the application's root container, in 2.x. Its errno is `E_DESTROY_RUNTIME_CONTAINER`.
+ * @deprecated Never thrown since 3.0: the errors of the teardown of the objects are reported to the application's
+ * logger, and `Application.exit()` ends the process with the code 1 when the teardown fails. Kept for the code
+ * catching it; it will be removed.
+ */
+export class DestroyRuntimeContainerException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_DESTROY_RUNTIME_CONTAINER';
+    }
+}

package/dist/esm/exceptions/InvalidActionPatternDepthException.js

@@ -0,0 +1,11 @@
+import { Exception } from '../lib/foundation/Exception.js';
+/**
+ * Thrown when the pattern of a service action (`@ServiceAction`) nests objects more than 2 levels deep.
+ * Its errno is `E_INVALID_ACTION_PATTERN_DEPTH`.
+ */
+export class InvalidActionPatternDepthException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_INVALID_ACTION_PATTERN_DEPTH';
+    }
+}

package/dist/esm/exceptions/InvalidAssistantFunctionTypeException.js

@@ -0,0 +1,12 @@
+import { Exception } from '../lib/foundation/Exception.js';
+/**
+ * Thrown when a `@Before` or `@After` decorator is applied to a member which is not a method, or gives an
+ * async function to a method which is not async. Thrown when the class is defined. Its errno is
+ * `E_INVALID_ASSISTANT_FUNCTION_TYPE`.
+ */
+export class InvalidAssistantFunctionTypeException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_INVALID_ASSISTANT_FUNCTION_TYPE';
+    }
+}

package/dist/esm/exceptions/InvalidObjectTypeException.js

@@ -0,0 +1,12 @@
+import { Exception } from '../lib/foundation/Exception.js';
+/**
+ * Thrown when an object is declared in the wrong module option (a provider in `components`, a module in
+ * `providers`…); its message names the right option. It fails the module's initialization. Its errno is
+ * `E_INVALID_OBJECT_TYPE`.
+ */
+export class InvalidObjectTypeException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_INVALID_OBJECT_TYPE';
+    }
+}

package/dist/esm/exceptions/MethodNotFoundException.js

@@ -0,0 +1,11 @@
+import { Exception } from '../lib/foundation/Exception.js';
+/**
+ * Thrown by `getMethod(name, true)` when the object has no method of this name. Its errno is
+ * `E_METHOD_NOT_FOUND`.
+ */
+export class MethodNotFoundException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_METHOD_NOT_FOUND';
+    }
+}

package/dist/esm/exceptions/ObjectDestroyedException.js

@@ -0,0 +1,12 @@
+import { Exception } from '../lib/foundation/Exception.js';
+/**
+ * Thrown when a destroyed (or being destroyed) object or container is used: `getObject()`,
+ * `buildObject()`, `createScope()`, `load()`, `get()`, or an initialization which a teardown interrupted. Its errno is
+ * `E_OBJECT_DESTROYED`.
+ */
+export class ObjectDestroyedException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_OBJECT_DESTROYED';
+    }
+}

package/dist/esm/exceptions/alias/AliasExistsException.js

@@ -0,0 +1,11 @@
+import { Exception } from '../../lib/foundation/Exception.js';
+/**
+ * Thrown when a path alias is registered twice without override (`Application.alias()` declaring an alias
+ * already registered, which fails the launch). Its errno is `E_ALIAS_EXISTS`.
+ */
+export class AliasExistsException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_ALIAS_EXISTS';
+    }
+}

package/dist/esm/exceptions/alias/AliasNotFoundException.js

@@ -0,0 +1,11 @@
+import { Exception } from '../../lib/foundation/Exception.js';
+/**
+ * Thrown when a path alias is read (`app.alias.get()`) without being registered. Its errno is
+ * `E_ALIAS_NOT_FOUND`.
+ */
+export class AliasNotFoundException extends Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_ALIAS_NOT_FOUND';
+    }
+}