@gzl10/nexus-backend 0.1.4 → 0.11.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.
Files changed (7) hide show
  1. package/README.md +141 -16
  2. package/dist/index.d.ts +1079 -371
  3. package/dist/index.js +8016 -1449
  4. package/dist/index.js.map +1 -1
  5. package/package.json +29 -2
  6. package/public/mail/base.html +54 -0
  7. package/public/nexus/nexus-light-512.png +0 -0
package/README.md CHANGED
@@ -1,4 +1,10 @@
1
- # nexus-backend
1
+ # @gzl10/nexus-backend
2
+
3
+ [![pipeline status](https://gitlab.gzl10.com/oss/nexus-backend/badges/main/pipeline.svg)](https://gitlab.gzl10.com/oss/nexus-backend/-/pipelines)
4
+ [![npm version](https://img.shields.io/npm/v/@gzl10/nexus-backend.svg)](https://www.npmjs.com/package/@gzl10/nexus-backend)
5
+ [![npm downloads](https://img.shields.io/npm/dm/@gzl10/nexus-backend.svg)](https://www.npmjs.com/package/@gzl10/nexus-backend)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
2
8
 
3
9
  > **Warning**: This project is currently in testing/experimental phase. Use at your own risk.
4
10
 
@@ -9,18 +15,20 @@ Backend as a Service (BaaS) with Express 5, Knex and CASL. Ready to use as an np
9
15
  ## Installation
10
16
 
11
17
  ```bash
12
- pnpm add nexus-backend
18
+ pnpm add @gzl10/nexus-backend
13
19
  ```
14
20
 
15
21
  ## Usage
16
22
 
17
23
  ```typescript
18
- import { start, stop, nexusEvents } from 'nexus-backend'
24
+ import { start, stop, nexusEvents } from '@gzl10/nexus-backend'
25
+
26
+ // Required auth secret (env)
27
+ process.env.AUTH_SECRET = 'your-secret-at-least-32-characters'
19
28
 
20
29
  // Start server
21
30
  await start({
22
31
  port: 3000,
23
- jwt: { secret: 'your-secret-at-least-32-characters' },
24
32
  database: { url: 'file:./data.db' }
25
33
  })
26
34
 
@@ -35,15 +43,40 @@ await stop()
35
43
 
36
44
  ## Configuration
37
45
 
38
- | Option | Description | Default |
39
- | -------------------- | ------------------------ | ----------------------- |
40
- | `port` | Server port | `3000` |
41
- | `host` | Server host | `0.0.0.0` |
42
- | `database.url` | Database URL | `file:./dev.db` |
43
- | `jwt.secret` | JWT secret (min 32 chars)| Required |
44
- | `jwt.accessExpires` | Access token expiration | `15m` |
45
- | `jwt.refreshExpires` | Refresh token expiration | `7d` |
46
- | `cors.origin` | Allowed CORS origin | `http://localhost:3001` |
46
+ ### Programmatic Options
47
+
48
+ | Option | Description | Default |
49
+ | -------------- | ------------------- | ----------------------- |
50
+ | `port` | Server port | `3000` |
51
+ | `host` | Server host | `0.0.0.0` |
52
+ | `homePath` | Home path (redirect `/`) | `/ui` |
53
+ | `database.url` | Database URL | `file:./dev.db` |
54
+ | `cors.origin` | Allowed CORS origin | `http://localhost:3001` |
55
+ | `timezone` | Server timezone | `Europe/Madrid` |
56
+ | `admin.email` | Admin email (seed) | Optional |
57
+ | `admin.password` | Admin password (seed) | Optional |
58
+
59
+ ### Environment Variables (Core)
60
+
61
+ | Variable | Description | Default |
62
+ | ---------------- | -------------------------- | ---------------------- |
63
+ | `NODE_ENV` | Environment | `development` |
64
+ | `PORT` | Server port | `3000` |
65
+ | `HOME_PATH` | Home path (redirect `/`) | `/ui` |
66
+ | `CORS_ORIGIN` | Allowed CORS origin | `http://localhost:3001`|
67
+ | `DATABASE_URL` | Database URL | `file:./dev.db` |
68
+ | `ADMIN_EMAIL` | Admin email (seed) | Optional |
69
+ | `ADMIN_PASSWORD` | Admin password (seed) | Optional |
70
+ | `BACKEND_URL` | Base URL for logs/CLI | Optional |
71
+ | `TZ` | Server timezone | `Europe/Madrid` |
72
+
73
+ ### Environment Variables (Auth)
74
+
75
+ | Variable | Description | Default |
76
+ | ---------------------- | ------------------------------ | --------- |
77
+ | `AUTH_SECRET` | JWT secret (min 32 chars) | Required |
78
+ | `AUTH_ACCESS_EXPIRES` | Access token expiration | `15m` |
79
+ | `AUTH_REFRESH_EXPIRES` | Refresh token expiration | `7d` |
47
80
 
48
81
  ### Supported Databases
49
82
 
@@ -54,11 +87,78 @@ await stop()
54
87
  ## API Endpoints
55
88
 
56
89
  - `POST /api/v1/auth/login` - Login
57
- - `POST /api/v1/auth/register` - Register
58
90
  - `POST /api/v1/auth/refresh` - Refresh token
91
+ - `POST /api/v1/auth/logout` - Logout
59
92
  - `GET /api/v1/users` - List users
60
- - `GET /api/v1/posts` - List posts
61
- - `GET /api/health` - Health check
93
+ - `GET /api/v1/users/roles` - List roles
94
+ - `GET /api/v1/system/modules` - List modules
95
+ - `GET /api/v1/storage/files` - List files
96
+ - `GET /health` - Health check
97
+ - `GET /api/openapi.json` - OpenAPI spec
98
+
99
+ ## Architecture
100
+
101
+ ```text
102
+ ┌──────────────────────────────────────────────────────────────────────────┐
103
+ │ NEXUS-BACKEND │
104
+ ├──────────────────────────────────────────────────────────────────────────┤
105
+ │ │
106
+ │ ┌────────────────────────────────────────────────────────────────────┐ │
107
+ │ │ ENGINE │ │
108
+ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
109
+ │ │ │ Registry │ │ Loader │ │ Queries │ │ │
110
+ │ │ │ (modules & │ │ (core mods) │ │ (getModules, getPlugins)│ │ │
111
+ │ │ │ plugins) │ │ │ │ │ │ │
112
+ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
113
+ │ └────────────────────────────────────────────────────────────────────┘ │
114
+ │ │ │
115
+ │ ▼ │
116
+ │ ┌────────────────────────────────────────────────────────────────────┐ │
117
+ │ │ RUNTIME │ │
118
+ │ │ EntityDefinition ──► Service ──► Controller ──► Routes │ │
119
+ │ │ │ │
120
+ │ │ Para cada entity en module.definitions[]: │ │
121
+ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ │
122
+ │ │ │ CollectionService│ │EntityController │ │ GET /items │ │ │
123
+ │ │ │ SingleService │ ──►│ (findAll, │ ──►│ GET /items/:id │ │ │
124
+ │ │ │ EventService │ │ findById, │ │ POST /items │ │ │
125
+ │ │ │ ActionService │ │ create, ...) │ │ PUT /items/:id │ │ │
126
+ │ │ │ ... │ │ │ │ DELETE /... │ │ │
127
+ │ │ └─────────────────┘ └─────────────────┘ └────────────────┘ │ │
128
+ │ └────────────────────────────────────────────────────────────────────┘ │
129
+ │ ▲ │
130
+ │ ┌──────────────────────────┼──────────────────────────┐ │
131
+ │ │ │ │ │
132
+ │ ┌──────┴───────┐ ┌───────┴───────┐ ┌───────┴───────┐ │
133
+ │ │ MODULE │ │ MODULE │ │ PLUGIN │ │
134
+ │ │ (core) │ │ (core) │ │ (external) │ │
135
+ │ ├──────────────┤ ├───────────────┤ ├───────────────┤ │
136
+ │ │ name: auth │ │ name: users │ │ name: cms │ │
137
+ │ │ definitions: │ │ definitions: │ │ definitions: │ │
138
+ │ │ - tokens │ │ - users │ │ - posts │ │
139
+ │ │ (temp) │ │ (collection│ │ (collection│ │
140
+ │ │ - audit │ │ - roles │ │ - pages │ │
141
+ │ │ (event) │ │ (collection│ │ (collection│ │
142
+ │ └──────────────┘ └───────────────┘ └───────────────┘ │
143
+ │ │
144
+ └──────────────────────────────────────────────────────────────────────────┘
145
+ ```
146
+
147
+ ### Entity Types
148
+
149
+ | Type | Operations | Use Case |
150
+ | ---------- | ----------------- | --------------------------------------------- |
151
+ | collection | CRUD | Users, posts, products, orders |
152
+ | single | GET, PUT | App settings, site config, preferences |
153
+ | reference | GET (read-only) | Countries, currencies, status codes |
154
+ | event | GET, POST | Audit logs, activity history, notifications |
155
+ | action | POST /execute | Send email, process payment, generate report |
156
+ | temp | CRUD + TTL | Sessions, OTP codes, temporary tokens |
157
+ | config | GET, PUT (scoped) | Module settings, feature flags per tenant |
158
+ | view | GET (query) | Dashboard stats, aggregated reports |
159
+ | computed | GET (on-demand) | Real-time metrics, calculated fields |
160
+ | external | GET (adapter) | Third-party APIs, external databases |
161
+ | virtual | GET (combine) | Unified search, merged data from sources |
62
162
 
63
163
  ## Development
64
164
 
@@ -71,6 +171,31 @@ pnpm db:migrate # Run migrations
71
171
  pnpm db:seed # Initial seed
72
172
  ```
73
173
 
174
+ ## Testing
175
+
176
+ ```bash
177
+ pnpm test # Run all tests
178
+ pnpm test:coverage # Run tests with coverage
179
+ ```
180
+
181
+ ### Coverage Summary
182
+
183
+ | Metric | Coverage |
184
+ | ---------- | -------- |
185
+ | Statements | 76% |
186
+ | Branches | 65% |
187
+ | Functions | 79% |
188
+ | Lines | 77% |
189
+
190
+ ### Test Structure
191
+
192
+ | Directory | Description |
193
+ | ---------------------- | -------------------------------- |
194
+ | `test/runtime/` | Unit tests for entity services |
195
+ | `test/runtime/routes/` | Integration tests with supertest |
196
+
197
+ All 11 entity types are tested (see [Entity Types](#entity-types)).
198
+
74
199
  ## Support
75
200
 
76
201
  <a href="https://www.buymeacoffee.com/gzl10g" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>