PathParser

Builds a Projection Expression that can be used to filter the returned attributes of a read operation like a GetItem, Query or Scan:

import { PathParser } from 'dynamodb-toolbox/entity/actions/parsePaths'

// 👇 To be used in DynamoDB commands
const { ProjectionExpression, ExpressionAttributeNames } =
  PokemonEntity.build(PathParser).parse(['name', 'level'])

Methods

transform(...)

(paths: Path<ENTITY>[], opt?: Options) => string[]

Validates the paths for the provided Entity and transforms them to match the underlying data if needed:

const pokemonSchema = item({
  name: string(),
  level: number().savedAs('_l')
  ...
})

PokemonEntity.build(PathParser).transform(['name', 'level'])
// => ['name', '_l']

By default, the method expects all the paths to be valid for the provided Entity and throws an invalidExpressionAttributePath error if not. You can unset the strict option to skip invalid paths:

const pokemonSchema = item({
  name: string(),
  level: number().savedAs('_l')
  ...
})

PokemonEntity.build(PathParser).transform(
  ['name', 'level', 'unknown.path'],
  { strict: false }
)
// => ['name', '_l']

info

Note that the transform(...) method may add paths if several options of an anyOf attribute match a provided path:

🔎 Show example

const pokemonSchema = item({
  meta: anyOf(
    map({ description: string() }),
    map({ description: string().savedAs('d') })
    ...
  )
  ...
})

PokemonEntity.build(PathParser).transform(['meta.description'])
// => ['meta.description', 'meta.d']

express(...)

static (paths: string[]) => ProjectionExpression

Translates any path list to a DynamoDB Projection Expression:

PathParser.express(['name', 'level'])
// => {
//   ProjectionExpression: '#p_1, #p_2',
//   ExpressionAttributeNames: {
//     '#p_1': 'name',
//     '#p_2': 'level'
//   },
// }

caution

The method's static nature emphasizes that it does not validate the paths. It should only be used on transformed paths.

parse(...)

(paths: Path<ENTITY>[]) => ProjectionExpression

Subsequently transform and express paths for the provided Entity:

PokemonEntity.build(PathParser).parse(['name', 'level'])
// => {
//   ProjectionExpression: '#p_1, #p_2',
//   ExpressionAttributeNames: {
//     '#p_1': 'name',
//     '#p_2': 'level'
//   },
// }

Paths

The path syntax from DynamoDB-Toolbox follows the DynamoDB specifications, while making it type-safe and simpler:

import type { EntityPaths } from 'dynamodb-toolbox/entity/actions/parsePaths'

type PokemonPath = EntityPaths<typeof PokemonEntity>

const namePath: PokemonPath = 'name'

const deepListPath: PokemonPath = 'pokeTypes[0]'

const deepMapOrRecordPath: PokemonPath = 'weaknesses.fire'
// 👇 Similar to
const deepMapOrRecordPath: PokemonPath = `weaknesses['fire']`

// 👇 Use this syntax to escape special chars (e.g. in `records`)
const deepRecordPath: PokemonPath = `meta['any[char]-you.want!']`