Repository navigation
docs(readme): list the mysql and postgres backends among the implementations - #89
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
Readers of interface-database should see every backend they can load. The README's implementations table named only mongodb and rethinkdb.
@antelopejs/mysql0.1.0 (MySQL 8.4 and 9.7, MariaDB 11.8 and 12.3) is now on npmlatest, and@antelopejs/postgres0.3.0 was missing from the table as well.What
## Implementationsadds@antelopejs/mysql(MySQL and MariaDB) and@antelopejs/postgres(PostgreSQL). Each row uses the same fields as the existing ones. The "Also implements" note names@antelopejs/interface-database-catalog, which both published packages declare inantelopeJs.implements.@antelopejs/mysql.The README's ecosystem table between the
antelopejs-framework-modulesmarkers is not edited here.antelopejs-syncgenerates it from@antelopejs/tooling-configs, which lists mysql from 0.5.7 (AntelopeJS/tooling-configs#324). It updates with the next tooling-configs bump.No docs page lists backends per conformance suite, so this PR adds no
dotted_pathssupport list.Proof
Before:
After:
Docs check (the
tooling-configs/actions/docsstep CI pins, run locally with--files "README.md docs" --typescript-project docs/tsconfig.json):The check covers local links only. Both new repository links point at public repos, and the npm registry reports
@antelopejs/mysqldist-taglatest=0.1.0.pnpm run checks:Checks: 11 passed, 0 failed.