Introduction

@ilokesto/store is a core primitive in the ilokesto ecosystem. It provides a minimal, synchronous, and framework-agnostic store implementation designed for reliability and performance.

While other packages in the ecosystem provide framework bindings or complex state management patterns, store remains a lean foundation that focuses on the basic contract of state: storage, updates, and notifications.

Installation

npm install @ilokesto/store

What it is

• Foundational: A minimal set of primitives for state storage.
• Framework-agnostic: Works in any JavaScript environment (Node.js, Browser, Deno, etc.).
• Synchronous: State updates and notifications happen immediately.
• Predictable: Uses standard Object.is checks and immutable patterns.

What it is not

• A Framework Binding: It does not contain React hooks or Vue composables.
• A Data Fetching Library: It does not manage server cache or loading states.
• A Multi-store Orchestrator: It manages a single state atom.

Mental Model

Think of a Store as a safe box for a single value. You can look at the value at any time, replace it with a new one, and register listeners to be notified whenever the value changes. It doesn't care what is inside the box, as long as you follow immutable update patterns.

Quick Example

import { Store } from "@ilokesto/store";

const store = new Store({ count: 0 });

// Subscribe to changes
const unsubscribe = store.subscribe(() => {
  console.log("State changed:", store.getState());
});

// Update state
store.setState({ count: 1 });

// Clean up
unsubscribe();

When to Use

• When building a library that needs internal state management without forcing a framework dependency on users.
• When you need a simple, reliable state container for vanilla JavaScript or TypeScript projects.
• As a base for building higher-level libraries, adapters, or domain-specific state layers.

Documentation Map

• API Reference: The public surface of the Store class.
• Update Semantics: How state updates work and the bailout rules.
• Subscriptions: Managing the observer lifecycle.
• Common Patterns: Practical recipes for real-world usage.
• Building on Store: Guidelines for adapter and library authors.
• Integrations: The ecosystem around @ilokesto/store.
• Semantics: The strict behavioral specification.
• Implementation Notes: Deep dive into internal mechanics.