npm package: @huncyrus/simple-validated-dto
Description: Simple Validated DTO class for JavaScript projects, using Zod for schema validation and deep-freezing data to ensure immutability.
Author: Györk Bakonyi
Latest version: 1.0.2

# Simple Validated DTO

A self-closing (immutable via freeze), self-building (pass the input, no need to design the class), self-validating (via `zod`) Data Transfer Object implementation for JavaScript projects.  

![GitHub Release](https://img.shields.io/github/v/release/DrakStadenConsulting/simple-validated-dto)
[![CI](https://github.com/DrakStadenConsulting/simple-validated-dto/actions/workflows/ci.yml/badge.svg)](…/actions/workflows/ci.yml)

<br>

## Reasons

- There are (older) projects where `TypeScript` can not be used, where validation schemas already exists, the project evolving rapidly (large team) or there are shared schemas across services/modules/functions already.  
- The nature of JavaScript itself (the lack of private and protected functions)
- Validation requirements (data immutability, guarantee of data structure, etc...)

<br>

### Features

- Minimal dependency (`zod`, `vitest`)
- Easy to use
- JavaScript support without overhead
- Support both `require` and `import` (ESM/CommonJs)

<br>

## Requirements

- Node.js v20+
- Basic `Zod` schema knowledge

<br>

## Usage

Import the dependencies:  

```bash
  npm install @huncyrus/simple-validated-dto
```

See the [example](examples/example.js) file.

Import the `SimpleValidatedDto`:  

```JavaScript
  import { z } from 'zod';
  import { SimpleValidatedDto } from '../src/SimpleValidatedDto.js';
  // Alias can be used also
  // import { SimpleValidatedDto as dto } from '../src/SimpleValidatedDto.js';
```

Create a schema, based on an input or data structure, example:  

```JavaScript
  const myDataInput = {
    id: 42,
    title: 'Ministry of Silly Walks',
    other: '',
  };
  // schema example
  const exampleSchema = z.object({
      id: z.number(),
      title: z.string().min(1),
      other: z.union([z.string(), z.number()]),
  });
```

Then pass the data and schema:

```JavaScript
  const dto = new SimpleValidatedDto(exampleInput, exampleSchema);
```

<br>

### Retrieve data from DTO

```JavaScript
 console.log('Data from DTO: ', dto.data);
```

> Note: alternatively, use the input fields as `dto.<field-name>` to retrieve its value

<br>

### Mutate via build

The DTO provides a method to mutate the data, which shall create a new object instead of mutation:  

```JavaScript
  const newDto = SimplevalidatedDto.build(newInput, schema);
```

<br>

## Tests

The DTO uses `vitest` for unit tests:  

```JavaScript
  npm run test
```

<br>

### Test Coverage

Test coverate via Vitest:  

```bash
  npm run test:coverage
```

<br>

### Tests via docker

Build the container:  

```bash
  docker build -t simple-validated-dto-tests .
  # or rebuild
  # docker build --no-cache -t simple-validated-dto-tests .
```

Then run the container:  

```bash
  docker run --rm simple-validated-dto-tests
```

<br>

## Author

Author: [Györk Bakonyi](https://github.com/huncyrus)

<br>

## Contribution

[Contributing rules](CONTRIBUTING.md)

<br>

## References

- [Zod](https://github.com/colinhacks/zod)
- [Vitest](https://vitest.dev)