feat: 🎸 support named keys in validation

streamich · streamich · commit 61d77a11a88c · 2025-08-10T10:28:32.000+02:00
diff --git a/src/codegen/AbstractCodege.ts b/src/codegen/AbstractCodege.ts
@@ -9,6 +9,7 @@ import type {
   MapType,
   NumType,
   ObjType,
+  KeyType,
   OrType,
   RefType,
   StrType,
@@ -27,6 +28,7 @@ export abstract class AbstractCodegen<Fn extends (...deps: any[]) => any = (...d
   protected abstract onBin(path: SchemaPath, r: JsExpression, type: BinType): void;
   protected abstract onArr(path: SchemaPath, r: JsExpression, type: ArrType): void;
   protected abstract onObj(path: SchemaPath, r: JsExpression, type: ObjType): void;
+  protected abstract onKey(path: SchemaPath, r: JsExpression, type: KeyType<any, any>): void;
   protected abstract onMap(path: SchemaPath, r: JsExpression, type: MapType): void;
   protected abstract onRef(path: SchemaPath, r: JsExpression, type: RefType): void;
   protected abstract onOr(path: SchemaPath, r: JsExpression, type: OrType): void;
@@ -62,6 +64,9 @@ export abstract class AbstractCodegen<Fn extends (...deps: any[]) => any = (...d
       case 'obj':
         this.onObj(path, r, type as ObjType);
         break;
+      case 'key':
+        this.onKey(path, r, type as KeyType<any, any>);
+        break;
       case 'map':
         this.onMap(path, r, type as MapType);
         break;
diff --git a/src/codegen/binary/cbor copy/CborCodegen.ts b/src/codegen/binary/cbor copy/CborCodegen.ts
@@ -1,7 +1,7 @@
 import {JsExpression} from '@jsonjoy.com/codegen/lib/util/JsExpression';
 import {normalizeAccessor} from '@jsonjoy.com/codegen/lib/util/normalizeAccessor';
 import {CborEncoder} from '@jsonjoy.com/json-pack/lib/cbor/CborEncoder';
-import {type MapType, ObjKeyOptType, type ObjType, type Type} from '../../../type';
+import {type MapType, KeyOptType, type ObjType, type Type} from '../../../type';
 import type {CompiledBinaryEncoder, SchemaPath} from '../../types';
 import {lazyKeyedFactory} from '../../util';
 import {AbstractBinaryCodegen} from '../AbstractBinaryCodegen';
@@ -23,8 +23,8 @@ export class CborCodegen extends AbstractBinaryCodegen<CborEncoder> {
     const r = codegen.r();
     const fields = type.keys;
     const length = fields.length;
-    const requiredFields = fields.filter((field) => !(field instanceof ObjKeyOptType));
-    const optionalFields = fields.filter((field) => field instanceof ObjKeyOptType);
+    const requiredFields = fields.filter((field) => !(field instanceof KeyOptType));
+    const optionalFields = fields.filter((field) => field instanceof KeyOptType);
     const requiredLength = requiredFields.length;
     const optionalLength = optionalFields.length;
     const encodeUnknownFields = !!type.schema.encodeUnknownKeys;
diff --git a/src/codegen/binary/cbor/CborCodegen.ts b/src/codegen/binary/cbor/CborCodegen.ts
@@ -1,7 +1,7 @@
 import {JsExpression} from '@jsonjoy.com/codegen/lib/util/JsExpression';
 import {normalizeAccessor} from '@jsonjoy.com/codegen/lib/util/normalizeAccessor';
 import {CborEncoder} from '@jsonjoy.com/json-pack/lib/cbor/CborEncoder';
-import {ObjKeyOptType, type ObjType, type Type} from '../../../type';
+import {KeyOptType, type ObjType, type Type} from '../../../type';
 import type {CompiledBinaryEncoder, SchemaPath} from '../../types';
 import {lazyKeyedFactory} from '../../util';
 import {AbstractBinaryCodegen} from '../AbstractBinaryCodegen';
@@ -23,8 +23,8 @@ export class CborCodegen extends AbstractBinaryCodegen<CborEncoder> {
     const r = codegen.r();
     const fields = type.keys;
     const length = fields.length;
-    const requiredFields = fields.filter((field) => !(field instanceof ObjKeyOptType));
-    const optionalFields = fields.filter((field) => field instanceof ObjKeyOptType);
+    const requiredFields = fields.filter((field) => !(field instanceof KeyOptType));
+    const optionalFields = fields.filter((field) => field instanceof KeyOptType);
     const requiredLength = requiredFields.length;
     const optionalLength = optionalFields.length;
     const encodeUnknownFields = !!type.schema.encodeUnknownKeys;
diff --git a/src/codegen/binary/json/JsonCodegen.ts b/src/codegen/binary/json/JsonCodegen.ts
@@ -1,7 +1,7 @@
 import {JsExpression} from '@jsonjoy.com/codegen/lib/util/JsExpression';
 import {normalizeAccessor} from '@jsonjoy.com/codegen/lib/util/normalizeAccessor';
 import {JsonEncoder} from '@jsonjoy.com/json-pack/lib/json/JsonEncoder';
-import {type ArrType, type MapType, ObjKeyOptType, type ObjType, type Type} from '../../../type';
+import {type ArrType, type MapType, KeyOptType, type ObjType, type Type} from '../../../type';
 import type {CompiledBinaryEncoder, SchemaPath} from '../../types';
 import {lazyKeyedFactory} from '../../util';
 import {AbstractBinaryCodegen} from '../AbstractBinaryCodegen';
@@ -98,8 +98,8 @@ export class JsonCodegen extends AbstractBinaryCodegen<JsonEncoder> {
     const codegen = this.codegen;
     const r = codegen.var(value.use());
     const fields = type.keys;
-    const requiredFields = fields.filter((field) => !(field instanceof ObjKeyOptType));
-    const optionalFields = fields.filter((field) => field instanceof ObjKeyOptType);
+    const requiredFields = fields.filter((field) => !(field instanceof KeyOptType));
+    const optionalFields = fields.filter((field) => field instanceof KeyOptType);
     const requiredLength = requiredFields.length;
     const optionalLength = optionalFields.length;
     const encodeUnknownFields = !!type.schema.encodeUnknownKeys;
diff --git a/src/codegen/binary/msgpack/MsgPackCodegen.ts b/src/codegen/binary/msgpack/MsgPackCodegen.ts
@@ -1,7 +1,7 @@
 import {JsExpression} from '@jsonjoy.com/codegen/lib/util/JsExpression';
 import {normalizeAccessor} from '@jsonjoy.com/codegen/lib/util/normalizeAccessor';
 import {MsgPackEncoder} from '@jsonjoy.com/json-pack/lib/msgpack/MsgPackEncoder';
-import {ObjKeyOptType, type ObjType, type Type} from '../../../type';
+import {KeyOptType, type ObjType, type Type} from '../../../type';
 import type {CompiledBinaryEncoder, SchemaPath} from '../../types';
 import {lazyKeyedFactory} from '../../util';
 import {AbstractBinaryCodegen} from '../AbstractBinaryCodegen';
@@ -23,8 +23,8 @@ export class MsgPackCodegen extends AbstractBinaryCodegen<MsgPackEncoder> {
     const r = codegen.r();
     const fields = type.keys;
     const length = fields.length;
-    const requiredFields = fields.filter((field) => !(field instanceof ObjKeyOptType));
-    const optionalFields = fields.filter((field) => field instanceof ObjKeyOptType);
+    const requiredFields = fields.filter((field) => !(field instanceof KeyOptType));
+    const optionalFields = fields.filter((field) => field instanceof KeyOptType);
     const requiredLength = requiredFields.length;
     const optionalLength = optionalFields.length;
     const totalMaxKnownFields = requiredLength + optionalLength;
diff --git a/src/codegen/capacity/CapacityEstimatorCodegen.ts b/src/codegen/capacity/CapacityEstimatorCodegen.ts
@@ -2,8 +2,8 @@ import {Codegen, CodegenStepExecJs} from '@jsonjoy.com/codegen';
 import {JsExpression} from '@jsonjoy.com/codegen/lib/util/JsExpression';
 import {normalizeAccessor} from '@jsonjoy.com/codegen/lib/util/normalizeAccessor';
 import {MaxEncodingOverhead, maxEncodingCapacity} from '@jsonjoy.com/util/lib/json-size';
-import {BoolType, ConType, NumType, ObjKeyOptType} from '../../type';
-import type {ArrType, MapType, ObjKeyType, ObjType, OrType, RefType, Type} from '../../type';
+import {BoolType, ConType, NumType, KeyOptType} from '../../type';
+import type {ArrType, MapType, KeyType, ObjType, OrType, RefType, Type} from '../../type';
 import {DiscriminatorCodegen} from '../discriminator';
 import {lazyKeyedFactory} from '../util';
 
@@ -113,10 +113,10 @@ export class CapacityEstimatorCodegen {
     this.inc(MaxEncodingOverhead.Object);
     const fields = objectType.keys;
     for (const f of fields) {
-      const field = f as ObjKeyType<any, any>;
+      const field = f as KeyType<any, any>;
       const accessor = normalizeAccessor(field.key);
       const fieldExpression = new JsExpression(() => `${r}${accessor}`);
-      const isOptional = field instanceof ObjKeyOptType;
+      const isOptional = field instanceof KeyOptType;
       if (isOptional) {
         codegen.if(/* js */ `${JSON.stringify(field.key)} in ${r}`, () => {
           this.inc(MaxEncodingOverhead.ObjectElement);
diff --git a/src/codegen/json/JsonTextCodegen.ts b/src/codegen/json/JsonTextCodegen.ts
@@ -5,7 +5,7 @@ import {normalizeAccessor} from '@jsonjoy.com/codegen/lib/util/normalizeAccessor
 import {stringify} from '@jsonjoy.com/json-pack/lib/json-binary/codec';
 import type {json_string} from '@jsonjoy.com/util/lib/json-brand';
 import {asString} from '@jsonjoy.com/util/lib/strings/asString';
-import {ObjKeyOptType} from '../../type';
+import {KeyOptType} from '../../type';
 import type {ArrType, ConType, MapType, ObjType, OrType, RefType, StrType, Type} from '../../type';
 import {DiscriminatorCodegen} from '../discriminator';
 import {lazyKeyedFactory} from '../util';
@@ -107,8 +107,8 @@ export class JsonTextCodegen {
     if (schema.encodeUnknownKeys) {
       this.js(/* js */ `var ${rKeys} = new Set(Object.keys(${r}));`);
     }
-    const requiredFields = fields.filter((field) => !(field instanceof ObjKeyOptType));
-    const optionalFields = fields.filter((field) => field instanceof ObjKeyOptType) as ObjKeyOptType<string, Type>[];
+    const requiredFields = fields.filter((field) => !(field instanceof KeyOptType));
+    const optionalFields = fields.filter((field) => field instanceof KeyOptType) as KeyOptType<string, Type>[];
     this.writeText('{');
     for (let i = 0; i < requiredFields.length; i++) {
       const field = requiredFields[i];
diff --git a/src/codegen/validator/ValidatorCodegen.ts b/src/codegen/validator/ValidatorCodegen.ts
@@ -11,12 +11,13 @@ import {
   type ConType,
   type MapType,
   type NumType,
-  ObjKeyOptType,
+  KeyOptType,
   type ObjType,
   type OrType,
   type RefType,
   type StrType,
   type Type,
+  KeyType,
 } from '../../type';
 import {floats, ints, uints} from '../../util';
 import {isAscii, isUtf8} from '../../util/stringFormats';
@@ -379,7 +380,7 @@ export class ValidatorCodegen extends AbstractCodegen {
       const accessor = normalizeAccessor(field.key);
       const keyPath = [...path, field.key];
       codegen.js(/* js */ `var ${rv} = ${r.use()}${accessor};`);
-      if (field instanceof ObjKeyOptType) {
+      if (field instanceof KeyOptType) {
         codegen.js(/* js */ `if (${rv} !== undefined) {`);
         this.onNode(keyPath, new JsExpression(() => rv), field.val);
         codegen.js(/* js */ `}`);
@@ -394,6 +395,10 @@ export class ValidatorCodegen extends AbstractCodegen {
     }
   }
 
+  protected onKey(path: SchemaPath, r: JsExpression, type: KeyType<any, any>): void {
+    this.onNode([...path, type.key], r, type.val);
+  }
+
   protected onMap(path: SchemaPath, r: JsExpression, type: MapType): void {
     const codegen = this.codegen;
     const err = this.err(ValidationError.MAP, path);
diff --git a/src/codegen/validator/__tests__/codegen.spec.ts b/src/codegen/validator/__tests__/codegen.spec.ts
@@ -841,6 +841,24 @@ describe('"arr" type', () => {
     });
   });
 
+  test('named head 2-tuple', () => {
+    const type = s.Tuple([s.Key('num', s.num), s.Key('str', s.str)]);
+    exec(type, [0, ''], null);
+    exec(type, [1, 'x'], null);
+    exec(type, ['', 'x'], {
+      code: 'NUM',
+      errno: ValidationError.NUM,
+      message: 'Not a number.',
+      path: [0, 'num'],
+    });
+    exec(type, [-1, true], {
+      code: 'STR',
+      errno: ValidationError.STR,
+      message: 'Not a string.',
+      path: [1, 'str'],
+    });
+  });
+
   test('head + elements', () => {
     const type = s.Tuple([s.Const<true>(true)], s.num);
     exec(type, [true, 123], null);
diff --git a/src/jtd/converter.ts b/src/jtd/converter.ts
@@ -1,4 +1,4 @@
-import {type ArrType, ObjKeyOptType, type ObjType, type RefType, type Type} from '../type';
+import {type ArrType, KeyOptType, type ObjType, type RefType, type Type} from '../type';
 import type * as jtd from './types';
 
 const NUMS_TYPE_MAPPING = new Map<string, jtd.JtdType>([
@@ -86,7 +86,7 @@ export function toJtdForm(type: Type): jtd.JtdForm {
           if (fieldType) {
             const fieldJtd = toJtdForm(fieldType);
             // Check if field is optional
-            if (field instanceof ObjKeyOptType) {
+            if (field instanceof KeyOptType) {
               form.optionalProperties[fieldName] = fieldJtd;
             } else {
               form.properties[fieldName] = fieldJtd;
diff --git a/src/schema/schema.ts b/src/schema/schema.ts
@@ -453,7 +453,7 @@ export type JsonSchema =
   | OptKeySchema
   | MapSchema;
 
-export type Schema = JsonSchema | RefSchema | OrSchema | AnySchema | FnSchema | FnRxSchema | AliasSchema | ModuleSchema;
+export type Schema = JsonSchema | RefSchema | OrSchema | AnySchema | FnSchema | FnRxSchema | AliasSchema | ModuleSchema | KeySchema | OptKeySchema;
 
 export type NoT<T extends SchemaBase> = Omit<T, 'kind'>;
 
diff --git a/src/type/TypeBuilder.ts b/src/type/TypeBuilder.ts
@@ -18,7 +18,7 @@ type ObjValueTuple<T, KS extends any[] = UnionToTuple<keyof T>, R extends any[]
   : R;
 
 type RecordToFields<O extends Record<string, Type>> = ObjValueTuple<{
-  [K in keyof O]: classes.ObjKeyType<K extends string ? K : never, O[K]>;
+  [K in keyof O]: classes.KeyType<K extends string ? K : never, O[K]>;
 }>;
 
 export class TypeBuilder {
@@ -118,7 +118,7 @@ export class TypeBuilder {
    * @returns An object type.
    */
   public readonly object = <R extends Record<string, Type>>(record: R): classes.ObjType<RecordToFields<R>> => {
-    const keys: classes.ObjKeyType<any, any>[] = [];
+    const keys: classes.KeyType<any, any>[] = [];
     for (const [key, value] of Object.entries(record)) keys.push(this.Key(key, value));
     return new classes.ObjType<RecordToFields<R>>(keys as any).sys(this.system);
   };
@@ -195,16 +195,16 @@ export class TypeBuilder {
     return new classes.ArrType(item, head, tail, options).sys(this.system);
   }
 
-  public Object<F extends (classes.ObjKeyType<any, any> | classes.ObjKeyOptType<any, any>)[]>(...keys: F) {
+  public Object<F extends (classes.KeyType<any, any> | classes.KeyOptType<any, any>)[]>(...keys: F) {
     return new classes.ObjType<F>(keys).sys(this.system);
   }
 
   public Key<K extends string, V extends Type>(key: K, value: V) {
-    return new classes.ObjKeyType<K, V>(key, value).sys(this.system);
+    return new classes.KeyType<K, V>(key, value).sys(this.system);
   }
 
   public KeyOpt<K extends string, V extends Type>(key: K, value: V) {
-    return new classes.ObjKeyOptType<K, V>(key, value).sys(this.system);
+    return new classes.KeyOptType<K, V>(key, value).sys(this.system);
   }
 
   public Map<T extends Type>(val: T, key?: Type, options?: schema.Optional<schema.MapSchema>) {
@@ -264,6 +264,10 @@ export class TypeBuilder {
         );
         return this.Object(...fields).options(node);
       }
+      case 'key':
+        return node.optional
+          ? this.KeyOpt(node.key, this.import(node.value as schema.Schema)).options(node)
+          : this.Key(node.key, this.import(node.value as schema.Schema)).options(node);
       case 'map':
         return this.Map(this.import(node.value), node.key ? this.import(node.key) : undefined, node);
       case 'con':
diff --git a/src/type/classes.ts b/src/type/classes.ts
@@ -23,8 +23,8 @@ export {
   StrType,
   BinType,
   ArrType,
-  KeyType as ObjKeyType,
-  KeyOptType as ObjKeyOptType,
+  KeyType,
+  KeyOptType,
   ObjType,
   MapType,
   RefType,
diff --git a/src/type/discriminator.ts b/src/type/discriminator.ts
@@ -1,5 +1,5 @@
 import type {Expr} from '@jsonjoy.com/json-expression';
-import {ArrType, BoolType, ConType, NumType, type ObjKeyType, ObjType, StrType} from './classes';
+import {ArrType, BoolType, ConType, NumType, type KeyType, ObjType, StrType} from './classes';
 import type {OrType, RefType, Type} from './types';
 
 /**
@@ -59,7 +59,7 @@ export class Discriminator {
         if (d) return new Discriminator('/' + i + d.path, d.type);
       }
     } else if (type instanceof ObjType) {
-      const fields = type.keys as ObjKeyType<string, Type>[];
+      const fields = type.keys as KeyType<string, Type>[];
       for (let i = 0; i < fields.length; i++) {
         const f = fields[i];
         const d = Discriminator.findConst(f.val);
diff --git a/src/type/types.ts b/src/type/types.ts
@@ -29,9 +29,9 @@ export type SchemaOfMap<M extends Record<string, Type>> = {
   [K in keyof M]: SchemaOf<M[K]>;
 };
 
-export type SchemaOfObjectFieldType<F> = F extends classes.ObjKeyOptType<infer K, infer V>
+export type SchemaOfObjectFieldType<F> = F extends classes.KeyOptType<infer K, infer V>
   ? schema.OptKeySchema<K, SchemaOf<V>>
-  : F extends classes.ObjKeyType<infer K, infer V>
+  : F extends classes.KeyType<infer K, infer V>
     ? schema.KeySchema<K, SchemaOf<V>>
     : never;
 
diff --git a/src/value/ObjValue.ts b/src/value/ObjValue.ts
@@ -7,8 +7,8 @@ import {Value} from './Value';
 
 export type UnObjType<T> = T extends classes.ObjType<infer U> ? U : never;
 export type UnObjValue<T> = T extends ObjValue<infer U> ? U : never;
-export type UnObjFieldTypeVal<T> = T extends classes.ObjKeyType<any, infer U> ? U : never;
-export type ObjFieldToTuple<F> = F extends classes.ObjKeyType<infer K, infer V> ? [K, V] : never;
+export type UnObjFieldTypeVal<T> = T extends classes.KeyType<any, infer U> ? U : never;
+export type ObjFieldToTuple<F> = F extends classes.KeyType<infer K, infer V> ? [K, V] : never;
 export type ToObject<T> = T extends [string, unknown][] ? {[K in T[number] as K[0]]: K[1]} : never;
 export type ObjValueToTypeMap<F> = ToObject<{
   [K in keyof F]: ObjFieldToTuple<F[K]>;
@@ -27,7 +27,7 @@ export class ObjValue<T extends classes.ObjType<any>> extends Value<T> implement
 
   public keys(): string[] {
     const type = this.type as T;
-    return type.keys.map((field: classes.ObjKeyType<string, any>) => field.key);
+    return type.keys.map((field: classes.KeyType<string, any>) => field.key);
   }
 
   public get<K extends keyof ObjValueToTypeMap<UnObjType<T>>>(
@@ -41,7 +41,7 @@ export class ObjValue<T extends classes.ObjType<any>> extends Value<T> implement
     return new Value(field.val, data) as any;
   }
 
-  public field<F extends classes.ObjKeyType<any, any>>(
+  public field<F extends classes.KeyType<any, any>>(
     field: F | ((t: TypeBuilder) => F),
     data: classes.ResolveType<UnObjFieldTypeVal<F>>,
   ): ObjValue<classes.ObjType<[...UnObjType<T>, F]>> {
