Supporting types: state, coordinates, collections, and callbacks

Manual contents | State management | Tools and utilities | Quick reference | Alphabetical index

This reference explains the small types used by the Main, Patch, and Turtle APIs. Examples assume aligned lifecycle where a running world is involved. It is not a reference for Stocks, integration machinery, or every class in the runtime. A type's existence does not make its internal lifecycle methods safe to call directly.

1. Store: current, next, and initial

Source: store.js. Import with import {Store} from "@nwk/api/store.js";. A Store holds arbitrary values, not just numbers. It has no automatic numeric validation, cloning, commitment schedule, or ownership inference.

Except shift/get/toString and the static factory, methods return undefined. Exceptions in factories/updaters/listeners propagate; operations do not roll back earlier mutations.

This standalone example calls shift itself to expose the distinction:

import {Store} from "@nwk/api/store.js";

const state = new Store(2);
state.next = 3;
const before = state.get();
state.shift();
const committed = state.get();
state.set(4);
state.reinitialize();
const restored = state.get();

before is 2, committed 3, restored 2. In a model, allocate once, call main.synchronize(state) once, propose with next, and restore explicitly in the owner's reset. Built-in properties already provide synchronization; use their public interfaces instead of private Stores. See state management.

Fields, notifications, and mutable values

• current, initial, updater, and listeners are implementation fields. Prefer methods/properties; direct current writes bypass synchronization and notification.
• _next is backing storage; initialValue is populated by initialize, not by construction. virgin is a runtime initialization flag, based on the truthiness of the constructor's evaluated value, then false after initialize. It is not a general "has never changed" flag.
• nextPinger is assigned by synchronization helpers; replacing it replaces that wiring. initializePinger is an optional one-argument callback receiving the new value; pinger is an optional zero-argument set callback. Capitalized InitializePinger is not a Store callback.
• Change listeners fire even for equal-value shifts. initialize/reinitialize reports a falsy old value as null; set/shift preserve the actual old value. Registration has no equality guard or disposal mechanism.

Objects/arrays are shared by reference. In-place mutation can change current, next, and reset baseline together. A reset factory creates fresh state:

const bag = new Store(() => ({food: 4}));
const original = bag.get();
bag.next = {food: 1};
bag.shift();
bag.reinitialize();
const fresh = bag.get();

fresh is a new {food: 4}, distinct from original. Factory evaluation is specific to constructor/initialize/reinitialize; assigning next a function stores a function rather than running it.

The same module exports Pinger, a minimal legacy wrapper whose constructor(ping) stores a .ping field. It does not subscribe, call the function, synchronize, or define reset policy. Ordinary models do not need it.

2. Property: immediate value with removable listeners

Source: tools.js. Property is not a Store: no next, shift, reset baseline, or synchronization.

Changing number 1 to string "1" stores the string but suppresses notification. Mutating an object in place is not detected. Listeners execute synchronously; exceptions propagate. Use Property for an immediate selection/control value, not a synchronous environmental quantity.

import {Property} from "@nwk/api/tools.js";

const selected = new Property(1);
const observations = [];
const listener = (property, oldValue, value) => observations.push([oldValue, value]);
selected.addListener(listener);
selected.value = "1";
selected.set(2);
selected.removeListener(listener);
selected.set(3);

observations contains just ["1", 2], nested as one entry.

3. Coordinates and CoordsFactory

Source: coordsfactory.js. CoordsFactory is exported; its Coords implementation is not. Normally obtain coordinates with this.newCoords(x, y), not a direct import of Coords. Creating coordinates neither moves/indexes an agent nor wraps/clamps.

Two coordinates with the same numbers are not the same object identity; Set/includes deduplicates identity, not coordinate equality.

import {CoordsFactory} from "@nwk/api/coordsfactory.js";

const factory = new CoordsFactory(10, 10);
const a = factory.create(1.5, 2.5);
const b = factory.create(1.5, 2.5);
const samePosition = a.x === b.x && a.y === b.y;
const sameObject = a === b;

samePosition is true, sameObject false. Movement calculations accumulate floating-point roundoff; use a tolerance rather than exact equality for such positions. Repaired radius/query helpers accept finite public x/y or col/row objects, sometimes legacy callable coordinates too; this does not change the requirements of every older coordinate method.

4. Collections: know what the operation returns

Sources: nlmatrix.js, nlvector.js, and agentgrid.js.

NLMatrix.forEach/filter call callbacks with patch values; array callback arguments can also include index/array. Matrix visit instead takes coordinates. Avoid inherited NLRoot.filter's legacy matrix overload; use patches.toList().filter(predicate).

AgentSet and AgentList details

Do not edit occupancy Sets or population maps directly to create/remove agents; runtime insertion/unlinking maintains relationships. Main population traversal includes entries that may still be hidden from local queries. Snapshots retain old turtle references after death/world reset; fetch residents again when needed. See population timing.

5. Callback signature lookup

A callback is a function passed to an operation. It is not automatically executed with this bound to the visited object. Arrow functions retain enclosing this; ordinary callbacks need the documented arguments/binding.

Callbacks are synchronous unless the particular API says otherwise. Returning false from a patch visitor does not break the traversal. These operations do not provide transaction rollback after a callback throws.

6. Enums and runtime choices

Source: tools.js.

The result object is frozen, but its values array and Enum slot objects are not deeply frozen. Do not mutate them or reuse names such as values/ordinal which collide with helper members. Neither constructor validates a schema. Symbols are not portable JSON configuration values.

import {Enum, EnumSym} from "@nwk/api/tools.js";

const Health = Enum({name: "Susceptible"}, {name: "Infected"});
const Mode = EnumSym("Searching", "Resting");
const paletteIndex = Health.Infected.ord;
const selectedMode = Mode.Searching;

paletteIndex is 1; selectedMode is a Symbol, not the string "Searching". Use the slot when identity matters and ord when a numeric palette value is required. See named-state examples.

Supplied choices

All except Dir use EnumSym. Project uses corresponding strings, with its shape spellings "circle"/"rectangle"; runtime Turtle shape uses Shape Symbols. Dir diagonals have grid offsets +/-1, not Euclidean unit vectors. Do not confuse cell BoundaryMode with agent EdgeMode. See Project configuration for what each selection controls.

7. Scope and verification

The guide tests inventory the Store, Property, coordinate-factory/coordinate, AgentSet, and AgentList declarations documented here, execute this page's examples, and check mutable factory reset, notification arguments, visibility filtering, and sorting mutation. Existing guide tests exercise enum identity, population/index timing, array payload shapes, and synchronous state behavior.

This is not a per-member reference for internal AgentGrid/NLMatrix/NLVector construction, collision machinery, parameter/display managers, or Stocks. Their model-facing use is described here and in the class references. No runtime behavior is changed, and unsupported legacy methods remain labeled.