`Noggin`

The primary handle every consumer uses to read a noggin's state and drive verbs. Same shape whether the noggin lives in-process behind a provider or behind an RPC transport.

A live noggin. The handle every consumer uses to drive verbs and read state — independent of whether the noggin lives in this process or behind an RPC transport.

Two implementations satisfy this shape today:

- In-process providers (MemoryNoggin, FileNoggin etc.). They also satisfy the wider NogginStore contract, which adds the atomic apply() primitive that verbs use internally. - RemoteNoggin from @noggin/rpc, which dispatches verbs over a JSON-RPC transport. Local accessors stay synchronous because RemoteNoggin mirrors the server's state into a memory noggin and reconciles on each noggin.changed notification.

Storage-tracking contract: - Accessors always reflect the latest known state. - onDidChange fires after every mutation (in-process, externally observed, or remote). After it fires, accessors are up to date.

Verb method semantics mirror the free verbs.*(noggin, opts) namespace: same option shapes, same return types, same error codes. They're convenience bindings — noggin.push(opts) is identical to verbs.push(noggin, opts) for in-process callers. Hosts and UI components should prefer the methods so the same code works against any noggin.

Extended by

NogginStore

Properties

Property	Modifier	Type	Description
`active`	`readonly`	`Item`	-
`items`	`readonly`	readonly `Item`[]	-
`location`	`readonly`	`string`	Canonical URL the provider opened. Mirrors the `location` the caller passed to `openNoggin` (e.g. `file:///work/today.yaml`, `memory://scratch`, `localstorage://groceries`).
`onDidChange`	`readonly`	`Event`<`ChangeEvent`>	-
`onDidError`	`readonly`	`Event`<`NogginError`>	-
`readOnly`	`readonly`	`boolean`	When `true`, the provider has declared this noggin read-only. Every `apply()` call will reject with `NogginError({ code: 'read-only' })`. UIs read this to gate mutation affordances preemptively rather than waiting for a failed round-trip. A provider is responsible for keeping the noggin's in-memory state in sync with its backing store on its own — via watchers for the fast path plus polling as a safety net. There is no `refresh()` verb because callers shouldn't need to know when a provider might have missed an external change: they observe `onDidChange` and trust the accessors.
`roots`	`readonly`	readonly `Item`[]	-

Methods

add()

add(opts: AddOptions): Promise<CurrentTreeView>;

Create a child without making it active.

Parameters

Parameter	Type
`opts`	`AddOptions`

Returns

Promise<CurrentTreeView>

childrenOf()

childrenOf(k: string): readonly Item[];

Parameters

Parameter	Type
`k`	`string`

Returns

readonly Item[]

delete()

delete(opts: DeleteOptions): Promise<DeleteResult>;

Remove an item (and optionally its subtree).

Parameters

Parameter	Type
`opts`	`DeleteOptions`

Returns

Promise<DeleteResult>

describe()

describe(): string;

Human-readable description of where this noggin lives. Not machine-parseable.

Returns

string

dispose()

dispose(): Promise<void>;

Release provider resources. After dispose the noggin is unusable.

Returns

Promise<void>

done()

done(opts?: DoneOptions): Promise<CurrentTreeView>;

Mark target done and surface to its parent. Idempotent.

Parameters

Parameter	Type
`opts?`	`DoneOptions`

Returns

Promise<CurrentTreeView>

edit()

edit(opts: EditOptions): Promise<CurrentTreeView>;

Idempotent mutation of an item's done state and/or title.

Parameters

Parameter	Type
`opts`	`EditOptions`

Returns

Promise<CurrentTreeView>

findByKey()

findByKey(k: string): Item;

Parameters

Parameter	Type
`k`	`string`

Returns

Item

goto()

goto(opts: GotoOptions): Promise<CurrentTreeView>;

Make the item at the given path active.

Parameters

Parameter	Type
`opts`	`GotoOptions`

Returns

Promise<CurrentTreeView>

move()

move(opts: MoveOptions): Promise<CurrentTreeView>;

Relocate an item under a new parent / among siblings.

Parameters

Parameter	Type
`opts`	`MoveOptions`

Returns

Promise<CurrentTreeView>

note()

note(opts: NoteOptions): Promise<CurrentTreeView>;

Append a timestamped note to an item.

Parameters

Parameter	Type
`opts`	`NoteOptions`

Returns

Promise<CurrentTreeView>

pathOf()

pathOf(item: Item): string;

Parameters

Parameter	Type
`item`	`Item`

Returns

string

pop()

pop(opts?: PopOptions): Promise<CurrentTreeView>;

Shorthand for done on the active item.

Parameters

Parameter	Type
`opts?`	`PopOptions`

Returns

Promise<CurrentTreeView>

push()

push(opts: PushOptions): Promise<CurrentTreeView>;

Create a child of active and immediately become it.

Parameters

Parameter	Type
`opts`	`PushOptions`

Returns

Promise<CurrentTreeView>

show()

show(opts?: ShowOptions): Promise<CurrentTreeView>;

Render the current-position view (spine + peers + first-level children).

Parameters

Parameter	Type
`opts?`	`ShowOptions`

Returns

Promise<CurrentTreeView>

tryResolvePath()

tryResolvePath(p: string): Item;

Parameters

Parameter	Type
`p`	`string`

Returns

Item