Standard Schema - อินเทอร์เฟซกลางสำหรับ TypeScript Validation

• สเปกที่ออกแบบมาเพื่อให้ไลบรารีสคีมาที่อิงกับ JavaScript/TypeScript สามารถใช้อินเทอร์เฟซร่วมกันได้
• เป้าหมายคือทำให้เครื่องมือต่าง ๆ ใช้งานร่วมกันได้โดยไม่ต้องมีอะแดปเตอร์แยก และสามารถนำตรรกะตรวจสอบชนิดข้อมูลที่ผู้ใช้กำหนดไว้ในแต่ละไลบรารีกลับมาใช้ซ้ำได้
• ออกแบบร่วมกันโดยผู้สร้างไลบรารีหลักอย่าง Zod, Valibot, ArkType เป็นต้น

อินเทอร์เฟซหลัก (StandardSchemaV1)

• ใช้งานสเปกทั้งหมดผ่านพร็อพเพอร์ตีอ็อบเจ็กต์ชื่อ ~standard
• ภายใน ~standard มีพร็อพเพอร์ตีบังคับ เช่น version, vendor, validate, types
• ฟังก์ชัน validate จะคืนค่า value เมื่อสำเร็จ และคืนอาร์เรย์ issues เมื่อไม่สำเร็จ
• พร็อพเพอร์ตี types ช่วยให้ TypeScript อนุมานชนิดข้อมูลขาเข้า (input) และขาออก (output) ของสคีมาได้
• การอัปเดตทั้งหมดจะคงความเข้ากันได้ไว้ ตราบใดที่ไม่ใช่การเปลี่ยนเวอร์ชันหลัก

เป้าหมายของการออกแบบ

• รองรับการตรวจสอบขณะรันไทม์: ส่งต่อข้อมูลข้อผิดพลาดในรูปแบบมาตรฐาน
• รองรับการอนุมานชนิดข้อมูลแบบสแตติก: เปิดเผยข้อมูลชนิดที่ไลบรารีบน TypeScript อนุมานไว้โดยชัดเจน
• ความกระชับ: สามารถเพิ่มเข้าไปในฟังก์ชันเดิมของไลบรารีได้ด้วยโค้ดเพียงไม่กี่บรรทัด
• หลีกเลี่ยงการชนกันของ API: รวมทุกอย่างไว้ในเนมสเปซ ~standard เพียงจุดเดียว เพื่อไม่ให้ชนกับ API เดิม
• คงประสบการณ์นักพัฒนา: ใช้การขึ้นต้นด้วยเครื่องหมายทิลด์ (~standard) เพื่อลดลำดับความสำคัญในการแสดงผลอัตโนมัติ

มีไลบรารีใดบ้างที่รองรับ

• ขณะนี้ Zod, Valibot, ArkType, Arri Schema, TypeMap และอื่น ๆ รองรับ Standard Schema แล้ว
• tRPC, TanStack Form, TanStack Router, Hono Middleware และอื่น ๆ ก็รองรับสคีมาของผู้ใช้ผ่าน Standard Schema เช่นกัน

วิธีนำสเปกไปใช้ในไลบรารีของตนเอง

• คัดลอกอินเทอร์เฟซ StandardSchemaV1 ไปไว้ในไลบรารี แล้วเพิ่มพร็อพเพอร์ตี ~standard
• เชื่อมฟังก์ชัน validate เข้ากับฟังก์ชันตรวจสอบเดิม เพื่อให้คืนค่า { value } เมื่อสำเร็จ และ { issues } เมื่อไม่สำเร็จ
• หากจำเป็นก็รองรับการตรวจสอบแบบอะซิงก์ได้ แต่แนะนำให้ใช้แบบซิงก์

วิธีรับสคีมาที่ผู้ใช้กำหนดผ่าน Standard Schema

• หากต้องการใช้งานโดยตรงโดยไม่พึ่งไลบรารีสคีมา สามารถติดตั้ง @standard-schema/spec หรือคัดลอกอินเทอร์เฟซไปใช้เองได้
• หากเป็นสคีมาที่มีอินเทอร์เฟซมาตรฐาน เช่นฟังก์ชันตัวอย่าง standardValidate ก็สามารถตรวจสอบความถูกต้องได้ด้วยวิธีเดียวกัน ไม่ว่าจะมาจากไลบรารีใด
• หากต้องการอนุญาตเฉพาะการตรวจสอบแบบซิงก์ ก็สามารถตรวจสอบได้ว่าค่าที่ validate คืนมาเป็น Promise หรือไม่ แล้วจัดการข้อยกเว้นตามนั้น

FAQ

• ต้องเพิ่ม dependency @standard-schema/spec หรือไม่?: ไม่จำเป็นต้องเพิ่มเป็น dependency เสมอไป สามารถคัดลอกแล้วใช้งานได้
• เพิ่มเป็น dev dependency อย่างเดียวไม่ได้: เพราะมันเป็นส่วนหนึ่งของ public API ของไลบรารี จึงต้องใช้งานได้จริงในสภาพแวดล้อมที่เผยแพร่
• เหตุผลที่ใช้ทิลด์ (~) หน้า ~standard: ตั้งใจให้แสดงหลังพร็อพเพอร์ตีอื่น ๆ ในการเติมข้อความอัตโนมัติ
• เหตุผลที่ใช้คีย์แบบสตริงแทน Symbol: เพราะคีย์แบบ Symbol ใน TypeScript อาจทำให้เกิดปัญหากับการจัดลำดับใน autocomplete และการอนุมานชนิดข้อมูล