Paths

Paths

See also (AWS JS SDK v3): Document paths in DynamoDB (the same path semantics the SDK uses in expressions). Vocabulary: Concepts.

dynamodb-toolkit/paths exports pure utility functions for nested-path access on plain JS objects. No SDK involvement — these are useful for shaping items before/after DynamoDB calls or building recursive prepare / revive hooks.

import {getPath, setPath, deletePath, applyPatch, normalizeFields, subsetObject} from 'dynamodb-toolkit/paths';

Path semantics

• Default separator is '.'. Pass a different one as the last argument.
• Pure-digit segments are array indices: 'tags.0' reads the first element of the tags array.
• Missing intermediate nodes:
  • getPath returns the supplied default value (or undefined).
  • setPath creates them (objects for non-numeric, arrays for numeric segments).
  • deletePath is a no-op.

getPath(obj, path, defaultValue?, separator?)

getPath({a: {b: {c: 1}}}, 'a.b.c');           // 1
getPath({a: {b: {}}}, 'a.b.c', 'fallback');   // 'fallback'
getPath({tags: ['x', 'y']}, 'tags.1');         // 'y'

setPath(obj, path, value, separator?)

Mutates obj in place, returns obj. Creates intermediate containers as needed.

const obj = {};
setPath(obj, 'a.b.0', 'x');
// obj === {a: {b: ['x']}}

deletePath(obj, path, separator?)

Removes the leaf at path. Mutates and returns obj. Leaves intermediate nodes intact.

const obj = {a: {b: {c: 1, d: 2}}};
deletePath(obj, 'a.b.c');
// obj === {a: {b: {d: 2}}}

applyPatch(obj, patch, options?)

Applies a flat patch object to an in-memory item using setPath for each key, plus options.delete for deletePath.

const obj = {name: 'Hoth', config: {gravity: '1g'}};
applyPatch(obj, {'config.gravity': '1.5g', 'climate': 'frozen'}, {delete: ['old_field']});
// obj === {name: 'Hoth', config: {gravity: '1.5g'}, climate: 'frozen'}

interface ApplyPatchOptions {
  delete?: string[];
  separator?: string;
}

This mirrors what the DynamoDB UpdateExpression does — useful for client-side preview of pending updates, optimistic UI, etc.

normalizeFields(fields, projectionFieldMap?, separator?)

Coerces field specifications into a string[] | null. Accepts string, comma-separated string, array, object (keys taken). Applies an alias map to the first segment of each path.

normalizeFields('name,climate,terrain');      // ['name','climate','terrain']
normalizeFields({a: 1, b: 1, c: 1});          // ['a', 'b', 'c']
normalizeFields(['desc'], {desc: 'description'}); // ['description']

subsetObject(obj, fields, separator?)

Returns a new object containing only the requested fields/paths. Used by the default revive hook when fields is supplied.

subsetObject({a: 1, b: 2, c: {x: 10, y: 20}}, ['a', 'c.x']);
// → {a: 1, c: {x: 10}}

Missing fields are silently omitted (no undefined key in the result).