@qwik.dev/core 2.0.0-beta.30 → 2.0.0-beta.32

package/dist/core-internal.d.ts

@@ -380,6 +380,8 @@ declare type AsyncCtx<T = unknown> = {
     readonly abortSignal: AbortSignal;
     /** The result of the previous computation, if any */
     readonly previous: T | undefined;
+    /** Extra info passed to `invalidate(info)` for this computation, if any. */
+    readonly info?: unknown;
 };
 
 /**
@@ -395,13 +397,15 @@ export declare type AsyncFn<T> = (ctx: AsyncCtx) => ValueOrPromise<T>;
 declare class AsyncJob<T> implements AsyncCtx<T> {
     readonly $signal$: AsyncSignalImpl<T>;
     /** First holds the compute promise and then the cleanup promise */
-    $promise$: Promise<void> | null;
+    $promise$: Promise<void> | null | void;
     $cleanupRequested$: boolean;
     $canWrite$: boolean;
     $track$: AsyncCtx<T>['track'] | undefined;
     $cleanups$: Parameters<AsyncCtx<T>['cleanup']>[0][] | undefined;
     $abortController$: AbortController | undefined;
-    constructor($signal$: AsyncSignalImpl<T>);
+    info: unknown;
+    $infoVersion$: number | undefined;
+    constructor($signal$: AsyncSignalImpl<T>, info: unknown, $infoVersion$: number | undefined);
     get track(): AsyncCtx<T>['track'];
     get abortSignal(): AbortSignal;
     /** Backward compatible cache method for resource */
@@ -447,25 +451,57 @@ export declare interface AsyncSignal<T = unknown> extends ComputedSignal<T> {
      * ```
      */
     loading: boolean;
+    /**
+     * Lets you read the loading state without subscribing to `.loading` updates. It also triggers
+     * lazy loading of the signal.
+     *
+     * Setting it will trigger listeners for `.loading`.
+     */
+    untrackedLoading: boolean;
     /**
      * The error that occurred while computing the signal, if any. This will be cleared when the
-     * signal is successfully computed.
+     * signal is successfully computed. It does not trigger lazy loading of the signal.
      */
     error: Error | undefined;
     /**
-     * Poll interval in ms. Writable and immediately effective when the signal has consumers. If set
-     * to `0`, polling stops.
+     * Lets you read the error state without subscribing to `.error` updates. It does not trigger lazy
+     * loading of the signal.
+     *
+     * Setting it will trigger listeners for `.error`.
+     */
+    untrackedError: Error | undefined;
+    /**
+     * Expiration time in ms. Writable and immediately effective.
+     *
+     * When set, the signal is invalidated after this many ms. Whether it auto-recomputes depends on
+     * the `poll` property. `0` means no expiration.
+     */
+    expires: number;
+    /**
+     * Whether to automatically re-run the function when the value expires. Writable and immediately
+     * effective. Only relevant when `expires` is set.
+     *
+     * Defaults to `true`.
      */
+    poll: boolean;
+    /** @deprecated Use `expires` and `poll` instead. Will be removed before v2 */
     interval: number;
     /** A promise that resolves when the value is computed or rejected. */
     promise(): Promise<void>;
     /** Abort the current computation and run cleanups if needed. */
     abort(reason?: any): void;
+    /**
+     * Use this to force recalculation. If you pass `info`, it will be provided to the calculation
+     * function.
+     */
+    invalidate(info?: unknown): void;
 }
 
 declare const enum AsyncSignalFlags {
     EAGER_CLEANUP = 32,
-    CLIENT_ONLY = 64
+    CLIENT_ONLY = 64,
+    CLEAR_ON_INVALIDATE = 128,
+    NO_POLL = 256
 }
 
 /**
@@ -474,23 +510,40 @@ declare const enum AsyncSignalFlags {
  * AsyncSignalImpl
  *
  * # ================================
+ *
+ * @internal
  */
 declare class AsyncSignalImpl<T> extends ComputedSignalImpl<T, AsyncQRL<T>> implements BackRef, AsyncSignal<T> {
     $untrackedLoading$: boolean;
     $untrackedError$: Error | undefined;
-    $loadingEffects$: undefined | Set<EffectSubscription>;
-    $errorEffects$: undefined | Set<EffectSubscription>;
     $current$: AsyncJob<T> | null;
-    $jobs$: AsyncJob<T>[];
-    $concurrency$: number;
-    $interval$: number;
+    $jobs$: AsyncJob<T>[] | undefined;
+    $concurrency$: number | undefined;
+    $expires$: number | undefined;
     $timeoutMs$: number | undefined;
+    $loadingEffects$: undefined | Set<EffectSubscription>;
+    $errorEffects$: undefined | Set<EffectSubscription>;
     $pollTimeoutId$: ReturnType<typeof setTimeout> | undefined;
     $computationTimeoutId$: ReturnType<typeof setTimeout> | undefined;
+    $info$: unknown | undefined;
+    $infoVersion$: number | undefined;
     [_EFFECT_BACK_REF]: Map<EffectProperty | string, EffectSubscription> | undefined;
     constructor(container: _Container | null, fn: AsyncQRL<T>, flags?: SignalFlags | SerializationSignalFlags, options?: AsyncSignalOptions<T>);
     get untrackedValue(): T;
     set untrackedValue(value: T);
+    /**
+     * Read the value, subscribing if in a tracking context. Triggers computation if needed.
+     *
+     * Setting the value will mark the signal as not loading and clear any error, and prevent any
+     * pending computations from writing their results.
+     *
+     * If you want to set the value without affecting loading or error state, set `untrackedValue`
+     * instead and make sure to trigger effects manually if needed.
+     *
+     * If you want to abort pending computations when setting, you have to call `abort()` manually.
+     */
+    get value(): T;
+    set value(value: T);
     /**
      * Loading is true if the signal is still waiting for the promise to resolve, false if the promise
      * has resolved or rejected.
@@ -505,10 +558,16 @@ declare class AsyncSignalImpl<T> extends ComputedSignalImpl<T, AsyncQRL<T>> impl
     get error(): Error | undefined;
     set untrackedError(value: Error | undefined);
     get untrackedError(): Error | undefined;
+    get expires(): number;
+    set expires(value: number);
+    get poll(): boolean;
+    set poll(value: boolean);
+    /** @deprecated Use `expires` and `poll` instead. */
     get interval(): number;
     set interval(value: number);
     /** Invalidates the signal, causing it to re-compute its value. */
-    invalidate(): Promise<void>;
+    invalidate(info?: unknown): Promise<void>;
+    $setInvalid$(allowRecalc: boolean, mustClear: boolean | number): void;
     /** Abort the current computation and run cleanups if needed. */
     abort(reason?: any): void;
     /** Schedule eager cleanup on next macro task if no subscribers remain. */
@@ -518,14 +577,19 @@ declare class AsyncSignalImpl<T> extends ComputedSignalImpl<T, AsyncQRL<T>> impl
     /** Run the computation if needed */
     $computeIfNeeded$(): void;
     $runComputation$(running: AsyncJob<T>): Promise<void>;
+    /**
+     * Sets the error from the given job. We only accept errors from the current job and we ignore
+     * AbortErrors.
+     */
+    $setError$(job: AsyncJob<T>, error: Error): void;
     /** Called after SSR/unmount */
     $destroy$(): Promise<void>;
     private $clearNextPoll$;
     private $scheduleNextPoll$;
     private $hasSubscribers$;
-    $requestCleanups$(job: AsyncJob<T>, reason?: any): Promise<void | null>;
+    $requestCleanups$(job: AsyncJob<T>, reason?: any): void;
     /** Clean up and trigger signal compute once complete */
-    $runCleanups$(job: AsyncJob<T>): Promise<void>;
+    $runCleanups$(job: AsyncJob<T>): Promise<void> | undefined;
 }
 
 /** @public */
@@ -546,19 +610,23 @@ export declare interface AsyncSignalOptions<T> extends ComputedOptions {
      */
     eagerCleanup?: boolean;
     /**
-     * Wait for previous invocation to complete before running again.
+     * Time in milliseconds after which the value expires.
      *
-     * Defaults to `true`.
+     * When the value expires and subscribers exist, the signal is invalidated. If `poll` is `true`
+     * (default), the function is re-run automatically. If `poll` is `false`, the value is marked
+     * stale and recomputation happens when reading `.value` or `.loading`.
      *
-     * @deprecated Not implemented yet
+     * `0` (default) means no expiration.
      */
-    awaitPrevious?: boolean;
+    expires?: number;
     /**
-     * In the browser, re-run the function after `interval` ms if subscribers exist, even when no
-     * input state changed. If `0`, does not poll.
+     * Whether to automatically re-run the function when the value expires. Only relevant when
+     * `expires` is set.
      *
-     * Defaults to `0`.
+     * Defaults to `true`.
      */
+    poll?: boolean;
+    /** @deprecated Use `expires` and `poll` instead. Will be removed before v2 */
     interval?: number;
     /**
      * When true, the async computation is postponed to the browser. On SSR, the signal remains
@@ -567,6 +635,23 @@ export declare interface AsyncSignalOptions<T> extends ComputedOptions {
      * Defaults to `false`.
      */
     clientOnly?: boolean;
+    /**
+     * When true (default), the previous value is kept while the signal re-computes after
+     * invalidation, so reads return stale data instead of throwing a promise. Reactivity will then
+     * update the readers when the new value is ready.
+     *
+     * When false, invalidation clears the value so reads throw the computation promise (like the
+     * initial load), which is useful for navigations where showing old data would be confusing.
+     *
+     * Note that polling invalidations (`expires` with `poll: true`) are not affected by this option
+     * and will keep the old value while the new value is loading, to avoid flashing loaders.
+     *
+     * This option only affects manual invalidations via `invalidate()`, and non-polling expirations
+     * (`poll: false`, or there are no subscribers).
+     *
+     * Defaults to `true`.
+     */
+    allowStale?: boolean;
     /**
      * Maximum time in milliseconds to wait for the async computation to complete. If exceeded, the
      * computation is aborted and an error is thrown.
@@ -604,6 +689,10 @@ declare type BivariantQrlFn<ARGS extends any[], RETURN> = {
 /** @public */
 declare type Booleanish = boolean | `${boolean}`;
 
+declare type Capture = {
+    [K in keyof HTMLElementEventMap as `capture:${K}`]?: boolean;
+};
+
 /**
  * The current captured scope during QRL invocation. This is used to provide the lexical scope for
  * QRL functions. It is used one time per invocation, synchronously, so it is safe to store it in
@@ -630,7 +719,8 @@ declare const enum ChoreBits {
     CHILDREN = 32,
     CLEANUP = 64,
     RECONCILE = 128,
-    DIRTY_MASK = 255
+    ERROR_WRAP = 256,
+    DIRTY_MASK = 511
 }
 
 /**
@@ -1164,7 +1254,7 @@ export declare interface DOMAttributes<EL extends Element> extends DOMAttributes
     class?: ClassList | Signal<ClassList> | undefined;
 }
 
-declare interface DOMAttributesBase<EL extends Element> extends QwikIntrinsicAttributes, PreventDefault, StopPropagation, RefAttr<EL> {
+declare interface DOMAttributesBase<EL extends Element> extends QwikIntrinsicAttributes, PreventDefault, StopPropagation, Capture, Passive, RefAttr<EL> {
     dangerouslySetInnerHTML?: string | undefined;
 }
 
@@ -1439,11 +1529,18 @@ export { h }
 export declare const _hasStoreEffects: (value: StoreTarget, prop: keyof StoreTarget) => boolean;
 
 /**
- * HMR event handler. Replaces the component QRL with a fresh one and marks dirty.
+ * HMR event handler. The host VNode is captured at registration time via QRL captures.
+ *
+ * When called by the qwikloader or the test dispatch, `this` is the serialized captures string
+ * which we deserialize to get the host VNode. When called through `_qDispatch` (client-rendered),
+ * `_captures` is already set by `ensureQrlCaptures` in the QRL call chain.
  *
  * @internal
  */
-export declare const _hmr: (event: Event, element: Element) => void;
+export declare const _hmr: (this: string | undefined, event: CustomEvent<{
+    files: string[];
+    t: number;
+}>, element: Element) => void;
 
 declare type HostElement = _VNode | ISsrNode;
 
@@ -1875,6 +1972,7 @@ declare class LazyRef<TYPE = unknown> {
     $ref$?: (null | ValueOrPromise<TYPE>) | undefined;
     $container$: _Container | undefined;
     dev?: QRLDev | null | undefined;
+    qrls?: Set<any>;
     constructor($chunk$: string | null, $symbol$: string, $symbolFn$: undefined | null | (() => Promise<Record<string, TYPE>>), $ref$?: (null | ValueOrPromise<TYPE>) | undefined, container?: _Container | null);
     /** We don't read hash very often so let's not allocate a string for every QRL */
     get $hash$(): string;
@@ -2065,6 +2163,10 @@ declare type PascalCaseName<T extends string> = T extends keyof LcEventNameMap ?
  */
 declare type PascalCaseNames = 'AnimationEnd' | 'AnimationIteration' | 'AnimationStart' | 'AuxClick' | 'BeforeToggle' | 'CanPlay' | 'CanPlayThrough' | 'CompositionEnd' | 'CompositionStart' | 'CompositionUpdate' | 'ContextMenu' | 'DblClick' | 'DragEnd' | 'DragEnter' | 'DragExit' | 'DragLeave' | 'DragOver' | 'DragStart' | 'DurationChange' | 'FocusIn' | 'FocusOut' | 'FullscreenChange' | 'FullscreenError' | 'GotPointerCapture' | 'KeyDown' | 'KeyPress' | 'KeyUp' | 'LoadedData' | 'LoadedMetadata' | 'LoadEnd' | 'LoadStart' | 'LostPointerCapture' | 'MouseDown' | 'MouseEnter' | 'MouseLeave' | 'MouseMove' | 'MouseOut' | 'MouseOver' | 'MouseUp' | 'PointerCancel' | 'PointerDown' | 'PointerEnter' | 'PointerLeave' | 'PointerMove' | 'PointerOut' | 'PointerOver' | 'PointerUp' | 'QIdle' | 'QInit' | 'QResume' | 'QSymbol' | 'QVisible' | 'QViewTransition' | 'RateChange' | 'RateChange' | 'SecurityPolicyViolation' | 'SelectionChange' | 'SelectStart' | 'TimeUpdate' | 'TouchCancel' | 'TouchEnd' | 'TouchMove' | 'TouchStart' | 'TransitionCancel' | 'TransitionEnd' | 'TransitionRun' | 'TransitionStart' | 'VisibilityChange' | 'VolumeChange';
 
+declare type Passive = {
+    [K in keyof HTMLElementEventMap as `passive:${K}`]?: boolean;
+};
+
 declare type PopoverTargetAction = 'hide' | 'show' | 'toggle';
 
 declare type PossibleEvents = Event | SimplifiedServerRequestEvent | typeof TaskEvent | typeof RenderEvent;
@@ -2409,6 +2511,7 @@ declare type QRLInternalMethods<TYPE> = {
     /** If this returns false, the function execution will be skipped */
     beforeFn?: () => void | false): TYPE extends (...args: any) => any ? (...args: Parameters<TYPE>) => ValueOrPromise<ReturnType<TYPE> | undefined> : unknown;
     $callFn$(withThis: unknown, ...args: QrlArgs<TYPE>): ValueOrPromise<QrlReturn<TYPE>>;
+    $setDev$(dev: QRLDev | null): void;
     /**
      * "with captures" - Get a new QRL for these captures, reusing the lazy ref. It's an internal
      * method but we need to have a stable name because it gets called in user code by the optimizer,
@@ -3390,6 +3493,7 @@ declare interface SSRContainer extends _Container {
     readonly resolvedManifest: ResolvedManifest;
     additionalHeadNodes: Array<JSXNodeInternal>;
     additionalBodyNodes: Array<JSXNodeInternal>;
+    $noScriptHere$: number;
     write(text: string): void;
     openContainer(): void;
     closeContainer(): ValueOrPromise<void>;
@@ -4165,7 +4269,7 @@ export declare const useLexicalScope: <VARS extends any[]>() => VARS;
  * @public
  * @see `useOn`, `useOnWindow`, `useOnDocument`.
  */
-export declare const useOn: <T extends KnownEventNames>(event: T | T[], eventQrl: EventQRL<T>) => void;
+export declare const useOn: <T extends KnownEventNames>(event: T | T[], eventQrl: EventQRL<T>, options?: UseOnOptions) => void;
 
 /**
  * Register a listener on `document`.
@@ -4194,7 +4298,21 @@ export declare const useOn: <T extends KnownEventNames>(event: T | T[], eventQrl
  * });
  * ```
  */
-export declare const useOnDocument: <T extends KnownEventNames>(event: T | T[], eventQrl: EventQRL<T>) => void;
+export declare const useOnDocument: <T extends KnownEventNames>(event: T | T[], eventQrl: EventQRL<T>, options?: UseOnOptions) => void;
+
+/** @public */
+export declare type UseOnOptions = UseOnOptionsBase & ({
+    passive?: boolean;
+    preventdefault?: never;
+} | {
+    passive?: never;
+    preventdefault?: boolean;
+});
+
+declare interface UseOnOptionsBase {
+    capture?: boolean;
+    stoppropagation?: boolean;
+}
 
 /**
  * Register a listener on `window`.
@@ -4224,7 +4342,7 @@ export declare const useOnDocument: <T extends KnownEventNames>(event: T | T[],
  * });
  * ```
  */
-export declare const useOnWindow: <T extends KnownEventNames>(event: T | T[], eventQrl: EventQRL<T>) => void;
+export declare const useOnWindow: <T extends KnownEventNames>(event: T | T[], eventQrl: EventQRL<T>, options?: UseOnOptions) => void;
 
 /**
  * This method works like an async memoized function that runs whenever some tracked value changes
@@ -4621,7 +4739,7 @@ export declare const _VAR_PROPS: unique symbol;
 export declare const _verifySerializable: <T>(value: T, preMessage?: string) => T;
 
 /**
- * 2.0.0-beta.30-dev+5421ed4
+ * 2.0.0-beta.32-dev+0e29f8a
  *
  * @public
  */