@nathapp/nestjs-data 3.2.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.eslintrc.js ADDED
@@ -0,0 +1,8 @@
1
+ module.exports = {
2
+ root: true,
3
+ extends: ["@nathapp/eslint-config/library.js"],
4
+ parser: "@typescript-eslint/parser",
5
+ parserOptions: {
6
+ project: true,
7
+ },
8
+ };
@@ -1,4 +1,4 @@
1
1
 
2
- > @nathapp/nestjs-data@3.2.1 build
2
+ > @nathapp/nestjs-data@4.0.0 build
3
3
  > rimraf dist && tsc -p tsconfig.json
4
4
 
package/AGENTS.md ADDED
@@ -0,0 +1,62 @@
1
+ # Agent Instructions
2
+
3
+ This file is auto-generated from `.nax/context.md`.
4
+ DO NOT EDIT MANUALLY — run `nax generate` to regenerate.
5
+
6
+ These instructions apply to all AI coding agents in this project.
7
+
8
+ ---
9
+
10
+ ## Project Metadata
11
+
12
+ > Auto-injected by `nax generate`
13
+
14
+ **Project:** `@nathapp/nestjs-data`
15
+
16
+ **Language:** TypeScript
17
+
18
+ **Key dependencies:** @golevelup/ts-jest, @nathapp/typescript-config, typescript
19
+
20
+ ---
21
+ # @nathapp/nestjs-data
22
+
23
+ ORM-agnostic data access abstractions. Pure-type package — no NestJS or ORM imports.
24
+
25
+ ## Exports
26
+
27
+ - `TRANSACTION_MANAGER` (Symbol) — DI token for `ITransactionManager`
28
+ - `ITransactionManager` — orm-agnostic transaction control via AsyncLocalStorage
29
+ - `IRepository<TDomain, TId>` — portable repository contract (CRUD + pagination)
30
+ - `IPageResult<T>` — structural shape of paginated results (compatible with `Page<T>` from `@nathapp/nestjs-common`)
31
+
32
+ ## Design
33
+
34
+ Services depend on `IRepository<TDomain>` via DI tokens (e.g. `USER_REPOSITORY`),
35
+ never on the concrete ORM repo class. Concrete implementations live in
36
+ `@nathapp/nestjs-typeorm` (`AbstractTypeOrmRepository`) and `@nathapp/nestjs-prisma`
37
+ (`AbstractPrismaRepository`). Both implementations:
38
+
39
+ - Accept the `TRANSACTION_MANAGER` provider and resolve the active client per operation.
40
+ - Require subclasses to implement three mappers (`toDomain`, `toPersistenceCreate`, `toPersistenceUpdate`).
41
+ - Return `Page<T>` from `@nathapp/nestjs-common` for `findAll` (compatible with `IPageResult<T>`).
42
+
43
+ For ORM-specific power (Prisma `include`, TypeORM `QueryBuilder`, raw SQL,
44
+ stored procedures), inject the concrete repo class directly — those call sites
45
+ intentionally lose portability. The portable surface is the `IRepository`
46
+ contract; everything else is an escape hatch.
47
+
48
+ ## Build
49
+
50
+ ```bash
51
+ cd packages/nestjs-data && npm run build
52
+ ```
53
+
54
+ ## Peer Dependencies
55
+
56
+ - `@nestjs/common` — for `Inject` typing
57
+ - `@nathapp/nestjs-common` — for `IPageOption` (used by `IRepository.findAll`)
58
+
59
+ ## Limitations
60
+
61
+ - Concrete base classes assume the primary key column/property is named `"id"`.
62
+ Schemas with different PK names must implement `IRepository` directly.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # @nathapp/nestjs-data
2
2
 
3
+ ## 4.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - 2319e9d: BREAKING: drop NestJS 8/9 peer ranges and require Node ^20.19.0 || >=22.12.0. Support NestJS 12. Peer ranges now cover NestJS 10, 11 and 12 (Node ^20.19.0 || >=22.12.0 is required because NestJS 12 is ESM-only). The configurable module builder no longer deep-imports a directory that is unresolvable on NestJS 12, and TwoFactorGuard / TwoFactorForceGuard redeclare their constructor DI metadata because NestJS 12 no longer inherits @Optional() from base classes.
8
+
9
+ Other consumer-facing changes:
10
+
11
+ - `@nathapp/nestjs-health`: `@nestjs/terminus` moved from `dependencies` to `peerDependencies` (`^11.0.0 || ^12.0.0`) so NestJS 12 apps can use terminus 12. Install `@nestjs/terminus` in your app.
12
+ - Optional-package loading (`loadPackage`) now throws a descriptive `Error` (original error on `cause`) instead of logging and calling `process.exit(1)` when an optional package is missing.
13
+
14
+ ### Patch Changes
15
+
16
+ - Updated dependencies [668055b]
17
+ - Updated dependencies [2319e9d]
18
+ - @nathapp/nestjs-common@4.0.0
19
+
20
+ ## 4.0.0-rc.0
21
+
22
+ ### Major Changes
23
+
24
+ - c3aeb46: BREAKING: drop NestJS 8/9 peer ranges and require Node ^20.19.0 || >=22.12.0. Support NestJS 12. Peer ranges now cover NestJS 10, 11 and 12 (Node ^20.19.0 || >=22.12.0 is required because NestJS 12 is ESM-only). The configurable module builder no longer deep-imports a directory that is unresolvable on NestJS 12, and TwoFactorGuard / TwoFactorForceGuard redeclare their constructor DI metadata because NestJS 12 no longer inherits @Optional() from base classes.
25
+
26
+ Other consumer-facing changes:
27
+
28
+ - `@nathapp/nestjs-health`: `@nestjs/terminus` moved from `dependencies` to `peerDependencies` (`^11.0.0 || ^12.0.0`) so NestJS 12 apps can use terminus 12. Install `@nestjs/terminus` in your app.
29
+ - Optional-package loading (`loadPackage`) now throws a descriptive `Error` (original error on `cause`) instead of logging and calling `process.exit(1)` when an optional package is missing.
30
+
31
+ ### Patch Changes
32
+
33
+ - Updated dependencies [c3aeb46]
34
+ - @nathapp/nestjs-common@4.0.0-rc.0
35
+
36
+ ## 3.3.0
37
+
38
+ ### Patch Changes
39
+
40
+ - @nathapp/nestjs-common@3.3.0
41
+
3
42
  ## 3.2.1
4
43
 
5
44
  ### Patch Changes
package/CLAUDE.md CHANGED
@@ -1,3 +1,21 @@
1
+ # Project Context
2
+
3
+ This file is auto-generated from `.nax/context.md`.
4
+ DO NOT EDIT MANUALLY — run `nax generate` to regenerate.
5
+
6
+ ---
7
+
8
+ ## Project Metadata
9
+
10
+ > Auto-injected by `nax generate`
11
+
12
+ **Project:** `@nathapp/nestjs-data`
13
+
14
+ **Language:** TypeScript
15
+
16
+ **Key dependencies:** @golevelup/ts-jest, @nathapp/typescript-config, typescript
17
+
18
+ ---
1
19
  # @nathapp/nestjs-data
2
20
 
3
21
  ORM-agnostic data access abstractions. Pure-type package — no NestJS or ORM imports.
package/GEMINI.md ADDED
@@ -0,0 +1,60 @@
1
+ # Gemini CLI Context
2
+
3
+ This file is auto-generated from `.nax/context.md`.
4
+ DO NOT EDIT MANUALLY — run `nax generate` to regenerate.
5
+
6
+ ---
7
+
8
+ ## Project Metadata
9
+
10
+ > Auto-injected by `nax generate`
11
+
12
+ **Project:** `@nathapp/nestjs-data`
13
+
14
+ **Language:** TypeScript
15
+
16
+ **Key dependencies:** @golevelup/ts-jest, @nathapp/typescript-config, typescript
17
+
18
+ ---
19
+ # @nathapp/nestjs-data
20
+
21
+ ORM-agnostic data access abstractions. Pure-type package — no NestJS or ORM imports.
22
+
23
+ ## Exports
24
+
25
+ - `TRANSACTION_MANAGER` (Symbol) — DI token for `ITransactionManager`
26
+ - `ITransactionManager` — orm-agnostic transaction control via AsyncLocalStorage
27
+ - `IRepository<TDomain, TId>` — portable repository contract (CRUD + pagination)
28
+ - `IPageResult<T>` — structural shape of paginated results (compatible with `Page<T>` from `@nathapp/nestjs-common`)
29
+
30
+ ## Design
31
+
32
+ Services depend on `IRepository<TDomain>` via DI tokens (e.g. `USER_REPOSITORY`),
33
+ never on the concrete ORM repo class. Concrete implementations live in
34
+ `@nathapp/nestjs-typeorm` (`AbstractTypeOrmRepository`) and `@nathapp/nestjs-prisma`
35
+ (`AbstractPrismaRepository`). Both implementations:
36
+
37
+ - Accept the `TRANSACTION_MANAGER` provider and resolve the active client per operation.
38
+ - Require subclasses to implement three mappers (`toDomain`, `toPersistenceCreate`, `toPersistenceUpdate`).
39
+ - Return `Page<T>` from `@nathapp/nestjs-common` for `findAll` (compatible with `IPageResult<T>`).
40
+
41
+ For ORM-specific power (Prisma `include`, TypeORM `QueryBuilder`, raw SQL,
42
+ stored procedures), inject the concrete repo class directly — those call sites
43
+ intentionally lose portability. The portable surface is the `IRepository`
44
+ contract; everything else is an escape hatch.
45
+
46
+ ## Build
47
+
48
+ ```bash
49
+ cd packages/nestjs-data && npm run build
50
+ ```
51
+
52
+ ## Peer Dependencies
53
+
54
+ - `@nestjs/common` — for `Inject` typing
55
+ - `@nathapp/nestjs-common` — for `IPageOption` (used by `IRepository.findAll`)
56
+
57
+ ## Limitations
58
+
59
+ - Concrete base classes assume the primary key column/property is named `"id"`.
60
+ Schemas with different PK names must implement `IRepository` directly.
package/README.md ADDED
@@ -0,0 +1,79 @@
1
+ # @nathapp/nestjs-data
2
+
3
+ ORM-agnostic data access abstractions — a portable repository contract and
4
+ transaction-manager interface, with no NestJS or ORM runtime imports.
5
+
6
+ ## Installation
7
+
8
+ ```bash
9
+ npm install @nathapp/nestjs-data
10
+ ```
11
+
12
+ This is a peer-layer library in the `@nathapp/nestjs-*` stack: it defines the
13
+ *contract*, not the implementation. Concrete implementations live in
14
+ `@nathapp/nestjs-prisma` (`AbstractPrismaRepository`) and
15
+ `@nathapp/nestjs-typeorm` (`AbstractTypeOrmRepository`).
16
+
17
+ ## What it provides
18
+
19
+ - `IRepository<TDomain, TId>` — portable repository contract: `findById`,
20
+ `findOne`, `findAll` (paginated), `count`, `create`, `update`, `delete`.
21
+ Services depend on this interface via a DI token instead of a concrete ORM
22
+ repo class.
23
+ - `IPageResult<T>` — ORM-agnostic paginated result shape (`total`, `current`,
24
+ `size`, `hasNext`, `hasPrev`, `records`), structurally compatible with
25
+ `Page<T>` from `@nathapp/nestjs-common`.
26
+ - `ITransactionManager` — ORM-agnostic transaction control built on
27
+ `AsyncLocalStorage`: `run(fn)`, `getClient<C>()`, `isInTransaction()`.
28
+ - `TRANSACTION_MANAGER` — global DI token (`Symbol.for('TRANSACTION_MANAGER')`)
29
+ for the default connection's `ITransactionManager`. Multi-DB apps must use
30
+ named tokens instead (see the concrete ORM package's docs).
31
+
32
+ ## Usage
33
+
34
+ Services depend on `IRepository<TDomain>` and `ITransactionManager` via DI
35
+ tokens, never on a concrete ORM class:
36
+
37
+ ```typescript
38
+ import { Inject, Injectable } from '@nestjs/common';
39
+ import { IRepository, ITransactionManager, TRANSACTION_MANAGER } from '@nathapp/nestjs-data';
40
+
41
+ export const USER_REPOSITORY = Symbol('USER_REPOSITORY');
42
+
43
+ interface User {
44
+ id: string;
45
+ email: string;
46
+ }
47
+
48
+ @Injectable()
49
+ export class UserService {
50
+ constructor(
51
+ @Inject(USER_REPOSITORY) private readonly users: IRepository<User>,
52
+ @Inject(TRANSACTION_MANAGER) private readonly tx: ITransactionManager,
53
+ ) {}
54
+
55
+ async register(input: User) {
56
+ return this.tx.run(async () => {
57
+ const existing = await this.users.findOne({ email: input.email });
58
+ if (existing) throw new Error('email already registered');
59
+ return this.users.create(input);
60
+ });
61
+ }
62
+
63
+ async list(page: { current: number; size: number }) {
64
+ return this.users.findAll(page); // -> IPageResult<User>
65
+ }
66
+ }
67
+ ```
68
+
69
+ Bind `USER_REPOSITORY` to a concrete implementation (e.g.
70
+ `AbstractPrismaRepository` subclass from `@nathapp/nestjs-prisma`) in your
71
+ module's `providers`. For ORM-specific power (Prisma `include`, TypeORM
72
+ `QueryBuilder`, raw SQL), inject the concrete repo class directly — those call
73
+ sites intentionally give up portability.
74
+
75
+ ## Limitations
76
+
77
+ Concrete base classes structurally assume the primary key property is named
78
+ `"id"`. Schemas using a different PK name must implement `IRepository`
79
+ directly rather than extending the abstract base class.
package/codex.md ADDED
@@ -0,0 +1,60 @@
1
+ # Codex Instructions
2
+
3
+ This file is auto-generated from `.nax/context.md`.
4
+ DO NOT EDIT MANUALLY — run `nax generate` to regenerate.
5
+
6
+ ---
7
+
8
+ ## Project Metadata
9
+
10
+ > Auto-injected by `nax generate`
11
+
12
+ **Project:** `@nathapp/nestjs-data`
13
+
14
+ **Language:** TypeScript
15
+
16
+ **Key dependencies:** @golevelup/ts-jest, @nathapp/typescript-config, typescript
17
+
18
+ ---
19
+ # @nathapp/nestjs-data
20
+
21
+ ORM-agnostic data access abstractions. Pure-type package — no NestJS or ORM imports.
22
+
23
+ ## Exports
24
+
25
+ - `TRANSACTION_MANAGER` (Symbol) — DI token for `ITransactionManager`
26
+ - `ITransactionManager` — orm-agnostic transaction control via AsyncLocalStorage
27
+ - `IRepository<TDomain, TId>` — portable repository contract (CRUD + pagination)
28
+ - `IPageResult<T>` — structural shape of paginated results (compatible with `Page<T>` from `@nathapp/nestjs-common`)
29
+
30
+ ## Design
31
+
32
+ Services depend on `IRepository<TDomain>` via DI tokens (e.g. `USER_REPOSITORY`),
33
+ never on the concrete ORM repo class. Concrete implementations live in
34
+ `@nathapp/nestjs-typeorm` (`AbstractTypeOrmRepository`) and `@nathapp/nestjs-prisma`
35
+ (`AbstractPrismaRepository`). Both implementations:
36
+
37
+ - Accept the `TRANSACTION_MANAGER` provider and resolve the active client per operation.
38
+ - Require subclasses to implement three mappers (`toDomain`, `toPersistenceCreate`, `toPersistenceUpdate`).
39
+ - Return `Page<T>` from `@nathapp/nestjs-common` for `findAll` (compatible with `IPageResult<T>`).
40
+
41
+ For ORM-specific power (Prisma `include`, TypeORM `QueryBuilder`, raw SQL,
42
+ stored procedures), inject the concrete repo class directly — those call sites
43
+ intentionally lose portability. The portable surface is the `IRepository`
44
+ contract; everything else is an escape hatch.
45
+
46
+ ## Build
47
+
48
+ ```bash
49
+ cd packages/nestjs-data && npm run build
50
+ ```
51
+
52
+ ## Peer Dependencies
53
+
54
+ - `@nestjs/common` — for `Inject` typing
55
+ - `@nathapp/nestjs-common` — for `IPageOption` (used by `IRepository.findAll`)
56
+
57
+ ## Limitations
58
+
59
+ - Concrete base classes assume the primary key column/property is named `"id"`.
60
+ Schemas with different PK names must implement `IRepository` directly.
package/package.json CHANGED
@@ -1,19 +1,25 @@
1
1
  {
2
2
  "name": "@nathapp/nestjs-data",
3
- "version": "3.2.1",
3
+ "version": "4.0.0",
4
4
  "description": "ORM-agnostic data access abstractions for NestJS",
5
5
  "scripts": {
6
6
  "clean": "rimraf dist/ .turbo/",
7
7
  "build": "rimraf dist && tsc -p tsconfig.json",
8
8
  "test": "jest --config ./test/jest-test.json",
9
- "test:cov": "jest --config ./test/jest-test.json --coverage"
9
+ "test:cov": "jest --config ./test/jest-test.json --coverage",
10
+ "type-check": "tsc --noEmit -p tsconfig.json",
11
+ "lint": "eslint -c .eslintrc.js",
12
+ "lint:fix": "eslint -c .eslintrc.js --fix"
10
13
  },
11
14
  "author": "William Khoo",
12
15
  "license": "ISC",
16
+ "engines": {
17
+ "node": "^20.19.0 || >=22.12.0"
18
+ },
13
19
  "types": "dist/index.d.ts",
14
20
  "main": "dist/index.js",
15
21
  "dependencies": {
16
- "@nathapp/nestjs-common": "^3.2.1"
22
+ "@nathapp/nestjs-common": "^4.0.0"
17
23
  },
18
24
  "devDependencies": {
19
25
  "@golevelup/ts-jest": "^0.6.1",
@@ -23,7 +29,7 @@
23
29
  "typescript": "^5"
24
30
  },
25
31
  "peerDependencies": {
26
- "@nathapp/nestjs-common": "^3.0.0",
27
- "@nestjs/common": "^10.0.0 || ^11.0.0"
32
+ "@nathapp/nestjs-common": "^4.0.0-rc.0",
33
+ "@nestjs/common": "^10.0.0 || ^11.0.0 || ^12.0.0"
28
34
  }
29
35
  }
@@ -0,0 +1,27 @@
1
+ {
2
+ "moduleFileExtensions": ["js", "json", "ts", "d.ts"],
3
+ "rootDir": "../",
4
+ "testEnvironment": "node",
5
+ "testMatch": ["**/.nax/**/*.test.ts"],
6
+ "transform": {
7
+ "^.+\\.(t)s$": [
8
+ "ts-jest",
9
+ {
10
+ "diagnostics": true,
11
+ "tsconfig": {
12
+ "esModuleInterop": true,
13
+ "emitDecoratorMetadata": true,
14
+ "experimentalDecorators": true
15
+ }
16
+ }
17
+ ]
18
+ },
19
+ "collectCoverageFrom": [
20
+ "lib/**/*.ts",
21
+ "!lib/**/*.spec.ts",
22
+ "!lib/**/*.d.ts",
23
+ "!**/node_modules/**"
24
+ ],
25
+ "forceExit": true,
26
+ "maxWorkers": 1
27
+ }
@@ -20,5 +20,6 @@
20
20
  "collectCoverageFrom": [
21
21
  "lib/**/*.ts",
22
22
  "!**/node_modules/**"
23
- ]
23
+ ],
24
+ "coverageProvider": "v8"
24
25
  }