From 650e8f05f87cc4b7176f06e586c1a1968f1f4ff4 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sun, 14 Apr 2024 17:39:13 +0200 Subject: [PATCH] update tsconfig --- npmextra.json | 15 ++++- package.json | 11 +++- readme.hints.md | 1 + readme.md | 146 +++++++++++++++++++++++++++++++++++++++--------- 4 files changed, 143 insertions(+), 30 deletions(-) create mode 100644 readme.hints.md diff --git a/npmextra.json b/npmextra.json index 7ea170c..9af797b 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,17 +5,26 @@ "githost": "code.foss.global", "gitscope": "push.rocks", "gitrepo": "smartguard", - "description": "smart guards for validations", + "description": "A library for creating and managing validation guards.", "npmPackagename": "@push.rocks/smartguard", "license": "MIT", - "projectDomain": "push.rocks" + "projectDomain": "push.rocks", + "keywords": [ + "validation", + "guards", + "typescript", + "async", + "nodejs", + "express", + "middleware" + ] } }, "npmci": { "npmGlobalTools": [], "npmAccessLevel": "public" }, - "tsdocs": { + "tsdoc": { "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n" } } \ No newline at end of file diff --git a/package.json b/package.json index a5f2d57..cbcdb6f 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/smartguard", "version": "2.0.1", "private": false, - "description": "smart guards for validations", + "description": "A library for creating and managing validation guards.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "type": "module", @@ -40,5 +40,14 @@ ], "browserslist": [ "last 1 chrome versions" + ], + "keywords": [ + "validation", + "guards", + "typescript", + "async", + "nodejs", + "express", + "middleware" ] } \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/readme.md b/readme.md index 4e8c14c..2561167 100644 --- a/readme.md +++ b/readme.md @@ -1,38 +1,132 @@ -# @pushrocks/smartguard +# @push.rocks/smartguard smart guards for validations -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@pushrocks/smartguard) -* [gitlab.com (source)](https://gitlab.com/pushrocks/smartguard) -* [github.com (source mirror)](https://github.com/pushrocks/smartguard) -* [docs (typedoc)](https://pushrocks.gitlab.io/smartguard/) +## Install -## Status for master +To install `@push.rocks/smartguard`, run the following command in your terminal: -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/pushrocks/smartguard/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/pushrocks/smartguard/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@pushrocks/smartguard)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/pushrocks/smartguard)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@pushrocks/smartguard)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@pushrocks/smartguard)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@pushrocks/smartguard)](https://lossless.cloud) -Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud) +```bash +npm install @push.rocks/smartguard --save +``` + +This will add `@push.rocks/smartguard` to your project's dependencies. ## Usage +`@push.rocks/smartguard` provides a sturdy and easy way to validate data by using guards. Guards are functions that return a Boolean value indicating whether the data meets certain criteria. This package is highly beneficial for input validation, security checks, or any scenario where data needs to conform to specific rules or patterns. -## Contribution +### Basics -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +At the core of `@push.rocks/smartguard` are two main classes: `Guard` and `GuardSet`. A `Guard` represents a single rule or validation step, while a `GuardSet` allows you to combine multiple `Guard` instances and evaluate them together. -For further information read the linked docs at the top of this readme. +### Creating a Guard -> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +A `Guard` is an object that encapsulates a validation rule. You define a guard by providing a function that takes an input and returns a Promise, resolving to a Boolean value indicating if the input meets the criteria. -[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com) +```typescript +import { Guard } from '@push.rocks/smartguard'; + +const isStringGuard = new Guard(async (data) => { + return typeof data === 'string'; +}); +``` + +In the example above, we define a simple guard that checks if the input is a string. + +### Using GuardSets for Composite Validations + +When you have multiple validation rules, you can combine them using `GuardSet`. This allows you to evaluate all guards on a piece of data and only pass if all guards return true. + +```typescript +import { Guard, GuardSet } from '@push.rocks/smartguard'; + +const isStringGuard = new Guard(async (data) => { + return typeof data === 'string'; +}); + +const isNotEmptyGuard = new Guard(async (data) => { + return data.length > 0; +}); + +const stringValidationSet = new GuardSet([isStringGuard, isNotEmptyGuard]); + +// Now you can use stringValidationSet.executeGuardsWithData(data) to validate your data +``` + +### Executing Guards + +To execute a guard or a set of guards against data, you use the `executeGuardWithData` method for a single guard, or `executeGuardsWithData` method for a `GuardSet`. + +```typescript +const isValidString = await isStringGuard.executeGuardWithData('Hello World!'); +console.log(isValidString); // true + +const areValidStrings = await stringValidationSet.executeGuardsWithData('Hello World!'); +console.log(areValidStrings.every(result => result)); // true if all validations passed +``` + +### Advanced Usage: Custom Guard Functions + +Guards can perform any asynchronous operation inside their validation function, making them incredibly versatile. For instance, you could call an API to validate an address, check if a username already exists in a database, or even integrate with third-party validation services. + +```typescript +import { Guard } from '@push.rocks/smartguard'; +import { someApiRequestFunction } from './myApiFunctions'; + +const isValidAddressGuard = new Guard(async (address) => { + const response = await someApiRequestFunction(address); + return response.isValid; +}); +``` + +### Integrating with Express Middleware + +`@push.rocks/smartguard` can easily integrate with frameworks like Express by utilizing guards within middleware functions. This allows you to perform validations before a request reaches your route handlers. + +```typescript +import * as express from 'express'; +import { Guard } from '@push.rocks/smartguard'; + +const app = express(); +const isAuthorizedUserGuard = new Guard(async (req) => { + // your logic here, return true if authorized + return req.headers.authorization === 'Bearer some-token'; +}); + +app.use(async (req, res, next) => { + const isAuthorized = await isAuthorizedUserGuard.executeGuardWithData(req); + if(!isAuthorized) { + res.status(403).send('Unauthorized'); + return; + } + next(); +}); + +app.listen(3000, () => console.log('Server running on port 3000')); +``` + +In the example above, we use a guard to check if a request has a valid authorization header. This demonstrates how `@push.rocks/smartguard` can be seamlessly integrated into existing server applications to enforce security or input validations. + +### Conclusion + +`@push.rocks/smartguard` offers a robust, flexible way to perform validations across your application. Whether you're validating simple data types, complex objects, or making asynchronous validation calls, smartguard simplifies the process and makes your code cleaner and more maintainable. + + +## License and Legal Information + +This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. + +**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. + +### Trademarks + +This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. + +### Company Information + +Task Venture Capital GmbH +Registered at District court Bremen HRB 35230 HB, Germany + +For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. + +By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.