@seip/bluebird-js 0.0.1 → 0.1.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 (81) hide show
  1. package/.env_example +53 -53
  2. package/AGENTS.md +426 -403
  3. package/LICENSE +1 -1
  4. package/README.md +292 -285
  5. package/app/routes/api.js +50 -50
  6. package/app/routes/web.js +55 -53
  7. package/app/views/about.js +63 -0
  8. package/app/views/dashboard.js +147 -0
  9. package/app/views/index.js +80 -0
  10. package/app/views/layouts/main/view.js +81 -0
  11. package/app/views/legal/terms.html +19 -0
  12. package/app/views/login.js +80 -0
  13. package/core/app.d.ts +18 -18
  14. package/core/app.js +684 -644
  15. package/core/auth.d.ts +13 -13
  16. package/core/auth.js +326 -326
  17. package/core/cache.d.ts +17 -17
  18. package/core/cache.js +475 -475
  19. package/core/cli/doctor.js +287 -287
  20. package/core/cli/ecosystem.js +162 -162
  21. package/core/cli/init.js +779 -779
  22. package/core/cli/migrate.js +541 -541
  23. package/core/cli/model.js +66 -66
  24. package/core/cli/nginx.js +199 -199
  25. package/core/cli/route.js +120 -120
  26. package/core/cli/view.js +55 -36
  27. package/core/config.d.ts +3 -3
  28. package/core/config.js +111 -111
  29. package/core/csrf.d.ts +3 -3
  30. package/core/csrf.js +114 -114
  31. package/core/database.d.ts +15 -15
  32. package/core/database.js +636 -636
  33. package/core/debug.d.ts +3 -3
  34. package/core/debug.js +249 -249
  35. package/core/hash.d.ts +3 -3
  36. package/core/hash.js +194 -194
  37. package/core/html.d.ts +42 -0
  38. package/core/html.js +217 -0
  39. package/core/index.d.ts +1176 -1071
  40. package/core/logger.d.ts +3 -3
  41. package/core/logger.js +127 -124
  42. package/core/middleware.d.ts +3 -3
  43. package/core/middleware.js +28 -28
  44. package/core/model.d.ts +19 -19
  45. package/core/model.js +600 -600
  46. package/core/queue.d.ts +13 -13
  47. package/core/queue.js +172 -172
  48. package/core/ratelimit.d.ts +3 -3
  49. package/core/ratelimit.js +145 -145
  50. package/core/redis.d.ts +21 -21
  51. package/core/redis.js +230 -230
  52. package/core/render-cache.js +212 -0
  53. package/core/render.d.ts +3 -3
  54. package/core/render.js +199 -555
  55. package/core/router.d.ts +3 -3
  56. package/core/router.js +171 -171
  57. package/core/seo.d.ts +3 -3
  58. package/core/seo.js +106 -106
  59. package/core/swagger.d.ts +3 -3
  60. package/core/swagger.js +60 -60
  61. package/core/upload.d.ts +13 -13
  62. package/core/upload.js +102 -102
  63. package/core/util/colors.js +82 -82
  64. package/core/validate.d.ts +15 -15
  65. package/core/validate.js +364 -364
  66. package/core/view-loader.js +162 -0
  67. package/core/vite.d.ts +3 -3
  68. package/core/vite.js +145 -145
  69. package/core/ws.d.ts +13 -13
  70. package/core/ws.js +245 -245
  71. package/index.js +18 -18
  72. package/jsconfig.json +15 -15
  73. package/package.json +85 -86
  74. package/production.md +273 -273
  75. package/public/css/bluebird.min.css +1 -1
  76. package/public/js/bluebird-client.js +1780 -1662
  77. package/public/js/bluebird.min.js +1072 -1072
  78. package/app/views/about.html +0 -161
  79. package/app/views/dashboard.html +0 -140
  80. package/app/views/index.html +0 -150
  81. package/app/views/login.html +0 -144
package/production.md CHANGED
@@ -1,273 +1,273 @@
1
- # Bluebird.js - Production Deployment Guide
2
-
3
- This guide covers recommended strategies for deploying a `@seip/bluebird-js` application in production environments. Bluebird is designed to be lightweight, native-first, and unopinionated about infrastructure, allowing you to choose the deployment pattern that best fits your workflow.
4
-
5
- ---
6
-
7
- ## 1. Quick Start: Standard Node.js (`npm start`)
8
-
9
- For single-instance VPS hosts, developer previews, or container runtimes, you can start the application directly using Node.js:
10
-
11
- ```bash
12
- npm run start
13
- ```
14
-
15
- This runs:
16
- ```bash
17
- node --env-file=.env index.js
18
- ```
19
-
20
- ### Production Checklist Before Starting
21
- - Set `DEBUG=false` in `.env`.
22
- - Ensure `JWT_SECRET` is set to a secure, random string (minimum 32 characters).
23
- - Ensure your database path or connection credentials in `.env` are secure and isolated.
24
-
25
- ---
26
-
27
- ## 2. Recommended: PM2 Process Manager
28
-
29
- PM2 provides automatic restarts on crashes, cluster mode across multi-core CPUs, log management, and system boot persistence.
30
-
31
- ### Step 1: Generate Ecosystem Configuration
32
-
33
- Bluebird provides a built-in CLI command to generate a production-ready `ecosystem.config.cjs`:
34
-
35
- ```bash
36
- npx bluebird-js make:ecosystem
37
- ```
38
-
39
- This command inspects your `.env` file for settings such as `TITLE`, `PM2_APP_NAME`, `PM2_INSTANCES`, and `PM2_MAX_MEMORY`, automatically configuring clustering and worker jobs found in `app/jobs/`.
40
-
41
- ### Step 2: Start and Save Immediately
42
-
43
- You can generate the configuration, start the application, and save the PM2 state in a single step:
44
-
45
- ```bash
46
- npx bluebird-js make:ecosystem --start
47
- ```
48
-
49
- Or execute the steps manually:
50
-
51
- ```bash
52
- pm2 start ecosystem.config.cjs
53
- pm2 save
54
- ```
55
-
56
- ### Step 3: Configure Startup on Server Reboot
57
-
58
- Generate and execute the systemd startup script:
59
-
60
- ```bash
61
- pm2 startup
62
- ```
63
-
64
- Follow the instruction printed by PM2 to register the startup hook with your system daemon.
65
-
66
- ### Useful PM2 Management Commands
67
-
68
- ```bash
69
- pm2 status # View status of running processes
70
- pm2 logs # Stream consolidated logs
71
- pm2 reload all --update-env # Zero-downtime rolling reload with updated .env
72
- pm2 restart all # Restart all instances
73
- pm2 stop all # Stop all instances
74
- pm2 delete all # Remove all processes from PM2
75
- ```
76
-
77
- ---
78
-
79
- ## 3. Systemd Service (Alternative to PM2)
80
-
81
- If you prefer native Linux systemd services instead of PM2:
82
-
83
- Create `/etc/systemd/system/bluebird.service`:
84
-
85
- ```ini
86
- [Unit]
87
- Description=Bluebird Application Service
88
- After=network.target
89
-
90
- [Service]
91
- Type=simple
92
- User=www-data
93
- WorkingDirectory=/var/www/bluebird-app
94
- ExecStart=/usr/bin/node --env-file=.env index.js
95
- Restart=always
96
- RestartSec=5
97
- Environment=NODE_ENV=production
98
- LimitNOFILE=65535
99
-
100
- [Install]
101
- WantedBy=multi-user.target
102
- ```
103
-
104
- Enable and start the service:
105
-
106
- ```bash
107
- sudo systemctl daemon-reload
108
- sudo systemctl enable bluebird
109
- sudo systemctl start bluebird
110
- sudo systemctl status bluebird
111
- ```
112
-
113
- ---
114
-
115
- ## 4. Nginx Reverse Proxy & SSL
116
-
117
- Expose your application securely on port 80/443 using Nginx as a reverse proxy.
118
-
119
- ### Step 1: Generate Nginx Configuration
120
-
121
- Run the Bluebird CLI helper to generate an optimized Nginx block (defaults to your current working directory or accepts a custom project path):
122
-
123
- ```bash
124
- npx bluebird-js nginx:conf yourdomain.com 3000 /var/www/my-project
125
- ```
126
-
127
- ### Step 2: Install Configuration on VPS
128
-
129
- Create the site configuration file:
130
-
131
- ```bash
132
- sudo nano /etc/nginx/sites-available/yourdomain.com
133
- ```
134
-
135
- Paste the generated snippet (featuring `upstream` keepalive connections, `5M` body limit, direct static delivery via `try_files`, and `@bluebird` Express fallback):
136
-
137
- ```nginx
138
- upstream bluebird_yourdomain_com {
139
- server 127.0.0.1:3000;
140
- keepalive 64;
141
- }
142
-
143
- server {
144
- listen 80;
145
- listen [::]:80;
146
- server_name yourdomain.com;
147
-
148
- root /var/www/my-project/public;
149
- client_max_body_size 5M;
150
-
151
- gzip on;
152
- gzip_vary on;
153
- gzip_proxied any;
154
- gzip_comp_level 6;
155
- gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;
156
-
157
- location ~* /\.(env|git|svn|htaccess|DS_Store) {
158
- deny all;
159
- return 404;
160
- }
161
-
162
- location /dist/ {
163
- try_files $uri =404;
164
- expires 1y;
165
- add_header Cache-Control "public, max-age=31536000, immutable";
166
- access_log off;
167
- }
168
-
169
- location ~* \.(?:css|js|mjs|jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc|woff|woff2|ttf|eot|webp|avif)$ {
170
- try_files $uri =404;
171
- expires 30d;
172
- add_header Cache-Control "public, max-age=2592000, immutable";
173
- access_log off;
174
- }
175
-
176
- location / {
177
- try_files $uri @bluebird;
178
- }
179
-
180
- location @bluebird {
181
- proxy_pass http://bluebird_yourdomain_com;
182
- proxy_http_version 1.1;
183
-
184
- proxy_set_header Upgrade $http_upgrade;
185
- proxy_set_header Connection $http_connection;
186
-
187
- proxy_set_header Host $host;
188
- proxy_set_header X-Real-IP $remote_addr;
189
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
190
- proxy_set_header X-Forwarded-Proto $scheme;
191
- proxy_set_header X-Forwarded-Host $host;
192
- proxy_set_header X-Forwarded-Port $server_port;
193
-
194
- proxy_connect_timeout 60s;
195
- proxy_send_timeout 60s;
196
- proxy_read_timeout 60s;
197
- }
198
- }
199
- ```
200
-
201
- Enable and reload Nginx:
202
-
203
- ```bash
204
- sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
205
- sudo nginx -t
206
- sudo systemctl reload nginx
207
- ```
208
-
209
- ### Step 3: Enable Free SSL with Let's Encrypt
210
-
211
- ```bash
212
- sudo certbot --nginx -d yourdomain.com
213
- ```
214
-
215
- ---
216
-
217
- ## 5. Optional: Standalone Docker Deployment
218
-
219
- If you prefer containerizing your application independently, here are minimal, production-ready standalone files you can add to your project:
220
-
221
- ### `Dockerfile`
222
-
223
- ```dockerfile
224
- FROM node:22-alpine
225
-
226
- WORKDIR /app
227
-
228
- ENV NODE_ENV=production
229
-
230
- COPY package*.json ./
231
-
232
- RUN npm ci --only=production
233
-
234
- COPY . .
235
-
236
- EXPOSE 3000
237
-
238
- CMD ["node", "--env-file=.env", "index.js"]
239
- ```
240
-
241
- ### `docker-compose.yml`
242
-
243
- ```yaml
244
- services:
245
- app:
246
- build: .
247
- restart: unless-stopped
248
- ports:
249
- - "127.0.0.1:3000:3000"
250
- env_file:
251
- - .env
252
- volumes:
253
- - ./database:/app/database
254
- - ./app/cache:/app/app/cache
255
- - ./logs:/app/logs
256
- ```
257
-
258
- Run containers:
259
-
260
- ```bash
261
- docker compose up -d --build
262
- ```
263
-
264
- ---
265
-
266
- ## 6. Cache and Scaling Recommendations
267
-
268
- | Deployment Profile | Recommended Cache | Database Recommendation |
269
- |---|---|---|
270
- | **Desktop App (Electron/Tauri)** | `CACHE_MODE=memory` | SQLite (`DB_TYPE=sqlite`) |
271
- | **Single VPS (`PM2_INSTANCES=1`)** | `CACHE_MODE=memory` or `CACHE_MODE=file` | SQLite or PostgreSQL/MySQL |
272
- | **Multi-Core Cluster (`PM2_INSTANCES=max`)** | `CACHE_MODE=memory` (per worker) or `CACHE_MODE=redis` | PostgreSQL or MySQL |
273
- | **Multi-Server Distributed Cluster** | `CACHE_MODE=redis` | PostgreSQL or MySQL |
1
+ # Bluebird.js - Production Deployment Guide
2
+
3
+ This guide covers recommended strategies for deploying a `@seip/bluebird-js` application in production environments. Bluebird is designed to be lightweight, native-first, and unopinionated about infrastructure, allowing you to choose the deployment pattern that best fits your workflow.
4
+
5
+ ---
6
+
7
+ ## 1. Quick Start: Standard Node.js (`npm start`)
8
+
9
+ For single-instance VPS hosts, developer previews, or container runtimes, you can start the application directly using Node.js:
10
+
11
+ ```bash
12
+ npm run start
13
+ ```
14
+
15
+ This runs:
16
+ ```bash
17
+ node --env-file=.env index.js
18
+ ```
19
+
20
+ ### Production Checklist Before Starting
21
+ - Set `DEBUG=false` in `.env`.
22
+ - Ensure `JWT_SECRET` is set to a secure, random string (minimum 32 characters).
23
+ - Ensure your database path or connection credentials in `.env` are secure and isolated.
24
+
25
+ ---
26
+
27
+ ## 2. Recommended: PM2 Process Manager
28
+
29
+ PM2 provides automatic restarts on crashes, cluster mode across multi-core CPUs, log management, and system boot persistence.
30
+
31
+ ### Step 1: Generate Ecosystem Configuration
32
+
33
+ Bluebird provides a built-in CLI command to generate a production-ready `ecosystem.config.cjs`:
34
+
35
+ ```bash
36
+ npx bluebird-js make:ecosystem
37
+ ```
38
+
39
+ This command inspects your `.env` file for settings such as `TITLE`, `PM2_APP_NAME`, `PM2_INSTANCES`, and `PM2_MAX_MEMORY`, automatically configuring clustering and worker jobs found in `app/jobs/`.
40
+
41
+ ### Step 2: Start and Save Immediately
42
+
43
+ You can generate the configuration, start the application, and save the PM2 state in a single step:
44
+
45
+ ```bash
46
+ npx bluebird-js make:ecosystem --start
47
+ ```
48
+
49
+ Or execute the steps manually:
50
+
51
+ ```bash
52
+ pm2 start ecosystem.config.cjs
53
+ pm2 save
54
+ ```
55
+
56
+ ### Step 3: Configure Startup on Server Reboot
57
+
58
+ Generate and execute the systemd startup script:
59
+
60
+ ```bash
61
+ pm2 startup
62
+ ```
63
+
64
+ Follow the instruction printed by PM2 to register the startup hook with your system daemon.
65
+
66
+ ### Useful PM2 Management Commands
67
+
68
+ ```bash
69
+ pm2 status # View status of running processes
70
+ pm2 logs # Stream consolidated logs
71
+ pm2 reload all --update-env # Zero-downtime rolling reload with updated .env
72
+ pm2 restart all # Restart all instances
73
+ pm2 stop all # Stop all instances
74
+ pm2 delete all # Remove all processes from PM2
75
+ ```
76
+
77
+ ---
78
+
79
+ ## 3. Systemd Service (Alternative to PM2)
80
+
81
+ If you prefer native Linux systemd services instead of PM2:
82
+
83
+ Create `/etc/systemd/system/bluebird.service`:
84
+
85
+ ```ini
86
+ [Unit]
87
+ Description=Bluebird Application Service
88
+ After=network.target
89
+
90
+ [Service]
91
+ Type=simple
92
+ User=www-data
93
+ WorkingDirectory=/var/www/bluebird-app
94
+ ExecStart=/usr/bin/node --env-file=.env index.js
95
+ Restart=always
96
+ RestartSec=5
97
+ Environment=NODE_ENV=production
98
+ LimitNOFILE=65535
99
+
100
+ [Install]
101
+ WantedBy=multi-user.target
102
+ ```
103
+
104
+ Enable and start the service:
105
+
106
+ ```bash
107
+ sudo systemctl daemon-reload
108
+ sudo systemctl enable bluebird
109
+ sudo systemctl start bluebird
110
+ sudo systemctl status bluebird
111
+ ```
112
+
113
+ ---
114
+
115
+ ## 4. Nginx Reverse Proxy & SSL
116
+
117
+ Expose your application securely on port 80/443 using Nginx as a reverse proxy.
118
+
119
+ ### Step 1: Generate Nginx Configuration
120
+
121
+ Run the Bluebird CLI helper to generate an optimized Nginx block (defaults to your current working directory or accepts a custom project path):
122
+
123
+ ```bash
124
+ npx bluebird-js nginx:conf yourdomain.com 3000 /var/www/my-project
125
+ ```
126
+
127
+ ### Step 2: Install Configuration on VPS
128
+
129
+ Create the site configuration file:
130
+
131
+ ```bash
132
+ sudo nano /etc/nginx/sites-available/yourdomain.com
133
+ ```
134
+
135
+ Paste the generated snippet (featuring `upstream` keepalive connections, `5M` body limit, direct static delivery via `try_files`, and `@bluebird` Express fallback):
136
+
137
+ ```nginx
138
+ upstream bluebird_yourdomain_com {
139
+ server 127.0.0.1:3000;
140
+ keepalive 64;
141
+ }
142
+
143
+ server {
144
+ listen 80;
145
+ listen [::]:80;
146
+ server_name yourdomain.com;
147
+
148
+ root /var/www/my-project/public;
149
+ client_max_body_size 5M;
150
+
151
+ gzip on;
152
+ gzip_vary on;
153
+ gzip_proxied any;
154
+ gzip_comp_level 6;
155
+ gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;
156
+
157
+ location ~* /\.(env|git|svn|htaccess|DS_Store) {
158
+ deny all;
159
+ return 404;
160
+ }
161
+
162
+ location /dist/ {
163
+ try_files $uri =404;
164
+ expires 1y;
165
+ add_header Cache-Control "public, max-age=31536000, immutable";
166
+ access_log off;
167
+ }
168
+
169
+ location ~* \.(?:css|js|mjs|jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc|woff|woff2|ttf|eot|webp|avif)$ {
170
+ try_files $uri =404;
171
+ expires 30d;
172
+ add_header Cache-Control "public, max-age=2592000, immutable";
173
+ access_log off;
174
+ }
175
+
176
+ location / {
177
+ try_files $uri @bluebird;
178
+ }
179
+
180
+ location @bluebird {
181
+ proxy_pass http://bluebird_yourdomain_com;
182
+ proxy_http_version 1.1;
183
+
184
+ proxy_set_header Upgrade $http_upgrade;
185
+ proxy_set_header Connection $http_connection;
186
+
187
+ proxy_set_header Host $host;
188
+ proxy_set_header X-Real-IP $remote_addr;
189
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
190
+ proxy_set_header X-Forwarded-Proto $scheme;
191
+ proxy_set_header X-Forwarded-Host $host;
192
+ proxy_set_header X-Forwarded-Port $server_port;
193
+
194
+ proxy_connect_timeout 60s;
195
+ proxy_send_timeout 60s;
196
+ proxy_read_timeout 60s;
197
+ }
198
+ }
199
+ ```
200
+
201
+ Enable and reload Nginx:
202
+
203
+ ```bash
204
+ sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
205
+ sudo nginx -t
206
+ sudo systemctl reload nginx
207
+ ```
208
+
209
+ ### Step 3: Enable Free SSL with Let's Encrypt
210
+
211
+ ```bash
212
+ sudo certbot --nginx -d yourdomain.com
213
+ ```
214
+
215
+ ---
216
+
217
+ ## 5. Optional: Standalone Docker Deployment
218
+
219
+ If you prefer containerizing your application independently, here are minimal, production-ready standalone files you can add to your project:
220
+
221
+ ### `Dockerfile`
222
+
223
+ ```dockerfile
224
+ FROM node:22-alpine
225
+
226
+ WORKDIR /app
227
+
228
+ ENV NODE_ENV=production
229
+
230
+ COPY package*.json ./
231
+
232
+ RUN npm ci --only=production
233
+
234
+ COPY . .
235
+
236
+ EXPOSE 3000
237
+
238
+ CMD ["node", "--env-file=.env", "index.js"]
239
+ ```
240
+
241
+ ### `docker-compose.yml`
242
+
243
+ ```yaml
244
+ services:
245
+ app:
246
+ build: .
247
+ restart: unless-stopped
248
+ ports:
249
+ - "127.0.0.1:3000:3000"
250
+ env_file:
251
+ - .env
252
+ volumes:
253
+ - ./database:/app/database
254
+ - ./app/cache:/app/app/cache
255
+ - ./logs:/app/logs
256
+ ```
257
+
258
+ Run containers:
259
+
260
+ ```bash
261
+ docker compose up -d --build
262
+ ```
263
+
264
+ ---
265
+
266
+ ## 6. Cache and Scaling Recommendations
267
+
268
+ | Deployment Profile | Recommended Cache | Database Recommendation |
269
+ |---|---|---|
270
+ | **Desktop App (Electron/Tauri)** | `CACHE_MODE=memory` | SQLite (`DB_TYPE=sqlite`) |
271
+ | **Single VPS (`PM2_INSTANCES=1`)** | `CACHE_MODE=memory` or `CACHE_MODE=file` | SQLite or PostgreSQL/MySQL |
272
+ | **Multi-Core Cluster (`PM2_INSTANCES=max`)** | `CACHE_MODE=memory` (per worker) or `CACHE_MODE=redis` | PostgreSQL or MySQL |
273
+ | **Multi-Server Distributed Cluster** | `CACHE_MODE=redis` | PostgreSQL or MySQL |