Skip to main content

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

.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
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)

.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
  }
})