feat!: 2024 updates, maintainer handoff proposal

.eslintrc.local.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  overrides: [{
+    files: ['test/fixtures/*.ts'],
+    rules: {
+      'max-len': 0,
+    },
+  }],
+}

.github/workflows/audit.yml

@@ -27,8 +27,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:

.github/workflows/ci-release.yml

@@ -47,8 +47,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:
@@ -77,20 +77,9 @@ jobs:
           - name: Linux
             os: ubuntu-latest
             shell: bash
-          - name: macOS
-            os: macos-latest
-            shell: bash
-          - name: macOS
-            os: macos-13
-            shell: bash
-          - name: Windows
-            os: windows-latest
-            shell: cmd
         node-version:
-          - 22.x
-        exclude:
-          - platform: { name: macOS, os: macos-13, shell: bash }
-            node-version: 22.x
+          - 18.6.0
+          - 18.x
     runs-on: ${{ matrix.platform.os }}
     defaults:
       run:

.github/workflows/ci.yml

@@ -31,8 +31,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:
@@ -54,20 +54,9 @@ jobs:
           - name: Linux
             os: ubuntu-latest
             shell: bash
-          - name: macOS
-            os: macos-latest
-            shell: bash
-          - name: macOS
-            os: macos-13
-            shell: bash
-          - name: Windows
-            os: windows-latest
-            shell: cmd
         node-version:
-          - 22.x
-        exclude:
-          - platform: { name: macOS, os: macos-13, shell: bash }
-            node-version: 22.x
+          - 18.6.0
+          - 18.x
     runs-on: ${{ matrix.platform.os }}
     defaults:
       run:

.github/workflows/post-dependabot.yml

@@ -28,8 +28,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:

.github/workflows/pull-request.yml

@@ -31,8 +31,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:

.github/workflows/release-integration.yml

@@ -15,17 +15,24 @@ on:
         required: true
         type: string
         description: 'A json array of releases. Required fields: publish: tagName, publishTag. publish check: pkgName, version'
+    secrets:
+      PUBLISH_TOKEN:
+        required: true
 
 jobs:
   publish:
-    name: Check Publish
+    name: Publish
     runs-on: ubuntu-latest
     defaults:
       run:
         shell: bash
+    permissions:
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          ref: ${{ fromJSON(inputs.releases)[0].tagName }}
       - name: Setup Git User
         run: |
           git config --global user.email "npm-cli+bot@github.com"
@@ -34,27 +41,29 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:
           node: ${{ steps.node.outputs.node-version }}
       - name: Install Dependencies
         run: npm i --ignore-scripts --no-audit --no-fund
-      - name: Check If Published
+      - name: Set npm authToken
+        run: npm config set '//registry.npmjs.org/:_authToken'=\${PUBLISH_TOKEN}
+      - name: Publish
+        env:
+          PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
+          RELEASES: ${{ inputs.releases }}
         run: |
           EXIT_CODE=0
 
           for release in $(echo $RELEASES | jq -r '.[] | @base64'); do
-            SPEC="$(echo "$release" | base64 --decode | jq -r .pkgName)@$(echo "$release" | base64 --decode | jq -r .version)"
-            npm view "$SPEC" --json
+            PUBLISH_TAG=$(echo "$release" | base64 --decode | jq -r .publishTag)
+            npm publish --provenance --tag="$PUBLISH_TAG"
             STATUS=$?
             if [[ "$STATUS" -eq 1 ]]; then
               EXIT_CODE=$STATUS
-              echo "$SPEC ERROR"
-            else
-              echo "$SPEC OK"
             fi
           done
 

.github/workflows/release.yml

@@ -39,8 +39,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:
@@ -119,8 +119,8 @@ jobs:
         uses: actions/setup-node@v4
         id: node
         with:
-          node-version: 22.x
-          check-latest: contains('22.x', '.x')
+          node-version: 18.x
+          check-latest: contains('18.x', '.x')
       - name: Install Latest npm
         uses: ./.github/actions/install-latest-npm
         with:
@@ -131,7 +131,7 @@ jobs:
         id: comment-text
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: npm exec --offline -- template-oss-release-manager --pr="${{ needs.release.outputs.pr-number }}" --backport="" --defaultTag="latest"
+        run: npm exec --offline -- template-oss-release-manager --pr="${{ needs.release.outputs.pr-number }}" --backport="" --defaultTag="latest" --publish
       - name: Append Release Manager Comment
         uses: peter-evans/create-or-update-comment@v3
         with:
@@ -243,6 +243,10 @@ jobs:
     name: Release Integration
     if: needs.release.outputs.releases
     uses: ./.github/workflows/release-integration.yml
+    permissions:
+      id-token: write
+    secrets:
+      PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
     with:
       releases: ${{ needs.release.outputs.releases }}
 

.gitignore

@@ -29,3 +29,4 @@ tap-testdir*/
 !/tap-snapshots/
 !/test/
 !/tsconfig.json
+!/types/

README.md

@@ -1,60 +1,34 @@
 # @npm/types
 
-Typescript definitions for npm registry content
+Typescript definitions for npm registry endpoints
+
+For example:
 
 ```typescript
 import * as npm from '@npm/types';
 
-const pkg = require('pacote');
-
-pkg.packument('libnpm').then((obj: npm.Packument) => {
-  console.log(obj.name, 'is the name of the package');
-});
-
+fetch('https://registry.npmjs.org/cookie)
+  .then((res) => res.json())
+  .then((obj: npm.Packument) => {
+    // `obj` has proper registry types!
+  })
 ```
 
-## GOAL
-
-Make it easier for typescript users to work with npm registry content! 
-
-![vscode tooltip screenshot](./docs/tool-tip.png)
-
-Types should have comments so documentation on npm object properties can appear in vscode contextual popups.
-
-## types
-
-- npm.PackageJson
-    - the object in the json file you have in your project
-
-- npm.PackageLock
-    - the file generated for you by npm that pins your deps.
-
-- npm.Packument
-    - the document you get from `https://registry.npmjs.org/<package name here>`
-
-- npm.Manifest
-    - the document you get from `curl -H 'accept:application/vnd.npm.install-v1+json' https://registry.npmjs.org/<package name here>`
-
-### subtypes
-
-
-- npm.PackageVersion
-    - the objects in the version fields of Packuments
+## Types
 
-- npm.LockDependency
-    - how package locks describe dependencies and sub dependencies
+### Packument
+Response type for the `https://registry.npmjs.org/:packageName` endpoint
 
-- npm.ManifestVersion  
-    - the version object in an AbbreviatedPackument
+### PackumentVersion
+Response type for the `https://registry.npmjs.org/:packageName/:packageVersion` endpoint.  Also the type of `Packument['versions']` entries.
 
-- npm.Dist
-    - the object in npm.PackageVersion that holds the tarball location and checksums
+### Manifest
+Response type for the `https://registry.npmjs.org/:packageName` endpoint, _when made with the 'Accept: application/vnd.npm.install-v1+json' header_.
 
-- npm.NpmScripts
-    - helpful object with all of the possible npm hooks
+### ManifestVersion
+Response type for the `https://registry.npmjs.org/:packageName/:packageVersion` endpoint, _when made with the 'Accept: application/vnd.npm.install-v1+json' header_.   Also the type of `Manifest['versions']` entries.
 
-- npm.Maintainer
-    - common type for author, maintainers etc used in many objects
+### PackageJSON
+A "loose" definition of the "package.json" file type.
 
-- npm.Repository
-    - string or object of repo data
+> [!NOTE] This is not an authoritative definition of package.json structures.  It is merely a best-effort attempt to define the fields that may appear in `PackumentVersion` structures, are copied from a module's package.json file.

package.json

@@ -2,52 +2,45 @@
   "name": "@npm/types",
   "version": "1.0.2",
   "description": "Typescript definitions for npm registry content",
-  "main": "./dist/commonjs/index.js",
-  "types": "./dist/commonjs/index.d.ts",
+  "types": "./types/index.d.ts",
   "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "import": {
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
-      },
-      "require": {
-        "types": "./dist/commonjs/index.d.ts",
-        "default": "./dist/commonjs/index.js"
-      }
-    }
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "template-oss-apply": "template-oss-apply --force",
-    "lintfix": "npm run lint -- --fix",
-    "snap": "tap",
+    "build": "tsc",
     "lint": "eslint \"**/*.{js,cjs,ts,mjs,jsx,tsx}\"",
+    "lintfix": "npm run lint -- --fix",
     "postlint": "template-oss-check",
-    "test": "tap",
     "posttest": "npm run lint",
-    "prepare": "tshy"
+    "pretest": "npm run build",
+    "template-oss-apply": "template-oss-apply --force",
+    "test": "tap",
+    "snap": "tap"
   },
-  "keywords": [],
+  "keywords": [
+    "npm registry",
+    "types",
+    "typescript",
+    "definitions",
+    "typings"
+  ],
   "author": "GitHub Inc.",
   "license": "MIT",
-  "contributors": [
-    {
-      "name": "Ryan Day",
-      "email": "ryaneday@google.com"
-    }
-  ],
+  "engines": {
+    "node": ">=18.6.0"
+  },
   "devDependencies": {
     "@npmcli/eslint-config": "^4.0.4",
     "@npmcli/template-oss": "4.22.0",
-    "@types/node": "^17.0.31",
+    "@types/node": "20.12.10",
     "@typescript-eslint/parser": "^7.8.0",
     "eslint-import-resolver-typescript": "^3.6.1",
     "tap": "^18.7.3",
     "tshy": "^1.14.0",
     "typescript": "^5.4.5"
   },
   "files": [
-    "dist/"
+    "types/"
   ],
   "repository": {
     "type": "git",
@@ -56,17 +49,12 @@
   "templateOSS": {
     "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
     "version": "4.22.0",
-    "typescript": true
+    "content": "./scripts/template-oss",
+    "publish": true
   },
   "type": "module",
   "tap": {
     "typecheck": true,
     "disable-coverage": true
-  },
-  "tshy": {
-    "exports": {
-      "./package.json": "./package.json",
-      ".": "./src/index.ts"
-    }
   }
 }