Refresh Project

.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  test:
+    name: Lint, typecheck, build & unit test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [ 24, latest ]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      # The precomputed route tree and handler typings are generated from
+      # default-routes.json and committed; fail if they are stale.
+      - run: |
+          npm run precompute-routes
+          git diff --exit-code lib/data/default-route-tree.json lib/data/default-route-handlers.ts
+      - run: npm run build
+      - run: npm run test:unit
+      - if: matrix.node-version == 'latest'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          retention-days: 1
+
+  # Smokes the built artifact under a production-only install (no devDependencies),
+  # which the test job above cannot catch: it verifies dist/ is self-contained and
+  # requires nothing outside the declared runtime dependencies.
+  dist-smoke:
+    name: Published dist works on Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    needs: test
+    strategy:
+      matrix:
+        node-version: [ 24 ]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci --omit=dev
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - run: |
+          node -e "
+            const WPAPI = require('./dist/index.cjs');
+            const wp = new WPAPI({ endpoint: 'http://localhost/wp-json' });
+            if (typeof wp.posts !== 'function') throw new Error('CJS entry did not bootstrap');
+            if (typeof WPAPI.transport.get !== 'function') throw new Error('CJS entry has no bound transport');
+          "
+          node --input-type=module -e "
+            import WPAPI from './dist/index.mjs';
+            const wp = new WPAPI({ endpoint: 'http://localhost/wp-json' });
+            if (typeof wp.posts !== 'function') throw new Error('ESM entry did not bootstrap');
+            if (typeof WPAPI.transport.get !== 'function') throw new Error('ESM entry has no bound transport');
+          "
+          node -e "
+            try { require('./dist/superagent.cjs'); }
+            catch (e) { if (/wpapi.superagent was removed/.test(e.message)) process.exit(0); throw e; }
+            throw new Error('superagent stub did not throw its migration error');
+          "
+
+  integration:
+    name: Integration tests (wp-env)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run env:start
+      - run: npm run env:seed
+      - run: npm run test:integration
+      # `npm run env:logs` defaults to `--watch`, which never exits; pass
+      # `--no-watch` directly so this step prints once and completes.
+      - if: always()
+        run: npx @wordpress/env logs development --no-watch
+      - if: always()
+        run: npm run env:stop

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+# Scaffolded in Phase 1, replacing the local `release-npm` script; not yet
+# exercised until publishing resumes (requires an `NPM_TOKEN` secret).
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  publish:
+    name: Build, test & publish to npm
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          # tsdown/rolldown require Node >=22.18 to run the build itself.
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm run test:unit
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -45,8 +45,5 @@ documentation/index.html
 *.sublime-*
 .ruby-version
 
-# Built files (for use in browser)
-browser/
-
-# Consuming applications should maintain their own lockfile.
-package-lock.json
+# Built files (tsdown output: ESM/CJS/UMD + .d.ts)
+dist/

.prettierignore

@@ -0,0 +1,7 @@
+# Route data: default-routes.json is machine-fetched from a live WP site;
+# default-route-tree.json and default-route-handlers.ts are generated from it
+# by build/scripts/precompute-default-routes.js. Formatting any of these would
+# break the CI staleness check for the generated files.
+lib/data/default-routes.json
+lib/data/default-route-tree.json
+lib/data/default-route-handlers.ts

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+	"useTabs": true,
+	"singleQuote": true,
+	"semi": true,
+	"trailingComma": "all",
+	"printWidth": 90
+}

.scratchpad/bench-startup.mjs

@@ -0,0 +1,69 @@
+// Benchmark default-mode WPAPI startup cost against the built dist/ output.
+// Usage: npm run build && node .scratchpad/bench-startup.mjs [samples]
+//
+// Reports, across N fresh node child processes:
+//   - load: time to require('dist/index.cjs')
+//   - init: time for the first default-mode `new WPAPI(...)` (route parse + factories)
+//   - init2: time for a second instantiation (factories already cached)
+// Plus an in-process micro-benchmark of the default-route bootstrap work itself.
+
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const repoRoot = path.resolve( path.dirname( fileURLToPath( import.meta.url ) ), '..' );
+const samples = parseInt( process.argv[ 2 ], 10 ) || 30;
+
+const childScript = `
+	const t0 = performance.now();
+	const WPAPI = require( ${ JSON.stringify( path.join( repoRoot, 'dist/index.cjs' ) ) } );
+	const t1 = performance.now();
+	new WPAPI( { endpoint: 'http://localhost/wp-json' } );
+	const t2 = performance.now();
+	new WPAPI( { endpoint: 'http://localhost/wp-json' } );
+	const t3 = performance.now();
+	console.log( JSON.stringify( { load: t1 - t0, init: t2 - t1, init2: t3 - t2 } ) );
+`;
+
+const results = [];
+for ( let i = 0; i < samples; i++ ) {
+	const out = execFileSync( process.execPath, [ '-e', childScript ], { encoding: 'utf8' } );
+	results.push( JSON.parse( out ) );
+}
+
+const stats = ( key ) => {
+	const values = results.map( r => r[ key ] ).sort( ( a, b ) => a - b );
+	const mean = values.reduce( ( a, b ) => a + b, 0 ) / values.length;
+	const median = values[ Math.floor( values.length / 2 ) ];
+	return { mean, median, min: values[ 0 ], max: values[ values.length - 1 ] };
+};
+
+const fmt = ( s ) => `median ${ s.median.toFixed( 3 ) }ms  mean ${ s.mean.toFixed( 3 ) }ms  min ${ s.min.toFixed( 3 ) }ms  max ${ s.max.toFixed( 3 ) }ms`;
+
+console.log( `samples: ${ samples } (fresh node process each)` );
+console.log( `require('dist/index.cjs')      ${ fmt( stats( 'load' ) ) }` );
+console.log( `first new WPAPI() (parse)      ${ fmt( stats( 'init' ) ) }` );
+console.log( `second new WPAPI() (cached)    ${ fmt( stats( 'init2' ) ) }` );
+
+// In-process micro-benchmark: repeat the first-instantiation bootstrap work by
+// clearing the module cache so the lazy default-factory cache is rebuilt.
+const microScript = `
+	const distPath = ${ JSON.stringify( path.join( repoRoot, 'dist/index.cjs' ) ) };
+	const ITERATIONS = 200;
+	// Warm up disk cache / JIT with one throwaway pass.
+	let WPAPI = require( distPath );
+	new WPAPI( { endpoint: 'http://localhost/wp-json' } );
+	const times = [];
+	for ( let i = 0; i < ITERATIONS; i++ ) {
+		delete require.cache[ require.resolve( distPath ) ];
+		WPAPI = require( distPath );
+		const t0 = performance.now();
+		new WPAPI( { endpoint: 'http://localhost/wp-json' } );
+		times.push( performance.now() - t0 );
+	}
+	times.sort( ( a, b ) => a - b );
+	const mean = times.reduce( ( a, b ) => a + b, 0 ) / times.length;
+	console.log( JSON.stringify( { mean, median: times[ Math.floor( times.length / 2 ) ] } ) );
+`;
+const micro = JSON.parse( execFileSync( process.execPath, [ '-e', microScript ], { encoding: 'utf8' } ) );
+console.log( `bootstrap micro (200 iter)     median ${ micro.median.toFixed( 3 ) }ms  mean ${ micro.mean.toFixed( 3 ) }ms` );

.scratchpad/type-consumer/README.md

@@ -0,0 +1,17 @@
+# Shipped-declaration consumer check
+
+Strict-mode consumers exercising the generated `dist/*.d.*` typings after
+`npm run build`. `consumer.cts`/`consumer.mts` must typecheck clean (require +
+import paths, constructability, statics, chaining); every line flagged in
+`negative.cts` must error (proves the types reject bad code, which is what
+regressed in Phase 2). The `wp.posts()` negative lines guard the Phase 4
+generated handler typings: if the declaration bundle ever degrades those
+handlers back to `any`, the positives stay clean but these stop erroring.
+
+Usage:
+
+```
+npx tsc --strict --noEmit --skipLibCheck --module node16 --moduleResolution node16 \
+  --target es2020 .scratchpad/type-consumer/consumer.cts .scratchpad/type-consumer/consumer.mts
+npx tsc --strict --noEmit ... .scratchpad/type-consumer/negative.cts  # expect 5 errors
+```

.scratchpad/type-consumer/consumer.cts

@@ -0,0 +1,34 @@
+// Strict-mode consumer exercising the shipped CJS declarations (require path).
+import WPAPI = require( '../../dist/index.cjs' );
+
+const wp = new WPAPI( { endpoint: 'http://example.com/wp-json' } );
+const viaSite = WPAPI.site( 'http://example.com/wp-json' );
+const req = wp.posts().perPage( 5 ).page( 2 );
+const url: string = req.toString();
+const chained = wp.url( 'http://x/' ).auth( { username: 'u', password: 'p' } );
+async function run(): Promise<void> {
+	const posts = await wp.posts();
+	console.log( posts, url, viaSite, chained );
+	const discovered = await WPAPI.discover( 'http://example.com' );
+	console.log( discovered.pages() );
+}
+run();
+
+// The wpapi/fetch alias must expose the same constructable type.
+import WPAPIFetch = require( '../../dist/fetch.cjs' );
+const wpF = new WPAPIFetch( { endpoint: 'http://example.com/wp-json' } );
+console.log( wpF.media().toString() );
+
+// Generated default-route handler typings (Phase 4): mixins and path-part
+// setters chain with WPRequest methods, and namespace() is overloaded for
+// the default namespaces.
+const typedChain: string = wp.posts()
+	.categories( [ 1, 2 ] )
+	.sticky( true )
+	.id( 7 )
+	.toString();
+console.log( typedChain, wp.pages().parent( 3 ).revisions( 12 ) );
+console.log( wp.namespace( 'wp/v2' ).users().me() );
+console.log( wp.namespace( 'oembed/1.0' ).proxy().param( 'url', 'http://x' ) );
+// Handlers registered from custom route data still pass the index signature.
+console.log( wp.namespace( 'someplugin/v1' ).customResource() );

.scratchpad/type-consumer/consumer.mts

@@ -0,0 +1,11 @@
+// Strict-mode consumer exercising the shipped ESM declarations (import path).
+import WPAPI from '../../dist/index.mjs';
+
+const wp = new WPAPI( { endpoint: 'http://example.com/wp-json' } );
+const req = wp.posts().perPage( 5 );
+const url: string = req.toString();
+async function run(): Promise<void> {
+	const posts = await wp.posts();
+	console.log( posts, url );
+}
+run();

.scratchpad/type-consumer/negative.cts

@@ -0,0 +1,8 @@
+import WPAPI = require( '../../dist/index.cjs' );
+const wp = new WPAPI( { endpoint: 'http://example.com/wp-json' } );
+// Each line below should be a type error:
+wp.url( 'x' ).nonexistentMethod();
+const n: number = wp.url( 'x' ).toString();
+wp.url( 'x' ).auth( { username: 42 } );
+wp.posts().nonexistentMethod();
+wp.posts().sticky( 'yes' );