@xrystal/core 3.38.2 → 3.39.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 +477 -2071
- package/package.json +3 -3
- package/x/bin/helpers/.generated/tmp-schema.mjs +8 -1
- package/x/bin/helpers/build-config.mjs +1 -0
- package/x/bin/scripts/clean-dist-tests.mjs +50 -0
- package/x/bin/scripts/fix-dist-imports.mjs +7 -2
- package/x/dist/loader/clients/index.js +1 -1
- package/x/dist/loader/configs/index.js +1 -1
- package/x/dist/loader/controller/index.js +1 -1
- package/x/dist/loader/dto/index.js +1 -1
- package/x/dist/loader/events/index.js +1 -1
- package/x/dist/loader/index.js +1 -1
- package/x/dist/loader/kafka/index.js +1 -1
- package/x/dist/loader/localizations/index.js +1 -1
- package/x/dist/loader/logger/index.js +1 -1
- package/x/dist/loader/system/index.js +1 -1
- package/x/dist/project/index.js +1 -1
- package/x/dist/utils/constants/index.js +1 -1
- package/x/dist/utils/helpers/context/index.js +1 -1
- package/x/dist/utils/helpers/core/index.js +1 -1
- package/x/dist/utils/helpers/core/tmp-layout.js +1 -1
- package/x/dist/utils/helpers/date/index.js +1 -1
- package/x/dist/utils/helpers/dispatch/index.js +1 -1
- package/x/dist/utils/helpers/framework/index.js +1 -1
- package/x/dist/utils/helpers/handlers/adapters.js +1 -1
- package/x/dist/utils/helpers/handlers/execute.js +1 -1
- package/x/dist/utils/helpers/handlers/index.js +1 -1
- package/x/dist/utils/helpers/index.js +1 -1
- package/x/dist/utils/helpers/middleware/index.js +1 -1
- package/x/dist/utils/helpers/protocol/index.js +1 -1
- package/x/dist/utils/helpers/protocol/options.js +1 -1
- package/x/dist/utils/helpers/runtime/dto-access.js +1 -1
- package/x/dist/utils/helpers/runtime/index.js +1 -1
- package/x/dist/utils/helpers/runtime/shutdown.js +1 -1
- package/x/dist/utils/helpers/state/index.js +1 -1
- package/x/dist/utils/helpers/state/props-from-tmp.js +1 -1
- package/x/dist/utils/helpers/state/request-key-guard.js +1 -1
- package/x/dist/utils/helpers/state/scopes.js +1 -1
- package/x/dist/utils/helpers/tmp/index.js +1 -1
- package/x/dist/utils/helpers/tmp/loader-tmp-sync.js +1 -1
- package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -1
- package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -1
- package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -1
- package/x/dist/utils/index.js +1 -1
- package/x/dist/utils/models/classes/class.clients.js +1 -1
- package/x/dist/utils/models/classes/class.tmp-file-loader.js +1 -1
- package/x/dist/utils/models/index.js +1 -1
- package/x/dist/utils/helpers/tests/tmp-schema.test.d.ts +0 -1
- package/x/dist/utils/helpers/tests/tmp-schema.test.js +0 -1
- package/x/dist/utils/helpers/tests/tmp-watch.test.d.ts +0 -1
- package/x/dist/utils/helpers/tests/tmp-watch.test.js +0 -1
package/README.md
CHANGED
|
@@ -1,2356 +1,762 @@
|
|
|
1
|
-
# xrystal
|
|
1
|
+
# @xrystal/core
|
|
2
2
|
|
|
3
|
-
> **EN** —
|
|
4
|
-
> **TR** —
|
|
3
|
+
> **EN** — Microservice runtime: Express or Elysia HTTP, DI loaders, live `tmp.yml`, standardized API responses.
|
|
4
|
+
> **TR** — Microservice runtime: Express veya Elysia HTTP, DI loader'lar, canlı `tmp.yml`, standart API cevapları.
|
|
5
5
|
|
|
6
|
-
**
|
|
6
|
+
**CLI:** `xcore` · `xrystal` · `tmp` (same binary / aynı binary)
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Why / Neden
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|---|--------|--------|
|
|
14
|
-
| **Ships** | `x/dist` (minified `.js` + `.d.ts`), `x/bin`, `x/tmp.yml`, `x/assets` | Aynı — yalnızca bunlar |
|
|
15
|
-
| **Never** | `source/` `.ts` in npm | npm'e `source/` `.ts` **asla** gitmez |
|
|
16
|
-
| **Runtime** | `main` / `exports` → `x/dist/` | `main` / `exports` → `x/dist/` |
|
|
12
|
+
**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 `xcore create` if you want a starter; otherwise add the package to **your** project and seed `x/tmp.yml`.
|
|
17
13
|
|
|
18
|
-
**
|
|
19
|
-
1. `package.json` `files` — no `source/`, `main`/`exports` → `x/dist`
|
|
20
|
-
2. `npm pack --dry-run` — no `source/` paths
|
|
21
|
-
3. CI: `prepare-npm-publish` → `verify-npm-pack` (strict: disk + minify)
|
|
22
|
-
|
|
23
|
-
**TR — 3 publish kontrolü (hepsi geçmeli):**
|
|
24
|
-
1. `package.json` `files` — `source/` yok, `main`/`exports` → `x/dist`
|
|
25
|
-
2. `npm pack --dry-run` — `source/` yok
|
|
26
|
-
3. CI: `prepare-npm-publish` → `verify-npm-pack` (strict: disk + minify)
|
|
14
|
+
**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 `xcore create`; mevcut projende sadece paketi kur + `xcore tmp` yeter.
|
|
27
15
|
|
|
28
16
|
```bash
|
|
29
|
-
|
|
30
|
-
|
|
17
|
+
# EN: existing project — kernel only · TR: mevcut proje — sadece kernel
|
|
18
|
+
bun add @xrystal/core
|
|
19
|
+
npx xcore tmp # seed x/tmp.yml into YOUR layout
|
|
20
|
+
# wire coreLoader + dtoMiddleware in your entry file
|
|
31
21
|
```
|
|
32
22
|
|
|
33
23
|
---
|
|
34
24
|
|
|
35
|
-
##
|
|
36
|
-
|
|
37
|
-
**EN — structure:** `service` (app identity, paths, runtime, build) + `core` (library mechanisms like tmp watch).
|
|
38
|
-
|
|
39
|
-
**TR — yapı:** `service` (uygulama kimliği, yollar, runtime, build) + `core` (tmp izleme gibi kütüphane mekanizmaları).
|
|
40
|
-
|
|
41
|
-
```yaml
|
|
42
|
-
project:
|
|
43
|
-
name: x
|
|
44
|
-
|
|
45
|
-
configs:
|
|
46
|
-
service:
|
|
47
|
-
name: my-api
|
|
48
|
-
framework: elysia
|
|
49
|
-
protocols: [http, ws]
|
|
50
|
-
|
|
51
|
-
paths:
|
|
52
|
-
root: x # EN: CLI root (test/dev/build) · TR: test/dev/build kökü
|
|
53
|
-
source: ./source # EN: source tree + dev entry · TR: kaynak + dev girişi
|
|
54
|
-
special:
|
|
55
|
-
tests: tests
|
|
56
|
-
environments: environments
|
|
57
|
-
dist: dist
|
|
25
|
+
## Quick start / Hızlı başlangıç
|
|
58
26
|
|
|
59
|
-
|
|
60
|
-
dto: { withDefaultHeaders: true }
|
|
61
|
-
loggers: { logLevel: info }
|
|
62
|
-
controller: {}
|
|
27
|
+
### Path A — `create` (starter template / başlangıç şablonu)
|
|
63
28
|
|
|
64
|
-
|
|
65
|
-
typecheck: true # EN: build override · TR: build override
|
|
66
|
-
minify: true # EN: @xrystal/core — minify x/dist JS · TR: x/dist JS küçültme
|
|
29
|
+
**EN:** Optional — clone GitHub template when you have no project yet.
|
|
67
30
|
|
|
68
|
-
|
|
69
|
-
tmp:
|
|
70
|
-
fileWatchIntervalMs: 500
|
|
31
|
+
**TR:** İsteğe bağlı — henüz proje yoksa GitHub template klonla.
|
|
71
32
|
|
|
72
|
-
|
|
73
|
-
|
|
33
|
+
```bash
|
|
34
|
+
mkdir my-api && cd my-api
|
|
35
|
+
bun init -y
|
|
36
|
+
bun add @xrystal/core
|
|
37
|
+
npx xcore create my-api .
|
|
74
38
|
```
|
|
75
39
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
| `configs.core.tmp` | `fileWatchIntervalMs` | tmp.yml dosya izleme (ms) |
|
|
81
|
-
|
|
82
|
-
**EN:** Save `tmp.yml` → no restart; loaders reload automatically.
|
|
83
|
-
**TR:** Kaydet → restart gerekmez; loader’lar otomatik yenilenir.
|
|
84
|
-
|
|
85
|
-
---
|
|
86
|
-
|
|
87
|
-
## How it works / Sistem nasıl çalışır
|
|
88
|
-
|
|
89
|
-
### EN — overview
|
|
90
|
-
|
|
91
|
-
In one sentence: **`tmp.yml` is the project key** — `@xrystal/core` reads it, boots loaders, and sends responses via `@xrystal/dto`.
|
|
92
|
-
|
|
93
|
-
| Layer | Module | Role |
|
|
94
|
-
|--------|--------|------|
|
|
95
|
-
| Defaults | `defaults.json` | `x`, `./source`, `tests`, template URI |
|
|
96
|
-
| Constants | `Constants` | Shared TS + CLI values |
|
|
97
|
-
| Layout | `tmp-layout.ts` | tmp path resolution — **CLI only** |
|
|
98
|
-
| Live config | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols |
|
|
99
|
-
| Runtime | `getTmpSnapshot()` | Parse + watch + live reload |
|
|
100
|
-
|
|
101
|
-
**Core repo:** `tmp.yml` must live at `x/tmp.yml` only (`ensureCoreTmpEntry`).
|
|
102
|
-
**Service:** tmp under `configs.service.paths.root`; runtime uses `getTmpSnapshot()` — no layout module needed.
|
|
103
|
-
|
|
104
|
-
**Boot:** `ensureCoreTmpEntry()` → `getTmpSnapshot()` → `coreLoader()` → loaders `syncFromTmp()`.
|
|
105
|
-
|
|
106
|
-
See [npm publish / npm yayın](#npm-publish--npm-yayın) for what ships to npm.
|
|
107
|
-
|
|
108
|
-
---
|
|
109
|
-
|
|
110
|
-
### TR — genel bakış
|
|
111
|
-
|
|
112
|
-
Tek cümle: **`tmp.yml` projenin anahtarı** — `@xrystal/core` onu okuyup loader’ları ayağa kaldırır; cevaplar `@xrystal/dto` ile gider.
|
|
113
|
-
|
|
114
|
-
| Katman | Modül | Rol |
|
|
115
|
-
|--------|--------|-----|
|
|
116
|
-
| Varsayılanlar | `defaults.json` | `x`, `./source`, `tests`, template URI |
|
|
117
|
-
| Sabitler | `Constants` | TS + CLI ortak değerler |
|
|
118
|
-
| Layout | `tmp-layout.ts` | tmp yolu — **sadece CLI** |
|
|
119
|
-
| Canlı config | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols |
|
|
120
|
-
| Runtime | `getTmpSnapshot()` | Parse + watch + canlı güncelleme |
|
|
121
|
-
|
|
122
|
-
**Core repo:** `tmp.yml` yalnızca `x/tmp.yml` (`ensureCoreTmpEntry`).
|
|
123
|
-
**Servis:** tmp `configs.service.paths.root` altında; runtime’da `getTmpSnapshot()` yeterli — layout modülü gerekmez.
|
|
124
|
-
|
|
125
|
-
**Boot:** `ensureCoreTmpEntry()` → `getTmpSnapshot()` → `coreLoader()` → loader’lar `syncFromTmp()`.
|
|
126
|
-
|
|
127
|
-
npm için → [npm publish / npm yayın](#npm-publish--npm-yayın).
|
|
128
|
-
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
## How it works — detail / Sistem nasıl çalışır — detay
|
|
132
|
-
|
|
133
|
-
**EN:** Deep-dive below (mermaid + tables). Turkish prose in this section; key labels are bilingual where it matters.
|
|
134
|
-
|
|
135
|
-
**TR:** Aşağıda detay (mermaid + tablolar). Türkçe anlatım; kritik etiketler iki dilli.
|
|
136
|
-
|
|
137
|
-
```mermaid
|
|
138
|
-
flowchart TB
|
|
139
|
-
subgraph config["Yapılandırma"]
|
|
140
|
-
DEF["defaults.json\n(paket varsayılanları)"]
|
|
141
|
-
CONST["Constants\n(TS sabitleri)"]
|
|
142
|
-
TMP["x/tmp.yml\n(canlı proje ayarı)"]
|
|
143
|
-
DEF --> CONST
|
|
144
|
-
CONST --> TMP
|
|
145
|
-
end
|
|
146
|
-
|
|
147
|
-
subgraph boot["Boot"]
|
|
148
|
-
ENTRY["dev: source/index.ts · prod: x/dist/index.js"]
|
|
149
|
-
GUARD["ensureCoreTmpEntry\n(sadece @xrystal/core)"]
|
|
150
|
-
SNAP["getTmpSnapshot()"]
|
|
151
|
-
LOADER["coreLoader() → Awilix DI"]
|
|
152
|
-
ENTRY --> GUARD
|
|
153
|
-
GUARD --> SNAP
|
|
154
|
-
SNAP --> LOADER
|
|
155
|
-
end
|
|
156
|
-
|
|
157
|
-
subgraph runtime["Runtime"]
|
|
158
|
-
SYS["System.applyTmp()"]
|
|
159
|
-
G["G store"]
|
|
160
|
-
L["Logger · Dto · i18n · Controller …"]
|
|
161
|
-
TMP --> SNAP
|
|
162
|
-
LOADER --> L
|
|
163
|
-
TMP -. watch .-> SYS
|
|
164
|
-
SYS --> G
|
|
165
|
-
SYS --> L
|
|
166
|
-
end
|
|
40
|
+
```bash
|
|
41
|
+
bun add elysia # EN: or express · TR: veya express
|
|
42
|
+
bun run dev
|
|
43
|
+
npx xcore doctor # EN: setup check · TR: kurulum kontrolü
|
|
167
44
|
```
|
|
168
45
|
|
|
169
|
-
|
|
170
|
-
|--------|----------------|----------|
|
|
171
|
-
| **Varsayılan değerler** | `source/utils/constants/defaults.json` | `x`, `./source`, `tests`, template URI — tek JSON kaynağı |
|
|
172
|
-
| **TS sabitleri** | `Constants` (`@/utils/constants`) | CLI + runtime aynı değerleri okur |
|
|
173
|
-
| **Layout çözümleme** | `tmp-layout.ts` | `tmp.yml` nerede, `tests/dist/env` yolları — CLI ve ensure için |
|
|
174
|
-
| **Canlı config** | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols — **runtime tek kaynak** |
|
|
175
|
-
| **Runtime okuma** | `TmpFileLoader` / `getTmpSnapshot()` | Serviste dosyayı bir kez okur, watch ile canlı günceller |
|
|
176
|
-
|
|
177
|
-
### Core kütüphane vs servis
|
|
178
|
-
|
|
179
|
-
| | **@xrystal/core repo** | **Microservice** |
|
|
180
|
-
|---|------------------------|------------------|
|
|
181
|
-
| `tmp.yml` konumu | **Zorunlu** `x/tmp.yml` — başka yerde kopya varsa hata | `configs.service.paths.root` altında (ör. `x/`, `infra/`) |
|
|
182
|
-
| Koruma | `ensureCoreTmpEntry()` — stray tmp engeli | Yok; `tmp.yml` recursive bulunur |
|
|
183
|
-
| Boot | `ensureCoreTmpEntry` → `getTmpSnapshot` → `coreLoader` | `coreLoader({})` + kendi HTTP sunucun |
|
|
184
|
-
| Layout runtime’da | Gerekmez — değerler tmp snapshot’tan | Gerekmez — aynı |
|
|
185
|
-
|
|
186
|
-
Servis runtime’ında `tmp-layout` çalıştırmana gerek yok: `getTmpSnapshot()` / `getRuntimeTmpConfigs()` yeterli.
|
|
187
|
-
|
|
188
|
-
**EN:** Layout module is for CLI only (`xcore dev`, `xcore tmp`, `xcore test`, `xcore build`).
|
|
189
|
-
|
|
190
|
-
**TR:** Layout modülü yalnızca CLI içindir (`xcore dev`, `xcore tmp`, `xcore test`, `xcore build`).
|
|
191
|
-
|
|
192
|
-
### Proje layout’u (`x/`)
|
|
193
|
-
|
|
194
|
-
```
|
|
195
|
-
{project-root}/ # EN: repo root · TR: proje kökü
|
|
196
|
-
├── package.json
|
|
197
|
-
└── {rootFolderPath}/ # default: x — EN: CLI root (test/dev/build) · TR: CLI kökü
|
|
198
|
-
├── tmp.yml # EN: main config entry · TR: ana giriş
|
|
199
|
-
├── tests/
|
|
200
|
-
├── environments/ # EN: .env files (xcore dev) · TR: .env (xcore dev)
|
|
201
|
-
└── dist/ # EN: build output (.js) · TR: build çıktısı (.js)
|
|
202
|
-
```
|
|
46
|
+
### Path B — Your project + kernel (most common / en yaygın)
|
|
203
47
|
|
|
204
|
-
|
|
48
|
+
**EN:** Keep your folder names — only add `tmp.yml`, `coreLoader`, controllers.
|
|
205
49
|
|
|
206
|
-
|
|
207
|
-
configs:
|
|
208
|
-
file:
|
|
209
|
-
rootFolderPath: x
|
|
210
|
-
configFileWatchIntervalMs: 500
|
|
50
|
+
**TR:** Kendi klasör adların kalsın — sadece `tmp.yml`, `coreLoader`, controller ekle.
|
|
211
51
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
paths:
|
|
218
|
-
tests: tests
|
|
219
|
-
environments: environments
|
|
220
|
-
dist: dist
|
|
221
|
-
build:
|
|
222
|
-
typecheck: true # tmp override — outDir/include tsconfig.json'dan
|
|
223
|
-
loaders:
|
|
224
|
-
dto: { withDefaultHeaders: true }
|
|
225
|
-
controller: {}
|
|
52
|
+
```bash
|
|
53
|
+
mkdir my-api && cd my-api
|
|
54
|
+
bun init -y
|
|
55
|
+
bun add @xrystal/core elysia
|
|
56
|
+
npx xcore tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa seed'den oluşturur
|
|
226
57
|
```
|
|
227
58
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
| Ayar | 1. tmp.yml `build.*` | 2. `tsconfig.json` | 3. fallback |
|
|
231
|
-
|------|----------------------|--------------------|-------------|
|
|
232
|
-
| Çıktı klasörü (`outDir`) | `build.outDir` | `compilerOptions.outDir` | `paths.dist` + `rootFolderPath` |
|
|
233
|
-
| Giriş dosyaları (glob) | `build.entries` / `build.glob` | `include` / `rootDir` | `service.paths.source` |
|
|
234
|
-
| Sourcemap | `build.sourcemap` | `sourceMap` / `inlineSourceMap` | kapalı |
|
|
235
|
-
| `.d.ts` | `build.declarations` | `declaration` / full `tsc` | kapalı |
|
|
236
|
-
| Minify (core) | `build.minify` | — | kapalı |
|
|
237
|
-
| Tip kontrolü | `build.typecheck` | — | `false` |
|
|
238
|
-
|
|
239
|
-
Servis örnek `tsconfig.json`:
|
|
59
|
+
`package.json`:
|
|
240
60
|
|
|
241
61
|
```json
|
|
242
62
|
{
|
|
243
|
-
"
|
|
244
|
-
|
|
245
|
-
"
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
"
|
|
249
|
-
"
|
|
250
|
-
"
|
|
63
|
+
"dependencies": {
|
|
64
|
+
"@xrystal/core": "^3.38.2",
|
|
65
|
+
"elysia": "^1.4.19"
|
|
66
|
+
},
|
|
67
|
+
"scripts": {
|
|
68
|
+
"dev": "xcore dev",
|
|
69
|
+
"build": "xcore build",
|
|
70
|
+
"start": "xcore start",
|
|
71
|
+
"test": "xcore test",
|
|
72
|
+
"doctor": "xcore doctor"
|
|
251
73
|
}
|
|
252
74
|
}
|
|
253
75
|
```
|
|
254
76
|
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
`tmp.yml` yoksa:
|
|
258
|
-
|
|
259
|
-
**EN:** `xcore tmp` or `xcore dev` copies seed from `@xrystal/core/x/tmp.yml`.
|
|
260
|
-
|
|
261
|
-
**TR:** `xcore tmp` veya `xcore dev` → seed `@xrystal/core/x/tmp.yml` kopyalanır.
|
|
262
|
-
|
|
263
|
-
### Boot sırası (lib)
|
|
77
|
+
**EN:** No global `xcore` install — runs via `node_modules/.bin` after `bun add @xrystal/core`.
|
|
264
78
|
|
|
265
|
-
|
|
266
|
-
2. `getTmpSnapshot()` — yaml parse, ilk snapshot
|
|
267
|
-
3. `coreLoader()` — Awilix: System → Configs → Kafka → Logger → … → Controller
|
|
268
|
-
4. Her loader `onInit`: `syncFromTmp()` + `bindLoaderTmpSync()` (dosya değişince otomatik)
|
|
79
|
+
**TR:** Global `xcore` gerekmez — `@xrystal/core` kurulunca `node_modules/.bin` üzerinden çalışır.
|
|
269
80
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
### CLI vs runtime / CLI ve runtime
|
|
273
|
-
|
|
274
|
-
| Tool / Araç | EN | TR |
|
|
275
|
-
|---------------|----|----|
|
|
276
|
-
| `xcore` / `xrystal` / `tmp` | Same binary — dev, test, build, doctor, tag, tmp ensure, create | Aynı binary — dev, test, build, doctor, tag, tmp ensure, create |
|
|
277
|
-
| `getTmpSnapshot()` | In-app config | Uygulama içi config |
|
|
278
|
-
| `dtoMiddleware()` + `ctr()` | HTTP handler pipeline | HTTP handler pipeline |
|
|
279
|
-
| `realtimeMiddleware()` + `runAction()` | WebSocket / Socket.IO | WebSocket / Socket.IO |
|
|
280
|
-
|
|
281
|
-
---
|
|
282
|
-
|
|
283
|
-
## 5 dakikada çalışan microservice
|
|
284
|
-
|
|
285
|
-
Tek repo, tek `tmp.yml`, tek boot — Elysia HTTP örneği:
|
|
81
|
+
### Project layout / Proje düzeni
|
|
286
82
|
|
|
287
83
|
```
|
|
288
84
|
my-api/
|
|
289
|
-
├──
|
|
290
|
-
|
|
291
|
-
│ ├──
|
|
292
|
-
│ └──
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
│ └── controllers/user.ts
|
|
296
|
-
└── package.json
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
**1) Kur**
|
|
300
|
-
|
|
301
|
-
```bash
|
|
302
|
-
npm i @xrystal/core elysia
|
|
85
|
+
├── package.json
|
|
86
|
+
├── source/
|
|
87
|
+
│ ├── index.ts # EN: dev entry (xcore dev) · TR: dev girişi
|
|
88
|
+
│ └── controllers/
|
|
89
|
+
└── x/
|
|
90
|
+
├── tmp.yml # EN: single config source · TR: tek diğerleri
|
|
303
91
|
```
|
|
304
92
|
|
|
305
|
-
|
|
93
|
+
### Minimal `x/tmp.yml`
|
|
306
94
|
|
|
307
95
|
```yaml
|
|
308
96
|
configs:
|
|
309
|
-
file:
|
|
310
|
-
rootFolderPath: x
|
|
311
|
-
|
|
312
97
|
service:
|
|
313
98
|
name: my-api
|
|
314
|
-
framework: elysia
|
|
315
|
-
|
|
99
|
+
framework: elysia # express | elysia | node | fetch
|
|
100
|
+
paths:
|
|
101
|
+
root: ./x
|
|
102
|
+
source: ./source
|
|
316
103
|
protocols: [http]
|
|
317
104
|
loaders:
|
|
318
|
-
system:
|
|
319
|
-
gStore:
|
|
320
|
-
options: { bootstrap: true, autoCreateProps: false }
|
|
321
|
-
vars: { maintenance: false }
|
|
322
105
|
dto: { withDefaultHeaders: true }
|
|
323
106
|
loggers: { logLevel: info }
|
|
324
107
|
controller: {}
|
|
325
108
|
```
|
|
326
109
|
|
|
327
|
-
|
|
110
|
+
### First endpoint / İlk endpoint (~5 min)
|
|
328
111
|
|
|
329
112
|
```typescript
|
|
330
|
-
//
|
|
113
|
+
// source/controllers/user.ts
|
|
331
114
|
import Controller from '@xrystal/core/loader/controller'
|
|
332
115
|
|
|
333
116
|
class UserController extends Controller {
|
|
334
117
|
list = this.ctr({
|
|
335
|
-
logic: async () => ({ data: [{ id: 1
|
|
118
|
+
logic: async () => ({ data: [{ id: 1 }], message: '@successfully user' }),
|
|
336
119
|
})
|
|
337
120
|
}
|
|
338
|
-
|
|
339
121
|
export const userCtrl = new UserController()
|
|
340
122
|
```
|
|
341
123
|
|
|
342
|
-
**4) Boot + route**
|
|
343
|
-
|
|
344
124
|
```typescript
|
|
345
|
-
//
|
|
125
|
+
// source/index.ts
|
|
346
126
|
import { Elysia } from 'elysia'
|
|
347
|
-
import coreLoader from '@xrystal/core
|
|
127
|
+
import coreLoader from '@xrystal/core'
|
|
348
128
|
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
349
129
|
import { userCtrl } from './controllers/user'
|
|
350
130
|
|
|
351
131
|
await coreLoader({})
|
|
352
|
-
new Elysia()
|
|
353
|
-
.use(dtoMiddleware())
|
|
354
|
-
.get('/users', userCtrl.list)
|
|
355
|
-
.listen(3000)
|
|
132
|
+
new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
|
|
356
133
|
```
|
|
357
134
|
|
|
358
|
-
**5) Çalıştır**
|
|
359
|
-
|
|
360
135
|
```bash
|
|
361
|
-
|
|
362
|
-
bun run dev # "dev": "xcore dev"
|
|
363
|
-
|
|
364
|
-
# veya doğrudan
|
|
365
|
-
bun src/boot.ts
|
|
366
|
-
xcore doctor # servis + @xrystal/core uyumu
|
|
136
|
+
bun run dev
|
|
367
137
|
# GET http://localhost:3000/users
|
|
368
138
|
```
|
|
369
139
|
|
|
370
|
-
Servis `package.json` örneği:
|
|
371
|
-
|
|
372
|
-
```json
|
|
373
|
-
{
|
|
374
|
-
"dependencies": { "@xrystal/core": "^3.32.2", "elysia": "^1.4.19" },
|
|
375
|
-
"scripts": {
|
|
376
|
-
"dev": "xcore dev",
|
|
377
|
-
"build": "xcore build",
|
|
378
|
-
"start:dist": "xcore start",
|
|
379
|
-
"test": "xcore test",
|
|
380
|
-
"lint": "eslint .",
|
|
381
|
-
"sync-toolchain": "xcore sync-toolchain",
|
|
382
|
-
"doctor": "xcore doctor",
|
|
383
|
-
"version:check": "xcore version",
|
|
384
|
-
"release:tag": "xcore tag",
|
|
385
|
-
"hooks:install": "xcore hooks install"
|
|
386
|
-
}
|
|
387
|
-
}
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
**İlk kurulum / klasör adı değişince (manuel, bir kez):**
|
|
391
|
-
|
|
392
|
-
```bash
|
|
393
|
-
bun run sync-toolchain # tmp.yml → tsconfig paths; eslint tmp'den okur
|
|
394
|
-
bun run doctor # drift kontrolü
|
|
395
|
-
# sync çıktısındaki satırı bunfig.toml [resolve.alias]'a ekle
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
Detay: [Servislerde `sync-toolchain`](#servislerde-sync-toolchain-manuel)
|
|
399
|
-
|
|
400
|
-
Public API:
|
|
401
|
-
|
|
402
|
-
```typescript
|
|
403
|
-
import { dtoMiddleware, G, runWithTrace, getRuntimeTmpConfigs } from '@xrystal/core/utils'
|
|
404
|
-
import { System, DtoRuntime, Controller } from '@xrystal/core/loader'
|
|
405
|
-
import coreLoader from '@xrystal/core/project'
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
`tmp.yml` kaydedilince loader'lar otomatik `syncFromTmp()` — restart gerekmez.
|
|
409
|
-
|
|
410
140
|
---
|
|
411
141
|
|
|
412
|
-
##
|
|
142
|
+
## Daily commands / Günlük komutlar
|
|
413
143
|
|
|
414
|
-
|
|
144
|
+
| Command / Komut | EN | TR |
|
|
145
|
+
|-----------------|----|----|
|
|
146
|
+
| `xcore create [name] [path]` | Start project from template + `tmp.yml` | Template + `tmp.yml` ile proje başlat |
|
|
147
|
+
| `xcore tmp` | Create `tmp.yml` from seed if missing | `tmp.yml` yoksa seed'den oluştur |
|
|
148
|
+
| `xcore dev` | Watch `source/index.ts` + dev env | `source/index.ts` watch + dev env |
|
|
149
|
+
| `xcore build` | Output → `x/dist` | Çıktı → `x/dist` |
|
|
150
|
+
| `xcore start` | Run `x/dist` + prod env | `x/dist` + prod env |
|
|
151
|
+
| `xcore test` | Run `x/tests` | `x/tests` çalıştır |
|
|
152
|
+
| `xcore doctor` | CLI, runtime, package health | CLI, runtime, paket uyumu |
|
|
415
153
|
|
|
416
|
-
|
|
417
|
-
configs:
|
|
418
|
-
file:
|
|
419
|
-
rootFolderPath: x
|
|
420
|
-
configFileWatchIntervalMs: 500
|
|
154
|
+
---
|
|
421
155
|
|
|
422
|
-
|
|
423
|
-
name: my-api
|
|
424
|
-
framework: elysia # elysia | express | node | fetch
|
|
425
|
-
folderPath: ./src
|
|
426
|
-
protocols: [http, ws] # http, ws, socketio
|
|
427
|
-
loaders:
|
|
428
|
-
system:
|
|
429
|
-
gStore:
|
|
430
|
-
options:
|
|
431
|
-
bootstrap: true
|
|
432
|
-
autoCreateProps: false
|
|
433
|
-
vars:
|
|
434
|
-
maintenance: false
|
|
435
|
-
dto: { withDefaultHeaders: true }
|
|
436
|
-
localization: { fallbackLang: en, preloadLangs: [en, tr] }
|
|
437
|
-
loggers: { logLevel: debug }
|
|
438
|
-
controller: {}
|
|
439
|
-
```
|
|
156
|
+
## Platform features / Platform özellikleri
|
|
440
157
|
|
|
441
|
-
|
|
158
|
+
**EN:** What the kernel gives you — one line each + minimal example.
|
|
442
159
|
|
|
443
|
-
|
|
160
|
+
**TR:** Kernel'in verdiği yetenekler — tek satır + kısa örnek.
|
|
444
161
|
|
|
445
|
-
|
|
162
|
+
| Feature / Özellik | EN | TR | Example / Örnek |
|
|
163
|
+
|-------------------|----|----|-----------------|
|
|
164
|
+
| **Boot / DI** | Awilix loaders: System, Logger, Kafka, Dto, i18n, … | Awilix loader'lar | `await coreLoader({})` |
|
|
165
|
+
| **Live `tmp.yml`** | Edit file → loaders re-sync without restart | Dosya değişince loader sync | `logLevel: debug` → save → logger updates |
|
|
166
|
+
| **`ctr()` pipeline** | `checks → logic → response`, no `res.json()` | Endpoint pipeline | `list = this.ctr({ logic: async () => ({ data: [] }) })` |
|
|
167
|
+
| **DTO responses** | Standard API shape via `@xrystal/dto` | Standart API cevabı | `return { data: [], message: '@successfully user' }` |
|
|
168
|
+
| **Trace** | `requestId` per request/job (ALS) | İstek/job trace id | `req.requestId` · `runWithTrace('job-1', fn)` |
|
|
169
|
+
| **i18n** | i18next + 50+ business message keys | Çok dilli mesajlar | `'@successfully user'` · `req.t('responseMessage.successfully')` |
|
|
170
|
+
| **G store** | App-wide state from `tmp.yml` vars | Global state | `G.get('maintenance')` · `checks: () => G.get('x') ? fail : true` |
|
|
171
|
+
| **Logger** | Winston: console + daily rotate files | Dosya + konsol log | `this.logger.log(LoggerLayerEnum.INFO, 'ok')` |
|
|
172
|
+
| **Kafka logs** | Structured logs → Kafka topic | Log → Kafka | `loaders.loggers` + `configs.kafkaLogsTopic` in env |
|
|
173
|
+
| **HTTP client** | Retries + circuit breaker + trace header | Dayanıklı outbound HTTP | extend `BaseApiClient` from loader/clients |
|
|
174
|
+
| **Scope validate** | OAuth-style `resource:permission` check | Scope doğrulama | `validateScopes({ scopes, resources, permissions })` |
|
|
175
|
+
| **Realtime** | Same `ctr()` for ws / socket.io | HTTP + ws aynı kalıp | `ctr({ logic }, { protocol: 'ws' })` — [guide](#realtime--websocket--socketio) |
|
|
176
|
+
| **CLI** | dev, build, start, test, doctor, tmp | Servis toolchain | `"dev": "xcore dev"` in your `package.json` |
|
|
177
|
+
| **Shutdown** | Graceful cleanup on SIGTERM | Temiz kapanış | auto via `registerGracefulShutdown()` on boot |
|
|
446
178
|
|
|
447
179
|
```typescript
|
|
180
|
+
// EN: minimal kernel boot in ANY entry file · TR: herhangi bir giriş dosyasında
|
|
181
|
+
import coreLoader from '@xrystal/core'
|
|
182
|
+
import { dtoMiddleware, G, runWithTrace } from '@xrystal/core/utils'
|
|
448
183
|
import Controller from '@xrystal/core/loader/controller'
|
|
449
184
|
|
|
450
|
-
|
|
451
|
-
list = this.ctr({
|
|
452
|
-
logic: async ({ req }) => ({ data: [], message: '@successfully user' }),
|
|
453
|
-
})
|
|
185
|
+
await coreLoader({})
|
|
454
186
|
|
|
455
|
-
|
|
456
|
-
|
|
187
|
+
class HealthController extends Controller {
|
|
188
|
+
check = this.ctr({
|
|
189
|
+
checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
|
|
190
|
+
logic: async ({ req }) => ({
|
|
191
|
+
data: { ok: true, trace: req.requestId },
|
|
192
|
+
message: '@successfully',
|
|
193
|
+
}),
|
|
457
194
|
})
|
|
458
195
|
}
|
|
196
|
+
export const healthCtrl = new HealthController()
|
|
459
197
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
---
|
|
464
|
-
|
|
465
|
-
### 3) Elysia (default HTTP)
|
|
466
|
-
|
|
467
|
-
```typescript
|
|
468
|
-
import { Elysia } from 'elysia'
|
|
469
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
470
|
-
import { userCtrl } from './controllers/user'
|
|
471
|
-
|
|
472
|
-
new Elysia()
|
|
473
|
-
.use(dtoMiddleware())
|
|
474
|
-
.get('/users', userCtrl.list)
|
|
475
|
-
.post('/users', userCtrl.create)
|
|
476
|
-
.listen(3000)
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
---
|
|
480
|
-
|
|
481
|
-
### 4) Express
|
|
482
|
-
|
|
483
|
-
```typescript
|
|
484
|
-
import express from 'express'
|
|
485
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
486
|
-
import { userCtrl } from './controllers/user'
|
|
487
|
-
|
|
488
|
-
const app = express()
|
|
489
|
-
app.use(dtoMiddleware('express'))
|
|
490
|
-
app.get('/users', userCtrl.list)
|
|
491
|
-
app.post('/users', userCtrl.create)
|
|
492
|
-
app.listen(3000)
|
|
493
|
-
```
|
|
494
|
-
|
|
495
|
-
---
|
|
496
|
-
|
|
497
|
-
### 5) Fetch / Bun.serve
|
|
498
|
-
|
|
499
|
-
`tmp.yml` → `framework: fetch`
|
|
500
|
-
|
|
501
|
-
```typescript
|
|
502
|
-
import { userCtrl } from './controllers/user'
|
|
503
|
-
|
|
504
|
-
Bun.serve({
|
|
505
|
-
port: 3000,
|
|
506
|
-
fetch: (req) => userCtrl.list(req),
|
|
507
|
-
})
|
|
508
|
-
```
|
|
509
|
-
|
|
510
|
-
---
|
|
511
|
-
|
|
512
|
-
### 6) WebSocket — same controller, different protocol
|
|
513
|
-
|
|
514
|
-
```typescript
|
|
515
|
-
import { WebSocketServer } from 'ws'
|
|
516
|
-
import Controller from '@xrystal/core/loader/controller'
|
|
517
|
-
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
518
|
-
|
|
519
|
-
class ChatController extends Controller {
|
|
520
|
-
onMessage = this.ctr({
|
|
521
|
-
logic: async ({ req }) => ({ data: { text: req.body } }),
|
|
522
|
-
}, { protocol: 'ws' })
|
|
523
|
-
}
|
|
524
|
-
|
|
525
|
-
const chatCtrl = new ChatController()
|
|
526
|
-
const wss = new WebSocketServer({ port: 3001 })
|
|
527
|
-
|
|
528
|
-
wss.on('connection', (socket) => {
|
|
529
|
-
realtimeMiddleware('ws')(socket, () => {})
|
|
530
|
-
socket.on('message', chatCtrl.onMessage.with(socket))
|
|
531
|
-
})
|
|
532
|
-
```
|
|
533
|
-
|
|
534
|
-
---
|
|
535
|
-
|
|
536
|
-
### 7) Socket.IO
|
|
537
|
-
|
|
538
|
-
```typescript
|
|
539
|
-
import { Server } from 'socket.io'
|
|
540
|
-
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
541
|
-
|
|
542
|
-
io.use(realtimeMiddleware('socketio'))
|
|
543
|
-
io.on('connection', (socket) => {
|
|
544
|
-
socket.on('chat', chatCtrl.onChat.with(socket)) // protocol: 'socketio' on ctr
|
|
545
|
-
})
|
|
546
|
-
```
|
|
547
|
-
|
|
548
|
-
---
|
|
549
|
-
|
|
550
|
-
### 8) No controller — `runAction`
|
|
551
|
-
|
|
552
|
-
```typescript
|
|
553
|
-
import { realtimeMiddleware, runAction } from '@xrystal/core/utils'
|
|
554
|
-
|
|
555
|
-
socket.on('message', async () => {
|
|
556
|
-
await runAction({ protocol: 'ws', socket }, async () =>
|
|
557
|
-
socket.builder.as.ok({ pong: true }).build(),
|
|
558
|
-
)
|
|
559
|
-
})
|
|
560
|
-
```
|
|
561
|
-
|
|
562
|
-
---
|
|
563
|
-
|
|
564
|
-
### 9) G store (process-wide, Zustand)
|
|
565
|
-
|
|
566
|
-
```typescript
|
|
567
|
-
import { G, GStoreScopeEnum, LoggerLayerEnum } from '@xrystal/core/utils'
|
|
568
|
-
|
|
569
|
-
G.get('maintenance', false)
|
|
570
|
-
G.set('maintenance', true) // only keys declared in tmp vars (when autoCreateProps: false)
|
|
571
|
-
|
|
572
|
-
G.subscribeKey('maintenance', (value, prev) => {
|
|
573
|
-
logger.log(LoggerLayerEnum.INFO, 'maintenance', { value, prev })
|
|
198
|
+
await runWithTrace('nightly-job', async () => {
|
|
199
|
+
// EN: cron/queue jobs get trace too · TR: cron/queue job'ları da trace alır
|
|
574
200
|
})
|
|
575
|
-
|
|
576
|
-
G.scope(GStoreScopeEnum.GLOBAL).set?.('flag', 1)
|
|
577
|
-
G.scope(GStoreScopeEnum.RUN).get('requestId') // inside request / job
|
|
578
|
-
G.scope(GStoreScopeEnum.CONTROLLER).patch?.({ metadata: { locals: { userId: 1 } } })
|
|
579
|
-
```
|
|
580
|
-
|
|
581
|
-
Controller check example:
|
|
582
|
-
|
|
583
|
-
```typescript
|
|
584
|
-
checks: () => G.get('maintenance', false) ? { message: '@unsuccessful maintenance' } : true
|
|
585
|
-
```
|
|
586
|
-
|
|
587
|
-
---
|
|
588
|
-
|
|
589
|
-
### 10) Trace / cron (no HTTP protocol)
|
|
590
|
-
|
|
591
|
-
```typescript
|
|
592
|
-
import { runWithTrace, LoggerLayerEnum } from '@xrystal/core/utils'
|
|
593
|
-
|
|
594
|
-
await runWithTrace('nightly-sync', async () => {
|
|
595
|
-
logger.log(LoggerLayerEnum.INFO, 'started')
|
|
596
|
-
}, 'sync-job')
|
|
597
|
-
```
|
|
598
|
-
|
|
599
|
-
---
|
|
600
|
-
|
|
601
|
-
### 11) DI boot + tmp reload (internal flow)
|
|
602
|
-
|
|
603
|
-
```typescript
|
|
604
|
-
// source/project/index.ts — Awilix order matters
|
|
605
|
-
await x.initialize([
|
|
606
|
-
{ service: System, props: { core } },
|
|
607
|
-
{ service: Configs },
|
|
608
|
-
{ service: KafkaForCore },
|
|
609
|
-
{ service: Logger },
|
|
610
|
-
// Events, Localizations, Dto, Controller, Clients …
|
|
611
|
-
])
|
|
612
|
-
|
|
613
|
-
// Each loader onInit:
|
|
614
|
-
await this.syncFromTmp()
|
|
615
|
-
bindLoaderTmpSync(this)
|
|
616
|
-
```
|
|
617
|
-
|
|
618
|
-
Public imports — always from utils barrel:
|
|
619
|
-
|
|
620
|
-
```typescript
|
|
621
|
-
import {
|
|
622
|
-
bindLoaderTmpSync,
|
|
623
|
-
dtoMiddleware,
|
|
624
|
-
G,
|
|
625
|
-
GStoreScopeEnum,
|
|
626
|
-
getRuntimeTmpConfigs,
|
|
627
|
-
getConfiguredProtocols,
|
|
628
|
-
realtimeMiddleware,
|
|
629
|
-
runAction,
|
|
630
|
-
runWithTrace,
|
|
631
|
-
type ITmpSyncLoader,
|
|
632
|
-
} from '@xrystal/core/utils'
|
|
633
201
|
```
|
|
634
202
|
|
|
635
|
-
More walkthrough: [Kullanım örnekleri](#kullanım-örnekleri-sıralı--kopyala-yapıştır) · Realtime: [Realtime rehberi](#realtime-rehberi--ws-vs-socketio-kafanda-otursun) · Architecture: [DI + tmp.yml](#di--tmpyml--boot-ve-canlı-güncelleme)
|
|
636
|
-
|
|
637
203
|
---
|
|
638
204
|
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
Two independent axes:
|
|
642
|
-
|
|
643
|
-
| Axis | Values | Source | Used when |
|
|
644
|
-
|------|--------|--------|-----------|
|
|
645
|
-
| **framework** | elysia, express, node, fetch | `tmp.yml` → `dtoMiddleware()` | HTTP only |
|
|
646
|
-
| **protocol** | http, ws, socketio | `ctr(..., { protocol })`, `runAction()`, `realtimeMiddleware()` | Every action |
|
|
647
|
-
|
|
648
|
-
Three stores (do not mix):
|
|
649
|
-
|
|
650
|
-
| Store | API | Lifetime |
|
|
651
|
-
|-------|-----|----------|
|
|
652
|
-
| Run context | `getRequestId`, `runWithTrace` | Per request / job |
|
|
653
|
-
| Controller context | `this.req`, `builder` | Per request |
|
|
654
|
-
| **G** | `G`, `system.g` | Process-wide — [Zustand](https://zustand.docs.pmnd.rs/) |
|
|
205
|
+
## Framework quickstarts / Framework hızlı başlangıç
|
|
655
206
|
|
|
656
|
-
|
|
207
|
+
**EN:** Same kernel — swap only `framework` in `tmp.yml` + middleware line.
|
|
657
208
|
|
|
658
|
-
|
|
209
|
+
**TR:** Aynı kernel — sadece `tmp.yml` → `framework` ve middleware satırı değişir.
|
|
659
210
|
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
| Eksen | Değerler | Kaynak | Ne zaman |
|
|
663
|
-
|-------|----------|--------|----------|
|
|
664
|
-
| **framework** | elysia, express, node, fetch | `tmp.yml` → `dtoMiddleware()` | Sadece HTTP |
|
|
665
|
-
| **protocol** | http, ws, socketio | `ctr(..., { protocol })`, `runAction()`, `realtimeMiddleware()` | Her action |
|
|
666
|
-
|
|
667
|
-
Üç depo (birbirinin yerine geçmez):
|
|
668
|
-
|
|
669
|
-
| Depo | API | Ömür |
|
|
670
|
-
|------|-----|------|
|
|
671
|
-
| Run context | `getRequestId`, `runWithTrace` | İstek / job başına |
|
|
672
|
-
| Controller context | `this.req`, `builder` | İstek başına |
|
|
673
|
-
| **G** | `G`, `system.g` | Process geneli — [Zustand](https://zustand.docs.pmnd.rs/) |
|
|
674
|
-
|
|
675
|
-
Hızlı kalıp: bir kez `dtoMiddleware()` → route'a `userCtrl.list` → `ctr()` handler döner → `dispatchResult()` dto sink ile gönderir.
|
|
676
|
-
|
|
677
|
-
---
|
|
678
|
-
|
|
679
|
-
## Supported frameworks
|
|
680
|
-
|
|
681
|
-
Set **one** HTTP default in `tmp.yml` — it drives `dtoMiddleware()` and `ctr()` for **HTTP only**.
|
|
682
|
-
|
|
683
|
-
| `tmp.yml` value | Layer | Middleware | Notes |
|
|
684
|
-
|---|---|---|---|
|
|
685
|
-
| **`elysia`** | HTTP stack (default) | `runtime.elysia()` | `.use(dtoMiddleware())` |
|
|
686
|
-
| **`express`** | HTTP stack | `runtime.express()` | `app.use(dtoMiddleware('express'))` |
|
|
687
|
-
| **`node`** | HTTP stack | `runtime.node()` | Raw `createServer` |
|
|
688
|
-
| **`fetch`** | HTTP stack | none (per-request) | `forRequest(req)` inside `ctr()` |
|
|
689
|
-
| **`websocket`** | Realtime attach | `runtime.websocket()` | Use with `toWebSocket()` — **not** HTTP framework |
|
|
690
|
-
| **`socketio`** | Realtime attach | `runtime.socketIo()` | Use with `toSocketIo()` — **not** HTTP framework |
|
|
691
|
-
|
|
692
|
-
### HTTP framework vs realtime protocol
|
|
693
|
-
|
|
694
|
-
| Eksen | Ne? | Nereden? | Dispatch |
|
|
695
|
-
|-------|-----|----------|----------|
|
|
696
|
-
| **framework** | HTTP mimarisi (elysia, express, node, fetch) | `tmp.yml` → `dtoMiddleware()` | Sadece `protocol: http` |
|
|
697
|
-
| **protocol** | Transport (http, ws, socketio) | `ctr(..., { protocol })` veya `runAction()` | `dispatchResult` önce buna bakar |
|
|
698
|
-
|
|
699
|
-
`tmp.yml` → `configs.protocols` = uygulamanın **desteklediği** protokoller (`getConfiguredProtocols()` / controller `onInit`):
|
|
700
|
-
|
|
701
|
-
```yaml
|
|
702
|
-
configs:
|
|
703
|
-
framework: elysia
|
|
704
|
-
protocols:
|
|
705
|
-
- http
|
|
706
|
-
- ws
|
|
707
|
-
loaders:
|
|
708
|
-
dto: { withDefaultHeaders: true }
|
|
709
|
-
localization: { fallbackLang: en, preloadLangs: [en, tr] }
|
|
710
|
-
controller: {}
|
|
711
|
-
```
|
|
712
|
-
|
|
713
|
-
Action başına protocol — controller bağımsızlığı:
|
|
714
|
-
|
|
715
|
-
```typescript
|
|
716
|
-
list = this.ctr({ logic: async ({ req }) => ({ data: [] }) })
|
|
717
|
-
|
|
718
|
-
onMessage = this.ctr({ logic: async () => ({ ok: true }) }, { protocol: 'ws' })
|
|
719
|
-
|
|
720
|
-
onChat = this.ctr({ logic: async () => ({ ok: true }) }, { protocol: 'socketio' })
|
|
721
|
-
```
|
|
722
|
-
|
|
723
|
-
**Realtime wiring (middleware + ctr):**
|
|
724
|
-
|
|
725
|
-
```typescript
|
|
726
|
-
wss.on('connection', (socket) => {
|
|
727
|
-
realtimeMiddleware()(socket, () => {})
|
|
728
|
-
socket.on('message', chatCtrl.onMessage.with(socket))
|
|
729
|
-
})
|
|
730
|
-
|
|
731
|
-
io.use(realtimeMiddleware('socketio'))
|
|
732
|
-
io.on('connection', (socket) => {
|
|
733
|
-
socket.on('chat', chatCtrl.onChat.with(socket))
|
|
734
|
-
})
|
|
735
|
-
```
|
|
736
|
-
|
|
737
|
-
**Controller olmadan saf fonksiyon:**
|
|
738
|
-
|
|
739
|
-
```typescript
|
|
740
|
-
await runAction({ protocol: 'ws', socket }, async () => {
|
|
741
|
-
return socket.builder.as.ok({ ping: 1 }).build()
|
|
742
|
-
})
|
|
743
|
-
```
|
|
744
|
-
|
|
745
|
-
`withProtocol(() => { ... }, 'ws')` — zaten açık context varsa protocol tag'ler (iç içe logic).
|
|
746
|
-
|
|
747
|
-
Override per app without editing `tmp.yml`:
|
|
748
|
-
|
|
749
|
-
```typescript
|
|
750
|
-
app.use(dtoMiddleware('elysia'))
|
|
751
|
-
app.use(dtoMiddleware({ framework: 'socketio' }))
|
|
752
|
-
```
|
|
753
|
-
|
|
754
|
-
`@xrystal/dto` v26.6.28+ does **not** pick framework — core maps config → the correct adapter (`socketio` → `socketIo()`, not `websocket()`).
|
|
755
|
-
|
|
756
|
-
---
|
|
757
|
-
|
|
758
|
-
## Realtime rehberi — WS vs Socket.IO (kafanda otursun)
|
|
759
|
-
|
|
760
|
-
HTTP ile realtime **aynı şey değil**. Realtime'da `framework` (elysia/express) **devreye girmez**. Sadece **protocol** (`ws` veya `socketio`) önemli.
|
|
761
|
-
|
|
762
|
-
### Tek kalıp — her realtime event için 3 adım
|
|
763
|
-
|
|
764
|
-
```
|
|
765
|
-
1. realtimeMiddleware() → socket.builder tak (tmp.yml veya explicit protocol)
|
|
766
|
-
2. logic çalış → ctr VEYA runAction
|
|
767
|
-
3. dispatch otomatik → send() veya emit()
|
|
768
|
-
```
|
|
769
|
-
|
|
770
|
-
**Protocol nereden gelir?**
|
|
771
|
-
|
|
772
|
-
| tmp.yml `protocols` | `realtimeMiddleware()` |
|
|
773
|
-
|---------------------|-------------------------|
|
|
774
|
-
| `[http, ws]` | Otomatik **ws** (default) |
|
|
775
|
-
| `[http, socketio]` | Otomatik **socketio** |
|
|
776
|
-
| `[http, ws, socketio]` | **Arg zorunlu:** `realtimeMiddleware('ws')` veya `realtimeMiddleware('socketio')` |
|
|
777
|
-
| Override | `realtimeMiddleware('socketio')` — açıkça belirt |
|
|
778
|
-
|
|
779
|
-
```yaml
|
|
780
|
-
configs:
|
|
781
|
-
protocols:
|
|
782
|
-
- http
|
|
783
|
-
- ws
|
|
784
|
-
```
|
|
785
|
-
|
|
786
|
-
### WS mi Socket.IO mu?
|
|
787
|
-
|
|
788
|
-
| | **Native WebSocket (`ws`)** | **Socket.IO (`socketio`)** |
|
|
789
|
-
|--|--|--|
|
|
790
|
-
| Client tarafı | `WebSocket`, `ws` kütüphanesi | `socket.io-client` |
|
|
791
|
-
| Cevap gider | `socket.send(JSON string)` | `socket.emit('response', object)` |
|
|
792
|
-
| Middleware | `realtimeMiddleware()` veya `'ws'` | `realtimeMiddleware('socketio')` |
|
|
793
|
-
| ctr protocol | `{ protocol: 'ws' }` | `{ protocol: 'socketio' }` |
|
|
794
|
-
| tmp.yml | `protocols: [http, ws]` | `protocols: [http, ws, socketio]` |
|
|
795
|
-
|
|
796
|
-
Aynı `FinalResult` (.build()) — sadece **taşıma** farklı.
|
|
797
|
-
|
|
798
|
-
### Yol A — Controller + ctr (checks, i18n, schema)
|
|
799
|
-
|
|
800
|
-
Logic karmaşıksa bunu kullan. HTTP'deki `ctr()` ile **aynı API**, sadece `{ protocol }` eklersin.
|
|
801
|
-
|
|
802
|
-
```typescript
|
|
803
|
-
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
804
|
-
|
|
805
|
-
class ChatController extends Controller {
|
|
806
|
-
list = this.ctr({
|
|
807
|
-
logic: async ({ req }) => ({ data: [] }),
|
|
808
|
-
})
|
|
809
|
-
|
|
810
|
-
onMessage = this.ctr({
|
|
811
|
-
logic: async ({ req }) => ({ data: { text: req.body } }),
|
|
812
|
-
}, { protocol: 'ws' })
|
|
813
|
-
|
|
814
|
-
onChat = this.ctr({
|
|
815
|
-
logic: async () => ({ data: { room: 'lobby' } }),
|
|
816
|
-
}, { protocol: 'socketio' })
|
|
817
|
-
}
|
|
818
|
-
|
|
819
|
-
const chatCtrl = new ChatController()
|
|
820
|
-
```
|
|
821
|
-
|
|
822
|
-
**Bağlama (Native WS — `ws` paketi):**
|
|
823
|
-
|
|
824
|
-
```typescript
|
|
825
|
-
import { WebSocketServer } from 'ws'
|
|
826
|
-
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
827
|
-
|
|
828
|
-
const wss = new WebSocketServer({ port: 3001 })
|
|
829
|
-
|
|
830
|
-
wss.on('connection', (socket) => {
|
|
831
|
-
realtimeMiddleware()(socket as any, () => {})
|
|
832
|
-
|
|
833
|
-
socket.on('message', chatCtrl.onMessage.with(socket))
|
|
834
|
-
})
|
|
835
|
-
```
|
|
836
|
-
|
|
837
|
-
**Bağlama (Socket.IO):**
|
|
838
|
-
|
|
839
|
-
```typescript
|
|
840
|
-
import { Server } from 'socket.io'
|
|
841
|
-
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
842
|
-
|
|
843
|
-
const io = new Server(3002)
|
|
844
|
-
|
|
845
|
-
io.use(realtimeMiddleware('socketio'))
|
|
846
|
-
|
|
847
|
-
io.on('connection', (socket) => {
|
|
848
|
-
socket.on('chat', chatCtrl.onChat.with(socket))
|
|
849
|
-
})
|
|
850
|
-
```
|
|
851
|
-
|
|
852
|
-
**`.with(socket)` neden?** Event handler (`socket.on('message', fn)`) her mesajda socket vermez — socket bağlantıda sabit. `.with(socket)` socket'i logic'e bağlar. Bağlantı anında tek seferlik: `chatCtrl.onMessage(socket)` de olur.
|
|
853
|
-
|
|
854
|
-
### Yol B — Controller yok (runAction)
|
|
855
|
-
|
|
856
|
-
Basit ping/pong, tek satır logic — class açma.
|
|
857
|
-
|
|
858
|
-
```typescript
|
|
859
|
-
import { realtimeMiddleware, runAction } from '@xrystal/core/utils'
|
|
860
|
-
|
|
861
|
-
wss.on('connection', (socket) => {
|
|
862
|
-
realtimeMiddleware()(socket, () => {})
|
|
863
|
-
|
|
864
|
-
socket.on('message', async () => {
|
|
865
|
-
await runAction({ protocol: 'ws', socket }, async () =>
|
|
866
|
-
socket.builder.as.ok({ pong: true }, 'pong').build(),
|
|
867
|
-
)
|
|
868
|
-
})
|
|
869
|
-
})
|
|
870
|
-
|
|
871
|
-
io.on('connection', (socket) => {
|
|
872
|
-
socket.on('ping', async () => {
|
|
873
|
-
await runAction({ protocol: 'socketio', socket }, async () =>
|
|
874
|
-
socket.builder.as.ok({ pong: true }).build(),
|
|
875
|
-
)
|
|
876
|
-
})
|
|
877
|
-
})
|
|
878
|
-
```
|
|
879
|
-
|
|
880
|
-
### Ne zaman hangisi?
|
|
881
|
-
|
|
882
|
-
| Durum | Kullan |
|
|
883
|
-
|-------|--------|
|
|
884
|
-
| checks, i18n, `@successfully`, logger | **ctr + protocol** |
|
|
885
|
-
| Tek satır ping, cron benzeri basit cevap | **runAction** |
|
|
886
|
-
| HTTP endpoint | **ctr** (protocol default http) |
|
|
887
|
-
|
|
888
|
-
### Genişletme (yeni protocol)
|
|
889
|
-
|
|
890
|
-
Yeni transport eklemek için 3 nokta:
|
|
891
|
-
|
|
892
|
-
1. `ProtocolEnum` + `parseProtocol('yeni')`
|
|
893
|
-
2. `dispatchResult` → yeni sink
|
|
894
|
-
3. `realtimeMiddleware('yeni')` veya `runAction({ protocol: 'yeni' })`
|
|
895
|
-
|
|
896
|
-
Controller/ctr API **değişmez** — sadece protocol enum genişler.
|
|
897
|
-
|
|
898
|
-
### Canlı testler
|
|
899
|
-
|
|
900
|
-
README tarifleri test olarak koşulur:
|
|
901
|
-
|
|
902
|
-
```bash
|
|
903
|
-
bun test x/tests/realtime.examples.test.ts
|
|
904
|
-
```
|
|
905
|
-
|
|
906
|
-
Tarif 1–6: ws/socketio × ctr/runAction × gerçek Controller.
|
|
907
|
-
|
|
908
|
-
---
|
|
909
|
-
|
|
910
|
-
## Quick start — ne yapman yeterli?
|
|
911
|
-
|
|
912
|
-
Her framework için aynı kalıp: **controller yaz → middleware tak → route/socket bağla**. Controller içinde `res.send()` yok; `ctr()` + `logic` yeter.
|
|
913
|
-
|
|
914
|
-
### Ortak (hepsi)
|
|
915
|
-
|
|
916
|
-
1. `tmp.yml` → `configs.framework: elysia` (default — express/node/fetch override edilebilir)
|
|
917
|
-
2. Controller:
|
|
918
|
-
|
|
919
|
-
```typescript
|
|
920
|
-
class UserController extends Controller {
|
|
921
|
-
list = this.ctr({
|
|
922
|
-
logic: async ({ req }) => ({ data: [] }),
|
|
923
|
-
})
|
|
924
|
-
}
|
|
925
|
-
const userCtrl = new UserController()
|
|
926
|
-
```
|
|
927
|
-
|
|
928
|
-
3. Mesaj (i18n): `return '@successfully user'` — `req.t` ile çevrilir
|
|
929
|
-
|
|
930
|
-
---
|
|
931
|
-
|
|
932
|
-
### Elysia (default)
|
|
933
|
-
|
|
934
|
-
1. `tmp.yml` → `framework: elysia` (veya hiç yazma — default elysia)
|
|
935
|
-
2. `new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list)`
|
|
936
|
-
|
|
937
|
-
### Express
|
|
938
|
-
|
|
939
|
-
1. `app.use(dtoMiddleware('express'))`
|
|
940
|
-
2. `app.get('/users', userCtrl.list)`
|
|
941
|
-
|
|
942
|
-
### Fetch / Bun.serve
|
|
943
|
-
|
|
944
|
-
1. `tmp.yml` → `framework: fetch`
|
|
945
|
-
2. Middleware yok — direkt: `fetch: (req) => userCtrl.list(req)`
|
|
946
|
-
|
|
947
|
-
### Node http
|
|
948
|
-
|
|
949
|
-
1. `tmp.yml` → `framework: node`
|
|
950
|
-
2. `createServer((req, res) => userCtrl.list(req, res))`
|
|
951
|
-
|
|
952
|
-
### WebSocket & Socket.IO
|
|
953
|
-
|
|
954
|
-
Realtime için ayrı bölüm: **[Realtime rehberi](#realtime-rehberi--ws-vs-socketio-kafanda-otursun)** (ctr'li / ctr'siz, ws vs socketio).
|
|
955
|
-
|
|
956
|
-
Kısa özet:
|
|
957
|
-
|
|
958
|
-
1. `realtimeMiddleware()` — tmp.yml tek realtime ise otomatik (default **ws**); ws + socketio birlikte ise middleware'de explicit belirt
|
|
959
|
-
2. `ctr({ logic }, { protocol: 'ws' })` veya `runAction({ protocol, socket }, fn)`
|
|
960
|
-
3. `socket.on('event', handler.with(socket))`
|
|
961
|
-
|
|
962
|
-
### i18n (dil)
|
|
963
|
-
|
|
964
|
-
1. i18next middleware’i **dtoMiddleware’den önce** tak (Express örneği):
|
|
965
|
-
|
|
966
|
-
```typescript
|
|
967
|
-
app.use(i18nextMiddleware.handle(i18n))
|
|
968
|
-
app.use(dtoMiddleware())
|
|
969
|
-
```
|
|
970
|
-
|
|
971
|
-
2. Locale dosyaları: `locales/en/translation.json` → `responseMessage.successfully`
|
|
972
|
-
3. Controller’da: `'@successfully user'` veya logic içinde `req.t('responseMessage.successfully')`
|
|
973
|
-
4. Client `Accept-Language: tr` gönderir → Türkçe mesaj döner
|
|
974
|
-
|
|
975
|
-
---
|
|
976
|
-
|
|
977
|
-
## What is `userCtrl.list`?
|
|
978
|
-
|
|
979
|
-
`list` is **not** a core keyword — it is **your action name** (you could call it `getUsers`, `index`, `findAll`, anything).
|
|
980
|
-
|
|
981
|
-
```typescript
|
|
982
|
-
const userCtrl = new UserController()
|
|
983
|
-
|
|
984
|
-
class UserController extends Controller {
|
|
985
|
-
list = this.ctr({
|
|
986
|
-
logic: async ({ req }) => ({ data: [] }),
|
|
987
|
-
})
|
|
988
|
-
|
|
989
|
-
create = this.ctr({
|
|
990
|
-
logic: async ({ req }) => ({ data: req.body }),
|
|
991
|
-
})
|
|
992
|
-
}
|
|
993
|
-
```
|
|
994
|
-
|
|
995
|
-
`this.ctr({ ... })` registers a **controller action** and returns a framework handler (Express or Elysia).
|
|
996
|
-
So `userCtrl.list` is that function — pass it when wiring URLs:
|
|
997
|
-
|
|
998
|
-
```typescript
|
|
999
|
-
app.use(dtoMiddleware())
|
|
1000
|
-
app.get('/users', userCtrl.list)
|
|
1001
|
-
app.post('/users', userCtrl.create)
|
|
1002
|
-
```
|
|
1003
|
-
|
|
1004
|
-
```
|
|
1005
|
-
URL path Controller action What runs
|
|
1006
|
-
──────── ───────────────── ───────────
|
|
1007
|
-
GET /users → userCtrl.list → ctr() → schema() → logic → dispatch
|
|
1008
|
-
POST /users → userCtrl.create → ctr() → schema() → logic → dispatch
|
|
1009
|
-
```
|
|
1010
|
-
|
|
1011
|
-
You never call `userCtrl.list()` yourself in app setup — Express/Elysia calls it when a request hits that path.
|
|
1012
|
-
|
|
1013
|
-
---
|
|
1014
|
-
|
|
1015
|
-
## Config
|
|
1016
|
-
|
|
1017
|
-
`x/tmp.yml`:
|
|
1018
|
-
|
|
1019
|
-
```yaml
|
|
1020
|
-
configs:
|
|
1021
|
-
framework: elysia
|
|
1022
|
-
service: my-api
|
|
1023
|
-
|
|
1024
|
-
protocols:
|
|
1025
|
-
- http
|
|
1026
|
-
- ws
|
|
1027
|
-
|
|
1028
|
-
loaders:
|
|
1029
|
-
dto:
|
|
1030
|
-
withDefaultHeaders: true
|
|
1031
|
-
loggers:
|
|
1032
|
-
loadPath: logs
|
|
1033
|
-
logLevel: debug
|
|
1034
|
-
localization:
|
|
1035
|
-
loadPath: assets/langs
|
|
1036
|
-
fallbackLang: en
|
|
1037
|
-
preloadLangs: [en, tr]
|
|
1038
|
-
controller: {}
|
|
1039
|
-
```
|
|
1040
|
-
|
|
1041
|
-
| Alan | Ne işe yarar |
|
|
1042
|
-
|------|----------------|
|
|
1043
|
-
| `framework` | HTTP stack default (elysia) |
|
|
1044
|
-
| `protocols` | App allowlist — hangi transport'lara izin var |
|
|
1045
|
-
| `loaders.*` | dto, i18n, logger, configs bootstrap |
|
|
1046
|
-
|
|
1047
|
-
`framework` is the single default for the whole app when you write `dtoMiddleware()` and `this.ctr({ ... })` without a second argument. You can omit it only if you pass framework explicitly everywhere (not recommended).
|
|
1048
|
-
|
|
1049
|
-
---
|
|
1050
|
-
|
|
1051
|
-
## Who does what
|
|
1052
|
-
|
|
1053
|
-
| Responsibility | Package |
|
|
1054
|
-
|---|---|
|
|
1055
|
-
| Adapter middleware — attach `builder` + send sink | **`@xrystal/dto`** |
|
|
1056
|
-
| `schema()`, i18n, business logic | **core / controller** |
|
|
1057
|
-
| `dispatchResult()` — per-framework send | **core / dispatch** |
|
|
1058
|
-
| `dtoMiddleware()`, `runController`, trace id | **core / handlers** |
|
|
1059
|
-
|
|
1060
|
-
Core never calls `res.json()` directly. Controller returns `FinalResult` via `.build()`; core dispatches through dto send sinks.
|
|
1061
|
-
|
|
1062
|
-
```
|
|
1063
|
-
dtoMiddleware() → expressSink(res) attached to res.builder
|
|
1064
|
-
ctr() / toHandler → runController + trace id
|
|
1065
|
-
schema() → builder.as.ok(...).build() ← schema only
|
|
1066
|
-
dispatchResult() → expressSink(res).dispatch() ← send HERE
|
|
1067
|
-
```
|
|
1068
|
-
|
|
1069
|
-
---
|
|
1070
|
-
|
|
1071
|
-
## Controller
|
|
1072
|
-
|
|
1073
|
-
Extend `Controller`, define **one property per endpoint** with `ctr()`:
|
|
1074
|
-
|
|
1075
|
-
```typescript
|
|
1076
|
-
import Controller from '@xrystal/core/loader/controller'
|
|
1077
|
-
import { LoggerLayerEnum } from '@xrystal/core/utils'
|
|
1078
|
-
|
|
1079
|
-
class UserController extends Controller {
|
|
1080
|
-
list = this.ctr({
|
|
1081
|
-
logic: async ({ req }) => {
|
|
1082
|
-
this.logger.log(LoggerLayerEnum.INFO, 'listing users')
|
|
1083
|
-
return { data: [] }
|
|
1084
|
-
},
|
|
1085
|
-
})
|
|
1086
|
-
}
|
|
1087
|
-
|
|
1088
|
-
const userCtrl = new UserController()
|
|
1089
|
-
```
|
|
1090
|
-
|
|
1091
|
-
Wire URLs to those properties:
|
|
1092
|
-
|
|
1093
|
-
```typescript
|
|
1094
|
-
app.use(dtoMiddleware())
|
|
1095
|
-
app.get('/users', userCtrl.list)
|
|
1096
|
-
```
|
|
1097
|
-
|
|
1098
|
-
`ctr()` = `schema()` + trace context + framework handler + dispatch. You do not write `toHandler` yourself.
|
|
1099
|
-
|
|
1100
|
-
### `schema()` pipeline (internal — called by `ctr()`)
|
|
1101
|
-
|
|
1102
|
-
1. **checks** — return `true` or a failure object
|
|
1103
|
-
2. **logic** — main work
|
|
1104
|
-
3. **response** — optional transform
|
|
1105
|
-
|
|
1106
|
-
Responses go through `builder.as.ok()` / `.fail()` then `.build()`. Messages support i18n:
|
|
1107
|
-
|
|
1108
|
-
```typescript
|
|
1109
|
-
return '@successfully user'
|
|
1110
|
-
return '@unsuccessful auth'
|
|
1111
|
-
```
|
|
1112
|
-
|
|
1113
|
-
### Why not embed everything in `schema()` alone?
|
|
1114
|
-
|
|
1115
|
-
`schema()` needs `req`, `res`, `builder` from the current HTTP request. Those only exist after the framework calls your route handler. Flow:
|
|
1116
|
-
|
|
1117
|
-
```
|
|
1118
|
-
Express calls userCtrl.list(req, res)
|
|
1119
|
-
→ runController stores req/res in context
|
|
1120
|
-
→ schema() reads context, returns builder.as.ok(...).build()
|
|
1121
|
-
→ dispatchResult() → expressSink(res).dispatch()
|
|
1122
|
-
```
|
|
1123
|
-
|
|
1124
|
-
`schema()` cannot run before Express gives you `req`/`res`. `ctr()` is the thin glue — one line per action.
|
|
1125
|
-
|
|
1126
|
-
### Where does the HTTP response go? (Express)
|
|
1127
|
-
|
|
1128
|
-
You never call `res.send()` in controller code. Chain:
|
|
1129
|
-
|
|
1130
|
-
```
|
|
1131
|
-
schema()
|
|
1132
|
-
→ builder.as.ok(data, message).build()
|
|
1133
|
-
dispatchResult()
|
|
1134
|
-
→ expressSink(res).dispatch(result)
|
|
1135
|
-
→ res.status(code).json(result.body)
|
|
1136
|
-
```
|
|
1137
|
-
|
|
1138
|
-
Middleware attaches sink to builder at request start. Sink runs only when core calls `dispatchResult()` — not on `.build()`.
|
|
1139
|
-
|
|
1140
|
-
### What you get in `logic`
|
|
1141
|
-
|
|
1142
|
-
| Field | Description |
|
|
1143
|
-
|---|---|
|
|
1144
|
-
| `req.body`, `req.query`, `req.params` | Normalized input |
|
|
1145
|
-
| `req.requestId` | Trace id (header or generated) |
|
|
1146
|
-
| `req.t` | i18n function |
|
|
1147
|
-
| `builder` | `@xrystal/dto` response builder |
|
|
1148
|
-
|
|
1149
|
-
---
|
|
1150
|
-
|
|
1151
|
-
## Setup (2 steps)
|
|
1152
|
-
|
|
1153
|
-
### 1. Middleware once — prepares every request
|
|
1154
|
-
|
|
1155
|
-
```typescript
|
|
1156
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
1157
|
-
|
|
1158
|
-
app.use(dtoMiddleware())
|
|
1159
|
-
app.use(dtoMiddleware('elysia'))
|
|
1160
|
-
app.use(dtoMiddleware({ framework: 'express' }))
|
|
1161
|
-
```
|
|
1162
|
-
|
|
1163
|
-
`dtoMiddleware(config)` maps config → `runtime.express()` / `.elysia()` / `.socketIo()` / `.websocket()` / `.node()`. Fetch has no global middleware — `ctr()` uses `forRequest(req)` per request.
|
|
1164
|
-
|
|
1165
|
-
### 2. Register routes — tell framework which URL → which action
|
|
1166
|
-
|
|
1167
|
-
```typescript
|
|
1168
|
-
app.get('/users', userCtrl.list)
|
|
1169
|
-
app.post('/users', userCtrl.create)
|
|
1170
|
-
```
|
|
1171
|
-
|
|
1172
|
-
Express requires a handler per route. Middleware cannot replace `app.get` — it runs for all paths but does not know `/users` → `list`.
|
|
1173
|
-
|
|
1174
|
-
`toHandler()` still exists for edge cases; prefer `this.ctr()`.
|
|
1175
|
-
|
|
1176
|
-
---
|
|
1177
|
-
|
|
1178
|
-
## Framework examples
|
|
1179
|
-
|
|
1180
|
-
### Express (default)
|
|
1181
|
-
|
|
1182
|
-
```typescript
|
|
1183
|
-
import express from 'express'
|
|
1184
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
1185
|
-
|
|
1186
|
-
const app = express()
|
|
1187
|
-
app.use(dtoMiddleware())
|
|
1188
|
-
|
|
1189
|
-
app.get('/health', healthCtrl.check)
|
|
1190
|
-
```
|
|
1191
|
-
|
|
1192
|
-
### Elysia
|
|
1193
|
-
|
|
1194
|
-
```yaml
|
|
1195
|
-
configs:
|
|
1196
|
-
framework: elysia
|
|
1197
|
-
```
|
|
1198
|
-
|
|
1199
|
-
```typescript
|
|
1200
|
-
import { Elysia } from 'elysia'
|
|
1201
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
1202
|
-
|
|
1203
|
-
const app = new Elysia()
|
|
1204
|
-
.use(dtoMiddleware())
|
|
1205
|
-
.get('/health', healthCtrl.check)
|
|
1206
|
-
```
|
|
1207
|
-
|
|
1208
|
-
### Fetch / Bun.serve
|
|
1209
|
-
|
|
1210
|
-
```yaml
|
|
1211
|
-
configs:
|
|
1212
|
-
framework: fetch
|
|
1213
|
-
```
|
|
1214
|
-
|
|
1215
|
-
```typescript
|
|
1216
|
-
class HealthController extends Controller {
|
|
1217
|
-
check = this.ctr({
|
|
1218
|
-
logic: async () => ({ status: 'ok' }),
|
|
1219
|
-
})
|
|
1220
|
-
}
|
|
1221
|
-
|
|
1222
|
-
Bun.serve({
|
|
1223
|
-
fetch: (req) => healthCtrl.check(req),
|
|
1224
|
-
})
|
|
1225
|
-
```
|
|
1226
|
-
|
|
1227
|
-
No global middleware — `ctr()` calls `forRequest(req)` to attach builder + fetch sink per request.
|
|
1228
|
-
|
|
1229
|
-
### Node (raw http)
|
|
1230
|
-
|
|
1231
|
-
```yaml
|
|
1232
|
-
configs:
|
|
1233
|
-
framework: node
|
|
1234
|
-
```
|
|
1235
|
-
|
|
1236
|
-
```typescript
|
|
1237
|
-
import http from 'node:http'
|
|
1238
|
-
|
|
1239
|
-
http.createServer((req, res) => healthCtrl.check(req, res)).listen(3000)
|
|
1240
|
-
```
|
|
1241
|
-
|
|
1242
|
-
### Realtime (özet — detay için üstteki rehber)
|
|
1243
|
-
|
|
1244
|
-
Native WS ve Socket.IO aynı 3 adım. `framework` tmp.yml'den gelmez.
|
|
1245
|
-
|
|
1246
|
-
```typescript
|
|
1247
|
-
onMessage = this.ctr({ logic: async () => ({ data: {} }) }, { protocol: 'ws' })
|
|
1248
|
-
socket.on('message', onMessage.with(socket))
|
|
1249
|
-
|
|
1250
|
-
await runAction({ protocol: 'socketio', socket }, async () =>
|
|
1251
|
-
socket.builder.as.ok({ ok: true }).build(),
|
|
1252
|
-
)
|
|
1253
|
-
```
|
|
1254
|
-
|
|
1255
|
-
---
|
|
1256
|
-
|
|
1257
|
-
## Mimari özeti (basit şema)
|
|
1258
|
-
|
|
1259
|
-
Tek cümle: **framework = HTTP taşıyıcı**, **protocol = action tipi**, **3 store = farklı ömür**.
|
|
1260
|
-
|
|
1261
|
-
```mermaid
|
|
1262
|
-
flowchart TB
|
|
1263
|
-
subgraph process["Process (servis örneği)"]
|
|
1264
|
-
G["G — global\nmaintenance, cache, flags\ntmp.yml vars"]
|
|
1265
|
-
end
|
|
1266
|
-
|
|
1267
|
-
subgraph request["Her istek / job"]
|
|
1268
|
-
RUN["Run context (ALS)\nrequestId, kind, trace"]
|
|
1269
|
-
CTRL["Controller context (ALS)\nreq, cookies, builder, socket"]
|
|
1270
|
-
RUN --> CTRL
|
|
1271
|
-
end
|
|
1272
|
-
|
|
1273
|
-
MW["dtoMiddleware()"] --> RUN
|
|
1274
|
-
CTRL --> LOGIC["ctr() logic"]
|
|
1275
|
-
LOGIC --> DISPATCH["dispatchResult() → dto sink"]
|
|
1276
|
-
G -.->|"sadece oku/yaz flag"| LOGIC
|
|
1277
|
-
```
|
|
1278
|
-
|
|
1279
|
-
| Veri | Nereye? | Örnek |
|
|
1280
|
-
|------|---------|--------|
|
|
1281
|
-
| `requestId`, correlation | **Run context** | `getRequestId()`, log, outbound header |
|
|
1282
|
-
| `cookies`, `body`, `headers`, `builder` | **Controller context** | `this.req.cookies`, `this.res.builder` |
|
|
1283
|
-
| Bakım modu, warmed cache, feature flag | **G** | `G.get('test')`, `G.set('maintenance', true)` |
|
|
1284
|
-
| Servisler arası state | **Hiçbiri (G değil!)** | DB, Redis, message bus |
|
|
1285
|
-
|
|
1286
|
-
**Patlamadan korunma — 4 kural:**
|
|
1287
|
-
|
|
1288
|
-
1. İstek verisini `G`'ye yazma — handler bitince kaybolması gereken her şey ALS'te kalır. `G.set('requestId'| 'cookies'| ...)` → runtime **warn** ( `warnOnRequestKeys: false` ile kapatılır).
|
|
1289
|
-
2. Handler dışında `this.req` / `getControllerCtx()` bekleme — `undefined` döner, bug değil.
|
|
1290
|
-
3. Realtime'da `protocol` açık ver — `ctr({ ... }, { protocol: 'ws' })`.
|
|
1291
|
-
4. Microservice'te her pod kendi `G`'sine sahip — cross-service state için Redis/DB kullan.
|
|
1292
|
-
|
|
1293
|
-
`G.scope(GStoreScopeEnum.*)` → debug/observability; günlük iş mantığında zorunlu değil.
|
|
1294
|
-
|
|
1295
|
-
**tmp.yml değişince:** `TmpFileLoader` izler → `System.applyTmp()` → runtime snapshot + `G` + loader'lar sırayla `syncFromTmp()` (`bindLoaderTmpSync(this)`).
|
|
1296
|
-
|
|
1297
|
-
---
|
|
1298
|
-
|
|
1299
|
-
## DI + tmp.yml — boot ve canlı güncelleme
|
|
1300
|
-
|
|
1301
|
-
Tek kaynak: proje kökündeki **`x/tmp.yml`**. Loader'lar dosyayı doğrudan okumaz; **System** okur, snapshot'ı dağıtır.
|
|
1302
|
-
|
|
1303
|
-
```mermaid
|
|
1304
|
-
sequenceDiagram
|
|
1305
|
-
participant YML as x/tmp.yml
|
|
1306
|
-
participant TFL as TmpFileLoader
|
|
1307
|
-
participant SYS as System (DI)
|
|
1308
|
-
participant RT as runtime snapshot
|
|
1309
|
-
participant G as G store
|
|
1310
|
-
participant L as Loaders
|
|
1311
|
-
|
|
1312
|
-
YML->>TFL: watchFile (configs.core.tmp.fileWatchIntervalMs)
|
|
1313
|
-
TFL->>SYS: reload event
|
|
1314
|
-
SYS->>SYS: applyTmp(parsed)
|
|
1315
|
-
SYS->>RT: setRuntimeTmpConfigs
|
|
1316
|
-
SYS->>G: configureFromTmp
|
|
1317
|
-
SYS->>L: notifyRuntimeTmpChange (sırayla)
|
|
1318
|
-
Note over L: Configs → Kafka → Logger → …
|
|
1319
|
-
L->>L: syncFromTmp()
|
|
1320
|
-
```
|
|
1321
|
-
|
|
1322
|
-
### Boot (Awilix DI)
|
|
1323
|
-
|
|
1324
|
-
`source/project/index.ts`:
|
|
1325
|
-
|
|
1326
|
-
```typescript
|
|
1327
|
-
const core = getCore() // tmp.yml oku (ilk snapshot)
|
|
1328
|
-
|
|
1329
|
-
await x.initialize([
|
|
1330
|
-
{ service: System, props: { core } },
|
|
1331
|
-
{ service: Configs, props: { system } },
|
|
1332
|
-
{ service: KafkaForCore, props: { system, configs } },
|
|
1333
|
-
{ service: Logger, props: { system, configs, kafkaForCore } },
|
|
1334
|
-
// … Events, Localizations, Dto, Controller, Clients
|
|
1335
|
-
])
|
|
1336
|
-
```
|
|
1337
|
-
|
|
1338
|
-
**Sıra önemli:** `Configs` önce init olur → `Kafka`/`Logger` onun `configs.all`'ını kullanır.
|
|
1339
|
-
|
|
1340
|
-
Her loader `onInit`:
|
|
1341
|
-
|
|
1342
|
-
```typescript
|
|
1343
|
-
await this.syncFromTmp()
|
|
1344
|
-
bindLoaderTmpSync(this)
|
|
1345
|
-
```
|
|
1346
|
-
|
|
1347
|
-
### tmp değişince ne olur?
|
|
1348
|
-
|
|
1349
|
-
| Adım | Ne |
|
|
1350
|
-
|------|-----|
|
|
1351
|
-
| 1 | `tmp.yml` kaydedilir |
|
|
1352
|
-
| 2 | `TmpFileLoader` değişikliği algılar |
|
|
1353
|
-
| 3 | `System.applyTmp(yeniTmp)` |
|
|
1354
|
-
| 4 | `getRuntimeTmpConfigs()` güncellenir — `getFramework()`, `getConfiguredProtocols()` bunu okur |
|
|
1355
|
-
| 5 | `G.configureFromTmp` — `loaders.system.gStore.vars` |
|
|
1356
|
-
| 6 | Her loader `syncFromTmp()` — winston, dto, i18n, kafka, … yeniden kurulur |
|
|
1357
|
-
|
|
1358
|
-
**Eski tmp affedilmez** — her reload tam sync.
|
|
1359
|
-
|
|
1360
|
-
### Nereden import?
|
|
1361
|
-
|
|
1362
|
-
Hepsi `@xrystal/core/utils` (veya loader içinden `../../utils`):
|
|
1363
|
-
|
|
1364
|
-
```typescript
|
|
1365
|
-
import {
|
|
1366
|
-
bindLoaderTmpSync,
|
|
1367
|
-
getRuntimeTmpConfigs,
|
|
1368
|
-
getConfiguredProtocols,
|
|
1369
|
-
G,
|
|
1370
|
-
GStoreScopeEnum,
|
|
1371
|
-
type ITmpSyncLoader,
|
|
1372
|
-
} from '@xrystal/core/utils'
|
|
1373
|
-
```
|
|
1374
|
-
|
|
1375
|
-
Runtime helper'lar (`getFramework`, `getConfiguredProtocols`) **System'in yazdığı snapshot**'ı okur — dosyadan tekrar parse etmez.
|
|
1376
|
-
|
|
1377
|
-
Uygulama kodunda tmp okumak için: `x.get<System>(System).tmp` veya `getRuntimeTmpConfigs()`.
|
|
1378
|
-
|
|
1379
|
-
---
|
|
1380
|
-
|
|
1381
|
-
## Three stores (by design)
|
|
1382
|
-
|
|
1383
|
-
Üç ayrı depo — birbirinin yerine geçmez:
|
|
1384
|
-
|
|
1385
|
-
| Store | Import | Lifetime | Ne için? |
|
|
1386
|
-
|---|---|---|---|
|
|
1387
|
-
| **Run context** | `getRequestId`, `runWithTrace` | İstek / job (ALS) | `requestId`, log correlation, outbound headers |
|
|
1388
|
-
| **Controller context** | `this.req`, `this.store`, `builder` | İstek (ALS) | HTTP/socket handler anı — req, res, builder |
|
|
1389
|
-
| **G** | `G`, `system.g` | Uygulama (store) | Düz prop'lar — System `onInit` tmp.yml'den bootstrap |
|
|
1390
|
-
|
|
1391
|
-
```
|
|
1392
|
-
HTTP isteği gelir
|
|
1393
|
-
→ run context açılır (requestId)
|
|
1394
|
-
→ controller context açılır (req, res, builder)
|
|
1395
|
-
→ logic biter → ikisi kapanır
|
|
1396
|
-
|
|
1397
|
-
G → process boyunca kalır (maintenance, warmed cache, …)
|
|
1398
|
-
```
|
|
1399
|
-
|
|
1400
|
-
### Run context (scoped trace)
|
|
1401
|
-
|
|
1402
|
-
```typescript
|
|
1403
|
-
import { getRequestId, runWithTrace } from '@xrystal/core/utils'
|
|
1404
|
-
```
|
|
1405
|
-
|
|
1406
|
-
- `ctr()` / `runAction()` / realtime handler otomatik açar
|
|
1407
|
-
- Handler bitince kapanır — **global değil**
|
|
1408
|
-
- Cron/queue: `runWithTrace('job-id', fn)`
|
|
1409
|
-
|
|
1410
|
-
```typescript
|
|
1411
|
-
list = this.ctr({
|
|
1412
|
-
logic: async () => {
|
|
1413
|
-
this.logger.log(LoggerLayerEnum.INFO, 'listing')
|
|
1414
|
-
return { data: [] }
|
|
1415
|
-
},
|
|
1416
|
-
})
|
|
1417
|
-
|
|
1418
|
-
await runWithTrace('nightly-sync', async () => {
|
|
1419
|
-
logger.log(LoggerLayerEnum.INFO, 'started')
|
|
1420
|
-
}, 'sync-users')
|
|
1421
|
-
```
|
|
1422
|
-
|
|
1423
|
-
### Controller context (scoped handler)
|
|
1424
|
-
|
|
1425
|
-
`runController()` `ControllerContext` yazar — controller içinde `this.req`, `this.store`, `builder`. Run context ile aynı istek; farklı veri.
|
|
1426
|
-
|
|
1427
|
-
### G — global store (Zustand)
|
|
1428
|
-
|
|
1429
|
-
Düz property bag. **Tek kaynak:** proje kökündeki `x/tmp.yml`. System boot: `G.configureFromTmp(tmp)`.
|
|
1430
|
-
|
|
1431
|
-
```typescript
|
|
1432
|
-
import { G } from '@xrystal/core/utils'
|
|
1433
|
-
|
|
1434
|
-
G.set('maintenance', false)
|
|
1435
|
-
G.get('test')
|
|
1436
|
-
this.system.g.get('region')
|
|
1437
|
-
```
|
|
1438
|
-
|
|
1439
|
-
| API | EN | TR |
|
|
1440
|
-
|-----|----|----|
|
|
1441
|
-
| `G.configureFromTmp(tmp)` | Boot from `system.gStore` (System loader) | tmp.yml → vars |
|
|
1442
|
-
| `G.set(key, value)` | Set prop (runtime) | Prop yaz |
|
|
1443
|
-
| `G.merge({ ... })` | Set many | Çoklu prop |
|
|
1444
|
-
| `G.get(key, fallback?)` | Read prop | Oku |
|
|
1445
|
-
| `G.subscribe(fn)` | `(state, prev, changes[])` | Değişen key'ler |
|
|
1446
|
-
| `G.subscribeKey(key, fn)` | Single prop | Tek prop dinle |
|
|
1447
|
-
|
|
1448
|
-
**tmp.yml:**
|
|
211
|
+
### Elysia (default)
|
|
1449
212
|
|
|
1450
213
|
```yaml
|
|
214
|
+
# x/tmp.yml
|
|
1451
215
|
configs:
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1456
|
-
bootstrap: true
|
|
1457
|
-
autoCreateProps: false
|
|
1458
|
-
vars:
|
|
1459
|
-
test: false
|
|
1460
|
-
```
|
|
1461
|
-
|
|
1462
|
-
→ `G.get('test')` — sadece `vars` içindeki key'ler
|
|
1463
|
-
|
|
1464
|
-
**Runtime — `autoCreateProps: false`:**
|
|
1465
|
-
|
|
1466
|
-
```typescript
|
|
1467
|
-
G.set('test', true) // ok — tmp vars'da tanımlı
|
|
1468
|
-
G.set('runtimeOnly', 1) // throws — tmp'de yok
|
|
1469
|
-
```
|
|
1470
|
-
|
|
1471
|
-
**Runtime — `autoCreateProps: true`:**
|
|
1472
|
-
|
|
1473
|
-
```typescript
|
|
1474
|
-
G.set('sessionCache', true) // ok — runtime key
|
|
1475
|
-
```
|
|
1476
|
-
|
|
1477
|
-
**Scope enum — string karışmasın:**
|
|
1478
|
-
|
|
1479
|
-
```typescript
|
|
1480
|
-
import { G, GStoreScopeEnum } from '@xrystal/core/utils'
|
|
1481
|
-
|
|
1482
|
-
G.scope(GStoreScopeEnum.GLOBAL)
|
|
1483
|
-
G.scope(GStoreScopeEnum.RUN)
|
|
1484
|
-
G.scope(GStoreScopeEnum.CONTROLLER)
|
|
1485
|
-
```
|
|
1486
|
-
|
|
1487
|
-
**Controller:**
|
|
1488
|
-
|
|
1489
|
-
```typescript
|
|
1490
|
-
checks: () => G.get('test', false) ? { message: '@unsuccessful maintenance' } : true
|
|
1491
|
-
```
|
|
1492
|
-
|
|
1493
|
-
**Subscribe:**
|
|
1494
|
-
|
|
1495
|
-
```typescript
|
|
1496
|
-
G.subscribe((_state, _prev, changes) => {
|
|
1497
|
-
for (const { key, value, prev } of changes) {
|
|
1498
|
-
logger.log(LoggerLayerEnum.INFO, `G.${key}`, { value, prev })
|
|
1499
|
-
}
|
|
1500
|
-
})
|
|
1501
|
-
|
|
1502
|
-
G.subscribeKey('test', (value, prev) => {
|
|
1503
|
-
logger.log(LoggerLayerEnum.INFO, 'test', { value, prev })
|
|
1504
|
-
})
|
|
1505
|
-
```
|
|
1506
|
-
|
|
1507
|
-
**Üç store'u tek yerden gör:**
|
|
1508
|
-
|
|
1509
|
-
```typescript
|
|
1510
|
-
G.list()
|
|
1511
|
-
|
|
1512
|
-
G.scope('global').set?.('flag', 1)
|
|
1513
|
-
G.scope('run').get('requestId')
|
|
1514
|
-
G.scope('run').patch?.({ meta: { source: 'cron' } })
|
|
1515
|
-
G.scope('controller').patch?.({ metadata: { locals: { userId: 1 } } } })
|
|
1516
|
-
```
|
|
1517
|
-
|
|
1518
|
-
| Store | Aktif ne zaman | Manipülasyon |
|
|
1519
|
-
|-------|----------------|--------------|
|
|
1520
|
-
| `global` | Her zaman | `set`, `merge` |
|
|
1521
|
-
| `run` | İstek / job içinde | `patch` (meta, label) |
|
|
1522
|
-
| `controller` | Handler içinde | `patch` (metadata.locals) |
|
|
1523
|
-
|
|
1524
|
-
### App responsibility (keep it simple)
|
|
1525
|
-
|
|
1526
|
-
1. **`tmp.yml`** — `framework: elysia` (veya express, fetch, …)
|
|
1527
|
-
2. **`app.use(dtoMiddleware())`** bir kez
|
|
1528
|
-
3. Process-wide bag gerekiyorsa **`G`** — per-request trace için değil
|
|
1529
|
-
|
|
1530
|
-
---
|
|
1531
|
-
|
|
1532
|
-
## Request ID (trace)
|
|
1533
|
-
|
|
1534
|
-
One id per request — from **run context** (not `G`).
|
|
1535
|
-
|
|
1536
|
-
```
|
|
1537
|
-
Incoming header (x-request-id / x-correlation-id)
|
|
1538
|
-
↓
|
|
1539
|
-
dto adapter middleware → req.ctx.requestId
|
|
1540
|
-
↓
|
|
1541
|
-
ensureRequestId() → run context requestId
|
|
1542
|
-
↓
|
|
1543
|
-
runWithRequestId(id, fn)
|
|
1544
|
-
↓
|
|
1545
|
-
req.requestId → controller context
|
|
1546
|
-
logger.log() → LogDTO.id
|
|
1547
|
-
Clients outbound → x-correlation-id
|
|
1548
|
-
```
|
|
1549
|
-
|
|
1550
|
-
| Case | Behaviour |
|
|
1551
|
-
|---|---|
|
|
1552
|
-
| Header present | That value is used |
|
|
1553
|
-
| No header | UUID generated automatically |
|
|
1554
|
-
| Cron / queue / script | `runWithTrace('job-42', () => { ... })` |
|
|
1555
|
-
|
|
1556
|
-
```typescript
|
|
1557
|
-
import { runWithTrace } from '@xrystal/core/utils'
|
|
1558
|
-
|
|
1559
|
-
await runWithTrace('nightly-sync', async () => {
|
|
1560
|
-
logger.log(LoggerLayerEnum.INFO, 'job started')
|
|
1561
|
-
})
|
|
1562
|
-
```
|
|
1563
|
-
|
|
1564
|
-
---
|
|
1565
|
-
|
|
1566
|
-
## @xrystal/dto migration (v26.6.28+)
|
|
1567
|
-
|
|
1568
|
-
Removed from dto — use core instead:
|
|
1569
|
-
|
|
1570
|
-
| Removed (dto) | Replacement (core) |
|
|
1571
|
-
|---|---|
|
|
1572
|
-
| `runtime.middleware()` | `dtoMiddleware()` |
|
|
1573
|
-
| `runtime.middleware('express')` | `dtoMiddleware('express')` |
|
|
1574
|
-
| `normalizeRuntimeKind()` | `normalizeFrameworkKind()` |
|
|
1575
|
-
|
|
1576
|
-
```typescript
|
|
1577
|
-
app.use(runtime.express())
|
|
1578
|
-
|
|
1579
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
1580
|
-
app.use(dtoMiddleware())
|
|
1581
|
-
app.use(dtoMiddleware('socketio'))
|
|
1582
|
-
```
|
|
1583
|
-
|
|
1584
|
-
Mapping lives in `utils/helpers/middleware/` — `socketio` → `socketIo()`, `websocket` → `websocket()`.
|
|
1585
|
-
|
|
1586
|
-
---
|
|
1587
|
-
|
|
1588
|
-
## CLI (`xcore` · `xrystal` · `tmp`)
|
|
1589
|
-
|
|
1590
|
-
**EN:** Installing `@xrystal/core` exposes **three bin names** for the same CLI (`x/bin/main-cli.js`) — same commands, same project-root resolution.
|
|
1591
|
-
|
|
1592
|
-
**TR:** `@xrystal/core` kurulunca **üç bin adı** aynı CLI’yı açar — aynı komutlar, aynı proje kökü çözümlemesi.
|
|
1593
|
-
|
|
1594
|
-
| Bin | EN | TR | Example |
|
|
1595
|
-
|-----|----|----|---------|
|
|
1596
|
-
| **`xcore`** | Primary name (recommended) | Ana isim (önerilen) | `xcore doctor`, `npx xcore dev` |
|
|
1597
|
-
| **`xrystal`** | Transition alias | Geçiş alias | `xrystal version` = `xcore version` |
|
|
1598
|
-
| **`tmp`** | Legacy alias | Eski alışkanlık alias | `tmp tag` = `xcore tag` |
|
|
1599
|
-
|
|
1600
|
-
**EN:** Any bin name resolves project root, git, version/tag, and `dev`/`build`/`test` through the **same code path**. Banner shows the bin you invoked.
|
|
1601
|
-
|
|
1602
|
-
**TR:** Hangi bin adını yazarsan yaz: proje kökü, git, version/tag, dev/build/test **aynı kod yolu**. Banner çağırdığın bin adını gösterir.
|
|
1603
|
-
|
|
1604
|
-
**EN:** Works in every service repo with `@xrystal/core` — no global install. From a subfolder (`src/`, `x/`, …) the CLI walks up to the `package.json` that depends on `@xrystal/core`; git / version / tag stay on **that service root**.
|
|
1605
|
-
|
|
1606
|
-
**TR:** `@xrystal/core` dependency’si olan her serviste doğrudan kullanılır — global kurulum gerekmez. Alt klasörden çalıştırsan bile CLI yukarı çıkar; git / version / tag **o servisin** kökünde kalır.
|
|
1607
|
-
|
|
1608
|
-
```bash
|
|
1609
|
-
cd api-gateway-svc/src
|
|
1610
|
-
|
|
1611
|
-
npx xcore doctor # → api-gateway-svc/package.json
|
|
1612
|
-
npx xrystal version # aynı
|
|
1613
|
-
npx tmp tag # aynı — servis tag + push
|
|
1614
|
-
```
|
|
1615
|
-
|
|
1616
|
-
**EN:** Any bin alias in service `package.json` scripts — same behavior.
|
|
1617
|
-
|
|
1618
|
-
**TR:** Servis `package.json` script’lerinde herhangi bir alias kullanılabilir; davranış değişmez.
|
|
1619
|
-
|
|
1620
|
-
```json
|
|
1621
|
-
{
|
|
1622
|
-
"scripts": {
|
|
1623
|
-
"dev": "xcore dev",
|
|
1624
|
-
"doctor": "xrystal doctor",
|
|
1625
|
-
"release:tag": "tmp tag"
|
|
1626
|
-
}
|
|
1627
|
-
}
|
|
1628
|
-
```
|
|
1629
|
-
|
|
1630
|
-
---
|
|
1631
|
-
|
|
1632
|
-
### Three script layers / Üç script katmanı
|
|
1633
|
-
|
|
1634
|
-
| Layer / Katman | Defined in / Tanım | When / Ne zaman | Example / Örnek |
|
|
1635
|
-
|----------------|-------------------|-----------------|-----------------|
|
|
1636
|
-
| **CLI (shared)** | `@xrystal/core` bin (`xcore` / `xrystal` / `tmp`) | Same in all services / Tüm servislerde aynı | `xcore dev`, `tmp version`, `xrystal tag` |
|
|
1637
|
-
| **Project (service)** | Service `package.json` → `scripts` | Service-specific; `xcore build` delegates if custom / Servise özel; özel build varsa delegate | `"build": "bun build src/boot.ts"` |
|
|
1638
|
-
| **Lib (core repo)** | `@xrystal/core` own `package.json` | Core dev / publish only / Sadece core geliştirme | `"release:prepare"`, `"tag"` |
|
|
1639
|
-
|
|
1640
|
-
**EN — shared CLI commands** (`<bin>` = `xcore` | `xrystal` | `tmp`; cwd = project root):
|
|
1641
|
-
|
|
1642
|
-
| Command | What it does |
|
|
1643
|
-
|---------|----------------|
|
|
1644
|
-
| `<bin> version` | CLI version + project `package.json` ↔ git HEAD |
|
|
1645
|
-
| `<bin> tag` | `v{version}` tag + push from **project** version |
|
|
1646
|
-
| `<bin> doctor` | Runtimes, git, installed `@xrystal/core` vs CLI |
|
|
1647
|
-
| `<bin> test` | `bun test ./{rootFolderPath}/{paths.tests}` |
|
|
1648
|
-
| `<bin> dev` | Watch `{service.folderPath}/index.ts` + dev env |
|
|
1649
|
-
| `<bin> build` | Output → `{rootFolderPath}/{paths.dist}/` |
|
|
1650
|
-
| `<bin> start` | Run `{rootFolderPath}/{paths.dist}/index.js` + prod env |
|
|
1651
|
-
| `<bin> tmp` | Ensure `tmp.yml` from seed if missing |
|
|
1652
|
-
| `<bin> create [name] [path]` | GitHub template clone + `tmp.yml` ensure |
|
|
1653
|
-
|
|
1654
|
-
**TR — ortak CLI komutlar** (`<bin>` = `xcore` | `xrystal` | `tmp`; cwd = proje kökü):
|
|
1655
|
-
|
|
1656
|
-
| Komut | Ne yapar |
|
|
1657
|
-
|-------|----------|
|
|
1658
|
-
| `<bin> version` | CLI sürümü + **proje** `package.json` ↔ git HEAD |
|
|
1659
|
-
| `<bin> tag` | **Proje** versiyonundan `v{version}` tag + push |
|
|
1660
|
-
| `<bin> doctor` | runtime, git, kurulu `@xrystal/core` vs CLI |
|
|
1661
|
-
| `<bin> test` | `bun test ./{rootFolderPath}/{paths.tests}` |
|
|
1662
|
-
| `<bin> dev` | `{service.folderPath}/index.ts` watch + dev env |
|
|
1663
|
-
| `<bin> build` | Çıktı → `{rootFolderPath}/{paths.dist}/` |
|
|
1664
|
-
| `<bin> start` | `{rootFolderPath}/{paths.dist}/index.js` + prod env |
|
|
1665
|
-
| `<bin> tmp` | `tmp.yml` yoksa seed’den oluşturur |
|
|
1666
|
-
| `<bin> create [name] [path]` | GitHub template + `tmp.yml` ensure |
|
|
1667
|
-
|
|
1668
|
-
**EN:** If `tmp.yml` is missing, `xcore tmp` / `dev` / `test` / `build` copy seed from `@xrystal/core/x/tmp.yml` into `{rootFolderPath}/tmp.yml`.
|
|
1669
|
-
|
|
1670
|
-
**TR:** `tmp.yml` silinmişse `xcore tmp` / `dev` / `test` / `build`, seed `@xrystal/core/x/tmp.yml` dosyasından `{rootFolderPath}/tmp.yml` oluşturur.
|
|
1671
|
-
|
|
1672
|
-
**EN — core repo guard:** In `@xrystal/core` repo, `tmp.yml` must be only `x/tmp.yml`; stray copies fail boot/CLI. Services have no such rule.
|
|
1673
|
-
|
|
1674
|
-
**TR — core koruması:** `@xrystal/core` repo’sunda `tmp.yml` yalnızca `x/tmp.yml`; başka kopya hata verir. Servislerde bu kural yok.
|
|
1675
|
-
|
|
1676
|
-
```bash
|
|
1677
|
-
xcore tmp # ensure tmp.yml
|
|
1678
|
-
xcore create example ./ # GitHub template + tmp ensure
|
|
1679
|
-
tmp dev # bin alias = xcore dev
|
|
1680
|
-
```
|
|
1681
|
-
|
|
1682
|
-
**EN:** `configs` in `tmp.yml`: `service.*` + `core.*` — single source per service. Core package default: `service.paths.root: x`.
|
|
1683
|
-
|
|
1684
|
-
**TR:** `tmp.yml` içinde `configs`: `service.*` + `core.*` — servis tek kaynak. Core pakette default `service.paths.root: x`.
|
|
1685
|
-
|
|
1686
|
-
**EN — recommended service `package.json` wiring** (bind shared CLI commands; keep service-specific scripts separate):
|
|
1687
|
-
|
|
1688
|
-
**TR — önerilen servis `package.json` wiring** (ortak komutları script’e bağla; servise özel olanları ayrı tut):
|
|
1689
|
-
|
|
1690
|
-
```json
|
|
1691
|
-
{
|
|
1692
|
-
"name": "api-gateway-svc",
|
|
1693
|
-
"version": "26.06.27-v1",
|
|
1694
|
-
"dependencies": {
|
|
1695
|
-
"@xrystal/core": "^3.34.0"
|
|
1696
|
-
},
|
|
1697
|
-
"scripts": {
|
|
1698
|
-
"dev": "xcore dev",
|
|
1699
|
-
"build": "xcore build",
|
|
1700
|
-
"start:dist": "xcore start",
|
|
1701
|
-
"test": "xcore test",
|
|
1702
|
-
"lint": "eslint .",
|
|
1703
|
-
"sync-toolchain": "xcore sync-toolchain",
|
|
1704
|
-
"doctor": "xcore doctor",
|
|
1705
|
-
"version:check": "xcore version",
|
|
1706
|
-
"release:tag": "xcore tag",
|
|
1707
|
-
"start": "bun --env-file=./x/environments/.prod.env x/dist/index.js"
|
|
1708
|
-
}
|
|
1709
|
-
}
|
|
1710
|
-
```
|
|
1711
|
-
|
|
1712
|
-
**EN — toolchain files (service)**
|
|
1713
|
-
|
|
1714
|
-
**TR — toolchain dosyaları (servis)**
|
|
1715
|
-
|
|
1716
|
-
| File / Dosya | Required? / Zorunlu? | Note / Not |
|
|
1717
|
-
|--------------|----------------------|------------|
|
|
1718
|
-
| `{rootFolderPath}/tmp.yml` | Yes / Evet | Folder names here / Klasör adları burada |
|
|
1719
|
-
| `tsconfig.json` | Yes / Evet | Updated by `sync-toolchain` |
|
|
1720
|
-
| `eslint.config.js` | Recommended / Önerilir | Reads tmp — [example](#toolchain--klasör-adları-tmpyml-kurallar-tsconfigbasejson) |
|
|
1721
|
-
| `bunfig.toml` | Bun test/dev | `@/*` alias from sync output |
|
|
1722
|
-
|
|
1723
|
-
**EN — from service root:**
|
|
1724
|
-
|
|
1725
|
-
**TR — servis kökünden:**
|
|
1726
|
-
|
|
1727
|
-
```bash
|
|
1728
|
-
bun run dev # = xcore dev
|
|
1729
|
-
bun run version:check # = xcore version → api-gateway-svc version, git HEAD
|
|
1730
|
-
bun run release:tag # = xcore tag → servis tag’i, core değil
|
|
1731
|
-
bun run doctor # CLI vs node_modules @xrystal/core uyumu
|
|
1732
|
-
bun run sync-toolchain # sadece layout değişince (aşağıya bak)
|
|
1733
|
-
```
|
|
1734
|
-
|
|
1735
|
-
**EN — dev vs prod entry**
|
|
1736
|
-
|
|
1737
|
-
| Command | Runs | Path |
|
|
1738
|
-
|---------|------|------|
|
|
1739
|
-
| `xcore dev` | TypeScript source | `{service.folderPath}/index.ts` |
|
|
1740
|
-
| `xcore build` | Compiles to dist | `{rootFolderPath}/{paths.dist}/` |
|
|
1741
|
-
| `xcore start` | Production JS | `{rootFolderPath}/{paths.dist}/index.js` |
|
|
1742
|
-
|
|
1743
|
-
**TR — dev vs prod giriş**
|
|
1744
|
-
|
|
1745
|
-
| Komut | Çalıştırır | Yol |
|
|
1746
|
-
|-------|------------|-----|
|
|
1747
|
-
| `xcore dev` | TypeScript kaynak | `{service.folderPath}/index.ts` |
|
|
1748
|
-
| `xcore build` | Derler | `{rootFolderPath}/{paths.dist}/` |
|
|
1749
|
-
| `xcore start` | Prod JS | `{rootFolderPath}/{paths.dist}/index.js` |
|
|
1750
|
-
|
|
1751
|
-
**EN — service build:** `tsconfig.json` is primary (`include`, `outDir`, `rootDir`, `sourceMap`, `paths`, `strict`). `tmp.yml` `build.*` = explicit overrides only. `tmp.yml` runtime = loaders, protocols, `rootFolderPath`.
|
|
1752
|
-
|
|
1753
|
-
**TR — servis build:** `tsconfig.json` birincil. `tmp.yml` `build.*` = yalnızca override. `tmp.yml` runtime = loaders, protocols, `rootFolderPath`.
|
|
1754
|
-
|
|
1755
|
-
| File / Dosya | EN | TR |
|
|
1756
|
-
|--------------|----|----|
|
|
1757
|
-
| `tsconfig.json` | `include`→glob, `outDir`→dist, `sourceMap`, `paths`, `strict`, `typecheck` via `--noEmit` | `include`→glob, `outDir`→dist, `sourceMap`, `paths`, `strict`, `typecheck` için `--noEmit` |
|
|
1758
|
-
| `tmp.yml` `build.*` | Override: `typecheck`, `glob`, `entries`, `outDir`, `sourcemap`, `declarations`, `minify` | Override: `typecheck`, `glob`, `entries`, `outDir`, `sourcemap`, `declarations`, `minify` |
|
|
1759
|
-
| `tmp.yml` `paths.*` | Runtime (test, env); dist fallback if no `outDir` | Runtime (test, env); `outDir` yoksa dist fallback |
|
|
216
|
+
service:
|
|
217
|
+
framework: elysia
|
|
218
|
+
paths: { root: ./x, source: ./source }
|
|
219
|
+
```
|
|
1760
220
|
|
|
1761
|
-
|
|
1762
|
-
|
|
1763
|
-
|
|
1764
|
-
|
|
1765
|
-
|
|
1766
|
-
| `declarations` | `declaration` / `emitDeclarationOnly` | `.d.ts` üret |
|
|
1767
|
-
| `minify` | — (core build) | `tsc` sonrası `minify-dist.mjs` (tmp `build.minify: true`) |
|
|
1768
|
-
| `typecheck` | — (tsconfig kuralları okunur) | `tsc --noEmit` build öncesi |
|
|
1769
|
-
| `tsconfig` | dosya yolu | `tsconfig.build.json` vb. |
|
|
1770
|
-
| `tscLenient` | — | Sadece `declarations: true` + tsc hatalarını yoksay |
|
|
221
|
+
```typescript
|
|
222
|
+
import { Elysia } from 'elysia'
|
|
223
|
+
import coreLoader from '@xrystal/core'
|
|
224
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
225
|
+
import { userCtrl } from './controllers/user'
|
|
1771
226
|
|
|
1772
|
-
|
|
227
|
+
await coreLoader({})
|
|
228
|
+
new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
|
|
229
|
+
```
|
|
1773
230
|
|
|
1774
|
-
|
|
231
|
+
### Express
|
|
1775
232
|
|
|
1776
233
|
```yaml
|
|
1777
234
|
configs:
|
|
1778
|
-
file:
|
|
1779
|
-
rootFolderPath: x
|
|
1780
|
-
|
|
1781
235
|
service:
|
|
1782
|
-
|
|
1783
|
-
build:
|
|
1784
|
-
typecheck: true # tek satır yeter — outDir/include tsconfig'te
|
|
236
|
+
framework: express
|
|
1785
237
|
```
|
|
1786
238
|
|
|
1787
|
-
```
|
|
1788
|
-
|
|
1789
|
-
|
|
1790
|
-
|
|
1791
|
-
|
|
1792
|
-
"rootDir": "./source",
|
|
1793
|
-
"outDir": "./x/dist",
|
|
1794
|
-
"sourceMap": false,
|
|
1795
|
-
"declaration": false,
|
|
1796
|
-
"strict": true,
|
|
1797
|
-
"paths": { "@/*": ["source/*"] }
|
|
1798
|
-
}
|
|
1799
|
-
}
|
|
1800
|
-
```
|
|
239
|
+
```typescript
|
|
240
|
+
import express from 'express'
|
|
241
|
+
import coreLoader from '@xrystal/core'
|
|
242
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
243
|
+
import { userCtrl } from './controllers/user'
|
|
1801
244
|
|
|
1802
|
-
|
|
245
|
+
await coreLoader({})
|
|
246
|
+
const app = express()
|
|
247
|
+
app.use(dtoMiddleware('express'))
|
|
248
|
+
app.get('/users', userCtrl.list)
|
|
249
|
+
app.listen(3000)
|
|
250
|
+
```
|
|
1803
251
|
|
|
1804
|
-
|
|
252
|
+
### Node (raw http)
|
|
1805
253
|
|
|
1806
|
-
|
|
254
|
+
```yaml
|
|
255
|
+
configs:
|
|
256
|
+
service:
|
|
257
|
+
framework: node
|
|
258
|
+
```
|
|
1807
259
|
|
|
1808
|
-
|
|
260
|
+
```typescript
|
|
261
|
+
import http from 'node:http'
|
|
262
|
+
import coreLoader from '@xrystal/core'
|
|
263
|
+
import { userCtrl } from './controllers/user'
|
|
1809
264
|
|
|
1810
|
-
|
|
265
|
+
await coreLoader({})
|
|
266
|
+
http.createServer((req, res) => userCtrl.list(req, res)).listen(3000)
|
|
267
|
+
```
|
|
1811
268
|
|
|
1812
|
-
|
|
269
|
+
### Fetch / Bun.serve
|
|
1813
270
|
|
|
1814
|
-
```
|
|
1815
|
-
|
|
1816
|
-
|
|
271
|
+
```yaml
|
|
272
|
+
configs:
|
|
273
|
+
service:
|
|
274
|
+
framework: fetch
|
|
1817
275
|
```
|
|
1818
276
|
|
|
1819
|
-
|
|
1820
|
-
|
|
1821
|
-
|
|
1822
|
-
|-------|------|------|
|
|
1823
|
-
| Source (dev) | `{service.folderPath}/**/*.ts` | `xcore dev` runs TS directly |
|
|
1824
|
-
| Prod runtime | `tsconfig outDir` → `.js` | `xcore start`, Docker |
|
|
1825
|
-
| Source map | `{outDir}/**/*.js.map` | tsconfig `sourceMap` veya tmp `build.sourcemap` |
|
|
1826
|
-
| Declarations | `{outDir}/**/*.d.ts` | tsconfig `emitDeclarationOnly` veya tmp `build.declarations` |
|
|
277
|
+
```typescript
|
|
278
|
+
import coreLoader from '@xrystal/core'
|
|
279
|
+
import { userCtrl } from './controllers/user'
|
|
1827
280
|
|
|
1828
|
-
|
|
281
|
+
await coreLoader({})
|
|
282
|
+
Bun.serve({ fetch: (req) => userCtrl.list(req) })
|
|
283
|
+
```
|
|
1829
284
|
|
|
1830
|
-
|
|
285
|
+
`fetch` — no global middleware; `ctr()` attaches builder per request.
|
|
1831
286
|
|
|
1832
|
-
**
|
|
287
|
+
**EN:** WebSocket & Socket.IO — full guide at the end: [Realtime](#realtime--websocket--socketio).
|
|
1833
288
|
|
|
1834
|
-
|
|
289
|
+
**TR:** WebSocket & Socket.IO — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
|
|
1835
290
|
|
|
1836
|
-
|
|
1837
|
-
|
|
1838
|
-
|
|
1839
|
-
|
|
291
|
+
| Framework | `tmp.yml` | Middleware |
|
|
292
|
+
|-----------|-----------|------------|
|
|
293
|
+
| elysia | `framework: elysia` | `dtoMiddleware()` |
|
|
294
|
+
| express | `framework: express` | `dtoMiddleware('express')` |
|
|
295
|
+
| node | `framework: node` | `dtoMiddleware('node')` |
|
|
296
|
+
| fetch | `framework: fetch` | — (per-request in `ctr`) |
|
|
1840
297
|
|
|
1841
|
-
|
|
298
|
+
---
|
|
1842
299
|
|
|
1843
|
-
|
|
1844
|
-
|--------|----|----|
|
|
1845
|
-
| `npm run dev` | Core source watch | Core kaynak watch |
|
|
1846
|
-
| `npm run build` | `tsc` → alias → fix-dist-imports (+ minify) | `tsc` tam emit → Node ESM import düzeltme |
|
|
1847
|
-
| `npm run release:prepare` | lint → build → test (no git write) | lint → build → test (git’e yazmaz) |
|
|
1848
|
-
| `xcore hooks install` | Install pre-commit into `.git/hooks` (core + services) | `.git/hooks` pre-commit (core + servis) |
|
|
1849
|
-
| `npm run tag` / `xcore tag` | prepare + git tag + push | prepare + tag + push |
|
|
1850
|
-
| `npm publish` | GitHub Actions on tag (`--ignore-scripts`) | Tag’de CI publish eder |
|
|
300
|
+
## Reference / Referans
|
|
1851
301
|
|
|
1852
|
-
|
|
302
|
+
| Topic / Konu | Section / Bölüm |
|
|
303
|
+
|--------------|-----------------|
|
|
304
|
+
| Why kernel vs template | [Why](#why--neden) |
|
|
305
|
+
| All platform capabilities | [Platform features](#platform-features--platform-özellikleri) |
|
|
306
|
+
| Per-framework boot | [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) |
|
|
307
|
+
| Controller, `ctr()` | [Controller](#controller) |
|
|
308
|
+
| Express / Elysia detail | [Framework](#express--elysia) |
|
|
309
|
+
| DI, boot, tmp watch | [DI](#di--tmpyml) |
|
|
310
|
+
| Locale / dil | [i18n](#i18n--locale) |
|
|
311
|
+
| Global state | [G store](#g-store) |
|
|
312
|
+
| WebSocket & Socket.IO | [Realtime](#realtime--websocket--socketio) |
|
|
313
|
+
| API response shape | [DTO](#dto-responses--dto-cevapları) |
|
|
314
|
+
| End-to-end flow | [Usage guide](#usage-guide--kullanım-rehberi) |
|
|
1853
315
|
|
|
1854
|
-
|
|
1855
|
-
**TR:** Önce `package.json` version commit edilmeli.
|
|
1856
|
-
2. **EN:** `lint` → `build` → `test` (TypeScript stays in git; runtime in `x/dist`).
|
|
1857
|
-
**TR:** `lint` → `build` → `test` (git’te `.ts` kalır; runtime `x/dist`’te).
|
|
1858
|
-
3. **EN:** `git tag vX.Y.Z` + push → GitHub Actions publishes to npm.
|
|
1859
|
-
**TR:** Tag + push → CI npm’e publish eder.
|
|
316
|
+
---
|
|
1860
317
|
|
|
1861
|
-
|
|
318
|
+
## Controller
|
|
1862
319
|
|
|
1863
|
-
**
|
|
320
|
+
**EN:** One endpoint = one class property + `this.ctr()`. Wire URL → property. No manual `res.json()`.
|
|
1864
321
|
|
|
1865
|
-
**
|
|
322
|
+
**TR:** Bir endpoint = bir property + `this.ctr()`. URL → property bağla. `res.json()` yazmazsın.
|
|
1866
323
|
|
|
1867
|
-
|
|
324
|
+
```typescript
|
|
325
|
+
import Controller from '@xrystal/core/loader/controller'
|
|
1868
326
|
|
|
1869
|
-
|
|
327
|
+
class UserController extends Controller {
|
|
328
|
+
list = this.ctr({
|
|
329
|
+
logic: async ({ req }) => {
|
|
330
|
+
return { data: [], message: '@successfully user' }
|
|
331
|
+
},
|
|
332
|
+
})
|
|
333
|
+
}
|
|
334
|
+
export const userCtrl = new UserController()
|
|
335
|
+
```
|
|
1870
336
|
|
|
1871
|
-
|
|
337
|
+
```typescript
|
|
338
|
+
app.use(dtoMiddleware())
|
|
339
|
+
app.get('/users', userCtrl.list)
|
|
340
|
+
```
|
|
1872
341
|
|
|
1873
|
-
|
|
1874
|
-
|
|
342
|
+
| In `logic` / Logic içinde | EN | TR |
|
|
343
|
+
|---------------------------|----|----|
|
|
344
|
+
| `req.body`, `req.query`, `req.params` | Normalized input | Normalize girdi |
|
|
345
|
+
| `req.requestId` | Trace id | İzleme id |
|
|
346
|
+
| `req.t` | i18n function | Çeviri fonksiyonu |
|
|
347
|
+
| `this.logger` | Logger from DI | DI logger |
|
|
1875
348
|
|
|
1876
|
-
|
|
1877
|
-
`xcore hooks install` `.git/hooks/pre-commit` dosyasını yazar (repo'ya commit edilmez, sadece senin makinede). Sonrasında **`git commit`** atarken: **`package.json` içindeki `version` değiştiyse**, yeni sürüm eskisinden **büyük** olmalı. Sadece kod değişikliği commit'lerinde version aynı kalabilir.
|
|
349
|
+
---
|
|
1878
350
|
|
|
1879
|
-
|
|
351
|
+
## Express & Elysia
|
|
1880
352
|
|
|
1881
|
-
|
|
1882
|
-
|-----------|----------------------|
|
|
1883
|
-
| First clone of **`-xrystal-core`** on this machine | **Yes — once** |
|
|
1884
|
-
| Commits never block same/lower version bumps | **Yes — once** |
|
|
1885
|
-
| After `bun install` in core repo | Run once after clone |
|
|
1886
|
-
| Before every commit or tag | **No** |
|
|
1887
|
-
| **Service repo** (only uses `@xrystal/core`) | **Yes — once** |
|
|
1888
|
-
| **`xcore create`** scaffolded a new service | **Auto** — hook + `hooks:install` script |
|
|
353
|
+
**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.
|
|
1889
354
|
|
|
1890
|
-
**TR
|
|
355
|
+
**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.
|
|
1891
356
|
|
|
1892
|
-
|
|
1893
|
-
|-------|------------------|
|
|
1894
|
-
| **`-xrystal-core`** reposunu bu makinede ilk kez clone'ladım | **Evet — bir kez** |
|
|
1895
|
-
| Commit atınca version kontrolü hiç çalışmıyor | **Evet — bir kez** |
|
|
1896
|
-
| Core repo'da `bun install` sonrası | Clone sonrası bir kez |
|
|
1897
|
-
| Her commit / tag öncesi | **Hayır** |
|
|
1898
|
-
| Sadece servis reposu | **Evet — bir kez** |
|
|
1899
|
-
| **`xcore create`** ile yeni servis oluşturdum | **Otomatik** — hook + `hooks:install` script |
|
|
357
|
+
**Express**
|
|
1900
358
|
|
|
1901
|
-
```
|
|
1902
|
-
|
|
1903
|
-
|
|
1904
|
-
|
|
1905
|
-
# core repo only: bun run hooks:install
|
|
359
|
+
```yaml
|
|
360
|
+
configs:
|
|
361
|
+
service:
|
|
362
|
+
framework: express
|
|
1906
363
|
```
|
|
1907
364
|
|
|
1908
|
-
|
|
1909
|
-
|
|
1910
|
-
|
|
1911
|
-
|
|
1912
|
-
| **pre-commit hook** | `git commit` (if hook installed) | Staged `version` > HEAD `version` |
|
|
1913
|
-
| **`xcore tag`** | Before tag + push | Committed `version` > latest git tag |
|
|
1914
|
-
|
|
1915
|
-
**TR — iki katman**
|
|
1916
|
-
|
|
1917
|
-
| Katman | Ne zaman | Kural |
|
|
1918
|
-
|--------|----------|-------|
|
|
1919
|
-
| **pre-commit hook** | `git commit` (hook kuruluysa) | Stage'deki `version` > HEAD'teki `version` |
|
|
1920
|
-
| **`xcore tag`** | Tag + push öncesi | Commit'teki `version` > son git tag |
|
|
365
|
+
```typescript
|
|
366
|
+
import express from 'express'
|
|
367
|
+
import coreLoader from '@xrystal/core'
|
|
368
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
1921
369
|
|
|
1922
|
-
|
|
370
|
+
await coreLoader({})
|
|
371
|
+
const app = express()
|
|
372
|
+
app.use(dtoMiddleware('express'))
|
|
373
|
+
app.get('/users', userCtrl.list)
|
|
374
|
+
app.listen(3000)
|
|
375
|
+
```
|
|
1923
376
|
|
|
1924
|
-
|
|
1925
|
-
# 1. Bump package.json version (e.g. 3.35.0 → 3.35.1)
|
|
1926
|
-
git add package.json
|
|
1927
|
-
git commit -m "chore: release 3.35.1" # hook blocks same/lower version
|
|
377
|
+
**Elysia**
|
|
1928
378
|
|
|
1929
|
-
|
|
379
|
+
```yaml
|
|
380
|
+
configs:
|
|
381
|
+
service:
|
|
382
|
+
framework: elysia
|
|
1930
383
|
```
|
|
1931
384
|
|
|
1932
|
-
|
|
1933
|
-
|
|
1934
|
-
|
|
1935
|
-
|
|
1936
|
-
git add package.json
|
|
1937
|
-
git commit -m "chore: release 3.35.1" # hook aynı/düşük version'u reddeder
|
|
385
|
+
```typescript
|
|
386
|
+
import { Elysia } from 'elysia'
|
|
387
|
+
import coreLoader from '@xrystal/core'
|
|
388
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
1938
389
|
|
|
1939
|
-
|
|
390
|
+
await coreLoader({})
|
|
391
|
+
new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
|
|
1940
392
|
```
|
|
1941
393
|
|
|
1942
|
-
|
|
1943
|
-
|
|
1944
|
-
|
|
1945
|
-
|
|
1946
|
-
|
|
394
|
+
| Framework | Middleware | EN | TR |
|
|
395
|
+
|-----------|------------|----|----|
|
|
396
|
+
| express | `dtoMiddleware('express')` | Default Express stack | Express stack |
|
|
397
|
+
| elysia | `dtoMiddleware()` | Default Elysia stack | Elysia stack |
|
|
398
|
+
| node | `dtoMiddleware('node')` | Raw `createServer` | Ham HTTP |
|
|
399
|
+
| fetch | none | `ctr()` attaches builder per request | Request başına builder |
|
|
1947
400
|
|
|
401
|
+
**EN:** Realtime (ws / socket.io) is separate from HTTP — full guide at the end: [Realtime](#realtime--websocket--socketio).
|
|
1948
402
|
|
|
403
|
+
**TR:** Realtime (ws / socket.io) HTTP'den ayrı — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
|
|
1949
404
|
|
|
1950
405
|
---
|
|
1951
406
|
|
|
1952
|
-
|
|
407
|
+
## DI & tmp.yml
|
|
1953
408
|
|
|
1954
|
-
|
|
409
|
+
**EN:** Single source of truth: **`x/tmp.yml`** at project root. Loaders read a live snapshot, not the file directly.
|
|
1955
410
|
|
|
1956
|
-
|
|
1957
|
-
|------|--------|
|
|
1958
|
-
| **CLI (tool)** | Çalışan `xcore` binary’sinin `@xrystal/core` sürümü |
|
|
1959
|
-
| **Project (service)** | `api-gateway-svc@1.x` — servisin kendi `package.json` `version` |
|
|
1960
|
-
| **node_modules** | Kurulu `@xrystal/core` — CLI ile eşleşiyor mu |
|
|
1961
|
-
| **Toolchain** | `defaults.json` → önerilen `outDir` / `include` / eslint — `tsconfig.json` uyumu |
|
|
411
|
+
**TR:** Tek kaynak: proje kökündeki **`x/tmp.yml`**. Loader'lar dosyayı değil canlı snapshot'ı okur.
|
|
1962
412
|
|
|
1963
|
-
|
|
413
|
+
| Step / Adım | EN | TR |
|
|
414
|
+
|-------------|----|----|
|
|
415
|
+
| 1 | `await coreLoader({})` at boot — Awilix DI (System, Logger, Dto, Controller, …) | Boot'ta `coreLoader` — Awilix DI |
|
|
416
|
+
| 2 | Edit `tmp.yml` → loaders auto-sync (log level, i18n, dto, …) | `tmp.yml` değişince loader'lar sync |
|
|
417
|
+
| 3 | Read config at runtime: `getRuntimeTmpConfigs()` or DI `System` | Runtime config: `getRuntimeTmpConfigs()` veya `System` |
|
|
1964
418
|
|
|
1965
|
-
|
|
419
|
+
```typescript
|
|
420
|
+
import coreLoader from '@xrystal/core'
|
|
421
|
+
import { getRuntimeTmpConfigs } from '@xrystal/core/utils'
|
|
1966
422
|
|
|
1967
|
-
|
|
423
|
+
await coreLoader({})
|
|
424
|
+
const tmp = getRuntimeTmpConfigs()
|
|
425
|
+
```
|
|
1968
426
|
|
|
1969
|
-
**
|
|
427
|
+
**EN:** `loaders.*` in `tmp.yml` enables subsystems (logger, localization, dto, system/gStore, …).
|
|
1970
428
|
|
|
1971
|
-
|
|
1972
|
-
|--------|-----------------|----------|
|
|
1973
|
-
| `import '@xrystal/core'` | Hayır (Node) | Lib runtime |
|
|
1974
|
-
| `xcore dev` / `build` | Evet (CLI) | Proje geliştirme |
|
|
1975
|
-
| Docker prod `node x/dist/index.js` | Hayır | Servis prod |
|
|
429
|
+
**TR:** `tmp.yml` içindeki `loaders.*` hangi alt sistemlerin açılacağını belirler.
|
|
1976
430
|
|
|
1977
431
|
---
|
|
1978
432
|
|
|
1979
|
-
|
|
433
|
+
## i18n / locale
|
|
1980
434
|
|
|
1981
|
-
**
|
|
435
|
+
**EN:** i18next via `loaders.localization` in `tmp.yml`. Use `@key` in responses or `req.t()`.
|
|
1982
436
|
|
|
1983
|
-
|
|
437
|
+
**TR:** `loaders.localization` ile i18next. Cevaplarda `@anahtar` veya `req.t()` kullan.
|
|
1984
438
|
|
|
1985
439
|
```yaml
|
|
1986
|
-
|
|
1987
|
-
|
|
1988
|
-
|
|
1989
|
-
|
|
1990
|
-
folderPath: ./src
|
|
1991
|
-
paths:
|
|
1992
|
-
dist: dist
|
|
440
|
+
loaders:
|
|
441
|
+
localization:
|
|
442
|
+
fallbackLang: en
|
|
443
|
+
preloadLangs: [en, tr]
|
|
1993
444
|
```
|
|
1994
445
|
|
|
1995
|
-
```
|
|
1996
|
-
|
|
1997
|
-
|
|
446
|
+
```typescript
|
|
447
|
+
return { message: '@successfully user' }
|
|
448
|
+
// or / veya req.t('responseMessage.successfully')
|
|
1998
449
|
```
|
|
1999
450
|
|
|
2000
|
-
|
|
2001
|
-
|-------|-------------------|-----|
|
|
2002
|
-
| `tmp.yml` | **Evet — tek kaynak** | `service.paths.root`, `service.paths.source`, `service.paths.*` |
|
|
2003
|
-
| `tsconfig.base.json` | Hayır | `strict`, `module`, `target` (npm export) |
|
|
2004
|
-
| `tsconfig.json` | Sync ile | `include`, `outDir`, `paths` — elle yazma |
|
|
2005
|
-
| `eslint.config.js` | tmp'den okur | `createEslintConfigFromProject(cwd)` |
|
|
2006
|
-
|
|
2007
|
-
**Servis eslint.config.js:**
|
|
451
|
+
**EN:** Express — mount i18next middleware **before** `dtoMiddleware`.
|
|
2008
452
|
|
|
2009
|
-
|
|
2010
|
-
import tseslint from 'typescript-eslint'
|
|
2011
|
-
import { createEslintConfigFromProject } from '@xrystal/core/x/bin/helpers/toolchain-config.mjs'
|
|
453
|
+
**TR:** Express — i18next middleware'i `dtoMiddleware`'den **önce** tak.
|
|
2012
454
|
|
|
2013
|
-
|
|
455
|
+
```typescript
|
|
456
|
+
app.use(i18nextMiddleware.handle(i18n))
|
|
457
|
+
app.use(dtoMiddleware('express'))
|
|
2014
458
|
```
|
|
2015
459
|
|
|
2016
|
-
|
|
460
|
+
**EN:** Client sends `Accept-Language: tr` → Turkish message.
|
|
2017
461
|
|
|
2018
|
-
|
|
462
|
+
**TR:** Client `Accept-Language: tr` gönderir → Türkçe mesaj döner.
|
|
2019
463
|
|
|
2020
|
-
|
|
464
|
+
---
|
|
2021
465
|
|
|
2022
|
-
|
|
2023
|
-
|---------------------|------------------------------|
|
|
2024
|
-
| `service.paths.root` (`x` → `infra`) | **Evet** |
|
|
2025
|
-
| `service.paths.source` (`./source` → `./src`) | **Evet** |
|
|
2026
|
-
| `service.paths.dist` / `service.paths.tests` | **Evet** |
|
|
2027
|
-
| `loaders`, `logLevel`, `protocols` | **Hayır** — runtime watch yeterli |
|
|
466
|
+
## G store
|
|
2028
467
|
|
|
2029
|
-
**
|
|
2030
|
-
**Ne yapmaz:** eslint dosyasını yazmaz — eslint her `lint`/`dev` öncesi tmp'yi okur. `bunfig.toml` satırını **çıktıda gösterir**, sen eklersin.
|
|
468
|
+
**EN:** App-wide shared state (Zustand). Bootstrapped from `tmp.yml` → `loaders.system.gStore.vars`.
|
|
2031
469
|
|
|
2032
|
-
**
|
|
470
|
+
**TR:** Uygulama genelinde paylaşılan state (Zustand). Boot'ta `tmp.yml` → `gStore.vars`.
|
|
2033
471
|
|
|
2034
|
-
```
|
|
2035
|
-
|
|
2036
|
-
|
|
2037
|
-
|
|
2038
|
-
|
|
2039
|
-
|
|
2040
|
-
# 4) bunfig.toml — sync'in yazdığı alias satırını ekle
|
|
472
|
+
```yaml
|
|
473
|
+
loaders:
|
|
474
|
+
system:
|
|
475
|
+
gStore:
|
|
476
|
+
vars:
|
|
477
|
+
maintenance: false
|
|
2041
478
|
```
|
|
2042
479
|
|
|
2043
|
-
|
|
480
|
+
```typescript
|
|
481
|
+
import { G } from '@xrystal/core/utils'
|
|
2044
482
|
|
|
2045
|
-
|
|
2046
|
-
|
|
2047
|
-
"lint": "eslint ."
|
|
2048
|
-
```
|
|
483
|
+
G.get('maintenance')
|
|
484
|
+
G.set('maintenance', true)
|
|
2049
485
|
|
|
2050
|
-
|
|
486
|
+
checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true
|
|
487
|
+
```
|
|
2051
488
|
|
|
2052
|
-
|
|
489
|
+
| Store | Lifetime / Ömür | EN | TR |
|
|
490
|
+
|-------|-----------------|----|----|
|
|
491
|
+
| **G** | App / Uygulama | Global flags, cache, maintenance | Global flag, cache, maintenance |
|
|
492
|
+
| **Controller context** | Request / İstek | `this.req`, `builder` | `this.req`, `builder` |
|
|
493
|
+
| **Run context** | Request or job / İstek veya job | `requestId`, log trace | `requestId`, log trace |
|
|
2053
494
|
|
|
2054
495
|
---
|
|
2055
496
|
|
|
2056
|
-
|
|
497
|
+
## DTO responses / DTO cevapları
|
|
2057
498
|
|
|
2058
|
-
**EN:**
|
|
499
|
+
**EN:** Standard `{ success, message, data, … }` via `@xrystal/dto`. `dtoMiddleware()` attaches builder; `ctr()` dispatches the result.
|
|
2059
500
|
|
|
2060
|
-
**TR:** `@xrystal/
|
|
2061
|
-
|
|
2062
|
-
```yaml
|
|
2063
|
-
# configs = proje ayarları (servis tek kaynak)
|
|
2064
|
-
configs:
|
|
2065
|
-
file:
|
|
2066
|
-
rootFolderPath: x # serviste infra, config, … olabilir
|
|
501
|
+
**TR:** `@xrystal/dto` ile standart `{ success, message, data, … }`. `dtoMiddleware()` builder takar; `ctr()` sonucu dispatch eder.
|
|
2067
502
|
|
|
2068
|
-
|
|
2069
|
-
name: my-api
|
|
2070
|
-
folderPath: ./source
|
|
2071
|
-
paths:
|
|
2072
|
-
tests: tests
|
|
2073
|
-
environments: environments
|
|
2074
|
-
dist: dist
|
|
2075
|
-
build:
|
|
2076
|
-
typecheck: true
|
|
2077
|
-
```
|
|
503
|
+
Details / detay: [`@xrystal/dto`](https://www.npmjs.com/package/@xrystal/dto)
|
|
2078
504
|
|
|
2079
|
-
|
|
505
|
+
---
|
|
2080
506
|
|
|
2081
|
-
|
|
2082
|
-
|------------------------|----|----|
|
|
2083
|
-
| `service.paths.root` | CLI root folder (`xcore test`/`dev`/`build`) | CLI kök klasörü (`xcore test`/`dev`/`build`) |
|
|
2084
|
-
| `core.tmp.fileWatchIntervalMs` | `tmp.yml` watch interval (ms, default `500`) | `tmp.yml` izleme aralığı (ms, default `500`) |
|
|
2085
|
-
| `service.paths.source` | Source tree + `xcore dev` entry | Kaynak klasörü + `xcore dev` girişi |
|
|
2086
|
-
| `service.paths.*` | `tests` / `environments` / `dist` subpaths | `tests` / `environments` / `dist` alt yolları |
|
|
2087
|
-
| `service.loaders`, `service.framework` | Runtime (System, dto, logger, …) | Runtime (System, dto, logger, …) |
|
|
2088
|
-
| `service.build.*` | Build override (`typecheck`, …) — tsconfig is primary | Build override — tsconfig birincil |
|
|
507
|
+
## Usage guide / Kullanım rehberi
|
|
2089
508
|
|
|
2090
|
-
**EN:**
|
|
509
|
+
**EN:** Typical flow when building a service.
|
|
2091
510
|
|
|
2092
|
-
**TR:**
|
|
511
|
+
**TR:** Servis yazarken tipik akış.
|
|
2093
512
|
|
|
2094
513
|
```
|
|
2095
|
-
|
|
2096
|
-
|
|
2097
|
-
|
|
2098
|
-
|
|
2099
|
-
|
|
514
|
+
1. Your repo + bun add @xrystal/core + xcore tmp (or xcore create for greenfield)
|
|
515
|
+
2. tmp.yml → framework, loaders, paths
|
|
516
|
+
3. coreLoader() → once at top of YOUR index.ts
|
|
517
|
+
4. Controller → ctr() per endpoint
|
|
518
|
+
5. Framework → dtoMiddleware + routes
|
|
519
|
+
6. xcore dev → develop
|
|
520
|
+
7. xcore build → start → production
|
|
2100
521
|
```
|
|
2101
522
|
|
|
2102
|
-
|
|
2103
|
-
|------|--------------------------|
|
|
2104
|
-
| **@xrystal/core** | EN: lib unit/integration tests · TR: lib unit/integration testleri |
|
|
2105
|
-
| **Service / Servis** | EN: service tests · TR: servis testleri |
|
|
523
|
+
### Express — end-to-end / uçtan uca
|
|
2106
524
|
|
|
2107
|
-
|
|
525
|
+
```typescript
|
|
526
|
+
// source/index.ts
|
|
527
|
+
import express from 'express'
|
|
528
|
+
import coreLoader from '@xrystal/core'
|
|
529
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
530
|
+
import { userCtrl } from './controllers/user'
|
|
2108
531
|
|
|
2109
|
-
|
|
532
|
+
await coreLoader({})
|
|
2110
533
|
|
|
2111
|
-
|
|
534
|
+
const app = express()
|
|
535
|
+
app.use(dtoMiddleware('express'))
|
|
536
|
+
app.get('/users', userCtrl.list)
|
|
537
|
+
app.listen(3000)
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
### Elysia — end-to-end / uçtan uca
|
|
541
|
+
|
|
542
|
+
```typescript
|
|
543
|
+
// source/index.ts
|
|
544
|
+
import { Elysia } from 'elysia'
|
|
545
|
+
import coreLoader from '@xrystal/core'
|
|
546
|
+
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
547
|
+
import { userCtrl } from './controllers/user'
|
|
548
|
+
|
|
549
|
+
await coreLoader({})
|
|
2112
550
|
|
|
2113
|
-
|
|
551
|
+
new Elysia()
|
|
552
|
+
.use(dtoMiddleware())
|
|
553
|
+
.get('/users', userCtrl.list)
|
|
554
|
+
.listen(3000)
|
|
555
|
+
```
|
|
2114
556
|
|
|
2115
|
-
###
|
|
557
|
+
### DI + locale + G store together / birlikte
|
|
2116
558
|
|
|
2117
559
|
```yaml
|
|
560
|
+
# x/tmp.yml
|
|
2118
561
|
configs:
|
|
2119
|
-
|
|
2120
|
-
|
|
2121
|
-
|
|
2122
|
-
|
|
2123
|
-
|
|
2124
|
-
|
|
2125
|
-
|
|
2126
|
-
|
|
562
|
+
service:
|
|
563
|
+
framework: express
|
|
564
|
+
loaders:
|
|
565
|
+
localization: { fallbackLang: en, preloadLangs: [en, tr] }
|
|
566
|
+
system:
|
|
567
|
+
gStore:
|
|
568
|
+
vars: { maintenance: false }
|
|
569
|
+
dto: { withDefaultHeaders: true }
|
|
570
|
+
loggers: { logLevel: info }
|
|
571
|
+
controller: {}
|
|
2127
572
|
```
|
|
2128
573
|
|
|
2129
|
-
### 2) Controller + ctr (HTTP)
|
|
2130
|
-
|
|
2131
574
|
```typescript
|
|
2132
|
-
import Controller from '@xrystal/core/loader/controller'
|
|
2133
|
-
|
|
2134
575
|
class UserController extends Controller {
|
|
2135
576
|
list = this.ctr({
|
|
2136
|
-
|
|
2137
|
-
|
|
2138
|
-
|
|
2139
|
-
|
|
577
|
+
checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
|
|
578
|
+
logic: async ({ req }) => ({
|
|
579
|
+
data: [],
|
|
580
|
+
message: '@successfully user',
|
|
581
|
+
}),
|
|
2140
582
|
})
|
|
2141
583
|
}
|
|
2142
|
-
|
|
2143
|
-
const userCtrl = new UserController()
|
|
2144
584
|
```
|
|
2145
585
|
|
|
2146
|
-
###
|
|
586
|
+
### Import summary / Import özeti
|
|
2147
587
|
|
|
2148
|
-
|
|
2149
|
-
|
|
2150
|
-
|
|
2151
|
-
|
|
2152
|
-
|
|
2153
|
-
.use(dtoMiddleware())
|
|
2154
|
-
.get('/users', userCtrl.list)
|
|
2155
|
-
.post('/users', userCtrl.create)
|
|
2156
|
-
```
|
|
588
|
+
| What / Ne | Import |
|
|
589
|
+
|-----------|--------|
|
|
590
|
+
| Boot | `import coreLoader from '@xrystal/core'` |
|
|
591
|
+
| Controller base | `import Controller from '@xrystal/core/loader/controller'` |
|
|
592
|
+
| Middleware, G, tmp helpers | `import { … } from '@xrystal/core/utils'` |
|
|
2157
593
|
|
|
2158
|
-
|
|
2159
|
-
|
|
2160
|
-
```typescript
|
|
2161
|
-
import express from 'express'
|
|
2162
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
594
|
+
---
|
|
2163
595
|
|
|
2164
|
-
|
|
2165
|
-
app.use(dtoMiddleware('express'))
|
|
2166
|
-
app.get('/users', userCtrl.list)
|
|
2167
|
-
```
|
|
596
|
+
## Realtime — WebSocket & Socket.IO
|
|
2168
597
|
|
|
2169
|
-
|
|
598
|
+
**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).
|
|
2170
599
|
|
|
2171
|
-
`tmp.yml`
|
|
600
|
+
**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).
|
|
2172
601
|
|
|
2173
|
-
|
|
2174
|
-
import { dtoMiddleware } from '@xrystal/core/utils'
|
|
602
|
+
### HTTP vs realtime / HTTP vs realtime
|
|
2175
603
|
|
|
2176
|
-
|
|
2177
|
-
|
|
2178
|
-
|
|
2179
|
-
|
|
604
|
+
| Axis / Eksen | `tmp.yml` | Middleware | Dispatch |
|
|
605
|
+
|--------------|-----------|------------|----------|
|
|
606
|
+
| **HTTP** | `framework: elysia` | `dtoMiddleware()` | `res.json()` / Elysia set |
|
|
607
|
+
| **WebSocket** | `protocols: [http, ws]` | `realtimeMiddleware()` | `socket.send(JSON)` |
|
|
608
|
+
| **Socket.IO** | `protocols: [http, socketio]` | `realtimeMiddleware('socketio')` | `socket.emit(event, payload)` |
|
|
2180
609
|
|
|
2181
|
-
|
|
610
|
+
**EN:** Same controller class can serve HTTP **and** realtime — different properties, different `protocol` on `ctr()`.
|
|
2182
611
|
|
|
2183
|
-
|
|
612
|
+
**TR:** Aynı controller sınıfı HTTP **ve** realtime verebilir — farklı property, farklı `protocol`.
|
|
2184
613
|
|
|
2185
|
-
|
|
2186
|
-
import http from 'node:http'
|
|
614
|
+
### 3-step pattern / 3 adım kalıbı
|
|
2187
615
|
|
|
2188
|
-
|
|
616
|
+
```
|
|
617
|
+
1. realtimeMiddleware() → socket'a builder tak
|
|
618
|
+
2. ctr({ logic }, { protocol }) → checks + logic + i18n (isteğe bağlı)
|
|
619
|
+
3. dispatch otomatik → ws: send · socketio: emit
|
|
2189
620
|
```
|
|
2190
621
|
|
|
2191
|
-
###
|
|
2192
|
-
|
|
2193
|
-
```typescript
|
|
2194
|
-
app.use(i18nextMiddleware.handle(i18n))
|
|
2195
|
-
app.use(dtoMiddleware())
|
|
622
|
+
### `tmp.yml` — `protocols`
|
|
2196
623
|
|
|
2197
|
-
|
|
2198
|
-
|
|
2199
|
-
|
|
2200
|
-
|
|
2201
|
-
|
|
2202
|
-
})
|
|
624
|
+
```yaml
|
|
625
|
+
configs:
|
|
626
|
+
service:
|
|
627
|
+
framework: elysia # EN: HTTP only · TR: sadece HTTP
|
|
628
|
+
protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
|
|
2203
629
|
```
|
|
2204
630
|
|
|
2205
|
-
|
|
631
|
+
| `protocols` in tmp.yml | `realtimeMiddleware()` |
|
|
632
|
+
|------------------------|-------------------------|
|
|
633
|
+
| `[http, ws]` | `realtimeMiddleware()` → auto **ws** |
|
|
634
|
+
| `[http, socketio]` | `realtimeMiddleware()` → auto **socketio** |
|
|
635
|
+
| `[http, ws, socketio]` | **Must specify:** `realtimeMiddleware('ws')` or `realtimeMiddleware('socketio')` |
|
|
636
|
+
|
|
637
|
+
### Native WebSocket (ws)
|
|
2206
638
|
|
|
2207
639
|
```typescript
|
|
2208
|
-
|
|
2209
|
-
import
|
|
640
|
+
// source/controllers/chat.ts
|
|
641
|
+
import Controller from '@xrystal/core/loader/controller'
|
|
2210
642
|
|
|
2211
643
|
class ChatController extends Controller {
|
|
2212
644
|
onMessage = this.ctr({
|
|
2213
|
-
logic: async ({ req }) => ({
|
|
645
|
+
logic: async ({ req }) => ({
|
|
646
|
+
data: { echo: req.body },
|
|
647
|
+
message: '@successfully',
|
|
648
|
+
}),
|
|
2214
649
|
}, { protocol: 'ws' })
|
|
2215
650
|
}
|
|
2216
|
-
|
|
2217
|
-
const wss = new WebSocketServer({ port: 3001 })
|
|
2218
|
-
wss.on('connection', (socket) => {
|
|
2219
|
-
realtimeMiddleware('ws')(socket, () => {})
|
|
2220
|
-
socket.on('message', chatCtrl.onMessage.with(socket))
|
|
2221
|
-
})
|
|
651
|
+
export const chatCtrl = new ChatController()
|
|
2222
652
|
```
|
|
2223
653
|
|
|
2224
|
-
### 9) Socket.IO — aynı controller, farklı protocol
|
|
2225
|
-
|
|
2226
654
|
```typescript
|
|
2227
|
-
|
|
2228
|
-
import {
|
|
655
|
+
// source/index.ts — Express + ws on same port (example)
|
|
656
|
+
import { WebSocketServer } from 'ws'
|
|
657
|
+
import express from 'express'
|
|
658
|
+
import coreLoader from '@xrystal/core'
|
|
659
|
+
import { dtoMiddleware, realtimeMiddleware } from '@xrystal/core/utils'
|
|
660
|
+
import { chatCtrl } from './controllers/chat'
|
|
2229
661
|
|
|
2230
|
-
|
|
2231
|
-
onMessage = this.ctr({ logic: async () => ({ data: {} }) }, { protocol: 'ws' })
|
|
2232
|
-
onChat = this.ctr({ logic: async () => ({ data: { room: 'lobby' } }) }, { protocol: 'socketio' })
|
|
2233
|
-
}
|
|
662
|
+
await coreLoader({})
|
|
2234
663
|
|
|
2235
|
-
const
|
|
2236
|
-
|
|
2237
|
-
io.on('connection', (socket) => {
|
|
2238
|
-
socket.on('chat', chatCtrl.onChat.with(socket))
|
|
2239
|
-
})
|
|
2240
|
-
```
|
|
664
|
+
const app = express()
|
|
665
|
+
app.use(dtoMiddleware('express'))
|
|
2241
666
|
|
|
2242
|
-
|
|
667
|
+
const server = app.listen(3000)
|
|
668
|
+
const wss = new WebSocketServer({ server })
|
|
2243
669
|
|
|
2244
|
-
|
|
2245
|
-
|
|
2246
|
-
|
|
670
|
+
wss.on('connection', (socket) => {
|
|
671
|
+
realtimeMiddleware()(socket, () => {}) // 1) builder attach
|
|
672
|
+
socket.on('message', chatCtrl.onMessage.with(socket)) // 2) ctr + 3) auto send
|
|
673
|
+
})
|
|
2247
674
|
```
|
|
2248
675
|
|
|
2249
|
-
|
|
2250
|
-
io.use(realtimeMiddleware('socketio'))
|
|
2251
|
-
wss.on('connection', (s) => realtimeMiddleware('ws')(s, () => {}))
|
|
2252
|
-
```
|
|
676
|
+
**EN:** `with(socket)` binds the socket for that event — core calls `socket.send(JSON)` after `ctr()` finishes.
|
|
2253
677
|
|
|
2254
|
-
|
|
678
|
+
**TR:** `with(socket)` socket'ı o event'e bağlar — `ctr()` bitince core `socket.send(JSON)` çağırır.
|
|
2255
679
|
|
|
2256
|
-
|
|
2257
|
-
import { realtimeMiddleware, runAction } from '@xrystal/core/utils'
|
|
680
|
+
### Socket.IO
|
|
2258
681
|
|
|
2259
|
-
|
|
2260
|
-
|
|
2261
|
-
|
|
2262
|
-
|
|
2263
|
-
|
|
2264
|
-
|
|
2265
|
-
})
|
|
2266
|
-
})
|
|
682
|
+
```typescript
|
|
683
|
+
class ChatController extends Controller {
|
|
684
|
+
onChat = this.ctr({
|
|
685
|
+
logic: async () => ({ data: { ok: true }, message: '@successfully' }),
|
|
686
|
+
}, { protocol: 'socketio' })
|
|
687
|
+
}
|
|
2267
688
|
```
|
|
2268
689
|
|
|
2269
|
-
### 12) Cron / queue — trace, protocol yok
|
|
2270
|
-
|
|
2271
690
|
```typescript
|
|
2272
|
-
import {
|
|
691
|
+
import { Server } from 'socket.io'
|
|
692
|
+
import coreLoader from '@xrystal/core'
|
|
693
|
+
import { realtimeMiddleware } from '@xrystal/core/utils'
|
|
694
|
+
import { chatCtrl } from './controllers/chat'
|
|
2273
695
|
|
|
2274
|
-
await
|
|
2275
|
-
logger.log(LoggerLayerEnum.INFO, 'started')
|
|
2276
|
-
}, 'sync-job')
|
|
2277
|
-
```
|
|
696
|
+
await coreLoader({})
|
|
2278
697
|
|
|
2279
|
-
|
|
698
|
+
const io = new Server(3001, { cors: { origin: '*' } })
|
|
2280
699
|
|
|
2281
|
-
|
|
2282
|
-
|
|
2283
|
-
|
|
2284
|
-
|
|
2285
|
-
gStore:
|
|
2286
|
-
options:
|
|
2287
|
-
bootstrap: true
|
|
2288
|
-
autoCreateProps: false
|
|
2289
|
-
vars:
|
|
2290
|
-
test: false
|
|
700
|
+
io.use((socket, next) => realtimeMiddleware('socketio')(socket, next)) // 1) builder
|
|
701
|
+
io.on('connection', (socket) => {
|
|
702
|
+
socket.on('chat', chatCtrl.onChat.with(socket)) // 2+3) ctr → emit
|
|
703
|
+
})
|
|
2291
704
|
```
|
|
2292
705
|
|
|
2293
|
-
|
|
2294
|
-
import { G, GStoreScopeEnum } from '@xrystal/core/utils'
|
|
706
|
+
**EN:** Default emit event comes from Dto config (`socket.event`, default `'response'`). Override in `tmp.yml` → `loaders.dto`.
|
|
2295
707
|
|
|
2296
|
-
|
|
2297
|
-
G.set('test', true) // declared in vars
|
|
2298
|
-
// G.set('runtimeProp', 1) // throws when autoCreateProps: false
|
|
708
|
+
**TR:** Varsayılan emit event'i Dto config'den gelir (`socket.event`, default `'response'`). `tmp.yml` → `loaders.dto` ile override.
|
|
2299
709
|
|
|
2300
|
-
|
|
710
|
+
### Without controller / Controller olmadan
|
|
2301
711
|
|
|
2302
|
-
|
|
2303
|
-
logger.log(LoggerLayerEnum.INFO, 'test', { value, prev })
|
|
2304
|
-
})
|
|
2305
|
-
```
|
|
712
|
+
**EN:** Plain function — use `runAction` when you don't need `checks` / i18n / `this.logger`.
|
|
2306
713
|
|
|
2307
|
-
|
|
714
|
+
**TR:** Düz fonksiyon — `checks` / i18n / `this.logger` gerekmiyorsa `runAction`.
|
|
2308
715
|
|
|
2309
|
-
|
|
716
|
+
```typescript
|
|
717
|
+
import { runAction, getDtoRuntime } from '@xrystal/core/utils'
|
|
2310
718
|
|
|
2311
|
-
|
|
719
|
+
// WebSocket
|
|
720
|
+
socket.on('message', () =>
|
|
721
|
+
runAction({ protocol: 'ws', socket }, async () => {
|
|
722
|
+
return socket.builder.as.ok({ ping: 1 }).build()
|
|
723
|
+
}),
|
|
724
|
+
)
|
|
2312
725
|
|
|
2313
|
-
|
|
2314
|
-
|
|
2315
|
-
|
|
2316
|
-
|
|
2317
|
-
|
|
726
|
+
// Socket.IO
|
|
727
|
+
socket.on('ping', () =>
|
|
728
|
+
runAction({ protocol: 'socketio', socket }, async () => {
|
|
729
|
+
return getDtoRuntime().forSocket(socket).builder.as.ok({ pong: true }).build()
|
|
730
|
+
}),
|
|
731
|
+
)
|
|
2318
732
|
```
|
|
2319
733
|
|
|
2320
|
-
|
|
2321
|
-
**TR:** Hafif unit/integration testleri (çoğu suite’te tam Awilix boot yok). `@/*` alias `bunfig.toml` ile çözülür.
|
|
734
|
+
### ws vs Socket.IO — transport farkı
|
|
2322
735
|
|
|
2323
|
-
|
|
736
|
+
| | WebSocket (ws) | Socket.IO |
|
|
737
|
+
|---|----------------|-----------|
|
|
738
|
+
| Wire / Kablo | `socket.send(JSON string)` | `socket.emit(event, object)` |
|
|
739
|
+
| `ctr()` protocol | `{ protocol: 'ws' }` | `{ protocol: 'socketio' }` |
|
|
740
|
+
| Middleware | `realtimeMiddleware()` or `realtimeMiddleware('ws')` | `realtimeMiddleware('socketio')` |
|
|
741
|
+
| Same `FinalResult` | ✅ same builder | ✅ same builder |
|
|
2324
742
|
|
|
2325
|
-
**
|
|
743
|
+
**EN:** Pick **ws** for native WebSocket clients. Pick **socket.io** when you need rooms, fallback transport, or existing Socket.IO clients.
|
|
2326
744
|
|
|
2327
|
-
|
|
745
|
+
**TR:** Native WebSocket client → **ws**. Room, fallback transport veya mevcut Socket.IO client → **socket.io**.
|
|
2328
746
|
|
|
2329
|
-
|
|
2330
|
-
|
|
2331
|
-
## DTO re-exports
|
|
747
|
+
### Same logic, two protocols / Aynı logic, iki protocol
|
|
2332
748
|
|
|
2333
749
|
```typescript
|
|
2334
|
-
|
|
750
|
+
class ChatController extends Controller {
|
|
751
|
+
onWs = this.ctr({ logic: async () => ({ data: { via: 'ws' } }) }, { protocol: 'ws' })
|
|
752
|
+
onSio = this.ctr({ logic: async () => ({ data: { via: 'socketio' } }) }, { protocol: 'socketio' })
|
|
753
|
+
}
|
|
2335
754
|
```
|
|
2336
755
|
|
|
2337
|
-
Same types as `@xrystal/dto` — use for logs, queues, standalone responses outside controllers.
|
|
2338
|
-
|
|
2339
756
|
---
|
|
2340
757
|
|
|
2341
|
-
##
|
|
758
|
+
## Maintainer note / Geliştirici notu
|
|
2342
759
|
|
|
2343
|
-
|
|
2344
|
-
{
|
|
2345
|
-
service,
|
|
2346
|
-
level,
|
|
2347
|
-
message,
|
|
2348
|
-
payload?,
|
|
2349
|
-
code?,
|
|
2350
|
-
timestamp,
|
|
2351
|
-
id,
|
|
2352
|
-
env
|
|
2353
|
-
}
|
|
2354
|
-
```
|
|
760
|
+
**EN:** This repo is the `@xrystal/core` source. npm publish and build pipeline live in repo scripts (`release:prepare`, `x/bin/scripts/`) — not needed for library consumers.
|
|
2355
761
|
|
|
2356
|
-
|
|
762
|
+
**TR:** Bu repo `@xrystal/core` kaynak kodudur. npm publish ve build pipeline repo script'lerinde — kütüphane tüketicisi için gerekli değildir.
|