Binary

Describes binary values:

import { binary } from 'dynamodb-toolbox/schema/binary'

const hashSchema = binary()

type Hash = FormattedValue<typeof hashSchema>
// => Uint8Array

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

Omits schema values during formatting:

const hashSchema = binary().hidden()
const hashSchema = binary({ 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 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 schema values during the transformation step (within items or 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 input props.

.transform(...)

Transformer<Uint8Array>

Allows modifying schema values during the transformation step:

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

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

    return concat
  },
  decode: (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. 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({ putDefault: bin })

// 🙌 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({
  key: true,
  required: 'always',
  keyDefault: bin
})

Update

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

const hashSchema = binary().updateDefault(bin)
// 👇 Similar to
const hashSchema = binary({ updateDefault: 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 = item({
  name: string()
}).and(prevSchema => ({
  nameHash: binary().link<typeof prevSchema>(
    // 🙌 Correctly typed!
    item => encoder.encode(item.name)
  )
}))

.validate(...)

Validator<Uint8Array>

Adds custom validation. 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({
  putValidator: input => input.length > 3
})