- สเปกที่ออกแบบมาเพื่อให้ไลบรารีสคีมาที่อิงกับ 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 และการอนุมานชนิดข้อมูล
ยังไม่มีความคิดเห็น