@xrystal/core 3.55.78 → 3.55.85

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +33 -913
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,946 +1,66 @@
1
1
  # @xrystal/core
2
2
 
3
- > **EN** — Runtime framework: API services & frontends, workspace CLI, DI loaders, live `tmp.yml`, multi-protocol.
4
- > **TR** — Runtime framework: API & frontend, workspace CLI, DI loader'lar, canlı `tmp.yml`, çoklu protokol.
3
+ > **EN** — Runtime library and `xry` CLI for TypeScript services: DI loaders, live `x/tmp.yml`, `ctr()` controllers, DTO / i18n / trace, HTTP and realtime.
4
+ > **TR** — TypeScript servisleri için runtime kütüphanesi ve `xry` CLI: DI loader'lar, canlı `x/tmp.yml`, `ctr()` controller'lar, DTO / i18n / trace, HTTP ve realtime.
5
5
 
6
- **CLI:** `xry` · **Version:** `3.52.5` · [npm](https://www.npmjs.com/package/@xrystal/core)
6
+ **CLI:** `xry` · [npm](https://www.npmjs.com/package/@xrystal/core)
7
7
 
8
8
  ---
9
9
 
10
- ## Platform services / Platform servisleri
10
+ ## Overview / Genel bakış
11
11
 
12
- **EN:** Consumer microservices in `../services/` — table below is the **pin matrix** (service pkg + `@xrystal/core`; bump rows when you ship). Apply pins with **`xry sync`** (not manual `bun add` per repo).
12
+ **EN:** `@xrystal/core` is an npm package (default export `coreLoader`) plus the **`xry`** CLI. You keep your own repo layout — monorepo, Docker, or a greenfield app from `xry create`. Cluster deploy, image pins, and GitOps are **outside** this package.
13
13
 
14
- **TR:** `../services/` altındaki microservice'ler — tablo **pin matrisi** (servis sürümü + `@xrystal/core`; release sonrası satırları güncelle). Pin uygulama: **`xry sync`** (her repo için elle `bun add` yazma).
15
-
16
- | Repo folder | `tmp.yml` name | Role | Service pkg | `@xrystal/core` |
17
- |-------------|----------------|------|-------------|-----------------|
18
- | `api-core-svc` | `core` | Core domain API | `1.0.24` | `3.52.5` |
19
- | `api-cron-svc` | `crons` | Scheduled jobs / Kafka queue worker | `0.1.25` | `3.52.5` |
20
- | `api-gateway-svc` | `gateway` | Edge gateway, routing, cache, Mongo config | `2.0.49` | `3.52.5` |
21
- | `api-gpt-svc` | `gpt` | GPT / AI features | `1.0.22` | `3.52.5` |
22
- | `api-iam-svc` | `iam` | Identity & access management | `0.7.26` | `3.52.5` |
23
- | `api-log-svc` | `log` | Logging service | `1.0.20` | `3.52.5` |
24
- | `api-websocket-svc` | `websocket` | WebSocket / realtime | `0.8.31` | `3.52.5` |
25
-
26
- **SSL / TLS helpers** (since 3.49.0): import from loader subpaths, not `@xrystal/core/utils`:
27
-
28
- ```ts
29
- import { resolveKafkaJsSsl } from '@xrystal/core/loader/kafka'
30
- import { resolveRedisSocketOptions } from '@xrystal/core/loader/redis'
31
- import { resolveMongoConnectOptions } from '@xrystal/core/loader/mongo'
32
- ```
33
-
34
- **After `@xrystal/core` publish / core yayın sonrası:** workspace root → `xry sync` (all linked `api/*` pins to CLI version). One service → `cd` that repo → `xry sync`. Build/tag images = each service’s own release flow (see monorepo release order in infra).
14
+ **TR:** `@xrystal/core` npm paketi (`coreLoader`) ve **`xry` CLI**. Repo düzeni sende — monorepo, Docker veya `xry create`. Cluster deploy, image pin ve GitOps **bu paketin dışında**.
35
15
 
36
16
  ---
37
17
 
38
- ## What's new in 3.46.0 / 3.46.0'da ne değişti
18
+ ## Features / Özellikler
39
19
 
40
- **EN:** SSOT architecture is closed — identity, runtime tooling, paths, and CLI share one source of truth. Missing values throw; layout drift auto-heals.
41
-
42
- **TR:** SSOT mimarisi kapandı — kimlik, runtime tooling, path ve CLI tek kaynaktan. Eksik değer throw; path drift otomatik heal.
43
-
44
- | Change / Değişiklik | EN | TR |
45
- |---------------------|----|----|
46
- | **Identity** | CLI display = `@xrystal/core`; invoke bin = `xry` | Kimlik paket adı, bin `xry` |
47
- | **defaults.json** | Package name, CLI, brand, `runtimes{}`, `bundlers[]` | Paket kimliği + tooling haritası |
48
- | **tmp.yml** | Layout, `global.runtime`, vars, `build.bundler` | Proje layout + runtime |
49
- | **Live pulse** | tmp watch → loader sync; path drift → tsconfig heal | Canlı sync + otomatik heal |
50
- | **Strict normalize** | Unknown/missing `runtime` / `bundler` throws (empty bundler → `auto`) | Sessiz `?? 'bun'` yok |
51
- | **Tooling map** | Scripts/build/CLI use `defaults.runtimes` (no `bun` / `x/dist` literals) | Hardcode temiz |
52
- | **`xry sync`** | Force / CI only — daily ritual değil | Force / CI |
53
-
54
- ```bash
55
- npx xry sync # force-apply tmp.yml → tsconfig (usually auto)
56
- npx xry sync --dry-run
57
- ```
20
+ | Area / Alan | EN | TR |
21
+ |-------------|----|----|
22
+ | **DI** | Awilix loaders, lifecycle hooks (`onInit`, `onAfterInit`, …) | Awilix loader'lar, yaşam döngüsü hook'ları |
23
+ | **Config** | Live `x/tmp.yml`; `xry sync` heals paths | Canlı `x/tmp.yml`; path düzeltme |
24
+ | **HTTP** | `ctr()` endpoint pipeline; Express / Elysia / raw Node | `ctr()` pipeline; Express / Elysia / Node |
25
+ | **DTO & UX** | `@xrystal/dto`, i18n, request trace, logging | DTO, i18n, trace, log |
26
+ | **Data (optional)** | Redis, MongoDB, Kafka loaders | İsteğe bağlı Redis / Mongo / Kafka |
27
+ | **Realtime** | WebSocket / Socket.IO on the same pattern as HTTP | HTTP ile aynı kalıpta ws / Socket.IO |
28
+ | **CLI** | `xry dev`, `build`, `start`, `test`, `create`, `version`, `tag` | Geliştirme, build, scaffold, sürüm |
58
29
 
59
30
  ---
60
31
 
61
- ## Why / Neden
62
-
63
- **EN:** `@xrystal/core` is a **kernel**, not only a GitHub template. Most teams already have their own repo layout, CI, Docker, or monorepo — they only need the runtime: DI, `tmp.yml`, `ctr()`, DTO, logger, i18n, trace. Use `xry create` if you want a starter; otherwise add the package to **your** project and seed `x/tmp.yml`.
32
+ ## Use cases / Kullanım senaryoları
64
33
 
65
- **TR:** `@xrystal/core` bir **kernel** — sadece GitHub template değil. Çoğu ekipte zaten kendi repo düzeni, CI, Docker veya monorepo vardır; ihtiyaç duyulan şey runtime: DI, `tmp.yml`, `ctr()`, DTO, logger, i18n, trace. Sıfırdan başlıyorsan `xry create`; mevcut projende sadece paketi kur + `xry tmp` yeter.
66
-
67
- ```bash
68
- # EN: existing project — kernel only · TR: mevcut proje — sadece kernel
69
- bun add @xrystal/core
70
- npx xry tmp # seed x/tmp.yml into YOUR layout
71
- # tsconfig paths auto-heal from tmp.yml (xry sync = force / CI)
72
- # wire coreLoader + dtoMiddleware in your entry file
73
- ```
34
+ | Scenario / Senaryo | EN | TR |
35
+ |--------------------|----|----|
36
+ | **Greenfield** | `npx xry create <name> .` → `source/`, `x/tmp.yml`, scripts | Sıfırdan proje iskeleti |
37
+ | **Existing HTTP app** | Add dependency; wire `coreLoader` + your framework adapter | Mevcut Express / Elysia uygulamasına ekleme |
38
+ | **Realtime** | Enable `protocols` in tmp; `ctr({ protocol: 'ws' \| 'socket.io' })` | Aynı DI/config ile websocket veya Socket.IO |
74
39
 
75
40
  ---
76
41
 
77
- ## Quick start / Hızlı başlangıç
78
-
79
- ### Path A — `create` (starter template / başlangıç şablonu)
80
-
81
- **EN:** Optional — clone GitHub template when you have no project yet.
82
-
83
- **TR:** İsteğe bağlı — henüz proje yoksa GitHub template klonla.
42
+ ## Installation / Kurulum
84
43
 
85
44
  ```bash
86
- mkdir my-api && cd my-api
87
- bun init -y
88
45
  bun add @xrystal/core
89
- npx xry create my-api .
90
- ```
91
-
92
- ```bash
93
- bun add elysia # EN: or express · TR: veya express
94
- bun run dev
95
- npx xry doctor # EN: setup check · TR: kurulum kontrolü
96
- ```
97
-
98
- ### Path B — Your project + kernel (most common / en yaygın)
99
-
100
- **EN:** Keep your folder names — only add `tmp.yml`, `coreLoader`, controllers.
101
-
102
- **TR:** Kendi klasör adların kalsın — sadece `tmp.yml`, `coreLoader`, controller ekle.
103
-
104
- ```bash
105
- mkdir my-api && cd my-api
106
- bun init -y
107
- bun add @xrystal/core elysia
108
- npx xry tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa seed'den oluşturur
109
- npx xry doctor # EN: optional health check · TR: isteğe bağlı sağlık kontrolü
110
- ```
111
-
112
- `package.json`:
113
-
114
- ```json
115
- {
116
- "dependencies": {
117
- "@xrystal/core": "^3.46.0",
118
- "elysia": "^1.4.19"
119
- },
120
- "scripts": {
121
- "dev": "xry dev",
122
- "build": "xry build",
123
- "start": "xry start",
124
- "test": "xry test",
125
- "sync": "xry sync",
126
- "doctor": "xry doctor"
127
- }
128
- }
129
- ```
130
-
131
- **EN:** No global `xry` install — runs via `node_modules/.bin` after `bun add @xrystal/core`.
132
-
133
- **TR:** Global `xry` gerekmez — `@xrystal/core` kurulunca `node_modules/.bin` üzerinden çalışır.
134
-
135
- ### Project layout / Proje düzeni
136
-
137
- ```
138
- my-api/
139
- ├── package.json
140
- ├── source/
141
- │ ├── index.ts # EN: dev entry (xry dev) · TR: dev girişi
142
- │ └── controllers/
143
- └── x/
144
- └── tmp.yml # EN: runtime + path SSOT · TR: runtime + path tek kaynak
46
+ # or / veya
47
+ npm install @xrystal/core
145
48
  ```
146
49
 
147
- ### Config sources / Config kaynakları
50
+ **EN:** The `xry` binary is available via `node_modules/.bin` (e.g. `bun xry dev`). Pick a peer HTTP stack: `elysia`, `express`, or raw `node` / `fetch`.
148
51
 
149
- | File / Dosya | Owns / Sahip olduğu |
150
- |--------------|---------------------|
151
- | `defaults.json` (package) | Identity (`@xrystal/core`), CLI bin (`xry`), brand, `runtimes` / `bundlers` tooling |
152
- | `x/tmp.yml` | Service paths, loaders, protocols, `global.runtime`, bundler · layout seed |
153
- | `tsconfig.json` | Compiler language options; path layout auto-heals from `tmp.yml` |
154
-
155
- **EN:** Edit `tmp.yml` for your project. Package defaults stay inside `@xrystal/core` — do not hardcode runtime/bin/path names in app code.
156
-
157
- **TR:** Projede `tmp.yml` düzenle. Paket default'ları `@xrystal/core` içinde kalır — uygulama kodunda runtime/bin/path hardcode etme.
158
-
159
- ### Minimal `x/tmp.yml`
160
-
161
- ```yaml
162
- configs:
163
- global:
164
- runtime: bun # bun | node
165
- service:
166
- name: my-api
167
- framework: elysia # express | elysia | node | fetch
168
- paths:
169
- root: ./x
170
- source: ./source
171
- protocols: [http]
172
- build:
173
- bundler: auto # auto → tsc (recommended) | bun | tsc | esbuild
174
- typecheck: false # optional tsc --noEmit before emit
175
- loaders:
176
- dto: { withDefaultHeaders: true }
177
- loggers: { logLevel: info }
178
- controller: {}
179
- ```
180
-
181
- ### Service build / Servis build
182
-
183
- **EN:** `bundler: auto` → **`tsc`** (full `source/` tree → `x/dist`). Post-steps: `tsc-alias` → `fix-dist-imports` → `clean-dist-tests` (same as core). This keeps `loader/kafka`, relative imports, and `import.meta.url` paths valid in the container.
184
-
185
- **TR:** `bundler: auto` → **`tsc`** (tüm `source/` ağacı `x/dist`'e). Sonrasında `tsc-alias` + import düzeltme — pod'da kafka/loader modülleri kaybolmaz.
186
-
187
- | `build.bundler` | Behavior / Davranış |
188
- |-----------------|---------------------|
189
- | `auto` / `tsc` | Full tree emit via tsconfig `include` (recommended) |
190
- | `bun` | Single entry `source/index.ts`, `--packages external` (not multi-entry) |
191
- | `esbuild` | Single entry bundle; `@/` aliases need tsc or pre-alias |
192
-
193
- **EN:** `@xrystal/core` itself uses a separate **core** build (package exports entries). Your service only builds **your** `source/` — `@xrystal/core` comes from `node_modules`.
194
-
195
- **TR:** `@xrystal/core` paketi kendi core build'ini kullanır. Servis build'i sadece **senin** `source/` klasörünü derler; core `node_modules`'dan gelir.
196
-
197
- ### Path alias `@/` / `@/` path alias
198
-
199
- **EN:** `@/*` maps to your **source folder** (`source/*`), not project root — same as NestJS `@/` → `src/*`, not repo root.
200
-
201
- **TR:** `@/*` proje root'u değil **source klasörünü** gösterir (`source/*`) — NestJS'teki `@/` → `src/*` gibi.
202
-
203
- | Write / Yaz | Means / Anlam |
204
- |-------------|---------------|
205
- | `@/utils/foo` | `source/utils/foo` ✅ |
206
- | `@/source/utils/foo` | legacy — treated as `@/utils/foo` |
207
- | `logs` in tmp `loadPath` | relative to `paths.root` (`x/logs`) |
208
-
209
- **EN:** `loadPath: '@/utils/helpers/configs/index'` resolves to `source/…` in dev and `x/dist/…` in prod when `source/` is absent.
210
-
211
- **TR:** tmp.yml `loadPath` prod'da `source/` yoksa otomatik `x/dist/` fallback kullanır.
212
-
213
- ### First endpoint / İlk endpoint (~5 min)
214
-
215
- ```typescript
216
- // source/controllers/user.ts
217
- import Controller from '@xrystal/core/loader/controller'
218
-
219
- class UserController extends Controller {
220
- list = this.ctr({
221
- logic: async () => ({ data: [{ id: 1 }], message: '@successfully user' }),
222
- })
223
- }
224
- export const userCtrl = new UserController()
225
- ```
226
-
227
- ```typescript
228
- // source/index.ts
229
- import { Elysia } from 'elysia'
230
- import coreLoader from '@xrystal/core'
231
- import { dtoMiddleware } from '@xrystal/core/utils'
232
- import { userCtrl } from './controllers/user'
233
-
234
- await coreLoader({})
235
- new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
236
- ```
237
-
238
- ```bash
239
- bun run dev
240
- # GET http://localhost:3000/users
241
- ```
52
+ **TR:** `xry` binary `node_modules/.bin` üzerinden kullanılır. HTTP stack: `elysia`, `express` veya `node` / `fetch`.
242
53
 
243
54
  ---
244
55
 
245
- ## Daily commands / Günlük komutlar
246
-
247
- | Command / Komut | EN | TR |
248
- |-----------------|----|----|
249
- | `xry create [name] [path]` | Start project from template + `tmp.yml` | Template + `tmp.yml` ile proje başlat |
250
- | `xry project` | **Context**: workspace root, inner service, standalone, or core library | **Bağlam**: workspace / servis / core |
251
- | `xry workspaces` | **Global registry** `~/.xrystal` (not tmp.yml) | Global kayıt defteri |
252
- | `xry create <name> --workspace` | Outer `./tmp.yml` + **api/general** + admin/web | Dış tmp + api/general |
253
- | `xry tmp` | Inner `x/tmp.yml` or outer workspace tmp; **`end.version` = schema (1)** | tmp.yml · şema sürümü |
254
- | `xry sync` | Inner tsconfig + pin `@xrystal/core` + registry (workspace mode) | tsconfig + core pin |
255
- | `xry config sync` | Copy TLS bundle + kubeconfig into `~/.xrystal` (explicit `--tls-from` / `--kubeconfig-from`) | PEM + kubeconfig → `~/.xrystal` |
256
- | `xry config tls` / `xry config kubeconfig` | Pin paths in `~/.xrystal/config.json` | Kalıcı path kaydı |
257
- | `xry tp connect --ns dev` / `xry tp intercept <deploy> --ns dev` | Telepresence connect / local intercept (`dev` = alias, not namespace) | Telepresence bağlan / local intercept |
258
- | `xry workspaces` | List `~/.xrystal` workspaces + linked projects | Kayıtlı workspace listesi |
259
- | `xry dev` | Watch `source/index.ts` + dev env | `source/index.ts` watch + dev env |
260
- | `xry build` | `tsc` full tree → dist (auto default) + alias/fix post-steps | `tsc` ile tüm `source/` → dist |
261
- | `xry start` | Run `x/dist` + prod env | `x/dist` + prod env |
262
- ### Laptop cluster + TLS (`xry config sync`)
263
-
264
- Copy **explicit** sources into `~/.xrystal` — core does not discover infra repos or scan the disk.
265
-
266
- | Output | Purpose |
267
- |--------|---------|
268
- | `~/.xrystal/kubeconfig` | `xry tp connect` (also saved in `config.json`) |
269
- | `~/.xrystal/certificates/` | Private CA + client PEMs (`ca.crt`, `mongodb.pem`, …) |
270
-
271
- ```bash
272
- # First time (paths you choose — ops bundle folder + kubeconfig file)
273
- xry config sync \
274
- --tls-from /path/to/pem-tree-or-flat \
275
- --kubeconfig-from /path/to/cluster.kubeconfig
276
-
277
- # Repeat (uses saved syncTlsFrom / syncKubeconfigFrom in ~/.xrystal/config.json)
278
- xry config sync
279
-
280
- # Or shell profile
281
- export XRY_SYNC_TLS_FROM=/path/to/certs
282
- export XRY_SYNC_KUBECONFIG_FROM=/path/to/kubeconfig
283
- ```
284
-
285
- **TLS source shape:** sync accepts tree or flat input but **stores flat only** under `~/.xrystal/certificates/` (`ca.crt`, `mongodb.pem`, … — same basenames as `/etc/tls/infra`).
286
-
287
- **Intercept:** before `xry dev`, `xry tp rewrite-env` patches `.env.telepresence` in place (only when matching PEM exists in `~/.xrystal/certificates`). When intercept ends (`Ctrl+C`, crash, or exit) or `xry tp stop`, cluster env snapshot is removed and empty scaffold is restored.
288
-
289
- **Unix optional:** `xry config sync --mirror-etc` copies flat PEMs to `/etc/tls/infra` (pod-style paths). Default is **off** — prefer auto path rewrite on dev (below).
290
-
291
- **TR:** PEM + kubeconfig’i senin gösterdiğin dosyalardan `~/.xrystal` altına kopyalar. Otomatik infra araması yok. Tekrar için `config.json` içindeki kaynaklar veya env.
292
-
293
- ### Runtime env (k8s / Docker) — since 3.55.18
294
-
295
- **EN:** `.env.telepresence` (cluster via intercept) is **rewritten in place** for TLS file paths (`/etc/tls/infra/<name>` → `~/.xrystal/certificates/<name>` when that file exists). No second override file. Optional `.env.local`. **Windows:** forward slashes in URIs (`C:/Users/.../.xrystal/certificates/ca.crt`). PEMs flat under `~/.xrystal/certificates` first (`config sync`). Not baked into images; k8s uses Secret `envFrom`.
296
-
297
- **TR:** TLS path rewrite tek dosyada; `tp stop` snapshot’ı siler. PEM’ler düz `~/.xrystal/certificates`.
298
-
299
- ### `x/environments/.env.local` (laptop, gitignore)
300
-
301
- | | |
302
- |---|---|
303
- | **Committed?** | **No** — stays on your machine in the service tree (`.gitignore`). |
304
- | **When loaded?** | Every **`xry dev`** / laptop **`xry start`**: after `.env.telepresence` (later file wins on same key). |
305
- | **Use for** | BM host overrides, new feature flags, local-only vars, anything not in cluster snapshot. |
306
- | **Not for** | Image / k8s — cluster uses Secret; never `COPY` into Dockerfile. |
307
-
308
- `xry tp intercept` scaffolds empty `.env.local` if missing.
309
-
310
- **Infra preflight:** Before Kafka/Redis/Mongo connect, TCP checks from tmp.yml + env. **Default fail-fast** in cluster and plain local dev. **Telepresence intercept** (pod env on laptop, no service-account token): lenient by default + 2s probe — override with `STRICT_INFRA_PREFLIGHT=1`.
311
-
312
- **Docker / Compose:** Image `CMD ["bun", "xry", "start"]` (dev: `xry dev`). Runtime skips `x/environments` when `/.dockerenv` or k8s is detected (optional override: `XRY_RUNTIME=container|docker|k8s`). Compose: `env_file:` on `x/docker/docker-compose*.yml` — not `COPY` env into the image.
313
- | `xry test` | Run `x/tests` | `x/tests` çalıştır |
314
- | `xry doctor` | CLI, runtime, package health | CLI, runtime, paket uyumu |
315
- | `xry tag` | Core → npm publish · service → `v<CalVer>` git tag | Core npm · servis GHCR tag |
316
- | `bun run version:patch` (or `xry version patch`) | Core SemVer patch · service CalVer (+pN) | Core patch · servis CalVer patch |
317
- | `bun run version:minor` | **Core only** (`-xrystal-core`) | **Sadece core** |
318
- | `bun run version:major` | **Core only** (`-xrystal-core`) | **Sadece core** |
319
-
320
- ### Release scripts (general — tek kaynak)
321
-
322
- | Repo | `package.json` scripts | Bump |
323
- |---|---|---|
324
- | **`-xrystal-core`** | `version:patch`, `version:minor`, `version:major`, `tag` | SemVer |
325
- | **`api-*-svc`** (deployed) | `version:patch`, `tag` | CalVer (branch → UTC + `pN`) |
326
- | **`api-gpt-svc`** (template, no cluster deploy) | `version:patch`, `minor`, `major`, `tag` | SemVer **or** CalVer — `version` şekline göre CLI |
327
-
328
- **EN:** Deployed services: patch + tag only. **`api-gpt-svc`** is the full script template (minor/major when `package.json` is SemVer; CalVer repos use patch only in practice).
329
-
330
- **TR:** Canlı servis: `xry version patch` (veya `bun run version:patch`) → commit → `xry tag`. Yeni servis: `api-gpt-svc` `package.json` scripts bloğunu kopyala.
331
-
332
- **GHA (`gha-gitops-pin`):** `make gha-gitops-pin` (infra) → kopyala `.github/workflows/gha-gitops-pin.yml` (`BUILD_ENABLED` / `GITOPS_PIN_ENABLED` ile build-only veya build+pin). `artifact.yml` ve `clean.yml` ayrı bakım workflow'larıdır. **Image sürümü** = **git tag** (`xry version patch` → `xry tag`).
333
-
334
- ---
335
-
336
- ## Platform features / Platform özellikleri
337
-
338
- **EN:** What the kernel gives you — one line each + minimal example.
339
-
340
- **TR:** Kernel'in verdiği yetenekler — tek satır + kısa örnek.
341
-
342
- | Feature / Özellik | EN | TR | Example / Örnek |
343
- |-------------------|----|----|-----------------|
344
- | **Boot / DI** | Awilix loaders: System, Logger, Kafka, Dto, i18n, … | Awilix loader'lar | `await coreLoader({})` |
345
- | **Live `tmp.yml`** | Edit file → loaders re-sync; path changes heal tsconfig | Dosya → loader sync; path → tsconfig heal | `paths.source` rename → tsconfig updates |
346
- | **`ctr()` pipeline** | `checks → logic → response`, no `res.json()` | Endpoint pipeline | `list = this.ctr({ logic: async () => ({ data: [] }) })` |
347
- | **DTO responses** | Standard API shape via `@xrystal/dto` | Standart API cevabı | `return { data: [], message: '@successfully user' }` |
348
- | **Trace** | `requestId` per request/job (ALS) | İstek/job trace id | `req.requestId` · `runWithTrace('job-1', fn)` |
349
- | **i18n** | i18next + 50+ business message keys | Çok dilli mesajlar | `'@successfully user'` · `req.t('responseMessage.successfully')` |
350
- | **G store** | App-wide state from `tmp.yml` vars | Global state | `G.get('maintenance')` · `checks: () => G.get('x') ? fail : true` |
351
- | **Logger** | Winston: console + daily rotate files | Dosya + konsol log | `this.logger.log(LoggerLayerEnum.INFO, 'ok')` |
352
- | **Kafka logs** | Structured logs → Kafka topic | Log → Kafka | `loaders.loggers` + `configs.kafkaLogsTopic` in env |
353
- | **HTTP client** | Retries + circuit breaker + trace header | Dayanıklı outbound HTTP | extend `BaseApiClient` from loader/clients |
354
- | **Scope validate** | OAuth-style `resource:permission` check | Scope doğrulama | `validateScopes({ scopes, resources, permissions })` |
355
- | **Realtime** | Same `ctr()` for ws / socket.io | HTTP + ws aynı kalıp | `ctr({ logic }, { protocol: 'ws' })` — [guide](#realtime--websocket--socketio) |
356
- | **CLI (`xry`)** | create, tmp, sync, dev, build, start, test, doctor | Servis toolchain | `"dev": "xry dev"` · `"sync": "xry sync"` |
357
- | **Shutdown** | Graceful cleanup on SIGTERM | Temiz kapanış | auto via `registerGracefulShutdown()` on boot |
358
-
359
- ```typescript
360
- // EN: minimal kernel boot in ANY entry file · TR: herhangi bir giriş dosyasında
361
- import coreLoader from '@xrystal/core'
362
- import { dtoMiddleware, G, runWithTrace } from '@xrystal/core/utils'
363
- import Controller from '@xrystal/core/loader/controller'
364
-
365
- await coreLoader({})
366
-
367
- class HealthController extends Controller {
368
- check = this.ctr({
369
- checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
370
- logic: async ({ req }) => ({
371
- data: { ok: true, trace: req.requestId },
372
- message: '@successfully',
373
- }),
374
- })
375
- }
376
- export const healthCtrl = new HealthController()
377
-
378
- await runWithTrace('nightly-job', async () => {
379
- // EN: cron/queue jobs get trace too · TR: cron/queue job'ları da trace alır
380
- })
381
- ```
382
-
383
- ---
384
-
385
- ## Framework quickstarts / Framework hızlı başlangıç
386
-
387
- **EN:** Same kernel — swap only `framework` in `tmp.yml` + middleware line.
388
-
389
- **TR:** Aynı kernel — sadece `tmp.yml` → `framework` ve middleware satırı değişir.
390
-
391
- ### Elysia (default)
392
-
393
- ```yaml
394
- # x/tmp.yml
395
- configs:
396
- service:
397
- framework: elysia
398
- paths: { root: ./x, source: ./source }
399
- ```
400
-
401
- ```typescript
402
- import { Elysia } from 'elysia'
403
- import coreLoader from '@xrystal/core'
404
- import { dtoMiddleware } from '@xrystal/core/utils'
405
- import { userCtrl } from './controllers/user'
406
-
407
- await coreLoader({})
408
- new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
409
- ```
410
-
411
- ### Express
412
-
413
- ```yaml
414
- configs:
415
- service:
416
- framework: express
417
- ```
418
-
419
- ```typescript
420
- import express from 'express'
421
- import coreLoader from '@xrystal/core'
422
- import { dtoMiddleware } from '@xrystal/core/utils'
423
- import { userCtrl } from './controllers/user'
424
-
425
- await coreLoader({})
426
- const app = express()
427
- app.use(dtoMiddleware('express'))
428
- app.get('/users', userCtrl.list)
429
- app.listen(3000)
430
- ```
431
-
432
- ### Node (raw http)
433
-
434
- ```yaml
435
- configs:
436
- service:
437
- framework: node
438
- ```
439
-
440
- ```typescript
441
- import http from 'node:http'
442
- import coreLoader from '@xrystal/core'
443
- import { userCtrl } from './controllers/user'
444
-
445
- await coreLoader({})
446
- http.createServer((req, res) => userCtrl.list(req, res)).listen(3000)
447
- ```
448
-
449
- ### Fetch / Bun.serve
450
-
451
- ```yaml
452
- configs:
453
- service:
454
- framework: fetch
455
- ```
456
-
457
- ```typescript
458
- import coreLoader from '@xrystal/core'
459
- import { userCtrl } from './controllers/user'
460
-
461
- await coreLoader({})
462
- Bun.serve({ fetch: (req) => userCtrl.list(req) })
463
- ```
464
-
465
- `fetch` — no global middleware; `ctr()` attaches builder per request.
466
-
467
- **EN:** WebSocket & Socket.IO — full guide at the end: [Realtime](#realtime--websocket--socketio).
468
-
469
- **TR:** WebSocket & Socket.IO — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
470
-
471
- | Framework | `tmp.yml` | Middleware |
472
- |-----------|-----------|------------|
473
- | elysia | `framework: elysia` | `dtoMiddleware()` |
474
- | express | `framework: express` | `dtoMiddleware('express')` |
475
- | node | `framework: node` | `dtoMiddleware('node')` |
476
- | fetch | `framework: fetch` | — (per-request in `ctr`) |
477
-
478
- ---
479
-
480
- ## Reference / Referans
481
-
482
- | Topic / Konu | Section / Bölüm |
483
- |--------------|-----------------|
484
- | Why kernel vs template | [Why](#why--neden) |
485
- | All platform capabilities | [Platform features](#platform-features--platform-özellikleri) |
486
- | Per-framework boot | [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) |
487
- | Controller, `ctr()` | [Controller](#controller) |
488
- | Express / Elysia detail | [Framework](#express--elysia) |
489
- | DI, boot, tmp watch | [DI](#di--tmpyml) |
490
- | Locale / dil | [i18n](#i18n--locale) |
491
- | Global state | [G store](#g-store) |
492
- | WebSocket & Socket.IO | [Realtime](#realtime--websocket--socketio) |
493
- | API response shape | [DTO](#dto-responses--dto-cevapları) |
494
- | End-to-end flow | [Usage guide](#usage-guide--kullanım-rehberi) |
495
-
496
- ---
497
-
498
- ## Controller
499
-
500
- **EN:** One endpoint = one class property + `this.ctr()`. Wire URL → property. No manual `res.json()`.
501
-
502
- **TR:** Bir endpoint = bir property + `this.ctr()`. URL → property bağla. `res.json()` yazmazsın.
503
-
504
- ```typescript
505
- import Controller from '@xrystal/core/loader/controller'
506
-
507
- class UserController extends Controller {
508
- list = this.ctr({
509
- logic: async ({ req }) => {
510
- return { data: [], message: '@successfully user' }
511
- },
512
- })
513
- }
514
- export const userCtrl = new UserController()
515
- ```
516
-
517
- ```typescript
518
- app.use(dtoMiddleware())
519
- app.get('/users', userCtrl.list)
520
- ```
521
-
522
- | In `logic` / Logic içinde | EN | TR |
523
- |---------------------------|----|----|
524
- | `req.body`, `req.query`, `req.params` | Normalized input | Normalize girdi |
525
- | `req.requestId` | Trace id | İzleme id |
526
- | `req.t` | i18n function | Çeviri fonksiyonu |
527
- | `this.logger` | Logger from DI | DI logger |
528
-
529
- ---
530
-
531
- ## Express & Elysia
532
-
533
- **EN:** See [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) for copy-paste per stack. `tmp.yml` → `configs.service.framework` picks the HTTP layer.
534
-
535
- **TR:** Kopyala-yapıştır örnekler için [Framework hızlı başlangıç](#framework-quickstarts--framework-hızlı-başlangıç). `tmp.yml` → `framework` HTTP katmanını seçer.
536
-
537
- **Express**
538
-
539
- ```yaml
540
- configs:
541
- service:
542
- framework: express
543
- ```
544
-
545
- ```typescript
546
- import express from 'express'
547
- import coreLoader from '@xrystal/core'
548
- import { dtoMiddleware } from '@xrystal/core/utils'
549
-
550
- await coreLoader({})
551
- const app = express()
552
- app.use(dtoMiddleware('express'))
553
- app.get('/users', userCtrl.list)
554
- app.listen(3000)
555
- ```
556
-
557
- **Elysia**
558
-
559
- ```yaml
560
- configs:
561
- service:
562
- framework: elysia
563
- ```
564
-
565
- ```typescript
566
- import { Elysia } from 'elysia'
567
- import coreLoader from '@xrystal/core'
568
- import { dtoMiddleware } from '@xrystal/core/utils'
569
-
570
- await coreLoader({})
571
- new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
572
- ```
573
-
574
- | Framework | Middleware | EN | TR |
575
- |-----------|------------|----|----|
576
- | express | `dtoMiddleware('express')` | Default Express stack | Express stack |
577
- | elysia | `dtoMiddleware()` | Default Elysia stack | Elysia stack |
578
- | node | `dtoMiddleware('node')` | Raw `createServer` | Ham HTTP |
579
- | fetch | none | `ctr()` attaches builder per request | Request başına builder |
580
-
581
- **EN:** Realtime (ws / socket.io) is separate from HTTP — full guide at the end: [Realtime](#realtime--websocket--socketio).
582
-
583
- **TR:** Realtime (ws / socket.io) HTTP'den ayrı — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
584
-
585
- ---
586
-
587
- ## DI & tmp.yml
588
-
589
- **EN:** Single source of truth: **`x/tmp.yml`** at project root. Loaders read a live snapshot, not the file directly.
590
-
591
- **TR:** Tek kaynak: proje kökündeki **`x/tmp.yml`**. Loader'lar dosyayı değil canlı snapshot'ı okur.
592
-
593
- | Step / Adım | EN | TR |
594
- |-------------|----|----|
595
- | 1 | `await coreLoader({})` at boot — Awilix DI (System, Logger, Dto, Controller, …) | Boot'ta `coreLoader` — Awilix DI |
596
- | 2 | Edit `tmp.yml` → loaders auto-sync (log level, i18n, dto, …) | `tmp.yml` değişince loader'lar sync |
597
- | 3 | Read config at runtime: `getRuntimeTmpConfigs()` or DI `System` | Runtime config: `getRuntimeTmpConfigs()` veya `System` |
598
-
599
- ```typescript
600
- import coreLoader from '@xrystal/core'
601
- import { getRuntimeTmpConfigs } from '@xrystal/core/utils'
602
-
603
- await coreLoader({})
604
- const tmp = getRuntimeTmpConfigs()
605
- ```
606
-
607
- **EN:** `loaders.*` in `tmp.yml` enables subsystems (logger, localization, dto, system/gStore, …).
608
-
609
- **TR:** `tmp.yml` içindeki `loaders.*` hangi alt sistemlerin açılacağını belirler.
610
-
611
- ---
612
-
613
- ## i18n / locale
614
-
615
- **EN:** i18next via `loaders.localization` in `tmp.yml`. Use `@key` in responses or `req.t()`.
616
-
617
- **TR:** `loaders.localization` ile i18next. Cevaplarda `@anahtar` veya `req.t()` kullan.
618
-
619
- ```yaml
620
- loaders:
621
- localization:
622
- fallbackLang: en
623
- preloadLangs: [en, tr]
624
- ```
625
-
626
- ```typescript
627
- return { message: '@successfully user' }
628
- // or / veya req.t('responseMessage.successfully')
629
- ```
630
-
631
- **EN:** Express — mount i18next middleware **before** `dtoMiddleware`.
632
-
633
- **TR:** Express — i18next middleware'i `dtoMiddleware`'den **önce** tak.
634
-
635
- ```typescript
636
- app.use(i18nextMiddleware.handle(i18n))
637
- app.use(dtoMiddleware('express'))
638
- ```
639
-
640
- **EN:** Client sends `Accept-Language: tr` → Turkish message.
641
-
642
- **TR:** Client `Accept-Language: tr` gönderir → Türkçe mesaj döner.
643
-
644
- ---
645
-
646
- ## G store
647
-
648
- **EN:** App-wide shared state (Zustand). Bootstrapped from `tmp.yml` → `loaders.system.gStore.vars`.
649
-
650
- **TR:** Uygulama genelinde paylaşılan state (Zustand). Boot'ta `tmp.yml` → `gStore.vars`.
651
-
652
- ```yaml
653
- loaders:
654
- system:
655
- gStore:
656
- vars:
657
- maintenance: false
658
- ```
659
-
660
- ```typescript
661
- import { G } from '@xrystal/core/utils'
662
-
663
- G.get('maintenance')
664
- G.set('maintenance', true)
665
-
666
- checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true
667
- ```
668
-
669
- | Store | Lifetime / Ömür | EN | TR |
670
- |-------|-----------------|----|----|
671
- | **G** | App / Uygulama | Global flags, cache, maintenance | Global flag, cache, maintenance |
672
- | **Controller context** | Request / İstek | `this.req`, `builder` | `this.req`, `builder` |
673
- | **Run context** | Request or job / İstek veya job | `requestId`, log trace | `requestId`, log trace |
674
-
675
- ---
676
-
677
- ## DTO responses / DTO cevapları
678
-
679
- **EN:** Standard `{ success, message, data, … }` via `@xrystal/dto`. `dtoMiddleware()` attaches builder; `ctr()` dispatches the result.
680
-
681
- **TR:** `@xrystal/dto` ile standart `{ success, message, data, … }`. `dtoMiddleware()` builder takar; `ctr()` sonucu dispatch eder.
682
-
683
- Details / detay: [`@xrystal/dto`](https://www.npmjs.com/package/@xrystal/dto)
684
-
685
- ---
686
-
687
- ## Usage guide / Kullanım rehberi
688
-
689
- **EN:** Typical flow when building a service.
690
-
691
- **TR:** Servis yazarken tipik akış.
692
-
693
- ```
694
- 1. Your repo + bun add @xrystal/core + xry tmp (or xry create for greenfield)
695
- 2. tmp.yml → framework, runtime, loaders, paths (tsconfig auto-heals)
696
- 3. coreLoader() → once at top of YOUR index.ts
697
- 4. Controller → ctr() per endpoint
698
- 5. Framework → dtoMiddleware + routes
699
- 6. xry dev → develop
700
- 7. xry build → start → production
701
- 8. xry sync → only when you need a force / dry-run / CI pin
702
- ```
703
-
704
- ### Express — end-to-end / uçtan uca
705
-
706
- ```typescript
707
- // source/index.ts
708
- import express from 'express'
709
- import coreLoader from '@xrystal/core'
710
- import { dtoMiddleware } from '@xrystal/core/utils'
711
- import { userCtrl } from './controllers/user'
712
-
713
- await coreLoader({})
714
-
715
- const app = express()
716
- app.use(dtoMiddleware('express'))
717
- app.get('/users', userCtrl.list)
718
- app.listen(3000)
719
- ```
720
-
721
- ### Elysia — end-to-end / uçtan uca
722
-
723
- ```typescript
724
- // source/index.ts
725
- import { Elysia } from 'elysia'
726
- import coreLoader from '@xrystal/core'
727
- import { dtoMiddleware } from '@xrystal/core/utils'
728
- import { userCtrl } from './controllers/user'
729
-
730
- await coreLoader({})
731
-
732
- new Elysia()
733
- .use(dtoMiddleware())
734
- .get('/users', userCtrl.list)
735
- .listen(3000)
736
- ```
737
-
738
- ### DI + locale + G store together / birlikte
739
-
740
- ```yaml
741
- # x/tmp.yml
742
- configs:
743
- service:
744
- framework: express
745
- loaders:
746
- localization: { fallbackLang: en, preloadLangs: [en, tr] }
747
- system:
748
- gStore:
749
- vars: { maintenance: false }
750
- dto: { withDefaultHeaders: true }
751
- loggers: { logLevel: info }
752
- controller: {}
753
- ```
754
-
755
- ```typescript
756
- class UserController extends Controller {
757
- list = this.ctr({
758
- checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
759
- logic: async ({ req }) => ({
760
- data: [],
761
- message: '@successfully user',
762
- }),
763
- })
764
- }
765
- ```
766
-
767
- ### Import summary / Import özeti
768
-
769
- | What / Ne | Import |
770
- |-----------|--------|
771
- | Boot | `import coreLoader from '@xrystal/core'` |
772
- | Controller base | `import Controller from '@xrystal/core/loader/controller'` |
773
- | Middleware, G, tmp helpers | `import { … } from '@xrystal/core/utils'` |
774
-
775
- ---
776
-
777
- ## Realtime — WebSocket & Socket.IO
778
-
779
- **EN:** HTTP framework (`express`, `elysia`, …) and realtime are **separate axes**. Realtime uses `protocol: 'ws'` or `'socketio'` on `ctr()` — not `framework` in `tmp.yml`. Integration tests cover both pipelines (34 tests pass).
780
-
781
- **TR:** HTTP framework (`express`, `elysia`, …) ile realtime **ayrı eksenler**. Realtime `ctr()` üzerinde `protocol: 'ws'` veya `'socketio'` kullanır — `tmp.yml`'deki `framework` değil. Her iki pipeline integration test ile doğrulanır (34 test geçer).
782
-
783
- ### HTTP vs realtime / HTTP vs realtime
784
-
785
- | Axis / Eksen | `tmp.yml` | Middleware | Dispatch |
786
- |--------------|-----------|------------|----------|
787
- | **HTTP** | `framework: elysia` | `dtoMiddleware()` | `res.json()` / Elysia set |
788
- | **WebSocket** | `protocols: [http, ws]` | `realtimeMiddleware()` | `socket.send(JSON)` |
789
- | **Socket.IO** | `protocols: [http, socketio]` | `realtimeMiddleware('socketio')` | `socket.emit(event, payload)` |
790
-
791
- **EN:** Same controller class can serve HTTP **and** realtime — different properties, different `protocol` on `ctr()`.
792
-
793
- **TR:** Aynı controller sınıfı HTTP **ve** realtime verebilir — farklı property, farklı `protocol`.
794
-
795
- ### 3-step pattern / 3 adım kalıbı
796
-
797
- ```
798
- 1. realtimeMiddleware() → socket'a builder tak
799
- 2. ctr({ logic }, { protocol }) → checks + logic + i18n (isteğe bağlı)
800
- 3. dispatch otomatik → ws: send · socketio: emit
801
- ```
802
-
803
- ### `tmp.yml` — `protocols`
804
-
805
- ```yaml
806
- configs:
807
- service:
808
- framework: elysia # EN: HTTP only · TR: sadece HTTP
809
- protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
810
- ```
811
-
812
- | `protocols` in tmp.yml | `realtimeMiddleware()` |
813
- |------------------------|-------------------------|
814
- | `[http, ws]` | `realtimeMiddleware()` → auto **ws** |
815
- | `[http, socketio]` | `realtimeMiddleware()` → auto **socketio** |
816
- | `[http, ws, socketio]` | **Must specify:** `realtimeMiddleware('ws')` or `realtimeMiddleware('socketio')` |
817
-
818
- ### Native WebSocket (ws)
819
-
820
- ```typescript
821
- // source/controllers/chat.ts
822
- import Controller from '@xrystal/core/loader/controller'
823
-
824
- class ChatController extends Controller {
825
- onMessage = this.ctr({
826
- logic: async ({ req }) => ({
827
- data: { echo: req.body },
828
- message: '@successfully',
829
- }),
830
- }, { protocol: 'ws' })
831
- }
832
- export const chatCtrl = new ChatController()
833
- ```
834
-
835
- ```typescript
836
- // source/index.ts — Express + ws on same port (example)
837
- import { WebSocketServer } from 'ws'
838
- import express from 'express'
839
- import coreLoader from '@xrystal/core'
840
- import { dtoMiddleware, realtimeMiddleware } from '@xrystal/core/utils'
841
- import { chatCtrl } from './controllers/chat'
842
-
843
- await coreLoader({})
844
-
845
- const app = express()
846
- app.use(dtoMiddleware('express'))
847
-
848
- const server = app.listen(3000)
849
- const wss = new WebSocketServer({ server })
850
-
851
- wss.on('connection', (socket) => {
852
- realtimeMiddleware()(socket, () => {}) // 1) builder attach
853
- socket.on('message', chatCtrl.onMessage.with(socket)) // 2) ctr + 3) auto send
854
- })
855
- ```
856
-
857
- **EN:** `with(socket)` binds the socket for that event — core calls `socket.send(JSON)` after `ctr()` finishes.
858
-
859
- **TR:** `with(socket)` socket'ı o event'e bağlar — `ctr()` bitince core `socket.send(JSON)` çağırır.
860
-
861
- ### Socket.IO
862
-
863
- ```typescript
864
- class ChatController extends Controller {
865
- onChat = this.ctr({
866
- logic: async () => ({ data: { ok: true }, message: '@successfully' }),
867
- }, { protocol: 'socketio' })
868
- }
869
- ```
870
-
871
- ```typescript
872
- import { Server } from 'socket.io'
873
- import coreLoader from '@xrystal/core'
874
- import { realtimeMiddleware } from '@xrystal/core/utils'
875
- import { chatCtrl } from './controllers/chat'
876
-
877
- await coreLoader({})
878
-
879
- const io = new Server(3001, { cors: { origin: '*' } })
880
-
881
- io.use((socket, next) => realtimeMiddleware('socketio')(socket, next)) // 1) builder
882
- io.on('connection', (socket) => {
883
- socket.on('chat', chatCtrl.onChat.with(socket)) // 2+3) ctr → emit
884
- })
885
- ```
886
-
887
- **EN:** Default emit event comes from Dto config (`socket.event`, default `'response'`). Override in `tmp.yml` → `loaders.dto`.
888
-
889
- **TR:** Varsayılan emit event'i Dto config'den gelir (`socket.event`, default `'response'`). `tmp.yml` → `loaders.dto` ile override.
890
-
891
- ### Without controller / Controller olmadan
892
-
893
- **EN:** Plain function — use `runAction` when you don't need `checks` / i18n / `this.logger`.
894
-
895
- **TR:** Düz fonksiyon — `checks` / i18n / `this.logger` gerekmiyorsa `runAction`.
896
-
897
- ```typescript
898
- import { runAction, getDtoRuntime } from '@xrystal/core/utils'
899
-
900
- // WebSocket
901
- socket.on('message', () =>
902
- runAction({ protocol: 'ws', socket }, async () => {
903
- return socket.builder.as.ok({ ping: 1 }).build()
904
- }),
905
- )
906
-
907
- // Socket.IO
908
- socket.on('ping', () =>
909
- runAction({ protocol: 'socketio', socket }, async () => {
910
- return getDtoRuntime().forSocket(socket).builder.as.ok({ pong: true }).build()
911
- }),
912
- )
913
- ```
914
-
915
- ### ws vs Socket.IO — transport farkı
916
-
917
- | | WebSocket (ws) | Socket.IO |
918
- |---|----------------|-----------|
919
- | Wire / Kablo | `socket.send(JSON string)` | `socket.emit(event, object)` |
920
- | `ctr()` protocol | `{ protocol: 'ws' }` | `{ protocol: 'socketio' }` |
921
- | Middleware | `realtimeMiddleware()` or `realtimeMiddleware('ws')` | `realtimeMiddleware('socketio')` |
922
- | Same `FinalResult` | ✅ same builder | ✅ same builder |
923
-
924
- **EN:** Pick **ws** for native WebSocket clients. Pick **socket.io** when you need rooms, fallback transport, or existing Socket.IO clients.
925
-
926
- **TR:** Native WebSocket client → **ws**. Room, fallback transport veya mevcut Socket.IO client → **socket.io**.
927
-
928
- ### Same logic, two protocols / Aynı logic, iki protocol
929
-
930
- ```typescript
931
- class ChatController extends Controller {
932
- onWs = this.ctr({ logic: async () => ({ data: { via: 'ws' } }) }, { protocol: 'ws' })
933
- onSio = this.ctr({ logic: async () => ({ data: { via: 'socketio' } }) }, { protocol: 'socketio' })
934
- }
935
- ```
936
-
937
- ---
56
+ ## Release (npm) / Yayın (npm)
938
57
 
939
- ## Maintainer note / Geliştirici notu
58
+ **EN:** Ship with `xry tag` (SemVer `v*` git tag). GitHub Actions `publish.yml` builds and publishes to npm using [Trusted Publishers](https://docs.npmjs.com/trusted-publishers) (OIDC). Housekeeping: `artifact.yml` (zip backups) and `clean.yml` (scheduled release pruning).
940
59
 
941
- **EN:** See **Release scripts (general)**. CalVer npm script örneği yalnız **`api-gpt-svc`** template’inde.
60
+ **TR:** `xry tag` ile SemVer `v*` git tag gönder. `publish.yml` npm’e [Trusted Publisher](https://docs.npmjs.com/trusted-publishers) (OIDC) ile yazar. Bakım: `artifact.yml` (zip yedek), `clean.yml` (release temizliği).
942
61
 
62
+ ## Further reading / Ek kaynak
943
63
 
944
- **npm CI (`E401` / invalid token):** GitHub → repo **Settings → Environments → NPM** → secret **`TOKEN`** = [npm Granular Access Token](https://www.npmjs.com/settings/~youruser/tokens) with **Publish** on package `@xrystal/core` (or whole `@xrystal` scope). Classic automation tokens that bypass 2FA are being restricted — prefer **Granular** + **Publish**. After rotate: re-run failed **Publish Core Library NPM** workflow or push empty commit / re-tag. Stage flow: workflow runs `npm stage publish` → approve on npmjs.com (`npm stage list` / Approve with 2FA).
64
+ **EN:** Package API and changelog on [npm](https://www.npmjs.com/package/@xrystal/core). Release notes on the GitHub **Releases** tab for this repository.
945
65
 
946
- **TR:** Yukarıdaki genel tablo. Serviste `version:minor|major` yok — yalnız CalVer patch.
66
+ **TR:** API ve changelog [npm](https://www.npmjs.com/package/@xrystal/core)'de; sürüm notları GitHub **Releases** sayfasında.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "author": "Yusuf Yasir KAYGUSUZ",
3
3
  "name": "@xrystal/core",
4
- "version": "3.55.78",
4
+ "version": "3.55.85",
5
5
  "description": "Runtime framework and CLI for API services, frontends, and multi-repo workspaces",
6
6
  "publishConfig": {
7
7
  "access": "public",