Binary

Defines a binary attribute:

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

const pokemonSchema = schema({
  ...
  hash: binary(),
});

type FormattedPokemon = FormattedItem<typeof PokemonEntity>;
// => {
//   ...
//   hash: Uint8Array
// }

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

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

.hidden()

boolean | undefined

Skips the attribute when formatting items:

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

info

key() is not restricted to the primary key attributes but also to the attributes they are be linked to.

.savedAs(...)

string

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

const hashSchema = binary().savedAs('h')
const hashSchema = binary({ savedAs: 'h' })

.enum(...)

Uint8Array[]

Provides a finite range of possible values:

const binA = new Uint8Array([1, 2, 3])
const binB = new Uint8Array([4, 5, 6])

const hashSchema = binary().enum(binA, binB, ...)

// 👇 Equivalent to `.enum(binA).default(binA)`
const hashSchema = binary().const(binA)

info

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

.transform(...)

Transformer<Uint8Array>

Allows modifying the attribute values during the transformation step:

const PREFIX = new Uint8Array([1, 2, 3])

const prefix = {
  parse: (input: Uint8Array) => {
    const concat = new Uint8Array(
      PREFIX.length + input.length
    )
    concat.set(PREFIX)
    concat.set(input, PREFIX.length)

    return concat
  },
  format: (saved: Uint8Array) => saved.slice(PREFIX.length)
}

// Prefixes the value
const hashSchema = binary().transform(prefix)
const hashSchema = binary({ transform: prefix })

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

.default(...)

ValueOrGetter<Uint8Array>

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

Examples

Put

const bin = new Uint8Array([1, 2, 3])

const hashSchema = binary().default(bin)
// 👇 Similar to
const hashSchema = binary().putDefault(bin)
// 👇 ...or
const hashSchema = binary({
  defaults: {
    key: undefined,
    put: bin,
    update: undefined
  }
})

// 🙌 Getters also work!
const hashSchema = binary().default(() => bin)

Key

const bin = new Uint8Array([1, 2, 3])

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

Update

const bin = new Uint8Array([1, 2, 3])

const hashSchema = binary().updateDefault(bin)
// 👇 Similar to
const hashSchema = binary({
  defaults: {
    key: undefined,
    put: undefined,
    update: bin
  }
})

.link<Schema>(...)

Link<SCHEMA, Uint8Array>

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

const encoder = new TextEncoder()

const pokemonSchema = schema({
  name: string()
}).and(prevSchema => ({
  nameHash: binary().link<typeof prevSchema>(
    // 🙌 Correctly typed!
    item => encoder.encode(item.name)
  )
}))

.validate(...)

Validator<Uint8Array>

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

Examples

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