@team-supercharge/oasg 19.0.0 → 20.0.0

package/README.md

@@ -231,6 +231,30 @@ This command is offered for `npm` based projects only to ensure that a working `
 $ npx oasg save-lock [target]
 ```
 
+## Dependency install cooldown
+
+`npm install` only resolves package versions that have been on the registry for at least 7 days, so a
+compromised release has a week to be caught and unpublished before it can reach a build. This is the
+`NPM_CONFIG_MIN_RELEASE_AGE` npm setting, and it applies in two places:
+
+* the _OASg_ image sets it for its own dependencies and CLI installs
+* the target scripts set it for the installs the `npm` based targets (`angular`, `nestjs`, `msw`,
+  `react`, `contract-testing`, `typescript-axios`, `typescript-fetch`) perform while building the
+  generated SDK, so the cooldown holds even when _OASg_ runs outside its own image
+
+`npm ci` is unaffected by design: it installs exactly what the lock file pins, which is what
+[`save-lock`](#save-lock) is for.
+
+If a target has to pick up a fresher release (a framework version published within the cooldown, for
+example), override the variable on the job:
+
+```yaml
+generate-sdk:
+  extends: .oasg
+  variables:
+    NPM_CONFIG_MIN_RELEASE_AGE: "0"
+```
+
 ---
 
 # Linter Rules
@@ -1195,6 +1219,26 @@ Validations from OpenAPI spec:
 | apiKey              | Api key of nuget source (If not specified, provide the CI_JOB_TOKEN)           | N        | -       |
 | generatorCustomArgs | Custom arguments of the generator (--global-property, --additional-properties) | N        | -       |
 
+> **Nullable object/enum references.** A property spec'd nullable as a
+> reference to a named schema — `nullable: true` alongside a `$ref` (OpenAPI
+> 3.0, typically via an `allOf` wrapper) or `oneOf: [$ref, {type: 'null'}]`
+> (OpenAPI 3.1) — now generates a nullable C# type (`Category?`), matching the
+> TypeScript targets' `Category | null`, regardless of whether the property is
+> `required`: `required` only governs presence of the key, never nullness of
+> the value. Previously only *optional, non-nullable* references got a `?`;
+> nullable references (required or not) silently generated a non-nullable
+> type, forcing consumers to suppress with `null!` and losing the compiler's
+> null-reference warnings at the point of use.
+>
+> Nullable **containers** (arrays, maps) are unaffected by this change and
+> still generate a non-nullable collection type.
+>
+> This applies to the `dotnet`, `dotnet-webapi` and
+> `dotnet-webapi-system-text-json` targets. `dotnet-system-text-json`
+> (`generichost`) already handled this correctly. To opt out entirely, disable
+> nullable reference types via `generatorCustomArgs`:
+> `--additional-properties=nullableReferenceTypes=false`.
+
 #### `dotnet-system-text-json`
 
 An AOT-oriented C# **client library**. Unlike `dotnet` (which uses the
@@ -1519,6 +1563,37 @@ setupWorker(
 
 This section covers the breaking changes and their migrations across major version upgrades.
 
+## From `19.x.x` to `20.0.0`
+
+From this version _OASg_ requires `node` version `>=24.21` (the current LTS line) and `npm` version
+`>=11` by default. `node@20` reached its end of life, so please upgrade your projects accordingly.
+
+The `stubby` target's generated `Dockerfile` is based on `node:24.21.0-alpine` as well.
+
+A 7 day [dependency install cooldown](#dependency-install-cooldown) now applies to every
+`npm install` _OASg_ runs, including the ones the `npm` based targets perform while building the
+generated SDK. A target that must pick up a release younger than that needs
+`NPM_CONFIG_MIN_RELEASE_AGE: "0"` on its job.
+
+### Peer dependencies in the `npm` based targets
+
+Framework packages that belong to the consuming application are declared as `peerDependencies`
+instead of being pinned by the generated SDK, so the application decides which version is used:
+
+* `typescript-axios`: `axios` moved from `dependencies` to `peerDependencies` (`^1.6.1`).
+  Applications that relied on the SDK to pull `axios` in have to depend on it themselves.
+* `angular`: `@angular/common` is declared as a peer next to `@angular/core` and `rxjs`, as the
+  generated services import `HttpClient` from `@angular/common/http`.
+* `nestjs`: `reflect-metadata` is `^0.2.2` rather than the exact `0.2.2`, `@types/multer` became an
+  optional peer (it is only needed for `binary` payloads), and the pinned `@types/validator` is no
+  longer shipped as a runtime dependency, since `class-validator` already depends on it.
+* `react`: `@tanstack/react-query` is `^5.90.21` rather than the exact `5.90.21`, so any _React
+  Query_ `5.x` can be used. The generated hooks take `NoInfer` from TypeScript instead of from
+  `@tanstack/react-query`, which stopped re-exporting it in `5.10x`, so they need TypeScript `>=5.4`.
+
+The `msw` target already declared `msw` as a peer, and `typescript-fetch` has no runtime dependency
+at all, so neither of them changed.
+
 ## From `18.x.x` to `19.0.0`
 
 ### Breaking in `spring`, `spring-kotlin`, `feign` and `feign-kotlin` targets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-supercharge/oasg",
-  "version": "19.0.0",
+  "version": "20.0.0",
   "description": "Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them",
   "author": "Supercharge",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "url": "git@gitlab.com:team-supercharge/oasg.git"
   },
   "engines": {
-    "node": ">=20.19",
-    "npm": ">=10"
+    "node": ">=24.21",
+    "npm": ">=11"
   },
   "files": [
     "bin",

package/targets/angular/templates/package.mustache

@@ -0,0 +1,40 @@
+{
+  "name": "{{{npmName}}}",
+  "version": "{{{npmVersion}}}",
+  "description": "OpenAPI client for {{{npmName}}}",
+  "author": "OpenAPI-Generator Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}.git"
+  },
+  "keywords": [
+    "openapi-client",
+    "openapi-generator"
+  ],
+  "license": "{{licenseName}}",
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json"
+  },
+  "peerDependencies": {
+    "@angular/common": "^{{ngVersion}}",
+    "@angular/core": "^{{ngVersion}}",
+    "rxjs": "^{{rxjsVersion}}"
+  },
+  "devDependencies": {
+    "@angular/common": "^{{ngVersion}}",
+    "@angular/compiler": "^{{ngVersion}}",
+    "@angular/compiler-cli": "^{{ngVersion}}",
+    "@angular/core": "^{{ngVersion}}",
+    "@angular/platform-browser": "^{{ngVersion}}",
+    "ng-packagr": "^{{ngPackagrVersion}}",
+    "reflect-metadata": "^0.1.3",
+    "rxjs": "^{{rxjsVersion}}",{{#tsickleVersion}}
+    "tsickle": "^{{tsickleVersion}}",{{/tsickleVersion}}
+    "typescript": "{{{tsVersion}}}",
+    "zone.js": "^{{zonejsVersion}}"
+  }{{#npmRepository}},
+  "publishConfig": {
+    "registry": "{{{npmRepository}}}"
+  }
+{{/npmRepository}}
+}

package/targets/common.sh

@@ -32,4 +32,12 @@ params=$(jq -r ".targets[] | select(.id == \"$targetId\") | del($blacklist) | to
 echo "$params"
 eval $params
 
+# Only resolve package versions that have been on the registry for at least a week, so a compromised
+# release has time to be caught and unpublished before it lands in a generated SDK. Every target's
+# `npm install` inherits this, including when OASg runs outside its own image, where the image level
+# default does not apply. Set NPM_CONFIG_MIN_RELEASE_AGE=0 on the job to turn the cooldown off.
+: "${NPM_CONFIG_MIN_RELEASE_AGE:=7}"
+export NPM_CONFIG_MIN_RELEASE_AGE
+echo "npm install cooldown (NPM_CONFIG_MIN_RELEASE_AGE): $NPM_CONFIG_MIN_RELEASE_AGE day(s)"
+
 echo -e "=====\n"

package/targets/dotnet/templates/model.mustache

@@ -0,0 +1,165 @@
+{{>partial_header}}
+using System;
+using System.Linq;
+using System.Text;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.ComponentModel.DataAnnotations;
+using System.Runtime.Serialization;
+using Newtonsoft.Json;
+using {{packageName}}.Converters;
+{{#models}}
+{{#model}}
+{{/model}}
+{{/models}}
+
+{{#models}}
+{{#model}}
+namespace {{modelPackage}}
+{ {{#isEnum}}{{>enumClass}}{{/isEnum}}{{^isEnum}}
+    /// <summary>
+    /// {{description}}
+    /// </summary>
+    [DataContract]
+    public {{#modelClassModifier}}{{.}} {{/modelClassModifier}}class {{classname}} : {{#parent}}{{{.}}}, {{/parent}}IEquatable<{{classname}}>
+    {
+        {{#vars}}
+        {{#items.isEnum}}
+        {{#items}}
+        {{^complexType}}
+{{>enumClass}}
+        {{/complexType}}
+        {{/items}}
+        {{/items.isEnum}}
+        {{^items.isEnum}}
+        {{#isEnum}}
+        {{^complexType}}
+{{>enumClass}}
+        {{/complexType}}
+        {{/isEnum}}
+        {{/items.isEnum}}
+        /// <summary>
+        /// {{description}}{{^description}}Gets or Sets {{{name}}}{{/description}}
+        /// </summary>{{#description}}
+        /// <value>{{.}}</value>{{/description}}{{#required}}
+        [Required]{{/required}}{{#pattern}}
+        [RegularExpression("{{{.}}}")]{{/pattern}}{{#minLength}}{{#maxLength}}
+        [StringLength({{maxLength}}, MinimumLength={{minLength}})]{{/maxLength}}{{/minLength}}{{#minLength}}{{^maxLength}}
+        [MinLength({{minLength}})]{{/maxLength}}{{/minLength}}{{^minLength}}{{#maxLength}}
+        [MaxLength({{.}})]{{/maxLength}}{{/minLength}}{{#minimum}}{{#maximum}}
+        [Range({{minimum}}, {{maximum}})]{{/maximum}}{{/minimum}}
+        [DataMember(Name="{{baseName}}", EmitDefaultValue={{#isNullable}}true{{/isNullable}}{{^isNullable}}false{{/isNullable}})]
+        {{#isEnum}}
+        public {{{datatypeWithEnum}}}{{#isNullable}}?{{/isNullable}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
+        {{/isEnum}}
+        {{^isEnum}}
+        {{! this generator never appends a question mark to dataType for a nullable object/model
+            ref (only for primitives in its hardcoded nullable-type list), so the isModel-guarded
+            branch below adds it back. isModel is never set for a primitive, so this cannot
+            produce a double question mark. Nullable containers are intentionally left non-null
+            (out of scope), matching the other .NET targets in this repo. }}
+        public {{{dataType}}}{{#nullableReferenceTypes}}{{#isNullable}}{{#isModel}}?{{/isModel}}{{/isNullable}}{{/nullableReferenceTypes}} {{name}} { get; {{#isReadOnly}}private {{/isReadOnly}}set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
+        {{/isEnum}}
+        {{^-last}}
+
+        {{/-last}}
+        {{/vars}}
+
+        /// <summary>
+        /// Returns the string presentation of the object
+        /// </summary>
+        /// <returns>String presentation of the object</returns>
+        public override string ToString()
+        {
+            var sb = new StringBuilder();
+            sb.Append("class {{classname}} {\n");
+            {{#vars}}
+            sb.Append("  {{name}}: ").Append({{name}}).Append("\n");
+            {{/vars}}
+            sb.Append("}\n");
+            return sb.ToString();
+        }
+
+        /// <summary>
+        /// Returns the JSON string presentation of the object
+        /// </summary>
+        /// <returns>JSON string presentation of the object</returns>
+        public {{#parent}}{{^isMap}}{{^isArray}}new {{/isArray}}{{/isMap}}{{/parent}}string ToJson()
+        {
+            return Newtonsoft.Json.JsonConvert.SerializeObject(this, Newtonsoft.Json.Formatting.Indented);
+        }
+
+        /// <summary>
+        /// Returns true if objects are equal
+        /// </summary>
+        /// <param name="obj">Object to be compared</param>
+        /// <returns>Boolean</returns>
+        public override bool Equals(object obj)
+        {
+            if (obj is null) return false;
+            if (ReferenceEquals(this, obj)) return true;
+            return obj.GetType() == GetType() && Equals(({{classname}})obj);
+        }
+
+        /// <summary>
+        /// Returns true if {{classname}} instances are equal
+        /// </summary>
+        /// <param name="other">Instance of {{classname}} to be compared</param>
+        /// <returns>Boolean</returns>
+        public bool Equals({{classname}} other)
+        {
+            if (other is null) return false;
+            if (ReferenceEquals(this, other)) return true;
+
+            return {{#vars}}{{^isContainer}}
+                (
+                    {{name}} == other.{{name}} ||
+                    {{^vendorExtensions.x-is-value-type}}{{name}} != null &&{{/vendorExtensions.x-is-value-type}}
+                    {{name}}.Equals(other.{{name}})
+                ){{^-last}} && {{/-last}}{{/isContainer}}{{#isContainer}}
+                (
+                    {{name}} == other.{{name}} ||
+                    {{^vendorExtensions.x-is-value-type}}{{name}} != null &&
+                    other.{{name}} != null &&
+                    {{/vendorExtensions.x-is-value-type}}{{name}}.SequenceEqual(other.{{name}})
+                ){{^-last}} && {{/-last}}{{/isContainer}}{{/vars}}{{^vars}}false{{/vars}};
+        }
+
+        /// <summary>
+        /// Gets the hash code
+        /// </summary>
+        /// <returns>Hash code</returns>
+        public override int GetHashCode()
+        {
+            unchecked // Overflow is fine, just wrap
+            {
+                var hashCode = 41;
+                // Suitable nullity checks etc, of course :)
+                {{#vars}}
+                    {{^vendorExtensions.x-is-value-type}}if ({{name}} != null){{/vendorExtensions.x-is-value-type}}
+                    hashCode = hashCode * 59 + {{name}}.GetHashCode();
+                {{/vars}}
+                return hashCode;
+            }
+        }
+
+        #region Operators
+        #pragma warning disable 1591
+
+        public static bool operator ==({{classname}} left, {{classname}} right)
+        {
+            return Equals(left, right);
+        }
+
+        public static bool operator !=({{classname}} left, {{classname}} right)
+        {
+            return !Equals(left, right);
+        }
+
+        #pragma warning restore 1591
+        #endregion Operators
+    }
+{{/isEnum}}
+{{/model}}
+{{/models}}
+}

package/targets/dotnet-webapi/templates/model.mustache

@@ -79,7 +79,12 @@ namespace {{modelPackage}}
         public {{{datatypeWithEnum}}}{{#isNullable}}{{^required}}?{{/required}}{{/isNullable}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
         {{/isEnum}}
         {{^isEnum}}
-        public {{{dataType}}}{{#nullableReferenceTypes}}{{^isContainer}}{{^required}}{{^isNullable}}?{{/isNullable}}{{/required}}{{/isContainer}}{{/nullableReferenceTypes}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
+        {{! nullable object/model refs get no question mark from the generator's dataType, unlike
+            primitives whose dataType already carries one -- so the isModel-guarded branch below
+            adds it back for those. isModel is only set for refs to named schemas, never for a
+            primitive whose dataType is already nullable, so this cannot produce a double question
+            mark. Nullable containers are intentionally left non-nullable (out of scope). }}
+        public {{{dataType}}}{{#nullableReferenceTypes}}{{^isContainer}}{{^required}}{{^isNullable}}?{{/isNullable}}{{/required}}{{#isNullable}}{{#isModel}}?{{/isModel}}{{/isNullable}}{{/isContainer}}{{/nullableReferenceTypes}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
         {{/isEnum}}
         {{^-last}}
 

package/targets/dotnet-webapi-system-text-json/templates/model.mustache

@@ -79,7 +79,12 @@ namespace {{modelPackage}}
         public {{{datatypeWithEnum}}}{{#isNullable}}{{^required}}?{{/required}}{{/isNullable}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
         {{/isEnum}}
         {{^isEnum}}
-        public {{{dataType}}}{{#nullableReferenceTypes}}{{^isContainer}}{{^required}}{{^isNullable}}?{{/isNullable}}{{/required}}{{/isContainer}}{{/nullableReferenceTypes}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
+        {{! nullable object/model refs get no question mark from the generator's dataType, unlike
+            primitives whose dataType already carries one -- so the isModel-guarded branch below
+            adds it back for those. isModel is only set for refs to named schemas, never for a
+            primitive whose dataType is already nullable, so this cannot produce a double question
+            mark. Nullable containers are intentionally left non-nullable (out of scope). }}
+        public {{{dataType}}}{{#nullableReferenceTypes}}{{^isContainer}}{{^required}}{{^isNullable}}?{{/isNullable}}{{/required}}{{#isNullable}}{{#isModel}}?{{/isModel}}{{/isNullable}}{{/isContainer}}{{/nullableReferenceTypes}} {{name}} { get; set; }{{#defaultValue}} = {{{.}}};{{/defaultValue}}
         {{/isEnum}}
         {{^-last}}
 

package/targets/nestjs/templates/package.mustache

@@ -16,16 +16,20 @@
     "@nestjs/common": ">=10.0.0 <12.0.0",
     "@nestjs/core": ">=10.0.0 <12.0.0",
     "@nestjs/platform-express": ">=10.0.0 <12.0.0",
+    "@types/multer": "^1.4.7",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.0",
-    "reflect-metadata": "0.2.2",
+    "reflect-metadata": "^0.2.2",
     "rxjs": "^7.2.0"
   },
-  "dependencies": {
-    "@types/validator": "13.11.7"
+  "peerDependenciesMeta": {
+    "@types/multer": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/multer": "^1.4.7",
+    "@types/validator": "^13.11.7",
     "typescript": "^5",
     "@types/node": "^20"
   }{{#npmRepository}},

package/targets/react/templates/hook.mustache

@@ -14,7 +14,6 @@ import {
   type DefinedInitialDataOptions,
   type UndefinedInitialDataOptions,
   type DefinedUseQueryResult,
-  type NoInfer,
   type UseSuspenseQueryOptions,
   type UseSuspenseQueryResult,
 } from '@tanstack/react-query';

package/targets/react/templates/package.mustache

@@ -28,12 +28,12 @@
     "redux-ts-simple": "^3.2.0",
     "reselect": "^4.0.0",
 {{/sagasAndRecords}}
-    "typescript": "^4.0",
+    "typescript": "^5.4",
     "@types/react": "^18.2.24 || ^19.0.0"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
-    "@tanstack/react-query": "5.90.21"
+    "@tanstack/react-query": "^5.90.21"
   }{{#npmRepository}},{{/npmRepository}}
 {{#npmRepository}}
   "publishConfig": {

package/targets/stubby/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18.15-alpine
+FROM node:24.21.0-alpine
 
 RUN npm install -g stubby
 

package/targets/typescript-axios/templates/package.mustache

@@ -0,0 +1,41 @@
+{
+  "name": "{{npmName}}",
+  "version": "{{npmVersion}}",
+  "description": "OpenAPI client for {{npmName}}",
+  "author": "OpenAPI-Generator Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}.git"
+  },
+  "keywords": [
+    "axios",
+    "typescript",
+    "openapi-client",
+    "openapi-generator",
+    "{{npmName}}"
+  ],
+  "license": "{{licenseName}}",
+  "main": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
+{{#supportsES6}}
+  "module": "./dist/esm/index.js",
+  "sideEffects": false,
+{{/supportsES6}}
+  "scripts": {
+    "build": "tsc{{#supportsES6}} && tsc -p tsconfig.esm.json{{/supportsES6}}",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "axios": "{{axiosVersion}}"
+  },
+  "devDependencies": {
+    "@types/node": "12.11.5 - 12.20.42",
+    "axios": "{{axiosVersion}}",
+    "typescript": "^4.0 || ^5.0"
+  }{{#npmRepository}},{{/npmRepository}}
+{{#npmRepository}}
+  "publishConfig": {
+    "registry": "{{npmRepository}}"
+  }
+{{/npmRepository}}
+}