@nathapp/nestjs-data 3.2.1 → 3.3.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 +8 -0
- package/.turbo/turbo-build.log +1 -1
- package/AGENTS.md +62 -0
- package/CHANGELOG.md +6 -0
- package/CLAUDE.md +18 -0
- package/GEMINI.md +60 -0
- package/README.md +79 -0
- package/codex.md +60 -0
- package/package.json +6 -3
- package/test/jest-nax.json +27 -0
- package/test/jest-test.json +2 -1
package/.eslintrc.js
ADDED
package/.turbo/turbo-build.log
CHANGED
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
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,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nathapp/nestjs-data",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.3.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",
|
|
13
16
|
"types": "dist/index.d.ts",
|
|
14
17
|
"main": "dist/index.js",
|
|
15
18
|
"dependencies": {
|
|
16
|
-
"@nathapp/nestjs-common": "^3.
|
|
19
|
+
"@nathapp/nestjs-common": "^3.3.0"
|
|
17
20
|
},
|
|
18
21
|
"devDependencies": {
|
|
19
22
|
"@golevelup/ts-jest": "^0.6.1",
|
|
@@ -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
|
+
}
|