Path utilities

Pure walkers over a {items, active} document snapshot. Used inside verbs and provider implementations; hosts occasionally reach for them too when they want to resolve a path against a snapshot that isn't behind a live Noggin.

Noggin and NogginStore bind path-resolution helpers on the handle itself (noggin.pathOf(item), noggin.resolvePath(p)) — use those when you have a live noggin. The free functions below are for the offline / snapshot case.

resolvePath()

function resolvePath(snapshot: {
  active: string;
  items: Item[];
}, p: string): Item;

Resolve a path string against a doc-shaped {items, active} snapshot. Throws NogginError('path-not-found') if the path doesn't resolve.

Parameters

Parameter	Type
`snapshot`	{ `active`: `string`; `items`: `Item`[]; }
`snapshot.active`	`string`
`snapshot.items`	`Item`[]
`p`	`string`

Returns

Item

tryResolvePath()

function tryResolvePath(snapshot: {
  active: string;
  items: Item[];
}, p: string): Item;

Like resolvePath but returns null instead of throwing.

Parameters

Parameter	Type
`snapshot`	{ `active`: `string`; `items`: `Item`[]; }
`snapshot.active`	`string`
`snapshot.items`	`Item`[]
`p`	`string`

Returns

Item

pathOf()

function pathOf(snapshot: {
  items: Item[];
}, item: Item): string;

Compute the absolute path string for an item.

Parameters

Parameter	Type
`snapshot`	{ `items`: `Item`[]; }
`snapshot.items`	`Item`[]
`item`	`Item`

Returns

string

childrenOf()

function childrenOf(snapshot: {
  items: Item[];
}, parentKey: string): Item[];

Direct children of parentKey (null = roots), in tree order.

Parameters

Parameter	Type
`snapshot`	{ `items`: `Item`[]; }
`snapshot.items`	`Item`[]
`parentKey`	`string`

Returns

Item[]

buildView()

function buildView(
   snapshot: {
  active: string;
  items: readonly Item[];
}, 
   target: Item, 
   opts?: {
  includeChildren?: boolean;
  withDescendants?: boolean;
  withSiblings?: boolean;
}): CurrentTreeView;

Build a CurrentTreeView for target. Pure; does not mutate. Accepts a noggin or a {items, active} doc-shape.

Parameters

Parameter	Type
`snapshot`	{ `active`: `string`; `items`: readonly `Item`[]; }
`snapshot.active`	`string`
`snapshot.items`	readonly `Item`[]
`target?`	`Item`
`opts?`	{ `includeChildren?`: `boolean`; `withDescendants?`: `boolean`; `withSiblings?`: `boolean`; }
`opts.includeChildren?`	`boolean`
`opts.withDescendants?`	`boolean`
`opts.withSiblings?`	`boolean`

Returns

CurrentTreeView