hanzoai/jose
2
0
Fork 0
mirror of https://github.com/hanzoai/jose.git synced 2026-09-24 17:00:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

build: simplify generated type documentation

Browse Source 
Render open identifier unions as `string` because their extra arms only
drive editor completion without narrowing accepted values. Fold the
equivalent inline unions as well.

Omit the redundant `JWK = object` and `JWKParameters = object` lines;
their pages list the object members immediately below.

Signed-off-by: Filip Skokan <[email protected]>
This commit is contained in:
Filip Skokan
2026-07-29 18:45:18 +02:00
parent fa8a53f6c5
commit 2bcf40f7be
3 changed files with 33 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/types/type-aliases/JWK.md
-2
View File
@@ -4,8 +4,6 @@
Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
• **JWK** = `object`
JSON Web Key ([JWK](https://www.rfc-editor.org/info/rfc7517/)). "RSA", "EC", "OKP", "AKP",
and "oct" key types are supported.
docs/types/type-aliases/JWKParameters.md
-2
View File
@@ -4,8 +4,6 @@
Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
• **JWKParameters** = `object`
Generic JSON Web Key Parameters.
> [!NOTE]\
tools/docs.cjs
+33 -3
View File
@@ -1,9 +1,24 @@
const { execSync } = require('child_process')
const { globSync, readdirSync, readFileSync, rmSync, writeFileSync } = require('fs')
const { globSync, readdirSync, readFileSync, writeFileSync, rmSync } = require('fs')
const { version } = require('../package.json')
const opts = { stdio: 'inherit' }
// The JOSE identifier unions each carry a `(string & {})` arm, so a plain string stays assignable
// and no call site changes meaning; the enumeration exists to give editors something to complete.
// They are `@ignore`d, which keeps typedoc from giving them pages or listing entries, and what is
// left is the bare name in the signatures that reference them - rewritten to `string` below, since
// that is what they are to a reader.
const openUnions = [
'GenerateKeyPairAlgorithm',
'GenerateSecretAlgorithm',
'JWEContentEncryptionAlgorithm',
'JWEKeyManagementAlgorithm',
'JWKKeyType',
'JWSAlgorithm',
'JWTClaimValidationReason',
]
// docs/README.md is hand-written, typedoc must not clobber it
const readme = readFileSync('docs/README.md')
@@ -17,9 +32,24 @@ execSync(`npm run docs:generate -- --gitRevision v${version}`, opts)
globSync('docs/**/*.md').forEach((file) => {
const content = readFileSync(file, 'utf-8')
const updatedContent = content.replaceAll('\\<`ArrayBufferLike`\\>', '')
.replaceAll('\\<`ArrayBufferLike`\\>', '')
.replace(new RegExp(`\`(?:${openUnions.join('|')})\``, 'g'), '`string`')
// an inline union carrying the arm - "sig" | "enc" | (string & {}) and the like - widens the
// same way, wherever typedoc sorted the arm within it
.replace(
/^(• .*?[:=] )([^=\n]*`string` & `object`[^=\n]*)/gm,
(_, head, union) => `${head}\`string\`${union.endsWith(' ') ? ' ' : ''}`,
)
// and a union of several of them folds to one. The negative lookahead keeps `string` \|
// `string`[] intact, where the second arm merely starts the same way.
.replace(/`string`(?: \\\| `string`(?!\[))+/g, '`string`')
// JWK and JWKParameters are type aliases only so that they carry the implicit index signature an
// interface does not. Their whole type is one object literal, which typedoc states as `object`
// before listing the members under "Type Declaration" anyway - so the line carries nothing an
// interface's page would have had, and goes.
.replace(/^• \*\*\w+\*\* = `object`\n\n/gm, '')
writeFileSync(file, updatedContent, 'utf-8')
writeFileSync(file, content, 'utf-8')
})
writeFileSync('docs/README.md', readme)