Building generic types

[daedalus28]

I'm not clear how to build generic types properly. I don't see an ecosystem of utility types nor documentation beyond a very basic note, so I figured I'd open a discussion. I have two use cases, both inspired by utility types from type-fest. My goal is to understand how to create these types of utilities in addition to figuring out the two use cases at hand. These could definitely end up as PRs to typebox or as a new repo of typebox utilities.

The first is SetOptional, which is like Type.Partial but applied to a list of fields. The pattern I'm generalizing is omitting a list of fields from a type and then intersecting with a partial pick of those fields:

/**
 * Like Type.Partial, but only applied to a list of fields instead of all fields.
 * Named SetOptional to align with type-fest https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts
 *
 * @param schema The schema being modified
 * @param fields The list of fields which should become options
 * @param options The list of options passed to typebox schemas. A common example is setting $id (for documentation)
 * @returns A typebox schema with a subset of the fields as optional
 */
export let SetOptional = <T extends TObject, K extends ObjectPropertyKeys<T>[]>(
  schema: T,
  fields: K,
  options?: SchemaOptions,
) =>
  Type.Intersect(
    [Type.Omit(schema, fields), Type.Partial(Type.Pick(schema, fields))],
    options,
  )

However, typing isn't preserved when I use this as typescript thinks this makes everything optional. It works perfectly inline when not wrapped in a function, so I suspect my typing for fields must be wrong somehow and causing type info to be lost.

My second use case is Merge, which is similar but overrides some properties with new ones. This is what I have so far:

export let Merge = <T extends TObject, TT extends TObject, K extends ObjectPropertyKeys<T>[]>(
  schema: T,
  schema2: TT,
  options?: SchemaOptions,
) => {
  let fields = Object.keys(schema2.properties) as K //as ObjectPropertyKeys<T>[]
  return Type.Intersect([Type.Omit(schema, fields), schema2], options)
}

The typing here just causes everything to get lost. Once again, inlining this makes everything work so I'm sure I just have the typings wrong.

Documenting a few of these examples would make these types of utilities more accessible.

[sinclairzx81]

@daedalus28 Hi,

I'm not clear how to build generic types properly. I don't see an ecosystem of utility types nor documentation beyond a very basic note, so I figured I'd open a discussion. I have two use cases, both inspired by utility types from type-fest. My goal is to understand how to create these types of utilities in addition to figuring out the two use cases at hand. These could definitely end up as PRs to typebox or as a new repo of typebox utilities.

TypeBox generics programming has been evolving alongside the advancements in the TypeScript type system and the emerging techniques and idioms being established within the type-level programming community. Given the complexity of this topic and its evolving nature, it has been challenging to document. My preference so far has just been to let users experiment and to answer questions around it.

This said, I would be happy to start an open dialog around generics programming in TypeBox.

---

See below for reference implementations of SetOptional and Merge types

TypeScript Link Here

import { Type, TObject, TProperties, SchemaOptions } from '@sinclair/typebox'
import { Syntax } from '@sinclair/typebox/syntax'

// ------------------------------------------------------------------------
// SetOptional
//
// When using a tuple as a parameter to a mapping, ensure the tuple is spread 
// via [...T]. This causes TS to expand the tuple into a fixed sized array. 
// This is important as all TypeBox types require fixed sized tuples to perform 
// tuple remapping.
//
// ------------------------------------------------------------------------

const SetOptional = <Type extends TObject, Key extends PropertyKey[]>(type: Type, fields: [...Key], options?: SchemaOptions) => 
  // tip: use Composite() instead of Intersect() to flatten the intersection. In future, Evaluate(Intersect([...T])) will 
  // become available to offer a more generalized version of Composite()
  Type.Intersect([ Type.Omit(type, fields),  Type.Partial(Type.Pick(type, fields))], options)

  const A = SetOptional(Syntax(`{ 
    x: number, 
    y: number, 
    z: number 
  }`), ['x', 'y'])


// ------------------------------------------------------------------------
// Merge
//
// Some types can't be naturally derived through JS logic. For a Merge
// operation, there is no equivalent in TS as it is based on sets and JS uses 
// property key override in Right. In cases like this you need to replicate 
// the JS logic at a type level. The TMerge type achieves this. Note the 
// symmetry between the TS and JS implementations.
// 
// ------------------------------------------------------------------------
type TMerge<Left extends TObject, Right extends TObject,
  Properties extends TProperties = Omit<Left['properties'], keyof Right['properties']> & Right['properties'],
  Evaluated extends TProperties = {[Key in keyof Properties]: Properties[Key]} & {}, // evalulated: prettify trick
  Result extends TObject = TObject<Evaluated>
> = Result

const Merge = <Left extends TObject, Right extends TObject>(left: Left, right: Right, options?: SchemaOptions): TMerge<Left, Right> => {
  const properties = { ...left.properties, ...right.properties }
  const result = Type.Object(properties, options)
  return result as never // computed type can't be inferred from JS logic. Use 'as never' and trust TMerge<...> return type
}

// override 'x', append 'w'
const B = Merge(Syntax(`{
  x: number,
  y: number,
  z: number
}`), Syntax(`{
  x: string,
  w: boolean
}`))

---

If you have any specific questions on generic programming with TypeBox (i.e. tuple mapping, computed types, recursive inference techniques, etc), I'm happy to field these questions on this thread.

Cheers!

[daedalus28]

@sinclairzx81 Thanks, this is really helpful! Are there some resources you recommend to learn more about this kind of stuff? Most of what I've found doesn't really go this deep.

Since I am currently using type-fest, I wonder if those types could be used to help out here instead of defining things like TMerge. It's probably a good practice to use standardized type utilities if we can.

You implementation ofMerge works very well! SetOptional seems to be throwing a type error when passing fields into Omit and Pick:
Argument of type '[...Key]' is not assignable to parameter of type 'readonly ObjectPropertyKeys<Type>[]'.

I am on an old version of typebox as I'm using feathersjs which is stuck at 0.25, so maybe that's the issue.

[daedalus28]

SetOptional works if I change the type of Key to Key extends ObjectPropertyKeys<Type>[] instead of Key extends PropertyKey[]. Could this be because I'm on an older version? I'm not super clear on the difference between ObjectPropertyKeys<Type> and PropertyKey