@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/utils/README.md

@@ -44,38 +44,6 @@ flowchart TD
 
 ## utils/memory.ts
 
-### MemoryStats
-
-Detailed statistics describing the current estimated memory footprint of
-tracked networks plus supporting pools.
-
-Important: All byte counts here are *estimates*. JavaScript engine object
-overhead varies; once slab (Structure of Arrays) storage dominates, these
-estimates get closer to real usage. Treat values as relative metrics for
-comparing configurations (e.g. before / after enabling pooling) rather than
-exact allocations.
-
-The payload is easiest to read as four cooperating layers:
-
-- `connections`, `nodes`, and `estimatedTotalBytes` summarize the tracked
-  network footprint itself,
-- `slabs` explains how much typed-array storage exists and how much of the
-  reserved connection capacity is currently used,
-- `pools` shows whether reusable allocation infrastructure is active,
-- `env` exposes the coarser browser or Node memory readings that surround the
-  heuristic network view.
-
-### NetworkView
-
-Minimal view of a network used for memory heuristics. Only properties
-accessed by this module are declared. This keeps coupling light while
-enabling typed local variables instead of loose catch-all types everywhere.
-
-### SlabAllocStats
-
-Minimal slab allocator stats shape used here. The real shape may
-include additional fields; we only rely on fresh/pooled counts.
-
 ### memoryStats
 
 ```ts
@@ -109,20 +77,32 @@ const snapshot = memoryStats();
 console.log(snapshot.estimatedTotalBytes, snapshot.slabs.fragmentationPct);
 ```
 
-### resetMemoryTracking
+### MemoryStats
 
-```ts
-resetMemoryTracking(): void
-```
+Detailed statistics describing the current estimated memory footprint of
+tracked networks plus supporting pools.
 
-Clear the internal list of networks tracked by `memoryStats()` when no
-explicit networks are provided. This does NOT free memory; it only
-removes references held by the registry.
+Important: All byte counts here are *estimates*. JavaScript engine object
+overhead varies; once slab (Structure of Arrays) storage dominates, these
+estimates get closer to real usage. Treat values as relative metrics for
+comparing configurations (e.g. before / after enabling pooling) rather than
+exact allocations.
 
-Use this when a teaching example, benchmark, or test wants a fresh registry
-boundary before capturing the next snapshot.
+The payload is easiest to read as four cooperating layers:
 
-Returns: void
+- `connections`, `nodes`, and `estimatedTotalBytes` summarize the tracked
+  network footprint itself,
+- `slabs` explains how much typed-array storage exists and how much of the
+  reserved connection capacity is currently used,
+- `pools` shows whether reusable allocation infrastructure is active,
+- `env` exposes the coarser browser or Node memory readings that surround the
+  heuristic network view.
+
+### NetworkView
+
+Minimal view of a network used for memory heuristics. Only properties
+accessed by this module are declared. This keeps coupling light while
+enabling typed local variables instead of loose catch-all types everywhere.
 
 ### registerTrackedNetwork
 
@@ -146,6 +126,26 @@ Parameters:
 
 Returns: void
 
+### resetMemoryTracking
+
+```ts
+resetMemoryTracking(): void
+```
+
+Clear the internal list of networks tracked by `memoryStats()` when no
+explicit networks are provided. This does NOT free memory; it only
+removes references held by the registry.
+
+Use this when a teaching example, benchmark, or test wants a fresh registry
+boundary before capturing the next snapshot.
+
+Returns: void
+
+### SlabAllocStats
+
+Minimal slab allocator stats shape used here. The real shape may
+include additional fields; we only rely on fresh/pooled counts.
+
 ### unregisterTrackedNetwork
 
 ```ts
@@ -197,44 +197,44 @@ flowchart LR
   Build --> Payload[MemoryStats]
 ```
 
-### normalizeNetworks
+### accumulateCapacitySlices
 
 ```ts
-normalizeNetworks(
-  targets: NetworkView | NetworkView[] | undefined,
-  trackedNetworks: NetworkView[],
-): NetworkView[]
+accumulateCapacitySlices(
+  accumulators: Accumulators,
+  network: NetworkView,
+  heuristics: HeuristicBytes,
+): void
 ```
 
-Normalize provided targets to an array of networks, falling back to tracked registry.
-
-This helper keeps the public entrypoint flexible without making later
-aggregation code branch on every call path.
+Track reserved vs used bytes based on connection capacity slices.
 
 Parameters:
-- `targets` - Optional single network or array.
-- `trackedNetworks` - Internal registry of tracked networks.
-
-Returns: Array of networks to summarize.
+- `accumulators` - Running totals for the memory snapshot.
+- `network` - Network exposing capacity metadata.
+- `heuristics` - Fallback byte weights for connection objects.
 
-### safeGetSlabAllocationStats
+### accumulateSlabArrays
 
 ```ts
-safeGetSlabAllocationStats(
-  getSlabAllocationStats: () => unknown,
-): SlabAllocStats
+accumulateSlabArrays(
+  accumulators: Accumulators,
+  typedArrays: (Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int32Array<ArrayBufferLike>)[],
+): void
 ```
 
-Safely read slab allocation stats, guarding against provider errors.
-
-Allocator telemetry is useful but optional. A failed probe should degrade the
-snapshot gracefully instead of turning diagnostics into a source of runtime
-failures.
+Sum slab-backed array counts and byte sizes into the accumulator.
 
 Parameters:
-- `getSlabAllocationStats` - Provider function returning allocator stats.
+- `accumulators` - Running totals for the memory snapshot.
+- `typedArrays` - Connection-parallel arrays to measure.
 
-Returns: Slab allocation stats or null on failure.
+### Accumulators
+
+Running totals used while walking networks to summarize memory consumption.
+Accumulates counts, slab byte totals, and reserved vs used capacity
+snapshots. This is the file's working ledger before the public-facing
+`MemoryStats` object is assembled.
 
 ### aggregateNetworkStats
 
@@ -258,20 +258,33 @@ Parameters:
 
 Returns: Accumulated summary of network metrics.
 
-### captureEnvironmentMetrics
+### buildFlagSnapshot
 
 ```ts
-captureEnvironmentMetrics(): { isBrowser: boolean; usedJSHeapSize?: number | undefined; totalJSHeapSize?: number | undefined; jsHeapSizeLimit?: number | undefined; rss?: number | undefined; heapUsed?: number | undefined; heapTotal?: number | undefined; external?: number | undefined; }
+buildFlagSnapshot(
+  configSnapshot: ConfigSnapshot,
+  allocationStats: SlabAllocStats,
+): { warnings: unknown; float32Mode: unknown; deterministicChainMode: unknown; enableGatingTraces: unknown; poolMaxPerBucket: number | null; poolPrewarmCount: number | null; enableNodePooling: boolean; allocStats: unknown; }
 ```
 
-Capture environment memory metrics from browser or Node when available.
+Build flag snapshot derived from config and allocator stats.
 
-The environment block complements the network-centric heuristics. It is not
-specific enough to explain every connection or node, but it helps readers see
-whether the broader runtime is moving in the same direction as the network
-summary.
+Flag snapshots explain *why* the memory picture may look the way it does by
+capturing the small set of runtime options that materially alter pooling,
+slab layout, and feature-gated storage paths.
 
-Returns: Environment metrics structure for the snapshot.
+Parameters:
+- `configSnapshot` - Relevant configuration values.
+- `allocationStats` - Allocator stats (nullable on failure).
+
+Returns: Flags snapshot for MemoryStats.
+
+### BuildMemoryStatsInput
+
+Structured inputs required to assemble a MemoryStats snapshot in one pass.
+Bundles precomputed accumulators, environment info, allocator stats, and
+flags. This keeps the final snapshot builder declarative: collect first,
+then fold into the public payload.
 
 ### buildMemoryStatsSnapshot
 
@@ -292,96 +305,84 @@ Parameters:
 
 Returns: Complete MemoryStats snapshot.
 
-### buildFlagSnapshot
+### buildSlabStats
 
 ```ts
-buildFlagSnapshot(
-  configSnapshot: ConfigSnapshot,
+buildSlabStats(
+  accumulators: Accumulators,
+  networksToSummarize: NetworkView[],
   allocationStats: SlabAllocStats,
-): { warnings: unknown; float32Mode: unknown; deterministicChainMode: unknown; enableGatingTraces: unknown; poolMaxPerBucket: number | null; poolPrewarmCount: number | null; enableNodePooling: boolean; allocStats: unknown; }
+): { slabBytes: number; slabArrayCount: number; fragmentationPct: number | null; reservedBytes: number | null; usedBytes: number | null; slabVersion: number | null; asyncBuilds: number; pooledFraction: number | null; }
 ```
 
-Build flag snapshot derived from config and allocator stats.
-
-Flag snapshots explain *why* the memory picture may look the way it does by
-capturing the small set of runtime options that materially alter pooling,
-slab layout, and feature-gated storage paths.
+Assemble slab-related statistics for the MemoryStats payload.
 
 Parameters:
-- `configSnapshot` - Relevant configuration values.
-- `allocationStats` - Allocator stats (nullable on failure).
-
-Returns: Flags snapshot for MemoryStats.
-
-### HeuristicBytes
-
-Heuristic byte weights used to approximate per-object overhead in the allocator.
-These numbers represent typical JS object footprints, not exact runtime
-measurements. They are teaching weights: stable enough to compare runs and
-storage strategies even when the engine's true overhead is more complicated.
-
-### Accumulators
+- `accumulators` - Running totals collected during aggregation.
+- `networksToSummarize` - Networks included in the snapshot.
+- `allocationStats` - Optional allocator stats for pooled fraction.
 
-Running totals used while walking networks to summarize memory consumption.
-Accumulates counts, slab byte totals, and reserved vs used capacity
-snapshots. This is the file's working ledger before the public-facing
-`MemoryStats` object is assembled.
+Returns: Structured slab metrics block.
 
-### ConfigSnapshot
+### calculateFragmentation
 
-Captured configuration knobs that influence memory usage and pooling behavior.
-Keeps only the flags relevant to the memory snapshot to avoid leaking full
-config. The goal is to explain the memory story, not to smuggle the entire
-runtime configuration surface into a diagnostic payload.
+```ts
+calculateFragmentation(
+  accumulators: Accumulators,
+): number | null
+```
 
-### BuildMemoryStatsInput
+Compute fragmentation percentage from reserved vs used connection bytes.
 
-Structured inputs required to assemble a MemoryStats snapshot in one pass.
-Bundles precomputed accumulators, environment info, allocator stats, and
-flags. This keeps the final snapshot builder declarative: collect first,
-then fold into the public payload.
+Parameters:
+- `accumulators` - Running totals holding reserved and used bytes.
 
-### CONNECTION_OBJECT_BYTES
+Returns: Fragmentation percent (0-100) or null when undefined.
 
-Estimated per-connection JS object footprint in bytes (includes metadata fields).
-Used as a fallback when typed-array parallel data is unavailable.
+### calculatePooledFraction
 
-### NODE_OBJECT_BYTES
+```ts
+calculatePooledFraction(
+  allocationStats: SlabAllocStats,
+): number | null
+```
 
-Estimated per-node JS object footprint in bytes, covering activation state and IDs.
-This heuristic keeps node weight comparable to connection objects during summaries.
+Calculate pooled fraction from allocator stats with four-decimal precision.
 
-### HEURISTIC_BYTES
+Parameters:
+- `allocationStats` - Allocator snapshot or null when unavailable.
 
-Default heuristics mapping human-readable weights to their byte estimates.
-Centralizes the fallback values so downstream summaries stay consistent.
-Read this as the chapter's shared baseline for "object-heavy" accounting
-when typed-array widths are unavailable or incomplete.
+Returns: Fraction of pooled allocations or null if indeterminate.
 
-### createEmptyAccumulators
+### captureEnvironmentMetrics
 
 ```ts
-createEmptyAccumulators(): Accumulators
+captureEnvironmentMetrics(): { isBrowser: boolean; usedJSHeapSize?: number | undefined; totalJSHeapSize?: number | undefined; jsHeapSizeLimit?: number | undefined; rss?: number | undefined; heapUsed?: number | undefined; heapTotal?: number | undefined; external?: number | undefined; }
 ```
 
-Initialize a fresh accumulator snapshot for memory summaries.
+Capture environment memory metrics from browser or Node when available.
 
-Returns: Zeroed accumulators ready for aggregation.
+The environment block complements the network-centric heuristics. It is not
+specific enough to explain every connection or node, but it helps readers see
+whether the broader runtime is moving in the same direction as the network
+summary.
 
-### computeCounts
+Returns: Environment metrics structure for the snapshot.
+
+### captureVersionMetadata
 
 ```ts
-computeCounts(
+captureVersionMetadata(
+  accumulators: Accumulators,
   network: NetworkView,
-): CountSnapshot
+): void
 ```
 
-Capture simple counts for nodes and connections on a network view.
+Capture slab metadata (version and async builds) once across all networks.
 
 Parameters:
-- `network` - Network being summarized.
-
-Returns: Connection and node counts.
+- `accumulators` - Running totals with metadata slots.
+- `network` - Network providing slab metadata fields.
 
 ### collectConnectionTypedArrays
 
@@ -398,37 +399,42 @@ Parameters:
 
 Returns: Typed arrays aligned to connections.
 
-### accumulateSlabArrays
+### computeCounts
 
 ```ts
-accumulateSlabArrays(
-  accumulators: Accumulators,
-  typedArrays: (Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int32Array<ArrayBufferLike>)[],
-): void
+computeCounts(
+  network: NetworkView,
+): CountSnapshot
 ```
 
-Sum slab-backed array counts and byte sizes into the accumulator.
+Capture simple counts for nodes and connections on a network view.
 
 Parameters:
-- `accumulators` - Running totals for the memory snapshot.
-- `typedArrays` - Connection-parallel arrays to measure.
+- `network` - Network being summarized.
 
-### accumulateCapacitySlices
+Returns: Connection and node counts.
+
+### ConfigSnapshot
+
+Captured configuration knobs that influence memory usage and pooling behavior.
+Keeps only the flags relevant to the memory snapshot to avoid leaking full
+config. The goal is to explain the memory story, not to smuggle the entire
+runtime configuration surface into a diagnostic payload.
+
+### CONNECTION_OBJECT_BYTES
+
+Estimated per-connection JS object footprint in bytes (includes metadata fields).
+Used as a fallback when typed-array parallel data is unavailable.
+
+### createEmptyAccumulators
 
 ```ts
-accumulateCapacitySlices(
-  accumulators: Accumulators,
-  network: NetworkView,
-  heuristics: HeuristicBytes,
-): void
+createEmptyAccumulators(): Accumulators
 ```
 
-Track reserved vs used bytes based on connection capacity slices.
+Initialize a fresh accumulator snapshot for memory summaries.
 
-Parameters:
-- `accumulators` - Running totals for the memory snapshot.
-- `network` - Network exposing capacity metadata.
-- `heuristics` - Fallback byte weights for connection objects.
+Returns: Zeroed accumulators ready for aggregation.
 
 ### describeConnectionBytes
 
@@ -447,66 +453,60 @@ Parameters:
 
 Returns: Estimated bytes per connection entry.
 
-### captureVersionMetadata
-
-```ts
-captureVersionMetadata(
-  accumulators: Accumulators,
-  network: NetworkView,
-): void
-```
-
-Capture slab metadata (version and async builds) once across all networks.
-
-Parameters:
-- `accumulators` - Running totals with metadata slots.
-- `network` - Network providing slab metadata fields.
+### HEURISTIC_BYTES
 
-### buildSlabStats
+Default heuristics mapping human-readable weights to their byte estimates.
+Centralizes the fallback values so downstream summaries stay consistent.
+Read this as the chapter's shared baseline for "object-heavy" accounting
+when typed-array widths are unavailable or incomplete.
 
-```ts
-buildSlabStats(
-  accumulators: Accumulators,
-  networksToSummarize: NetworkView[],
-  allocationStats: SlabAllocStats,
-): { slabBytes: number; slabArrayCount: number; fragmentationPct: number | null; reservedBytes: number | null; usedBytes: number | null; slabVersion: number | null; asyncBuilds: number; pooledFraction: number | null; }
-```
+### HeuristicBytes
 
-Assemble slab-related statistics for the MemoryStats payload.
+Heuristic byte weights used to approximate per-object overhead in the allocator.
+These numbers represent typical JS object footprints, not exact runtime
+measurements. They are teaching weights: stable enough to compare runs and
+storage strategies even when the engine's true overhead is more complicated.
 
-Parameters:
-- `accumulators` - Running totals collected during aggregation.
-- `networksToSummarize` - Networks included in the snapshot.
-- `allocationStats` - Optional allocator stats for pooled fraction.
+### NODE_OBJECT_BYTES
 
-Returns: Structured slab metrics block.
+Estimated per-node JS object footprint in bytes, covering activation state and IDs.
+This heuristic keeps node weight comparable to connection objects during summaries.
 
-### calculateFragmentation
+### normalizeNetworks
 
 ```ts
-calculateFragmentation(
-  accumulators: Accumulators,
-): number | null
+normalizeNetworks(
+  targets: NetworkView | NetworkView[] | undefined,
+  trackedNetworks: NetworkView[],
+): NetworkView[]
 ```
 
-Compute fragmentation percentage from reserved vs used connection bytes.
+Normalize provided targets to an array of networks, falling back to tracked registry.
+
+This helper keeps the public entrypoint flexible without making later
+aggregation code branch on every call path.
 
 Parameters:
-- `accumulators` - Running totals holding reserved and used bytes.
+- `targets` - Optional single network or array.
+- `trackedNetworks` - Internal registry of tracked networks.
 
-Returns: Fragmentation percent (0-100) or null when undefined.
+Returns: Array of networks to summarize.
 
-### calculatePooledFraction
+### safeGetSlabAllocationStats
 
 ```ts
-calculatePooledFraction(
-  allocationStats: SlabAllocStats,
-): number | null
+safeGetSlabAllocationStats(
+  getSlabAllocationStats: () => unknown,
+): SlabAllocStats
 ```
 
-Calculate pooled fraction from allocator stats with four-decimal precision.
+Safely read slab allocation stats, guarding against provider errors.
+
+Allocator telemetry is useful but optional. A failed probe should degrade the
+snapshot gracefully instead of turning diagnostics into a source of runtime
+failures.
 
 Parameters:
-- `allocationStats` - Allocator snapshot or null when unavailable.
+- `getSlabAllocationStats` - Provider function returning allocator stats.
 
-Returns: Fraction of pooled allocations or null if indeterminate.
+Returns: Slab allocation stats or null on failure.