@depup/typeorm-extension 3.9.0-depup.0 → 4.1.0-depup.0

package/README.MD

@@ -1,24 +1,20 @@
-# Typeorm Extension 🚀
+<p align="center">
+  <img src=".github/assets/logo.svg" alt="typeorm-extension" width="120">
+</p>
 
-[![npm version](https://badge.fury.io/js/typeorm-extension.svg)](https://badge.fury.io/js/typeorm-extension)
-[![codecov](https://codecov.io/gh/Tada5hi/typeorm-extension/branch/master/graph/badge.svg?token=4KNSG8L13V)](https://codecov.io/gh/Tada5hi/typeorm-extension)
-[![Master Workflow](https://github.com/Tada5hi/typeorm-extension/workflows/CI/badge.svg)](https://github.com/Tada5hi/typeorm-extension)
-[![Known Vulnerabilities](https://snyk.io/test/github/Tada5hi/typeorm-extension/badge.svg?targetFile=package.json)](https://snyk.io/test/github/Tada5hi/typeorm-extension?targetFile=package.json)
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
+<h1 align="center">typeorm-extension</h1>
+
+<p align="center">
+  <a href="https://badge.fury.io/js/typeorm-extension"><img src="https://badge.fury.io/js/typeorm-extension.svg" alt="npm version"></a>
+  <a href="https://codecov.io/gh/Tada5hi/typeorm-extension"><img src="https://codecov.io/gh/Tada5hi/typeorm-extension/branch/master/graph/badge.svg?token=4KNSG8L13V" alt="codecov"></a>
+  <a href="https://github.com/Tada5hi/typeorm-extension"><img src="https://github.com/Tada5hi/typeorm-extension/workflows/CI/badge.svg" alt="Master Workflow"></a>
+  <a href="https://snyk.io/test/github/Tada5hi/typeorm-extension?targetFile=package.json"><img src="https://snyk.io/test/github/Tada5hi/typeorm-extension/badge.svg?targetFile=package.json" alt="Known Vulnerabilities"></a>
+  <a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white" alt="Conventional Commits"></a>
+</p>
 
 This is a library to
 - `create`, `drop` & `seed` the (default-) database 🔥
 - manage one or many data-source instances 👻
-- parse & apply query parameters (extended **JSON:API** specification & fully typed) to:
-    - `filter` (related) resources according to one or more criteria,
-    - reduce (related) resource `fields`,
-    - `include` related resources,
-    - `sort` resources according to one or more criteria,
-    - limit the number of resources returned in a response by `page` limit & offset
-
-> **Warning**
-> This readme includes the documentation for the upcoming version 3.
-> This is the [link](https://github.com/tada5hi/typeorm-extension/tree/v2) for the v2.
 
 **Table of Contents**
 - [Installation](#installation)
@@ -30,6 +26,9 @@ This is a library to
   - [Database](#database)
     - [Create](#create)
     - [Drop](#drop)
+    - [Schema Drift](#schema-drift)
+    - [Generate Migration](#generate-migration)
+    - [Repair Migrations](#repair-migrations)
   - [Instances](#instances)
     - [Single](#single)
     - [Multiple](#multiple)
@@ -46,9 +45,13 @@ This is a library to
 ## Installation
 
 ```bash
-npm install typeorm-extension --save
+npm install typeorm-extension typeorm --save
 ```
 
+`typeorm` is a peer dependency and is required in the range `^1.1.0`. Seeder factories generate their data
+with a library of your choice, so nothing else is required. The examples below use
+[faker](https://fakerjs.dev/guide/) (`npm install @faker-js/faker`).
+
 ## Documentation
 
 To read the docs, visit [https://typeorm-extension.tada5hi.net](https://typeorm-extension.tada5hi.net)
@@ -57,64 +60,74 @@ To read the docs, visit [https://typeorm-extension.tada5hi.net](https://typeorm-
 
 ### CLI
 
-If you use esm, the executable must be changed from `typeorm-extension` to `typeorm-extension-esm`.
 The following commands are available in the terminal:
-- `typeorm-extension db:create` to create the database
-- `typeorm-extension db:drop` to drop the database
-- `typeorm-extension seed:run` seed the database
-- `typeorm-extension seed:create` to create a new seeder
+- `typeorm-extension db create` to create the database
+- `typeorm-extension db drop` to drop the database
+- `typeorm-extension db drift` to assert that the database schema matches the entity metadata
+- `typeorm-extension seed run` to seed the database
+- `typeorm-extension seed create` to create a new seeder
 
-If the application has not yet been built or is to be tested with ts-node, the commands can be adapted as follows:
+The legacy colon-form (`db:create`, `db:drop`, `seed:run`, `seed:create`) is still accepted for backwards compatibility.
+
+If the application has not yet been built and you want to run the CLI against TypeScript sources directly, invoke the ESM bundle with a TypeScript-aware Node loader (e.g. `tsx` or Node's `--experimental-strip-types`):
 
 ```
 "scripts": {
-    "db:create": "ts-node ./node_modules/typeorm-extension/bin/cli.cjs db:create",
-    "db:drop": "ts-node ./node_modules/typeorm-extension/bin/cli.cjs db:drop",
-    "seed:run": "ts-node ./node_modules/typeorm-extension/bin/cli.cjs seed:run",
-    "seed:create": "ts-node ./node_modules/typeorm-extension/bin/cli.cjs seed:create"
+    "db:create":   "tsx ./node_modules/typeorm-extension/bin/cli.mjs db create",
+    "db:drop":     "tsx ./node_modules/typeorm-extension/bin/cli.mjs db drop",
+    "db:drift":    "tsx ./node_modules/typeorm-extension/bin/cli.mjs db drift",
+    "seed:run":    "tsx ./node_modules/typeorm-extension/bin/cli.mjs seed run",
+    "seed:create": "tsx ./node_modules/typeorm-extension/bin/cli.mjs seed create"
 }
 ```
-To test the application in the context of an esm project, the following adjustments must be made:
-- executable `ts-node` to `ts-node-esm`
-- library path `cli.cjs` to `cli.mjs`
 
 Read the [Seeding Configuration](#configuration) section to find out how to specify the path,
 for the seeder- & factory-location.
 
 #### CLI Options
 
-| Option                  | Commands                                           | Default         | Description                                                                                                                                                                                                                             |
-|-------------------------|----------------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--root` or `-r`        | `db:create`, `db:drop`, `seed:create` & `seed:run` | `process.cwd()` | Root directory of the project.                                                                                                                                                                                                          |
-| `--dataSource` or `-d`  | `db:create`, `db:drop` & `seed:run`                | `data-source`   | Name (or relative path incl. name) of the data-source file.                                                                                                                                                                             |
-| `--synchronize` or `-s` | `db:create`                            | `yes`           | Synchronize the database schema after database creation. Options: `yes` or `no`.                                                                                                                                                        |
-| `--initialDatabase`     | `db:create`                                        | `undefined`     | Specify the initial database to connect to. This option is only relevant for the `postgres` driver, which must always connect to a database. If no database is provided, the database name will be equal to the connection user name. |
-| `--name`                | `seed:create` & `seed:run`                         | `undefined`     | Name (or relative path incl. name) of the seeder.                                                                                                                                                                                       |
-| `--preserveFilePaths`   | `db:create`, `db:drop`, `seed:create` & `seed:run` | `false`         | This option indicates if file paths should be preserved and treated as if the just-in-time compilation environment is detected.                                                                                                         |
+| Option                  | Commands                                          | Default         | Description                                                                                                                                                                                                                           |
+|-------------------------|---------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--root` or `-r`        | `db create`, `db drift`, `db drop`, `seed create`, `seed run` | `process.cwd()` | Root directory of the project.                                                                                                                                                                                                        |
+| `--tsconfig` or `-tc`   | `db create`, `db drift`, `db drop`, `seed run` | `tsconfig.json` | Name (or relative path incl. name) of the tsconfig file.                                                                                                                                                                              |
+| `--dataSource` or `-d`  | `db create`, `db drift`, `db drop`, `seed run` | `data-source`   | Name (or relative path incl. name) of the data-source file.                                                                                                                                                                           |
+| `--synchronize` or `-s` | `db create`                                       | `yes`           | Synchronize the database schema after database creation. Options: `yes` or `no`.                                                                                                                                                      |
+| `--initialDatabase`     | `db create`                                       | `undefined`     | Specify the initial database to connect to. This option is only relevant for the `postgres` driver, which must always connect to a database. If no database is provided, the database name will be equal to the connection user name. |
+| `--skipWithoutMigrations` | `db drift`                                      | `false`         | Report no drift if the data-source has no migrations registered.                                                                                                                                                                      |
+| `--name` or `-n`        | `seed create` (required), `seed run` (optional)   | `undefined`     | Name (or relative path incl. name) of the seeder. Required on `seed create`; on `seed run` restricts execution to the matching seeder.                                                                                                |
+| `--timestamp` or `-t`   | `seed create`                                     | `Date.now()`    | Custom timestamp used in the generated seeder filename.                                                                                                                                                                               |
+| `--javascript` or `-j`  | `seed create`                                     | `false`         | Generate a seeder file for JavaScript instead of TypeScript.                                                                                                                                                                          |
+| `--preserveFilePaths`   | `db create`, `db drift`, `db drop`, `seed run` | `false`         | This option indicates if file paths should be preserved and treated as if the just-in-time compilation environment is detected.                                                                                                       |
+| `--log-level`           | `db create`, `db drift`, `db drop`, `seed create`, `seed run` | `info`          | Logger verbosity. One of `silent`, `info`, `debug`.                                                                                                                                                                                   |
 
 #### CLI Examples
 **`Database Create`**
 ```shell
-ts-node ./node_modules/typeorm-extension/bin/cli.cjs db:create  -d src/data-source.ts
+tsx ./node_modules/typeorm-extension/bin/cli.mjs db create  -d src/data-source.ts
 ```
 **`Database Drop`**
 ```shell
-ts-node ./node_modules/typeorm-extension/bin/cli.cjs db:drop  -d src/data-source.ts
+tsx ./node_modules/typeorm-extension/bin/cli.mjs db drop  -d src/data-source.ts
+```
+
+**`Database Drift`**
+```shell
+tsx ./node_modules/typeorm-extension/bin/cli.mjs db drift  -d src/data-source.ts
 ```
 
 **`Seed Run`**
 ```shell
-ts-node ./node_modules/typeorm-extension/bin/cli.cjs seed:run  -d src/data-source.ts
+tsx ./node_modules/typeorm-extension/bin/cli.mjs seed run  -d src/data-source.ts
 ```
 
 **`Seed Run Explicit`**
 ```shell
-ts-node ./node_modules/typeorm-extension/bin/cli.cjs seed:run  -d src/data-source.ts --name src/database/seeds/user.ts
+tsx ./node_modules/typeorm-extension/bin/cli.mjs seed run  -d src/data-source.ts --name src/database/seeds/user.ts
 ```
 
 **`Seed Create`**
 ```shell
-ts-node ./node_modules/typeorm-extension/bin/cli.cjs seed:create  --name src/database/seeds/user.ts
+tsx ./node_modules/typeorm-extension/bin/cli.mjs seed create  --name src/database/seeds/user.ts
 ```
 
 ### Database
@@ -129,7 +142,7 @@ import { createDatabase } from 'typeorm-extension';
 
 (async () => {
     const options: DataSourceOptions = {
-        type: 'better-sqlite',
+        type: 'better-sqlite3',
         database: 'db.sqlite'
     };
 
@@ -201,7 +214,7 @@ import { dropDatabase } from 'typeorm-extension';
 
 (async () => {
     const options: DataSourceOptions = {
-        type: 'better-sqlite',
+        type: 'better-sqlite3',
         database: 'db.sqlite'
     };
 
@@ -252,6 +265,99 @@ To get a better overview and understanding of the
 [dropDatabase](https://typeorm-extension.tada5hi.net/guide/database-api-reference.html#dropDatabase)
 function, check out the documentation.
 
+#### Schema Drift
+
+Compare the database schema against the entity metadata and get back the statements which would reconcile them.
+
+Run it right after the migrations to close the blind spot of a project which builds its schema with migrations in
+production but with `synchronize()` in tests: the two descriptions can drift apart silently, and it only surfaces
+when the next generated migration reconciles them.
+
+```typescript
+import { assertSchemaMatchesMetadata, getSchemaDrift } from 'typeorm-extension';
+
+(async () => {
+    const drift = await getSchemaDrift(dataSource);
+    if (drift.exists) {
+        console.log(drift.up.map((statement) => statement.query));
+    }
+
+    // ... or let it throw a SchemaDriftError listing the statements
+    await assertSchemaMatchesMetadata(dataSource);
+})();
+```
+
+The same check is available on the command line as `typeorm-extension db drift`, which exits with code `1` on drift.
+
+#### Generate Migration
+
+`generateMigration` writes a migration file from the same schema comparison, using typeorm's own statements and file
+templates. The data source must already be initialized.
+
+```typescript
+import { generateMigration } from 'typeorm-extension';
+
+(async () => {
+    await generateMigration({
+        dataSource,
+        name: 'add-role',
+        directoryPath: 'src/migrations',
+    });
+})();
+```
+
+The file is written as `<timestamp>-<name>.<language>`, by default into `migrations/`. Set `language: 'js'` (plus
+`esm: true` for `export class` syntax) for a JavaScript migration, or `preview: true` to receive the statements without
+writing a file.
+
+#### Repair Migrations
+
+Renaming a constraint is dialect-asymmetric and easy to get wrong. These helpers read the current state back from the
+database, apply the change only if it is still pending, and return whether they did something. That way a repair migration
+stays resumable (mysql commits DDL regardless of the surrounding transaction) and safe to run against a database which
+never had the drift.
+
+```typescript
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+import { changeColumnType, renameForeignKey, renameIndex } from 'typeorm-extension';
+
+export class RepairSchema1700000000000 implements MigrationInterface {
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await renameIndex(queryRunner, {
+            table: 'auth_events',
+            from: 'IDX_auth_events_actor_name',
+            to: 'IDX_9f6d1a2b3c4d5e6f70819293',
+        });
+
+        await renameForeignKey(queryRunner, {
+            table: 'auth_permissions',
+            from: 'FK_auth_permissions_client',
+            to: 'FK_1a2b3c4d5e6f708192a3b4c5',
+        });
+
+        await changeColumnType(queryRunner, {
+            table: 'auth_permissions',
+            column: 'client_id',
+            from: { type: 'varchar', length: 36 },
+            to: { type: 'varchar', length: 255 },
+        });
+    }
+}
+```
+
+`renameIndex` and `renameForeignKey` support `postgres`, `cockroachdb`, `mysql` and `mariadb` and throw a `DriverError`
+on any other driver. `changeColumnType` and `withForeignKeyChecksDisabled` work everywhere: `changeColumnType` alters
+the column in place (keeping its values) on every relational driver but sqlite, which typeorm handles safely by
+recreating the table.
+
+Each helper returns `false` when the change is already applied, which keeps a repair migration resumable. If the
+database is in **neither** the expected nor the desired state it raises a `SchemaAlterationError` instead of returning
+quietly, since a repair migration which repairs nothing would otherwise pass for a successful one. Pass
+`strict: false` per call to opt out.
+
+To get a better overview and understanding of these functions, check out the
+[documentation](https://typeorm-extension.tada5hi.net/guide/database-api-reference.html).
+
 ### Instances
 
 #### Single
@@ -311,7 +417,7 @@ Seeding the database is fairly easy and can be achieved by following the steps b
 
 Seeder paths are configured as **glob patterns**, making it easy
 to match all the factory/seeder files in your project without configuration effort:
-- use `*` to match anything expect slashes and hidden files
+- use `*` to match anything except slashes and hidden files
 - use `**` to match zero or more directories
 - use comma separate values between `{}` to match against a list of options
 
@@ -330,8 +436,14 @@ The following values are assumed by default:
 
 Note: When seeder paths are configured as **glob patterns**, the paths are resolved and sorted in alphabetical order using filenames. This helps to ensure that the seeders are executed in the correct order.
 
+Seeder options can be provided per invocation (`runSeeder(s)` options parameter), on the extended
+data-source options, or via environment variables. Explicit input wins over the data-source options,
+which win over the environment; built-in defaults apply last.
+
 It is possible to define that a seeder is only executed once.
-This can either be set globally using the seedTacking option or locally using the track property of a seeder class.
+This can either be set globally using the `seedTracking` option or locally using the `track` property of a seeder class.
+Executed seeds are recorded in a `seeds` table (a collection for MongoDB);
+the table name can be changed with the `seedTableName` option.
 
 `data-source.ts`
 
@@ -340,7 +452,7 @@ import { DataSource, DataSourceOptions } from 'typeorm';
 import { SeederOptions } from 'typeorm-extension';
 
 const options: DataSourceOptions & SeederOptions = {
-    type: 'better-sqlite',
+    type: 'better-sqlite3',
     database: 'db.sqlite',
 
     seeds: ['src/database/seeds/**/*{.ts,.js}'],
@@ -359,7 +471,7 @@ import { runSeeders, SeederOptions } from 'typeorm-extension';
 
 (async () => {
     const options: DataSourceOptions = {
-        type: 'better-sqlite',
+        type: 'better-sqlite3',
         database: 'db.sqlite',
     };
 
@@ -404,27 +516,32 @@ export class User {
 To create entities with random data, create a factory for each desired entity.
 The definition of a factory is **optional**.
 
-The factory callback provides an instance of the [faker](https://fakerjs.dev/guide/) library as function argument,
-to populate the entity with random data.
+The factory callback returns the entity to persist. Pick any data generator you like and import it in the
+factory file. The examples use [faker](https://fakerjs.dev/guide/) (`npm install @faker-js/faker`).
 
 **`user.factory.ts`**
 ```typescript
+import { faker } from '@faker-js/faker';
 import { setSeederFactory } from 'typeorm-extension';
 import { User } from './user';
 
-export default setSeederFactory(User, (faker) => {
+export default setSeederFactory(User, () => {
     const user = new User();
-    user.firstName = faker.name.firstName('male');
-    user.lastName = faker.name.lastName('male');
-    user.email = faker.internet.email(user.firstName, user.lastName);
+    user.firstName = faker.person.firstName('male');
+    user.lastName = faker.person.lastName('male');
+    user.email = faker.internet.email({ firstName: user.firstName, lastName: user.lastName });
 
     return user;
 })
 ```
 
+Since the generator instance belongs to the factory file, locales and reproducible runs are configured
+through the generator's own API, for example `import { fakerDE as faker } from '@faker-js/faker'`
+or `faker.seed(1234)`.
+
 #### Seed
-And last but not least, create a seeder. The seeder can be called by the cli command `seed` or in the codebase
-by using the function `runSeeder`.
+And last but not least, create a seeder. The seeder can be called by the cli command `seed:run` or in the codebase
+by using the function `runSeeder` / `runSeeders`.
 A seeder class only requires one method, called `run` and provides the arguments `dataSource` & `factoryManager`.
 
 **`user.seeder.ts`**
@@ -469,6 +586,10 @@ export default class UserSeeder implements Seeder {
 }
 ```
 
+Factories obtained through the `factoryManager` argument are bound to the data source of the
+current seeder run, so `save()` and `saveMany()` persist there. A factory used outside a seeder
+run falls back to the data source registered for the `default` alias.
+
 #### Execute
 
 Populate the database from the code base:
@@ -476,11 +597,11 @@ Populate the database from the code base:
 ```typescript
 import { DataSource, DataSourceOptions } from 'typeorm';
 import { runSeeders, SeederOptions } from 'typeorm-extension';
-import { User } from 'user';
+import { User } from './user';
 
 (async () => {
     const options: DataSourceOptions & SeederOptions = {
-        type: 'better-sqlite',
+        type: 'better-sqlite3',
         database: 'db.sqlite',
         entities: [User],
 
@@ -500,13 +621,13 @@ Populate the database by explicit definitions from the codebase.
 ```typescript
 import { DataSource, DataSourceOptions } from 'typeorm';
 import { runSeeders, SeederOptions } from 'typeorm-extension';
-import { User } from 'user';
-import UserSeeder from 'user.seeder';
-import UserFactory from 'user.factory';
+import { User } from './user';
+import UserSeeder from './user.seeder';
+import UserFactory from './user.factory';
 
 (async () => {
     const options: DataSourceOptions & SeederOptions = {
-        type: 'better-sqlite',
+        type: 'better-sqlite3',
         database: 'db.sqlite',
         entities: [User],
 
@@ -522,20 +643,31 @@ import UserFactory from 'user.factory';
 ```
 
 ### Query
-The query submodule enables query parameter (fields, filter, ...) values to be build, parsed & validated.
-Therefore, the [rapiq](https://www.npmjs.com/package/rapiq) library is used under the hood.
 
-The query parameter options (allowed, default, ...) are fully typed 🔥 and depend on the (nested-) properties of the target entity passed to
-the typeorm query builder.
+The query submodule (`applyQuery`, `applyFilters`, ...) was removed in v4.
+Its successor is [@rapiq/adapter-typeorm](https://github.com/tada5hi/rapiq/tree/master/packages/adapter-typeorm), the dedicated
+TypeORM adapter of the [rapiq](https://github.com/tada5hi/rapiq) v2 monorepo. The query pipeline is now fully
+**self-contained** in rapiq: decoding the raw URL query string (`@rapiq/codec-url`), typed schema
+validation (`@rapiq/core`) and application onto the `SelectQueryBuilder` (`@rapiq/adapter-typeorm`).
+`typeorm-extension` is no longer involved. On top of the full `applyQuery` use case it adds typed
+schemas, nested `and` / `or` filter compounds, the `contains` operator family and collision-free join aliases.
+
+The [monorepo](https://github.com/tada5hi/rapiq) hosts more than the TypeORM adapter: adapters for
+drizzle, prisma, raw SQL and in-memory collections, plus pluggable input parsers (e.g. a MongoDB-style
+filter parser and an expression parser). If rapiq is useful to you, consider giving the repo a ⭐ on GitHub.
+
+```bash
+npm install @rapiq/core @rapiq/codec-url @rapiq/adapter-typeorm --save
+```
 
-For explanation proposes,
-two simple entities with a relation between them are declared to demonstrate the usage of the query utils:
+For demonstration purposes, two simple entities with a relation between them are used:
 
 ```typescript
 import {
     Entity,
     PrimaryGeneratedColumn,
     Column,
+    Index,
     OneToOne,
     JoinColumn
 } from 'typeorm';
@@ -573,94 +705,118 @@ export class Profile {
 }
 ```
 
-In this example [routup](https://www.npmjs.com/package/routup) and the
-plugin [@routup/query](https://www.npmjs.com/package/@routup/query) is used to handle HTTP requests,
-but there is also a guide available for [express](https://typeorm-extension.tada5hi.net/guide/query.html).
+Instead of passing loose options per call (as `applyQuery` did), the allowed query features are declared
+once as a typed **schema** and registered alongside a codec:
 
 ```typescript
-import { createServer } from 'node:http';
-import type { Request, Response } from 'routup';
-import { createNodeDispatcher, Router } from 'routup';
-import { createHandler, useQuery } from '@routup/query';
+import { SchemaRegistry, defineSchema } from '@rapiq/core';
+import { createURLCodec } from '@rapiq/codec-url';
+import { Profile, User } from './entities';
+
+const registry = new SchemaRegistry();
+
+registry.add(defineSchema<Profile>({
+    name: 'profile',
+    fields: { allowed: ['id', 'avatar'] },
+    filters: { allowed: ['id'] },
+}));
+
+registry.add(defineSchema<User>({
+    name: 'user',
+    fields: {
+        allowed: ['id', 'name', 'email'],
+        default: ['id', 'name'],
+    },
+    filters: { allowed: ['id', 'name', 'profile.id'] },
+    relations: { allowed: ['profile'] },
+    sort: { allowed: ['id', 'name'], default: { id: 'DESC' } },
+    pagination: { maxLimit: 20 },
+    schemaMapping: { profile: 'profile' },
+}));
+
+export const codec = createURLCodec(registry);
+```
 
-import {
-    applyQuery,
-    useDataSource
-} from 'typeorm-extension';
+The codec owns both directions. A client builds the query string with `encode`, from a typed query
+instead of string concatenation (no registry needed on the client):
+
+```typescript
+import { defineQuery } from '@rapiq/core';
+import { createURLCodec } from '@rapiq/codec-url';
+import type { User } from './entities';
+
+const codec = createURLCodec();
+
+const query = defineQuery<User>({
+    fields: ['id', 'name'],
+    filters: { id: 1 },
+    relations: ['profile'],
+    pagination: { limit: 10, offset: 0 },
+});
+
+const response = await fetch(`/users?${codec.encode(query)}`);
+```
 
-const router = new Router();
-router.use(createHandler());
+The request handler then decodes the raw query parameters against the schema and lets the adapter apply
+the result onto the query builder. It is shown here with [express](https://www.npmjs.com/package/express),
+but the flow is framework-agnostic:
+
+```typescript
+import { ParseError } from '@rapiq/core';
+import { TypeormAdapter } from '@rapiq/adapter-typeorm';
+import { useDataSource } from 'typeorm-extension';
+import { codec } from './codec';
+import { User } from './entities';
 
 /**
  * Get many users.
  *
  * Request example
  * - url: /users?page[limit]=10&page[offset]=0&include=profile&filter[id]=1&fields[user]=id,name
- *
- * Return Example:
- * {
- *     data: [
- *         {id: 1, name: 'tada5hi', profile: {avatar: 'avatar.jpg', cover: 'cover.jpg'}}
- *      ],
- *     meta: {
- *        total: 1,
- *        limit: 20,
- *        offset: 0
- *    }
- * }
- * @param req
- * @param res
  */
-router.get('users', async (req: Request, res: Response) => {
+app.get('/users', async (req, res) => {
+    let query;
+    try {
+        query = codec.decode(req.query, { schema: 'user' });
+    } catch (e) {
+        // e.g. a malformed filter expression
+        if (e instanceof ParseError) {
+            return res.status(400).json({ error: e.message });
+        }
+        throw e;
+    }
+    if (!query) {
+        return res.status(400).json({ error: 'Invalid query input.' });
+    }
+
     const dataSource = await useDataSource();
-    const repository = dataSource.getRepository(User);
-    const query = repository.createQueryBuilder('user');
-
-    // -----------------------------------------------------
-
-    const { pagination } = applyQuery(query, useQuery(req), {
-        defaultAlias: 'user',
-        fields: {
-            // porfile fields can only be included,
-            // if the relation 'profile' is included.
-            allowed: ['id', 'name', 'profile.id', 'profile.avatar'],
-        },
-        filters: {
-            // porfile.id can only be used as a filter,
-            // if the relation 'profile' is included.
-            allowed: ['id', 'name', 'profile.id'],
-        },
-        pagination: {
-            // only allow to select 20 items at maximum.
-            maxLimit: 20
-        },
-        relations: {
-            allowed: ['profile']
-        },
-        sort: {
-            // profile.id can only be used as sorting key,
-            // if the relation 'profile' is included.
-            allowed: ['id', 'name', 'profile.id']
-        },
-    });
+    const queryBuilder = dataSource.getRepository(User).createQueryBuilder('user');
 
-    // -----------------------------------------------------
+    const { pagination } = new TypeormAdapter({ queryBuilder }).execute(query);
 
-    const [entities, total] = await query.getManyAndCount();
+    const [entities, total] = await queryBuilder.getManyAndCount();
 
-    return {
+    res.json({
         data: entities,
         meta: {
             total,
             ...pagination
         }
-    };
+    });
 });
-
-const server = createServer(createNodeDispatcher(router));
-server.listen(80);
 ```
 
+A production-shaped version with strict schema-violation handling (`throwOnFailure`) is in the
+[Express + TypeORM recipe](https://rapiq.tada5hi.net/guide/recipes/express-typeorm); the client side is covered by the
+[frontend recipe](https://rapiq.tada5hi.net/guide/recipes/frontend).
+
+To move over from the removed submodule, follow the migration guide:
+[https://rapiq.tada5hi.net/guide/migration-typeorm-extension](https://rapiq.tada5hi.net/guide/migration-typeorm-extension)
+
+> **Note**: This section is kept during the v4 release cycle to route former `applyQuery` users to the
+> successor. With the next major release (v5) it will be removed from the README and docs; the
+> [rapiq documentation](https://rapiq.tada5hi.net) is the canonical reference.
+
 ## Contributing
 
 Before starting to work on a pull request, it is important to review the guidelines for

package/README.md

@@ -13,19 +13,17 @@ npm install @depup/typeorm-extension
 
 | Field | Value |
 |-------|-------|
-| Original | [typeorm-extension](https://www.npmjs.com/package/typeorm-extension) @ 3.9.0 |
-| Processed | 2026-03-19 |
+| Original | [typeorm-extension](https://www.npmjs.com/package/typeorm-extension) @ 4.1.0 |
+| Processed | 2026-08-23 |
 | Smoke test | failed |
-| Deps updated | 4 |
+| Deps updated | 2 |
 
 ## Dependency Changes
 
 | Dependency | From | To |
 |------------|------|-----|
-| consola | ^3.4.0 | ^3.4.2 |
 | pascal-case | ^3.1.2 | ^4.0.0 |
-| rapiq | ^0.9.0 | ^1.0.0 |
-| smob | ^1.5.0 | ^1.6.1 |
+| smob | ^1.5.0 | ^1.6.2 |
 
 ---