@muggridge/substrate

High-performance, allocation-sensitive utility primitives and data structures optimized for the V8/JSC runtime.

Core Feature Checklist

• [ ] Enum - Smi-backed, boundary-checked execution backbone to replace standard string/object enums.

  • [ ] has: Type-guard via fast integer bounds verification.
  • [ ] derive: Tightly-packed, hole-free sequential lookup structures.
  • [ ] associate: Map human-readable tokens to integer variants without runtime lookup cost.
  • [ ] match: Exhaustive variant matching against switch-case matrices.
  • [ ] matchPartial: Non-exhaustive matching with fallback traps.

• [ ] Flags

  • Bitfield bitmask implementation for zero-allocation permission and state calculation ($1 \ll 0, 1 \ll 1$).

• [ ] View

  • Zero-copy, fat pointer abstraction providing ergonomic slicing across standard ArrayLike buffers.
  • [ ] from: Wrap an existing backing buffer without memory duplication.
  • [ ] get: Bound-checked index access with offset scaling.
  • [ ] forEach, map, filter: Iteration loops passing views without array reallocation.

• [ ] Result

  • Idiomatic error-handling variant to eliminate try/catch optimization blocks and deoptimization penalties in V8/JSC.
  • [ ] isOk / isErr: Monomorphic, shape-stable type-guards.
  • [ ] from / fromAsync: Intercept standard exception-throwing APIs into safe tracking structures.
  • [ ] map / mapErr: Structural mutations passing data variants seamlessly.
  • [ ] unwrap / unwrapOr: Direct evaluation extraction with predictable fallback mechanisms.
  • [ ] match: Fast-path structural or positional matching to minimize allocation.

• [ ] Option

  • Null/undefined avoidance wrapper utilizing predictable memory structures.
  • [ ] some / none: Primitive wrapper factories (utilizing a shared None singleton asset).
  • [ ] isSome / isNone: Shape-stable type-guards.
  • [ ] map / match / unwrapOr: Safe mutation and transformation pipelines.

• [ ] Rng

  • High-performance, seeded PRNG utilizing the Xoshiro algorithm.
  • [ ] next: Generate unboxed pseudo-random float sequences.
  • [ ] integer: Inclusive min/max discrete integer generation.
  • [ ] shuffle: In-place array mutation avoiding internal structural array re-allocations.

• [ ] Range

  • Memory-less, bidirectional numeric indexing ranges (range(start, end)). Supports forward and reverse progressions without sparse array generation or resizing taxes.

• [ ] PooledIterator

  • Universal, shape-stable iterator implementing Iterator and IteratorResult simultaneously. Utilizes an internal Pool buffer to eliminate { value, done } heap allocations in for...of execution loops. Completely resets on loop completion or early runtime loop termination.

• [ ] Concur

  • Lazy evaluation streaming architecture utilizing structural pipelining. Up to 47,000x faster and 99% less heap allocation intensive than native array method chaining.
  • [ ] Native fluent-style API mapping (.filter.map.skip.take.toArray).

Collections Checklist

• [ ] Vector (Contiguous, size-managed arrays)
• [ ] LinkedList / DoublyLinkedList
• [ ] RingBuffer (Fixed-size cyclic tracking structures)
• [ ] Heap (Monomorphic Min/Max binary priority arrays)
• [ ] Radix Trie (String & Buffer key prefixes)

Subsystems

• [ ] Type
  • A zero-dependency validation framework engineered to replace Zod with up to 26x faster execution paths by targeting optimized V8 shape models.
• [ ] Serializer
  • Schema-driven serialization system using JIT-compiled deserialization. Bypasses dynamic Object.defineProperties manipulation to retain fast-property hidden classes on decoded outputs.

TBD

• Defer / using helper

• Memo

• EventEmitter

• BiMap: two way key-value lookup

• LruCache

• Arena

• Chunked Arena

• BitSet

• HashMap (Monomorphic Flat Object Hash)

• SparseSet

Bloom Filter: A probabilistic structure that tells you if an item is definitely not in a set. Extremely memory efficient and fits your "avoid allocation/expensive lookups" theme.

B-Tree or AVL Tree: While you have a Radix Trie, a balanced search tree is necessary for range queries on non-sequential keys.

Reference Counting (Rc / Arc): If you have ResourceCell, you eventually need a way to track how many systems are holding a reference to that cell before it can be returned to the pool.