String

Defines a string attribute:

import { string } from 'dynamodb-toolbox/attributes/string';

const pokemonSchema = schema({
  ...
  name: string(),
});

type FormattedPokemon = FormattedItem<typeof PokemonEntity>;
// => {
//   ...
//   name: string
// }

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

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

.hidden()

boolean | undefined

Skips the attribute when formatting items:

const nameSchema = string().hidden()
const nameSchema = string({ hidden: true })

.key()

boolean | undefined

Tags the attribute as needed to compute the primary key:

// 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 nameSchema = string().key()
const nameSchema = string({
  key: true,
  required: 'always'
})

.savedAs(...)

string

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

const nameSchema = string().savedAs('n')
const nameSchema = string({ savedAs: 'n' })

.enum(...)

string[]

Provides a finite range of possible values:

const pokeTypeSchema = string().enum('fire', 'water', ...)

// 👇 Equivalent to `.enum('fire').default('fire')`
const pokeTypeSchema = string().const('fire')

info

For type inference reasons, the enum option is only available as a method and not as a constructor property.

.transform(...)

Transformer<string>

Allows modifying the attribute values during the transformation step:

const PREFIX = 'PREFIX#'

const prefix = {
  parse: (input: string) => [PREFIX, input].join(''),
  format: (saved: string) => saved.slice(PREFIX.length)
}

// Prefixes the value
const prefixedStrSchema = string().transform(prefix)
const prefixedStrSchema = string({ transform: prefix })

DynamoDB-Toolbox exposes on-the-shelf transformers (including prefix), so feel free to use them!

.default(...)

ValueOrGetter<string>

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

Examples

Put

const nameSchema = string().default('Pikachu')
// 👇 Similar to
const nameSchema = string().putDefault('Pikachu')
// 👇 ...or
const nameSchema = string({
  defaults: {
    key: undefined,
    put: 'Pikachu',
    update: undefined
  }
})

// 🙌 Getters also work!
const nameSchema = string().default(() => 'Pikachu')

Key

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

Update

// 👇 Records the date at each update
const lastUpdatedSchema = string().updateDefault(() =>
  new Date().toISOString()
)
// 👇 Similar to
const lastUpdatedSchema = string({
  defaults: {
    key: undefined,
    put: undefined,
    update: () => new Date().toISOString()
  }
})

.link<Schema>(...)

Link<SCHEMA, string>

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

const pokemonSchema = schema({
  level: string()
}).and(prevSchema => ({
  captureLevel: string().link<typeof prevSchema>(
    // 🙌 Correctly typed!
    item => item.level
  )
}))

.validate(...)

Validator<string>

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

Examples

const longStrSchema = string().validate(
  input => input.length > 3
)
// 👇 Similar to
const longStrSchema = string().putValidate(
  input => input.length > 3
)
// 👇 ...or
const longStrSchema = string({
  validators: {
    key: undefined,
    put: input => input.length > 3,
    update: undefined
  }
})