From 7dd79e059b8ac903d59d1f684e37ac28b0b715c3 Mon Sep 17 00:00:00 2001
From: montmorill <montmorill@outlook.com>
Date: Tue, 14 Apr 2026 22:52:48 +0800
Subject: [PATCH 1/4] Adds type safety for schema roles and refines generic
 signatures

Introduces a `Roles` interface to define valid role strings for each schema type, enforcing type safety when setting the `role` meta property. Updates the `Schema` generic to include a `Type` parameter, allowing the `meta.role` to be constrained to the specific roles permitted for that schema type. This prevents invalid role assignments and improves developer experience with better IDE autocompletion and error checking.
---
 packages/core/src/index.ts | 156 +++++++++++++++++++++----------------
 1 file changed, 88 insertions(+), 68 deletions(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index c8d8269..f6fc55b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -38,30 +38,30 @@ declare global {
       prototype: Schema
       resolve: Resolve
       from<X = any>(source?: X): From<X>
-      extend(type: string, resolve: Resolve): void
-      any<T = any>(): Schema<T>
-      never(): Schema<never>
-      const<const T>(value: T): Schema<T>
-      string(): Schema<string>
-      number(): Schema<number>
-      natural(): Schema<number>
-      percent(): Schema<number>
-      boolean(): Schema<boolean>
+      extend(type: keyof Roles, resolve: Resolve): void
+      any<T = any>(): Schema<T, T, 'any'>
+      never(): Schema<never, never, 'never'>
+      const<const T>(value: T): Schema<T, T, 'const'>
+      string(): Schema<string, string, 'string'>
+      number(): Schema<number, number, 'number'>
+      natural(): Schema<number, number, 'number'>
+      percent(): Schema<number, number, 'number'>
+      boolean(): Schema<boolean, boolean, 'boolean'>
       date(): Schema<string | Date, Date>
       regExp(flag?: string): Schema<string | RegExp, RegExp>
       arrayBuffer(): Schema<Binary.Source, ArrayBufferLike>
       arrayBuffer(encoding: 'hex' | 'base64'): Schema<Binary.Source | string, ArrayBufferLike>
-      bitset<K extends string>(bits: Partial<Record<K, number>>): Schema<number | readonly K[], number>
-      function(): Schema<Function, (...args: any[]) => any>
-      is(constructor: string): Schema
-      is<T>(constructor: Constructor<T>): Schema<T>
-      array<X>(inner: X): Schema<TypeS<X>[], TypeT<X>[]>
-      dict<X, Y extends Schema<any, string> = Schema<string>>(inner: X, sKey?: Y): Schema<Dict<TypeS<X>, TypeS<Y>>, Dict<TypeT<X>, TypeT<Y>>>
-      tuple<const X extends readonly any[]>(list: X): Schema<TupleS<X>, TupleT<X>>
-      object<X extends Dict>(dict: X): Schema<ObjectS<X>, ObjectT<X>>
-      union<const X>(list: readonly X[]): Schema<TypeS<X>, TypeT<X>>
-      intersect<const X>(list: readonly X[]): Schema<IntersectS<X>, IntersectT<X>>
-      transform<X, T>(inner: X, callback: (value: TypeS<X>, options: Schemastery.Options) => T, preserve?: boolean): Schema<TypeS<X>, T>
+      bitset<K extends string>(bits: Partial<Record<K, number>>): Schema<number | readonly K[], number, 'bitset'>
+      function(): Schema<Function, (...args: any[]) => any, 'function'>
+      is(constructor: string): Schema<any, any, 'is'>
+      is<T>(constructor: Constructor<T>): Schema<T, T, 'is'>
+      array<X>(inner: X): Schema<TypeS<X>[], TypeT<X>[], 'array'>
+      dict<X, Y extends Schema<any, string> = Schema<string>>(inner: X, sKey?: Y): Schema<Dict<TypeS<X>, TypeS<Y>>, Dict<TypeT<X>, TypeT<Y>>, 'dict'>
+      tuple<const X extends readonly any[]>(list: X): Schema<TupleS<X>, TupleT<X>, 'tuple'>
+      object<X extends Dict>(dict: X): Schema<ObjectS<X>, ObjectT<X>, 'object'>
+      union<const X>(list: readonly X[]): Schema<TypeS<X>, TypeT<X>, 'union'>
+      intersect<const X>(list: readonly X[]): Schema<IntersectS<X>, IntersectT<X>, 'intersect'>
+      transform<X, T>(inner: X, callback: (value: TypeS<X>, options: Schemastery.Options) => T, preserve?: boolean): Schema<TypeS<X>, T, 'transform'>
       lazy<X extends Schema>(callback: () => X): X
       ValidationError: typeof ValidationError
     }
@@ -72,7 +72,27 @@ declare global {
       path?: (keyof any)[]
     }
 
-    export interface Meta<T = any> {
+    export interface Roles {
+      lazy: never
+      any: never
+      never: never
+      const: never
+      string: 'datetime' | 'regexp' | 'textarea'
+      number: 'slider'
+      boolean: never
+      bitset: 'select'
+      function: never
+      is: never
+      array: 'select' | 'checkbox' | 'table'
+      dict: 'table'
+      tuple: never
+      object: never
+      union: 'radio'
+      intersect: never
+      transform: never
+    }
+
+    export interface Meta<T = any, Type extends string = string> {
       default?: T extends {} ? Partial<T> : T
       required?: boolean
       disabled?: boolean
@@ -80,7 +100,7 @@ declare global {
       badges?: { text: string; type: string }[]
       hidden?: boolean
       loose?: boolean
-      role?: string
+      role?: Type extends keyof Roles ? Roles[Type] : never
       extra?: any
       link?: string
       description?: string | Dict<string>
@@ -92,13 +112,13 @@ declare global {
     }
   }
 
-  interface Schemastery<S = any, T = S> {
+  interface Schemastery<S = any, T = S, Type extends string = string> {
     (data?: S | null, options?: Schemastery.Options): T
-    new (data?: S | null, options?: Schemastery.Options): T
+    new(data?: S | null, options?: Schemastery.Options): T
     [kSchema]: true
     uid: number
-    meta: Schemastery.Meta<T>
-    type: string
+    meta: Schemastery.Meta<T, Type>
+    type: Type
     sKey?: Schema
     inner?: Schema
     list?: Schema[]
@@ -112,28 +132,28 @@ declare global {
     preserve?: boolean
     '~standard': StandardSchemaV1.Props // <S, T>
     toString(inline?: boolean): string
-    toJSON(): Schema<S, T>
-    required(value?: boolean): Schema<S, T>
-    hidden(value?: boolean): Schema<S, T>
-    loose(value?: boolean): Schema<S, T>
-    role(text: string, extra?: any): Schema<S, T>
-    link(link: string): Schema<S, T>
-    default(value: T): Schema<S, T>
-    comment(text: string): Schema<S, T>
-    description(text: string): Schema<S, T>
-    disabled(value?: boolean): Schema<S, T>
-    collapse(value?: boolean): Schema<S, T>
-    deprecated(): Schema<S, T>
-    experimental(): Schema<S, T>
-    pattern(regexp: RegExp): Schema<S, T>
-    max(value: number): Schema<S, T>
-    min(value: number): Schema<S, T>
-    step(value: number): Schema<S, T>
-    set(key: string, value: Schema): Schema<S, T>
-    push(value: Schema): Schema<S, T>
+    toJSON(): Schema<S, T, Type>
+    required(value?: boolean): Schema<S, T, Type>
+    hidden(value?: boolean): Schema<S, T, Type>
+    loose(value?: boolean): Schema<S, T, Type>
+    role(role: this['meta']['role'], extra?: any): Schema<S, T, Type>
+    link(link: string): Schema<S, T, Type>
+    default(value: T): Schema<S, T, Type>
+    comment(text: string): Schema<S, T, Type>
+    description(text: string): Schema<S, T, Type>
+    disabled(value?: boolean): Schema<S, T, Type>
+    collapse(value?: boolean): Schema<S, T, Type>
+    deprecated(): Schema<S, T, Type>
+    experimental(): Schema<S, T, Type>
+    pattern(regexp: RegExp): Schema<S, T, Type>
+    max(value: number): Schema<S, T, Type>
+    min(value: number): Schema<S, T, Type>
+    step(value: number): Schema<S, T, Type>
+    set(key: string, value: Schema): Schema<S, T, Type>
+    push(value: Schema): Schema<S, T, Type>
     simplify(value?: any): any
-    i18n(messages: Dict): Schema<S, T>
-    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T>
+    i18n(messages: Dict): Schema<S, T, Type>
+    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T, Type>
   }
 }
 
@@ -173,7 +193,7 @@ Object.defineProperty(ValidationError.prototype, kValidationError, {
   value: true,
 })
 
-type Schema<S = any, T = S> = Schemastery<S, T>
+type Schema<S = any, T = S, Type extends string = string> = Schemastery<S, T, Type>
 
 const Schema = function (options: Schema) {
   const schema = function (data: any, options: Schemastery.Options = {}) {
@@ -198,7 +218,7 @@ const Schema = function (options: Schema) {
     try {
       // eslint-disable-next-line no-new-func
       schema.callback = new Function('return ' + schema.callback)()
-    } catch {}
+    } catch { }
   }
   Object.defineProperty(schema, 'uid', { value: globalThis.__schemastery_index__++ })
   Object.setPrototypeOf(schema, Schema.prototype)
@@ -357,11 +377,11 @@ Schema.prototype.simplify = function simplify(this: Schema, value) {
     return result
   } else if (this.type === 'array' || this.type === 'tuple') {
     const result: any[] = []
-    ;(value as any[]).forEach((value, index) => {
-      const schema = this.type === 'array' ? this.inner : this.list![index]
-      const item = schema ? schema.simplify(value) : value
-      result.push(item)
-    })
+      ; (value as any[]).forEach((value, index) => {
+        const schema = this.type === 'array' ? this.inner : this.list![index]
+        const item = schema ? schema.simplify(value) : value
+        result.push(item)
+      })
     return result
   } else if (this.type === 'intersect') {
     const result: Dict = {}
@@ -374,7 +394,7 @@ Schema.prototype.simplify = function simplify(this: Schema, value) {
       try {
         Schema.resolve(value, schema, {})
         return schema.simplify(value)
-      } catch {}
+      } catch { }
     }
   }
   return value
@@ -384,7 +404,7 @@ Schema.prototype.toString = function toString(inline?: boolean) {
   return formatters[this.type]?.(this, inline) ?? `Schema<${this.type}>`
 }
 
-Schema.prototype.role = function role(role, extra) {
+Schema.prototype.role = function role<This extends Schema>(this: This, role: This['meta']['role'], extra?: any) {
   const schema = Schema(this)
   schema.meta = { ...schema.meta, role, extra }
   return schema
@@ -481,7 +501,7 @@ Schema.date = function date() {
       if (isNaN(+date)) throw new ValidationError(`invalid date "${value}"`, options)
       return date
     }, true),
-  ])
+  ]) as unknown as Schema<string | Date, Date, 'date'>
 }
 
 Schema.regExp = function regExp(flag = '') {
@@ -737,15 +757,15 @@ Schema.extend('transform', (data, { inner, callback, preserve }, options) => {
   const [result, adapted = data] = Schema.resolve(data, inner!, options, true)
   if (preserve) {
     return [callback!(result)]
-  // } else if (isPlainObject(data)) {
-  //   const temp: any = {}
-  //   for (const key in result) {
-  //     if (!(key in data)) continue
-  //     temp[key] = data[key]
-  //     delete data[key]
-  //   }
-  //   Object.assign(data, callback!(temp))
-  //   return [callback!(result)]
+    // } else if (isPlainObject(data)) {
+    //   const temp: any = {}
+    //   for (const key in result) {
+    //     if (!(key in data)) continue
+    //     temp[key] = data[key]
+    //     delete data[key]
+    //   }
+    //   Object.assign(data, callback!(temp))
+    //   return [callback!(result)]
   } else {
     return [callback!(result), callback!(adapted)]
   }
@@ -775,13 +795,13 @@ function defineMethod(name: string, keys: (keyof Schema)[], format: Formatter) {
           }
           case 'callback': {
             const callback = schema.callback = args[index]
-            ;callback['toJSON'] ||= () => callback.toString()
+              ; callback['toJSON'] ||= () => callback.toString()
             break
           }
           case 'constructor': {
             const constructor = schema.constructor = args[index]
             if (typeof constructor === 'function') {
-              ;constructor['toJSON'] ||= () => constructor['name']
+              ; constructor['toJSON'] ||= () => constructor['name']
             }
             break
           }

From 27ae8ba52a9cadab8d6ed251a23b692767551c94 Mon Sep 17 00:00:00 2001
From: montmorill <montmorill@outlook.com>
Date: Tue, 14 Apr 2026 23:00:44 +0800
Subject: [PATCH 2/4] Fix indentation in transform schema extension

Corrects inconsistent indentation in commented-out code block to maintain consistent formatting throughout the file.
---
 packages/core/src/index.ts | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index f6fc55b..e1919ec 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -757,15 +757,15 @@ Schema.extend('transform', (data, { inner, callback, preserve }, options) => {
   const [result, adapted = data] = Schema.resolve(data, inner!, options, true)
   if (preserve) {
     return [callback!(result)]
-    // } else if (isPlainObject(data)) {
-    //   const temp: any = {}
-    //   for (const key in result) {
-    //     if (!(key in data)) continue
-    //     temp[key] = data[key]
-    //     delete data[key]
-    //   }
-    //   Object.assign(data, callback!(temp))
-    //   return [callback!(result)]
+  // } else if (isPlainObject(data)) {
+  //   const temp: any = {}
+  //   for (const key in result) {
+  //     if (!(key in data)) continue
+  //     temp[key] = data[key]
+  //     delete data[key]
+  //   }
+  //   Object.assign(data, callback!(temp))
+  //   return [callback!(result)]
   } else {
     return [callback!(result), callback!(adapted)]
   }

From ca979fe2edd71f474764f9f53bc6298657c297e5 Mon Sep 17 00:00:00 2001
From: montmorill <montmorill@outlook.com>
Date: Tue, 14 Apr 2026 23:06:19 +0800
Subject: [PATCH 3/4] Fixes code formatting and removes unnecessary semicolons

Standardizes code style by removing extraneous semicolons and fixing indentation
in array iteration and property assignment patterns
---
 packages/core/src/index.ts | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e1919ec..502b7ea 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -218,7 +218,7 @@ const Schema = function (options: Schema) {
     try {
       // eslint-disable-next-line no-new-func
       schema.callback = new Function('return ' + schema.callback)()
-    } catch { }
+    } catch {}
   }
   Object.defineProperty(schema, 'uid', { value: globalThis.__schemastery_index__++ })
   Object.setPrototypeOf(schema, Schema.prototype)
@@ -377,11 +377,11 @@ Schema.prototype.simplify = function simplify(this: Schema, value) {
     return result
   } else if (this.type === 'array' || this.type === 'tuple') {
     const result: any[] = []
-      ; (value as any[]).forEach((value, index) => {
-        const schema = this.type === 'array' ? this.inner : this.list![index]
-        const item = schema ? schema.simplify(value) : value
-        result.push(item)
-      })
+    ;(value as any[]).forEach((value, index) => {
+      const schema = this.type === 'array' ? this.inner : this.list![index]
+      const item = schema ? schema.simplify(value) : value
+      result.push(item)
+    })
     return result
   } else if (this.type === 'intersect') {
     const result: Dict = {}
@@ -394,7 +394,7 @@ Schema.prototype.simplify = function simplify(this: Schema, value) {
       try {
         Schema.resolve(value, schema, {})
         return schema.simplify(value)
-      } catch { }
+      } catch {}
     }
   }
   return value
@@ -795,13 +795,13 @@ function defineMethod(name: string, keys: (keyof Schema)[], format: Formatter) {
           }
           case 'callback': {
             const callback = schema.callback = args[index]
-              ; callback['toJSON'] ||= () => callback.toString()
+            callback.toJSON ||= () => callback.toString()
             break
           }
           case 'constructor': {
             const constructor = schema.constructor = args[index]
             if (typeof constructor === 'function') {
-              ; constructor['toJSON'] ||= () => constructor['name']
+              constructor.toJSON ||= () => constructor.name
             }
             break
           }

From 87dc834cc48ea2bc42abf8aa9adb6c843c6945f7 Mon Sep 17 00:00:00 2001
From: montmorill <montmorill@outlook.com>
Date: Tue, 14 Apr 2026 23:07:08 +0800
Subject: [PATCH 4/4] Removes unnecessary type assertion from date schema

The explicit type cast was redundant as TypeScript can infer
the correct return type from the function implementation.
---
 packages/core/src/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 502b7ea..8bd6bb8 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -501,7 +501,7 @@ Schema.date = function date() {
       if (isNaN(+date)) throw new ValidationError(`invalid date "${value}"`, options)
       return date
     }, true),
-  ]) as unknown as Schema<string | Date, Date, 'date'>
+  ])
 }
 
 Schema.regExp = function regExp(flag = '') {