Null

Describes null values:

// `null` is a reserved keyword 🤷‍♂️
import { nul } from 'dynamodb-toolbox/schema/nul'

const nullSchema = nul()

type Null = FormattedValue<typeof nullSchema>
// => null

info

Not very useful on itself, nul is more likely to be used in conjunction with anyOf to define nullable schemas:

const nullableString = anyOf(string(), nul())

type NullableString = FormattedValue<typeof nullableString>
// => string | null

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 nullSchema = nul()
const nullSchema = nul().required()
const nullSchema = nul({ required: 'atLeastOnce' })

// shorthand for `.required('never')`
const nullSchema = nul().optional()
const nullSchema = nul({ required: 'never' })

.hidden()

boolean | undefined

Omits schema values during formatting:

const nullSchema = nul().hidden()
const nullSchema = nul({ 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 nullSchema = nul().key()
const nullSchema = nul({
  key: true,
  required: 'always'
})

.savedAs(...)

string

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

const nullSchema = nul().savedAs('_n')
const nullSchema = nul({ savedAs: '_n' })

.default(...)

ValueOrGetter<null>

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

Examples

Put

const nullSchema = nul().default(null)
// 👇 Similar to
const nullSchema = nul().putDefault(null)
// 👇 ...or
const nullSchema = nul({ putDefault: null })

Key

const nullSchema = nul().key().default(null)
// 👇 Similar to
const nullSchema = nul().key().keyDefault(null)
// 👇 ...or
const nullSchema = nul({
  key: true,
  required: 'always',
  keyDefault: null
})

Update

const isUpdatedSchema = nul().updateDefault(null)
// 👇 Similar to
const isUpdatedSchema = nul({ updateDefault: null })

.link<Schema>(...)

Link<SCHEMA, null>

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

const pokemonSchema = item({
  boolean: boolean()
}).and(prevSchema => ({
  nullIfTrue: nul()
    .optional()
    .link<typeof prevSchema>(
      // 🙌 Correctly typed!
      ({ boolean }) => (boolean ? null : undefined)
    )
}))

.validate(...)

Validator<null>

Adds custom validation. See Custom Validation for more details.