Skip to content

ci(release): tag pre-releases as alpha via post-publish step - #12

Merged
igorgolovanov merged 2 commits into
mainfrom
fix/release-post-publish-alpha-tag
May 23, 2026
Merged

igorgolovanov merged 2 commits into
mainfrom
fix/release-post-publish-alpha-tag

Conversation

@igorgolovanov

Copy link
Copy Markdown
Owner

@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.

@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.
Copilot AI review requested due to automatic review settings May 23, 2026 08:44

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 publish without --tag.
  • Adds a post-publish GitHub Actions step that iterates steps.changesets.outputs.publishedPackages and applies npm 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
igorgolovanov merged commit 382ded3 into main May 23, 2026
43 of 44 checks passed
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.
@igorgolovanov
igorgolovanov deleted the fix/release-post-publish-alpha-tag branch October 6, 2026 08:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants