@xrystal/core 3.28.3 → 3.37.3

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