Repository navigation
ci(release): accept an exact release-version on dispatch - #92
Merged
Merged
Conversation
Upd4ting
added a commit
that referenced
this pull request
Nov 13, 2026
## Why A user upgrading `@antelopejs/interface-database` to 0.4.0 should learn from its release notes which changes break their code and how to adapt. Today the `## v0.4.0` section of `CHANGELOG.md` and the v0.4.0 GitHub release name #91 only as "Drop casts, thenable queries and caller-typed schema lookups". Its upgrade notes live in `UPGRADING.md`. The release commit (7268503) does not copy them, so this PR does, as AGENTS.md asks. ## What This adds a `### Upgrade notes` block under `## v0.4.0` in `CHANGELOG.md`, right after the compare link, where the v0.3.0 block sits. It holds the `UPGRADING.md` v0.4.0 bullets verbatim, snippets included. It lists no implementer action: database modules implement nothing new, and the conformance suite in `dist/tests` already runs every query with `run()`. ## Pending step for Antony I have not edited the v0.4.0 GitHub release body. Paste the text under **Release notes to paste** into https://github.com/AntelopeJS/interface-database/releases/tag/v0.4.0. It is the current release body with the same upgrade-notes block after the compare link. ## Release notes to paste ````markdown [compare changes](v0.3.3...v0.4.0) ### Upgrade notes - **A query is no longer a promise.** `Query` has no `then()`, and `QueryExecution` no longer extends `PromiseLike`. `await query` gives back the query object and sends nothing to the provider. Run a query with `run()`, or read it with `cursor()` or `for await`. A query in `Promise.all([...])`, or returned from an `async` function, is no longer run either. TypeScript rejects a query passed where a `PromiseLike` is expected, and the `typescript/await-thenable` lint rule reports `await` on a query and a query passed to `Promise.all`, `Promise.race` or another promise aggregator. The conformance suite in `dist/tests` runs every query with `run()`. A database module implements nothing new. ```ts // Before const adults = await users.filter((u) => u.key("age").ge(18)); // After const adults = await users.filter((u) => u.key("age").ge(18)).run(); ``` - **`cast()` returns a new object.** `Datum#cast`, `Stream#cast` and `ValueProxy#cast` return a new object with the same stages, built by the new `StagedObject` constructor form `new X(undefined, previous)`, which records no stage. `cast()` on a `Table`, a `Selection` or a `SingleSelection` returns a plain `Stream` or `Datum`, the class its type already declared. Code that compared the result with its receiver, or relied on it keeping the subclass methods at runtime, such as a table's `insert` or `getAll`, keeps the receiver instead. ```ts // Before: the same object, still a Table at runtime table.cast<Row>() === table; // true // After: a new Stream with the same stages table.cast<Row>() === table; // false table.cast<Row>().build(); // equal to table.build() ``` - **`Schema.get()` takes no type arguments.** The registry keeps none, so `Schema.get(id)` returns `Schema<any, unknown> | undefined`: tables hold `any` documents, and the definition is typed `unknown`. A typed lookup such as `Schema.get<{ users: User }>(id)` fails to compile (TS2558). Query typed tables through the schema object the constructor returned. On the runtime entry, `Schema.list().get(id)` returns the schema with its definition typed `SchemaDefinition`. ```ts // Before const schema = Schema.get<{ users: User }>("myapp")!; // After: export the schema you define, and import it export const schema = new Schema<{ users: User }>("myapp", definition); ``` - **The build-only `Query<T>` keeps its result type.** Loaded from `@antelopejs/interface-database/staged-query` alone, `Query<T>` now uses `T`, so `ExtractType` reads the result type of a `Datum` or a `Stream` a mapper returns, and a `Query<string>` is no longer assignable to a `Query<number>`. Code that relied on that assignment fails to compile. ```ts // Before, build-only entry: compiled, typed unknown const q: Query<number> = schema.createInstance(); // Query<string> // After: TS2322 ``` - **`StagedObject#callfunc` checks its argument classes.** The protected method takes one or two `StagedConstructor`s, and each must build the parameter type `func` declares. A subclass that passed `ValueProxy<unknown>` for a parameter typed `ValueProxy<T>` passes `ValueProxy<T>`. ```ts // Before this.callfunc(mapper, Stream<T>, ValueProxy<unknown>); // After this.callfunc( mapper, Stream<T>, ValueProxy<K extends keyof T ? T[K] : unknown>, ); ``` ### 🚀 Enhancements - **staged-query:**⚠️ Drop casts, thenable queries and caller-typed schema lookups ([#91](#91)) ### 💅 Refactors - **tests:** Drop the no-unused-expressions suppression ([#88](#88)) ### 📖 Documentation - **readme:** List the mysql and postgres backends among the implementations ([#89](#89)) ### ✅ Tests - **atomic:** Move off-contract refusal checks into an untyped spec ([#90](#90)) ### 🤖 CI - **release:** Accept an exact release-version on dispatch ([#92](#92)) ####⚠️ Breaking Changes - **staged-query:**⚠️ Drop casts, thenable queries and caller-typed schema lookups ([#91](#91)) ### ❤️ Contributors - Antony Rizzitelli ([@Upd4ting](http://github.com/Upd4ting)) ```` ## Proof The inserted block matches `UPGRADING.md`'s v0.4.0 block line for line: ``` $ diff <(grep -v '^$' notes-from-UPGRADING.md) <(grep -v '^$' block-in-CHANGELOG.md) && echo verbatim verbatim ``` CHANGELOG diff: ````diff diff --git a/CHANGELOG.md b/CHANGELOG.md index bb189cc..d22fdb7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,57 @@ [compare changes](v0.3.3...v0.4.0) +### Upgrade notes + +- **A query is no longer a promise.** `Query` has no `then()`, and `QueryExecution` no longer extends `PromiseLike`. `await query` gives back the query object and sends nothing to the provider. Run a query with `run()`, or read it with `cursor()` or `for await`. A query in `Promise.all([...])`, or returned from an `async` function, is no longer run either. TypeScript rejects a query passed where a `PromiseLike` is expected, and the `typescript/await-thenable` lint rule reports `await` on a query and a query passed to `Promise.all`, `Promise.race` or another promise aggregator. The conformance suite in `dist/tests` runs every query with `run()`. A database module implements nothing new. + + ```ts + // Before + const adults = await users.filter((u) => u.key("age").ge(18)); + // After + const adults = await users.filter((u) => u.key("age").ge(18)).run(); + ``` + +- **`cast()` returns a new object.** `Datum#cast`, `Stream#cast` and `ValueProxy#cast` return a new object with the same stages, built by the new `StagedObject` constructor form `new X(undefined, previous)`, which records no stage. `cast()` on a `Table`, a `Selection` or a `SingleSelection` returns a plain `Stream` or `Datum`, the class its type already declared. Code that compared the result with its receiver, or relied on it keeping the subclass methods at runtime, such as a table's `insert` or `getAll`, keeps the receiver instead. + + ```ts + // Before: the same object, still a Table at runtime + table.cast<Row>() === table; // true + // After: a new Stream with the same stages + table.cast<Row>() === table; // false + table.cast<Row>().build(); // equal to table.build() + ``` + +- **`Schema.get()` takes no type arguments.** The registry keeps none, so `Schema.get(id)` returns `Schema<any, unknown> | undefined`: tables hold `any` documents, and the definition is typed `unknown`. A typed lookup such as `Schema.get<{ users: User }>(id)` fails to compile (TS2558). Query typed tables through the schema object the constructor returned. On the runtime entry, `Schema.list().get(id)` returns the schema with its definition typed `SchemaDefinition`. + + ```ts + // Before + const schema = Schema.get<{ users: User }>("myapp")!; + // After: export the schema you define, and import it + export const schema = new Schema<{ users: User }>("myapp", definition); + ``` + +- **The build-only `Query<T>` keeps its result type.** Loaded from `@antelopejs/interface-database/staged-query` alone, `Query<T>` now uses `T`, so `ExtractType` reads the result type of a `Datum` or a `Stream` a mapper returns, and a `Query<string>` is no longer assignable to a `Query<number>`. Code that relied on that assignment fails to compile. + + ```ts + // Before, build-only entry: compiled, typed unknown + const q: Query<number> = schema.createInstance(); // Query<string> + // After: TS2322 + ``` + +- **`StagedObject#callfunc` checks its argument classes.** The protected method takes one or two `StagedConstructor`s, and each must build the parameter type `func` declares. A subclass that passed `ValueProxy<unknown>` for a parameter typed `ValueProxy<T>` passes `ValueProxy<T>`. + + ```ts + // Before + this.callfunc(mapper, Stream<T>, ValueProxy<unknown>); + // After + this.callfunc( + mapper, + Stream<T>, + ValueProxy<K extends keyof T ? T[K] : unknown>, + ); + ``` + ### 🚀 Enhancements - **staged-query:**⚠️ Drop casts, thenable queries and caller-typed schema lookups ([#91](#91)) ```` `pnpm run checks`: ``` Checks: 11 passed, 0 failed. ``` The CI docs check reads only `README.md` and `docs/`, so this PR does not change its inputs.
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.
Why
#91 is a breaking change, so it has to ship as 0.4.0: database modules cap their range below the next minor. This repo's release workflow takes no
release-versioninput. Dispatching it with one fails withUnexpected inputs provided, and the automatic increment would publish the breaking change as a patch. This PR adds the optional input and passes it toAntelopeJS/.github/.github/workflows/release-npm-public.yml@v1, the same way tooling-configs'release.ymldoes.What
.github/workflows/release.ymlgets the optional string inputrelease-version, which it passes to the reusable workflow. When it is empty, the automatic increment applies as before.Proof
Before, dispatching with
-f release-version=0.4.0:After, the file is byte-identical to tooling-configs'
release.yml:The reusable workflow at
v1declares the input and checks it:pnpm run checks:Checks: 11 passed, 0 failed.I did not dispatch a test run, because it would publish a release.