@lakutata/core 1.0.59 → 3.0.0-beta.0

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

@@ -0,0 +1,94 @@
+import { BaseObject } from '../../lib/base/BaseObject.js';
+import { ClassDecorator } from '../../types/ClassDecorator.js';
+import { LifetimeType } from '../../lib/ioc/Lifetime.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 declare function Lifetime<ClassConstructor extends typeof BaseObject>(lifetime: LifetimeType, lock?: boolean): ClassDecorator<ClassConstructor>;
+/**
+ * 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 declare function Singleton<ClassConstructor extends typeof BaseObject>(lock?: boolean): ClassDecorator<ClassConstructor>;
+/**
+ * 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 declare function Transient<ClassConstructor extends typeof BaseObject>(lock?: boolean): ClassDecorator<ClassConstructor>;
+/**
+ * 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 declare function Scoped<ClassConstructor extends typeof BaseObject>(lock?: boolean): ClassDecorator<ClassConstructor>;

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

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lifetime = Lifetime;
+exports.Singleton = Singleton;
+exports.Transient = Transient;
+exports.Scoped = Scoped;
+const ObjectLifetime_js_1 = require("../../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
+ * }
+ * ```
+ */
+function Lifetime(lifetime, lock = false) {
+    return (target) => (0, ObjectLifetime_js_1.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()
+ * }
+ * ```
+ */
+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
+ *     }
+ * }
+ * ```
+ */
+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()
+ * }
+ * ```
+ */
+function Scoped(lock = false) {
+    return Lifetime('SCOPED', lock);
+}

package/dist/cjs/decorators/dto/Accept.d.ts

@@ -0,0 +1,38 @@
+import { DTO } from '../../lib/dto/DTO.js';
+import { MethodDecorator } from '../../types/MethodDecorator.js';
+import { Schema } from '../../lib/validation/types/Schema.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 declare function Accept<ClassPrototype, DTOConstructor extends typeof DTO, Method>(...defs: (DTOConstructor | Schema)[]): MethodDecorator<ClassPrototype, Method>;

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

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Accept = Accept;
+const MethodValidation_js_1 = require("../../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)
+ *     }
+ * }
+ * ```
+ */
+function Accept(...defs) {
+    return (target, propertyKey, descriptor) => (0, MethodValidation_js_1.setMethodAcceptArgumentsValidator)(target, propertyKey, descriptor, defs);
+}

package/dist/cjs/decorators/dto/Expect.d.ts

@@ -0,0 +1,38 @@
+import { DTO } from '../../lib/dto/DTO.js';
+import { PropertyDecorator } from '../../types/PropertyDecorator.js';
+import { Schema } from '../../lib/validation/types/Schema.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 declare function Expect<ClassPrototype extends DTO>(schema: Schema): PropertyDecorator<ClassPrototype>;

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

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Expect = Expect;
+const ObjectSchemaValidation_js_1 = require("../../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'
+ * ```
+ */
+function Expect(schema) {
+    return (target, propertyKey) => (0, ObjectSchemaValidation_js_1.setObjectPropertySchema)(target, propertyKey, schema);
+}

package/dist/cjs/decorators/dto/IndexSignature.d.ts

@@ -0,0 +1,30 @@
+import { DTO } from '../../lib/dto/DTO.js';
+import { ClassDecorator } from '../../types/ClassDecorator.js';
+import { Schema } from '../../lib/validation/types/Schema.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 declare function IndexSignature<ClassConstructor extends typeof DTO>(schema: Schema): ClassDecorator<ClassConstructor>;

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexSignature = IndexSignature;
+const ObjectSchemaValidation_js_1 = require("../../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)
+ * ```
+ */
+function IndexSignature(schema) {
+    return (target) => (0, ObjectSchemaValidation_js_1.setObjectIndexSignatureSchema)(target, schema);
+}

package/dist/cjs/decorators/dto/Return.d.ts

@@ -0,0 +1,39 @@
+import { DTO } from '../../lib/dto/DTO.js';
+import { MethodDecorator } from '../../types/MethodDecorator.js';
+import { Schema } from '../../lib/validation/types/Schema.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 declare function Return<ClassPrototype, DTOConstructor extends typeof DTO, Method>(def: DTOConstructor | Schema): MethodDecorator<ClassPrototype, Method>;

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Return = Return;
+const MethodValidation_js_1 = require("../../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)
+ *     }
+ * }
+ * ```
+ */
+function Return(def) {
+    return (target, propertyKey, descriptor) => (0, MethodValidation_js_1.setMethodReturnValueValidator)(target, propertyKey, descriptor, def);
+}

package/dist/cjs/dto/PaginationResultDTO.d.ts

@@ -0,0 +1,33 @@
+import { DTO } from '../lib/dto/DTO.js';
+import { type PaginationMeta } from '../types/PaginationMeta.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 declare class PaginationResultDTO<T = any, U = T[]> extends DTO {
+    /**
+     * The items of the page (an array; its items are not validated).
+     */
+    items: U;
+    /**
+     * Where the page is: `count` the number of items of the page, `total` the number of items of the whole result,
+     * `limit` and `offset` those of the search. All integers, 0 or more.
+     */
+    meta: PaginationMeta;
+}

package/dist/cjs/dto/PaginationResultDTO.js

@@ -0,0 +1,50 @@
+"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.PaginationResultDTO = void 0;
+const DTO_js_1 = require("../lib/dto/DTO.js");
+const Expect_js_1 = require("../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}}
+ *     }
+ * }
+ * ```
+ */
+class PaginationResultDTO extends DTO_js_1.DTO {
+}
+exports.PaginationResultDTO = PaginationResultDTO;
+__decorate([
+    (0, Expect_js_1.Expect)(DTO_js_1.DTO.Array(DTO_js_1.DTO.Any()).required()),
+    __metadata("design:type", Object)
+], PaginationResultDTO.prototype, "items", void 0);
+__decorate([
+    (0, Expect_js_1.Expect)(DTO_js_1.DTO.Object({
+        count: DTO_js_1.DTO.Number().integer().positive().allow(0).required(),
+        total: DTO_js_1.DTO.Number().integer().positive().allow(0).required(),
+        limit: DTO_js_1.DTO.Number().integer().positive().allow(0).required(),
+        offset: DTO_js_1.DTO.Number().integer().positive().allow(0).required()
+    }).required()),
+    __metadata("design:type", Object)
+], PaginationResultDTO.prototype, "meta", void 0);

package/dist/cjs/dto/PaginationSearchDTO.d.ts

@@ -0,0 +1,33 @@
+import { DTO } from '../lib/dto/DTO.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 declare class PaginationSearchDTO extends DTO {
+    /**
+     * The maximum number of items to return: an integer, 0 or more.
+     * @default 10
+     */
+    limit?: number;
+    /**
+     * The number of items to skip before the first one returned: an integer, 0 or more.
+     * @default 0
+     */
+    offset?: number;
+}