@stacksjs/router 0.75.9 → 0.75.11

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export type { BootHook, StacksRouterConfig } from './stacks-router';
 export type { MiddlewareAliases, MiddlewareClasses, MiddlewareClassName, MiddlewareConfig, Request } from './middleware';
 // Export route loader
 export type { RootMountedAppRoute } from './route-loader';
+export type { DefaultRouteBundleSelection } from './route-loader';
 // Export route registry types — owned here rather than in app/Routes.ts
 // so the path doesn't depend on a 5-level relative reach across the
 // framework defaults tree (stacksjs/stacks#1863, T-10).
@@ -33,7 +34,7 @@ export { assertRouteMiddlewareResolvable,
 export { cacheRequestQuery, clearCurrentRequest, getCurrentRequest, getTraceId, request, runWithRequest, setCurrentRequest, withTraceId } from './request-context';
 // Export Middleware class for defining route middleware
 export { defineMiddleware, Middleware } from './middleware';
-export { appRouteRegistry, DEFAULT_ROUTE_REGISTRY, listRootMountedAppRoutes, loadRoutes } from './route-loader';
+export { appRouteRegistry, bundleMounts, DEFAULT_ROUTE_BUNDLE_FEATURES, DEFAULT_ROUTE_REGISTRY, listRootMountedAppRoutes, loadRoutes, mountedDefaultRouteBundles } from './route-loader';
 // Export error handler utilities
 export {
   clearTrackedQueries,

package/dist/index.js

@@ -1 +1 @@
-import"./request-augmentation";export*from"@stacksjs/bun-router";export{assertRouteMiddlewareResolvable,configureViewDirectories,clearCsrfModuleCache,clearMiddlewareCache,createStacksRouter,disableViewRouting,enhanceRequest,findUnresolvableRouteMiddleware,installMiddlewareHotReload,loadMiddlewareHandlers,resetBootHooks,route,runBootHooks,serve,serverResponse,url,warnOnMultipleRouterInstances}from"./stacks-router";export{cacheRequestQuery,clearCurrentRequest,getCurrentRequest,getTraceId,request,runWithRequest,setCurrentRequest,withTraceId}from"./request-context";export{defineMiddleware,Middleware}from"./middleware";export{appRouteRegistry,DEFAULT_ROUTE_REGISTRY,listRootMountedAppRoutes,loadRoutes}from"./route-loader";export{clearTrackedQueries,createErrorResponse,createMiddlewareErrorResponse,createNotFoundResponse,createValidationErrorResponse,getQueryShapeCounts,trackQuery}from"./error-handler";export{listNamedRoutes,listRegisteredRoutes,routeParams}from"./stacks-router";export{isRouterAction,wrapAction}from"./stacks-router";export{createTypedRouter}from"./typed-router";export{clearRouteModelBindings,defineRouteModelBinding,resolveRouteModel,routeModelBindings,setRouteModelFallback}from"./route-model-binding";export{isApiRequest,JSON_CONTENT_TYPE}from"./api-shape";export{rateLimit,rateLimitStatus,clearRateLimit}from"./rate-limit";export{PathParamError,safePathParam,sanitizePathParam}from"./path-sanitize";export{checkApplicationHealth,runHealthProbes}from"./health";export{stream}from"./stacks-router";export{signedUrl,signUrl,verifySignedUrl,verifySignedUrlMiddleware}from"./signed-url";export{EncryptedSessionStore}from"./encrypted-session-store";export{createSessionStore,createStacksSessionStore,DatabaseSessionStore,FileSessionStore,MemorySessionStore,RedisSessionStore}from"./session-factory";
+import"./request-augmentation";export*from"@stacksjs/bun-router";export{assertRouteMiddlewareResolvable,configureViewDirectories,clearCsrfModuleCache,clearMiddlewareCache,createStacksRouter,disableViewRouting,enhanceRequest,findUnresolvableRouteMiddleware,installMiddlewareHotReload,loadMiddlewareHandlers,resetBootHooks,route,runBootHooks,serve,serverResponse,url,warnOnMultipleRouterInstances}from"./stacks-router";export{cacheRequestQuery,clearCurrentRequest,getCurrentRequest,getTraceId,request,runWithRequest,setCurrentRequest,withTraceId}from"./request-context";export{defineMiddleware,Middleware}from"./middleware";export{appRouteRegistry,bundleMounts,DEFAULT_ROUTE_BUNDLE_FEATURES,DEFAULT_ROUTE_REGISTRY,listRootMountedAppRoutes,loadRoutes,mountedDefaultRouteBundles}from"./route-loader";export{clearTrackedQueries,createErrorResponse,createMiddlewareErrorResponse,createNotFoundResponse,createValidationErrorResponse,getQueryShapeCounts,trackQuery}from"./error-handler";export{listNamedRoutes,listRegisteredRoutes,routeParams}from"./stacks-router";export{isRouterAction,wrapAction}from"./stacks-router";export{createTypedRouter}from"./typed-router";export{clearRouteModelBindings,defineRouteModelBinding,resolveRouteModel,routeModelBindings,setRouteModelFallback}from"./route-model-binding";export{isApiRequest,JSON_CONTENT_TYPE}from"./api-shape";export{rateLimit,rateLimitStatus,clearRateLimit}from"./rate-limit";export{PathParamError,safePathParam,sanitizePathParam}from"./path-sanitize";export{checkApplicationHealth,runHealthProbes}from"./health";export{stream}from"./stacks-router";export{signedUrl,signUrl,verifySignedUrl,verifySignedUrlMiddleware}from"./signed-url";export{EncryptedSessionStore}from"./encrypted-session-store";export{createSessionStore,createStacksSessionStore,DatabaseSessionStore,FileSessionStore,MemorySessionStore,RedisSessionStore}from"./session-factory";

package/dist/route-loader.d.ts

@@ -78,6 +78,33 @@ export declare function resolveDefaultRouteBundles(env?: NodeJS.ProcessEnv): Set
  * named, the flags gate exactly as they did before.
  */
 export declare function resolveDefaultRouteBundlesWithDiagnostics(env?: NodeJS.ProcessEnv): { bundles: Set<DefaultRouteBundle>, unknown: string[], explicit: boolean };
+/**
+ * Whether one default bundle mounts, given the selection and its feature flag.
+ *
+ * An app that NAMED its bundles has already answered the question, so the
+ * feature flag does not get a second veto - otherwise `STACKS_DEFAULT_ROUTES=auth`
+ * would still be withheld from an app running with `dashboard` off, which is
+ * the exact case the variable exists for. When nothing was named, the flag
+ * gates as it always did.
+ *
+ * `defaults/bootstrap.ts` decides with this, and so does the views server
+ * when it works out which default pages have routes behind them. One rule in
+ * two processes; a copy in each is how they come to disagree.
+ */
+export declare function bundleMounts(selection: DefaultRouteBundleSelection | undefined, bundle: string, featureEnabled: boolean): boolean;
+/**
+ * The default bundles this app mounts, without mounting anything.
+ *
+ * For a process that needs the answer but does not own the routes: the views
+ * server serves `/login` only when the API process mounts `POST /login`
+ * (stacksjs/stacks#2237). `featureEnabled` is `feature` from
+ * `@stacksjs/config`, passed in so this stays free of config state; call it
+ * after `overridesReady`, for the reason {@link loadFrameworkRoutes} awaits it.
+ *
+ * `social` is not included. It is opt-in, decided by configured providers,
+ * and no default page depends on it alone.
+ */
+export declare function mountedDefaultRouteBundles(featureEnabled: (name: string) => boolean, env?: NodeJS.ProcessEnv): Set<typeof DEFAULT_ROUTE_BUNDLES[number]>;
 /**
  * Load all routes from the registry
  */
@@ -120,9 +147,21 @@ export declare const DEFAULT_ROUTE_BUNDLES: readonly ['auth', 'dashboard', 'deli
 export declare const OPT_IN_ROUTE_BUNDLES: readonly ['social'];
 /** Where {@link loadFrameworkRoutes} leaves the selection for bootstrap.ts. */
 export declare const DEFAULT_ROUTE_BUNDLES_KEY: '__stacksDefaultRouteBundles';
+/**
+ * The feature flag that gates each default bundle when an app has not named
+ * its bundles. `auth` rides on `dashboard` rather than `auth` for the reason
+ * `defaults/bootstrap.ts` gives: `config/auth.ts` ships enabled in every app,
+ * so gating on it would widen existing apps' public surface on upgrade.
+ */
+export declare const DEFAULT_ROUTE_BUNDLE_FEATURES: Record<typeof DEFAULT_ROUTE_BUNDLES[number], string>;
 export declare interface RootMountedAppRoute {
   method: string
   path: string
   file: string
 }
+/** What {@link loadFrameworkRoutes} publishes for bootstrap.ts. */
+export declare interface DefaultRouteBundleSelection {
+  bundles: ReadonlySet<string>
+  explicit: boolean
+}
 export type DefaultRouteBundle = typeof DEFAULT_ROUTE_BUNDLES[number] | typeof OPT_IN_ROUTE_BUNDLES[number];

package/dist/route-loader.js

@@ -1 +1 @@
-import{existsSync}from"node:fs";import{log}from"@stacksjs/logging/runtime";import{route}from"./stacks-router";let rootMountedAppRoutes;export function listRootMountedAppRoutes(){return rootMountedAppRoutes??=[]}export const DEFAULT_ROUTE_REGISTRY={api:"api"};export async function appRouteRegistry(){const{projectPath}=await import("@stacksjs/path"),file=projectPath("app/Routes.ts");if(!existsSync(file))return DEFAULT_ROUTE_REGISTRY;const registry=(await import(file)).default;if(!registry||typeof registry!=="object"||Object.keys(registry).length===0){log.debug("[route-loader] app/Routes.ts exports no registry; using the default");return DEFAULT_ROUTE_REGISTRY}return registry}export async function loadRoutes(registry){for(const[key,definition]of Object.entries(registry)){const config=normalizeDefinition(definition),prefix=config.prefix!==void 0?config.prefix?config.prefix.startsWith("/")?config.prefix:`/${config.prefix}`:void 0:key==="web"?void 0:`/${key}`,middleware=normalizeMiddleware(config.middleware);log.debug(`[route-loader] Loading: ${config.path} prefix=${prefix||"/"} middleware=[${middleware.join(", ")}]`);try{if(prefix||middleware.length>0)await route.group({prefix,middleware:middleware.length>0?middleware:void 0},async()=>{await importRouteFile(config.path)});else{const before=registeredRouteKeys();await importRouteFile(config.path);for(const entry of currentRouteTable()){const method=String(entry.method??"").toUpperCase(),path=String(entry.path??"");if(!method||!path||before.has(`${method} ${path}`))continue;(rootMountedAppRoutes??=[]).push({method,path,file:`routes/${config.path}.ts`})}}}catch(error){const message=error instanceof Error?error.message:String(error);console.error(`[Routes] Failed to load route file '${config.path}': ${message}`);throw Error(`Route loading failed for '${config.path}': ${message}`)}}await loadFrameworkRoutes()}export const DEFAULT_ROUTE_BUNDLES=["auth","dashboard","delivery","email","forms"],OPT_IN_ROUTE_BUNDLES=["social"],DEFAULT_ROUTE_BUNDLES_KEY="__stacksDefaultRouteBundles";export function resolveDefaultRouteBundles(env=process.env){return resolveDefaultRouteBundlesWithDiagnostics(env).bundles}export function resolveDefaultRouteBundlesWithDiagnostics(env=process.env){const all=()=>new Set(DEFAULT_ROUTE_BUNDLES),raw=env.STACKS_DEFAULT_ROUTES;if(raw!==void 0){const names=raw.split(",").map((name)=>name.trim().toLowerCase()).filter(Boolean);if(names.length===0||names.includes("none"))return{bundles:new Set,unknown:[],explicit:!0};if(names.includes("all"))return{bundles:all(),unknown:[],explicit:!0};const bundles=new Set,unknown=[];for(const name of names)if(DEFAULT_ROUTE_BUNDLES.includes(name)||OPT_IN_ROUTE_BUNDLES.includes(name))bundles.add(name);else unknown.push(name);return{bundles,unknown,explicit:!0}}if(env.STACKS_SKIP_DEFAULT_ROUTES==="1")return{bundles:new Set,unknown:[],explicit:!0};return{bundles:all(),unknown:[],explicit:!1}}async function loadFrameworkRoutes(){const{bundles,unknown,explicit}=resolveDefaultRouteBundlesWithDiagnostics();for(const name of unknown)log.warn(`[Routes] STACKS_DEFAULT_ROUTES lists unknown bundle "${name}" - known bundles are ${DEFAULT_ROUTE_BUNDLES.join(", ")}.`);if(bundles.size===0)return;globalThis[DEFAULT_ROUTE_BUNDLES_KEY]={bundles,explicit};try{try{const{overridesReady}=await import("@stacksjs/config");await overridesReady}catch{}const{frameworkPath}=await import("@stacksjs/path"),bootstrapPath=frameworkPath("defaults/bootstrap.ts");if(await Bun.file(bootstrapPath).exists())await import(bootstrapPath)}catch(error){const message=error instanceof Error?error.message:String(error);if(!message.includes("Cannot find module")&&!message.includes("MODULE_NOT_FOUND"))console.error(`[Routes] Failed to load framework bootstrap: ${message}`)}}function assertSafeRouteName(routeName){if(typeof routeName!=="string"||routeName.length===0)throw Error("[route-loader] Invalid route path: empty or non-string");if(routeName.includes("\x00"))throw Error("[route-loader] Invalid route path: null byte");let decoded;try{decoded=decodeURIComponent(routeName)}catch{throw Error("[route-loader] Invalid route path: malformed URL encoding")}const cleanPath=decoded.replace(/\.ts$/,"");if(cleanPath.startsWith("/")||/^[A-Za-z]:[\\/]/.test(cleanPath))throw Error(`[route-loader] Invalid route path: absolute paths not allowed (${cleanPath})`);if(cleanPath.split(/[/\\]/).some((s)=>s===".."))throw Error(`[route-loader] Invalid route path: '..' segment not allowed (${cleanPath})`);return cleanPath}async function importRouteFile(routeName){const cleanPath=assertSafeRouteName(routeName),{projectPath}=await import("@stacksjs/path");await import(projectPath(`routes/${cleanPath}`))}function normalizeDefinition(def){if(typeof def==="string")return{path:def};return def}function normalizeMiddleware(middleware){if(!middleware)return[];if(typeof middleware==="string")return[middleware];return middleware}function currentRouteTable(){return route.routes??[]}function registeredRouteKeys(){const keys=new Set;for(const entry of currentRouteTable())keys.add(`${String(entry.method??"").toUpperCase()} ${String(entry.path??"")}`);return keys}
+import{existsSync}from"node:fs";import{log}from"@stacksjs/logging/runtime";import{route}from"./stacks-router";let rootMountedAppRoutes;export function listRootMountedAppRoutes(){return rootMountedAppRoutes??=[]}export const DEFAULT_ROUTE_REGISTRY={api:"api"};export async function appRouteRegistry(){const{projectPath}=await import("@stacksjs/path"),file=projectPath("app/Routes.ts");if(!existsSync(file))return DEFAULT_ROUTE_REGISTRY;const registry=(await import(file)).default;if(!registry||typeof registry!=="object"||Object.keys(registry).length===0){log.debug("[route-loader] app/Routes.ts exports no registry; using the default");return DEFAULT_ROUTE_REGISTRY}return registry}export async function loadRoutes(registry){for(const[key,definition]of Object.entries(registry)){const config=normalizeDefinition(definition),prefix=config.prefix!==void 0?config.prefix?config.prefix.startsWith("/")?config.prefix:`/${config.prefix}`:void 0:key==="web"?void 0:`/${key}`,middleware=normalizeMiddleware(config.middleware);log.debug(`[route-loader] Loading: ${config.path} prefix=${prefix||"/"} middleware=[${middleware.join(", ")}]`);try{if(prefix||middleware.length>0)await route.group({prefix,middleware:middleware.length>0?middleware:void 0},async()=>{await importRouteFile(config.path)});else{const before=registeredRouteKeys();await importRouteFile(config.path);for(const entry of currentRouteTable()){const method=String(entry.method??"").toUpperCase(),path=String(entry.path??"");if(!method||!path||before.has(`${method} ${path}`))continue;(rootMountedAppRoutes??=[]).push({method,path,file:`routes/${config.path}.ts`})}}}catch(error){const message=error instanceof Error?error.message:String(error);console.error(`[Routes] Failed to load route file '${config.path}': ${message}`);throw Error(`Route loading failed for '${config.path}': ${message}`)}}await loadFrameworkRoutes()}export const DEFAULT_ROUTE_BUNDLES=["auth","dashboard","delivery","email","forms"],OPT_IN_ROUTE_BUNDLES=["social"],DEFAULT_ROUTE_BUNDLES_KEY="__stacksDefaultRouteBundles";export function resolveDefaultRouteBundles(env=process.env){return resolveDefaultRouteBundlesWithDiagnostics(env).bundles}export function resolveDefaultRouteBundlesWithDiagnostics(env=process.env){const all=()=>new Set(DEFAULT_ROUTE_BUNDLES),raw=env.STACKS_DEFAULT_ROUTES;if(raw!==void 0){const names=raw.split(",").map((name)=>name.trim().toLowerCase()).filter(Boolean);if(names.length===0||names.includes("none"))return{bundles:new Set,unknown:[],explicit:!0};if(names.includes("all"))return{bundles:all(),unknown:[],explicit:!0};const bundles=new Set,unknown=[];for(const name of names)if(DEFAULT_ROUTE_BUNDLES.includes(name)||OPT_IN_ROUTE_BUNDLES.includes(name))bundles.add(name);else unknown.push(name);return{bundles,unknown,explicit:!0}}if(env.STACKS_SKIP_DEFAULT_ROUTES==="1")return{bundles:new Set,unknown:[],explicit:!0};return{bundles:all(),unknown:[],explicit:!1}}export const DEFAULT_ROUTE_BUNDLE_FEATURES={auth:"dashboard",dashboard:"dashboard",delivery:"commerce",email:"email",forms:"forms"};export function bundleMounts(selection,bundle,featureEnabled){if(selection&&!selection.bundles.has(bundle))return!1;return selection?.explicit?!0:featureEnabled}export function mountedDefaultRouteBundles(featureEnabled,env=process.env){const selection=resolveDefaultRouteBundlesWithDiagnostics(env),mounted=new Set;for(const bundle of DEFAULT_ROUTE_BUNDLES)if(bundleMounts(selection,bundle,featureEnabled(DEFAULT_ROUTE_BUNDLE_FEATURES[bundle])))mounted.add(bundle);return mounted}async function loadFrameworkRoutes(){const{bundles,unknown,explicit}=resolveDefaultRouteBundlesWithDiagnostics();for(const name of unknown)log.warn(`[Routes] STACKS_DEFAULT_ROUTES lists unknown bundle "${name}" - known bundles are ${DEFAULT_ROUTE_BUNDLES.join(", ")}.`);if(bundles.size===0)return;globalThis[DEFAULT_ROUTE_BUNDLES_KEY]={bundles,explicit};try{try{const{overridesReady}=await import("@stacksjs/config");await overridesReady}catch{}const{frameworkPath}=await import("@stacksjs/path"),bootstrapPath=frameworkPath("defaults/bootstrap.ts");if(await Bun.file(bootstrapPath).exists())await import(bootstrapPath)}catch(error){const message=error instanceof Error?error.message:String(error);if(!message.includes("Cannot find module")&&!message.includes("MODULE_NOT_FOUND"))console.error(`[Routes] Failed to load framework bootstrap: ${message}`)}}function assertSafeRouteName(routeName){if(typeof routeName!=="string"||routeName.length===0)throw Error("[route-loader] Invalid route path: empty or non-string");if(routeName.includes("\x00"))throw Error("[route-loader] Invalid route path: null byte");let decoded;try{decoded=decodeURIComponent(routeName)}catch{throw Error("[route-loader] Invalid route path: malformed URL encoding")}const cleanPath=decoded.replace(/\.ts$/,"");if(cleanPath.startsWith("/")||/^[A-Za-z]:[\\/]/.test(cleanPath))throw Error(`[route-loader] Invalid route path: absolute paths not allowed (${cleanPath})`);if(cleanPath.split(/[/\\]/).some((s)=>s===".."))throw Error(`[route-loader] Invalid route path: '..' segment not allowed (${cleanPath})`);return cleanPath}async function importRouteFile(routeName){const cleanPath=assertSafeRouteName(routeName),{projectPath}=await import("@stacksjs/path");await import(projectPath(`routes/${cleanPath}`))}function normalizeDefinition(def){if(typeof def==="string")return{path:def};return def}function normalizeMiddleware(middleware){if(!middleware)return[];if(typeof middleware==="string")return[middleware];return middleware}function currentRouteTable(){return route.routes??[]}function registeredRouteKeys(){const keys=new Set;for(const entry of currentRouteTable())keys.add(`${String(entry.method??"").toUpperCase()} ${String(entry.path??"")}`);return keys}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/router",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.9",
+  "version": "0.75.11",
   "description": "The Stacks framework router.",
   "author": "Chris Breuer",
   "contributors": [
@@ -67,27 +67,27 @@
   },
   "dependencies": {
     "@stacksjs/bun-router": "^0.1.18",
-    "@stacksjs/cache": "0.75.9",
-    "@stacksjs/collections": "0.75.9",
-    "@stacksjs/config": "0.75.9",
-    "@stacksjs/error-handling": "0.75.9",
-    "@stacksjs/logging": "0.75.9",
-    "@stacksjs/pagination": "0.75.9",
-    "@stacksjs/path": "0.75.9",
-    "@stacksjs/security": "0.75.9",
-    "@stacksjs/storage": "0.75.9",
+    "@stacksjs/cache": "0.75.11",
+    "@stacksjs/collections": "0.75.11",
+    "@stacksjs/config": "0.75.11",
+    "@stacksjs/error-handling": "0.75.11",
+    "@stacksjs/logging": "0.75.11",
+    "@stacksjs/pagination": "0.75.11",
+    "@stacksjs/path": "0.75.11",
+    "@stacksjs/security": "0.75.11",
+    "@stacksjs/storage": "0.75.11",
     "ts-rate-limiter": "^0.4.10"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.75.9",
-    "@stacksjs/types": "0.75.9",
+    "@stacksjs/actions": "0.75.11",
+    "@stacksjs/types": "0.75.11",
     "better-dx": "^0.2.24"
   },
   "peerDependencies": {
-    "@stacksjs/api": "0.75.9",
-    "@stacksjs/auth": "0.75.9",
-    "@stacksjs/database": "0.75.9",
-    "@stacksjs/validation": "0.75.9"
+    "@stacksjs/api": "0.75.11",
+    "@stacksjs/auth": "0.75.11",
+    "@stacksjs/database": "0.75.11",
+    "@stacksjs/validation": "0.75.11"
   },
   "peerDependenciesMeta": {
     "@stacksjs/api": {