Lakutata

English

简体中文

English

简体中文

Appearance

Class: ContainerCreateOptions ​

The settings of a container created by Containerd.createContainer: its image, its process, its mounts, its networks, its resources and its security. Only image is required; the container is created stopped (start() it) as a nerdctl container (nerdctl ps lists it), with an OCI runtime specification built as nerdctl builds it. The component keeps these settings: ContainerdContainer.update creates the container again with the ones it changes.

As with the Docker component, the container joins the default network bridge unless network or networks is given (here a CNI network, the CNI plugins needed); its ports are published only on a CNI network, and its named volumes are directories the component keeps (not Docker's nor nerdctl's volumes).

Example ​

typescript
import {Containerd} from 'lakutata/com/containerd'

declare const containerd: Containerd

await containerd.pullImage({image: 'nginx:1.27'})
const container = await containerd.createContainer({
    image: 'nginx:1.27',
    name: 'web',
    env: {NGINX_PORT: '80'},
    binds: [{hostPath: '/srv/www', containerPath: '/usr/share/nginx/html', rw: false}],
    volumes: [{volumeName: 'web-cache', containerPath: '/var/cache/nginx'}],
    //The default nerdctl network, its port 80 published on the host port 8080
    networks: [{networkName: 'bridge'}],
    ports: [{port: 80, hostPorts: [8080]}],
    memoryLimit: 256 * 1024 * 1024,
    cpus: 0.5,
    restartPolicy: 'unless-stopped'
})
await container.start()

Extends ​

Indexable ​

[prop: string | symbol]: any

Constructors ​

Constructor ​

new ContainerCreateOptions(props?): ContainerCreateOptions

Create a DTO from its data, validated against the class schema: the defaults applied, the keys without schema removed (unless the class has an @IndexSignature). The instance then validates each change of a property, or of a value nested in it (an array, an object): an invalid change throws an InvalidValueException and is undone.

Parameters ​

props? ​

Record<string, any>

The data of the DTO. Default: no data ({}).

Returns ​

ContainerCreateOptions

Throws ​

When the data does not match the class schema.

Inherited from ​

DTO.constructor

Properties ​

binds? ​

optional binds?: ContainerdBind[]

The host directories and files mounted into the container. Each needs hostPath and containerPath; rw defaults to true, propagation to 'rprivate'.

capabilities? ​

optional capabilities?: string[]

The Linux capabilities added to the default ones (the 14 Docker gives: CHOWN, DAC_OVERRIDE, FSETID, FOWNER, MKNOD, NET_RAW, SETGID, SETUID, SETFCAP, SETPCAP, NET_BIND_SERVICE, SYS_CHROOT, KILL, AUDIT_WRITE), with or without the CAP_ prefix, in any case ('NET_ADMIN', 'cap_sys_time'); 'ALL' adds them all. Added after capabilitiesDrop is applied. Unlike the Docker component, the names are not checked against a list.

capabilitiesDrop? ​

optional capabilitiesDrop?: string[]

The Linux capabilities removed from the default ones, with or without the CAP_ prefix ('NET_RAW'); 'ALL' removes them all, before capabilities adds its ones.

cgroupns? ​

optional cgroupns?: "private" | "host"

The cgroup namespace: 'private', one of its own (its cgroup seen as the root of its /sys/fs/cgroup), applied on cgroup v2 hosts only; 'host', the host's one.

Default ​

ts
'private'

cmd? ​

optional cmd?: string[]

The command of the container, its arguments (['nginx', '-g', 'daemon off;']), run after the entry point. The image's command by default; dropped when entrypoint is given without it (as Docker does).

cpus? ​

optional cpus?: number

The CPUs the container uses at most, a positive number (1.5): a CFS quota of cpus × 100000 µs per period of 100000 µs. No limit by default.

cpuSet? ​

optional cpuSet?: number[]

The CPUs the container may run on, by their numbers ([0, 1]); all of them by default.

cpuShares? ​

optional cpuShares?: number

The relative CPU weight of the container against the others when the CPUs are busy, in cgroup v1 CPU shares (1024 is the kernel's default; runc converts them to a cpu.weight on cgroup v2). A positive integer; the kernel's default when not given.

deviceCgroupRules? ​

optional deviceCgroupRules?: string[]

The devices the container's cgroup allows besides the ones given, as Docker's --device-cgroup-rule writes them: a type (c character, b block, a all), the major and minor numbers or *, the access (one to three of r, w, m, each at most once): "c 188:* rwm" for the USB serial ports. They let the container use the devices plugged after its start, with a bind of /dev (or of /dev/serial, /dev/bus/usb).

devices? ​

optional devices?: ContainerdDevice[]

The host devices given to the container (ContainerdDevice): a device node, or a directory of them. Each needs hostPath; cgroupPermissions is one to three of r, w and m, each at most once, in any order ('rw', 'mr'), 'rwm' by default.

dns? ​

optional dns?: string[]

The IP addresses of the name servers of the container's /etc/resolv.conf, replacing the host's. By default, the host's /etc/resolv.conf, without its loopback name servers outside the host network (and with 8.8.8.8 and 8.8.4.4 when none is left, as Docker does).

entrypoint? ​

optional entrypoint?: string[]

The entry point of the container, its arguments, replacing the image's; [''] removes the image's entry point. The image's entry point by default. A container left with neither an entry point nor a command fails to be created.

env? ​

optional env?: Record<string, string>

The environment variables of the container, added to the image's ones (and replacing them by name). The container also gets HOSTNAME, and PATH and HOME (the user's home directory) when the image has none.

extraHosts? ​

optional extraHosts?: Record<string, string>

The host names added to the container's /etc/hosts, each mapped to an IP address ({'db.local': '10.4.1.5'}).

hostname? ​

optional hostname?: string

The host name of the container, written to its /etc/hostname and its HOSTNAME variable. By default, the host's name on the host network, the first 12 digits of the container ID otherwise.

image ​

image: string

The image of the container: its name or a reference ('alpine:3.20', 'docker.io/library/alpine:3.20', 'registry.example.com/app@sha256:…'). Required. The image must be in containerd already (pull, import or build it first): a missing one throws ContainerdImageNotFoundException.

ipcMode? ​

optional ipcMode?: "host"

'host' shares the host's IPC namespace (its shared memory and message queues); a namespace of its own when not given.

labels? ​

optional labels?: Record<string, string>

The labels of the container, added to the image's ones; the ones the component sets (nerdctl/…, containerd.io/restart.…) cannot be overridden. Containerd.listContainers filters by them.

memoryLimit? ​

optional memoryLimit?: number

The memory limit in bytes, a non-negative integer; 0 or absent for no limit. With it, the swap is limited too (see memorySwap).

memorySwap? ​

optional memorySwap?: number

The limit of the memory and the swap together in bytes, as Docker's and nerdctl's --memory-swap: at least memoryLimit (equal to it, no swap), or -1 for unlimited swap. 0 or absent with memoryLimit: twice memoryLimit (as much swap as memory). A positive value needs memoryLimit: without it, the options are refused. Discarded when the kernel does not limit the swap of the cgroups (as Docker discards it).

name? ​

optional name?: string

The name of the container, matching [a-zA-Z0-9][a-zA-Z0-9_.-]* and unique in the namespace (a name in use throws ContainerdContainerNameConflictException). By default, the last part of the image name and the first 5 hexadecimal digits of the container ID ('nginx-3fa2c').

network? ​

optional network?: "host" | "none"

The network of a container without networks: 'host', the host's network stack, or 'none', a network namespace with only its loopback. Ignored when networks is given. Without both, the container joins the default CNI network bridge, as with Docker and nerdctl (its ports published there; the CNI plugins needed).

Default ​

the network bridge

networks? ​

optional networks?: object[]

The CNI networks the container joins, in order (its interfaces eth0, eth1…): 'bridge', the default nerdctl network (10.4.0.0/24, created when first used), or one created by Containerd.createNetwork. Each needs networkName, of an existing network other than host and none (a missing one throws ContainerdNetworkNotFoundException), given once; ip and ipv6 set its address on the network ('' or absent: one given by the network's IPAM). Requires the CNI plugins in the component's cniPath.

ip? ​

optional ip?: string

ipv6? ​

optional ipv6?: string

networkName ​

networkName: string

OOMKillDisable? ​

optional OOMKillDisable?: boolean

Disable the kernel's OOM killer for the container: its processes wait for memory instead of being killed at its memory limit. Supported on cgroup v1 only.

Default ​

ts
false

pidMode? ​

optional pidMode?: "host"

'host' shares the host's PID namespace (the container sees the host processes); a namespace of its own when not given.

pidsLimit? ​

optional pidsLimit?: number

The processes (and threads) the container may have at most, a positive integer; no limit by default.

platform? ​

optional platform?: string

The platform of the image run ('linux/amd64', 'linux/arm/v7', or 'arm64' for linux/arm64), pulled beforehand; another architecture than the machine's needs a QEMU emulator registered in binfmt_misc (Containerd.supportedPlatforms). The machine's platform by default; an image without it throws ContainerdPlatformException.

ports? ​

optional ports?: object[]

The container ports published on the host, by the CNI portmap plugin on its first network: it needs networks (ports on the host or none network fail the creation). Each needs port, the container port, and hostPorts, one or more host ports forwarding to it; type is 'tcp' (the default), 'udp' or 'sctp'; hostIP limits them to one host address (all of them by default). Unlike the Docker component, hostPorts is required and type is optional.

hostIP? ​

optional hostIP?: string

hostPorts ​

hostPorts: number[]

port ​

port: number

type? ​

optional type?: "tcp" | "udp" | "sctp"

privileged? ​

optional privileged?: boolean

Give the container all the capabilities, access to every device by its cgroup, the host's devices in its /dev (the character and block devices of the host's /dev when the container is created, as nerdctl gives them; a device plugged later needs a bind of /dev), /sys and /sys/fs/cgroup writable, no masked paths, no seccomp filter and no no_new_privs.

Default ​

ts
false

readonlyRootfs? ​

optional readonlyRootfs?: boolean

Mount the container's root file system read only (its mounts, tmpfs and volumes stay writable).

Default ​

ts
false

restartPolicy? ​

optional restartPolicy?: ContainerdRestartPolicy

The restart policy, applied by containerd's restart monitor (ContainerdRestartPolicy): '' or 'no', 'always', 'unless-stopped', 'on-failure', 'on-failure:N'. Never restarted by default.

seccompProfile? ​

optional seccompProfile?: string

The seccomp profile filtering the system calls of the container: 'default', the default profile of containerd and nerdctl (the system calls allowed by the container's capabilities), applied when the kernel supports seccomp; 'unconfined', no filter; or the path of a JSON file holding an OCI seccomp profile (the linux.seccomp object of a runtime specification), read when the container is created. Privileged containers have no filter.

Default ​

ts
'default'

shmSize? ​

optional shmSize?: number

The size of the container's /dev/shm in bytes, a positive integer.

Default ​

ts
67108864

stopSignal? ​

optional stopSignal?: string

The signal stop() sends first ('SIGTERM', 'SIGQUIT', 'TERM', '15'); the image's stop signal by default, SIGTERM without it.

sysctls? ​

optional sysctls?: Record<string, string>

The kernel parameters set in the container's namespaces ({'net.ipv4.ip_forward': '1'}); runc accepts only the namespaced ones (net.* outside the host network, kernel.shm*, kernel.msg*, fs.mqueue.*…).

tmpfs? ​

optional tmpfs?: ContainerdTmpfs[]

The tmpfs mounted into the container (ContainerdTmpfs). Each needs containerPath; size is a positive integer of bytes, mode three or four octal digits.

user? ​

optional user?: string

The user of the container's process: 'user', 'user:group', 'uid' or 'uid:gid', the names resolved by the image's /etc/passwd and /etc/group. The image's user by default, root without it.

volumes? ​

optional volumes?: ContainerdVolume[]

The named volumes mounted into the container, created empty when they do not exist (ContainerdVolume). Each needs volumeName ([a-zA-Z0-9][a-zA-Z0-9_.-]*) and containerPath.

workingDir? ​

optional workingDir?: string

The working directory of the container's process; the image's one by default, / without it.

Methods ​

Alternatives() ​

static Alternatives<TSchema>(...types): AlternativesSchema<TSchema>

Build a schema matching a value against several schemas, in order: the first one matching validates it.

Type Parameters ​

TSchema ​

TSchema = any

Parameters ​

types ​

...SchemaLike[]

The schemas tried in order.

Returns ​

AlternativesSchema<TSchema>

A new alternatives schema.

Inherited from ​

DTO.Alternatives

Any() ​

static Any<TSchema>(): AnySchema<TSchema>

Build a schema accepting any value (undefined included unless marked required()).

Type Parameters ​

TSchema ​

TSchema = any

Returns ​

AnySchema<TSchema>

A new schema.

Inherited from ​

DTO.Any

Array() ​

static Array<TSchema>(...types): ArraySchema<TSchema>

Build a schema of arrays whose items match one of the schemas given; strict.

Type Parameters ​

TSchema ​

TSchema = any[]

Parameters ​

types ​

...SchemaLikeWithoutArray[]

The schemas an item may match. Default: any item.

Returns ​

ArraySchema<TSchema>

A new array schema.

Inherited from ​

DTO.Array

AsyncFunction() ​

static AsyncFunction<TSchema>(): FunctionSchema<TSchema>

Build a schema of async functions (declared async); a function which only returns a promise is rejected.

Type Parameters ​

TSchema ​

TSchema = Function

Returns ​

FunctionSchema<TSchema>

A new function schema.

Inherited from ​

DTO.AsyncFunction

Attempt() ​

static Attempt<TSchema>(value, schema, options?): TSchema extends Schema<Value> ? Value : never

Validate a value against a schema and return the validated value. Unlike DTO.validate(), the default options of lakutata are not applied: an unknown key is rejected, not removed.

Type Parameters ​

TSchema ​

TSchema extends Schema

Parameters ​

value ​

any

The value to validate.

schema ​

TSchema

The schema to validate against.

options? ​

ValidationOptions

The validation options.

Returns ​

TSchema extends Schema<Value> ? Value : never

The validated value.

Throws ​

When the value does not match the schema.

Inherited from ​

DTO.Attempt

BigInt() ​

static BigInt<TSchema>(): BigIntSchema<TSchema>

Build a schema of bigints; strict: a value of another type is rejected, not converted.

Type Parameters ​

TSchema ​

TSchema = bigint

Returns ​

BigIntSchema<TSchema>

A new bigint schema.

Inherited from ​

DTO.BigInt

Binary() ​

static Binary<TSchema>(): BinarySchema<TSchema>

Build a schema of Buffers; strict: a value of another type is rejected, not converted.

Type Parameters ​

TSchema ​

TSchema = Buffer<ArrayBufferLike>

Returns ​

BinarySchema<TSchema>

A new binary schema.

Inherited from ​

DTO.Binary

Boolean() ​

static Boolean<TSchema>(): BooleanSchema<TSchema>

Build a schema of booleans; strict: a value of another type is rejected, not converted (the string 'true' is not a boolean).

Type Parameters ​

TSchema ​

TSchema = boolean

Returns ​

BooleanSchema<TSchema>

A new boolean schema.

Inherited from ​

DTO.Boolean

Build() ​

static Build<TSchema>(description): Schema<TSchema>

Rebuild a schema from its description (the output of schema.describe()), exactly.

Type Parameters ​

TSchema ​

TSchema = any

Parameters ​

description ​

Description

The description of the schema.

Returns ​

Schema<TSchema>

The schema.

Inherited from ​

DTO.Build

Class() ​

static Class<TSchema>(inheritsFrom?): FunctionSchema<TSchema>

Build a schema of classes, optionally of the subclasses of a class.

Type Parameters ​

TSchema ​

TSchema = Function

Parameters ​

inheritsFrom? ​

TSchema | (() => TSchema)

The class the value must be or extend, or a function returning it (for a class declared later). Default: any class.

Returns ​

FunctionSchema<TSchema>

A new function schema.

Inherited from ​

DTO.Class

Cron() ​

static Cron<TSchema>(options?): StringSchema<TSchema>

Build a schema of cron expression strings. The options not given default to: seconds allowed (6 fields), ? allowed for a day, 7 accepted as Sunday, no aliases (@daily).

Type Parameters ​

TSchema ​

TSchema = string

Parameters ​

options? ​

CronOptions

The cron syntax accepted.

Returns ​

StringSchema<TSchema>

A new string schema.

Inherited from ​

DTO.Cron

Date() ​

static Date<TSchema>(): DateSchema<TSchema>

Build a schema of Date objects; strict: a value of another type is rejected, not converted (a date string or a timestamp is not a date).

Type Parameters ​

TSchema ​

TSchema = Date

Returns ​

DateSchema<TSchema>

A new date schema.

Inherited from ​

DTO.Date

description() ​

static description(desc): typeof DTO

Set the description of the class schema, written into its JSON Schema and its descriptions. The description is not inherited by the subclasses.

Parameters ​

desc ​

string

The description.

Returns ​

typeof DTO

The class itself, for chaining.

Inherited from ​

DTO.description

fromJsonSchema() ​

static fromJsonSchema<T>(this, schema, options?): T

Create a DTO class (a subclass of the current DTO class) from an object JSON Schema (or an OpenAPI schema object), validating like JSON Schema: its properties become the properties of the DTO, its other keywords (unknown keys, pattern properties, key counts, dependencies, subschemas) constrain the whole object.

Type Parameters ​

T ​

T extends typeof DTO

Parameters ​

this ​

T

schema ​

JSONSchema

The JSON Schema of an object (or an OpenAPI schema object), or a reference ($ref) to one.

options? ​

FromJsonSchemaOptions & object

The version of the JSON Schema, where its references are resolved, whether the values are converted, and the name of the class. Default name: the title of the JSON Schema, else the current class name followed by FromJsonSchema.

Returns ​

T

The new DTO class.

Throws ​

When the JSON Schema does not describe objects, a reference cannot be resolved, or a pattern is not a valid regular expression.

Inherited from ​

DTO.fromJsonSchema

fromOpenAPI() ​

static fromOpenAPI<T>(this, document, options?): Record<string, T>

Create the DTO classes of the object schemas of an OpenAPI document (its components.schemas), by name; the references between the schemas are resolved in the document. The schemas which do not describe objects are skipped.

Type Parameters ​

T ​

T extends typeof DTO

Parameters ​

this ​

T

document ​

Record<string, unknown>

The OpenAPI 3.0 or 3.1 document.

options? ​

Omit<FromJsonSchemaOptions, "document">

How the JSON Schemas are read. Default dialect: the version of the document's openapi field.

Returns ​

Record<string, T>

The DTO classes, by the names of their schemas.

Throws ​

When the document has no components.schemas, or a schema cannot be converted.

Inherited from ​

DTO.fromOpenAPI

Function() ​

static Function<TSchema>(): FunctionSchema<TSchema>

Build a schema of functions; strict.

Type Parameters ​

TSchema ​

TSchema = Function

Returns ​

FunctionSchema<TSchema>

A new function schema.

Inherited from ​

DTO.Function

Glob() ​

static Glob<TSchema>(): StringSchema<TSchema>

Build a schema of glob pattern strings (*.ts, src/**).

Type Parameters ​

TSchema ​

TSchema = string

Returns ​

StringSchema<TSchema>

A new string schema.

Inherited from ​

DTO.Glob

HttpDocument() ​

static HttpDocument<TSchema>(): StringSchema<TSchema>

Build a schema of HTML or XML document strings.

Type Parameters ​

TSchema ​

TSchema = string

Returns ​

StringSchema<TSchema>

A new string schema.

Inherited from ​

DTO.HttpDocument

In() ​

static In(ref, options?): Reference

Create a reference to an array of the validated object, whose items are the values allowed, for valid() or invalid().

Parameters ​

ref ​

string

The path of the referenced array.

options? ​

ReferenceOptions

How the reference is resolved.

Returns ​

Reference

The reference.

Inherited from ​

DTO.In

InstanceOf() ​

static InstanceOf<TSchema>(constructor): AnySchema<TSchema>

Build a schema of the instances of a class (the instances of its subclasses included).

Type Parameters ​

TSchema ​

TSchema = Function

Parameters ​

constructor ​

TSchema

The class.

Returns ​

AnySchema<TSchema>

A new schema.

Inherited from ​

DTO.InstanceOf

isValid() ​

Call Signature ​

static isValid<T>(data): boolean

Check whether a value matches a schema (the class schema when none is given), without throwing.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

Returns ​

boolean

true when the value matches the schema, else false.

Inherited from ​

DTO.isValid

Call Signature ​

static isValid<T>(data, options): boolean

Check whether a value matches a schema (the class schema when none is given), without throwing.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

boolean

true when the value matches the schema, else false.

Inherited from ​

DTO.isValid

Call Signature ​

static isValid<T>(data, schema): boolean

Check whether a value matches a schema (the class schema when none is given), without throwing.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

Returns ​

boolean

true when the value matches the schema, else false.

Inherited from ​

DTO.isValid

Call Signature ​

static isValid<T>(data, schema, options): boolean

Check whether a value matches a schema (the class schema when none is given), without throwing.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

boolean

true when the value matches the schema, else false.

Inherited from ​

DTO.isValid

isValidAsync() ​

Call Signature ​

static isValidAsync<T>(data): Promise<boolean>

Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

Returns ​

Promise<boolean>

A promise of true when the value matches the schema, else false.

Inherited from ​

DTO.isValidAsync

Call Signature ​

static isValidAsync<T>(data, options): Promise<boolean>

Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

Promise<boolean>

A promise of true when the value matches the schema, else false.

Inherited from ​

DTO.isValidAsync

Call Signature ​

static isValidAsync<T>(data, schema): Promise<boolean>

Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

Returns ​

Promise<boolean>

A promise of true when the value matches the schema, else false.

Inherited from ​

DTO.isValidAsync

Call Signature ​

static isValidAsync<T>(data, schema, options): Promise<boolean>

Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

Promise<boolean>

A promise of true when the value matches the schema, else false.

Inherited from ​

DTO.isValidAsync

static Link<TSchema>(ref): LinkSchema<TSchema>

Build a schema linking to another schema of the same tree, for the recursive structures (a tree of nodes): #id for the schema given that id, / for the root, ... for an ancestor.

Type Parameters ​

TSchema ​

TSchema extends Schema

Parameters ​

ref ​

string

The path of the linked schema.

Returns ​

LinkSchema<TSchema>

A new link schema.

Inherited from ​

DTO.Link

Number() ​

static Number<TSchema>(): NumberSchema<TSchema>

Build a schema of numbers; strict: a value of another type is rejected, not converted (the string '5' is not the number 5).

Type Parameters ​

TSchema ​

TSchema = number

Returns ​

NumberSchema<TSchema>

A new number schema.

Inherited from ​

DTO.Number

Object() ​

static Object<TSchema, isStrict, T>(schema?): ObjectSchema<TSchema>

Build a schema of objects, with the schemas of their keys; strict. With the default validation options, the keys without schema are removed.

Type Parameters ​

TSchema ​

TSchema = any

isStrict ​

isStrict = false

T ​

T = TSchema

Parameters ​

schema? ​

SchemaMap<T, isStrict>

The schemas of the keys, by key. Default: no key declared.

Returns ​

ObjectSchema<TSchema>

A new object schema.

Inherited from ​

DTO.Object

optional() ​

static optional(): ObjectSchema

Get the class schema marked as optional: undefined is accepted (as by Schema()).

Returns ​

ObjectSchema

A new object schema.

Inherited from ​

DTO.optional

options() ​

static options(options): ObjectSchema

Get the class schema with its own validation options, which override the options of the validation for the object and its nested values.

Parameters ​

options ​

ValidationOptions

The validation options.

Returns ​

ObjectSchema

A new object schema.

Inherited from ​

DTO.options

Ref() ​

static Ref(key, options?): Reference

Create a reference to another value of the validated object (a sibling key by default), resolved at validation, for the rules comparing values (DTO.Number().greater(DTO.Ref('min'))).

Parameters ​

key ​

string

The path of the referenced value: a key, a.b for a nested key, /key from the root.

options? ​

ReferenceOptions

How the reference is resolved.

Returns ​

Reference

The reference.

Inherited from ​

DTO.Ref

required() ​

static required(): ObjectSchema

Get the class schema marked as required: undefined is rejected.

Returns ​

ObjectSchema

A new object schema.

Inherited from ​

DTO.required

Schema() ​

static Schema(): ObjectSchema

Get the class schema: an object schema of the properties declared with @Expect (the parents' included), with the @IndexSignature and the description of the class. The schema is optional (it accepts undefined): use required() for a required one.

Returns ​

ObjectSchema

The object schema; the same instance until a schema declaration changes.

Inherited from ​

DTO.Schema

String() ​

static String<TSchema>(): StringSchema<TSchema>

Build a schema of strings; strict: a value of another type is rejected, not converted.

Type Parameters ​

TSchema ​

TSchema = string

Returns ​

StringSchema<TSchema>

A new string schema.

Inherited from ​

DTO.String

Symbol() ​

static Symbol<TSchema>(): SymbolSchema<TSchema>

Build a schema of symbols; strict.

Type Parameters ​

TSchema ​

TSchema = Symbol

Returns ​

SymbolSchema<TSchema>

A new symbol schema.

Inherited from ​

DTO.Symbol

toJsonSchema() ​

static toJsonSchema(version?, options?): JSONSchema

Convert the class schema to a JSON Schema, for an API document or another validator. What JSON Schema cannot express (custom rules, references to other values) is dropped, so the JSON Schema may accept more values, never less.

Parameters ​

version? ​

"draft-2020-12" | "draft-2019-09" | "draft-07" | "draft-04"

The JSON Schema version to write. Default 'draft-2020-12'.

options? ​

Omit<ToJsonSchemaOptions, "target">

The validation options the schema is used with, whether $schema is written, and the object receiving the shared schemas. Default: no option ({}).

Returns ​

JSONSchema

A new JSON Schema.

Throws ​

When the version is unknown.

Inherited from ​

DTO.toJsonSchema

toOpenAPIJsonSchema() ​

static toOpenAPIJsonSchema(version?, options?): JSONSchema

Convert the class schema to an OpenAPI schema object, for the components.schemas of an OpenAPI document.

Parameters ​

version? ​

"3.0" | "3.1"

The OpenAPI version: '3.0' or '3.1'. Default '3.1'.

options? ​

Omit<ToJsonSchemaOptions, "target" | "dialect">

The validation options the schema is used with, and the object receiving the shared schemas. Default: no option ({}).

Returns ​

JSONSchema

A new OpenAPI schema object.

Inherited from ​

DTO.toOpenAPIJsonSchema

validate() ​

Call Signature ​

static validate<T>(data): T

Validate a value against a schema (the class schema when none is given).

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

Returns ​

T

The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (its cause holds the details).

Inherited from ​

DTO.validate

Call Signature ​

static validate<T>(data, options): T

Validate a value against a schema (the class schema when none is given).

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

T

The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (its cause holds the details).

Inherited from ​

DTO.validate

Call Signature ​

static validate<T>(data, schema): T

Validate a value against a schema (the class schema when none is given).

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

Returns ​

T

The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (its cause holds the details).

Inherited from ​

DTO.validate

Call Signature ​

static validate<T>(data, schema, options): T

Validate a value against a schema (the class schema when none is given).

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

T

The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (its cause holds the details).

Inherited from ​

DTO.validate

validateAsync() ​

Call Signature ​

static validateAsync<T>(data): Promise<T>

Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

Returns ​

Promise<T>

A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (the promise rejects; its cause holds the details).

Inherited from ​

DTO.validateAsync

Call Signature ​

static validateAsync<T>(data, options): Promise<T>

Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

Promise<T>

A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (the promise rejects; its cause holds the details).

Inherited from ​

DTO.validateAsync

Call Signature ​

static validateAsync<T>(data, schema): Promise<T>

Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

Returns ​

Promise<T>

A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (the promise rejects; its cause holds the details).

Inherited from ​

DTO.validateAsync

Call Signature ​

static validateAsync<T>(data, schema, options): Promise<T>

Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.

Type Parameters ​
T ​

T = any

Parameters ​
data ​

T

The value to check.

schema ​

Schema

The schema to check against, instead of the class schema.

options ​

ValidationOptions

The validation options, merged with the defaults (unknown keys removed, the first error only).

Returns ​

Promise<T>

A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).

Throws ​

When the value does not match the schema (the promise rejects; its cause holds the details).

Inherited from ​

DTO.validateAsync

Released under the MIT License.

Copyright © 2023-present Lakutata