@xrystal/core 3.38.3 → 3.40.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/README.md +397 -65
- package/package.json +2 -4
- package/x/bin/commands/create.mjs +2 -1
- package/x/bin/commands/doctor.mjs +5 -4
- package/x/bin/commands/hooks.mjs +2 -1
- package/x/bin/commands/project.mjs +2 -1
- package/x/bin/commands/release.mjs +3 -2
- package/x/bin/commands/sync.mjs +51 -0
- package/x/bin/commands/tmp.mjs +2 -1
- package/x/bin/helpers/.generated/tmp-schema.mjs +54 -85
- package/x/bin/helpers/banner.mjs +2 -2
- package/x/bin/helpers/build-config.mjs +11 -2
- package/x/bin/helpers/cli-help.mjs +9 -9
- package/x/bin/helpers/cli-identity.mjs +7 -17
- package/x/bin/helpers/defaults.json +14 -30
- package/x/bin/helpers/package-defaults.mjs +46 -12
- package/x/bin/helpers/project-artifacts.mjs +7 -0
- package/x/bin/helpers/seed-from-tmp.mjs +52 -0
- package/x/bin/helpers/toolchain-config.mjs +6 -12
- package/x/bin/main-cli.js +2 -2
- package/x/bin/scripts/install-git-hooks.mjs +3 -2
- package/x/bin/scripts/sync-cli-defaults.mjs +7 -2
- package/x/dist/project/index.js +1 -1
- package/x/dist/utils/constants/defaults.json +14 -30
- package/x/dist/utils/constants/index.d.ts +20 -12
- package/x/dist/utils/constants/index.js +1 -1
- package/x/dist/utils/helpers/tmp/index.d.ts +2 -0
- package/x/dist/utils/helpers/tmp/index.js +1 -1
- package/x/dist/utils/helpers/tmp/path-normalize.d.ts +10 -0
- package/x/dist/utils/helpers/tmp/path-normalize.js +1 -0
- package/x/dist/utils/helpers/tmp/seed-from-tmp.d.ts +9 -0
- package/x/dist/utils/helpers/tmp/seed-from-tmp.js +1 -0
- package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -1
- package/x/dist/utils/helpers/tmp/tmp-schema.d.ts +1 -0
- package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -1
- package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -1
- package/x/bin/commands/sync-toolchain.mjs +0 -43
package/README.md
CHANGED
|
@@ -3,42 +3,77 @@
|
|
|
3
3
|
> **EN** — Microservice runtime: Express or Elysia HTTP, DI loaders, live `tmp.yml`, standardized API responses.
|
|
4
4
|
> **TR** — Microservice runtime: Express veya Elysia HTTP, DI loader'lar, canlı `tmp.yml`, standart API cevapları.
|
|
5
5
|
|
|
6
|
-
**CLI:** `
|
|
6
|
+
**CLI:** `xry` · **Version:** `3.40.0` · [npm](https://www.npmjs.com/package/@xrystal/core)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## What's new in 3.40.0 / 3.40.0'da ne değişti
|
|
11
|
+
|
|
12
|
+
| Change / Değişiklik | EN | TR |
|
|
13
|
+
|---------------------|----|----|
|
|
14
|
+
| **Single CLI** | Bin is only `xry` (`xcore` / `xrystal` / `tmp` removed) | Tek bin: `xry` (eski isimler kalktı) |
|
|
15
|
+
| **`xry sync`** | Writes `tsconfig` `include` / `outDir` / `@/*` from project `tmp.yml` | `tmp.yml` → tsconfig path sync |
|
|
16
|
+
| **Config SSOT** | Layout seed from bundled `x/tmp.yml` — not `defaults.json` | Layout seed = `x/tmp.yml`, `defaults.json` değil |
|
|
17
|
+
| **`defaults.json`** | Package identity + CLI + build flags only | Sadece kimlik, CLI, build flag'leri |
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx xry sync # apply tmp.yml → tsconfig / bunfig aliases
|
|
21
|
+
npx xry sync --dry-run
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**Breaking / Kırıcı:** replace scripts and docs that called `xcore`, `xrystal`, or the old `tmp` bin with `xry`.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Why / Neden
|
|
29
|
+
|
|
30
|
+
**EN:** `@xrystal/core` is a **kernel**, not only a GitHub template. Most teams already have their own repo layout, CI, Docker, or monorepo — they only need the runtime: DI, `tmp.yml`, `ctr()`, DTO, logger, i18n, trace. Use `xry create` if you want a starter; otherwise add the package to **your** project and seed `x/tmp.yml`.
|
|
31
|
+
|
|
32
|
+
**TR:** `@xrystal/core` bir **kernel** — sadece GitHub template değil. Çoğu ekipte zaten kendi repo düzeni, CI, Docker veya monorepo vardır; ihtiyaç duyulan şey runtime: DI, `tmp.yml`, `ctr()`, DTO, logger, i18n, trace. Sıfırdan başlıyorsan `xry create`; mevcut projende sadece paketi kur + `xry tmp` yeter.
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# EN: existing project — kernel only · TR: mevcut proje — sadece kernel
|
|
36
|
+
bun add @xrystal/core
|
|
37
|
+
npx xry tmp # seed x/tmp.yml into YOUR layout
|
|
38
|
+
npx xry sync # align tsconfig paths with tmp.yml
|
|
39
|
+
# wire coreLoader + dtoMiddleware in your entry file
|
|
40
|
+
```
|
|
7
41
|
|
|
8
42
|
---
|
|
9
43
|
|
|
10
44
|
## Quick start / Hızlı başlangıç
|
|
11
45
|
|
|
12
|
-
### Path A — `create` (
|
|
46
|
+
### Path A — `create` (starter template / başlangıç şablonu)
|
|
13
47
|
|
|
14
|
-
**EN:**
|
|
48
|
+
**EN:** Optional — clone GitHub template when you have no project yet.
|
|
15
49
|
|
|
16
|
-
**TR:**
|
|
50
|
+
**TR:** İsteğe bağlı — henüz proje yoksa GitHub template klonla.
|
|
17
51
|
|
|
18
52
|
```bash
|
|
19
53
|
mkdir my-api && cd my-api
|
|
20
54
|
bun init -y
|
|
21
55
|
bun add @xrystal/core
|
|
22
|
-
npx
|
|
56
|
+
npx xry create my-api .
|
|
23
57
|
```
|
|
24
58
|
|
|
25
59
|
```bash
|
|
26
60
|
bun add elysia # EN: or express · TR: veya express
|
|
27
61
|
bun run dev
|
|
28
|
-
npx
|
|
62
|
+
npx xry doctor # EN: setup check · TR: kurulum kontrolü
|
|
29
63
|
```
|
|
30
64
|
|
|
31
|
-
### Path B —
|
|
65
|
+
### Path B — Your project + kernel (most common / en yaygın)
|
|
32
66
|
|
|
33
|
-
**EN:**
|
|
67
|
+
**EN:** Keep your folder names — only add `tmp.yml`, `coreLoader`, controllers.
|
|
34
68
|
|
|
35
|
-
**TR:**
|
|
69
|
+
**TR:** Kendi klasör adların kalsın — sadece `tmp.yml`, `coreLoader`, controller ekle.
|
|
36
70
|
|
|
37
71
|
```bash
|
|
38
72
|
mkdir my-api && cd my-api
|
|
39
73
|
bun init -y
|
|
40
74
|
bun add @xrystal/core elysia
|
|
41
|
-
npx
|
|
75
|
+
npx xry tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa seed'den oluşturur
|
|
76
|
+
npx xry sync # EN: tsconfig from tmp.yml · TR: tmp.yml → tsconfig
|
|
42
77
|
```
|
|
43
78
|
|
|
44
79
|
`package.json`:
|
|
@@ -46,22 +81,23 @@ npx xcore tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa
|
|
|
46
81
|
```json
|
|
47
82
|
{
|
|
48
83
|
"dependencies": {
|
|
49
|
-
"@xrystal/core": "^3.
|
|
84
|
+
"@xrystal/core": "^3.40.0",
|
|
50
85
|
"elysia": "^1.4.19"
|
|
51
86
|
},
|
|
52
87
|
"scripts": {
|
|
53
|
-
"dev": "
|
|
54
|
-
"build": "
|
|
55
|
-
"start": "
|
|
56
|
-
"test": "
|
|
57
|
-
"
|
|
88
|
+
"dev": "xry dev",
|
|
89
|
+
"build": "xry build",
|
|
90
|
+
"start": "xry start",
|
|
91
|
+
"test": "xry test",
|
|
92
|
+
"sync": "xry sync",
|
|
93
|
+
"doctor": "xry doctor"
|
|
58
94
|
}
|
|
59
95
|
}
|
|
60
96
|
```
|
|
61
97
|
|
|
62
|
-
**EN:** No global `
|
|
98
|
+
**EN:** No global `xry` install — runs via `node_modules/.bin` after `bun add @xrystal/core`.
|
|
63
99
|
|
|
64
|
-
**TR:** Global `
|
|
100
|
+
**TR:** Global `xry` gerekmez — `@xrystal/core` kurulunca `node_modules/.bin` üzerinden çalışır.
|
|
65
101
|
|
|
66
102
|
### Project layout / Proje düzeni
|
|
67
103
|
|
|
@@ -69,14 +105,20 @@ npx xcore tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa
|
|
|
69
105
|
my-api/
|
|
70
106
|
├── package.json
|
|
71
107
|
├── source/
|
|
72
|
-
│ ├── index.ts # EN: dev entry (
|
|
108
|
+
│ ├── index.ts # EN: dev entry (xry dev) · TR: dev girişi
|
|
73
109
|
│ └── controllers/
|
|
74
110
|
└── x/
|
|
75
|
-
|
|
76
|
-
├── environments/ # .dev.env, .prod.env
|
|
77
|
-
└── tests/
|
|
111
|
+
└── tmp.yml # EN: runtime + path SSOT · TR: runtime + path tek kaynak
|
|
78
112
|
```
|
|
79
113
|
|
|
114
|
+
### Config sources / Config kaynakları
|
|
115
|
+
|
|
116
|
+
| File / Dosya | Owns / Sahip olduğu |
|
|
117
|
+
|--------------|---------------------|
|
|
118
|
+
| `x/tmp.yml` | Service paths, loaders, protocols, build flags · layout seed |
|
|
119
|
+
| `tsconfig.json` | Compiler language options; path layout via `xry sync` |
|
|
120
|
+
| Package defaults (internal) | CLI name (`xry`), package identity — not project layout |
|
|
121
|
+
|
|
80
122
|
### Minimal `x/tmp.yml`
|
|
81
123
|
|
|
82
124
|
```yaml
|
|
@@ -130,13 +172,158 @@ bun run dev
|
|
|
130
172
|
|
|
131
173
|
| Command / Komut | EN | TR |
|
|
132
174
|
|-----------------|----|----|
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
175
|
+
| `xry create [name] [path]` | Start project from template + `tmp.yml` | Template + `tmp.yml` ile proje başlat |
|
|
176
|
+
| `xry tmp` | Create `tmp.yml` from seed if missing | `tmp.yml` yoksa seed'den oluştur |
|
|
177
|
+
| `xry sync` | Sync `tsconfig` / aliases from `tmp.yml` | `tmp.yml` → `tsconfig` / alias |
|
|
178
|
+
| `xry dev` | Watch `source/index.ts` + dev env | `source/index.ts` watch + dev env |
|
|
179
|
+
| `xry build` | Output → `x/dist` | Çıktı → `x/dist` |
|
|
180
|
+
| `xry start` | Run `x/dist` + prod env | `x/dist` + prod env |
|
|
181
|
+
| `xry test` | Run `x/tests` | `x/tests` çalıştır |
|
|
182
|
+
| `xry doctor` | CLI, runtime, package health | CLI, runtime, paket uyumu |
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Platform features / Platform özellikleri
|
|
187
|
+
|
|
188
|
+
**EN:** What the kernel gives you — one line each + minimal example.
|
|
189
|
+
|
|
190
|
+
**TR:** Kernel'in verdiği yetenekler — tek satır + kısa örnek.
|
|
191
|
+
|
|
192
|
+
| Feature / Özellik | EN | TR | Example / Örnek |
|
|
193
|
+
|-------------------|----|----|-----------------|
|
|
194
|
+
| **Boot / DI** | Awilix loaders: System, Logger, Kafka, Dto, i18n, … | Awilix loader'lar | `await coreLoader({})` |
|
|
195
|
+
| **Live `tmp.yml`** | Edit file → loaders re-sync without restart | Dosya değişince loader sync | `logLevel: debug` → save → logger updates |
|
|
196
|
+
| **`ctr()` pipeline** | `checks → logic → response`, no `res.json()` | Endpoint pipeline | `list = this.ctr({ logic: async () => ({ data: [] }) })` |
|
|
197
|
+
| **DTO responses** | Standard API shape via `@xrystal/dto` | Standart API cevabı | `return { data: [], message: '@successfully user' }` |
|
|
198
|
+
| **Trace** | `requestId` per request/job (ALS) | İstek/job trace id | `req.requestId` · `runWithTrace('job-1', fn)` |
|
|
199
|
+
| **i18n** | i18next + 50+ business message keys | Çok dilli mesajlar | `'@successfully user'` · `req.t('responseMessage.successfully')` |
|
|
200
|
+
| **G store** | App-wide state from `tmp.yml` vars | Global state | `G.get('maintenance')` · `checks: () => G.get('x') ? fail : true` |
|
|
201
|
+
| **Logger** | Winston: console + daily rotate files | Dosya + konsol log | `this.logger.log(LoggerLayerEnum.INFO, 'ok')` |
|
|
202
|
+
| **Kafka logs** | Structured logs → Kafka topic | Log → Kafka | `loaders.loggers` + `configs.kafkaLogsTopic` in env |
|
|
203
|
+
| **HTTP client** | Retries + circuit breaker + trace header | Dayanıklı outbound HTTP | extend `BaseApiClient` from loader/clients |
|
|
204
|
+
| **Scope validate** | OAuth-style `resource:permission` check | Scope doğrulama | `validateScopes({ scopes, resources, permissions })` |
|
|
205
|
+
| **Realtime** | Same `ctr()` for ws / socket.io | HTTP + ws aynı kalıp | `ctr({ logic }, { protocol: 'ws' })` — [guide](#realtime--websocket--socketio) |
|
|
206
|
+
| **CLI (`xry`)** | create, tmp, sync, dev, build, start, test, doctor | Servis toolchain | `"dev": "xry dev"` · `"sync": "xry sync"` |
|
|
207
|
+
| **Shutdown** | Graceful cleanup on SIGTERM | Temiz kapanış | auto via `registerGracefulShutdown()` on boot |
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
// EN: minimal kernel boot in ANY entry file · TR: herhangi bir giriş dosyasında
|
|
211
|
+
import coreLoader from '@xrystal/core'
|
|
212
|
+
import { dtoMiddleware, G, runWithTrace } from '@xrystal/core/utils'
|
|
213
|
+
import Controller from '@xrystal/core/loader/controller'
|
|
214
|
+
|
|
215
|
+
await coreLoader({})
|
|
216
|
+
|
|
217
|
+
class HealthController extends Controller {
|
|
218
|
+
check = this.ctr({
|
|
219
|
+
checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
|
|
220
|
+
logic: async ({ req }) => ({
|
|
221
|
+
data: { ok: true, trace: req.requestId },
|
|
222
|
+
message: '@successfully',
|
|
223
|
+
}),
|
|
224
|
+
})
|
|
225
|
+
}
|
|
226
|
+
export const healthCtrl = new HealthController()
|
|
227
|
+
|
|
228
|
+
await runWithTrace('nightly-job', async () => {
|
|
229
|
+
// EN: cron/queue jobs get trace too · TR: cron/queue job'ları da trace alır
|
|
230
|
+
})
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## Framework quickstarts / Framework hızlı başlangıç
|
|
236
|
+
|
|
237
|
+
**EN:** Same kernel — swap only `framework` in `tmp.yml` + middleware line.
|
|
238
|
+
|
|
239
|
+
**TR:** Aynı kernel — sadece `tmp.yml` → `framework` ve middleware satırı değişir.
|
|
240
|
+
|
|
241
|
+
### Elysia (default)
|
|
242
|
+
|
|
243
|
+
```yaml
|
|
244
|
+
# x/tmp.yml
|
|
245
|
+
configs:
|
|
246
|
+
service:
|
|
247
|
+
framework: elysia
|
|
248
|
+
paths: { root: ./x, source: ./source }
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
```typescript
|
|
252
|
+
import { Elysia } from 'elysia'
|
|
253
|
+
import coreLoader from '@xrystal/core'
|
|
254
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
255
|
+
import { userCtrl } from './controllers/user'
|
|
256
|
+
|
|
257
|
+
await coreLoader({})
|
|
258
|
+
new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Express
|
|
262
|
+
|
|
263
|
+
```yaml
|
|
264
|
+
configs:
|
|
265
|
+
service:
|
|
266
|
+
framework: express
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
```typescript
|
|
270
|
+
import express from 'express'
|
|
271
|
+
import coreLoader from '@xrystal/core'
|
|
272
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
273
|
+
import { userCtrl } from './controllers/user'
|
|
274
|
+
|
|
275
|
+
await coreLoader({})
|
|
276
|
+
const app = express()
|
|
277
|
+
app.use(dtoMiddleware('express'))
|
|
278
|
+
app.get('/users', userCtrl.list)
|
|
279
|
+
app.listen(3000)
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Node (raw http)
|
|
283
|
+
|
|
284
|
+
```yaml
|
|
285
|
+
configs:
|
|
286
|
+
service:
|
|
287
|
+
framework: node
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
import http from 'node:http'
|
|
292
|
+
import coreLoader from '@xrystal/core'
|
|
293
|
+
import { userCtrl } from './controllers/user'
|
|
294
|
+
|
|
295
|
+
await coreLoader({})
|
|
296
|
+
http.createServer((req, res) => userCtrl.list(req, res)).listen(3000)
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### Fetch / Bun.serve
|
|
300
|
+
|
|
301
|
+
```yaml
|
|
302
|
+
configs:
|
|
303
|
+
service:
|
|
304
|
+
framework: fetch
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
import coreLoader from '@xrystal/core'
|
|
309
|
+
import { userCtrl } from './controllers/user'
|
|
310
|
+
|
|
311
|
+
await coreLoader({})
|
|
312
|
+
Bun.serve({ fetch: (req) => userCtrl.list(req) })
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
`fetch` — no global middleware; `ctr()` attaches builder per request.
|
|
316
|
+
|
|
317
|
+
**EN:** WebSocket & Socket.IO — full guide at the end: [Realtime](#realtime--websocket--socketio).
|
|
318
|
+
|
|
319
|
+
**TR:** WebSocket & Socket.IO — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
|
|
320
|
+
|
|
321
|
+
| Framework | `tmp.yml` | Middleware |
|
|
322
|
+
|-----------|-----------|------------|
|
|
323
|
+
| elysia | `framework: elysia` | `dtoMiddleware()` |
|
|
324
|
+
| express | `framework: express` | `dtoMiddleware('express')` |
|
|
325
|
+
| node | `framework: node` | `dtoMiddleware('node')` |
|
|
326
|
+
| fetch | `framework: fetch` | — (per-request in `ctr`) |
|
|
140
327
|
|
|
141
328
|
---
|
|
142
329
|
|
|
@@ -144,12 +331,15 @@ bun run dev
|
|
|
144
331
|
|
|
145
332
|
| Topic / Konu | Section / Bölüm |
|
|
146
333
|
|--------------|-----------------|
|
|
334
|
+
| Why kernel vs template | [Why](#why--neden) |
|
|
335
|
+
| All platform capabilities | [Platform features](#platform-features--platform-özellikleri) |
|
|
336
|
+
| Per-framework boot | [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) |
|
|
147
337
|
| Controller, `ctr()` | [Controller](#controller) |
|
|
148
|
-
| Express / Elysia | [Framework](#express--elysia) |
|
|
338
|
+
| Express / Elysia detail | [Framework](#express--elysia) |
|
|
149
339
|
| DI, boot, tmp watch | [DI](#di--tmpyml) |
|
|
150
340
|
| Locale / dil | [i18n](#i18n--locale) |
|
|
151
341
|
| Global state | [G store](#g-store) |
|
|
152
|
-
| WebSocket | [Realtime](#realtime) |
|
|
342
|
+
| WebSocket & Socket.IO | [Realtime](#realtime--websocket--socketio) |
|
|
153
343
|
| API response shape | [DTO](#dto-responses--dto-cevapları) |
|
|
154
344
|
| End-to-end flow | [Usage guide](#usage-guide--kullanım-rehberi) |
|
|
155
345
|
|
|
@@ -190,9 +380,9 @@ app.get('/users', userCtrl.list)
|
|
|
190
380
|
|
|
191
381
|
## Express & Elysia
|
|
192
382
|
|
|
193
|
-
**EN:** `tmp.yml` → `configs.service.framework` picks the HTTP
|
|
383
|
+
**EN:** See [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) for copy-paste per stack. `tmp.yml` → `configs.service.framework` picks the HTTP layer.
|
|
194
384
|
|
|
195
|
-
**TR:** `tmp.yml` → `
|
|
385
|
+
**TR:** Kopyala-yapıştır örnekler için [Framework hızlı başlangıç](#framework-quickstarts--framework-hızlı-başlangıç). `tmp.yml` → `framework` HTTP katmanını seçer.
|
|
196
386
|
|
|
197
387
|
**Express**
|
|
198
388
|
|
|
@@ -238,9 +428,9 @@ new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
|
|
|
238
428
|
| node | `dtoMiddleware('node')` | Raw `createServer` | Ham HTTP |
|
|
239
429
|
| fetch | none | `ctr()` attaches builder per request | Request başına builder |
|
|
240
430
|
|
|
241
|
-
**EN:** Realtime (ws / socket.io) is separate from HTTP
|
|
431
|
+
**EN:** Realtime (ws / socket.io) is separate from HTTP — full guide at the end: [Realtime](#realtime--websocket--socketio).
|
|
242
432
|
|
|
243
|
-
**TR:** Realtime (ws / socket.io) HTTP
|
|
433
|
+
**TR:** Realtime (ws / socket.io) HTTP'den ayrı — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
|
|
244
434
|
|
|
245
435
|
---
|
|
246
436
|
|
|
@@ -334,27 +524,6 @@ checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } :
|
|
|
334
524
|
|
|
335
525
|
---
|
|
336
526
|
|
|
337
|
-
## Realtime
|
|
338
|
-
|
|
339
|
-
**EN:** Not HTTP — use `protocol: 'ws'` or `'socketio'` on `ctr()`. Set `protocols` in `tmp.yml`.
|
|
340
|
-
|
|
341
|
-
**TR:** HTTP değil — `ctr()` üzerinde `protocol: 'ws'` veya `'socketio'`. `tmp.yml` → `protocols`.
|
|
342
|
-
|
|
343
|
-
```typescript
|
|
344
|
-
onMessage = this.ctr({ logic: async () => ({ ok: true }) }, { protocol: 'ws' })
|
|
345
|
-
|
|
346
|
-
wss.on('connection', (socket) => {
|
|
347
|
-
realtimeMiddleware()(socket, () => {})
|
|
348
|
-
socket.on('message', chatCtrl.onMessage.with(socket))
|
|
349
|
-
})
|
|
350
|
-
```
|
|
351
|
-
|
|
352
|
-
```yaml
|
|
353
|
-
protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
---
|
|
357
|
-
|
|
358
527
|
## DTO responses / DTO cevapları
|
|
359
528
|
|
|
360
529
|
**EN:** Standard `{ success, message, data, … }` via `@xrystal/dto`. `dtoMiddleware()` attaches builder; `ctr()` dispatches the result.
|
|
@@ -372,13 +541,14 @@ Details / detay: [`@xrystal/dto`](https://www.npmjs.com/package/@xrystal/dto)
|
|
|
372
541
|
**TR:** Servis yazarken tipik akış.
|
|
373
542
|
|
|
374
543
|
```
|
|
375
|
-
1.
|
|
376
|
-
2.
|
|
377
|
-
3.
|
|
378
|
-
4.
|
|
379
|
-
5.
|
|
380
|
-
6.
|
|
381
|
-
7.
|
|
544
|
+
1. Your repo + bun add @xrystal/core + xry tmp (or xry create for greenfield)
|
|
545
|
+
2. xry sync → tsconfig include / outDir / @/* from tmp.yml
|
|
546
|
+
3. tmp.yml → framework, loaders, paths
|
|
547
|
+
4. coreLoader() → once at top of YOUR index.ts
|
|
548
|
+
5. Controller → ctr() per endpoint
|
|
549
|
+
6. Framework → dtoMiddleware + routes
|
|
550
|
+
7. xry dev → develop
|
|
551
|
+
8. xry build → start → production
|
|
382
552
|
```
|
|
383
553
|
|
|
384
554
|
### Express — end-to-end / uçtan uca
|
|
@@ -454,8 +624,170 @@ class UserController extends Controller {
|
|
|
454
624
|
|
|
455
625
|
---
|
|
456
626
|
|
|
627
|
+
## Realtime — WebSocket & Socket.IO
|
|
628
|
+
|
|
629
|
+
**EN:** HTTP framework (`express`, `elysia`, …) and realtime are **separate axes**. Realtime uses `protocol: 'ws'` or `'socketio'` on `ctr()` — not `framework` in `tmp.yml`. Integration tests cover both pipelines (34 tests pass).
|
|
630
|
+
|
|
631
|
+
**TR:** HTTP framework (`express`, `elysia`, …) ile realtime **ayrı eksenler**. Realtime `ctr()` üzerinde `protocol: 'ws'` veya `'socketio'` kullanır — `tmp.yml`'deki `framework` değil. Her iki pipeline integration test ile doğrulanır (34 test geçer).
|
|
632
|
+
|
|
633
|
+
### HTTP vs realtime / HTTP vs realtime
|
|
634
|
+
|
|
635
|
+
| Axis / Eksen | `tmp.yml` | Middleware | Dispatch |
|
|
636
|
+
|--------------|-----------|------------|----------|
|
|
637
|
+
| **HTTP** | `framework: elysia` | `dtoMiddleware()` | `res.json()` / Elysia set |
|
|
638
|
+
| **WebSocket** | `protocols: [http, ws]` | `realtimeMiddleware()` | `socket.send(JSON)` |
|
|
639
|
+
| **Socket.IO** | `protocols: [http, socketio]` | `realtimeMiddleware('socketio')` | `socket.emit(event, payload)` |
|
|
640
|
+
|
|
641
|
+
**EN:** Same controller class can serve HTTP **and** realtime — different properties, different `protocol` on `ctr()`.
|
|
642
|
+
|
|
643
|
+
**TR:** Aynı controller sınıfı HTTP **ve** realtime verebilir — farklı property, farklı `protocol`.
|
|
644
|
+
|
|
645
|
+
### 3-step pattern / 3 adım kalıbı
|
|
646
|
+
|
|
647
|
+
```
|
|
648
|
+
1. realtimeMiddleware() → socket'a builder tak
|
|
649
|
+
2. ctr({ logic }, { protocol }) → checks + logic + i18n (isteğe bağlı)
|
|
650
|
+
3. dispatch otomatik → ws: send · socketio: emit
|
|
651
|
+
```
|
|
652
|
+
|
|
653
|
+
### `tmp.yml` — `protocols`
|
|
654
|
+
|
|
655
|
+
```yaml
|
|
656
|
+
configs:
|
|
657
|
+
service:
|
|
658
|
+
framework: elysia # EN: HTTP only · TR: sadece HTTP
|
|
659
|
+
protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
| `protocols` in tmp.yml | `realtimeMiddleware()` |
|
|
663
|
+
|------------------------|-------------------------|
|
|
664
|
+
| `[http, ws]` | `realtimeMiddleware()` → auto **ws** |
|
|
665
|
+
| `[http, socketio]` | `realtimeMiddleware()` → auto **socketio** |
|
|
666
|
+
| `[http, ws, socketio]` | **Must specify:** `realtimeMiddleware('ws')` or `realtimeMiddleware('socketio')` |
|
|
667
|
+
|
|
668
|
+
### Native WebSocket (ws)
|
|
669
|
+
|
|
670
|
+
```typescript
|
|
671
|
+
// source/controllers/chat.ts
|
|
672
|
+
import Controller from '@xrystal/core/loader/controller'
|
|
673
|
+
|
|
674
|
+
class ChatController extends Controller {
|
|
675
|
+
onMessage = this.ctr({
|
|
676
|
+
logic: async ({ req }) => ({
|
|
677
|
+
data: { echo: req.body },
|
|
678
|
+
message: '@successfully',
|
|
679
|
+
}),
|
|
680
|
+
}, { protocol: 'ws' })
|
|
681
|
+
}
|
|
682
|
+
export const chatCtrl = new ChatController()
|
|
683
|
+
```
|
|
684
|
+
|
|
685
|
+
```typescript
|
|
686
|
+
// source/index.ts — Express + ws on same port (example)
|
|
687
|
+
import { WebSocketServer } from 'ws'
|
|
688
|
+
import express from 'express'
|
|
689
|
+
import coreLoader from '@xrystal/core'
|
|
690
|
+
import { dtoMiddleware, realtimeMiddleware } from '@xrystal/core/utils'
|
|
691
|
+
import { chatCtrl } from './controllers/chat'
|
|
692
|
+
|
|
693
|
+
await coreLoader({})
|
|
694
|
+
|
|
695
|
+
const app = express()
|
|
696
|
+
app.use(dtoMiddleware('express'))
|
|
697
|
+
|
|
698
|
+
const server = app.listen(3000)
|
|
699
|
+
const wss = new WebSocketServer({ server })
|
|
700
|
+
|
|
701
|
+
wss.on('connection', (socket) => {
|
|
702
|
+
realtimeMiddleware()(socket, () => {}) // 1) builder attach
|
|
703
|
+
socket.on('message', chatCtrl.onMessage.with(socket)) // 2) ctr + 3) auto send
|
|
704
|
+
})
|
|
705
|
+
```
|
|
706
|
+
|
|
707
|
+
**EN:** `with(socket)` binds the socket for that event — core calls `socket.send(JSON)` after `ctr()` finishes.
|
|
708
|
+
|
|
709
|
+
**TR:** `with(socket)` socket'ı o event'e bağlar — `ctr()` bitince core `socket.send(JSON)` çağırır.
|
|
710
|
+
|
|
711
|
+
### Socket.IO
|
|
712
|
+
|
|
713
|
+
```typescript
|
|
714
|
+
class ChatController extends Controller {
|
|
715
|
+
onChat = this.ctr({
|
|
716
|
+
logic: async () => ({ data: { ok: true }, message: '@successfully' }),
|
|
717
|
+
}, { protocol: 'socketio' })
|
|
718
|
+
}
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
```typescript
|
|
722
|
+
import { Server } from 'socket.io'
|
|
723
|
+
import coreLoader from '@xrystal/core'
|
|
724
|
+
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
725
|
+
import { chatCtrl } from './controllers/chat'
|
|
726
|
+
|
|
727
|
+
await coreLoader({})
|
|
728
|
+
|
|
729
|
+
const io = new Server(3001, { cors: { origin: '*' } })
|
|
730
|
+
|
|
731
|
+
io.use((socket, next) => realtimeMiddleware('socketio')(socket, next)) // 1) builder
|
|
732
|
+
io.on('connection', (socket) => {
|
|
733
|
+
socket.on('chat', chatCtrl.onChat.with(socket)) // 2+3) ctr → emit
|
|
734
|
+
})
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
**EN:** Default emit event comes from Dto config (`socket.event`, default `'response'`). Override in `tmp.yml` → `loaders.dto`.
|
|
738
|
+
|
|
739
|
+
**TR:** Varsayılan emit event'i Dto config'den gelir (`socket.event`, default `'response'`). `tmp.yml` → `loaders.dto` ile override.
|
|
740
|
+
|
|
741
|
+
### Without controller / Controller olmadan
|
|
742
|
+
|
|
743
|
+
**EN:** Plain function — use `runAction` when you don't need `checks` / i18n / `this.logger`.
|
|
744
|
+
|
|
745
|
+
**TR:** Düz fonksiyon — `checks` / i18n / `this.logger` gerekmiyorsa `runAction`.
|
|
746
|
+
|
|
747
|
+
```typescript
|
|
748
|
+
import { runAction, getDtoRuntime } from '@xrystal/core/utils'
|
|
749
|
+
|
|
750
|
+
// WebSocket
|
|
751
|
+
socket.on('message', () =>
|
|
752
|
+
runAction({ protocol: 'ws', socket }, async () => {
|
|
753
|
+
return socket.builder.as.ok({ ping: 1 }).build()
|
|
754
|
+
}),
|
|
755
|
+
)
|
|
756
|
+
|
|
757
|
+
// Socket.IO
|
|
758
|
+
socket.on('ping', () =>
|
|
759
|
+
runAction({ protocol: 'socketio', socket }, async () => {
|
|
760
|
+
return getDtoRuntime().forSocket(socket).builder.as.ok({ pong: true }).build()
|
|
761
|
+
}),
|
|
762
|
+
)
|
|
763
|
+
```
|
|
764
|
+
|
|
765
|
+
### ws vs Socket.IO — transport farkı
|
|
766
|
+
|
|
767
|
+
| | WebSocket (ws) | Socket.IO |
|
|
768
|
+
|---|----------------|-----------|
|
|
769
|
+
| Wire / Kablo | `socket.send(JSON string)` | `socket.emit(event, object)` |
|
|
770
|
+
| `ctr()` protocol | `{ protocol: 'ws' }` | `{ protocol: 'socketio' }` |
|
|
771
|
+
| Middleware | `realtimeMiddleware()` or `realtimeMiddleware('ws')` | `realtimeMiddleware('socketio')` |
|
|
772
|
+
| Same `FinalResult` | ✅ same builder | ✅ same builder |
|
|
773
|
+
|
|
774
|
+
**EN:** Pick **ws** for native WebSocket clients. Pick **socket.io** when you need rooms, fallback transport, or existing Socket.IO clients.
|
|
775
|
+
|
|
776
|
+
**TR:** Native WebSocket client → **ws**. Room, fallback transport veya mevcut Socket.IO client → **socket.io**.
|
|
777
|
+
|
|
778
|
+
### Same logic, two protocols / Aynı logic, iki protocol
|
|
779
|
+
|
|
780
|
+
```typescript
|
|
781
|
+
class ChatController extends Controller {
|
|
782
|
+
onWs = this.ctr({ logic: async () => ({ data: { via: 'ws' } }) }, { protocol: 'ws' })
|
|
783
|
+
onSio = this.ctr({ logic: async () => ({ data: { via: 'socketio' } }) }, { protocol: 'socketio' })
|
|
784
|
+
}
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
---
|
|
788
|
+
|
|
457
789
|
## Maintainer note / Geliştirici notu
|
|
458
790
|
|
|
459
|
-
**EN:** This repo is the `@xrystal/core` source.
|
|
791
|
+
**EN:** This repo is the `@xrystal/core` source. Bump `package.json` → commit → `xry tag` (runs prepare + pushes `vX.Y.Z`; GitHub Publish workflow releases to npm). Consumers only need `bun add @xrystal/core`.
|
|
460
792
|
|
|
461
|
-
**TR:** Bu repo `@xrystal/core`
|
|
793
|
+
**TR:** Bu repo `@xrystal/core` kaynağıdır. `package.json` bump → commit → `xry tag` (prepare + `vX.Y.Z` push; GitHub Publish → npm). Tüketici için sadece `bun add @xrystal/core` yeter.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"author": "Yusuf Yasir KAYGUSUZ",
|
|
3
3
|
"name": "@xrystal/core",
|
|
4
|
-
"version": "3.
|
|
4
|
+
"version": "3.40.0",
|
|
5
5
|
"description": "Project core for xrystal",
|
|
6
6
|
"publishConfig": {
|
|
7
7
|
"access": "public",
|
|
@@ -50,9 +50,7 @@
|
|
|
50
50
|
},
|
|
51
51
|
"type": "module",
|
|
52
52
|
"bin": {
|
|
53
|
-
"
|
|
54
|
-
"xrystal": "./x/bin/main-cli.js",
|
|
55
|
-
"tmp": "./x/bin/main-cli.js"
|
|
53
|
+
"xry": "./x/bin/main-cli.js"
|
|
56
54
|
},
|
|
57
55
|
"scripts": {
|
|
58
56
|
"dev": "node x/bin/main-cli.js dev",
|
|
@@ -15,8 +15,9 @@ import {
|
|
|
15
15
|
import { formatLoaderSummary, summarizeLoaders } from '../helpers/tmp-config.mjs'
|
|
16
16
|
import { formatCreateHelp, formatCreateCommandHelp, LIST_BULLET } from '../helpers/cli-help.mjs'
|
|
17
17
|
import { setupProjectGitHooks } from '../scripts/install-git-hooks.mjs'
|
|
18
|
+
import { CLI_PRIMARY_NAME } from '../helpers/cli-identity.mjs'
|
|
18
19
|
|
|
19
|
-
export function registerCreateCommand(cli, { cliName =
|
|
20
|
+
export function registerCreateCommand(cli, { cliName = CLI_PRIMARY_NAME, runtimeName, packageManager, installCommand, devCommand }) {
|
|
20
21
|
cli
|
|
21
22
|
.command('create <project-name> [target-path]')
|
|
22
23
|
.description('Scaffold new service from GitHub template')
|
|
@@ -2,6 +2,7 @@ import chalk from 'chalk'
|
|
|
2
2
|
|
|
3
3
|
import { printCommandHeader } from '../helpers/banner.mjs'
|
|
4
4
|
import { resolveDistLayout } from '../helpers/project-artifacts.mjs'
|
|
5
|
+
import { CLI_PRIMARY_NAME } from '../helpers/cli-identity.mjs'
|
|
5
6
|
import {
|
|
6
7
|
getInstalledCoreVersion,
|
|
7
8
|
getProjectRoot,
|
|
@@ -22,7 +23,7 @@ function printSection(title) {
|
|
|
22
23
|
console.log(chalk.bold.cyan(`\n ${title}`))
|
|
23
24
|
}
|
|
24
25
|
|
|
25
|
-
export function registerDoctorCommand(cli, { cliName =
|
|
26
|
+
export function registerDoctorCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
|
|
26
27
|
cli
|
|
27
28
|
.command('doctor')
|
|
28
29
|
.description('Check runtime, git, and @xrystal/core alignment')
|
|
@@ -75,7 +76,7 @@ export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
|
|
|
75
76
|
console.log(` ${'source'.padEnd(18)}${chalk.bold(distLayout.layout.mainFolderPath)} ${chalk.gray('(paths.source)')}`)
|
|
76
77
|
console.log(` ${'dist'.padEnd(18)}${chalk.bold(distLayout.distPrefix)} ${chalk.gray('(paths.special.dist)')}`)
|
|
77
78
|
} else {
|
|
78
|
-
console.log(chalk.yellow(
|
|
79
|
+
console.log(chalk.yellow(` layout: tmp.yml not resolved — run ${CLI_PRIMARY_NAME} tmp`))
|
|
79
80
|
}
|
|
80
81
|
|
|
81
82
|
printSection('CLI (tool)')
|
|
@@ -134,7 +135,7 @@ export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
|
|
|
134
135
|
}
|
|
135
136
|
console.log(` ${'working tree'.padEnd(18)}${state.isClean ? chalk.green('clean') : chalk.yellow('dirty')}`)
|
|
136
137
|
const hookOk = isGitHookInstalled(root)
|
|
137
|
-
console.log(` ${'pre-commit hook'.padEnd(18)}${hookOk ? chalk.green('installed') : chalk.yellow('missing')} ${chalk.gray(
|
|
138
|
+
console.log(` ${'pre-commit hook'.padEnd(18)}${hookOk ? chalk.green('installed') : chalk.yellow('missing')} ${chalk.gray(`· ${CLI_PRIMARY_NAME} hooks install`)}`)
|
|
138
139
|
} catch (error) {
|
|
139
140
|
console.log(chalk.yellow(` git: ${error.message}`))
|
|
140
141
|
}
|
|
@@ -145,7 +146,7 @@ export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
|
|
|
145
146
|
console.log(` ${'outDir'.padEnd(18)}${chalk.bold(toolchain.outDir)}`)
|
|
146
147
|
const tsAudit = auditTsconfigAlignment(root)
|
|
147
148
|
if (tsAudit.missing) {
|
|
148
|
-
console.log(chalk.yellow(` ${'tsconfig'.padEnd(18)}missing · run
|
|
149
|
+
console.log(chalk.yellow(` ${'tsconfig'.padEnd(18)}missing · run ${CLI_PRIMARY_NAME} sync`))
|
|
149
150
|
} else if (tsAudit.ok) {
|
|
150
151
|
console.log(chalk.green(` ${'tsconfig'.padEnd(18)}aligned with tmp.yml`))
|
|
151
152
|
} else {
|
package/x/bin/commands/hooks.mjs
CHANGED
|
@@ -4,8 +4,9 @@ import { printCommandHeader } from '../helpers/banner.mjs'
|
|
|
4
4
|
import { readCliPackageJson } from '../helpers/project-root.mjs'
|
|
5
5
|
import { installGitHooks, isGitHookInstalled } from '../scripts/install-git-hooks.mjs'
|
|
6
6
|
import { getProjectRoot } from '../helpers/project-root.mjs'
|
|
7
|
+
import { CLI_PRIMARY_NAME } from '../helpers/cli-identity.mjs'
|
|
7
8
|
|
|
8
|
-
export function registerHooksCommand(cli, { cliName =
|
|
9
|
+
export function registerHooksCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
|
|
9
10
|
const hooks = cli
|
|
10
11
|
.command('hooks')
|
|
11
12
|
.description('Install git hooks for version bump checks')
|