@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.
- package/README.md +2331 -21
- package/package.json +66 -24
- package/tsconfig.base.json +15 -0
- package/x/bin/commands/create.mjs +136 -0
- package/x/bin/commands/doctor.mjs +149 -0
- package/x/bin/commands/hooks.mjs +55 -0
- package/x/bin/commands/project.mjs +126 -0
- package/x/bin/commands/release.mjs +66 -0
- package/x/bin/commands/sync-toolchain.mjs +43 -0
- package/x/bin/commands/tmp.mjs +57 -0
- package/x/bin/constants/index.mjs +6 -0
- package/x/bin/helpers/.generated/.generated-from +1 -0
- package/x/bin/helpers/.generated/tmp-schema.mjs +192 -0
- package/x/bin/helpers/banner.mjs +80 -0
- package/x/bin/helpers/build-config.mjs +342 -0
- package/x/bin/helpers/cli-help.mjs +164 -0
- package/x/bin/helpers/cli-identity.mjs +17 -0
- package/x/bin/helpers/create-target.mjs +35 -0
- package/{bin → x/bin}/helpers/index.mjs +44 -1
- package/x/bin/helpers/project-artifacts.mjs +140 -0
- package/x/bin/helpers/project-root.mjs +70 -0
- package/x/bin/helpers/runtime-info.mjs +172 -0
- package/x/bin/helpers/tmp-config.mjs +67 -0
- package/x/bin/helpers/tmp-layout.mjs +281 -0
- package/x/bin/helpers/tmp-schema.mjs +9 -0
- package/x/bin/helpers/toolchain-config.mjs +233 -0
- package/x/bin/main-cli.js +80 -0
- package/x/bin/paths.mjs +14 -0
- package/x/bin/scripts/clean-source-types.mjs +19 -0
- package/x/bin/scripts/fix-dist-imports.mjs +80 -0
- package/x/bin/scripts/install-git-hooks.mjs +86 -0
- package/x/bin/scripts/minify-dist.mjs +50 -0
- package/x/bin/scripts/prepare-npm-publish.mjs +49 -0
- package/x/bin/scripts/release-prepare.mjs +56 -0
- package/x/bin/scripts/tag.mjs +17 -0
- package/x/bin/scripts/unpublish-leaked-versions.mjs +62 -0
- package/x/bin/scripts/verify-npm-pack.mjs +45 -0
- package/x/bin/scripts/verify-version-bump.mjs +27 -0
- package/x/bin/scripts/version-check.mjs +370 -0
- package/x/dist/index.d.ts +3 -0
- package/x/dist/index.js +1 -0
- package/{source → x/dist}/loader/clients/index.d.ts +2 -1
- package/x/dist/loader/clients/index.js +1 -0
- package/{source → x/dist}/loader/configs/index.d.ts +3 -2
- package/x/dist/loader/configs/index.js +1 -0
- package/x/dist/loader/controller/index.d.ts +69 -0
- package/x/dist/loader/controller/index.js +1 -0
- package/x/dist/loader/dto/index.d.ts +39 -0
- package/x/dist/loader/dto/index.js +1 -0
- package/{source → x/dist}/loader/events/index.d.ts +1 -1
- package/x/dist/loader/events/index.js +1 -0
- package/{source → x/dist}/loader/index.d.ts +2 -1
- package/x/dist/loader/index.js +1 -0
- package/{source → x/dist}/loader/kafka/index.d.ts +6 -3
- package/x/dist/loader/kafka/index.js +1 -0
- package/{source → x/dist}/loader/localizations/index.d.ts +4 -3
- package/x/dist/loader/localizations/index.js +1 -0
- package/{source → x/dist}/loader/logger/index.d.ts +10 -7
- package/x/dist/loader/logger/index.js +2 -0
- package/x/dist/loader/service/index.js +1 -0
- package/{source → x/dist}/loader/system/index.d.ts +4 -3
- package/x/dist/loader/system/index.js +1 -0
- package/{source → x/dist}/project/index.d.ts +2 -2
- package/x/dist/project/index.js +1 -0
- package/x/dist/utils/constants/defaults.json +44 -0
- package/x/dist/utils/constants/index.d.ts +27 -0
- package/x/dist/utils/constants/index.js +1 -0
- package/x/dist/utils/helpers/configs/index.js +1 -0
- package/x/dist/utils/helpers/context/controller-store.d.ts +51 -0
- package/x/dist/utils/helpers/context/controller-store.js +1 -0
- package/x/dist/utils/helpers/context/index.d.ts +18 -0
- package/x/dist/utils/helpers/context/index.js +1 -0
- package/{source → x/dist}/utils/helpers/core/index.d.ts +8 -6
- package/x/dist/utils/helpers/core/index.js +1 -0
- package/x/dist/utils/helpers/core/paths.d.ts +2 -0
- package/x/dist/utils/helpers/core/paths.js +1 -0
- package/x/dist/utils/helpers/core/tmp-layout.d.ts +45 -0
- package/x/dist/utils/helpers/core/tmp-layout.js +1 -0
- package/{source → x/dist}/utils/helpers/date/index.d.ts +1 -1
- package/x/dist/utils/helpers/date/index.js +1 -0
- package/x/dist/utils/helpers/dispatch/index.d.ts +9 -0
- package/x/dist/utils/helpers/dispatch/index.js +1 -0
- package/x/dist/utils/helpers/dto/index.d.ts +10 -0
- package/x/dist/utils/helpers/dto/index.js +1 -0
- package/x/dist/utils/helpers/filters/index.js +1 -0
- package/x/dist/utils/helpers/framework/index.d.ts +3 -0
- package/x/dist/utils/helpers/framework/index.js +1 -0
- package/x/dist/utils/helpers/handlers/adapters.d.ts +10 -0
- package/x/dist/utils/helpers/handlers/adapters.js +1 -0
- package/x/dist/utils/helpers/handlers/execute.d.ts +5 -0
- package/x/dist/utils/helpers/handlers/execute.js +1 -0
- package/x/dist/utils/helpers/handlers/index.d.ts +18 -0
- package/x/dist/utils/helpers/handlers/index.js +1 -0
- package/x/dist/utils/helpers/hash/crypto.js +1 -0
- package/x/dist/utils/helpers/id/index.js +1 -0
- package/x/dist/utils/helpers/index.d.ts +26 -0
- package/x/dist/utils/helpers/index.js +1 -0
- package/x/dist/utils/helpers/ip/index.js +1 -0
- package/x/dist/utils/helpers/is/index.js +1 -0
- package/{source → x/dist}/utils/helpers/locales/index.d.ts +1 -0
- package/x/dist/utils/helpers/locales/index.js +1 -0
- package/x/dist/utils/helpers/math/index.js +1 -0
- package/x/dist/utils/helpers/middleware/index.d.ts +19 -0
- package/x/dist/utils/helpers/middleware/index.js +1 -0
- package/x/dist/utils/helpers/objects/index.js +1 -0
- package/x/dist/utils/helpers/path/index.js +1 -0
- package/x/dist/utils/helpers/protocol/index.d.ts +20 -0
- package/x/dist/utils/helpers/protocol/index.js +1 -0
- package/x/dist/utils/helpers/protocol/options.d.ts +6 -0
- package/x/dist/utils/helpers/protocol/options.js +1 -0
- package/x/dist/utils/helpers/regex/checkSpecialRegexControl.js +1 -0
- package/x/dist/utils/helpers/runtime/dto-access.d.ts +3 -0
- package/x/dist/utils/helpers/runtime/dto-access.js +1 -0
- package/x/dist/utils/helpers/runtime/dto-types.d.ts +19 -0
- package/x/dist/utils/helpers/runtime/dto-types.js +1 -0
- package/x/dist/utils/helpers/runtime/index.d.ts +3 -0
- package/x/dist/utils/helpers/runtime/index.js +1 -0
- package/x/dist/utils/helpers/runtime/shutdown.d.ts +3 -0
- package/x/dist/utils/helpers/runtime/shutdown.js +1 -0
- package/x/dist/utils/helpers/state/index.d.ts +59 -0
- package/x/dist/utils/helpers/state/index.js +1 -0
- package/x/dist/utils/helpers/state/props-from-tmp.d.ts +9 -0
- package/x/dist/utils/helpers/state/props-from-tmp.js +1 -0
- package/x/dist/utils/helpers/state/request-key-guard.d.ts +3 -0
- package/x/dist/utils/helpers/state/request-key-guard.js +1 -0
- package/x/dist/utils/helpers/state/scopes.d.ts +21 -0
- package/x/dist/utils/helpers/state/scopes.js +1 -0
- package/x/dist/utils/helpers/string/index.js +1 -0
- package/x/dist/utils/helpers/tests/tmp-schema.test.js +1 -0
- package/{source/utils/models/types/index.js → x/dist/utils/helpers/tests/tmp-watch.test.d.ts} +0 -1
- package/x/dist/utils/helpers/tests/tmp-watch.test.js +1 -0
- package/x/dist/utils/helpers/timer/index.js +1 -0
- package/x/dist/utils/helpers/tmp/index.d.ts +5 -0
- package/x/dist/utils/helpers/tmp/index.js +1 -0
- package/x/dist/utils/helpers/tmp/loader-tmp-sync.d.ts +4 -0
- package/x/dist/utils/helpers/tmp/loader-tmp-sync.js +1 -0
- package/x/dist/utils/helpers/tmp/runtime-tmp.d.ts +9 -0
- package/x/dist/utils/helpers/tmp/runtime-tmp.js +1 -0
- package/x/dist/utils/helpers/tmp/tmp-loader.d.ts +7 -0
- package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -0
- package/x/dist/utils/helpers/tmp/tmp-schema.d.ts +47 -0
- package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -0
- package/x/dist/utils/helpers/tmp/tmp-watch.d.ts +1 -0
- package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -0
- package/x/dist/utils/helpers/validates/index.js +1 -0
- package/x/dist/utils/index.d.ts +3 -0
- package/x/dist/utils/index.js +1 -0
- package/x/dist/utils/models/classes/class.clients.js +1 -0
- package/x/dist/utils/models/classes/class.interfaces.js +1 -0
- package/x/dist/utils/models/classes/class.service-locator.js +1 -0
- package/{source → x/dist}/utils/models/classes/class.tmp-file-loader.d.ts +3 -2
- package/x/dist/utils/models/classes/class.tmp-file-loader.js +1 -0
- package/x/dist/utils/models/classes/class.x.js +1 -0
- package/{source → x/dist}/utils/models/enums/index.d.ts +14 -1
- package/x/dist/utils/models/enums/index.js +1 -0
- package/x/dist/utils/models/index.d.ts +9 -0
- package/x/dist/utils/models/index.js +1 -0
- package/x/dist/utils/models/types/index.d.ts +5 -0
- package/x/dist/utils/models/types/index.js +1 -0
- package/x/dist/utils/package-root.d.ts +2 -0
- package/x/dist/utils/package-root.js +1 -0
- package/x/tmp.yml +48 -17
- package/bin/constants/index.mjs +0 -17
- package/bin/main-cli.js +0 -131
- package/source/index.js +0 -6
- package/source/loader/clients/index.js +0 -18
- package/source/loader/configs/index.js +0 -81
- package/source/loader/controller/index.d.ts +0 -129
- package/source/loader/controller/index.js +0 -327
- package/source/loader/events/index.js +0 -44
- package/source/loader/index.js +0 -10
- package/source/loader/kafka/index.js +0 -122
- package/source/loader/localizations/index.js +0 -40
- package/source/loader/logger/index.js +0 -183
- package/source/loader/service/index.js +0 -7
- package/source/loader/system/index.js +0 -19
- package/source/project/index.js +0 -66
- package/source/utils/constants/index.d.ts +0 -10
- package/source/utils/constants/index.js +0 -11
- package/source/utils/helpers/configs/index.js +0 -1
- package/source/utils/helpers/core/index.js +0 -105
- package/source/utils/helpers/date/index.js +0 -48
- package/source/utils/helpers/filters/index.js +0 -44
- package/source/utils/helpers/hash/crypto.js +0 -22
- package/source/utils/helpers/id/index.js +0 -24
- package/source/utils/helpers/index.d.ts +0 -17
- package/source/utils/helpers/index.js +0 -17
- package/source/utils/helpers/ip/index.js +0 -21
- package/source/utils/helpers/is/index.js +0 -35
- package/source/utils/helpers/locales/index.js +0 -63
- package/source/utils/helpers/math/index.js +0 -14
- package/source/utils/helpers/middlewares/index.d.ts +0 -1
- package/source/utils/helpers/middlewares/index.js +0 -26
- package/source/utils/helpers/objects/index.js +0 -55
- package/source/utils/helpers/path/index.js +0 -4
- package/source/utils/helpers/regex/checkSpecialRegexControl.js +0 -3
- package/source/utils/helpers/string/index.js +0 -9
- package/source/utils/helpers/timer/index.js +0 -5
- package/source/utils/helpers/validates/index.js +0 -20
- package/source/utils/index.d.ts +0 -3
- package/source/utils/index.js +0 -3
- package/source/utils/models/classes/class.clients.js +0 -142
- package/source/utils/models/classes/class.dtos.d.ts +0 -47
- package/source/utils/models/classes/class.dtos.js +0 -36
- package/source/utils/models/classes/class.interfaces.js +0 -10
- package/source/utils/models/classes/class.response.d.ts +0 -17
- package/source/utils/models/classes/class.response.js +0 -35
- package/source/utils/models/classes/class.service-locator.js +0 -16
- package/source/utils/models/classes/class.tmp-file-loader.js +0 -38
- package/source/utils/models/classes/class.x.js +0 -179
- package/source/utils/models/enums/index.js +0 -133
- package/source/utils/models/index.d.ts +0 -11
- package/source/utils/models/index.js +0 -11
- package/source/utils/models/types/index.d.ts +0 -3
- /package/{source → x/dist}/loader/service/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/configs/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/filters/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/hash/crypto.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/id/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/ip/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/is/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/math/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/objects/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/path/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/regex/checkSpecialRegexControl.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/string/index.d.ts +0 -0
- /package/{source/index.d.ts → x/dist/utils/helpers/tests/tmp-schema.test.d.ts} +0 -0
- /package/{source → x/dist}/utils/helpers/timer/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/validates/index.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.clients.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.interfaces.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.service-locator.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.x.d.ts +0 -0
package/README.md
CHANGED
|
@@ -1,21 +1,2331 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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.
|