Set

Describes set values. Sets can contain numbers, strings, or binaries:

import { set } from 'dynamodb-toolbox/schema/set';
import { string } from 'dynamodb-toolbox/schema/string';

const pokeTypeSchema = string().enum('fire', ...)
const pokemonTypesSchema = set(pokeTypeSchema)

type PokemonType = FormattedValue<typeof pokemonTypesSchema>;
// => Set<'fire' | ...>

Set elements must respect some constraints:

• They cannot be optional or always required
• They cannot be hidden or key (tagging the set itself as key is enough)
• They cannot have default or links

// ❌ Raises a type AND a run-time error
const strSet = set(string().optional())
const strSet = set(string().hidden())
const strSet = set(string().key())
const strSet = set(string().default('foo'))

Properties

.required()

string | undefined

Tags schema values as required (within items or maps). Possible values are:

• 'atLeastOnce' (default): Required (starting value)
• 'always': Always required (including updates)
• 'never': Optional

// Equivalent
const pokeTypesSchema = set(pokeTypeSchema)
const pokeTypesSchema = set(pokeTypeSchema).required()
const pokeTypesSchema = set(
  pokeTypeSchema,
  // Options can be provided as 2nd argument
  { required: 'atLeastOnce' }
)

// shorthand for `.required('never')`
const pokeTypesSchema = set(pokeTypeSchema).optional()
const pokeTypesSchema = set(..., { required: 'never' })

.hidden()

boolean | undefined

Omits schema values during formatting:

const pokeTypesSchema = set(pokeTypeSchema).hidden()
const pokeTypesSchema = set(..., { hidden: true })

.key()

boolean | undefined

Tags schema values as a primary key attribute or linked to a primary key attribute:

// Note: The method also sets the `required` property to 'always'
// (it is often the case in practice, you can still use `.optional()` if needed)
const pokeTypesSchema = set(pokeTypeSchema).key()
const pokeTypesSchema = set(..., {
  key: true,
  required: 'always'
})

.savedAs(...)

string

Renames schema values during the transformation step (within items or maps):

const pokeTypesSchema = set(pokeTypeSchema).savedAs('pt')
const pokeTypesSchema = set(..., { savedAs: 'pt' })

.default(...)

ValueOrGetter<Set<ELEMENTS>>

Specifies default values. See Defaults and Links for more details:

Examples

Put/Update

const now = () => new Date().toISOString()

const timestampsSchema = set(string())
  .default(() => new Set([now()]))
  .updateDefault(() => $add(now()))
// 👇 Similar to
const timestampsSchema = set(string())
  .putDefault(() => new Set([now()]))
  .updateDefault(() => $add(now()))
// 👇 ...or
const timestampsSchema = set({
  putDefault: () => new Set([now()])
})

Key

const defaultSpecifiers = new Set(['POKEMON'])

const specifiersSchema = set(string())
  .key()
  .default(defaultSpecifiers)
// 👇 Similar to
const specifiersSchema = set(string())
  .key()
  .keyDefault(defaultSpecifiers)
// 👇 ...or
const specifiersSchema = set({
  key: true,
  required: 'always',
  keyDefault: defaultSpecifiers
})

.link<Schema>(...)

Link<SCHEMA, Set<ELEMENTS>>

Similar to .default(...) but allows deriving the default value from other attributes. See Defaults and Links for more details:

const pokemonSchema = item({
  pokeTypeList: list(pokeTypeSchema)
}).and(prevSchema => ({
  pokeTypeSet: set(pokeTypeSchema).link<typeof prevSchema>(
    // 🙌 Correctly typed!
    item => new Set(item.pokeTypeList)
  )
}))

.validate(...)

Validator<Set<ELEMENTS>>

Adds custom validation. See Custom Validation for more details:

Examples

const nonEmptySetSchema = set(string()).validate(
  input => input.size > 0
)
// 👇 Similar to
const nonEmptySetSchema = set(string()).putValidate(
  input => input.size > 0
)
// 👇 ...or
const nonEmptySetSchema = set(string(), {
  putValidator: input => input.size > 0
})