Typesafe HTTP

Goal

Project goal is to provide an easy-to-use tool for Angular engineers to check HTTP response schemas at run-time and to identify/handle schema errors.

Features

• io-ts support: relevant sources available in workspace/projects/typesafe-http-iots directory
• zod support: relevant sources available in workspace/projects/typesafe-http-zod directory

Prerequisites

• Angular CLI (v16+)
• Node.js, according to Angular version

Contribution

Contributions are welcome! Please follow these high-level steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Commit your changes and push the branch.
4. Submit a pull request.

Adding support to new Angular version

1. Create directory for major version in ./versions directory. Name must follow ngXX scheme where XX is major version number of Angular. E.g. for supporting Angular 20, it'd be ng20.
2. Add ./versions/ngXX/package.json. This is the complete workspace package.json for this Angular version. It must contain all Angular version-specific dependencies, devDependencies, and scripts.
3. Add ./versions/ngXX/angular.json. This is the complete Angular workspace configuration for this version.
4. Add ./versions/ngXX/package.iots.json and ./versions/ngXX/package.zod.json. These are the complete package.json files for the io-ts and zod libraries respectively. The peerDependencies section must list @angular/core and @angular/common with versions following >=XX.0.0 <YY.0.0 pattern, where XX is the current and YY is the next Angular version. E.g. >=20.0.0 <21.0.0.
5. Add ./versions/ngXX/files.json. This manifest declares all files that should be copied from the version directory into the workspace directory when prepws:ngXX runs. It must include entries for package.json, angular.json, the library package files, and any other version-specific files such as ESLint config, TypeScript types, test setup, spec files, and tsconfig overrides. It follows this format:

   {
     "copy": [
       { "from": "eslint.config.js", "to": "eslint.config.js" },
       { "from": "angular.json", "to": "angular.json" },
       { "from": "package.json", "to": "package.json" },
       { "from": "package.iots.json", "to": "projects/typesafe-http-iots/package.json" },
       { "from": "package.zod.json", "to": "projects/typesafe-http-zod/package.json" },
       { "from": "http-options-base.type.ts", "to": "projects/typesafe-http-iots/src/lib/types/http-options-base.type.ts" },
       { "from": "http-options-base.type.ts", "to": "projects/typesafe-http-zod/src/lib/types/http-options-base.type.ts" }
     ]
   }

   • from is relative to the version directory.
   • to is relative to the workspace/ directory.
   • Add an entry for every file that varies between Angular versions (ESLint config, TypeScript types file, test setup, spec files, tsconfig overrides, etc.).
6. If the version introduces a new test runner (e.g. Vitest), add the corresponding tsconfig.spec.json, tsconfig.spec.iots.json, and tsconfig.spec.zod.json overrides to the version directory, register them in files.json, and configure the architect.test section in angular.json accordingly.
7. Add relevant prepws:ngXX script to repository's ./package.json.
8. Update package version to next major version in ./package.json only. The version is automatically propagated to each library's package.json right before its build step.

Removing support of older Angular version

NOTE that version support removal must be applied to oldest version only and only 1 version is allowed to be removed in one shot!

1. Remove relevant prepws:ngXX script from repository's package.json
2. Remove ngXX directory and its content from ./versions directory
3. Update package version to next major version in ./package.json only. The version is automatically propagated to each library's package.json right before its build step.

Improving library code

1. Apply your changes in library or libraries under workspace/projects/ directory
2. npm run lint
3. npm run test
4. Follow Manual testing of library for each supported version to discover discrepancies
5. Update package version in ./package.json only (it is propagated automatically to each library's package.json right before its build step) as follows:
   • to next minor version, when:
     • new feature added to all libraries
     • new runtime-type-checker library support added
   • to next build, when:
     • any fix applied on at least one of the libraries

Building a library

NOTE that proper Node.js version must be prepared before library build started. Please check table below for reference versions:

Tagname	Node version
ng16	18.16.1
ng17	18.16.1
ng18	18.20.8
ng19	18.20.8
ng20	20.19.0
ng21	20.19.0

Consider using NVM tool to smoothly switch from one version to another.

npm run prepws:ngXX
cd workspace
npm run build:lib

Publishing a library

npm run publish:iots -- --tag ngXX

Manual testing of library

Minimalist sample apps included in repository, see /sample-apps directory.

Here's a full script to manually test library changes across all supported Angular versions:

npm run prepws:ngXX
cd workspace
npm run lint:lib
npm run test
npm run build:lib
rm -rf projects/sample-iots
rm -rf projects/sample-zod
npm run ng -- generate application sample-iots
npm run ng -- generate application sample-zod
rm -rf projects/sample-iots/src
rm -rf projects/sample-zod/src
cp -R ../sample-apps/iots/ projects/sample-iots
cp -R ../sample-apps/zod/ projects/sample-zod
npm run ng -- serve sample-iots
ctrl-c
npm run ng -- serve sample-zod
ctrl-c
cd ..

Run this script above on all available versions.

No NPM publish recommended until all versions are checked and work as expected!

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Contact

For questions or support, please contact peppierre@gmail.com.