Null

Defines a null attribute:

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

const pokemonSchema = schema({
  ...
  nullValue: nul(),
});

type FormattedPokemon = FormattedItem<typeof PokemonEntity>;
// => {
//   ...
//   nullValue: null
// }

info

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

const pokemonSchema = schema({
  ...
  nullableString: anyOf(string(), nul()),
});

Options

.required()

string | undefined

Tags the attribute as required (at root level or within Maps). Possible values are:

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

// Equivalent
const nullishSchema = nul()
const nullishSchema = nul().required()
const nullishSchema = nul({ required: 'atLeastOnce' })

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

.hidden()

boolean | undefined

Skips the attribute when formatting items:

const nullishSchema = nul().hidden()
const nullishSchema = nul({ hidden: true })

.key()

boolean | undefined

Tags the attribute as a primary key attribute or linked to a primary 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 nullishSchema = nul().key()
const nullishSchema = nul({
  key: true,
  required: 'always'
})

.savedAs(...)

string

Renames the attribute during the transformation step (at root level or within Maps):

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

.default(...)

ValueOrGetter<null>

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

Examples

Put

const nullishSchema = nul().default(null)
// 👇 Similar to
const nullishSchema = nul().putDefault(null)
// 👇 ...or
const nullishSchema = nul({
  defaults: {
    key: undefined,
    put: null,
    update: undefined
  }
})

Key

const nullishSchema = nul().key().default(null)
// 👇 Similar to
const nullishSchema = nul().key().keyDefault(null)
// 👇 ...or
const nullishSchema = nul({
  defaults: {
    key: null,
    // put & update defaults are not useful in `key` attributes
    put: undefined,
    update: undefined
  },
  key: true,
  required: 'always'
})

Update

const isUpdatedSchema = nul().updateDefault(null)
// 👇 Similar to
const isUpdatedSchema = nul({
  defaults: {
    key: undefined,
    put: undefined,
    update: 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 = schema({
  boolean: boolean()
}).and(prevSchema => ({
  nullIfTrue: nul()
    .optional()
    .link<typeof prevSchema>(
      // 🙌 Correctly typed!
      ({ boolean }) => (boolean ? null : undefined)
    )
}))

.validate(...)

Validator<null>

Adds custom validation to the attribute. See Custom Validation for more details.