Merge pull request #12 from ismailza/chore/improve-compatibility-validation

ci: validate the published package against Angular 17-22

Author: ismailza

.github/workflows/ci.yml

@@ -8,14 +8,15 @@ on:
 
 jobs:
   build:
+    name: Lint, test & build
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v5
 
       - uses: actions/setup-node@v5
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
 
       - run: npm ci
@@ -28,3 +29,93 @@ jobs:
 
       - name: Build
         run: npm run build
+
+      # Catches an omission that would otherwise only surface after publishing.
+      - name: Verify package contents
+        run: npm run verify:package
+
+      # The compatibility matrix consumes exactly what would be published,
+      # so pack once here instead of rebuilding per Angular version.
+      - name: Pack
+        run: |
+          npm pack --pack-destination "$RUNNER_TEMP" --silent
+          mv "$RUNNER_TEMP"/*.tgz "$GITHUB_WORKSPACE/package.tgz"
+        working-directory: dist/ngx-api-client
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-tarball
+          path: package.tgz
+          retention-days: 1
+
+  versions:
+    # Derived from the library's `@angular/core` peer range so the matrix cannot
+    # drift from what the package claims to support.
+    name: Resolve supported Angular versions
+    runs-on: ubuntu-latest
+    outputs:
+      angular: ${{ steps.derive.outputs.angular }}
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - id: derive
+        run: echo "angular=$(node scripts/check-angular-compat.mjs --list)" >> "$GITHUB_OUTPUT"
+
+  compat:
+    # The workspace builds on the newest Angular, but the package supports a
+    # range of majors. Install the packed tarball into a throwaway consumer
+    # project per combination and type-check, bundle and run it there, so the
+    # supported range is verified rather than asserted.
+    name: Angular ${{ matrix.angular }} / Node ${{ matrix.node }}
+    needs: [build, versions]
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        angular: ${{ fromJSON(needs.versions.outputs.angular) }}
+        node: [22, 24]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node }}
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: package-tarball
+
+      - name: Verify against Angular ${{ matrix.angular }}
+        run: |
+          npm run compat -- ${{ matrix.angular }} \
+            --tarball package.tgz \
+            --report "compat-${{ matrix.angular }}-node${{ matrix.node }}.json"
+
+      # `always()`: a failed combination still belongs in the summary table.
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: compat-result-${{ matrix.angular }}-node${{ matrix.node }}
+          path: compat-*.json
+          retention-days: 1
+          if-no-files-found: ignore
+
+  report:
+    name: Compatibility report
+    needs: compat
+    if: always()
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: compat-result-*
+          path: compat-results
+
+      - name: Publish compatibility table
+        run: node scripts/compat-report.mjs compat-results >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release.yml

@@ -28,7 +28,9 @@ jobs:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
-  # Builds the tarball once so both registries receive identical bytes.
+  # Builds the package once so both registries receive identical contents. Each
+  # publish job packs its own tarball from this directory, so the two must stay
+  # on the same Node — a differing bundled npm changes the shasum.
   build:
     name: Build
     needs: release-please
@@ -39,22 +41,21 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
 
       - run: npm ci
 
       - name: Test
         run: npm test
 
+      # `postbuild` stages LICENSE and CHANGELOG.md, which ng-packagr does not
+      # copy, so this produces the same bytes CI validated.
       - name: Build
         run: npm run build
 
-      # ng-packagr copies README.md but not these.
-      - name: Include LICENSE and CHANGELOG in the package
-        run: |
-          cp LICENSE dist/ngx-api-client/LICENSE
-          cp projects/ngx-api-client/CHANGELOG.md dist/ngx-api-client/CHANGELOG.md
+      - name: Verify package contents
+        run: npm run verify:package
 
       - uses: actions/upload-artifact@v4
         with:
@@ -77,7 +78,7 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: 22
+          node-version: 24
           registry-url: https://registry.npmjs.org
 
       - run: npm publish ./package --provenance --access public
@@ -99,9 +100,9 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: 22
+          node-version: 24
           registry-url: https://npm.pkg.github.com
-          scope: "@ismailza"
+          scope: '@ismailza'
 
       - run: npm publish ./package
         env:

.gitignore

@@ -6,6 +6,9 @@
 /out-tsc
 /bazel-out
 
+# Tarball packed for the Angular compatibility matrix
+/package.tgz
+
 # Node
 /node_modules
 npm-debug.log

CONTRIBUTING.md

@@ -34,7 +34,8 @@ Small bug fixes, documentation improvements, and typo fixes can generally be sub
 
 Make sure you have the following installed:
 
-- Node.js (LTS recommended)
+- Node.js `^22.22.3`, `^24.15.0` or newer — the floor comes from the Angular CLI
+  the workspace builds with, and an older release will refuse to run `ng`
 - npm
 - Git
 
@@ -129,6 +130,37 @@ Run the linter:
 npm run lint
 ```
 
+### Compatibility Checks
+
+The package supports a range of Angular majors, so a change that compiles
+against the workspace's Angular can still break consumers on an older one. CI
+runs these on every push; run them locally when you touch the public API, the
+build setup or `peerDependencies`.
+
+Verify the packaged artifact contains everything it should:
+
+```bash
+npm run build
+npm run verify:package
+```
+
+Verify the package against every supported Angular major — this installs each
+one into a throwaway project, so expect it to take a few minutes:
+
+```bash
+npm run compat
+```
+
+To check a single version while iterating:
+
+```bash
+npm run compat -- 17
+```
+
+See [`compat/README.md`](compat/README.md) for what each check covers and how to
+extend the fixture. When you add a public export, reference it there — an export
+no fixture touches is an export the matrix does not cover.
+
 ## Commit Messages
 
 This project follows the **Conventional Commits** specification.

README.md

@@ -281,9 +281,22 @@ own `ApiSuccessHandler`.
 
 ## Compatibility
 
-Developed and tested against **Angular 21**. The declared floor of `>=17` reflects
-the APIs used — signals and functional interceptors — rather than a range the CI
-matrix currently covers.
+| Requirement       | Supported                                                 |
+| ----------------- | --------------------------------------------------------- |
+| Angular           | 17 · 18 · 19 · 20 · 21 · 22                               |
+| RxJS              | `^7.4.0`                                                  |
+| Peer dependencies | `@angular/core`, `@angular/common`, `rxjs` — nothing else |
+
+Every Angular major above is verified on each push, against the packed tarball
+rather than the source. CI installs the package into a throwaway consumer
+application per version and runs three checks: a type-check against that
+version's Angular types, a production `ng build` — which is what exercises the
+Angular linker over the shipped partial declarations — and a runtime test of the
+injector and the `exports` map. Each combination runs on both Node 22 and 24.
+
+The peer range is bounded (`>=17.0.0 <23.0.0`) deliberately: a new Angular major
+is added only once it has been validated, so the supported range is a tested
+claim rather than an assumption.
 
 ## Contributing
 

compat/README.md

@@ -0,0 +1,54 @@
+# Angular compatibility fixture
+
+The workspace builds on the newest Angular, but `@ismailza/ngx-api-client`
+supports a range of majors. This directory is the consumer project used to check
+that claim against every version in the range.
+
+`scripts/check-angular-compat.mjs` copies these files into a throwaway project
+outside the repo, installs one Angular major plus the packed tarball, and runs
+three checks — each covering something the previous one cannot:
+
+| Check                                 | Catches                                                                                          |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `ngc -p tsconfig.json`                | type-level breaks between the shipped `.d.ts` and that version's Angular types                   |
+| `ng build --configuration production` | Angular **linker** failures over the shipped partial declarations, plus bundler/AOT breakage     |
+| `node smoke.mjs`                      | JIT compilation, injector behaviour and `exports` map resolution — none of which a build reaches |
+
+The supported majors are derived from the library's `@angular/core` peer range,
+so the matrix cannot drift from what is published.
+
+## Running it
+
+```bash
+npm run build
+npm run compat            # every supported major
+npm run compat -- 17 22   # selected majors
+npm run compat -- --list  # the derived matrix, as JSON
+```
+
+## Layout
+
+| File                | Role                                                                   |
+| ------------------- | ---------------------------------------------------------------------- |
+| `src/models.ts`     | domain types standing in for a consumer's own                          |
+| `src/handlers.ts`   | `ApiErrorHandler` / `ApiSuccessHandler` subclasses                     |
+| `src/services.ts`   | a service injecting `ApiService`, calling every verb                   |
+| `src/providers.ts`  | `appConfig` wiring `provideApi()` and the interceptors                 |
+| `src/index.ts`      | barrel — the `ngc` entry point                                         |
+| `src/browser.ts`    | the `ng build` entry point                                             |
+| `tsconfig.json`     | `ngc` config (`skipLibCheck: false`, so the shipped types are checked) |
+| `tsconfig.app.json` | `ng build` config                                                      |
+
+## Editing the fixture
+
+These sources must stay valid on **all** supported majors, so they declare no
+components: standalone semantics changed between v17 and v19, and the library
+ships no declarables anyway. Keep to DI, the public types and the interceptors.
+
+`browser.ts` parks the fixture on `globalThis` deliberately — the application
+builder tree-shakes aggressively, and without a live reference the library would
+be dropped from the bundle, leaving the linker with nothing to do and the build
+proving nothing. `assertBundleLinked()` in the runner guards both directions.
+
+When a public export is added, reference it here — an export that no fixture
+touches is an export the matrix does not cover.

compat/smoke.mjs

@@ -0,0 +1,71 @@
+/**
+ * Runtime smoke test: the published package ships partial (unlinked) Angular
+ * declarations, so importing it under an older runtime exercises that runtime's
+ * JIT compiler. Type-checking alone would not catch a linker/runtime break.
+ *
+ * Also asserts the `exports` map resolves the way consumers rely on it.
+ */
+import '@angular/compiler';
+import { ErrorHandler, Injector } from '@angular/core';
+import {
+  API_BASE_URL,
+  API_PREFIX,
+  API_RETRY_CONFIG,
+  API_VERSION,
+  API_VERSIONING,
+  ApiErrorHandler,
+  ApiLoadingService,
+  ApiSuccessHandler,
+  provideApi,
+} from '@ismailza/ngx-api-client';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const injector = Injector.create({
+  providers: [
+    { provide: ErrorHandler, useValue: new ErrorHandler() },
+    provideApi({
+      baseUrl: 'https://api.example.com/',
+      prefix: 'api',
+      version: 2,
+      versioning: 'url',
+      retry: { maxRetries: 5 },
+    }),
+    ApiLoadingService,
+  ],
+});
+
+assert.equal(injector.get(API_BASE_URL), 'https://api.example.com');
+assert.equal(injector.get(API_PREFIX), 'api');
+assert.equal(injector.get(API_VERSION), 2);
+assert.equal(injector.get(API_VERSIONING).strategy, 'url');
+assert.equal(injector.get(API_RETRY_CONFIG).maxRetries, 5);
+
+// Fallback handlers registered by provideApi() must be constructible.
+assert.ok(injector.get(ApiErrorHandler) instanceof ApiErrorHandler);
+assert.ok(injector.get(ApiSuccessHandler) instanceof ApiSuccessHandler);
+
+// Signal-based loading state.
+const loading = injector.get(ApiLoadingService);
+assert.equal(loading.loading(), false);
+loading.start();
+assert.equal(loading.loading(), true);
+loading.stop();
+assert.equal(loading.loading(), false);
+
+// --- exports map -----------------------------------------------------------
+
+// `./package.json` is exported so tooling can read the manifest.
+const require = createRequire(import.meta.url);
+const manifest = require('@ismailza/ngx-api-client/package.json');
+assert.equal(manifest.name, '@ismailza/ngx-api-client');
+
+// Deep imports must stay blocked: reaching past the entry point would let
+// consumers depend on paths that are free to change between releases.
+await assert.rejects(
+  () => import('@ismailza/ngx-api-client/lib/api.service'),
+  (error) => error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED',
+  'deep imports should be blocked by the exports map',
+);
+
+console.log('runtime smoke ok');

compat/src/browser.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser entry for the `ng build` leg of the matrix.
+ *
+ * The application builder tree-shakes aggressively: without a live reference the
+ * library would be dropped from the bundle and the Angular linker would never
+ * run over its partial declarations, making the build a vacuous check.
+ */
+import { appConfig, OrderService, publicTokens } from './index';
+
+(globalThis as Record<string, unknown>)['__compatFixture'] = {
+  appConfig,
+  OrderService,
+  publicTokens,
+};