Repository navigation
ci(release): tag pre-releases as alpha via post-publish step - #12
Merged
Merged
Conversation
@changesets/cli refuses `--tag` in pre-release mode (changesets/changesets#942), so the previous fix that added `--tag alpha` to the root `release` script broke the publish step entirely ("Releasing under custom tag is not allowed in pre mode"). Revert the script to `changeset publish` (default tag `latest`) and add a follow-up step in release.yml that walks `steps.changesets.outputs.publishedPackages` and runs `npm dist-tag add <name>@<version> alpha` for each. Freshly published pre-releases land in both `latest` (changesets default, not fought) and `alpha` (our step), so `npm install @nestjs-transactional/<pkg>@alpha` resolves to the newest pre-release again. `publishConfig.tag = "alpha"` stays as declarative metadata for direct `npm publish` callers. The workflow step and the manifest field will become no-ops once we run `pnpm changeset pre exit` before stable 1.0.0.
There was a problem hiding this comment.
Pull request overview
Adjusts the release pipeline to keep using changeset publish in Changesets pre-release mode (where --tag is rejected), while still ensuring npm consumers can install the newest pre-release via the alpha dist-tag.
Changes:
- Reverts the root publish/release scripts to run
changeset publishwithout--tag. - Adds a post-publish GitHub Actions step that iterates
steps.changesets.outputs.publishedPackagesand appliesnpm dist-tag add … alpha. - Adds a changeset documenting the release workflow change and bumping affected packages.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| package.json | Removes --tag alpha from publish/release scripts to avoid Changesets pre-mode rejection. |
| .github/workflows/release.yml | Adds a post-publish step to apply the alpha dist-tag to published versions. |
| .changeset/release-post-publish-alpha-tag.md | Documents the workflow change and triggers patch releases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+77
to
+81
| - name: Tag pre-releases as alpha | ||
| if: steps.changesets.outputs.published == 'true' | ||
| env: | ||
| NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} | ||
| NPM_TOKEN: ${{ secrets.NPM_TOKEN }} |
Comment on lines
+29
to
+30
| callers. Both — the workflow step and the manifest field — become | ||
| no-ops after `pnpm changeset pre exit` for stable `1.0.0`. |
@changesets/cli refuses `--tag` in pre-release mode (changesets/changesets#942), so the previous fix that added `--tag alpha` to the root `release` script broke the publish step entirely ("Releasing under custom tag is not allowed in pre mode"). Revert the script to `changeset publish` (default tag `latest`) and add a follow-up step in release.yml that walks `steps.changesets.outputs.publishedPackages` and runs `npm dist-tag add <name>@<version> alpha` for each. Freshly published pre-releases land in both `latest` (changesets default, not fought) and `alpha` (our step), so `npm install @nestjs-transactional/<pkg>@alpha` resolves to the newest pre-release again. Two guards prevent the step from tagging stable versions as `alpha` after `pnpm changeset pre exit`: 1. `if: hashFiles('.changeset/pre.json') != ''` — primary gate; the file exists only while the cohort is in pre-release mode. 2. Per-version skip on a missing prerelease segment (no `-` in the semver) — safety net for a mixed publish or a misconfigured pre-exit. `publishConfig.tag = "alpha"` stays as declarative metadata for direct `npm publish` callers. The workflow step and the manifest field will become no-ops once we run `pnpm changeset pre exit` before stable 1.0.0.
igorgolovanov
added a commit
that referenced
this pull request
Aug 20, 2026
runInSavepoint emitted raw SAVEPOINT SQL unconditionally. On SQL Server, SAP HANA, MongoDB, Spanner or Cordova the driver rejects that statement, so the caller got an opaque driver-level error that says nothing about NESTED propagation — while the TransactionAdapter contract has always specified IllegalTransactionStateError for this case. The adapter now checks the capability first and throws that error, naming the driver, the capability TypeORM reported, and the propagation modes to use instead. The callback is not invoked, so there is no half-executed nested block. No dialect allowlist: TypeORM reports the capability itself through the public driver.transactionSupport field, with identical values in 0.3 and 1.0. The check stays permissive when the flag is absent — a version that renames or drops it must not turn every NESTED call into a hard failure, since absence of the signal is not evidence of absent support. Adds a contract suite (item A6) pinning the TypeORM internals the transparent-repository patches depend on: plain-assignment `manager` in the Repository constructor (the load-bearing one — a class field or defineProperty would create an own property that shadows the patched getter), delegation through this.manager with this.metadata.target, getRepository on EntityManager.prototype, extend on Repository.prototype, DataSource keeping manager as an own instance property, and the transactionSupport flag the check above reads. Those patches fail silently when a shape moves — repositories quietly run on their own autocommit connection instead of the transaction, and behavioural tests still pass — so the suite imports only `typeorm`, never our own modules (which install the patches on import, convention #12), and each failure names the file to revisit. Verified against both CI matrix cells and probed against a simulated break.
igorgolovanov
added a commit
that referenced
this pull request
Aug 20, 2026
* docs: correct drifted API and SPI contract claims (DD-025) Three claims in the shipped documentation described behaviour the code does not have. No runtime behaviour changes; JSDoc, README and guide text only. `readOnly` and `timeout` on TransactionOptions are documented as unimplemented. Both are accepted by the core and handed to the adapter, but TypeOrmTransactionAdapter forwards only `isolation`. Their JSDoc read as a working feature, which made @readonly and the cqrs module's `defaultQueryOptions: { readOnly: true }` default look like write protection. The options keep their place in the type surface — they are the intended extension point — but nothing claims to enforce them, and known-limitations.md gained an entry. CqrsTransactionalModule's @example no longer violates convention #6. It imported @nestjs/cqrs's CqrsModule alongside CqrsTransactionalModule .forRoot() — the double-import that shadows the EventPublisher override and silently routes aggregate events around the dispatcher. It was the only place in the repository still showing that pattern, and it shipped in the .d.ts. The example also called a non-existent TypeOrmTransactionalModule.forFeature(); it now uses forRoot. The EventPublicationRepository concurrency contract is stated on the right method. Docs and the SPI's own JSDoc required production findReadyForProcessing implementations to use FOR UPDATE SKIP LOCKED "to be safe against concurrent workers". No implementation does — row locking was dropped before release, because a pessimistic lock must be held by a transaction spanning the listener invocation, which is unsafe for user code of unbounded duration. The in-memory reference does not lock either, and the interface contradicted itself: tryClaim's JSDoc also claimed responsibility for preventing double-processing. DD-025 puts the atomicity obligation where it belongs: tryClaim's status check and transition MUST be one indivisible operation, since a read-then-write claim lets two workers both observe PUBLISHED and both dispatch. findReadyForProcessing is documented as deliberately non-exclusive. This matters to anyone implementing the SPI for another datastore — the previous wording pointed the obligation at the wrong method. ADR-007's SPI-contract appendix is amended inline (its decision, the package split, is unaffected). * test(outbox-typeorm): cover the claim contract and schema initializer The package had no unit tests — its repository and schema logic were reachable only through the testcontainers suite. 21 Docker-free specs add coverage for the parts that never needed a database. The DD-025 claim contract is the centrepiece: tryClaim translating TypeORM's `affected` count into won/lost, including that a null or undefined count reads as *lost*. Reading it as success would let every worker dispatch the same publication. Mutation-checked — removing the `?? 0` guard fails exactly these three cases. SchemaInitializer covers the production-safety rules: auto-init off by default, no database probe at all when disabled, existing schema left untouched, and the query runner released even when DDL throws (a leaked runner exhausts the pool, turning a one-off DDL error into an app that cannot serve traffic). Query-builder call shapes for findCompleted/findIncomplete/findFailed are deliberately left to the integration suite — asserting them against a mocked EntityManager would pin mock structure rather than behaviour. * ci: enforce per-package coverage baselines `passWithNoTests: true` in jest.config.base.js meant a package with zero unit tests reported success — outbox-typeorm did exactly that, printing "No tests found, exiting with code 0". Removed, so a package without tests now fails its own test script. Every package declares a coverageThreshold in its jest.config.js, set from measured coverage rather than aspiration: core/cqrs/outbox at 95 statements, typeorm at 90, outbox-microservices at 97, outbox-typeorm at 60. Branches are the weak axis (typeorm 62, outbox-microservices 65) and the honest next target. outbox-typeorm's floors are dominated by src/module/, which the testcontainers suite covers; migrations are excluded from unit coverage since TypeORM's runner executes them. A `coverage` CI job runs test:cov on one cell (Node 22 / TypeORM 0.3 — coverage does not vary by runtime, and the test job already spans the full matrix) and uploads lcov as an artifact. This is the enforcement behind the "coverage has not dropped below baseline" quality gate, which was previously unverifiable. Both failure modes were negative-tested: a violated threshold and a package with no matching tests each exit non-zero. CONTRIBUTING's per-package "coverage targets" were never enforced and did not match reality (outbox-typeorm claimed 85% lines against an actual 59%). Replaced with the enforced floors, documented as ratcheting: raising one is welcome, lowering one is a reviewable decision. Also adds docs/roadmap/improvement-plan.md — the post-alpha assessment this and the preceding commits work through. * feat(outbox): drain in-flight work on shutdown `OutboxProcessingModule.onApplicationShutdown` was synchronous: it set `running = false` and cancelled the next-poll `setTimeout`, but did not await the `processBatch()` already dispatched by the previous tick. NestJS moved on to destroying providers — the TypeORM DataSource among them — so an in-flight `processOne()` writing PROCESSING → COMPLETED could race the pool teardown and strand the row until the staleness monitor recovered it on a later boot. `EventPublicationProcessor.stop()` and `StalenessMonitor.stop()` are now async and await the work in flight; the module hook awaits all of them concurrently, so multi-dataSource deployments do not add up their budgets. An idle worker still resolves immediately. `processor.shutdownTimeout` and `staleness.shutdownTimeout` bound the wait, defaulting to the exported DEFAULT_DRAIN_TIMEOUT_MS (10s, sized so a 30s platform grace period still has room for the pool to close). 0 restores the previous no-wait behaviour. Work abandoned at the deadline is abandoned, not cancelled — there is no safe way to interrupt a half-finished listener invocation. The trade-off is shutdown latency against recovery lag, never durability. Convention #24's user-side OutboxDrainService workaround is retired and deleted from the graceful-shutdown example, which now configures shutdownTimeout instead. Pinned by unit specs for the drain, the timeout, the 0 case and idempotency, plus the graceful-shutdown integration suite against real Postgres; both mutation-checked. * feat(outbox): opt-in automatic retry with backoff (DD-026) Recovery was entirely operator-driven: someone had to call FailedEventPublications.resubmit(), there was no backoff, and nothing consumed completionAttempts, so a permanently failing publication could be resubmitted forever. Checking the Spring Modulith reference while designing this corrected the assessment's framing: Spring Modulith has no automatic retry or dead-letter state either. Its model is the one we already had. This is therefore a deliberate step past parity, not a parity fix — and it is opt-in, off by default (retry.maxAttempts = 0, following the same "0 disables" convention as StalenessConfig). OutboxRetryScheduler is a per-dataSource worker shaped like StalenessMonitor, started and drained by OutboxProcessingModule. It is layered over FailedEventPublications.resubmit(), passing a backoff predicate as the filter, so there is one resubmission code path and anything it does a user can do from their own cron. No sixth lifecycle state: a publication that exhausts its attempts stays FAILED and stays queryable, so the cap bounds the automatic path only. Deferred rather than refused — status is a plain varchar(32), so an ABANDONED state can be added later without a migration. Backoff needs no schema change: eligibility is measured from lastResubmissionDate ?? publicationDate, exact from the second retry onward. The one imprecision — a long-lived publication that just failed is immediately due for its first retry — is documented in DD-026. Also removes ResubmissionOptions.maxInFlight (item A5), declared but never read and absent from Spring Modulith. BREAKING for that option. * docs: repoint 20 rotted relative links and gate them in CI Twenty relative markdown links pointed at files that do not exist — mostly example READMEs citing an ADR or DD by a guessed slug (019-single-unit-atomicity.md for 019-hybrid-delivery-atomicity.md, and so on). Nothing failed, so they had accumulated unnoticed; they surfaced while verifying links during improvement-plan item C1. Eighteen were path fixes, with the link text checked against each target's actual title; DD-023's text is aligned to the document's real subject for consistency with the one README that already had it right. Two needed a decision rather than a slug swap. The text "dataSource name as primary identifier" describes DD-020, not the DD-021 its number claimed — DD-020 is also the more useful pointer for a read-write separation example than DD-021's adapter-constructor detail. docs/architecture/cqrs-integration.md never existed, and the nearest name match is about outbox↔cqrs bridging, which neither citing example uses; both now point at packages/cqrs/README.md, which actually documents the integration. ADR-020's dangling link was a plan, not a typo: the three scope specs it scheduled under packages/cqrs/test/integration/ shipped as one colocated suite instead. Noted where they landed rather than silently rewriting the path. scripts/check-doc-links.sh now gates this in CI as the doc-links job — plain shell over git ls-files, no install and no build, so it fails fast. Writing it exposed one more latent break: ADR-020 cited node_modules/.pnpm/@nestjs[email protected]_<hash>/..., which resolves only on an installed tree and rots on every version bump. Those two citations now point upstream, and the guard was verified against a checkout with no node_modules. * docs: drop internal phase references from user-facing docs * feat(cqrs): add CqrsTransactionalModule.forRootAsync Core and typeorm already had forRootAsync; cqrs did not, which made it the one module you could not configure from a ConfigService. It now mirrors their shape: structural flags on the options object, value-shaped config from the factory. useTransactionalEventPublisher stays on the options object rather than the factory result — it decides whether the EventPublisher override provider is registered at all, and NestJS needs provider tokens at module-definition time, before any async factory runs. Same split OutboxModule.forRootAsync uses for `repository` (convention #21). Both paths now share one defaults resolver and one provider-matrix builder, so they cannot drift; a spec asserts they produce identical exports and provider counts. The `exports: exportTokens as never[]` cast is gone, replaced by a typed InjectionToken[]. Two things the new specs caught. Naming the local array `exports` breaks the module at runtime: in the CommonJS output it shadows the module-level exports object, and the local const's TDZ makes every earlier `exports.X = ...` assignment throw. And `module.get(EventPublisher)` from a root non-strict scope returns CqrsModule's own publisher rather than the override — in both forRoot and forRootAsync — because the override reaches consumers through this module's exports, the same mechanism behind convention #6. Structural assertions on the returned DynamicModule are the reliable test; the behavioural coverage stays in the E2E spec. Also documents why the @nestjs/cqrs peer stays at ^11 while every other peer here accepts ^10 || ^11 (item A3). The wrapping mechanism would work on v10 — the metadata constants are identical across majors — but AsyncContext is a v11 addition and it is what makes the documented request-scoped handler support work. v10 also peers on @nestjs/common ^9 || ^10, so anyone pinned to it is on NestJS 10 anyway. * feat(typeorm): reject NESTED on drivers without savepoint support runInSavepoint emitted raw SAVEPOINT SQL unconditionally. On SQL Server, SAP HANA, MongoDB, Spanner or Cordova the driver rejects that statement, so the caller got an opaque driver-level error that says nothing about NESTED propagation — while the TransactionAdapter contract has always specified IllegalTransactionStateError for this case. The adapter now checks the capability first and throws that error, naming the driver, the capability TypeORM reported, and the propagation modes to use instead. The callback is not invoked, so there is no half-executed nested block. No dialect allowlist: TypeORM reports the capability itself through the public driver.transactionSupport field, with identical values in 0.3 and 1.0. The check stays permissive when the flag is absent — a version that renames or drops it must not turn every NESTED call into a hard failure, since absence of the signal is not evidence of absent support. Adds a contract suite (item A6) pinning the TypeORM internals the transparent-repository patches depend on: plain-assignment `manager` in the Repository constructor (the load-bearing one — a class field or defineProperty would create an own property that shadows the patched getter), delegation through this.manager with this.metadata.target, getRepository on EntityManager.prototype, extend on Repository.prototype, DataSource keeping manager as an own instance property, and the transactionSupport flag the check above reads. Those patches fail silently when a shape moves — repositories quietly run on their own autocommit connection instead of the transaction, and behavioural tests still pass — so the suite imports only `typeorm`, never our own modules (which install the patches on import, convention #12), and each failure names the file to revisit. Verified against both CI matrix cells and probed against a simulated break. * feat(typeorm): enforce readOnly on Postgres-family dialects (DD-027) TransactionOptions.readOnly had been declared since the core package shipped but never honoured — @readonly() and the cqrs defaultQueryOptions default documented intent while a stray write committed anyway. The adapter now issues SET TRANSACTION READ ONLY as the transaction's first statement on postgres, cockroachdb and aurora-postgres, so the database refuses the write. It stays a hint, and enforcement is per-dialect. MySQL is not merely unimplemented but unimplementable: SET TRANSACTION there applies to the next transaction and raises ERROR 1568 inside a started one, so read-only must be given as START TRANSACTION READ ONLY — a moment TypeORM never exposes. Other dialects get a silent no-op rather than an error, because the cqrs module defaults every query handler to readOnly: true and throwing would break consumers on an option they never set. Researching this also corrected the premise: readOnly is a hint in Spring too, where the benefit comes from Hibernate's FlushMode.MANUAL. TypeORM has no unit of work, so there is no equivalent optimisation — "declared but not enforced" had been at parity all along and only the JSDoc oversold it. timeout stays declared and deliberately not approximated. Postgres' statement_timeout bounds each statement rather than the transaction, so timeout: 5000 on a method issuing four queries would allow twenty seconds. It remains in the surface as the extension point for adapters whose driver has a real transaction budget — Prisma's $transaction accepts exactly that. An explicit dialect allowlist was unavoidable: unlike the savepoint check, TypeORM publishes no capability flag for transaction access mode. The adapter says so, and the list needs review when a driver is added. Pinned by per-dialect unit specs (including that the statement precedes any user query, which Postgres requires) and by integration tests against real Postgres: the write is refused, reads still work, read-only does not leak into the next transaction on the same pooled connection, and a nested savepoint inherits it. * chore(deps): develop and test against TypeORM 1.1.0 The lockfile now pins typeorm 1.1.0 and the two adapter packages declare it as their devDependency. The peer range is untouched: `^0.3.0 || ^1.0.0` already admitted 1.1.0, so nothing changes for consumers except that the version is verified rather than merely permitted. No production code needed changing — the prototype-patching contract tests, the driver.transactionSupport check behind NESTED and SET TRANSACTION READ ONLY all hold on 0.3.31, 1.0.0 and 1.1.0. Two problems surfaced on the way. `@nestjs-transactional/cqrs` used typeorm, @nestjs/typeorm, @nestjs/testing and @nestjs-transactional/typeorm in its specs without declaring any of them, resolving them through the workspace's `public-hoist-pattern[]=*` instead. That worked only while every package happened to resolve the same TypeORM copy. With two versions in the tree its E2E suite built a DataSource from one copy and looked the token up from the other — getDataSourceToken() returns the DataSource class itself for the default source, so class identity decides — and Nest could not resolve the provider. Declared, and audited across every package: cqrs was the only offender. The examples move for the same reason rather than for tidiness. Left on 0.3.x they break against packages developed against 1.1.0, exactly as the cqrs spec did; basic-transactional reproduced it. All 17 move to ^1.1.0 with no source changes. CI's matrix legs derived the `0.3` version from the lockfile instead of naming it, so bumping the lockfile would silently have turned that leg into a duplicate of the 1.1.0 one. Every leg now names its exact version — 0.3.31 (newest 0.3.x), 1.0.0 (floor of ^1.0.0), 1.1.0 (current) — and a post-install step asserts the version that actually resolved. That guard matters because the override is a silent mechanism: pnpm 10 no longer reads `pnpm.overrides` from package.json, and an ignored override would leave a leg claiming a compatibility it never exercised. Also corrects AGENTS.md, which still advertised a `typeorm ^0.3.25` peer, and both adapter READMEs, which described the matrix as "both majors". * ci: build and test the example apps All 19 example apps were excluded from every CI job by the `--filter './packages/*'` every job applies, so they could break against a library change and nobody would find out until someone ran them by hand. The new `examples` job builds the packages, builds all 19 examples, runs their unit tests, and runs the 14 `test:integration` suites against testcontainers Postgres. The gap was not hypothetical: the TypeORM 1.1.0 bump broke examples/basic-transactional at runtime — two TypeORM copies in one workspace, so `getDataSourceToken()` resolved against the wrong DataSource class — and no CI job covered it. One job rather than three. The useful work is about 30 seconds; the install and the package build dominate, and splitting build from test from integration would pay for both three times over. Deliberately off the TypeORM matrix, and the job records why: the examples declare `typeorm ^1.1.0` while the matrix legs force their version through a repo-wide pnpm override, which would put two TypeORM copies in the workspace and reproduce that very failure. Peer-range coverage is the matrix's job; this one asks whether an ordinary consumer app still builds and runs. No broker service is needed. Every example integration suite starts `postgres:16-alpine` through testcontainers and mocks ClientProxy, so the externalization examples' docker-compose.yml files stay what they are — fixtures for `pnpm start`. The Postgres image is already pulled by the library's integration job. Verified by running the job's steps in order from a clean `dist/`: 19 builds, 26 unit tests across 6 examples, 65 integration tests across 14. * chore: close the release-readiness backlog before 1.0.0 Everything here is repository hygiene with no effect on runtime behaviour, but two of the items were not the mechanical changes the plan assumed. `format:check` had shipped in package.json since the first release and had never run in CI, so the tree drifted: 76 files failed it. Enabling the gate meant reformatting 72 source files, and it also meant narrowing Prettier's scope. Prettier does not tidy hand-wrapped prose, it rewrites it — on AGENTS.md it turned a continuation line starting with `+` into a `-` list item, changing what the sentence said, and it pads every markdown table to its widest cell, defeating the wrapping the rest of the file depends on. Root markdown therefore joins `docs/` and CLAUDE.md in .prettierignore: formatting is enforced on code, prose stays hand-wrapped. eslint-config-prettier already disabled ESLint's formatting rules, so Prettier was always meant to own this. `sideEffects` is declared on every published package but deliberately not uniformly, because the uniform answer would have been false. core, cqrs, outbox and outbox-microservices have no import-time statements and declare false. packages/typeorm calls applyAllPatches() at module load — that is how the Repository.prototype patches behind transparent transactional repositories get installed — so it lists that file instead. A blanket false would let a bundler drop the module when a consumer imports only getCurrentEntityManager, and the patches would never install: repositories would keep working and would silently stop being transactional. outbox-typeorm's @entity() decorators register into TypeORM's global metadata storage when the entity modules are evaluated, so its entity files are listed too. The Node floor moves up. .nvmrc pinned 20 against an engines floor of >=22.11.0; it is now 22, matching CI's node-version, and the root floor becomes >=22.13.0 — the real development floor, since TypeORM 1.x requires ^22.13.0 on the 22 line. Both adapter packages already said so; the root and CONTRIBUTING still said 22.11. Community health files, none of which existed: SECURITY.md, CODE_OF_CONDUCT.md, CODEOWNERS, two issue forms with a config, and a PR template. The bug-report form asks for the dialect and whether the deployment is multi-dataSource, because both change the answer — readOnly is enforced only on the Postgres family (DD-027) — and points at known-limitations.md and ADR-016 up front, since a fair share of reported bugs here are documented trade-offs. SECURITY.md also records the data-at-rest footprint: serialized payloads and listener exception messages persist in event_publication until purged. Not a vulnerability, but not something to meet by surprise. The code of conduct adopts the Contributor Covenant by reference rather than pasting it. Dependabot runs weekly for npm and github-actions, grouped so a NestJS or ESLint bump arrives as one PR rather than a dozen that each fail until the others land. typeorm is on the ignore list on purpose: which version the lockfile pins is tied to the CI matrix and to what the examples declare, so a bot bumping it would quietly change what the matrix means. Major bumps of the @nestjs peers are ignored for the same kind of reason — those are peer-range decisions needing a changeset and a compatibility argument, not upgrades. CodeQL runs the security-and-quality pack with no build step; the javascript-typescript extractor reads the sources directly. husky, lint-staged and commitlint cover the local side. pre-commit formats exactly the file set the `format` job checks, so the hook and the gate cannot disagree. ESLint is deliberately absent from it: its type-aware rules resolve cross-package imports through dist/*.d.ts, so running it would mean building six packages on every commit. commitlint relaxes three defaults, each because the default rejected commits this history actually contains — header-max-length raised to 120 (three headers run 103-108), subject-case disabled (subjects legitimately open with identifiers: "ADR-019 — ...", "OutboxTypeOrmModule reshape ..."), and the body/footer line caps disabled so URLs need not be broken. No scope-enum: the history uses 19 distinct scopes, including combined ones like cqrs,outbox. publint and @arethetypeswrong/cli are NOT added — the dependencies were not approved. ADR-004 has claimed since before the first release that both run in CI and are non-negotiable parts of the release process, and recorded them as added in Phase 4. Neither was ever wired up, and six alpha releases shipped under that claim. The ADR now states that plainly rather than continuing to assert it, and says what actually guards `exports` today: review, plus a type-check job that compiles the sources and says nothing about what a consumer resolves from the published tarball. Two additions need a repository setting before they do anything: private vulnerability reporting must be enabled for the SECURITY.md link to resolve, and CODEOWNERS only gates merges once branch protection requires code-owner review. Verified after the reformat: format:check and lint:doc-links clean, --frozen-lockfile installs, every added YAML parses, build and lint 6/6, tsc clean, 687 unit tests against their coverage thresholds, 76 integration tests, and all 19 examples (19 builds, 6 unit suites, 14 integration suites). Hooks exercised for real — lint-staged reformatted a deliberately misformatted staged file and re-staged it, and commitlint was checked against six cases including the long and identifier-leading headers from this history. * build: guard the public API surface with api-extractor ADR-004 promises API stability and has been enforcing it by hoping a reviewer notices a changed export. api-extractor now reports the signature of every entry point into packages/<name>/etc/*.api.md, those reports are committed, and the api-surface CI job regenerates them from the built .d.ts and fails on any difference. `pnpm api:update` accepts an intended change, and the resulting diff belongs in the PR next to the changeset that classifies it as major, minor or patch. Eight reports, not six: api-extractor covers one entry point per run, and core and outbox each publish a ./testing subpath as well. 1658 lines in total. Baselined deliberately before the stable 1.0.0. Taken later the first diff would have had nothing meaningful to compare against, and the surface 1.0.0 actually froze would never have been recorded anywhere. Two message rules are silenced, each checked rather than assumed. ae-unresolved-link fired 13 times in core alone, always on the `{@link member}` shorthand for a sibling of the same class or enum — getActiveTransaction, code, REQUIRED — which are real members that resolve in IDE tooltips; api-extractor only resolves package-level exports. ae-missing-release-tag is off because ADR-004 draws the public/internal line by entry point rather than with @public tags, so it would fire once per export and say nothing. ae-forgotten-export stays on, and reports nothing across all six packages: no public signature references a type a consumer cannot name. Verified by mutation — adding one exported interface makes api:check exit 1. Worth checking, because api-extractor calls a changed surface a *warning* and prints "completed with warnings", so the output reads benign and only the exit code is unambiguous. temp/ is gitignored: that is where api-extractor writes the freshly-generated report it diffs the committed baseline against. Nothing here reaches consumers — `npm pack --dry-run` on core lists 77 files, all from dist/, with no etc/ and no config. ADR-004 records what this does and does not cover. The gap left by the still-absent publint and @arethetypeswrong/cli is narrower now but not closed: api-extractor reads the built declarations, so it sees what the sources declare, while whether a consumer resolves them through the exports map remains verified by review alone. * fix: resolve the /testing subpath under node10 module resolution publint and @arethetypeswrong/cli now run in CI via the publish-check job, and attw found a real defect on its first run. @nestjs-transactional/core/testing and @nestjs-transactional/outbox/testing did not resolve to their type declarations under node10 resolution — what TypeScript selects for module: commonjs when a project does not name moduleResolution, and so what a stock NestJS tsconfig gets. TypeScript's own message was explicit: "There are types at .../dist/testing/index.d.ts, but this result could not be resolved under your current 'moduleResolution' setting." node10 predates exports maps and looks for <pkg>/testing/ on disk. A documented entry point, unusable for a large share of consumers, across six alpha releases. Fixed with typesVersions. Runtime was never affected — Node honours exports regardless of the TypeScript setting — so the defect was types-only, which is why nothing else caught it: the packages' own tsconfig.base.json uses moduleResolution: node but imports ./testing by relative path, and the examples override to Node16. Neither configuration could hit it. Reproduced against a throwaway consumer project before and after the fix. publint reported no errors but two manifest gaps on all six packages: no "type" field, now "commonjs" so Node is not left to detect it, and a repository.url missing the canonical git+ prefix. Both gates mutation-tested, because a tool that prints a problem and exits 0 is not a gate. Removing typesVersions makes attw exit 1; pointing an exports target at a nonexistent file makes publint exit 1. Notably publint exits 0 for the missing typesVersions and attw says nothing about a dangling exports target — the two cover different ground rather than overlapping. ADR-004 had asserted since before the first release that both tools ran in CI and were non-negotiable parts of the release process. They now do. The Tooling section describes what each one actually covers, and the note kept in Notes is not about these two tools: a decision record asserting that a check exists is exactly as useful as no check, and reads better. * docs: rewrite every package README These are the pages npm renders, and they had drifted far enough that rewriting beat editing. Six factual defects, found by checking each snippet against the api-extractor surface reports: - core showed `timeout: 10_000` in an options example. timeout is accepted by the type and not implemented (DD-027). - outbox's primary wiring snippet passed `adapters: [...]` to TransactionalModule.forRoot. No such option exists — it is `adapter`, singular — so the first thing a reader copies did not compile. - typeorm told readers to import `@nestjs-transactional/typeorm/test/setup-testcontainers`. Nothing under test/ is published, so that path cannot resolve. - outbox-typeorm documented OutboxTypeOrmModule.forFeature and an isDefault option, neither of which exists, and described the module wiring as arriving "in a later iteration" two paragraphs above documenting it. Its install heading still read "(once published)". - All six claimed the API "may change between 0.x releases" while shipping as 1.0.0-alpha.x. - All six linked documentation with relative paths — seventy links, dead on npmjs.com, which renders a README outside the repository tree. All six now follow one shape: what it is, a snippet that runs, how it relates to the sibling packages, then the specifics, then links out. They lead with working code instead of an inventory of internals — core used to open with a twenty-line list of its own classes. Total length drops from 2280 lines to 1147. The caveats that cost people production incidents are kept and made prominent rather than trimmed for brevity: importing CqrsModule twice shadows the EventPublisher override and events silently stop arriving; omitting `repository` leaves the in-memory outbox default installed, so publications vanish on restart with no error; readOnly is enforced only on Postgres-family dialects; ClientProxy.emit() cannot report a broker failure. Links are absolute now, which npm requires but check-doc-links.sh did not cover. The script now resolves `blob/main/<path>` and `tree/main/<path>` back to repository paths, so the most-read documents in the project are no longer the only ones nothing verifies. Confirmed by mutation: a link to a nonexistent DD fails the run. Three types found by ae-forgotten-export while verifying the examples are also exported, since each appeared in a public signature a consumer could call but not name: CqrsTransactionalAsyncOptions (and its factory result), AggregateConstructor, RegistrarListenerEntry. Every main entry point is now clean; the eleven remaining warnings are all in /testing reports, where api-extractor's one-entry-point-at-a-time analysis cannot see that the main entry exports the type. * chore(release): leave the alpha series for stable 1.0.0 The README blockquote saying the API "may still change before 1.0.0" was the visible half of it. Alpha was asserted in nine places, and removing one line would have left the rest contradicting the release. - All six package READMEs: the alpha notice is gone, and the npm badges no longer point at the `alpha` dist-tag — same for the six badges in the root README and the "(alpha)" labels in its phase table. - docs/roadmap/README.md described the framework as "alpha / in-development. Public API not yet stable; breaking changes are accepted between 0.x releases". That was wrong twice over: the cohort never sat on 0.x, it shipped as 1.0.0-alpha.N from the start. - AGENTS.md carried "(alpha)" tier markers on three packages, a "Last update" describing the first alpha publish, and a next-step bullet proposing `pre exit` "when the API stabilises" — which is now. - SECURITY.md listed 1.0.0-alpha.x as the supported line. It is 1.0.x, with prereleases unmaintained. - ADR-004 wrote minor as `0.x.0` and patch as `0.0.x`, framed its pre-1.0 section as the current phase, and noted that it "predates the actual 1.0 release (still pending)". The pre-release section is now marked historical and the notation matches a 1.x project. - publishConfig no longer pins `tag: "alpha"` in any package, so publishing goes to `latest` and `npm install` resolves without an explicit @Alpha. - `changeset pre exit`: pre.json moves to mode "exit". Verified rather than assumed, because getting the number wrong is unrecoverable once published: `changeset status` reports a major bump for all six against a current version of 1.0.0-alpha.5, which raises the question of whether that lands on 1.0.0 or skips to 2.0.0. Ran `changeset version` locally with the plain changelog generator, read the result — 1.0.0 for all six — and restored the tree. semver treats any increment of a 1.0.0 prerelease as 1.0.0. Note for whoever runs the release: `changeset version` fails locally because @changesets/changelog-github wants a GitHub token; CI supplies one. And pre-release mode retains consumed changesets by design, so all 22 land in the 1.0.0 changelog — the release notes cover the whole alpha series rather than just the last iteration. * ci(release): gate the publish on packaging correctness release.yml ran build and unit tests and then published. Neither of the checks that look at what actually ships was in the release path: both live in ci.yml, which gates pull requests — a different event. A push straight to main, or a merge that landed before required checks were configured, reaches the release workflow without ci.yml having run at all. `api:check` and `publish:check` now run after Build and before changesets/action, so a mismatch stops the release rather than shipping. publish:check is the one that belongs here rather than only in CI: publint and attw inspect the packed tarball, and on the publish run the versions have already been bumped, so they see exactly what a consumer will resolve. That is the check that found `/testing` to be unresolvable under node10 resolution after six releases had shipped it. Verified against both states the workflow encounters, since a gate that only passes in the state it was written in is not a gate: the version run (1.0.0-alpha.5 with 23 pending changesets) and the publish run (1.0.0, changesets consumed, pre.json gone). Both pass — the second reproduced by running `changeset version` locally, rebuilding, running the gates, and restoring. The duplication with ci.yml is deliberate and the step says so, so it does not get "cleaned up" later. * test(examples): wait for the emits the assertions read The `Examples` job — new, and required as of this commit's ruleset — failed on its first PR run in externalization-multi-broker: "routes RefundRequestedEvent to RabbitMQ ONLY" expected Redis to have emitted `cache.invalidated` and got an empty list. One placeOrder produces three publications — OrderPlaced to Kafka, RefundRequested to RabbitMQ, CacheInvalidation to Redis — and the worker externalizes them concurrently within a batch, so completion order is arbitrary. The test awaited only RabbitMQ's emit and then asserted on the Kafka and Redis call lists. Locally the batch always finished first; on a CI runner it did not. Both spots in the file are fixed the way the other tests there already do it: await the mock calls the assertions read. The first test had the narrower version of the same race — it awaited the local cache handler while asserting on redis.emit, and externalization runs after the local listener completes (DD-019 ordering). Attempting a deterministic repro with maxConcurrent: 1 did not reproduce it — sequential processing happens to order the emits favourably. The fix therefore rests on the causal chain plus the CI log rather than a local repro: the assertion read mock state it never waited for. Scanned every example suite for the same shape. Three other hits were false positives: a negative assertion needs no wait, and e-commerce-orders does wait, via .some() rather than .length. * docs: rewrite the root README around the reader's problem The old one opened with a table of six package names, so a visitor met the inventory before the point. It also carried a fourteen-row table of internal phases 0-14, all "done" — a view from inside the project that tells a reader nothing. It now opens with the code people actually write: an EntityManager threaded through every service layer, then the same method with one decorator. That comparison is the strongest honest pitch this library has, because transparent repositories make the second version真 work without rewriting anything. The features follow as an escalating story rather than a list, each step closing a failure the reader has already hit: the transaction, then AFTER_COMMIT meaning committed (the email sent for an order the rollback erased), then the outbox surviving the process dying. Two new sections. "Where the sharp edges are" states the per-dialect readOnly, the unimplemented timeout, the fire-and-forget broker delivery from ADR-016 and the two escape hatches — and points at typeorm-transactional as the smaller choice when only transparent repositories are wanted. "How it is verified" says what CI actually proves: real Postgres, three TypeORM versions across three Node versions, all 19 examples built and run, a committed API surface, publint and attw on the packed tarball. For anyone choosing a library for production, those two sections are worth more than another feature bullet. The phase table is gone; docs/roadmap/README.md keeps the history and Status now says what is next instead. Three claims of my own drafting were corrected on review: the outbox storage package no longer advertises MySQL and SQLite, which are never exercised by its integration tests; "provably cannot enrol" became the documented fallback it actually is; and the typeorm-transactional link points at npm rather than a guessed GitHub org, since the link checker does not verify external URLs.
igorgolovanov
added a commit
that referenced
this pull request
Aug 20, 2026
The Version Packages PR aggregates every changeset of the alpha series into the 1.0.0 section — that is how changesets' pre-release mode works, and it means release notes for a stable version opened with "First public alpha release." and explained how the `alpha` dist-tag had been pinned. Three release-plumbing entries are dropped from the 1.0.0 section: the dist-tag pin (#8), `--tag alpha` in the publish script (#10), and the post-publish re-tagging step (#12). They say nothing to a consumer and contradict the release they now sit in. They remain in the alpha sections below, where they are accurate history. The headline becomes "First stable release." and the closing line points at the ADR-004 stability policy instead of claiming the API "may change between 0.x releases" — wrong twice over, since the cohort never sat on 0.x. The per-package feature summary underneath is kept intact; it is exactly what someone wants from 1.0.0 notes. Only the `## 1.0.0` section is touched. The alpha sections below hash identically before and after in all six files.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
@changesets/cli refuses
--tagin pre-release mode (changesets/changesets#942), so the previous fix that added--tag alphato the rootreleasescript broke the publish step entirely ("Releasing under custom tag is not allowed in pre mode").Revert the script to
changeset publish(default taglatest) and add a follow-up step in release.yml that walkssteps.changesets.outputs.publishedPackagesand runsnpm dist-tag add <name>@<version> alphafor each. Freshly published pre-releases land in bothlatest(changesets default, not fought) andalpha(our step), sonpm install @nestjs-transactional/<pkg>@alpharesolves to the newest pre-release again.publishConfig.tag = "alpha"stays as declarative metadata for directnpm publishcallers. The workflow step and the manifest field will become no-ops once we runpnpm changeset pre exitbefore stable 1.0.0.