Askr

A TypeScript UI runtime with getter-based state, fine-grained bindings, transactional commits with rollback, and one route graph for SPA, SSR, and SSG.

How Askr works

• Getter-based state with automatic tracking. state() gives you a getter and a setter. Calling the getter while a component renders subscribes that component; you do not list dependencies for state or derive().
• Component re-render plus fine-grained bindings. A state change re-runs the components that read it. A function child or prop, such as {() => count()}, is a binding: it updates its own DOM node without re-running the component around it.
• Transactional commits with rollback. Each render is prepared and applied as one transaction. If a component throws or the DOM commit fails, Askr restores the last committed DOM, and the listeners, refs, resources, and subscriptions created by the failed render never become live. The error goes to the nearest ErrorBoundary, or is rethrown when no boundary catches it. Bindings keep showing current state across a rollback.
• One route graph. The registry from createRouteRegistry() drives browser navigation (createSPA), hydration (hydrateSPA), server rendering (renderRouteRequest), and static generation (createStaticGen).

Writes made in one event handler are batched into one scheduled render, and queued work runs in a fixed order. See Update ordering for exactly what Askr guarantees and what it does not.

Quick Start

import { state } from '@askrjs/askr';
import { createIsland } from '@askrjs/askr/boot';

function Counter() {
  const [count, setCount] = state(0);

  return (
    <button onClick={() => setCount((value) => value + 1)}>{count()}</button>
  );
}

createIsland({ root: document.body, component: Counter });

The tuple form above and the direct callable form below are equivalent; see State usage forms for when each is convenient.

What It Provides

Runtime

@askrjs/askr exports the core runtime primitives: state(), derive(), selector(), defineScope(), readScope(), getSignal(), and the JSX runtime exports.

Public APIs are mostly functions and closures. Error classes such as RouteDataLoadError and SSRDataMissingError live on their subpaths. Lexical ownership uses defineScope() and readScope(); there are no compatibility aliases for the clean-break vocabulary.

App startup, routing, async resources, data helpers, and error boundaries live on their own subpaths.

Getter-based state

State is read through getter functions and updated through setter functions. Reads are explicit calls, but dependency tracking is automatic: a component re-renders when state it read during its last committed render changes.

state(), derive(), selector(), resource(), and the other render-scoped primitives are hooks in the React sense. Each call is matched to its slot by call position, so call them unconditionally and in the same order on every render; the runtime throws when the order changes (see Runtime Enforcement). resource() takes a dependency array that decides when its loader re-runs.

State usage forms

state() returns one callable state cell that is also iterable. Destructuring it gives the cell as the getter and its .set() method as the setter. Call state() inside a component function:

const [count, setCount] = state(0);
console.log(count());
setCount(1);

The same state can be kept as one value and updated through .set():

const count = state(0);
console.log(count());
count.set(1);

Prefer destructuring when local getter and setter names make event handlers clear. Prefer the direct form when passing the state cell around as one value or when keeping reads and writes under one name. Both forms have the same tracking, scheduling, and update semantics.

Routing and app startup

Startup belongs in @askrjs/askr/boot. Routing helpers live in @askrjs/askr/router.

import { createSPA } from '@askrjs/askr/boot';
import { createRouteRegistry, route } from '@askrjs/askr/router';

const registry = createRouteRegistry(() => {
  route('/', Home);
  route('/about', About);
});

createSPA({
  root: document.body,
  registry,
});

Async resources

resource() manages async work with cancellation support.

import { resource } from '@askrjs/askr/resources';

function Data({ id }: { id: string }) {
  const data = resource(
    async ({ signal }) => {
      const response = await fetch(`/api/${id}`, { signal });
      return response.json();
    },
    [id]
  );

  if (data.pending) return <div>Loading...</div>;
  if (data.error) return <div>Failed to load</div>;
  return <div>{data.value?.name}</div>;
}

@askrjs/askr/data is the only entrypoint for query, mutation, invalidation, and data-runtime helpers; the root package does not re-export them.

Developer error boundaries

ErrorBoundary is the opt-in boundary primitive for render-time failures. It renders a visible fallback in every environment (with error details expanded by default in development), still logs the underlying error, and can reset via a resetKey tied to your app state. The boundary protects both initial mount and scheduled post-mount updates. Portal content follows its logical writer boundary and can also recover through a boundary around its host.

import { ErrorBoundary } from '@askrjs/askr/components';

function App() {
  return (
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <FlakyView />
    </ErrorBoundary>
  );
}

Documentation

• Documentation Index
• Installation
• Quick Start
• State Guide
• Router Guide
• Resources Guide
• SSG Guide
• Runtime Enforcement
• Update Ordering
• API Reference

Release Notes

The published package is versioned with the repository package.json. Release workflows validate the version tag before publishing.

Install

npm install @askrjs/askr

License

Apache 2.0