@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/rsc/types.ts

@@ -7,7 +7,7 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouter } from "../router.js";
+import type { RSCRouterInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
@@ -114,6 +114,14 @@ export interface SSRRenderOptions {
    * Nonce for Content Security Policy (CSP)
    */
   nonce?: string;
+
+  /**
+   * SSR stream mode.
+   *
+   * - `"stream"` (default) — start flushing HTML immediately.
+   * - `"allReady"` — await `stream.allReady` before returning.
+   */
+  streamMode?: import("../router/router-options.js").SSRStreamMode;
 }
 
 /**
@@ -161,7 +169,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouter<TEnv, TRoutes>;
+  router: RSCRouterInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.
@@ -238,6 +246,16 @@ export interface CreateRSCHandlerOptions<
    *   nonce: (request, env) => env.nonce,
    * });
    * ```
+   *
+   * @example Access nonce in middleware
+   * ```tsx
+   * import { nonce } from "@rangojs/router";
+   *
+   * const cspMiddleware: Middleware = async (ctx, next) => {
+   *   const value = ctx.get(nonce); // string | undefined
+   *   await next();
+   * };
+   * ```
    */
   nonce?: NonceProvider<TEnv>;
 }

package/src/search-params.ts

@@ -55,14 +55,22 @@ type Simplify<T> = { [K in keyof T]: T[K] };
 /**
  * Resolve a SearchSchema to its typed object.
  *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
  * @example
  * type S = { q: "string"; page: "number?"; sort: "string?" };
  * type R = ResolveSearchSchema<S>;
- * // { q: string; page?: number; sort?: string }
+ * // { q: string | undefined; page?: number; sort?: string }
  */
 export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
   {
-    [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>>;
+    [K in RequiredKeys<T> & string]:
+      | ResolveBaseType<BaseType<T[K]>>
+      | undefined;
   } & {
     [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
   }
@@ -127,20 +135,32 @@ type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap
       : {}
   : {};
 
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
 /** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
 type ExtractParamsFromPattern<T extends string> =
   T extends `${string}:${infer Param}/${infer Rest}`
-    ? Param extends `${infer Name}?`
-      ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
-      : Param extends `${infer Name}(${string})`
-        ? { [K in Name]: string } & ExtractParamsFromPattern<`/${Rest}`>
-        : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
+    ? Param extends `${infer Name}(${infer C})?`
+      ? {
+          [K in Name]?: ParseConstraint<C>;
+        } & ExtractParamsFromPattern<`/${Rest}`>
+      : Param extends `${infer Name}(${infer C})`
+        ? {
+            [K in Name]: ParseConstraint<C>;
+          } & ExtractParamsFromPattern<`/${Rest}`>
+        : Param extends `${infer Name}?`
+          ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
+          : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
     : T extends `${string}:${infer Param}`
-      ? Param extends `${infer Name}?`
-        ? { [K in Name]?: string }
-        : Param extends `${infer Name}(${string})`
-          ? { [K in Name]: string }
-          : { [K in Param]: string }
+      ? Param extends `${infer Name}(${infer C})?`
+        ? { [K in Name]?: ParseConstraint<C> }
+        : Param extends `${infer Name}(${infer C})`
+          ? { [K in Name]: ParseConstraint<C> }
+          : Param extends `${infer Name}?`
+            ? { [K in Name]?: string }
+            : { [K in Param]: string }
       : {};
 
 // ============================================================================
@@ -154,7 +174,9 @@ type ExtractParamsFromPattern<T extends string> =
  * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
  *
- * Missing required params are set to their zero value (empty string / 0 / false).
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
  */
 export function parseSearchParams<T extends SearchSchema>(
   searchParams: URLSearchParams,
@@ -168,13 +190,7 @@ export function parseSearchParams<T extends SearchSchema>(
     const raw = searchParams.get(key);
 
     if (raw === null) {
-      if (!isOptional) {
-        // Required param missing: use zero value
-        if (baseType === "string") result[key] = "";
-        else if (baseType === "number") result[key] = 0;
-        else if (baseType === "boolean") result[key] = false;
-      }
-      // Optional params are omitted (undefined)
+      // Missing params are omitted (undefined) regardless of required/optional
       continue;
     }
 
@@ -182,11 +198,10 @@ export function parseSearchParams<T extends SearchSchema>(
       result[key] = raw;
     } else if (baseType === "number") {
       const num = Number(raw);
-      if (Number.isNaN(num)) {
-        if (!isOptional) result[key] = 0;
-      } else {
+      if (!Number.isNaN(num)) {
         result[key] = num;
       }
+      // NaN treated as missing (undefined)
     } else if (baseType === "boolean") {
       result[key] = raw === "true" || raw === "1";
     }

package/src/server/context.ts

@@ -11,6 +11,7 @@ import type {
   TransitionConfig,
 } from "../types";
 import { invariant } from "../errors";
+import type { DefaultRouteName } from "../types/global-namespace.js";
 
 // ============================================================================
 //  Performance Metrics Types
@@ -25,6 +26,7 @@ export interface PerformanceMetric {
   label: string; // e.g., "route-matching", "loader:UserLoader"
   duration: number; // milliseconds
   startTime: number; // relative to request start
+  depth?: number; // nesting level for hierarchical display (0 = top-level)
 }
 
 /**
@@ -120,6 +122,8 @@ export type InterceptSelectorContext<TEnv = any> = {
   request: Request; // The HTTP request object
   env: TEnv; // Platform bindings (Cloudflare env, etc.)
   segments: InterceptSegmentsState; // Client's current segments (where navigating FROM)
+  fromRouteName?: DefaultRouteName; // Named route being navigated away from (undefined for unnamed routes)
+  toRouteName?: DefaultRouteName; // Named route being navigated to (undefined for unnamed routes)
 };
 
 /**
@@ -254,10 +258,18 @@ interface HelperContext {
   urlPrefix?: string;
   /** Name prefix from include() - applied to all named routes */
   namePrefix?: string;
+  /** True when this scope is at root level (no named include boundary above).
+   *  Routes at root scope allow dot-local reverse to fall back to bare names. */
+  rootScoped?: boolean;
   /** Run helper for cleaner middleware code */
   run?: <T>(fn: () => T | Promise<T>) => T | Promise<T>;
   /** Tracked includes for build-time manifest generation */
   trackedIncludes?: TrackedInclude[];
+  /** Cache profiles for DSL-time cache("profileName") resolution */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
 }
 // Use a global symbol key so the AsyncLocalStorage instance survives HMR
 // module re-evaluation. Without this, Vite's RSC module runner may create
@@ -399,7 +411,9 @@ export const getContext = (): {
           searchSchemas: store.searchSchemas,
           urlPrefix: store.urlPrefix,
           namePrefix: store.namePrefix,
+          rootScoped: store.rootScoped,
           trackedIncludes: store.trackedIncludes,
+          cacheProfiles: store.cacheProfiles,
         },
         callback,
       );
@@ -436,7 +450,9 @@ export const getContext = (): {
           searchSchemas,
           urlPrefix: store?.urlPrefix,
           namePrefix: store?.namePrefix,
+          rootScoped: store?.rootScoped,
           trackedIncludes: store?.trackedIncludes,
+          cacheProfiles: store?.cacheProfiles,
         },
         callback,
       );
@@ -469,17 +485,41 @@ export function runWithPrefixes<T>(
   } else {
     combinedUrlPrefix = urlPrefix;
   }
-  const combinedNamePrefix = namePrefix
-    ? store.namePrefix
-      ? `${store.namePrefix}.${namePrefix}`
-      : namePrefix
-    : store.namePrefix;
+  const combinedNamePrefix =
+    namePrefix !== undefined
+      ? namePrefix === ""
+        ? store.namePrefix
+        : store.namePrefix
+          ? `${store.namePrefix}.${namePrefix}`
+          : namePrefix
+      : store.namePrefix;
+
+  // Track root scope for dot-local reverse resolution.
+  //
+  // The flag answers: "can this route reach bare names at root scope?"
+  // It propagates through the include chain:
+  //
+  //   { name: "" }    — transparent: inherit parent, default true
+  //   { name: "foo" } — inherit parent if already set, else create boundary (false)
+  //   no name          — inherit parent unchanged
+  //
+  // This means { name: "" } + nested { name: "sub" } keeps rootScoped=true
+  // (the outer transparent include establishes root access, and the inner
+  // named include inherits it). But a direct { name: "sub" } at root gets
+  // rootScoped=false (no prior root-access grant, so it creates a boundary).
+  const combinedRootScoped =
+    namePrefix === ""
+      ? (store.rootScoped ?? true)
+      : namePrefix !== undefined
+        ? (store.rootScoped ?? false)
+        : store.rootScoped;
 
   return RSCRouterContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
       namePrefix: combinedNamePrefix,
+      rootScoped: combinedRootScoped,
     },
     callback,
   );
@@ -501,6 +541,15 @@ export function getNamePrefix(): string | undefined {
   return store?.namePrefix;
 }
 
+/**
+ * Get whether the current scope is at root level (no named include boundary above).
+ * Returns true at root or inside { name: "" } includes, false inside named includes.
+ */
+export function getRootScoped(): boolean {
+  const store = RSCRouterContext.getStore();
+  return store?.rootScoped ?? true;
+}
+
 // Export HelperContext type for use in other modules
 export type { HelperContext };
 
@@ -519,7 +568,7 @@ export type { HelperContext };
  * done(); // Records duration
  * ```
  */
-export function track(label: string): () => void {
+export function track(label: string, depth?: number): () => void {
   const store = RSCRouterContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
@@ -532,6 +581,11 @@ export function track(label: string): () => void {
   return () => {
     const duration =
       performance.now() - store.metrics!.requestStart - startTime;
-    store.metrics!.metrics.push({ label, duration, startTime });
+    store.metrics!.metrics.push({
+      label,
+      duration,
+      startTime,
+      ...(depth != null ? { depth } : {}),
+    });
   };
 }

package/src/server/cookie-store.ts

@@ -0,0 +1,190 @@
+/**
+ * Cookie Store — Next.js-style cookie facade backed by the response-derived model.
+ *
+ * `cookies()` returns a CookieStore scoped to the current request.
+ * Reads merge the original Cookie header with Set-Cookie mutations
+ * already queued on the response stub (last-write-wins).
+ * Writes append Set-Cookie to the response stub.
+ */
+
+import type { CookieOptions } from "../router/middleware-types.js";
+import { getRequestContext } from "./request-context.js";
+import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
+
+/**
+ * A single cookie entry returned by get() and getAll().
+ */
+export interface Cookie {
+  name: string;
+  value: string;
+}
+
+/**
+ * Request-scoped cookie store.
+ *
+ * Reads see the effective merged view (original request + same-request mutations).
+ * Writes append Set-Cookie headers to the shared response stub.
+ */
+export interface CookieStore {
+  /** Get a single cookie by name. Returns undefined if not set or deleted. */
+  get(name: string): Cookie | undefined;
+
+  /** Get all effective cookies, or all cookies with a given name. */
+  getAll(name?: string): Cookie[];
+
+  /** Check whether a cookie exists in the effective view. */
+  has(name: string): boolean;
+
+  /** Set a cookie (appends Set-Cookie to the response stub). */
+  set(name: string, value: string, options?: CookieOptions): void;
+
+  /** Delete a cookie (appends Set-Cookie with maxAge=0 to the response stub). */
+  delete(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+}
+
+/**
+ * Get the request-scoped cookie store.
+ *
+ * Must be called inside a request context (middleware, handler, loader, action).
+ * Throws if called outside request scope.
+ *
+ * @example
+ * ```typescript
+ * import { cookies } from "@rangojs/router";
+ *
+ * // In a handler, loader, or action:
+ * const session = cookies().get("session")?.value;
+ * cookies().set("session", "new-token", { httpOnly: true });
+ * cookies().delete("session");
+ * ```
+ */
+export function cookies(): CookieStore {
+  const ctx = getRequestContext();
+  assertNotInsideCacheContext(ctx, "cookies");
+  return createCookieStore(ctx);
+}
+
+/**
+ * Read-only view of HTTP headers.
+ * Exposes only the read methods of the Headers API.
+ */
+export interface ReadonlyHeaders {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): HeadersIterator<[string, string]>;
+  keys(): HeadersIterator<string>;
+  values(): HeadersIterator<string>;
+  forEach(
+    callback: (value: string, name: string, parent: ReadonlyHeaders) => void,
+  ): void;
+  [Symbol.iterator](): HeadersIterator<[string, string]>;
+}
+
+// Minimal iterator interface (avoids pulling IterableIterator from lib.dom)
+type HeadersIterator<T> = IterableIterator<T>;
+
+/**
+ * Throw if called inside a "use cache" function.
+ * Reading request-scoped data (cookies, headers) inside a cached function
+ * produces results that vary per request but the cache key does not include
+ * those values, leading to one user's data being served to another.
+ */
+function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `${fnName}() cannot be called inside a "use cache" function. ` +
+        `Request-scoped data (cookies, headers) varies per request but is not ` +
+        `reflected in the cache key, so cached results would be served to the ` +
+        `wrong users. Extract the value before the cached function and pass it ` +
+        `as an argument:\n\n` +
+        `  const locale = cookies().get("locale")?.value ?? "en";\n` +
+        `  const data = await getCachedData(locale); // locale is now in the cache key`,
+    );
+  }
+}
+
+const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
+
+/**
+ * Get the original request headers (read-only).
+ *
+ * Must be called inside a request context.
+ * Returns a read-only view of the incoming request's headers.
+ * Mutation methods (set, append, delete) throw at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { headers } from "@rangojs/router";
+ *
+ * const auth = headers().get("authorization");
+ * const contentType = headers().get("content-type");
+ * ```
+ */
+export function headers(): ReadonlyHeaders {
+  const ctx = getRequestContext();
+  assertNotInsideCacheContext(ctx, "headers");
+  return new Proxy(ctx.request.headers, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {
+        return () => {
+          throw new Error(
+            `headers().${prop}() is not allowed. headers() returns a read-only view of request headers. ` +
+              `Use ctx.header() to set response headers.`,
+          );
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as unknown as ReadonlyHeaders;
+}
+
+/**
+ * Create a CookieStore backed by a RequestContext.
+ * @internal Shared between cookies() shorthand and context methods.
+ */
+function createCookieStore(ctx: {
+  cookie(name: string): string | undefined;
+  cookies(): Record<string, string>;
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  deleteCookie(
+    name: string,
+    options?: Pick<CookieOptions, "domain" | "path">,
+  ): void;
+}): CookieStore {
+  return {
+    get(name: string): Cookie | undefined {
+      const value = ctx.cookie(name);
+      return value !== undefined ? { name, value } : undefined;
+    },
+
+    getAll(name?: string): Cookie[] {
+      const all = ctx.cookies();
+      if (name !== undefined) {
+        const value = all[name];
+        return value !== undefined ? [{ name, value }] : [];
+      }
+      return Object.entries(all).map(([n, v]) => ({ name: n, value: v }));
+    },
+
+    has(name: string): boolean {
+      return ctx.cookie(name) !== undefined;
+    },
+
+    set(name: string, value: string, options?: CookieOptions): void {
+      ctx.setCookie(name, value, options);
+    },
+
+    delete(
+      name: string,
+      options?: Pick<CookieOptions, "domain" | "path">,
+    ): void {
+      ctx.deleteCookie(name, options);
+    },
+  };
+}

package/src/server/fetchable-loader-store.ts

@@ -12,21 +12,26 @@
 import type { LoaderFn } from "../types.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 
-const fetchableLoaderRegistry = new Map<
-  string,
-  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
->();
+export interface LoaderRegistryEntry {
+  fn: LoaderFn<any, any, any>;
+  middleware: MiddlewareFn[];
+  /** Whether this loader is fetchable via the _rsc_loader endpoint. */
+  fetchable: boolean;
+}
+
+const fetchableLoaderRegistry = new Map<string, LoaderRegistryEntry>();
 
 export function registerFetchableLoader(
   id: string,
   fn: LoaderFn<any, any, any>,
   middleware: MiddlewareFn[],
+  fetchable: boolean,
 ): void {
-  fetchableLoaderRegistry.set(id, { fn, middleware });
+  fetchableLoaderRegistry.set(id, { fn, middleware, fetchable });
 }
 
 export function getFetchableLoader(
   id: string,
-): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
+): LoaderRegistryEntry | undefined {
   return fetchableLoaderRegistry.get(id);
 }

package/src/server/handle-store.ts

@@ -13,6 +13,19 @@
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
+function createLateHandlePushError(
+  handleName: string,
+  segmentId: string,
+): Error {
+  const error = new Error(
+    `Handle "${handleName}" for segment "${segmentId}" was pushed after handle collection completed. ` +
+      `This usually means an async JSX subtree suspended and later tried to push a handle during streaming. ` +
+      `Push handles from the route/layout handler or during the initial synchronous JSX render instead.`,
+  );
+  error.name = "LateHandlePushError";
+  return error;
+}
+
 /**
  * Deep clone handle data to create a snapshot.
  * @internal
@@ -44,11 +57,26 @@ export interface HandleStore {
   track<T>(promise: Promise<T>): Promise<T>;
 
   /**
-   * Promise that resolves when all tracked handlers have settled.
-   * Does not reject - uses Promise.allSettled internally.
+   * Signal that no more track() calls will be made.
+   * settled will not resolve until seal() is called AND all tracked
+   * promises have settled. Calling stream() or getData() auto-seals.
+   */
+  seal(): void;
+
+  /**
+   * Promise that resolves when the store is sealed AND all tracked
+   * handlers have settled.
    */
   readonly settled: Promise<void>;
 
+  /**
+   * Optional error callback for late streaming-handle failures.
+   * Called when push() throws LateHandlePushError (handle pushed after
+   * stream completion). Allows the router to surface these errors
+   * to onError and telemetry.
+   */
+  onError?: (error: Error) => void;
+
   /**
    * Push handle data for a specific handle and segment.
    * Multiple pushes to the same handle/segment accumulate in an array.
@@ -58,9 +86,7 @@ export interface HandleStore {
 
   /**
    * Get all collected handle data after all handlers have settled.
-   * Returns a promise that waits for `settled`, then returns the data.
-   * The data may contain unresolved promises which RSC will stream.
-   * @deprecated Use stream() for progressive updates
+   * Waits for `settled`, then returns the finalized data.
    */
   getData(): Promise<HandleData>;
 
@@ -108,9 +134,31 @@ export interface HandleStore {
  * ```
  */
 export function createHandleStore(): HandleStore {
-  const pending: Promise<unknown>[] = [];
   const data: HandleData = {};
 
+  // Settlement barrier: resolved only when sealed AND inflight === 0.
+  // seal() signals "no more track() calls". Each track() increments
+  // inflightCount, each promise.finally() decrements. settled resolves
+  // once both conditions are met — even if tracks are added while
+  // earlier ones are still in flight.
+  let sealed = false;
+  let inflightCount = 0;
+  let drainWaiters: (() => void)[] = [];
+
+  function notifyDrain() {
+    if (sealed && inflightCount === 0 && drainWaiters.length > 0) {
+      const waiters = drainWaiters;
+      drainWaiters = [];
+      for (const resolve of waiters) resolve();
+    }
+  }
+
+  function sealInternal() {
+    if (sealed) return;
+    sealed = true;
+    notifyDrain();
+  }
+
   // Queue for pending emissions and resolver for waiting consumer
   let pendingEmissions: HandleData[] = [];
   let emissionResolver: (() => void) | null = null;
@@ -137,18 +185,38 @@ export function createHandleStore(): HandleStore {
 
   return {
     track<T>(promise: Promise<T>): Promise<T> {
-      pending.push(promise);
+      inflightCount++;
+      // Use .then(onSettle, onSettle) instead of .finally() to avoid
+      // creating an unhandled rejection branch when the tracked promise
+      // rejects (e.g. error route handlers). .finally() re-throws the
+      // rejection on a new branch that nobody catches, which can crash
+      // the server process.
+      const onSettle = () => {
+        inflightCount--;
+        notifyDrain();
+      };
+      promise.then(onSettle, onSettle);
       return promise;
     },
 
+    seal() {
+      sealInternal();
+    },
+
     get settled(): Promise<void> {
-      if (pending.length === 0) {
-        return Promise.resolve();
-      }
-      return Promise.allSettled(pending).then(() => {});
+      if (sealed && inflightCount === 0) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        drainWaiters.push(resolve);
+      });
     },
 
     push(handleName: string, segmentId: string, value: unknown): void {
+      if (completed) {
+        const error = createLateHandlePushError(handleName, segmentId);
+        if (this.onError) this.onError(error);
+        throw error;
+      }
+
       if (!data[handleName]) {
         data[handleName] = {};
       }
@@ -163,10 +231,14 @@ export function createHandleStore(): HandleStore {
     },
 
     getData(): Promise<HandleData> {
-      return this.settled.then(() => data);
+      sealInternal();
+      return this.settled.then(() => cloneHandleData(data));
     },
 
     async *stream(): AsyncGenerator<HandleData, void, unknown> {
+      // Auto-seal: stream() is called after all track() registrations.
+      sealInternal();
+
       // Set up completion handler
       this.settled.then(() => {
         completed = true;