@decaf-ts/decorator-validation
v1.0.7
Published
simple decorator based validation engine
Downloads
12
Maintainers
Readme
Simple Model Validation Engine
Decorator based
Simple implementation of a Typescript decorator based validation system.
Meant to be easily extended, customized and integrated with the browser's input validation mechanisms
Provides access to common features in other languages:
- Model serialization/deserialization;
- Model Hashing;
- Model Equality;
- TODO: Model Deep Cloning
Initial Setup
if you use github
create a new project using this one as a template.
clone it git clone <project>
and navigate to the root folder cd <project>
If your project has private dependencies or publishes to private npm registries, create an .npmrc
containing:
@<scope1>:registry=https://<ADDRESS>.com/api/v4/packages/npm/
@<scope2>:registry=https://<ADDRESS>.<DOMAIN>.com/api/v4/packages/npm/
//<ADDRESS>.<DOMAIN>.com/:_authToken=${TOKEN}
//<ADDRESS>.<DOMAIN>.com/api/v4/groups/<GROUP_ID>/packages/npm/:_authToken=${TOKEN}
//<ADDRESS>.<DOMAIN>.com/api/v4/projects/<PROJECT_ID>/packages/npm/:_authToken=${TOKEN}
Changing:
- to your domain if any (if you are using plain gitlab or github use empty and take care to remove the extra
.
); - <GROUP_ID> to your project's group id (if any). otherwise remove this line
- <PROJECT_ID> to your project's id
and adding a .token
file containing your access token to the private registries na repositories.
Installation
Run npm install
(or npm run do-install
if you have private dependencies and a .token
file) to install the dependencies:
If this is the first time you are running this command it will also:
- update this repository's dependencies to their latest version;
- creates a
.token
file which you can leave empty unless you have private dependencies or publish to private registries - delete this 'first run script' file and npm call from the
package.json
; - try to commit the updated
package.json
and deleted files (having ssh access helps here);
Linting
This repo comes with eslint + prettier preconfigured to the default standards
Testing
Preconfigured Jest based testing:
- unit tests under the
tests/unit
folder;- include a default bundle test (helps with circular dependencies and such);
- integration tests under the
tests/integration
folder; - stores converage results under
workdocs/coverage
; - publishes coverage result to docs;
- ignores
cli.ts
from coverage since that is an executable file; - defines the coverage threshold in
jest.config.ts
;
Releases
This repository automates releases in the following manner:
- run
npm run release -- <major|minor|patch|version> <message>
:- if arguments are missing you will be prompted for them;
- it will run
npm run prepare-release
npm script; - it will commit all changes;
- it will push the new tag;
If publishing to a private repo's npm registry, make sure you add to your package.json
:
{
"publishConfig": {
"<SCOPE>:registry": " https://<REGISTRY>/api/v4/projects/<PROJECT_ID>/packages/npm/"
}
}
Where:
<SCOPE>
- Is the scope of your package;<REGISTRY>
- your registry host;<PROJECT_ID>
- you project ID number (easy to grab via UI in gitlab or by running$("meta[name=octolytics-dimension-repository_id]").getAttribute('content')
in the repository page in github) ;
Publishing
Unless the -no-ci
flag is passed in the commit message to the npm run release
command, publishing will be handled
automatically by github/gitlab (triggered by the tag).
When the -no-ci
flag is passed then you can:
- run
npm run publish
. This command assumes :- you have previously run the
npm run release
; - you have you publishing properly configured in
npmrc
andpackage.json
; - The token for any special access required is stored in the
.token
file;
- you have previously run the
Continuous Integration/Deployment
While the implementationfor gitlab and github are not perfectly matched, they are perfectly usable.
The template comes with ci/cd for :
- gitlab (with caching for performance):
- stages:
- dependencies: Installs dependencies (on
package-lock.json
changes, caches node modules); - build: builds the code (on
src/*
changes, cacheslib
anddist
); - test: tests the code (on
src/*
,test/*
changes, cachesworkdocs/{resources, badges, coverage}
); - deploy:
- deploys to package registry on a tag (public|private);
- deploys docker image to docker registry (private);
- Deploys the documentation to the repository pages;
- dependencies: Installs dependencies (on
- stages:
- github:
- jest-test: standard
install -> build -> test
loop; - jest-coverage: extracts coverage from the tests;
- codeql-analysis: Code quality analisys;
- pages: builds the documentation and deploys to github pages
- release-on-tag: issues a release when the tag does not contain
-no-ci
string - publish-on-release: publishes to package registry when the tag does not contain the
-no-ci
string - Requires Variables:
- CONSECUTIVE_ACTION_TRIGGER: secret to enable actions to trigger other actions;
- NPM_TOKEN: npm/docker registry token
- jest-test: standard
Considerations
Typescript Compilation options
Even though all code is exported in both CommonJS and ESM format, and the default is ES2022
in order to take advantage to all the latest Typescript and JS features,
when importing these libraries the following flag in tsconfig.compilerOptions
is mandatory:
{
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"useDefineForClassFields": false
}
Documentation
The repository proposes a way to generate documentation that while still not ideal, produces verys consitest results.
In the code you see an example on how to properly document each code object, but the overall structure is:
- each package is a
@module
; - Classes and Interfaces are categorized into
@category
and@subcategory
; - All other objects are categorized by
@namespace
and@memberOf
; - Enums and const are declared as
@const
and both must describe their properties as@property
(when constants are objects); - Interfaces must declare their methods
@method
;
There is one smple step to generating the documentation (automated in CI):
npm run docs
- this has several stages, defined under thegulp docs
(gulpfile.js):- compiles the Readme file via md compile:
- enables keeping separate files for sections that are then joined into a single file;
- Allows keeping specific files in the jsdocs tutorial folder so they show up on their own menu;
- compiles the documentation from the source code using jsdocs:
- uses the better docs template with the category and component plugins
- uses the mermaid jsdoc plugin to embue uml diagrams in the docs
- includes a nav link to the test coverage results;
- copies the jsdoc and mds to
/docs
; - copies the
./workdocs/{drawings, uml, assets, resources}
to./docs
;
- compiles the Readme file via md compile:
The produced docs
folder contains the resulting documentation;
Related
Social
Scripts
The following npm scripts are available for development:
preinstall
- will run only on the first install to trigger the dep update. will self delete;do-install
- sets aTOKEN
environment variable to the contents of.token
and runs npm install (useful when you have private dependencies);flash-forward
- updates all dependencies. Take care, This may not be desirable is some cases;reset
- updates all dependencies. Take care, This may not be desirable is some cases;build
- builds the code (via gulpgulpfile.js
) in development mode (generateslib
anddist
folder);build:prod
- builds the code (via gulpgulpfile.js
) in production mode (generateslib
anddist
folder);test
- runs unit tests;test:integration
- runs it tests;test:all
- runs all tests;lint
- runs es lint on the code folder;lint-fix
- tries to auto-fix the code folder;prepare-release
- defines the commands to run prior to a new tag (defaults to linting, building production code, running tests and documentation generation);release
- triggers a new tag being pushed to master (via./bin/tag_release.sh
);clean-publish
- cleans the package.json for publishing;coverage
- runs all test, calculates coverage and generates badges for readme;drawings
- compiles all DrawIO*.drawio
files in theworkdocs/drawings
folder to png and moves them to theworkdocs/resources
folder;uml
- compiles all PlantUML*.puml
files in theworkdocs/uml
folder to png and moves them to theworkdocs/resources
folder;docs
- compiles all the coverage, drawings, uml, jsdocs and md docs into a readable web page under./docs
;
Repository Structure
decorator-validation
│
│ .gitignore <-- Defines files ignored to git
│ .npmignore <-- Defines files ignored by npm
│ .nmprc <-- Defines the Npm registry for this package
│ .eslintrc.cjs <-- linting for the project
│ .prettier.config.cjs <-- Code style for the project
│ .gitlab-ci.yml <-- Gillab CI/CD file
│ gulpfile.js <-- Gulp build scripts. used for building na other features (eg docs)
│ jest.config.ts <-- Tests Configuration file
│ mdCompile.json <-- md Documentation generation configuration file
│ jsdocs.json <-- jsdoc Documentation generation configuration file
│ Dockerfile <-- minimal example of a node service Dockerfile
│ LICENCE.md <-- Licence disclamer
│ package.json
│ package-lock.json
│ README.md <-- Readme File dynamically compiled from 'workdocs' via the 'docs' npm script
│ tsconfig.json <-- Typescript config file. Is overriden in 'gulpfile.js'
│
└───bin
│ │ tag_release.sh <-- Script to help with releases
│
└───docs
│ │ ... <-- Dinamically generated folder, containing the compiled documentation for this repository. generated via the 'docs' npm script
│
└───src
│ │ ... <-- Source code for this repository
│
└───tests
│ │───unit <-- Unit tests
│ └───integration <-- Integration tests
│
└───workdocs <-- Folder with all pre-compiled documentation
│ │───assets <-- Documentation asset folder
│ │───badges <-- Auto generated coverage badges folder
│ │───coverage <-- Auto generated coverage results
│ │───drawings <-- DrawIO folder. Drawings (*.drawio) here will be processed to generate documentation (requires docker)
│ │───uml <-- PlantUML folder. Diagrams (*.puml) here will be processed to generate documentation (requires docker)
│ │───tutorials <-- Tutorial folder
│ │ ... <-- Categorized *.md files that are merged to generate the final readme (via md compile)
│ │ Readme.md <-- Entry point to the README.md
│
└───dist
│ │ ... <-- Dinamically generated folder containing the bundles for distribution
│
└───lib
| ... <-- Dinamically generated folder containing the compiled code
Getting help
If you have bug reports, questions or suggestions please create a new issue.
Contributing
I am grateful for any contributions made to this project. Please read this to get started.
Supporting
The first and easiest way you can support it is by Contributing. Even just finding a typo in the documentation is important.
Financial support is always welcome and helps keep the both me and the project alive and healthy.
So if you can, if this project in any way. either by learning something or simply by helping you save precious time, please consider donating.
License
This project is released under the MIT License.