openapi-typesafe-migrate 1.0.0-rc.1 → 1.0.0-rc.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +452 -0
- package/LICENSE +0 -1
- package/README.md +249 -23
- package/dist/cli/main.mjs +6804 -546
- package/dist/cli/main.mjs.map +1 -1
- package/package.json +6 -4
package/README.md
CHANGED
|
@@ -10,34 +10,247 @@ npx openapi-typesafe-migrate --write # change the files
|
|
|
10
10
|
|
|
11
11
|
Run it in the project root, with a clean git tree, so you can review the diff.
|
|
12
12
|
|
|
13
|
+
> **Release candidate.** The current version is a 1.0.0 release candidate (`1.0.0-rc.N`);
|
|
14
|
+
> names and output can still change before 1.0.0.
|
|
15
|
+
|
|
13
16
|
Run it with `npx` (or `pnpm dlx`, `yarn dlx`, `bunx`), not as a dependency: it uses TypeScript 6
|
|
14
17
|
(`@typescript/typescript6`), and an npm install of it links the project's `tsc` to TypeScript 6.
|
|
15
18
|
|
|
16
19
|
## What it changes
|
|
17
20
|
|
|
18
|
-
| Where | Change
|
|
19
|
-
| -------------------------------------------------------------------------------------- |
|
|
20
|
-
| Every `package.json`
|
|
21
|
-
| `pnpm-workspace.yaml`
|
|
22
|
-
| `
|
|
23
|
-
|
|
|
24
|
-
|
|
|
21
|
+
| Where | Change |
|
|
22
|
+
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
23
|
+
| Every `package.json` and pnpm's `package.yaml` | `dependencies`, `devDependencies`, `peerDependencies` and `optionalDependencies` get the new names, with the version of this tool, in the style of the old range (see below). `catalog:` stays; a dependency on a local package (`workspace:`, `link:`, `file:`) keeps its name and is reported, and so do the imports of it in the files for which that manifest is the nearest one that declares the name, as Node resolves it. An `npm:` alias of an original package (`"my-fetch": "npm:openapi-fetch@^0.13"`) points at the new package. The keys of `peerDependenciesMeta` and `dependenciesMeta` and the names in `bundleDependencies` get the new names too, and so do bun's `catalog` and `catalogs`. The targets of subpath `imports` (`"#client": "openapi-fetch"`, under any conditions) get the new names; the `#` keys stay. So do the keys and values of the `browser` field (`"openapi-fetch": false`). |
|
|
24
|
+
| `pnpm-workspace.yaml`, `.yarnrc.yml` | Entries of `catalog:` and `catalogs:` (pnpm, Yarn 4.10 and newer), ranges with spaces included. |
|
|
25
|
+
| `deno.json`, `deno.jsonc`, `import_map.json` | Keys of `imports` and `scopes` that name an original package (`openapi-fetch`, `openapi-fetch/`), and their `npm:` values, also in the file a config names as its `importMap` (`"importMap": "./deps.json"`). |
|
|
26
|
+
| `tsconfig.json`, `tsconfig.*.json`, `jsconfig.json` | The `compilerOptions.paths` keys of an original package (`"openapi-fetch/*"`) and its name in `compilerOptions.types`. |
|
|
27
|
+
| Commands (the files are listed below the table) | The `openapi-typescript` command (also as `npx`, `pnpm exec`, `node_modules/.bin/…` or `npm:openapi-typescript`), and the flags it renamed, in that command only: `--immutable-types` / `-it` → `--immutable`, `--support-array-length` → `--array-length`, `--redoc` → `--redocly`, `-ap` → `--additional-properties`. The old package names in install commands (`npm i`, `pnpm add`, `npx -p`, …). |
|
|
28
|
+
| `.github/dependabot.yml` | Every old package name in `dependency-name` and `patterns`. |
|
|
29
|
+
| Sources (`.ts`, `.tsx`, `.js`, `.mjs`, `.cjs`, `.vue`, `.svelte`, `.astro`, `.mdx`, …) | Module specifiers only: `import` / `export … from`, `import()`, `require()`, `require.resolve()`, `import("…")` types and `@import` tags in JSDoc (every block), `declare module`, `/// <reference types>`, and module mocks: `vi.mock()` and the other `vi` / `jest` module methods (`jest.setMock()`, `jest.requireActual()`, …), bun's `mock.module()`. Components: their `<script>` blocks and Astro's frontmatter; MDX: its `import` / `export` blocks. A bundler query stays (`openapi-fetch?url`). |
|
|
30
|
+
| `openapiTS(source, { transform })` calls | When `transform` is the only callback and returns plain `ts.factory` types (or the helper constants), the returns become type text and `irCallbacks: true` is added. The options may also be a `const` of the same file that only this call uses (without a type, the option is `irCallbacks: true as const`, which keeps the type `true` that the call needs); options or a named `transform` function that other code can reach (another use, or an export) are kept and reported. Module constants and imports that only the old returns used are removed; exported ones stay. Names are resolved by scope, so a local constant is never taken for a module one. Options declared as `OpenAPITSOptions` are declared as `OpenAPITSIrOptions` then, and a node type declared for `transform` (its return type, the type of its `const`, a JSDoc `@type` or `@returns`) becomes `string`; a declared type the tool cannot map keeps the `transform`, which is reported. |
|
|
31
|
+
|
|
32
|
+
Commands are read in `package.json` scripts, shell scripts (`.sh`, `.bash`, `.zsh`), husky hooks,
|
|
33
|
+
`Makefile`, `justfile`, `Dockerfile`, CI and other YAML files, Nx `project.json` targets and
|
|
34
|
+
`nx.json` target defaults (also their `configurations`), `deno.json` tasks, pnpm `package.yaml`
|
|
35
|
+
scripts, Task's `Taskfile.yml` (`cmds`, `cmd`, `sh`, `status`, `defer`, `preconditions`),
|
|
36
|
+
pre-commit hooks (`entry` with its `args`), and the `simple-git-hooks`, `lint-staged`,
|
|
37
|
+
`nx.targets` and wireit `command` commands of a manifest, also in `.lintstagedrc*` and `.simple-git-hooks.json`. The
|
|
38
|
+
generator is found behind the usual wrappers too (`npx`, `pnpm exec`, `yarn workspace <name>`,
|
|
39
|
+
`dotenvx run`, `nx exec`, `tsx`, `timeout`, `xargs`, …), and under its Windows names
|
|
40
|
+
(`openapi-typescript.cmd`, `.ps1`, `.exe`, `node_modules\.bin\openapi-typescript.cmd`, and the
|
|
41
|
+
cmd.exe path `node_modules\.bin\openapi-typescript`). A here-document is data, except the one a
|
|
42
|
+
shell runs (`bash <<EOF`, `cat <<EOF | sh`). They are read word by word, the way the shell splits
|
|
43
|
+
them (quotes, `\` line continuations, comments, `&&`, `|`,
|
|
44
|
+
`sh -c "…"`, and the commands inside `if`, `while`, `for` and `{ … }`), so only the generator's
|
|
45
|
+
own flags are renamed, and a script name (`npm run openapi-typescript`) is never changed. A
|
|
46
|
+
Dockerfile's exec form (`RUN ["npx",
|
|
47
|
+
"openapi-typescript", …]`, also after `RUN --mount=…`) is read word by word, and the command line of
|
|
48
|
+
`["sh", "-c", "…"]` as shell text. The items of an exec-form `CMD` are the arguments of the
|
|
49
|
+
exec-form `ENTRYPOINT` of its stage (or of the stage it starts `FROM`), so after
|
|
50
|
+
`ENTRYPOINT ["openapi-typescript"]` the old flags of `CMD ["api.yaml", "-it"]` are renamed, and an
|
|
51
|
+
entrypoint script that may pass them on is reported. A YAML `command` after an `entrypoint` of
|
|
52
|
+
the same map (Compose, GitLab, CircleCI) and Kubernetes `args` after a `command` are read the
|
|
53
|
+
same way; when both are lists, they are one exec-form command, the entrypoint first
|
|
54
|
+
(`entrypoint: ["npx"]` with `command: ["openapi-typescript", "-it"]`, or `command: ["/bin/sh",
|
|
55
|
+
"-c"]` with its script in `args`), and Compose's `$$GEN` there is the container's `$GEN`. A
|
|
56
|
+
Makefile variable that holds the generator (`OAT :=
|
|
57
|
+
openapi-typescript`, also for some targets only, and `GEN := $(OAT)`) is renamed where it is set,
|
|
58
|
+
and the flags after `$(OAT)` (or `$G` for a one-letter name) where it runs; so is an `env` variable
|
|
59
|
+
of a workflow and the flags after `$GEN` or `${{ env.GEN }}` (also GitLab CI `variables`,
|
|
60
|
+
Azure Pipelines `variables`, a map or `- name: / value:` items, with the flags after `$(gen)` or
|
|
61
|
+
`${{ variables.gen }}`, CircleCI, Drone, Woodpecker and Docker Compose `environment`, and
|
|
62
|
+
Taskfile `vars` and `env` with the flags after `{{.GEN}}`), and a Dockerfile `ARG` or `ENV`
|
|
63
|
+
variable and the flags after `$GEN`, and a justfile variable (`gen := "npx openapi-typescript"`)
|
|
64
|
+
and the flags after `{{gen}}` (or `$gen`, when `export`, a `$gen` parameter or `set export` gives
|
|
65
|
+
it to the recipe's shell). In a justfile every string and backtick of an expression is read
|
|
66
|
+
as a command line where it is written: in a value that just computes
|
|
67
|
+
(`env_var_or_default("GEN", "npx openapi-typescript")`, an `if`), in a recipe parameter default
|
|
68
|
+
(`types gen="npx openapi-typescript":`) and in an interpolation; such a value and a parameter (the
|
|
69
|
+
command line can set it) may run another program, so the flags after them are reported. A shell variable that a script, a `run` block or a package.json
|
|
70
|
+
script sets itself (`GEN="npx openapi-typescript"`, also after `export`, `local` or `readonly`,
|
|
71
|
+
and written with a backslash or in several quoted parts, `GEN=npx\ openapi-typescript`, which
|
|
72
|
+
is read as the shell reads it) is renamed where it is set, and the flags after `$GEN` where it
|
|
73
|
+
runs. A command line passed to a program as a variable (`cross-env GEN="npx openapi-typescript
|
|
74
|
+
-it" node gen.js`, `env GEN="…" make`, `$(MAKE) GEN="…"`) is migrated where it is written. Text
|
|
75
|
+
appended to a variable the file does not set before is the value when it runs the generator
|
|
76
|
+
itself (`H+="npx openapi-typescript"`, a Makefile `GEN += npx openapi-typescript`), so it is
|
|
77
|
+
migrated where it is written. Text appended to such a
|
|
78
|
+
variable (a Makefile `GEN += --immutable-types`, a shell `G+=" -it"`, a justfile
|
|
79
|
+
`"npx openapi-typescript" + " -it"`) holds arguments of the program its value runs, so its old
|
|
80
|
+
flags are renamed where they are written, or reported when the variable may run another program;
|
|
81
|
+
a Makefile `+=` after an empty value (`CMD =`) is the value. The word of a default
|
|
82
|
+
(`${GEN:-npx openapi-typescript}`, `${GEN:=…}`, `${GEN:+…}`) is read as a command line where it
|
|
83
|
+
is written, so the old name in it is renamed; the variable may hold another program set outside
|
|
84
|
+
the file, so the flags after such a default are reported, as they are after a default whose
|
|
85
|
+
word is a workflow expression (`${GEN:-${{ inputs.gen }}}`). The same holds for the string literals
|
|
86
|
+
of a GitHub Actions expression (`${{ inputs.gen || 'npx openapi-typescript' }}`), which the runner
|
|
87
|
+
puts into the script before the shell runs, and for the default of an input
|
|
88
|
+
(`inputs.command.default` of an `action.yml`, `workflow_call` and `workflow_dispatch` inputs):
|
|
89
|
+
the old name in them is renamed, and the flags after an expression are reported, because its value
|
|
90
|
+
comes from the run; so are the flags after a variable that an expression sets
|
|
91
|
+
(`GEN: ${{ vars.GEN || 'npx openapi-typescript' }}`, then `$GEN`). A Makefile program that make
|
|
92
|
+
computes (`$(or $(GEN),npx openapi-typescript)`, `$(shell …)`) may run the generator too, so the
|
|
93
|
+
flags after it are reported; the arguments that `$(or …)`, `$(and …)` and `$(if …)` can give, and
|
|
94
|
+
the text of `$(strip …)`, are read as command lines where they are written, so the old name in
|
|
95
|
+
them is renamed. A call of any other make function whose arguments name an old package
|
|
96
|
+
(`$(firstword npx openapi-typescript)`, `$(filter-out …)`, `$(call …)`, `$(shell …)`) is
|
|
97
|
+
reported. A Makefile
|
|
98
|
+
variable set with `?=` (the environment can override it) or to a value that make computes is
|
|
99
|
+
reported the same way where it runs. The flags change only when every definition of the variable
|
|
100
|
+
in the file sets it to the generator: a variable that another Dockerfile stage, a step `env` or a
|
|
101
|
+
later Makefile line or shell assignment sets to another program is reported with its old flags. So is a
|
|
102
|
+
variable that runs a command but that no definition the tool reads sets: one set by another
|
|
103
|
+
`script` item or step (`echo "GEN=…" >> "$GITHUB_ENV"`), a Makefile recipe's `$$GEN`, a bash
|
|
104
|
+
array (`GEN=(npx openapi-typescript)`, whose items are renamed, run as `"${GEN[@]}"`), or one
|
|
105
|
+
set outside the file. A variable of old
|
|
106
|
+
flags that the generator gets (`$(FLAGS)` with `FLAGS := -it`, a justfile `{{flags}}` with
|
|
107
|
+
`flags := '-it'` or a recipe parameter `*flags='-it'`, an exported justfile `$FLAGS`, or
|
|
108
|
+
`${{ inputs.flags }}` with an input default `-it`, also as `${{ github.event.inputs.flags }}`,
|
|
109
|
+
through an `env` value `FL: ${{ inputs.flags }}`, or as a literal in an expression,
|
|
110
|
+
`${{ inputs.flags || '-it' }}`) may serve other commands too, so it
|
|
111
|
+
is reported, not changed. A GitLab variable's `options` are values of the variable. A variable map in a list item
|
|
112
|
+
(a step's `env`) reaches only that item. The defaults of CircleCI `parameters`
|
|
113
|
+
(`<< parameters.gen >>`), GitLab `spec: inputs` (`$[[ inputs.gen ]]`) and Azure Pipelines
|
|
114
|
+
`parameters` (`${{ parameters.gen }}`) are read as input defaults are. A file that a Taskfile
|
|
115
|
+
`includes`, a GitLab local `include` (also with `*` and `**`) or an Azure `template` names is read
|
|
116
|
+
as a file of that kind. A variable that a YAML variable map sets to the generator may run it in
|
|
117
|
+
any file the tool reads (a script that a CI job runs), so the flags after `$GEN` there are
|
|
118
|
+
reported. YAML files are changed only in command
|
|
119
|
+
keys (`run`, `script`, `command`, `entrypoint`, …), in the values of the variable maps above and in input
|
|
120
|
+
defaults, in block and flow style, never in other values. An anchor that an alias uses under such
|
|
121
|
+
a key (`script: [*gen_scripts]`, `env: *common`) is migrated where it is written, once. A CI step whose `shell` is another program (`shell: python`) runs
|
|
122
|
+
code of that language, so its script is not changed, and it is reported when it names an old
|
|
123
|
+
package. The nearest `shell` counts: the step's own, then the job's and the workflow's
|
|
124
|
+
`defaults.run.shell` (GitHub Actions), or the job's `shell` and then the `shell` of the
|
|
125
|
+
executor the job names (`executor: py`, CircleCI). `env` (`/usr/bin/env bash
|
|
126
|
+
-e {0}`) runs the program after it, and `msys2 {0}` and `wsl-bash {0}` run bash. The same holds for a
|
|
127
|
+
justfile recipe whose first line is a shebang for another program (`#!/usr/bin/env python3`), and
|
|
128
|
+
for code given on the command line (`python3 -c '…'`, `node -e "…"`, `ruby -e '…'`). An API description (a YAML document with a top-level `openapi`,
|
|
129
|
+
`swagger`, `asyncapi`, `overlay` or `arazzo` key whose value is a version, such as `openapi: 3.1.0`;
|
|
130
|
+
a CI config such as `.gitlab-ci.yml` or a workflow never is one, so a GitLab job named `openapi`
|
|
131
|
+
is migrated) is data, so it is never changed, not even an
|
|
132
|
+
example `command`, and neither is a YAML file that such a document (YAML or JSON) reaches by
|
|
133
|
+
`$ref`, directly or through other such files (a split layout's `components/schemas/Job.yaml`); a
|
|
134
|
+
YAML file that names no old package is not even parsed. A config that cannot be parsed and names an old package is reported with the
|
|
135
|
+
line and column, not changed. `Makefile`, `justfile` and `Dockerfile` are read only under the names
|
|
136
|
+
make, just and docker look for (also `makefile`, `GNUmakefile`, `Justfile`, `.justfile`,
|
|
137
|
+
`Containerfile` and `*.mk`), so `Dockerfile.dev` is not changed.
|
|
138
|
+
|
|
139
|
+
A range keeps its style: `^` and `>=` give `^1.0.0`, `~` gives `~1.0.0`, an exact version stays
|
|
140
|
+
exact, and a partial version keeps what it fixes (`7`, `7.x` and `0.x` give `^1.0.0`; `0.13` and
|
|
141
|
+
`0.13.x` give `~1.0.0`). A range of several comparators (`>=0.13 <0.18`, `^0.13 || ^0.17`) takes
|
|
142
|
+
the style of its first one. Anything else (`*`, `latest`, an upper bound only, a URL or a file) is
|
|
143
|
+
kept and reported.
|
|
144
|
+
|
|
145
|
+
Manifests, catalogs and import maps are edited in place: only the renamed keys and the new values
|
|
146
|
+
change, and comments, formatting, key order and line endings stay. A byte order mark is kept. An
|
|
147
|
+
entry whose new name is already in the same map is left and reported, and so is an entry the tool
|
|
148
|
+
does not edit (a YAML alias, anchor or block value). A catalog entry and the `catalog:` dependencies
|
|
149
|
+
on it keep one name: an entry stays while a dependency that was left or an override
|
|
150
|
+
(`"openapi-fetch": "catalog:"` under `overrides`, which are reported, not changed) still uses it,
|
|
151
|
+
and a dependency stays while its entry does, so the install never misses a catalog entry; both are
|
|
152
|
+
reported. Sources also get `npm:` specifiers renamed (`import x from "npm:openapi-fetch@^0.13"`).
|
|
25
153
|
|
|
26
|
-
|
|
27
|
-
`.
|
|
154
|
+
In a git repository the tool reads the files git lists: tracked files, and untracked files that
|
|
155
|
+
`.gitignore` does not ignore, so ignored build output (`cjs/`, `esm/`, `types/`, …) stays out. A
|
|
156
|
+
submodule or a nested repository is read the same way, with its own git and its own `.gitignore`.
|
|
157
|
+
Outside a git repository, without `git` (or with git older than 2.31), and in a folder that the
|
|
158
|
+
repository around it ignores, it reads the whole tree of that folder. Either way `node_modules`,
|
|
159
|
+
`.git`, `dist` and the output folders `.next`, `.nuxt`, `.output`, `.svelte-kit`, `.turbo` and
|
|
160
|
+
`coverage` are skipped, and links are not followed. The log names the folders and how each one
|
|
161
|
+
was read.
|
|
162
|
+
|
|
163
|
+
The tool does not trust the folder it migrates. Git is the `git` of an absolute folder on `PATH`
|
|
164
|
+
outside the project and outside every `node_modules` (as written and after links, in any case,
|
|
165
|
+
since macOS and Windows ignore case in folder names), so neither a `git` at the project root nor
|
|
166
|
+
one in a `node_modules/.bin` that `npx` puts on `PATH` runs (npx adds those of the project and of
|
|
167
|
+
every folder above it, such as a workspace root), and it runs with `core.fsmonitor` turned off and every transport refused
|
|
168
|
+
(`GIT_ALLOW_PROTOCOL` set to an empty list, which no `protocol.*` key of a repository's config can
|
|
169
|
+
undo), so a nested repository's `.git/config` cannot make it run a command, not even through a
|
|
170
|
+
partial clone that fetches a missing object. It does not open a bare repository that is not named
|
|
171
|
+
explicitly, and the folder whose `.git` git takes as the repository is the work tree, so a
|
|
172
|
+
`core.worktree` in the config cannot point the listing at another folder; `GIT_DIR` and the other
|
|
173
|
+
variables that name a repository are not passed on. A path that git lists but that leads outside the
|
|
174
|
+
folder (`../`, an absolute path, a linked parent folder or a link to a file elsewhere) is not read
|
|
175
|
+
or written; the report lists it under "Skipped". A file is written as a new file that replaces the
|
|
176
|
+
old one (same mode), so a hard link to a file elsewhere keeps its old text; the log notes it.
|
|
177
|
+
A file whose bytes are not UTF-8 (a Latin-1 source, for example) is not changed, because its
|
|
178
|
+
text cannot be written back without changing other characters; neither is a file that cannot be
|
|
179
|
+
read. The report lists both under "Skipped". So does a file that a bug of the tool would corrupt
|
|
180
|
+
(two of its edits overlap): it is left as it was, the other files are still migrated, and the
|
|
181
|
+
command exits with `1`. Every file is read and migrated before the first one is written. If a write fails, the writing stops, the command exits with `1`, and the report names
|
|
182
|
+
the files written before it and the ones that were not.
|
|
183
|
+
The report and the log show a spec with credentials (`git+https://<token>@…`) as
|
|
184
|
+
`git+https://***@…`; the file keeps it as written.
|
|
28
185
|
|
|
29
186
|
## What it leaves to you
|
|
30
187
|
|
|
31
188
|
The report lists each of these with the file and line:
|
|
32
189
|
|
|
33
|
-
- a version spec it cannot replace (`latest`, a URL, a file, an npm alias
|
|
34
|
-
`
|
|
35
|
-
|
|
190
|
+
- a version spec it cannot replace (`latest`, a URL, a file, an npm alias of another package;
|
|
191
|
+
Yarn's `npm:^0.13.0` is a range and gets the new version), and `overrides` /
|
|
192
|
+
`resolutions` and every other package manager setting (`packageExtensions`,
|
|
193
|
+
`allowedDeprecatedVersions`, bun's `trustedDependencies`, …, in `package.json`,
|
|
194
|
+
`pnpm-workspace.yaml` or `.yarnrc.yml`, patches included) that names an old package, except an
|
|
195
|
+
override that aliases it to its
|
|
196
|
+
successor (`"openapi-fetch": "npm:openapi-typesafe-fetch@^1.0.0"`), which is the migration done;
|
|
197
|
+
- a dependency under an old name on a local package (`workspace:*`, `link:`, `file:`, `portal:`),
|
|
198
|
+
such as a fork in the workspace: it and the imports of it keep the old name, because the new
|
|
199
|
+
name would point at a package the project does not have;
|
|
200
|
+
- a `catalog:` dependency whose catalog entry is outside the folder it migrates (`--root` of one
|
|
201
|
+
package of a workspace), or missing from the workspace: it keeps its old name, because the
|
|
202
|
+
entry is not edited;
|
|
203
|
+
- a patch file of an old package (`patches/openapi-fetch+0.13.0.patch`): the new package has other
|
|
204
|
+
code, so check whether the fix is still needed;
|
|
205
|
+
- a word in a command that names an old package where the tool cannot tell what runs it (an
|
|
206
|
+
argument of a program it does not know, a script name, a one-word variable passed to a
|
|
207
|
+
program such as `make GEN=openapi-typescript`), a generator installed outside the project
|
|
208
|
+
(`/usr/local/bin/openapi-typescript`, `C:\tools\openapi-typescript`), and a Kubernetes `env` item
|
|
209
|
+
(`- name: GEN / value: npx openapi-typescript`), which no shell reads: migrate it by hand;
|
|
210
|
+
- a CI step whose `shell` is another program (`shell: python`), a justfile recipe with a shebang
|
|
211
|
+
for one, or inline code (`python3 -c '…'`) that names an old package: the tool does not read
|
|
212
|
+
code of other languages, so migrate it by hand;
|
|
213
|
+
- an import map that a Deno config names by a URL or a path outside the folder;
|
|
36
214
|
- a renamed peer dependency: users of your package must switch too;
|
|
37
|
-
- `
|
|
38
|
-
|
|
39
|
-
- `
|
|
40
|
-
|
|
215
|
+
- a pnpm `package.json5` that names an old package: the tool does not read JSON5, so rename the
|
|
216
|
+
packages and the command there by hand, or write it as `package.json` and run the tool again;
|
|
217
|
+
- `npx openapi-typescript@<version>`, and pinned old packages in install commands
|
|
218
|
+
(`npm i openapi-fetch@0.13`): change them by hand;
|
|
219
|
+
- a command that runs a file inside the old package
|
|
220
|
+
(`node node_modules/openapi-typescript/bin/cli.js`): run `openapi-typesafe` instead;
|
|
221
|
+
- strings in sources that run `openapi-typescript` (`execSync("npx openapi-typescript …")`, also
|
|
222
|
+
a template such as `` `npx openapi-typescript ${spec}` ``),
|
|
223
|
+
with the command they should become;
|
|
224
|
+
- deep imports such as `openapi-fetch/dist/...` (also subpath import targets and `browser` keys):
|
|
225
|
+
check that the file exists in the new package;
|
|
226
|
+
- imports from the `node_modules` folder of an old package (`../node_modules/openapi-fetch/x.js`),
|
|
227
|
+
and such paths in a tsconfig or in `typesVersions`: import from the new package instead, or
|
|
228
|
+
point the path at its files;
|
|
229
|
+
- Jest patterns that name an old package (`moduleNameMapper`, `transformIgnorePatterns`): make
|
|
230
|
+
them match the new name where they mean the package;
|
|
231
|
+
- a module name built at run time right after an old package name
|
|
232
|
+
(``import(`openapi-fetch${suffix}`)``): the rest may go on with the name, so only you know what
|
|
233
|
+
to write;
|
|
234
|
+
- imports of `openapi-typesafe-helpers` that no `package.json` or Deno import map at or above the
|
|
235
|
+
file lists, also imports that an earlier run renamed: openapi-fetch and openapi-react-query
|
|
236
|
+
installed `openapi-typescript-helpers` with them, the openapi-typesafe packages do not. Add it to the dependencies, or import the types from
|
|
237
|
+
`openapi-typesafe-fetch/helpers`;
|
|
238
|
+
- strings that equal an old package name outside a module specifier (an object key, a label, a
|
|
239
|
+
bundler option such as `external: ["openapi-fetch"]`): they are kept, because only you know
|
|
240
|
+
whether they mean the package. Comments are not changed or reported;
|
|
241
|
+
- `swr-openapi` in your dependencies, until the alias is in place: it takes its client type from
|
|
242
|
+
`openapi-fetch` (a peer dependency), so alias `openapi-fetch` to `openapi-typesafe-fetch` with
|
|
243
|
+
`overrides` or `resolutions` (see
|
|
244
|
+
[Libraries built on openapi-fetch](https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/fetch/index.md#libraries-built-on-openapi-fetch));
|
|
245
|
+
- `transform` callbacks it cannot rewrite (also when their options use a type built from
|
|
246
|
+
`OpenAPITSOptions`, such as `Partial<OpenAPITSOptions>`, or when the type declared for them
|
|
247
|
+
names another type, such as a local alias), and `postTransform` /
|
|
248
|
+
`transformProperty`, also in options that other code shares, and `openapiTS()` calls whose options it cannot see (a
|
|
249
|
+
parameter, a function call). Options that take keys from another object (`{ ...base }`) are read
|
|
250
|
+
through it when the file writes it (`...{ … }` or a `const` with an object), so its callbacks are
|
|
251
|
+
reported and a `transform` in it is kept; a spread of anything else (an import, a call, a `let`)
|
|
252
|
+
is reported, since it may bring callbacks the tool cannot see. They keep working with a
|
|
253
|
+
deprecation warning; see
|
|
41
254
|
[IR callbacks](https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/node.md#ir-callbacks).
|
|
42
255
|
|
|
43
256
|
Then install, regenerate your types and commit them once (the file header names openapi-typesafe
|
|
@@ -45,14 +258,27 @@ now, so `--check` fails until you do), and run your type check and tests.
|
|
|
45
258
|
|
|
46
259
|
## Options
|
|
47
260
|
|
|
48
|
-
| Option
|
|
49
|
-
|
|
|
50
|
-
| `--write`
|
|
51
|
-
| `--root <dir>`
|
|
52
|
-
| `--log <file>`
|
|
261
|
+
| Option | Default |
|
|
262
|
+
| ----------------- | --------------------------------------------------------------------------------------------- |
|
|
263
|
+
| `--write` | Dry run: nothing is written |
|
|
264
|
+
| `--root <dir>` | The current directory |
|
|
265
|
+
| `--log <file>` | A new JSON Lines file in a new private folder in the temporary directory; its path is printed |
|
|
266
|
+
| `--help`, `-h` | Show the help |
|
|
267
|
+
| `--version`, `-v` | Show the version |
|
|
268
|
+
|
|
269
|
+
The default log folder is new for each run and only you can open it (mode 0700). A `--log` file
|
|
270
|
+
that exists gets the new lines appended, and missing parent folders are created.
|
|
271
|
+
|
|
272
|
+
Exit codes: `0` done, `1` the migration failed (the message and the log say why), a file could not
|
|
273
|
+
be written (the report names what was written), a bug of the tool left a file as it was (the report
|
|
274
|
+
lists it under "Skipped"), the project folder does not exist or is a file,
|
|
275
|
+
or the log could not be created (nothing is changed then), `2` unknown option or argument.
|
|
276
|
+
|
|
277
|
+
## Versioning
|
|
53
278
|
|
|
54
|
-
|
|
55
|
-
|
|
279
|
+
Semantic versioning from 1.0.0, with one version for all openapi-typesafe packages. What the
|
|
280
|
+
version promises, and what may grow in a minor release, is listed under
|
|
281
|
+
[Versioning](https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/compatibility.md#versioning).
|
|
56
282
|
|
|
57
283
|
## License
|
|
58
284
|
|