Utilities

Superstruct also ships with a handful of utility type factories, which allow you to easily manipulate and transforms existing structs.

assign

assign(object({ id: string() }), object({ name: string() }))

{
  id: 1,
  name: 'Jane',
}

assign creates a new struct by mixing the properties of existing object structs, similar to JavaScript's native Object.assign. It can accept object and type structs, returning a struct matching whichever is passed in as the first parameter (ie, which struct is being "assigned" into).

deprecated

object({
  id: number(),
  full_name: string(),
  name: deprecated(string(), (value, ctx) => {
    console.warn(`${ctx.path} is deprecated, but value was '${value}'. Please use 'full_name' instead.`)
  }),
})

{ id: 1, name: 'Jane' }

deprecated structs validate that a value matches a specific struct, or that it is undefined. But in addition, when the value is not undefined, it will call the log function you pass in so you can warn users that they're using a deprecated API.

dynamic

const User = object({ ... })
const Bot = object({ ... })

dynamic((value) => {
  return value.kind === 'user' ? User : Bot
})

dynamic allows you to create a struct with validation logic that can change at runtime. The callback will be called with (value, context) and must return the struct to continue validation with.

lazy

const Node = object({
  id: number(),
  children: lazy(() => array(Node)),
})

lazy allows you to create a self-referential struct, useful for defining recursive data structures.

🤖 Note that TypeScript can't automatically infer the type from this kind of recursive structure, so you'll need to pass in the type manually.

omit

omit(
  object({
    id: number(),
    name: string(),
  }),
  ['name']
)

omit allows you to create a new struct based on an existing object or type struct, but excluding specific properties.

partial

partial(
  object({
    id: number(),
    name: string(),
  })
)

{ id: 1, name: 'Jane' }
{ id: 1 }
{ name: 'Jane' }

partial allows you to create a new struct based on an existing object or type struct, but with all of its properties being optional.

pick

pick(
  object({
    id: number(),
    name: string(),
  }),
  ['id']
)

pick allows you to create a new struct based on an existing object or type struct, but only including specific properties.