@team-supercharge/oasg 17.1.0 → 18.0.0

package/README.md

@@ -128,38 +128,39 @@ include:
 
 The table below gives an overview of the changes (breaking, non-breaking, bug fixes) introduced in various major versions. For the resolution of breaking changes please consult the [Migration Guide](#migration-guide).
 
-| Component                    |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
-|------------------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
-| **Internal**                 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
-| _Core_                       |💥  |✨  |🐛  |💥  |✨  |🐛  |✨  |➖  |✨  |🐛  |🐛  |➖  |💥  |💥  |✨  |💥  |🆕  |
-| _Linter_                     |➖  |🐛  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |🐛  |➖  |✨  |💥  |🆕  |
-| **Client Targets**           | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
-| `android`                    |➖  |➖  |➖  |🐛  |💥  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
-| `angular`                    |➖  |✨  |➖  |🐛  |💥  |➖  |➖  |➖  |🐛  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |🆕  |
-| `dotnet`                     |➖  |➖  |➖  |🆕  |
-| `feign`                      |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |🐛  |🐛  |🆕  |
-| `feign-kotlin`               |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |🆕  |
-| `plain-java`                 |🐛  |🆕  |
-| `flutter`                    |➖  |➖  |➖  |➖  |🆕  |
-| `ios`                        |➖  |➖  |➖  |➖  |💥  |🐛  |➖  |➖  |➖  |✨  |➖  |💥  |➖  |➖  |✨  |🆕  |
-| `apple-swift`                |➖  |🆕  |
-| `kmp`                        |✨  |➖  |➖  |🆕  |
-| `python`                     |➖  |🆕  |
-| `python-legacy`              |➖  |💥  |➖  |🐛  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
-| `react`                      |➖  |🐛  |🐛  |➖  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
-| `typescript-axios`           |➖  |🆕  |
-| `typescript-fetch`           |➖  |🆕  |
-| **Server Targets**           | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
-| `nestjs`                     |🐛  |💥  |💥  |➖  |💥  |✨  |➖  |➖  |🐛  |➖  |➖  |✨  |🆕  |
-| `python-fastapi`             |➖  |➖  |➖  |🆕  |
-| `python-fastapi-raw-request` |➖  |➖  |➖  |🆕  |
-| `spring`                     |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |➖  |✨  |➖  |🆕  |
-| `spring-kotlin`              |✨  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |🐛  |✨  |➖  |🆕  |
-| **Misc Targets**             | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
-| `contract-testing`           |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
-| `openapi`                    |➖  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |✨  |➖  |🆕  |
-| `stubby`                     |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |🆕  |
-| `postman`                    |➖  |➖  |🆕  |
+| Component                    |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
+|------------------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| **Internal**                 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
+| _Core_                       |✨  |💥  |✨  |🐛  |💥  |✨  |🐛  |✨  |➖  |✨  |🐛  |🐛  |➖  |💥  |💥  |✨  |💥  |🆕  |
+| _Linter_                     |➖  |➖  |🐛  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |🐛  |➖  |✨  |💥  |🆕  |
+| **Client Targets**           | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
+| `android`                    |✨  |➖  |➖  |➖  |🐛  |💥  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
+| `angular`                    |➖  |➖  |✨  |➖  |🐛  |💥  |➖  |➖  |➖  |🐛  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |🆕  |
+| `dotnet`                     |➖  |➖  |➖  |➖  |🆕  |
+| `feign`                      |➖  |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |🐛  |🐛  |🆕  |
+| `feign-kotlin`               |➖  |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |🆕  |
+| `plain-java`                 |➖  |🐛  |🆕  |
+| `flutter`                    |➖  |➖  |➖  |➖  |➖  |🆕  |
+| `ios`                        |➖  |➖  |➖  |➖  |➖  |💥  |🐛  |➖  |➖  |➖  |✨  |➖  |💥  |➖  |➖  |✨  |🆕  |
+| `apple-swift`                |➖  |➖  |🆕  |
+| `kmp`                        |✨  |✨  |➖  |➖  |🆕  |
+| `python`                     |➖  |➖  |🆕  |
+| `python-legacy`              |➖  |➖  |💥  |➖  |🐛  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
+| `react`                      |💥  |➖  |🐛  |🐛  |➖  |💥  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
+| `typescript-axios`           |✨  |➖  |🆕  |
+| `typescript-fetch`           |✨  |➖  |🆕  |
+| **Server Targets**           | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
+| `nestjs`                     |✨  |🐛  |💥  |💥  |➖  |💥  |✨  |➖  |➖  |🐛  |➖  |➖  |✨  |🆕  |
+| `python-fastapi`             |➖  |➖  |➖  |➖  |🆕  |
+| `python-fastapi-raw-request` |➖  |➖  |➖  |➖  |🆕  |
+| `spring`                     |➖  |🐛  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |➖  |✨  |➖  |🆕  |
+| `spring-kotlin`              |➖  |✨  |✨  |➖  |➖  |➖  |➖  |➖  |✨  |💥  |💥  |➖  |➖  |🐛  |✨  |➖  |🆕  |
+| **Misc Targets**             | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9  | 8  | 7  | 6  | 5   | 4  | 3  | 2  | 1  |
+| `contract-testing`           |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |🆕  |
+| `openapi`                    |➖  |➖  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |✨  |➖  |🆕  |
+| `stubby`                     |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |➖  |💥  |➖  |➖  |➖  |➖  |🆕  |
+| `postman`                    |➖  |➖  |➖  |🆕  |
+| `msw`                        |🆕  |
 
 **Legend:**
 
@@ -218,6 +219,15 @@ Publishes the generated API client package of the specified target. If no target
 $ npx oasg publish [target]
 ```
 
+## `save-lock`
+
+Saves the current state of the package-lock.json file to the `.oasg` directory. This is useful for later restoring the lock file in case of a failed install or build.
+This command is offered for `npm` based projects only to ensure that a working `package-lock.json` file is always available for the project.
+
+```shell
+$ npx oasg save-lock [target]
+```
+
 ---
 
 # Linter Rules
@@ -522,20 +532,6 @@ Common target parameters
 | packageName | Name of the generated NPM package | Y | - |
 | repository | URL of the NPM package registry | Y | - |
 
-##### Known issue: breaking dependencies
-
-The Angular target has a known issue related to dependency versioning. The generated Angular project's `package.json` currently defines multiple dependencies with flexible versions (e.g., using `^` or `~` in version constraints). This flexibility allows newer versions of dependencies (not to mention the transitive dependencies), to be pulled in, which can occasionally lead to breaking changes.
-
-A notable instance of this issue occurred with **Angular version 12**, which introduced changes that broke the build of generated projects. To address this specific case, we implemented a **temporary fix** in the `targets/angular/generate.sh` script. This script now manually installs problematic dependencies with fixed, validated versions.
-
-###### Long-Term Solution
-
-We are actively discussing a long-term solution to this issue. Potential approaches include implementing dependency version locking mechanisms (`package-lock.json`) per Angular versions.
-
-The temporary fix may not cover all future breaking changes from other dependencies. Projects using different versions of Angular may encounter issues if the fix does not align with their specific requirements.
-
-We welcome feedback and contributions to help address this issue.
-
 #### `react`
 
 ```json
@@ -553,7 +549,132 @@ We welcome feedback and contributions to help address this issue.
 | packageName | Name of the generated NPM package | Y | - |
 | repository | URL of the NPM package registry | Y | - |
 
-> ℹ️ This package offers React Hooks for convenience.
+**Usage**<br>
+
+1. Provide API config and instances
+
+Let's create a component to setup API configuration and the APIs you need. Wrap your application with this components afterwards.
+
+```tsx
+import { type Type, type APIS, type ConfigurationParameters, ApiConfigProvider, ApiInstancesProvider, UsersApi } from '@project/oasg-example-react';
+
+// Provide here all the APIs you need (might change during the project)
+const providedApis: Type<APIS>[] = [UsersApi];
+
+const ApiProvider = ({ children }) => {
+  const config = useMemo<ConfigurationParameters>(
+    () => ({
+      basePath: 'https://your-api-url.domain',
+      middlewares: [/* Your middlewares, eg. adding authorization header */]
+    }),
+    []
+  );
+
+  return (
+    <ApiConfigProvider config={config}>
+      <ApiInstancesProvider apis={providedApis}>{children}</ApiInstancesProvider>
+    </ApiConfigProvider>
+  );
+};
+```
+
+2. Using the hooks
+
+The SDK exposes two React hooks for each endpoints: a query and a mutation. Their name come from the `operationId` you provided for them in the OpenAPI files. Eg.`useGetUsersQuery` and `useGetUsersMutation`.
+
+Note: While both hooks are generated for all endpoints, we recommend using queries for GET requests and mutations for POST/PUT/PATCH/DELETE requests.
+
+They can be used in a very similar way like `useQuery` and `useMutation` from `@tanstack/react-query` but they provide:
+- built-in `queryFn`s
+- built-in `queryKey`s
+- typed input parameters and outputs
+
+To fetch the list of users from the above examples is as simple as:
+
+```ts
+const usersQuery = useGetUsersQuery();
+//    ^- usersQuery.data: GetUsersListResponse | undefined
+```
+
+Or if your query has parameters they be passed as the first parameter:
+```ts
+const usersQuery = useGetUsersQuery({ offset: 15, limit: 10 });
+```
+
+3. Query options
+
+Query options are available as the first or the second parameter of the query, depending on if the query has parameters or not.
+
+```ts
+const usersQuery = useGetUsersQuery({ refetchInterval: 5000 });
+```
+
+or
+```ts
+const usersQuery = useGetUsersQuery({ offset: 15, limit: 10 }, { refetchInterval: 5000 });
+```
+
+4. Managing query keys
+
+You don't have to and also you can't provide `queryFn` or the `queryKey` options for use*Query hooks, as the SDK handles them automatically. You might still need to access the automatically generated query keys, so the SDK also exposes query key factories that you can use to refetch/invalidate query keys. This means that the SDK is the single source of the query keys in your app.
+
+```tsx
+const queryClient = useQueryClient();
+
+queryClient.invalidateQueries({ queryKey: getUsersQueryKey.all() })
+
+// or if your query has parameters
+queryClient.invalidateQueries({ queryKey: getUsersQueryKey.withParams({ offset: 15, limit: 10 }) })
+```
+
+5. Disabled queries
+
+Queries with parameters can also be disabled by providing `undefined` as a parameter for them. This set's `enabled` option to `false` under the hood for the query. This could help you to write dependent queries easier.
+
+```ts
+const accountsQuery = useGetAccountsQuery();
+const accountId = accountsQuery.data?.at(0)?.id;
+
+const reportsQuery = useGetReportsQuery(accountId && { accountId });
+```
+
+In this case `reportsQuery` is not running until `accountsQuery` finished fetching.
+
+6. Passing headers to queries and mutations
+
+`@tanstack/react-query` is not reposinble from what data sources you gather your data. This SDK does, it is deeply integrated with an underlaying API layer. So we added support to add headers to your requests.
+
+```ts
+// HEADERS is a JavaScript symbol provided by the SDK. By its unique nature it makes sure that it doesn't interfere with the other parameters you pass to your queries.
+import { HEADERS } from '@project/oasg-example-react';
+
+// Use with queries:
+const usersQuery = useGetUsersQuery({
+  [HEADERS]: {
+    'X-Users-Feature-Flag': 'B',
+  }
+})
+
+// With mutations - headers can be passed at the hook level:
+const createUserMutation = useCreateUserMutation({
+  [HEADERS]: {
+    'X-Users-Feature-Flag': 'A',
+  }
+});
+
+// Or while calling `mutate` or `mutateAsync`:
+createUserMutation.mutate({
+  createUserRequest: userData,
+  [HEADERS]: {
+    'X-Users-Feature-Flag': 'B',
+  }
+})
+
+// Headers are merged in this order (later overrides earlier):
+// 1. middleware configuration
+// 2. mutation hook options
+// 3. mutate/mutateAsync parameters
+```
 
 #### `stubby`
 
@@ -1117,12 +1238,104 @@ Validations from OpenAPI spec:
 | packageName | Name of the generated NPM package | Y | - |
 | repository | URL of the NPM package registry | Y | - |
 
+#### `msw`
+
+```json
+{
+  "id": "msw",
+  "type": "msw",
+  "source": "source-merged",
+  "packageName": "@project/oasg-example-msw",
+  "repository": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/npm/"
+}
+```
+
+|Parameter| Description| Required | Default |
+|-|-|-|-|
+| packageName | Name of the generated NPM package | Y | - |
+| repository | URL of the NPM package registry | Y | - |
+
+**Usage**<br>
+
+1. Configure the SDK
+
+Start by configuring the SDK with a `baseUrl` and an optional `delay`:
+
+```ts
+import { setMswSdkConfig } from '@project/oasg-example-msw';
+
+setMswSdkConfig({
+  baseUrl: 'https://your-api-url.domain',
+  // each request will take at least 100ms and at most 400ms (this is the default)
+  // disable delay by setting it to [0, 0]
+  delay: [100, 400],
+});
+```
+
+2. Mock your endpoints
+
+Once configured, you can start mocking your endpoints.
+The SDK automatically sets up the handlers and enforces fully typed params, query params, request bodies, and responses based on your OpenAPI spec.
+
+```ts
+import { setupWorker } from 'msw/browser';
+import { HttpReponse } from 'msw';
+import { mockUsersApi, type User } from '@project/oasg-example-msw';
+
+const mockUsers: User[] = [
+  {
+    id: crypto.randomUUID(),
+    firstName: 'Chester',
+    lastName: 'Bennington',
+    createdAt: new Date(),
+  },
+  {
+    id: crypto.randomUUID(),
+    firstName: 'Emily',
+    lastName: 'Armstrong',
+    createdAt: new Date(),
+  }
+];
+
+setupWorker(
+  // each tag in your OpenAPI spec exposes a `mock{ApiName}Api` helper
+  ...mockUsersApi({
+    // provide the endpoints you want to mock by their `operationId`
+    getUsers: (info) => {
+      return HttpResponse({
+        items: info.queryParams.sortDirection === 'desc'
+          ? mockUsers.toSorted((a, b) => a.createdAt - b.createdAt)
+          : mockUsers.toSorted((a, b) => b.createdAt - a.createdAt),
+      })
+    },
+    createUser: (info) => {
+      const user = await info.request.json();
+      mockUsers.push({
+        id: crypto.randomUUID(),
+        createdAt: new Date(),
+        ...user,
+      });
+
+      return HttpResponse(null, { status: 201 });
+    }
+  }),
+)
+```
+
 ---
 
 # Migration Guide
 
 This section covers the breaking changes and their migrations across major version upgrades.
 
+## From `17.x.x` to `18.0.0`
+
+### Breaking in `react` target
+
+1. Exported hooks were renamed. API names are not part of the hooks anymore as `operationId` is unique by itself. E.g. instead of `useUsersApiCreateUserMutation` the name is `useCreateApiMutation`.
+2. *Query keys* are now managed by the SDK itself and they were removed from the query's options object. Check the *Managing query keys* section below to get an idea of how you can still work with query keys in your application.
+3. If an endpoint has URL parameters, search parameters, or a body, it is now the first parameter of the `use*Query` hooks. E.g. instead of `useGetUserList({ refetchInterval: 60_000 }, { limit, offset })` it is `useGetUserList({ limit, offset }, { refetchInterval: 60_000 })`. This especially comes in handy together with the automatic queryKey management the SDK provides, as without the queryKey there are no required parameters in the query's options object, so you can completely ignore it if you don't want to set any options. E.g. instead of `useGetUserList({}, { limit, offset })` it is `useGetUserList({ limit, offset })` now.
+
 ## From `16.x.x` to `17.0.0`
 
 From this version _OASg_ requires `node` version `^20.19` by default. Please upgrade your projects accordingly.

package/bin/oasg

@@ -21,6 +21,7 @@ const { applyOverrides } = require(`${__dirname}/overrider.js`);
 const { openApiTarget } = require(`${__dirname}/openapi-target.js`);
 const { postmanTarget } = require(`${__dirname}/postman-target.js`);
 const { processSource } = require(`${__dirname}/process-source.js`);
+const { saveLock } = require(`${__dirname}/save-lock.js`);
 const { globSync } = require('glob');
 
 const projectPackageJson = JSON.parse(fs.readFileSync('package.json'));
@@ -35,7 +36,7 @@ const PROXY_PORT = '9999';
 
 const DEFAULT_GENERATOR_MAPPING = {
   // client targets
-  "android":                      { version: '7.0.1',   generator: 'kotlin' },
+  "android":                      { version: '7.17.0',  generator: 'kotlin' },
   "angular":                      { version: '7.11.0',  generator: 'typescript-angular' },
   "feign":                        { version: '7.12.0',  generator: 'spring' },
   "feign-kotlin":                 { version: '7.12.0',  generator: 'kotlin-spring' },
@@ -43,7 +44,7 @@ const DEFAULT_GENERATOR_MAPPING = {
   "flutter":                      { version: '7.0.1',   generator: 'dart-dio' },
   "ios":                          { version: '7.0.1',   generator: 'swift5' },
   "apple-swift":                  { version: undefined, generator: undefined },
-  "kmp":                          { version: '7.14.0',  generator: 'kotlin' },
+  "kmp":                          { version: '7.17.0',  generator: 'kotlin' },
   "python":                       { version: '7.11.0',  generator: 'python' },
   "python-legacy":                { version: '7.11.0',  generator: 'python-pydantic-v1' },
   "react":                        { version: '7.0.1',   generator: 'typescript-fetch' },
@@ -62,6 +63,7 @@ const DEFAULT_GENERATOR_MAPPING = {
   "openapi":                      { version: undefined, generator: undefined },
   "stubby":                       { version: '4.3.1',   generator: 'stubby' },
   "postman":                      { version: undefined, generator: undefined },
+  "msw":                          { version: '7.11.0',  generator: 'typescript-fetch' },
 };
 const DEFAULT_KTLINT_VERSION = '1.0.0';
 const BIN_FOLDER = 'out/.bin';
@@ -134,8 +136,23 @@ async function run() {
           describe: 'Generate as pre-release (optional). \nHow a pre-release is handled varies between different target types.',
           type: 'boolean'
         })
+        .option('force-lock', {
+          describe: 'Force usage of saved package-lock.json (skip npm install, use saved lock immediately)',
+          type: 'boolean',
+          default: false
+        })
     }, (argv) => generate(argv))
 
+    // save-lock
+    .command(['save-lock [target]', 'sl'], 'save package-lock.json for a target', (yargs) => {
+      yargs
+        .positional('target', {
+          describe: 'specify the target name',
+          type: 'string',
+          demandOption: true
+        })
+    }, (argv) => saveLock(argv, config, checkTargetId))
+
     // publish
     .command(['publish [target]', 'p'], 'publish packages', (yargs) => {
       yargs
@@ -159,7 +176,7 @@ function checkVersionMismatch() {
   const oasgVersion = oasgPackageJson.version;
   const oasgDepVersion = projectPackageJson.dependencies[oasgPackageJson.name];
 
-  if (oasgDepVersion.startsWith('file:')) {
+  if (!oasgDepVersion || oasgDepVersion.startsWith('file:')) {
     return;
   }
 
@@ -477,6 +494,7 @@ async function generate(argv) {
   const targetIds = determineTargetIds(argv);
   VERSION = determineArtifactVersion(argv);
   const preRelease = determinePreRelease(argv);
+  const forceLock = argv['force-lock'] || argv.forceLock || false;
 
   const sources = await buildSources(sourceIdsFromTargetIds(targetIds));
 
@@ -509,7 +527,7 @@ async function generate(argv) {
     const templateDir = customizeTemplates(target);
 
     // run generation
-    exec(`bash -e ${__dirname}/../targets/${target.type}/generate.sh ${VERSION} ${binary} ${CONFIG_FILE_NAME} ${target.id} ${sources[target.source]} ${formatter} ${target.generatorId} ${preRelease.toString()} ${templateDir}`);
+    exec(`bash -e ${__dirname}/../targets/${target.type}/generate.sh ${VERSION} ${binary} ${CONFIG_FILE_NAME} ${target.id} ${sources[target.source]} ${formatter} ${target.generatorId} ${preRelease.toString()} ${templateDir} ${forceLock.toString()}`);
   });
 }
 
@@ -721,3 +739,4 @@ function determineArtifactVersion(argv) {
 function determinePreRelease(argv) {
   return argv.preRelease ? true : false;
 }
+

package/bin/save-lock.js

@@ -0,0 +1,101 @@
+const fs = require('fs');
+const path = require('path');
+const { exit } = require('process');
+
+const { getTargetVersion } = require(`${__dirname}/target-version.js`);
+
+async function saveLock(argv, config, checkTargetId) {
+  const { target } = argv;
+
+  // Validate target
+  checkTargetId(target);
+
+  // Validate target is applicable for save-lock (must be npm-based)
+  const targetObj = config.targets.find(t => t.id === target);
+  if (!targetObj) {
+    console.error(`Error: target '${target}' not found in config`);
+    exit(1);
+  }
+
+  const generateScriptPath = path.join(__dirname, '..', 'targets', targetObj.type, 'generate.sh');
+  let isNpmBased = false;
+  try {
+    if (fs.existsSync(generateScriptPath)) {
+      const scriptContent = fs.readFileSync(generateScriptPath, 'utf8');
+      // Heuristics: target is npm-based if its generate script uses npm
+      isNpmBased = /\bnpm\b/.test(scriptContent);
+    }
+  } catch (_) {
+    // ignore and treat as non-npm-based below
+  }
+
+  if (!isNpmBased) {
+    // Collect npm-capable targets to help the user
+    const npmTargets = config.targets
+      .filter(t => {
+        const p = path.join(__dirname, '..', 'targets', t.type, 'generate.sh');
+        try {
+          if (!fs.existsSync(p)) return false;
+          const s = fs.readFileSync(p, 'utf8');
+          return /\bnpm\b/.test(s);
+        } catch (_) {
+          return false;
+        }
+      })
+      .map(t => t.id);
+
+    console.error(`Error: target '${target}' is not applicable for save-lock. This command only supports npm-based targets.`);
+    if (npmTargets.length > 0) {
+      console.error(`Valid npm targets: ${npmTargets.join(', ')}`);
+    }
+    exit(1);
+  }
+
+  const locksDir = '.oasg';
+  const sourceLockFile = path.join('out', target, 'package-lock.json');
+
+  console.log(`Saving package-lock.json for ${target}...`);
+
+  // Check if source package-lock.json exists
+  if (!fs.existsSync(sourceLockFile)) {
+    console.error(`Error: package-lock.json not found at ${sourceLockFile}`);
+    console.error(`Please run 'oasg generate ${target}' first to create the package-lock.json file.`);
+    exit(1);
+  }
+
+  // Get target version for dependency locking using the abstraction
+  const targetVersion = getTargetVersion(targetObj);
+
+  // Build path based on whether we have a target version
+  let targetLockDir, targetLockFile;
+  if (targetVersion) {
+    targetLockDir = path.join(locksDir, `${target}-${targetVersion}`);
+    targetLockFile = path.join(targetLockDir, 'package-lock.json');
+  } else {
+    targetLockDir = path.join(locksDir, target);
+    targetLockFile = path.join(targetLockDir, 'package-lock.json');
+  }
+
+  // Create target directory
+  if (!fs.existsSync(targetLockDir)) {
+    fs.mkdirSync(targetLockDir, { recursive: true });
+  }
+
+  // Copy package-lock.json
+  try {
+    fs.copyFileSync(sourceLockFile, targetLockFile);
+    console.log(`✓ Package-lock.json saved to ${targetLockFile}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log(`1. Commit the saved lock file to version control:`);
+    console.log(`   git add ${targetLockFile}`);
+    console.log(`   git commit -m "Add/update package-lock.json for ${target}"`);
+    console.log('');
+    console.log('2. This lock file will be used as a fallback if future builds fail due to dependency issues.');
+  } catch (error) {
+    console.error(`Error copying package-lock.json: ${error.message}`);
+    exit(1);
+  }
+}
+
+exports.saveLock = saveLock;

package/bin/target-version.js

@@ -0,0 +1,84 @@
+/**
+ * Utility module for extracting target versions from target configurations.
+ *
+ * This module is used exclusively by the save-lock feature for npm-based projects
+ * to determine version-specific lock file paths.
+ *
+ * Different target types may have different target version extraction strategies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Get the target version for a target.
+ *
+ * This function is used by the save-lock feature for npm-based targets to determine
+ * version-specific paths for storing package-lock.json files in the .oasg directory.
+ *
+ * For npm-based Angular and NestJS targets:
+ * - First checks if ngVersion is overridden in generatorCustomArgs (-p ngVersion=X.X.X)
+ * - Falls back to ngVersion in generator-config.json
+ *
+ * For other npm-based targets (react, typescript-axios, typescript-fetch, contract-testing):
+ * - Returns empty string (no target version, uses target id only for lock file path)
+ *
+ * @param {Object} targetObj - The target object from config
+ * @param {string} targetObj.type - The target type (e.g., 'angular', 'nestjs', 'react')
+ * @param {string} [targetObj.generatorCustomArgs] - Optional custom arguments passed to generator
+ * @returns {string} The target version or empty string if not applicable
+ */
+function getTargetVersion(targetObj) {
+  const targetType = targetObj.type;
+
+  // Only Angular and NestJS have target versions (ngVersion)
+  if (targetType !== 'angular' && targetType !== 'nestjs') {
+    return '';
+  }
+
+  return getAngularNestjsTargetVersion(targetObj);
+}
+
+/**
+ * Get the ngVersion for Angular or NestJS npm-based targets.
+ *
+ * Used by save-lock to create version-specific lock file paths (e.g., .oasg/angular-12.0.0/).
+ *
+ * Priority: 1. generatorCustomArgs override, 2. generator-config.json default
+ *
+ * @param {Object} targetObj - The target object
+ * @returns {string} The ngVersion or empty string
+ */
+function getAngularNestjsTargetVersion(targetObj) {
+  let targetVersion = '';
+
+  // First, check if ngVersion is overridden in generatorCustomArgs
+  if (targetObj.generatorCustomArgs) {
+    const ngVersionMatch = targetObj.generatorCustomArgs.match(/-p\s*ngVersion=(\d+\.\d+\.\d+)/);
+    if (ngVersionMatch) {
+      targetVersion = ngVersionMatch[1];
+      console.log(`Using ngVersion from generatorCustomArgs: ${targetVersion}`);
+      return targetVersion;
+    }
+  }
+
+  // Fall back to generator-config.json if not found in generatorCustomArgs
+  const generatorConfigPath = path.join(__dirname, '..', 'targets', targetObj.type, 'generator-config.json');
+  try {
+    if (fs.existsSync(generatorConfigPath)) {
+      const generatorConfig = JSON.parse(fs.readFileSync(generatorConfigPath, 'utf8'));
+      targetVersion = generatorConfig.ngVersion || '';
+      if (targetVersion) {
+        console.log(`Using ngVersion from generator-config.json: ${targetVersion}`);
+      }
+    }
+  } catch (error) {
+    // Silently ignore - no target version available
+  }
+
+  return targetVersion;
+}
+
+module.exports = {
+  getTargetVersion
+};

package/config.schema.yml

@@ -38,6 +38,7 @@ properties:
         - $ref: '#/targets/Postman'
         - $ref: '#/targets/TypeScriptAxios'
         - $ref: '#/targets/TypeScriptFetch'
+        - $ref: '#/targets/MSW'
 required:
   - targets
 additionalProperties: false
@@ -533,6 +534,20 @@ targets:
           - packageName
           - repository
 
+  MSW:
+    allOf:
+      - $ref: '#/targets/Base'
+      - properties:
+          type:
+            pattern: "^msw$"
+          packageName:
+            type: string
+          repository:
+            type: string
+        required:
+          - packageName
+          - repository
+
 definitions:
   # default
   SourceOverrides:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-supercharge/oasg",
-  "version": "17.1.0",
+  "version": "18.0.0",
   "description": "Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them",
   "author": "Supercharge",
   "license": "MIT",

package/targets/android/generate.sh

@@ -1,4 +1,4 @@
-#/bin/bash
+#!/bin/bash
 
 source $(dirname "$0")/../common.sh
 
@@ -7,7 +7,7 @@ mkdir -p out/$targetId
 
 if [ -z "$formatterCustomArgs" ]
 then
-  formatterCustomArgs="--disabled_rules=no-wildcard-imports,max-line-length,enum-entry-name-case"
+  formatterCustomArgs="--disabled_rules=no-wildcard-imports,max-line-length,enum-entry-name-case,filename,no-empty-file"
 fi
 
 java -jar $binary generate \