docs(validation): add validation middleware pages

- Add advanced patterns, define schema, and overview pages
- Add reading validated data and validator middleware pages
- Document the same pages in Indonesian

Author: NeaByteLab

docs/id/middleware/validation/advanced-patterns.md

@@ -0,0 +1,196 @@
+---
+description: "Pilih validator yang tepat per request saat satu prefix menampung beberapa method, pola selectValidator."
+---
+
+# Pola Lanjutan
+
+Validator prefix berjalan untuk setiap method dan setiap path bersarang di bawah prefix itu. Itu baik saat satu schema cocok untuk seluruh prefix, tetapi sebuah resource nyata sering mencampur beberapa bentuk di bawah satu path. Halaman ini membahas pola yang memilih schema yang tepat per request.
+
+## Validator Berjalan Sebelum Routing
+
+Middleware berjalan sebelum router mencocokkan method atau path, jadi validator prefix menyala pada setiap request yang disentuh prefix, bahkan yang tidak dilayani handler mana pun. Sebuah validator di `/accounts` berjalan untuk `POST /accounts` dan untuk `GET /accounts/anything`, keduanya sebelum router memutuskan tidak ada rute seperti itu.
+
+Saat validator itu gagal, 422-nya mencapai client lebih dulu dan menyembunyikan status yang akan diproduksi router:
+
+- `POST /accounts` dengan header yang hilang mengembalikan **422**, bukan **405** yang akan diberikan handler POST yang tidak ada.
+- `GET /accounts/missing` dengan header yang hilang mengembalikan **422**, bukan **404** untuk path tak dikenal.
+
+Membatasi validator berdasarkan method dan path menjaga validasi pada request yang menjadi haknya dan membiarkan router menjawab sisanya. Dengan batas yang tepat, `POST /transfers/tx_abc123` mengembalikan **405** yang bersih alih-alih 422 validasi body, karena validator melewati request yang memang bukan tugasnya.
+
+## Satu Prefix, Beberapa Bentuk
+
+`router.use('/transfers', ...)` mencocokkan `/transfers` dan setiap path yang berlanjut dengan garis miring, seperti `/transfers/tx_abc123`. Aturan pencocokan berasal dari [Middleware Spesifik Rute](/id/middleware/route-specific). Sebuah resource `transfers` biasanya membawa dua request berbeda di bawah satu prefix itu:
+
+- `POST /transfers` mengirim body JSON yang butuh kontrak `json`.
+- `GET /transfers/:id` tidak membawa body dan memvalidasi param-nya di dalam handler.
+
+Mendaftarkan validator `json` pada seluruh prefix akan menjalankannya pada GET juga, dan membaca body yang tidak ada mengubah request valid menjadi kegagalan. Validator perlu menyala hanya untuk POST.
+
+## Helper selectValidator
+
+Sebuah pembungkus kecil menyelesaikannya. Helper ini menerima sebuah pemilih yang mengembalikan schema untuk request saat ini atau `undefined` untuk melewati, membangun validator sesuai kebutuhan, dan menyimpannya di cache agar setiap schema dibungkus sekali:
+
+![Pola selectValidator: sebuah request pada prefix bersama mencapai pemilih yang membaca method dan pathname, mengembalikan schema membangun dan men-cache validator sekali sebelum handler, dan mengembalikan undefined memanggil next sehingga request mengalir lewat tanpa disentuh](/diagrams/validation-select-validator.png)
+
+```typescript twoslash
+import { type Context, type MiddlewareFn, Mware, type ValidationSchema } from '@neabyte/deserve'
+
+// Pilih sebuah schema atau lewati validasi
+function selectValidator(pick: (ctx: Context) => ValidationSchema | undefined): MiddlewareFn {
+  const cache = new Map<ValidationSchema, MiddlewareFn>()
+  return async (ctx: Context, next) => {
+    const schema = pick(ctx)
+    if (schema === undefined) {
+      return await next()
+    }
+    let validator = cache.get(schema)
+    if (validator === undefined) {
+      // Bangun sekali, pakai ulang nanti
+      validator = Mware.validator(schema)
+      cache.set(schema, validator)
+    }
+    return await validator(ctx, next)
+  }
+}
+```
+
+Mengembalikan `undefined` langsung memanggil `next`, jadi request mengalir lewat tanpa disentuh. Mengembalikan sebuah schema menjalankan [Middleware Validator](/id/middleware/validation/validator-middleware) yang cocok sebelum handler.
+
+## Menghubungkan Ke Sebuah Prefix
+
+Pemilih membaca `ctx.pathname` dan method request untuk memutuskan. Di sini kontrak `json` berjalan hanya untuk POST koleksi, dan GET diteruskan untuk memvalidasi param-nya di handler:
+
+```typescript twoslash
+import { type Context, type MiddlewareFn, Define, Mware, Router, type ValidationSchema } from '@neabyte/deserve'
+
+declare function selectValidator(pick: (ctx: Context) => ValidationSchema | undefined): MiddlewareFn
+
+const router = new Router({ routesDir: './routes' })
+
+const createTransfer = {
+  json: Define((body: { amount: number }) => ({ amount: body.amount }))
+}
+// ---cut---
+// Validasi body hanya pada POST koleksi
+router.use(
+  '/transfers',
+  selectValidator((ctx) =>
+    ctx.pathname === '/transfers' && ctx.request.method === 'POST'
+      ? createTransfer
+      : undefined
+  )
+)
+```
+
+Handler `GET /transfers/:id` lalu memvalidasi param-nya sendiri dengan `Validator.check`, pendekatan dari [Membaca Data Tervalidasi](/id/middleware/validation/reading-data#memeriksa-params-di-handler). Validasi body dan validasi param tetap terpisah, masing-masing menyala hanya di tempat yang sesuai.
+
+## Memilih Di Antara Beberapa Schema
+
+Pemilih yang sama menangani lebih dari satu cabang saat sebuah prefix menampung banyak method. Setiap cabang mengembalikan schema untuk kasus itu, dan apa pun yang tidak cocok mengembalikan `undefined`:
+
+```typescript twoslash
+import { type Context, type MiddlewareFn, Define, Router, type ValidationSchema } from '@neabyte/deserve'
+
+declare function selectValidator(pick: (ctx: Context) => ValidationSchema | undefined): MiddlewareFn
+
+const router = new Router({ routesDir: './routes' })
+
+const listQuery = { query: Define((q: Record<string, string>) => ({ page: Number(q['page'] ?? '1') })) }
+const createBody = { json: Define((body: { name: string }) => ({ name: body.name.trim() })) }
+// ---cut---
+// Satu pemilih, satu schema per method
+router.use(
+  '/users',
+  selectValidator((ctx) => {
+    const isCollection = ctx.pathname === '/users'
+    if (isCollection && ctx.request.method === 'GET') {
+      return listQuery
+    }
+    if (isCollection && ctx.request.method === 'POST') {
+      return createBody
+    }
+    return undefined
+  })
+)
+```
+
+Ini menjaga satu pendaftaran validator per prefix sementara setiap method mendapat schema persis yang dibutuhkannya.
+
+## Urutan Validasi
+
+Mengetahui apa yang gagal lebih dulu membuat 422 dapat diprediksi. Dua aturan mencakup setiap kasus, satu untuk sumber dan satu untuk guard.
+
+Sebuah schema dengan beberapa sumber memvalidasinya dalam urutan kemunculan key, dan sumber pertama yang gagal menghentikan sisanya. Sebuah schema `{ query, headers, cookies }` dengan query buruk dan header yang hilang hanya melaporkan alasan query, karena `query` datang lebih dulu dan kontrak header tidak pernah berjalan:
+
+![Urutan sumber lintas schema: kontrak query buruk melempar lebih dulu dan hanya melaporkan alasan query, sementara kontrak headers dan cookies yang datang setelahnya dalam urutan key tidak pernah berjalan](/diagrams/validation-source-order.png)
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Sumber divalidasi dalam urutan key
+const listAccounts = {
+  query: Define((q: Record<string, string>) => q),
+  headers: Define((h: Record<string, string>) => h),
+  cookies: Define((c: Record<string, string>) => c)
+}
+```
+
+Di dalam satu sumber, kontrak menentukan seberapa banyak yang dilaporkan. Satu guard yang mendorong ke array alasan memunculkan setiap field rusak sekaligus, sementara daftar guard berhenti pada kegagalan pertama. Pembagian itu datang langsung dari [Define Schema](/id/middleware/validation/define-schema#menyusun-beberapa-guard), jadi sebuah guard bentuk bisa melaporkan semua field yang hilang sementara guard invariant berikutnya hanya berjalan setelah bentuknya terpenuhi.
+
+Hasilnya terbaca rapi. Di antara sumber, kegagalan pertama menang, di dalam satu sumber kontrak memilih satu alasan atau banyak, dan di antara guard, guard pertama yang gagal menang.
+
+## Menyusun Struktur Schema
+
+Kontrak tidak harus berada di samping rute yang memakainya. Saat sebuah proyek tumbuh, folder tersendiri menjaga tiap kontrak tetap kecil dan membiarkan beberapa rute berbagi aturan yang sama. Sebuah tata letak yang berskala biasanya terlihat seperti ini:
+
+```
+schemas/
+  _shared.ts    # helper guard kecil dipakai lintas kontrak
+  transfer.ts   # satu resource, kontraknya
+  account.ts
+  index.ts      # barrel yang mengelompokkan kontrak ke schema
+routes/
+  transfers.ts
+  accounts.ts
+```
+
+Barrel mengelompokkan kontrak tunggal menjadi schema per sumber yang dibaca sebuah rute, jadi perakitannya tetap di satu tempat:
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+declare const Transfer: ReturnType<typeof Define>
+declare const AccountQuery: ReturnType<typeof Define>
+declare const ApiKeyHeader: ReturnType<typeof Define>
+// ---cut---
+// schemas/index.ts kelompokkan kontrak per sumber
+export const createTransferSchema = {
+  json: Transfer
+}
+
+export const listAccountsSchema = {
+  query: AccountQuery,
+  headers: ApiKeyHeader
+}
+```
+
+Sebuah rute mengimpor hanya tipe schema yang dibutuhkannya, sehingga handler tetap fokus pada respons alih-alih aturan:
+
+```typescript twoslash
+import { type Context, Define, Validator } from '@neabyte/deserve'
+const createTransferSchema = { json: Define((body: { amount: number }) => ({ amount: body.amount })) }
+// ---cut---
+// routes/transfers.ts baca body tervalidasi
+export function POST(ctx: Context): Response {
+  const { json } = Validator.read<typeof createTransferSchema>(ctx)
+  return ctx.send.json({ amount: json.amount }, { status: 201 })
+}
+```
+
+Ini sebuah saran, bukan aturan. Aplikasi kecil menyimpan kontrak inline di samping rute, dan yang lebih besar memisahkannya begitu sebuah kontrak layak dipakai ulang.
+
+## Langkah Berikutnya
+
+- [Middleware Validator](/id/middleware/validation/validator-middleware) - pendaftaran per sumber yang dibungkus pola ini.
+- [Membaca Data Tervalidasi](/id/middleware/validation/reading-data) - memvalidasi params di handler di samping pola ini.
+- [Middleware Spesifik Rute](/id/middleware/route-specific) - aturan pencocokan prefix di baliknya.
+- [Ringkasan Validasi](/id/middleware/validation/overview) - bagaimana semua bagian saling terhubung.

docs/id/middleware/validation/define-schema.md

@@ -0,0 +1,159 @@
+---
+description: "Bangun kontrak request dengan Define, sebuah transform yang dipasangkan dengan guard untuk menolak input buruk."
+---
+
+# Define Schema
+
+> **Referensi**: [Repositori GitHub Typebox](https://github.com/NeaByteLab/Typebox)
+
+Sebuah kontrak adalah fungsi yang menerima satu input dan mengembalikan nilai yang sudah bersih. `Define` membangunnya dari dua bagian, sebuah transform yang membentuk output dan guard opsional yang menolak input sebelum transform berjalan.
+
+## Bentuk Define
+
+`Define(transform, guard?)` mengembalikan sebuah kontrak:
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Hanya transform, tanpa guard
+const Trim = Define((body: { name: string }) => ({
+  name: body.name.trim()
+}))
+```
+
+Transform menormalkan nilai, memangkas string, membuat email jadi huruf kecil, atau memaksa angka. Transform berjalan sebagai badan kontrak setelah input dipercaya.
+
+Transform juga memiliki bentuk output. Guard yang lolos tidak membuang key tambahan, jadi field tak dikenal dari client tetap ada kecuali transform menghilangkannya. Mengembalikan object baru hanya dengan field yang diinginkan menjaga input kejutan keluar dari data tervalidasi:
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Output hanya menyimpan field yang disebut
+const NewUser = Define((body: { name: string; role: string }) => ({
+  name: body.name.trim()
+}))
+```
+
+Di sini client yang mengirim `role: 'admin'` mendapati nilainya dibuang, karena transform tidak pernah menyalinnya.
+
+## Urutan Operasi
+
+Memanggil sebuah kontrak menjalankan empat langkah dalam urutan tetap, dan transform hanya pernah melihat input yang sudah lolos setiap guard:
+
+1. Input string yang lebih panjang dari 10000 karakter ditolak sebelum hal lain.
+2. Input object dibekukan dalam (deep frozen) agar guard tidak bisa memutasinya.
+3. Setiap guard berjalan berurutan, melempar pada kegagalan pertama.
+4. Transform berjalan dan mengembalikan nilai yang sudah bersih.
+
+Kontrak tanpa guard langsung lompat ke transform, jadi transform harus memercayai inputnya atau melakukan pemeriksaan sendiri.
+
+![Urutan operasi Define: sebuah kontrak pertama membatasi input string pada 10000 karakter, lalu membekukan dalam sebuah object agar guard tidak bisa memutasinya, lalu menjalankan tiap guard berurutan dengan melempar pada kegagalan pertama, dan baru kemudian menjalankan transform pada input yang sudah lolos setiap guard](/diagrams/validation-contract-order.png)
+
+## Guard Menentukan Lolos Atau Gagal
+
+Sebuah guard memeriksa input mentah dan mengembalikan keputusan:
+
+- `true` saat input lolos.
+- Sebuah `string` untuk satu alasan kegagalan.
+- Sebuah `string[]` untuk beberapa alasan kegagalan sekaligus.
+
+![Keputusan guard: mengembalikan true mengirim input ke transform, sementara mengembalikan sebuah string atau array string membuat kontrak melempar dan menjadi 422 dengan alasan itu terjaga di error.cause](/diagrams/validation-guard-verdict.png)
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Guard menolak nama kosong
+const NewUser = Define(
+  (body: { name: string }) => ({ name: body.name.trim() }),
+  (body) => (body.name.trim().length > 0 ? true : 'name must not be empty')
+)
+```
+
+Guard yang mengembalikan alasan membuat kontrak melempar, dan validator mengubah lemparan itu menjadi 422 yang membawa alasan persis tersebut. Jalur dari sebuah alasan menuju respons ada di [Membaca Data Tervalidasi](/id/middleware/validation/reading-data#cara-kegagalan-muncul).
+
+## Memeriksa Bentuk Lebih Dulu
+
+Sebuah guard menerima input mentah, yang bisa `null`, sebuah array, atau nilai JSON apa pun yang dikirim client. Mengambil sebuah field pada bentuk yang salah akan melempar di dalam guard sebelum aturannya berjalan, jadi pemeriksaan bentuk datang lebih dulu:
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Pastikan object sebelum membaca field
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+const NewUser = Define(
+  (body: { name: string }) => ({ name: body.name.trim() }),
+  (body) => {
+    if (!isRecord(body)) {
+      return 'body must be a JSON object'
+    }
+    return typeof body['name'] === 'string' ? true : 'name must be a string'
+  }
+)
+```
+
+Lemparan di dalam guard tetap menjadi 422, tidak pernah 500, jadi pemeriksaan bentuk yang terlewat gagal dengan aman alih-alih menjatuhkan request.
+
+## Melaporkan Beberapa Field Sekaligus
+
+Mengembalikan sebuah array melaporkan setiap field yang rusak dalam satu respons alih-alih satu per satu:
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Kumpulkan tiap kegagalan ke satu array
+const NewUser = Define(
+  (body: { name: string; age: number }) => body,
+  (body) => {
+    const reasons: string[] = []
+    if (body.name.trim().length === 0) {
+      reasons.push('name must not be empty')
+    }
+    if (body.age < 18) {
+      reasons.push('age must be at least 18')
+    }
+    return reasons.length === 0 ? true : reasons
+  }
+)
+```
+
+## Menyusun Beberapa Guard
+
+Argumen kedua juga menerima array guard. Guard berjalan berurutan dan kontrak melempar pada yang pertama gagal, jadi guard berikutnya tidak pernah melihat input yang sudah ditolak guard sebelumnya:
+
+```typescript twoslash
+import { Define } from '@neabyte/deserve'
+
+// Cek bentuk dulu, aturan bisnis kedua
+function hasFields(body: { from: string; to: string }): true | string {
+  return body.from && body.to ? true : 'from and to are required'
+}
+
+function distinctAccounts(body: { from: string; to: string }): true | string {
+  return body.from !== body.to ? true : 'from and to must differ'
+}
+
+const Transfer = Define(
+  (body: { from: string; to: string }) => body,
+  [hasFields, distinctAccounts]
+)
+```
+
+Memisahkan pemeriksaan bentuk dari aturan bisnis menjaga tiap guard tetap kecil dan membuat aturan lintas-field bisa berasumsi field-nya sudah ada.
+
+## Pengaman Bawaan
+
+Batas string dan pembekuan dari [Urutan Operasi](#urutan-operasi) berjalan otomatis, jadi sebuah kontrak tidak pernah membuang waktu pada payload raksasa dan sebuah guard tidak pernah memutasi nilai yang diperiksanya. Satu aturan lagi menjaga model waktunya:
+
+- Guard async ditolak, karena validasi tetap sinkron dan dapat diprediksi.
+
+Aturan ini berasal dari Typebox sendiri dan berlaku untuk setiap kontrak, baik yang berjalan lewat [Middleware Validator](/id/middleware/validation/validator-middleware) maupun panggilan `Validator.check` langsung.
+
+## Langkah Berikutnya
+
+- [Middleware Validator](/id/middleware/validation/validator-middleware) - menghubungkan kontrak ke sumber request.
+- [Membaca Data Tervalidasi](/id/middleware/validation/reading-data) - membaca output transform di handler.
+- [Pola Lanjutan](/id/middleware/validation/advanced-patterns) - menyusun guard dan mengatur urutan kegagalannya.
+- [Ringkasan Validasi](/id/middleware/validation/overview) - bagaimana semua bagian saling terhubung.