GoldarDocsAlpha
Documentation menu

Runtime API

The goldar root exports the complete author-facing runtime. The narrower subpaths below expose the same symbols when an application wants explicit dependency boundaries.

Application assembly

Available from goldar and goldar/app.

Application

new Application(router, options?) binds a Router to optional server configuration. The options.server(hono) callback runs once while createApplication() assembles the Hono instance; use it to install middleware or configure the server before routes are registered.

The parameterless constructor exists for legacy subclasses. A legacy ApplicationConstructor declares a static routes array whose entries are StaticRouteConstructor values.

  • ApplicationOptions<E> contains the optional server callback.
  • ApplicationConstructor<E> describes a legacy constructible application with static routes.
  • ApplicationSource<E> accepts either an Application instance or legacy constructor.
  • Application.configure(hono) applies the configured server callback. Legacy subclasses may override it while migrating.

createApplication(source, options?)

Builds and returns a Hono application. Each matching request receives a fresh route instance and a fresh store record from its router. Store hooks run before data loads; owned data loads concurrently before route rendering. POST requests dispatch to an action owned by that route.

CreateApplicationOptions<E> supports:

  • configure: installs adapter-owned middleware after application middleware and before routes. This is intended for generated server and deployment adapters, not routine application setup.
  • csrf: same-origin Hono CSRF middleware is enabled unless this is explicitly false. Disabling it changes the application’s security boundary.
  • requestScope: optional RequestScopeHooks for store initialization and data interception.

RequestScopeHooks<E> contains:

  • initializeStore(request): runs once for each named store before any owned data loads.
  • loadData(request): may return a replacement value or call request.load() to delegate to the real resource. Delegated loads are memoized within that request.

StoreInitializationRequest exposes the resource context, owned name, route owner, and store. DataLoadRequest exposes the same ownership information plus the data resource and memoized load() delegate.

Routing

Available from goldar and goldar/router.

Router

new Router(options?) creates a route registry. RouterOptions<Stores>.createStores() returns the named store record passed to every route constructor in one request. It is called again for the next request.

router.addRoute(path, RouteType) registers a Route constructor and returns the router for chaining. Paths must be non-empty absolute paths and must be unique within the router. The current implementation accepts constructors, not route factories.

Route

Subclass Route<Stores, E> and implement render(context). The store record is the common first generic; routes with a custom Hono environment provide it as the second generic. A route owns three named records:

  • stores: the store record supplied by its router;
  • data: Data instances loaded before rendering;
  • actions: FormAction instances addressable by form submissions.

render() may return a View, a standard Response, or a RouteResult, synchronously or through a promise. RouteConstructor describes normal registered route types. StaticRouteConstructor adds a required static path for the legacy application and direct test APIs.

A route may also declare singular store for mutable state used only by that route. It is initialized through the same request-scope hook as named stores, under the stable name store. Plural stores is reserved for the exact shared record injected by the router; explicit route constructors must forward that record to super(stores) and must not overwrite it.

RouteContext<E> exposes:

  • hono, request, url, and signal for the underlying request;
  • params, an immutable Params snapshot;
  • data(resource), which returns the resolved value for an owned data instance;
  • action(action), which returns the hidden-field metadata for an owned action;
  • submission(action), which returns preserved values and errors after that action returns an invalid result.

Passing a resource or action not owned by the route throws an error.

Params

new Params(values) takes an immutable snapshot of route parameters. get(name) returns a string or undefined; require(name) returns the string or throws an HTTP 400 exception; toObject() returns the frozen snapshot.

RouteResult

RouteResult is a discriminated union with view and response variants.

  • RouteResult.view(view, init?) renders a view with optional response status and headers.
  • RouteResult.response(response) preserves a standard response escape hatch.

Returning a View directly is equivalent to a view result with default response metadata.

Data

Available from goldar and goldar/data.

Subclass Data<Output, E> and implement load(context). Each owned instance loads once per route request; separate owned instances load independently and concurrently. There is no cross-request cache.

DataContext<E> exposes the Hono context, immutable route parameters, raw request, request URL, and abort signal. DataValue<T> infers and awaits the output of a specific data instance. DataConstructor<E> describes a parameterless data subclass for testing APIs.

Stores

Available from goldar and goldar/store.

Store is the base marker for mutable request-local state. StoreRecord is a readonly named record of stores, and StoreConstructor<T> is a parameterless store constructor used by testing and request-scope APIs. A store instance does not persist across HTTP requests unless the application explicitly synchronizes it with durable state.

Form actions

Available from goldar and goldar/form-action. The older goldar/helpers subpath remains an equivalent compatibility alias.

Subclass FormAction<E> and implement submit(context). It may return a standard Response or one of the branded ActionResult values created by the context helpers:

  • invalid(errors, options?) rerenders the owning route with status 422. By default it preserves every submitted field except the action selector; options.values can replace that snapshot.
  • redirect(location, status?) returns a 303 redirect by default. Status 307 and 308 are also accepted.
  • success(options?) reloads route data before rerendering. An optional revalidate list is validated against data owned by the route; there is no external cache invalidation.

FormActionContext<E> includes the Hono/request fields used by DataContext plus the raw formData, an immutable FormSubmission wrapper, and the three result helpers. FormActionConstructor<E> describes a form-action subclass constructor for APIs that create owned instances.

FormSubmission provides get(name), getAll(name), string(name), and values(). The string helper returns an empty string for missing or file-valued fields. FieldErrors, FormValue, FormValues, FormActionSubmission, InvalidActionOptions, and SuccessfulActionOptions describe validation and result payloads.

RouteContext.action() returns a FormActionReference containing method, url, id, fieldName, and ready-to-spread fields. The wire names are also exported as GOLDAR_ACTION_FIELD and GOLDAR_ACTION_HEADER for integrations that construct submissions directly.

Views

Available from goldar and goldar/view.

.hbs modules compile to a callable CompiledTemplate<Props>. Calling a template with props and optional child views returns an opaque View. ViewFunction<Props> describes that callable contract. A template declares Props in leading TypeScript frontmatter; goldar sync turns it into a compiler-owned declaration beneath .goldar/types, giving direct imports an exact call signature. The template-language reference defines supported expressions, blocks, composition, styles, and diagnostics.

createCompiledTemplate() snapshots, validates, and deeply freezes its ViewProgram and imported template dependencies. It rejects malformed recursive instructions, invalid lexical references, mismatched element nesting, duplicate outlets, unauthenticated dependencies, and unknown instructions or capabilities before a template can render.

defineView<Props>(template) remains as a deprecated compatibility bridge for older applications. New application code should call its typed template imports directly.

renderToString(view) executes a compiled view program, including if branches, array-only each blocks with explicit lexical bindings, and imported-template calls. Ordinary expressions and attributes are escaped. Triple-mustache expressions accept only TrustedHtml values created by trustedHtml(value). The branding function does not sanitize its input; callers must establish and review the trust boundary before branding content.

Shared types

Available from goldar and goldar/async.

MaybePromise<T> is T | Promise<T>. Lifecycle methods accept it so implementations can remain synchronous until they actually need asynchronous work.