@askrjs/askr 0.2.4 → 0.3.0

package/dist/domains/server.d.ts

@@ -0,0 +1,112 @@
+import { JSXElementType, JSXElement, Props } from '../elements.js';
+import '../jsx-globals.js';
+import { AuthContext, AuthRequirement } from '@askrjs/auth';
+import { InferSchema, ObjectSchema } from '@askrjs/schema';
+import { RenderableChild, Scope } from './context.js';
+
+/**
+ * Common call contracts: SSR types
+ */
+/** Arbitrary serializable data attached to an SSR render pass (e.g. loader output). */
+type SSRData = Record<string, unknown>;
+
+/** Styles produced while rendering a request, kept with that request's SSR context. */
+interface SSRStyleRegistration {
+  id: string;
+  cssText: string;
+}
+
+interface DocumentRenderRoute {
+  path: string;
+  namespace?: string;
+}
+
+/** Request/render metadata passed to a {@link DocumentRenderer}. */
+interface DocumentRenderContext {
+  mode: 'ssr' | 'ssg';
+  url: string;
+  pathname: string;
+  search: string;
+  hash: string;
+  params: Record<string, string>;
+  data?: SSRData;
+  seed: number;
+  route: DocumentRenderRoute;
+  cspNonce?: string;
+  styles?: readonly SSRStyleRegistration[];
+}
+
+/** Arguments passed to a {@link DocumentRenderer}: the rendered app HTML and its context. */
+interface DocumentRenderArgs {
+  appHtml: string;
+  context: DocumentRenderContext;
+}
+
+/** Wraps rendered app HTML in a full document (`<html>`, `<head>`, etc.) for SSR/SSG output. */
+type DocumentRenderer = (args: DocumentRenderArgs) => string;
+
+/** How to react when SSR styles were registered but not included in the rendered document. */
+type SSRStyleRegistrationValidation = 'warn' | 'error' | 'off';
+
+/** Full context for sink-based streaming SSR */
+type SSRContext = {
+  url: string;
+  seed: number;
+  data?: SSRData;
+  params?: Record<string, string>;
+  signal?: AbortSignal;
+};
+
+/** Lexical scope carrying the CSP nonce for the current render, if any. */
+declare const CspNonceScope: Scope<string | undefined>;
+
+/**
+ * Read the CSP nonce for the current render from {@link CspNonceScope}.
+ *
+ * @returns The active nonce, or `undefined` when called outside of a
+ * component render or when no nonce was configured.
+ */
+declare function cspNonce(): string | undefined;
+
+interface DeferredBoundaryRegistration {
+  id: string;
+  promise: Promise<unknown>;
+  fulfilled(value: unknown): RenderableChild;
+  rejected(error: unknown): RenderableChild;
+}
+
+interface SSRPortalHostRegistration {
+  token: string;
+  automatic: boolean;
+}
+
+interface SSRPortalSlot {
+  hasValue: boolean;
+  value: RenderableChild | undefined;
+  hosts: SSRPortalHostRegistration[];
+}
+
+interface SSRPortalState {
+  slots: Map<object, SSRPortalSlot>;
+  nextHostId: number;
+}
+
+/** Register request-local CSS produced during SSR without importing the SSR renderer in clients. */
+declare function registerSSRStyle(id: string, cssText: string): void;
+export {
+  SSRData,
+  SSRStyleRegistration,
+  DocumentRenderRoute,
+  DocumentRenderContext,
+  DocumentRenderArgs,
+  DocumentRenderer,
+  SSRStyleRegistrationValidation,
+  SSRContext,
+  CspNonceScope,
+  cspNonce,
+  DeferredBoundaryRegistration,
+  SSRPortalHostRegistration,
+  SSRPortalSlot,
+  SSRPortalState,
+  registerSSRStyle,
+};

package/dist/domains/state.d.ts

@@ -0,0 +1,129 @@
+import { JSXElementType, JSXElement, Props } from '../elements.js';
+import '../jsx-globals.js';
+import { AuthContext, AuthRequirement } from '@askrjs/auth';
+import { InferSchema, ObjectSchema } from '@askrjs/schema';
+import { ReadableSource } from './component.js';
+import { capture } from './lifecycle.js';
+import { For } from './control.js';
+
+/**
+ * State value holder - callable to read, has set method to update
+ * @example
+ * const count = state(0);
+ * count();           // read: 0
+ * count.set(1);      // write: triggers re-render
+ */
+interface State<T> extends ReadableSource<T> {
+  (): T;
+  set(...args: StateSetterArgs<T>): void;
+  [Symbol.iterator](): IterableIterator<StateTuple<T>[number]>;
+}
+
+type StateUpdater<T> = (prev: T) => T;
+
+type StateSetterArgs<T> = [Extract<T, (...args: any[]) => unknown>] extends [
+  never,
+]
+  ? [value: T] | [updater: StateUpdater<T>]
+  : [updater: StateUpdater<T>];
+
+/**
+ * Public setter type for state cells.
+ */
+type StateSetter<T> = (...args: StateSetterArgs<T>) => void;
+
+/**
+ * Tuple-first state handle returned by `state()`.
+ */
+type StateTuple<T> = [get: State<T>, set: StateSetter<T>] & State<T>;
+
+/**
+ * Creates a local state value for a component
+ * Optimized for:
+ * - O(1) read performance
+ * - Minimal allocation per state
+ * - Fast scheduler integration
+ *
+ * IMPORTANT: state() must be called during component render execution.
+ * It captures the current component instance from context.
+ * Calling outside a component function will throw an error.
+ *
+ * @example
+ * ```ts
+ * // ✅ Correct: called during render
+ * export function Counter() {
+ *   const [count, setCount] = state(0);
+ *   return { type: 'button', children: [count()] };
+ * }
+ *
+ * // ❌ Wrong: called outside component
+ * const count = state(0);
+ * export function BadComponent() {
+ *   return { type: 'div' };
+ * }
+ * ```
+ */
+declare function state<T>(initialValue: T): StateTuple<T>;
+
+declare const SNAPSHOT_SOURCE_BRAND: unique symbol;
+
+type SnapshotSourceBrand = {
+  readonly [SNAPSHOT_SOURCE_BRAND]: true;
+};
+
+/** A reactive derived value produced by {@link derive}; call it to read the current result. */
+interface Derived<T> extends ReadableSource<T> {
+  (): T;
+}
+
+type SnapshotSource<T> = {
+  value: T | null;
+  pending?: boolean;
+  error?: Error | null;
+} & SnapshotSourceBrand;
+
+/** Creates a render-scoped derived value; must be called during component render. */
+declare function derive<TOut>(fn: () => TOut): Derived<TOut>;
+
+declare function derive<TIn, TOut>(
+  source: SnapshotSource<TIn> | TIn | (() => TIn),
+  map: (value: TIn) => TOut
+): Derived<TOut | null>;
+
+/** A fine-grained reactive membership check produced by {@link selector}. */
+interface Selector<T> {
+  (candidate: T): boolean;
+}
+
+type SelectorEquals<T> = {
+  bivarianceHack(a: T, b: T): boolean;
+}['bivarianceHack'];
+
+/**
+ * Creates a render-scoped predicate for keyed membership in reactive list rows.
+ *
+ * Use this when a `<For>` child needs to compare each stable item with a
+ * changing selected value. Unlike a plain closure capture, the predicate
+ * subscribes the affected rows and updates them without rebuilding the list.
+ * Must be called during component render.
+ */
+declare function selector<T>(
+  source: () => T,
+  equals?: SelectorEquals<T>
+): Selector<T>;
+export {
+  State,
+  StateUpdater,
+  StateSetterArgs,
+  StateSetter,
+  StateTuple,
+  state,
+  SNAPSHOT_SOURCE_BRAND,
+  SnapshotSourceBrand,
+  Derived,
+  SnapshotSource,
+  derive,
+  Selector,
+  SelectorEquals,
+  selector,
+};

package/dist/domains/telemetry.d.ts

@@ -0,0 +1,29 @@
+import { JSXElementType, JSXElement, Props } from '../elements.js';
+import '../jsx-globals.js';
+import { AuthContext, AuthRequirement } from '@askrjs/auth';
+import { InferSchema, ObjectSchema } from '@askrjs/schema';
+import { action } from './actions.js';
+
+interface TelemetryFields {
+  requestId?: string;
+  traceId?: string;
+  route?: string;
+  action?: string;
+  operation?: string;
+  status?: number;
+  durationMs?: number;
+}
+
+type TelemetrySpan = <T>(fields: TelemetryFields, work: () => T) => T;
+
+/**
+ * Structural subset implemented by `createTelemetry()` from `@askrjs/otel`.
+ * Core does not install an OpenTelemetry SDK, backend, or exporter.
+ */
+interface CoreTelemetry {
+  routeMatch?: TelemetrySpan;
+  loader?: TelemetrySpan;
+  queryPrefetch?: TelemetrySpan;
+  ssrRender?: TelemetrySpan;
+}
+export { TelemetryFields, TelemetrySpan, CoreTelemetry };

package/dist/eager-control.d.ts

@@ -0,0 +1,8 @@
+import { Props } from './elements.js';
+declare const EAGER_CONTROL_PRIMITIVE: unique symbol;
+type EagerControlPrimitive<P extends Props = Props> = ((
+  props: P
+) => unknown) & {
+  [EAGER_CONTROL_PRIMITIVE]?: true;
+};
+export { EagerControlPrimitive };

package/dist/{effect-CNwstBBD.js → effect-C3Zsc1k6.js}

@@ -1,6 +1,6 @@
-import { t as enqueueRuntimeLane } from "./access-BucjYZcX.js";
-import { m as withFineGrainedReadTracking } from "./readable-Di1fzSwm.js";
-//#region src/runtime/effect.ts
+import { b as ScheduledWork, f as requestRuntimeWork, y as SCHEDULER_LANES } from "./access-CEA2pOry.js";
+import { S as withFineGrainedReadTracking } from "./notify-DxxuDPeY.js";
+//#region src/runtime/reactivity/effect.ts
 const SOURCE_EFFECTS = Symbol("askr.source-effects");
 const effectSources = /* @__PURE__ */ new WeakMap();
 const dirtyEffectsByLane = {
@@ -9,24 +9,12 @@ const dirtyEffectsByLane = {
 	reactive: /* @__PURE__ */ new Set(),
 	post: /* @__PURE__ */ new Set()
 };
-const hasPendingLaneFlush = {
-	derived: false,
-	component: false,
-	reactive: false,
-	post: false
-};
-const dirtyLaneState = {
-	derived: false,
-	component: false,
-	reactive: false,
-	post: false
-};
 const MAX_EFFECT_RUNS_PER_FLUSH = 50;
 const LANE_FLUSH_TASKS = {
-	derived: () => flushLaneEffects("derived"),
-	component: () => flushLaneEffects("component"),
-	reactive: () => flushLaneEffects("reactive"),
-	post: () => flushLaneEffects("post")
+	derived: new ScheduledWork(() => flushLaneEffects("derived")),
+	component: new ScheduledWork(() => flushLaneEffects("component")),
+	reactive: new ScheduledWork(() => flushLaneEffects("reactive")),
+	post: new ScheduledWork(() => flushLaneEffects("post"))
 };
 function isEffectReadSourceCollection(sources) {
 	return Array.isArray(sources) || sources instanceof Set;
@@ -171,7 +159,6 @@ function handleEffectError(effect, error) {
 	throw error;
 }
 function flushLaneEffects(lane) {
-	hasPendingLaneFlush[lane] = false;
 	const effects = dirtyEffectsByLane[lane];
 	if (effects.size === 0) return;
 	const pending = effects.values();
@@ -211,11 +198,6 @@ function flushLaneEffects(lane) {
 	if (failures?.length === 1) throw failures[0];
 	if (failures && failures.length > 1) throw new AggregateError(failures, "Fine-grained effect failures");
 }
-function scheduleLaneFlush(lane) {
-	if (hasPendingLaneFlush[lane]) return;
-	hasPendingLaneFlush[lane] = true;
-	enqueueRuntimeLane(lane, LANE_FLUSH_TASKS[lane]);
-}
 function unscheduleEffect(effect) {
 	dirtyEffectsByLane[effect.lane].delete(effect);
 }
@@ -229,22 +211,13 @@ function recomputeEffectNow(effect) {
 function markFineGrainedEffectsDirtySource(source) {
 	const registered = getRegisteredEffects(source);
 	if (!registered) return;
-	dirtyLaneState.derived = false;
-	dirtyLaneState.component = false;
-	dirtyLaneState.reactive = false;
-	dirtyLaneState.post = false;
-	const markDirty = (effect) => {
-		if (!effect.isActive) return;
-		const lane = effect.lane;
-		dirtyEffectsByLane[lane].add(effect);
-		dirtyLaneState[lane] = true;
-	};
-	if (registered instanceof Set) for (const effect of registered) markDirty(effect);
-	else markDirty(registered);
-	if (dirtyLaneState.derived) scheduleLaneFlush("derived");
-	if (dirtyLaneState.component) scheduleLaneFlush("component");
-	if (dirtyLaneState.reactive) scheduleLaneFlush("reactive");
-	if (dirtyLaneState.post) scheduleLaneFlush("post");
+	if (registered instanceof Set) for (const effect of registered) markDirtyEffect(effect);
+	else markDirtyEffect(registered);
+	for (const lane of SCHEDULER_LANES) if (dirtyEffectsByLane[lane].size) requestRuntimeWork(lane, LANE_FLUSH_TASKS[lane]);
+}
+function markDirtyEffect(effect) {
+	if (!effect.isActive) return;
+	dirtyEffectsByLane[effect.lane].add(effect);
 }
 var FineGrainedEffectImpl = class {
 	constructor(lane, compute, commit, equals, onError, owner) {

package/dist/{types-DWVrKn9N.d.ts → elements.d.ts}

@@ -1,4 +1,3 @@
-//#region src/common/props.d.ts
 /**
  * Common call contracts: Props
  *
@@ -29,12 +28,26 @@ type IntrinsicTextValue = string | null | undefined;
 type IntrinsicTextLikeValue = string | number | null | undefined;
 type IntrinsicStyleEntryValue = string | number | null | undefined | false;
 type IntrinsicStyleObject = Record<string, IntrinsicStyleEntryValue>;
-type IntrinsicStyleValue = string | IntrinsicStyleObject | null | undefined | false;
-type IntrinsicFormValue = string | number | readonly string[] | null | undefined;
+type IntrinsicStyleValue =
+  | string
+  | IntrinsicStyleObject
+  | null
+  | undefined
+  | false;
+type IntrinsicFormValue =
+  | string
+  | number
+  | readonly string[]
+  | null
+  | undefined;
 type IntrinsicRefTarget = Element | null;
-type IntrinsicRef = BivariantHandler<IntrinsicRefTarget> | {
-  current: IntrinsicRefTarget;
-} | null | undefined;
+type IntrinsicRef =
+  | BivariantHandler<IntrinsicRefTarget>
+  | {
+      current: IntrinsicRefTarget;
+    }
+  | null
+  | undefined;
 interface IntrinsicEventProps {
   onAbort?: BivariantHandler<Event>;
   onBlur?: BivariantHandler<FocusEvent>;
@@ -144,7 +157,10 @@ type ForbiddenLayoutOnlyProps = {
   value?: never;
   width?: never;
 };
-type StructuredContentIntrinsicProps<TAllowed extends object = {}> = IntrinsicFallbackProps & Omit<ForbiddenLayoutOnlyProps, keyof TAllowed> & TAllowed;
+type StructuredContentIntrinsicProps<TAllowed extends object = {}> =
+  IntrinsicFallbackProps &
+    Omit<ForbiddenLayoutOnlyProps, keyof TAllowed> &
+    TAllowed;
 type LayoutIntrinsicProps = StructuredContentIntrinsicProps;
 type OrderedListIntrinsicProps = StructuredContentIntrinsicProps<{
   reversed?: ReactiveProp<IntrinsicBooleanValue>;
@@ -159,12 +175,21 @@ type TableCellIntrinsicAllowedProps = {
   headers?: ReactiveProp<IntrinsicTextValue>;
   rowSpan?: ReactiveProp<IntrinsicNumberValue>;
 };
-type TableHeaderScopeValue = 'col' | 'colgroup' | 'row' | 'rowgroup' | null | undefined;
-type TableCellIntrinsicProps = StructuredContentIntrinsicProps<TableCellIntrinsicAllowedProps>;
-type TableHeaderIntrinsicProps = StructuredContentIntrinsicProps<TableCellIntrinsicAllowedProps & {
-  abbr?: ReactiveProp<IntrinsicTextValue>;
-  scope?: ReactiveProp<TableHeaderScopeValue>;
-}>;
+type TableHeaderScopeValue =
+  | 'col'
+  | 'colgroup'
+  | 'row'
+  | 'rowgroup'
+  | null
+  | undefined;
+type TableCellIntrinsicProps =
+  StructuredContentIntrinsicProps<TableCellIntrinsicAllowedProps>;
+type TableHeaderIntrinsicProps = StructuredContentIntrinsicProps<
+  TableCellIntrinsicAllowedProps & {
+    abbr?: ReactiveProp<IntrinsicTextValue>;
+    scope?: ReactiveProp<TableHeaderScopeValue>;
+  }
+>;
 interface AnchorIntrinsicProps extends IntrinsicProps {
   href?: ReactiveProp<IntrinsicTextValue>;
   rel?: ReactiveProp<IntrinsicTextValue>;
@@ -223,29 +248,38 @@ type SvgPresentationIntrinsicAllowedProps = {
   strokeLinejoin?: ReactiveProp<IntrinsicTextValue>;
   strokeWidth?: ReactiveProp<IntrinsicTextLikeValue>;
 };
-type SvgIntrinsicProps = StructuredContentIntrinsicProps<SvgPresentationIntrinsicAllowedProps & {
-  height?: ReactiveProp<IntrinsicTextLikeValue>;
-  viewBox?: ReactiveProp<IntrinsicTextValue>;
-  width?: ReactiveProp<IntrinsicTextLikeValue>;
-  xmlns?: ReactiveProp<IntrinsicTextValue>;
-}>;
-type SvgCircleIntrinsicProps = StructuredContentIntrinsicProps<SvgPresentationIntrinsicAllowedProps & {
-  cx?: ReactiveProp<IntrinsicTextLikeValue>;
-  cy?: ReactiveProp<IntrinsicTextLikeValue>;
-  r?: ReactiveProp<IntrinsicTextLikeValue>;
-}>;
-type SvgGroupIntrinsicProps = StructuredContentIntrinsicProps<SvgPresentationIntrinsicAllowedProps>;
-type SvgPathIntrinsicProps = StructuredContentIntrinsicProps<SvgPresentationIntrinsicAllowedProps & {
-  d?: ReactiveProp<IntrinsicTextValue>;
-}>;
-type SvgRectIntrinsicProps = StructuredContentIntrinsicProps<SvgPresentationIntrinsicAllowedProps & {
-  height?: ReactiveProp<IntrinsicTextLikeValue>;
-  rx?: ReactiveProp<IntrinsicTextLikeValue>;
-  ry?: ReactiveProp<IntrinsicTextLikeValue>;
-  width?: ReactiveProp<IntrinsicTextLikeValue>;
-  x?: ReactiveProp<IntrinsicTextLikeValue>;
-  y?: ReactiveProp<IntrinsicTextLikeValue>;
-}>;
+type SvgIntrinsicProps = StructuredContentIntrinsicProps<
+  SvgPresentationIntrinsicAllowedProps & {
+    height?: ReactiveProp<IntrinsicTextLikeValue>;
+    viewBox?: ReactiveProp<IntrinsicTextValue>;
+    width?: ReactiveProp<IntrinsicTextLikeValue>;
+    xmlns?: ReactiveProp<IntrinsicTextValue>;
+  }
+>;
+type SvgCircleIntrinsicProps = StructuredContentIntrinsicProps<
+  SvgPresentationIntrinsicAllowedProps & {
+    cx?: ReactiveProp<IntrinsicTextLikeValue>;
+    cy?: ReactiveProp<IntrinsicTextLikeValue>;
+    r?: ReactiveProp<IntrinsicTextLikeValue>;
+  }
+>;
+type SvgGroupIntrinsicProps =
+  StructuredContentIntrinsicProps<SvgPresentationIntrinsicAllowedProps>;
+type SvgPathIntrinsicProps = StructuredContentIntrinsicProps<
+  SvgPresentationIntrinsicAllowedProps & {
+    d?: ReactiveProp<IntrinsicTextValue>;
+  }
+>;
+type SvgRectIntrinsicProps = StructuredContentIntrinsicProps<
+  SvgPresentationIntrinsicAllowedProps & {
+    height?: ReactiveProp<IntrinsicTextLikeValue>;
+    rx?: ReactiveProp<IntrinsicTextLikeValue>;
+    ry?: ReactiveProp<IntrinsicTextLikeValue>;
+    width?: ReactiveProp<IntrinsicTextLikeValue>;
+    x?: ReactiveProp<IntrinsicTextLikeValue>;
+    y?: ReactiveProp<IntrinsicTextLikeValue>;
+  }
+>;
 interface OptionIntrinsicProps extends IntrinsicProps {
   disabled?: ReactiveProp<IntrinsicBooleanValue>;
   label?: ReactiveProp<IntrinsicTextValue>;
@@ -329,8 +363,6 @@ interface KnownIntrinsicElementProps {
   tr: LayoutIntrinsicProps;
   ul: LayoutIntrinsicProps;
 }
-//#endregion
-//#region src/common/jsx.d.ts
 /** The element type marker for JSX fragments (`<>...</>`), groups children without a wrapper element. */
 declare const Fragment: unique symbol;
 /** A component function accepting `TProps`, usable as a JSX element's `type`. */
@@ -350,8 +382,6 @@ interface JSXElement {
   /** Optional key (normalized by runtime) */
   key?: string | number | null;
 }
-//#endregion
-//#region src/jsx/types.d.ts
 declare global {
   namespace JSX {
     interface Element extends JSXElement {
@@ -366,5 +396,12 @@ declare global {
     }
   }
 }
-//#endregion
-export { IntrinsicFallbackProps as a, JSXElementType as i, JSXComponent as n, KnownIntrinsicElementProps as o, JSXElement as r, Props as s, Fragment as t };
+export {
+  IntrinsicFallbackProps,
+  JSXElementType,
+  JSXComponent,
+  KnownIntrinsicElementProps,
+  JSXElement,
+  Props,
+  Fragment,
+};