@stacksjs/config 0.74.50 → 0.74.52

package/dist/config.d.ts

@@ -1,115 +1,2 @@
-import { defaults } from './defaults';
-import { overrides, overridesReady } from './overrides';
-import type { StacksOptions } from '@stacksjs/types';
-/*.ts` file has loaded and the
- * `overrides` instance has been mutated in place. Use this in code paths
- * that *must* see the merged values — typically anything outside the
- * normal request flow (e.g. CLI commands, top-level boot scripts) where
- * the request hasn't yet hit a route handler that already awaited.
- *
- * Inside request handlers / routes you generally do *not* need to await
- * this: the router's `serverResponse()` only fires after `importRoutes()`
- * resolves, and `importRoutes()` indirectly awaits config (it reads
- * `app/Routes.ts`, which imports config). So the proxy returns merged
- * values for all "normal" request-time reads.
- *
- * @example
- * ```ts
- * import { config, awaitConfig } from '@stacksjs/config'
- *
- * // CLI / top-level script — config files may not be loaded yet
- * await awaitConfig()
- * console.log(config.ports.api) // guaranteed to be the user value
- * ```
- */
-export declare function awaitConfig(): Promise<StacksOptions>;
-/**
- * Resolves once `database` config has been read by `@stacksjs/database`'s
- * lazy initializer. Use it from boot scripts that need a live `db` handle
- * before the request loop starts.
- *
- * Why a separate signal: `overridesReady` only signals that `~/config/database.ts`
- * was *imported*, not that `@stacksjs/database` has actually wired up the
- * connection. Calling `db.selectFrom(...)` immediately after `overridesReady`
- * resolves can still race the connection setup. The database driver flips
- * this signal to `true` once it has a working connection.
- */
-export declare function awaitDatabaseConfig(): Promise<StacksOptions>;
-/**
- * Called by `@stacksjs/database` once the connection is live. Internal —
- * users shouldn't need to invoke this directly.
- */
-export declare function markDatabaseReady(): void;
-export declare function getConfig(): StacksOptions;
-export declare function determineAppEnv(): AppEnv;
-export declare const config: StacksOptions;
-// Per-section convenience exports.
-//
-// Caveat: these are *snapshots* taken at module-load time. ESM `export
-// const x = expr` evaluates `expr` once and binds `x` to that result —
-// there's no language-level way to make a named export re-evaluate
-// per access. So `import { ports } from '@stacksjs/config'` returns
-// whatever `config.ports` was when the config module first evaluated,
-// which is *before* `overridesReady` resolves and the user's
-// `config/*.ts` files land.
-//
-// These start as snapshots of the framework defaults (because the user's
-// `config/*.ts` haven't loaded yet — see `overridesReady`). Once the
-// async loader resolves we reassign each `let` binding so consumers of
-// `import { ports } from '@stacksjs/config'` see the merged value.
-//
-// ESM live bindings make this work: when an exporting module reassigns
-// a `let`-bound export, every importer immediately sees the new value
-// (no re-import needed). The earlier `export const x = config.x` form
-// captured the empty-default snapshot forever.
-//
-// Caveat: code that destructures (`const { ports } = config` or reads
-// at the top of a function) before `overridesReady` resolves still
-// gets the early snapshot. For correctness in that path, read off
-// the `config` proxy: `config.ports.api` always pulls live.
-export declare let ai: StacksOptions['ai'];
-export declare let analytics: StacksOptions['analytics'];
-export declare let app: StacksOptions['app'];
-export declare let auth: StacksOptions['auth'];
-export declare let realtime: StacksOptions['realtime'];
-export declare let cache: StacksOptions['cache'];
-export declare let cloud: StacksOptions['cloud'];
-export declare let cli: StacksOptions['cli'];
-export declare let dashboard: StacksOptions['dashboard'];
-export declare let database: StacksOptions['database'];
-export declare let dns: StacksOptions['dns'];
-export declare let docs: StacksOptions['docs'];
-export declare let email: StacksOptions['email'];
-export declare let errors: StacksOptions['errors'];
-export declare let featureFlags: StacksOptions['featureFlags'];
-export declare let git: StacksOptions['git'];
-export declare let hashing: StacksOptions['hashing'];
-export declare let library: StacksOptions['library'];
-export declare let logging: StacksOptions['logging'];
-export declare let notification: StacksOptions['notification'];
-export declare let payment: StacksOptions['payment'];
-export declare let ports: StacksOptions['ports'];
-export declare let queue: StacksOptions['queue'];
-export declare let security: StacksOptions['security'];
-export declare let saas: StacksOptions['saas'];
-export declare let searchEngine: StacksOptions['searchEngine'];
-export declare let server: StacksOptions['server'];
-export declare let services: StacksOptions['services'];
-export declare let filesystems: StacksOptions['filesystems'];
-export declare let team: StacksOptions['team'];
-export declare let ui: StacksOptions['ui'];
-/**
- * What `determineAppEnv` answers.
- *
- * The three canonical values, plus a passthrough for any other configured
- * environment - the function maps local/development, staging and production
- * onto them and returns anything else unchanged.
- *
- * `(string & {})` rather than a bare `string`: a bare one absorbs the literals
- * and the union collapses, so the three canonical values stop being offered as
- * completions and the type says nothing at all.
- */
-// eslint-disable-next-line ts/ban-types -- `string & {}` keeps literal completions alive
-declare type AppEnv = 'dev' | 'stage' | 'prod' | (string & {});
+export * from './runtime';
 export * from './helpers';
-export { defaults, overrides, overridesReady };

package/dist/config.js

@@ -1 +1 @@
-import{defaults}from"./defaults";import{overrides,overridesReady}from"./overrides";function isPlainObject(value){if(typeof value!=="object"||value===null||Array.isArray(value))return!1;const proto=Object.getPrototypeOf(value);return proto===Object.prototype||proto===null}function overlay(base,over){const out={...base};for(const key of Object.keys(over)){const next=over[key],prev=out[key];if(next===void 0)continue;out[key]=isPlainObject(prev)&&isPlainObject(next)?overlay(prev,next):next}return out}const mergedSections=new Map;function readMerged(prop){const o=overrides[prop],d=defaults[prop];if(!(o!==void 0&&(typeof o!=="object"||o===null||Object.keys(o).length>0)))return d;if(!isPlainObject(o)||!isPlainObject(d))return o;const cached=mergedSections.get(prop);if(cached&&cached.from===o)return cached.merged;const merged=overlay(d,o);mergedSections.set(prop,{from:o,merged});return merged}const proxyTarget=function configProxyTarget(){};export const config=new Proxy(proxyTarget,{get(_t,prop){return readMerged(prop)},set(_t,prop,value){overrides[prop]=value;return!0},deleteProperty(_t,prop){delete overrides[prop];return!0},has(_t,prop){return prop in overrides||prop in defaults},ownKeys(){return Array.from(new Set([...Object.keys(overrides),...Object.keys(defaults)]))},getOwnPropertyDescriptor(_t,prop){if(typeof prop!=="string")return;if(!(prop in overrides)&&!(prop in defaults))return;return{enumerable:!0,configurable:!0,writable:!0,value:readMerged(prop)}},isExtensible(){return!0},preventExtensions(){return!1}});export async function awaitConfig(){await overridesReady;return config}const DB_READY=Symbol.for("@stacksjs/config:databaseReady"),globalScope=globalThis;export async function awaitDatabaseConfig(){await overridesReady;const deadline=Date.now()+5000;while(!globalScope[DB_READY]&&Date.now()<deadline)await new Promise((r)=>setTimeout(r,25));if(!globalScope[DB_READY])console.warn("[config] awaitDatabaseConfig() timed out - database driver did not signal readiness within 5s");return config}export function markDatabaseReady(){globalScope[DB_READY]=!0}export function getConfig(){return config}export let{ai,analytics,app,auth,realtime,cache,cloud,cli,dashboard,database,dns,docs,email,errors,featureFlags,git,hashing,library,logging,notification,payment,ports,queue,security,saas,searchEngine,server,services,filesystems,team,ui}=config;overridesReady.then(()=>{ai=config.ai;analytics=config.analytics;app=config.app;auth=config.auth;realtime=config.realtime;cache=config.cache;cloud=config.cloud;cli=config.cli;dashboard=config.dashboard;database=config.database;dns=config.dns;docs=config.docs;email=config.email;errors=config.errors;featureFlags=config.featureFlags;git=config.git;hashing=config.hashing;library=config.library;logging=config.logging;notification=config.notification;payment=config.payment;ports=config.ports;queue=config.queue;security=config.security;saas=config.saas;searchEngine=config.searchEngine;server=config.server;services=config.services;filesystems=config.filesystems;team=config.team;ui=config.ui}).catch(()=>{});export*from"./helpers";export{defaults,overrides,overridesReady};export function determineAppEnv(){const env=config.app?.env;if(env==="local"||env==="development")return"dev";if(env==="staging")return"stage";if(env==="production")return"prod";if(!env)throw Error("Couldn't determine app environment");return env}
+export*from"./runtime";export*from"./helpers";

package/dist/features.js

@@ -1 +1 @@
-import{config}from"./config";const FEATURE_NAMES=["auth","marketing","cms","commerce","forms","dashboard","monitoring","realtime","queue"],FEATURE_DEFAULTS={dashboard:!0},overrides=new Map;function configFor(name){const raw=config[name];return raw&&typeof raw==="object"?raw:void 0}function canonicalFeatures(){return process.env.STACKS_CANONICAL_FEATURES==="1"}export function feature(name){if(overrides.has(name))return overrides.get(name);if(canonicalFeatures()&&FEATURE_NAMES.includes(name))return!0;const cfg=configFor(name);if(cfg){const enabledField=cfg.enabled;if(enabledField===!1)return!1;if(Array.isArray(cfg.env)&&cfg.env.length>0){const currentEnv=(config.app?.env??"").toString();if(!cfg.env.includes(currentEnv))return!1}if(enabledField!==void 0)return!!enabledField;return!0}return FEATURE_DEFAULTS[name]??!1}export function enableFeature(name){overrides.set(name,!0)}export function disableFeature(name){overrides.set(name,!1)}export function resetFeature(name){overrides.delete(name)}export function listFeatures(){const out={};for(const name of FEATURE_NAMES)out[name]=feature(name);for(const name of overrides.keys())out[name]=feature(name);return out}
+import{config}from"./runtime";const FEATURE_NAMES=["auth","marketing","cms","commerce","forms","dashboard","monitoring","realtime","queue"],FEATURE_DEFAULTS={dashboard:!0},overrides=new Map;function configFor(name){const raw=config[name];return raw&&typeof raw==="object"?raw:void 0}function canonicalFeatures(){return process.env.STACKS_CANONICAL_FEATURES==="1"}export function feature(name){if(overrides.has(name))return overrides.get(name);if(canonicalFeatures()&&FEATURE_NAMES.includes(name))return!0;const cfg=configFor(name);if(cfg){const enabledField=cfg.enabled;if(enabledField===!1)return!1;if(Array.isArray(cfg.env)&&cfg.env.length>0){const currentEnv=(config.app?.env??"").toString();if(!cfg.env.includes(currentEnv))return!1}if(enabledField!==void 0)return!!enabledField;return!0}return FEATURE_DEFAULTS[name]??!1}export function enableFeature(name){overrides.set(name,!0)}export function disableFeature(name){overrides.set(name,!1)}export function resetFeature(name){overrides.delete(name)}export function listFeatures(){const out={};for(const name of FEATURE_NAMES)out[name]=feature(name);for(const name of overrides.keys())out[name]=feature(name);return out}

package/dist/helpers.d.ts

@@ -1,4 +1,4 @@
-import { config } from '.';
+import { config } from './runtime';
 import type { AppConfig, AuthConfig, CacheConfig, CdnConfig, ChatConfig, CliConfig, CloudConfig, DatabaseConfig, DependenciesConfig, DnsConfig, EmailConfig, FilesystemsConfig, FeatureFlagsConfig, GitConfig, HashingConfig, ImagesConfig, LibraryConfig, NotificationConfig, PaymentConfig, QueueConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, SmsConfig, StacksConfig, StorageConfig, UiConfig } from '@stacksjs/types';
 export declare function localUrl(options?: {
   domain?: string

package/dist/helpers.js

@@ -1 +1 @@
-import{config}from".";export async function localUrl(options={}){const domain=options.domain??config.app.url??"stacks",type=options.type??"frontend",localhost=options.localhost??!1,{https,network}=options;let url=domain.replace(/\.[^.]+$/,".localhost");async function tunnel(port){const{createLocalTunnel}=await import("@stacksjs/tunnel");return createLocalTunnel(port)}switch(type){case"frontend":if(network)return await tunnel(config.ports?.frontend||3000);if(localhost)return`http://localhost:${config.ports?.frontend}`;break;case"backend":if(network)return await tunnel(config.ports?.backend||3001);if(localhost)return`http://localhost:${config.ports?.backend}`;url=`api.${url}`;break;case"admin":if(network)return await tunnel(config.ports?.admin||3002);if(localhost)return`http://localhost:${config.ports?.admin}`;url=`admin.${url}`;break;case"library":if(network)return await tunnel(config.ports?.library||3003);if(localhost)return`http://localhost:${config.ports?.library}`;url=`libs.${url}`;break;case"email":if(network)return await tunnel(config.ports?.email||3005);if(localhost)return`http://localhost:${config.ports?.email}`;url=`email.${url}`;break;case"desktop":if(network)return await tunnel(config.ports?.desktop||3004);if(localhost)return`http://localhost:${config.ports?.desktop}`;url=`desktop.${url}`;break;case"docs":if(network)return await tunnel(config.ports?.docs||3006);if(localhost)return`http://localhost:${config.ports?.docs}`;url=`docs.${url}`;break;case"inspect":if(network)return await tunnel(config.ports?.inspect||3007);if(localhost)return`http://localhost:${config.ports?.inspect}`;url=`inspect.${url}`;break;default:if(localhost)return`http://localhost:${config.ports?.frontend}`}if(https)return`https://${url}`;return`http://${url}`}export function defineStacksConfig(config){return config}export function defineApp(config){return config}export function defineAuth(config){return config}export function defineCache(config){return config}export function defineCloud(config){return config}export function defineCdn(config){return config}export function defineChat(config){return config}export function defineCli(config){return config}export function defineDatabase(config){return config}export function defineDependencies(config){return config}export function defineDns(config){return config}export function defineEmailConfig(config){return config}export function defineEmail(config){return config}export function defineGit(config){return config}export function defineHashing(config){return config}export function defineImages(config){return config}export function defineLibrary(config){return config}export function defineNotification(config){return config}export function definePayment(config){return config}export function defineQueue(config){return config}export function defineSearchEngine(config){return config}export function defineSecurity(config){return config}export function defineServices(config){return config}export function defineSms(config){return config}export function defineStorage(config){return config}export function defineFilesystems(config){return config}export function defineFeatureFlags(config){return config}export function defineUi(config){return config}export{defineEvents}from"@stacksjs/events";
+import{config}from"./runtime";export async function localUrl(options={}){const domain=options.domain??config.app.url??"stacks",type=options.type??"frontend",localhost=options.localhost??!1,{https,network}=options;let url=domain.replace(/\.[^.]+$/,".localhost");async function tunnel(port){const{createLocalTunnel}=await import("@stacksjs/tunnel");return createLocalTunnel(port)}switch(type){case"frontend":if(network)return await tunnel(config.ports?.frontend||3000);if(localhost)return`http://localhost:${config.ports?.frontend}`;break;case"backend":if(network)return await tunnel(config.ports?.backend||3001);if(localhost)return`http://localhost:${config.ports?.backend}`;url=`api.${url}`;break;case"admin":if(network)return await tunnel(config.ports?.admin||3002);if(localhost)return`http://localhost:${config.ports?.admin}`;url=`admin.${url}`;break;case"library":if(network)return await tunnel(config.ports?.library||3003);if(localhost)return`http://localhost:${config.ports?.library}`;url=`libs.${url}`;break;case"email":if(network)return await tunnel(config.ports?.email||3005);if(localhost)return`http://localhost:${config.ports?.email}`;url=`email.${url}`;break;case"desktop":if(network)return await tunnel(config.ports?.desktop||3004);if(localhost)return`http://localhost:${config.ports?.desktop}`;url=`desktop.${url}`;break;case"docs":if(network)return await tunnel(config.ports?.docs||3006);if(localhost)return`http://localhost:${config.ports?.docs}`;url=`docs.${url}`;break;case"inspect":if(network)return await tunnel(config.ports?.inspect||3007);if(localhost)return`http://localhost:${config.ports?.inspect}`;url=`inspect.${url}`;break;default:if(localhost)return`http://localhost:${config.ports?.frontend}`}if(https)return`https://${url}`;return`http://${url}`}export function defineStacksConfig(config){return config}export function defineApp(config){return config}export function defineAuth(config){return config}export function defineCache(config){return config}export function defineCloud(config){return config}export function defineCdn(config){return config}export function defineChat(config){return config}export function defineCli(config){return config}export function defineDatabase(config){return config}export function defineDependencies(config){return config}export function defineDns(config){return config}export function defineEmailConfig(config){return config}export function defineEmail(config){return config}export function defineGit(config){return config}export function defineHashing(config){return config}export function defineImages(config){return config}export function defineLibrary(config){return config}export function defineNotification(config){return config}export function definePayment(config){return config}export function defineQueue(config){return config}export function defineSearchEngine(config){return config}export function defineSecurity(config){return config}export function defineServices(config){return config}export function defineSms(config){return config}export function defineStorage(config){return config}export function defineFilesystems(config){return config}export function defineFeatureFlags(config){return config}export function defineUi(config){return config}export{defineEvents}from"@stacksjs/events";

package/dist/index.d.ts

@@ -16,10 +16,15 @@ export { packageComponentRoots, packageJobRoots, packageMigrationRoots, packageM
 export { resolveViewPatterns, type DefaultViewsSetting, type ViewPatternResolution } from './views';
 export {
   createRequestContext,
+  enterRequestScope,
   installRequestContext,
+  installRequestScope,
   parseCookieHeader,
+  scopedRequestSnapshot,
+  scopeStxServeContext,
   useRequestEvent,
   type RequestContextSnapshot,
+  type SiteSnapshot,
   type StacksRequestContext,
 } from './request-context';
 export * from './capabilities';

package/dist/index.js

@@ -1 +1 @@
-export*from"./config";export{FRAMEWORK_DEFAULTS}from"./defaults";export{validateConfig,reportConfigIssues}from"./validators";export{feature,enableFeature,disableFeature,resetFeature,listFeatures}from"./features";export{packageComponentRoots,packageJobRoots,packageMigrationRoots,packageModelRoots,packageViewRoots}from"./discovered-resources";export{resolveViewPatterns}from"./views";export{createRequestContext,installRequestContext,parseCookieHeader,useRequestEvent}from"./request-context";export*from"./capabilities";
+export*from"./config";export{FRAMEWORK_DEFAULTS}from"./defaults";export{validateConfig,reportConfigIssues}from"./validators";export{feature,enableFeature,disableFeature,resetFeature,listFeatures}from"./features";export{packageComponentRoots,packageJobRoots,packageMigrationRoots,packageModelRoots,packageViewRoots}from"./discovered-resources";export{resolveViewPatterns}from"./views";export{createRequestContext,enterRequestScope,installRequestContext,installRequestScope,parseCookieHeader,scopedRequestSnapshot,scopeStxServeContext,useRequestEvent}from"./request-context";export*from"./capabilities";

package/dist/request-context.d.ts

@@ -20,6 +20,70 @@ export declare function createRequestContext(read: () => RequestContextSnapshot
  * object by accident.
  */
 export declare function installRequestContext(read: () => RequestContextSnapshot | undefined): StacksRequestContext;
+/**
+ * Open a scope for `request` and return its snapshot, for the server to add
+ * the site or a locale to once it has resolved them.
+ *
+ * Call it FIRST in stx serve's `onRequest` hook, before the hook's first
+ * `await`. stx calls the hook from the request's own async context and awaits
+ * it before rendering, so a scope entered in the hook's synchronous prefix is
+ * the one every `<script server>` of that render runs in: the page's, the
+ * layout's and the components'. core/buddy/tests/request-context-concurrency
+ * .test.ts sends 400 storefront requests, sixteen in flight, to each view
+ * server and checks the page and the layout both read their own.
+ *
+ * Entered after an `await` in the hook, the scope reaches no script. The rest
+ * of an async function runs in a context of its own, and stx resumes in the
+ * one it called the hook from. The dev server entered its scope there, and
+ * production-server.ts said it had tried the dev server's approach before
+ * settling on globals, which is where "AsyncLocalStorage does not survive
+ * into stx-serve's render" came from. request-scope.test.ts pins both
+ * placements, and that a request that entered no scope reads none rather
+ * than a neighbour's.
+ */
+export declare function enterRequestScope(request: Request): RequestContextSnapshot;
+/**
+ * The request the caller is running inside, or undefined outside any scope.
+ *
+ * What stx published for the render wins, so `requestContext` answers what
+ * stx hands the same render as bindings (route `params`, the client `ip`, its
+ * locale, a CSRF cookie it minted). The server's own snapshot supplies the
+ * site, which stx does not carry, and stands in for everything on a stx that
+ * publishes nothing.
+ *
+ * Outside a scope there is no request, and every `requestContext` accessor
+ * answers with its empty value. Nothing here falls back to a process-wide
+ * value: that fallback is how one visitor saw another's cart.
+ */
+export declare function scopedRequestSnapshot(): RequestContextSnapshot | undefined;
+/**
+ * Keep stx's `__stxServeContext` mirror per request.
+ *
+ * stx serve assigns the request it is about to render to
+ * `globalThis.__stxServeContext` (`injectServeRequestContext` in
+ * bun-plugin-stx's serve), once per render, before the page's server
+ * scripts. As a plain global it holds whichever render assigned it last. The
+ * assignment runs inside the rendering request's async context, so this turns
+ * the global into an accessor that files the value under that request's scope
+ * and reads back the reader's own.
+ *
+ * It is what carries route `params`, the client `ip` and stx's locale into
+ * {@link scopedRequestSnapshot}: `onRequest` runs before stx matches the route,
+ * and is not handed the server stx reads the address from.
+ *
+ * An assignment made outside any scope is kept for readers outside one, as
+ * the plain global kept it. A reader inside a scope only ever gets its own.
+ */
+export declare function scopeStxServeContext(): void;
+/**
+ * What both servers install at boot: `requestContext`, reading the scope of
+ * the request each script runs in.
+ *
+ * One call rather than the pieces, so neither server can scope stx's mirror
+ * and forget the reader, or the reverse. The other half is
+ * {@link enterRequestScope}, first in each server's `onRequest`.
+ */
+export declare function installRequestScope(): StacksRequestContext;
 /**
  * The single accessor (#2232 ask 4), for callers who would rather have one
  * object than reach for ambient globals.
@@ -40,34 +104,6 @@ export declare function useRequestEvent(): {
   host: string
   site: SiteSnapshot | null
 };
-/**
- * One request object for `<script server>` blocks (stacksjs/stacks#2232).
- *
- * `requestContext` was installed twice — once by the dev views server, once by
- * the production server — with two different backings, two different sets of
- * methods, and no shared type. Both installers were `(globalThis)`, so
- * nothing could catch a divergence. Two already shipped:
- *
- *   - production's `url()` returned only the query string, so a page doing
- *     `new URL(requestContext.url())` worked in dev and threw on the box
- *   - production had no `locale()` at all, so a page that branched on locale
- *     threw "requestContext.locale is not a function" on the box
- *
- * Both were found by an end-to-end test, not by inspection, because there was
- * nothing to inspect against.
- *
- * A shared TYPE would only have made those detectable. A shared FACTORY makes
- * them impossible: each server supplies a snapshot reader and gets the same
- * object built the same way. The only thing a server still chooses is where
- * the snapshot comes from, which is the one thing that genuinely differs (dev
- * has AsyncLocalStorage available; production established it does not survive
- * into stx-serve's render).
- *
- * Home of convenience: `@stacksjs/config` is the only package both the dev
- * server (`@stacksjs/actions`) and the production server (`@stacksjs/buddy`)
- * already depend on. It is not conceptually config, and moving it later is a
- * re-export away.
- */
 /**
  * What a server knows about the request in flight.
  *
@@ -90,11 +126,13 @@ export declare interface RequestContextSnapshot {
 /**
  * The site a multi-site server resolved for this request's Host header.
  *
- * Carried on the snapshot rather than AsyncLocalStorage because ALS does not
- * survive into stx-serve's render (see the module comment): a `<script server>`
- * block that asked an ALS-backed `currentSite()` would silently get undefined.
- * The resolving server (`@stacksjs/sites` middleware / onRequest hook) stashes
- * it here; pages read `requestContext.site()`.
+ * Carried on the snapshot because `@stacksjs/sites`' own AsyncLocalStorage
+ * context does not reach the render: both servers set it (`setCurrentSite`)
+ * after the first `await` of their `onRequest` hook, and a scope entered there
+ * ends with the hook (see {@link enterRequestScope}). A `<script server>`
+ * block that asked `currentSite()` would get undefined. The resolving server
+ * stores it on the snapshot {@link enterRequestScope} returned; pages read
+ * `requestContext.site()`.
  */
 export declare interface SiteSnapshot {
   id: number

package/dist/request-context.js

@@ -1 +1 @@
-export function parseCookieHeader(header){const out={};if(!header)return out;for(const part of header.split(";")){const trimmed=part.trim(),eq=trimmed.indexOf("=");if(eq===-1)continue;const key=trimmed.slice(0,eq).trim();if(!key)continue;const value=trimmed.slice(eq+1).trim();try{out[key]=decodeURIComponent(value)}catch{out[key]=value}}return out}export function createRequestContext(read){const snapshot=()=>read()??{},searchOf=()=>{const direct=snapshot().search;if(direct)return direct;const url=snapshot().url??"",mark=url.indexOf("?");return mark===-1?"":url.slice(mark)};return{cookie:(name)=>snapshot().cookies?.[name]??null,cookies:()=>snapshot().cookies??{},url:()=>snapshot().url??"",path:()=>{const direct=snapshot().path;if(direct)return direct;const url=snapshot().url??"";if(!url)return"";try{return new URL(url).pathname}catch{const mark=url.indexOf("?");return mark===-1?url:url.slice(0,mark)}},search:searchOf,query:()=>{const out={},search=searchOf();if(!search)return out;new URLSearchParams(search.startsWith("?")?search.slice(1):search).forEach((value,key)=>{out[key]=value});return out},params:()=>snapshot().params??{},locale:()=>snapshot().locale??"en",ip:()=>snapshot().ip??"",host:()=>snapshot().host??"",site:()=>snapshot().site??null}}export function installRequestContext(read){const context=createRequestContext(read);globalThis.requestContext=context;return context}export function useRequestEvent(){const context=globalThis.requestContext??createRequestContext(()=>{return});return{url:context.url(),path:context.path(),search:context.search(),query:context.query(),cookies:context.cookies(),params:context.params(),locale:context.locale(),ip:context.ip(),host:context.host(),site:context.site()}}
+import{AsyncLocalStorage}from"node:async_hooks";export function parseCookieHeader(header){const out={};if(!header)return out;for(const part of header.split(";")){const trimmed=part.trim(),eq=trimmed.indexOf("=");if(eq===-1)continue;const key=trimmed.slice(0,eq).trim();if(!key)continue;const value=trimmed.slice(eq+1).trim();try{out[key]=decodeURIComponent(value)}catch{out[key]=value}}return out}export function createRequestContext(read){const snapshot=()=>read()??{},searchOf=()=>{const direct=snapshot().search;if(direct)return direct;const url=snapshot().url??"",mark=url.indexOf("?");return mark===-1?"":url.slice(mark)};return{cookie:(name)=>snapshot().cookies?.[name]??null,cookies:()=>snapshot().cookies??{},url:()=>snapshot().url??"",path:()=>{const direct=snapshot().path;if(direct)return direct;const url=snapshot().url??"";if(!url)return"";try{return new URL(url).pathname}catch{const mark=url.indexOf("?");return mark===-1?url:url.slice(0,mark)}},search:searchOf,query:()=>{const out={},search=searchOf();if(!search)return out;new URLSearchParams(search.startsWith("?")?search.slice(1):search).forEach((value,key)=>{out[key]=value});return out},params:()=>snapshot().params??{},locale:()=>snapshot().locale??"en",ip:()=>snapshot().ip??"",host:()=>snapshot().host??"",site:()=>snapshot().site??null}}export function installRequestContext(read){const context=createRequestContext(read);globalThis.requestContext=context;return context}const SCOPE_STORAGE_KEY=Symbol.for("stacks.config.requestScope"),scopeStorage=globalThis[SCOPE_STORAGE_KEY]??=new AsyncLocalStorage;export function enterRequestScope(request){const url=new URL(request.url),own={cookies:parseCookieHeader(request.headers.get("cookie")),url:request.url,path:url.pathname,search:url.search,host:request.headers.get("host")??url.host,site:null};scopeStorage.enterWith({own});return own}export function scopedRequestSnapshot(){const scope=scopeStorage.getStore();if(!scope)return;const{own,published}=scope;if(!published)return own;return{...own,...published,site:own.site??published.site??null}}const STX_SERVE_CONTEXT="__stxServeContext";export function scopeStxServeContext(){const existing=Object.getOwnPropertyDescriptor(globalThis,STX_SERVE_CONTEXT);if(existing?.get)return;let unscoped=existing?.value;Object.defineProperty(globalThis,STX_SERVE_CONTEXT,{configurable:!0,enumerable:!1,get:()=>{const scope=scopeStorage.getStore();return scope?scope.published:unscoped},set:(value)=>{const scope=scopeStorage.getStore();if(scope)scope.published=value;else unscoped=value}})}export function installRequestScope(){scopeStxServeContext();return installRequestContext(scopedRequestSnapshot)}export function useRequestEvent(){const context=globalThis.requestContext??createRequestContext(()=>{return});return{url:context.url(),path:context.path(),search:context.search(),query:context.query(),cookies:context.cookies(),params:context.params(),locale:context.locale(),ip:context.ip(),host:context.host(),site:context.site()}}

package/dist/runtime.d.ts

@@ -0,0 +1,114 @@
+import { defaults } from './defaults';
+import { overrides, overridesReady } from './overrides';
+import type { StacksOptions } from '@stacksjs/types';
+/*.ts` file has loaded and the
+ * `overrides` instance has been mutated in place. Use this in code paths
+ * that *must* see the merged values — typically anything outside the
+ * normal request flow (e.g. CLI commands, top-level boot scripts) where
+ * the request hasn't yet hit a route handler that already awaited.
+ *
+ * Inside request handlers / routes you generally do *not* need to await
+ * this: the router's `serverResponse()` only fires after `importRoutes()`
+ * resolves, and `importRoutes()` indirectly awaits config (it reads
+ * `app/Routes.ts`, which imports config). So the proxy returns merged
+ * values for all "normal" request-time reads.
+ *
+ * @example
+ * ```ts
+ * import { config, awaitConfig } from '@stacksjs/config'
+ *
+ * // CLI / top-level script — config files may not be loaded yet
+ * await awaitConfig()
+ * console.log(config.ports.api) // guaranteed to be the user value
+ * ```
+ */
+export declare function awaitConfig(): Promise<StacksOptions>;
+/**
+ * Resolves once `database` config has been read by `@stacksjs/database`'s
+ * lazy initializer. Use it from boot scripts that need a live `db` handle
+ * before the request loop starts.
+ *
+ * Why a separate signal: `overridesReady` only signals that `~/config/database.ts`
+ * was *imported*, not that `@stacksjs/database` has actually wired up the
+ * connection. Calling `db.selectFrom(...)` immediately after `overridesReady`
+ * resolves can still race the connection setup. The database driver flips
+ * this signal to `true` once it has a working connection.
+ */
+export declare function awaitDatabaseConfig(): Promise<StacksOptions>;
+/**
+ * Called by `@stacksjs/database` once the connection is live. Internal —
+ * users shouldn't need to invoke this directly.
+ */
+export declare function markDatabaseReady(): void;
+export declare function getConfig(): StacksOptions;
+export declare function determineAppEnv(): AppEnv;
+export declare const config: StacksOptions;
+// Per-section convenience exports.
+//
+// Caveat: these are *snapshots* taken at module-load time. ESM `export
+// const x = expr` evaluates `expr` once and binds `x` to that result —
+// there's no language-level way to make a named export re-evaluate
+// per access. So `import { ports } from '@stacksjs/config'` returns
+// whatever `config.ports` was when the config module first evaluated,
+// which is *before* `overridesReady` resolves and the user's
+// `config/*.ts` files land.
+//
+// These start as snapshots of the framework defaults (because the user's
+// `config/*.ts` haven't loaded yet — see `overridesReady`). Once the
+// async loader resolves we reassign each `let` binding so consumers of
+// `import { ports } from '@stacksjs/config'` see the merged value.
+//
+// ESM live bindings make this work: when an exporting module reassigns
+// a `let`-bound export, every importer immediately sees the new value
+// (no re-import needed). The earlier `export const x = config.x` form
+// captured the empty-default snapshot forever.
+//
+// Caveat: code that destructures (`const { ports } = config` or reads
+// at the top of a function) before `overridesReady` resolves still
+// gets the early snapshot. For correctness in that path, read off
+// the `config` proxy: `config.ports.api` always pulls live.
+export declare let ai: StacksOptions['ai'];
+export declare let analytics: StacksOptions['analytics'];
+export declare let app: StacksOptions['app'];
+export declare let auth: StacksOptions['auth'];
+export declare let realtime: StacksOptions['realtime'];
+export declare let cache: StacksOptions['cache'];
+export declare let cloud: StacksOptions['cloud'];
+export declare let cli: StacksOptions['cli'];
+export declare let dashboard: StacksOptions['dashboard'];
+export declare let database: StacksOptions['database'];
+export declare let dns: StacksOptions['dns'];
+export declare let docs: StacksOptions['docs'];
+export declare let email: StacksOptions['email'];
+export declare let errors: StacksOptions['errors'];
+export declare let featureFlags: StacksOptions['featureFlags'];
+export declare let git: StacksOptions['git'];
+export declare let hashing: StacksOptions['hashing'];
+export declare let library: StacksOptions['library'];
+export declare let logging: StacksOptions['logging'];
+export declare let notification: StacksOptions['notification'];
+export declare let payment: StacksOptions['payment'];
+export declare let ports: StacksOptions['ports'];
+export declare let queue: StacksOptions['queue'];
+export declare let security: StacksOptions['security'];
+export declare let saas: StacksOptions['saas'];
+export declare let searchEngine: StacksOptions['searchEngine'];
+export declare let server: StacksOptions['server'];
+export declare let services: StacksOptions['services'];
+export declare let filesystems: StacksOptions['filesystems'];
+export declare let team: StacksOptions['team'];
+export declare let ui: StacksOptions['ui'];
+/**
+ * What `determineAppEnv` answers.
+ *
+ * The three canonical values, plus a passthrough for any other configured
+ * environment - the function maps local/development, staging and production
+ * onto them and returns anything else unchanged.
+ *
+ * `(string & {})` rather than a bare `string`: a bare one absorbs the literals
+ * and the union collapses, so the three canonical values stop being offered as
+ * completions and the type says nothing at all.
+ */
+// eslint-disable-next-line ts/ban-types -- `string & {}` keeps literal completions alive
+declare type AppEnv = 'dev' | 'stage' | 'prod' | (string & {});
+export { defaults, overrides, overridesReady };

package/dist/runtime.js

@@ -0,0 +1 @@
+import{defaults}from"./defaults";import{overrides,overridesReady}from"./overrides";function isPlainObject(value){if(typeof value!=="object"||value===null||Array.isArray(value))return!1;const proto=Object.getPrototypeOf(value);return proto===Object.prototype||proto===null}function overlay(base,over){const out={...base};for(const key of Object.keys(over)){const next=over[key],prev=out[key];if(next===void 0)continue;out[key]=isPlainObject(prev)&&isPlainObject(next)?overlay(prev,next):next}return out}const mergedSections=new Map;function readMerged(prop){const o=overrides[prop],d=defaults[prop];if(!(o!==void 0&&(typeof o!=="object"||o===null||Object.keys(o).length>0)))return d;if(!isPlainObject(o)||!isPlainObject(d))return o;const cached=mergedSections.get(prop);if(cached&&cached.from===o)return cached.merged;const merged=overlay(d,o);mergedSections.set(prop,{from:o,merged});return merged}const proxyTarget=function configProxyTarget(){};export const config=new Proxy(proxyTarget,{get(_t,prop){return readMerged(prop)},set(_t,prop,value){overrides[prop]=value;return!0},deleteProperty(_t,prop){delete overrides[prop];return!0},has(_t,prop){return prop in overrides||prop in defaults},ownKeys(){return Array.from(new Set([...Object.keys(overrides),...Object.keys(defaults)]))},getOwnPropertyDescriptor(_t,prop){if(typeof prop!=="string")return;if(!(prop in overrides)&&!(prop in defaults))return;return{enumerable:!0,configurable:!0,writable:!0,value:readMerged(prop)}},isExtensible(){return!0},preventExtensions(){return!1}});export async function awaitConfig(){await overridesReady;return config}const DB_READY=Symbol.for("@stacksjs/config:databaseReady"),globalScope=globalThis;export async function awaitDatabaseConfig(){await overridesReady;const deadline=Date.now()+5000;while(!globalScope[DB_READY]&&Date.now()<deadline)await new Promise((r)=>setTimeout(r,25));if(!globalScope[DB_READY])console.warn("[config] awaitDatabaseConfig() timed out - database driver did not signal readiness within 5s");return config}export function markDatabaseReady(){globalScope[DB_READY]=!0}export function getConfig(){return config}export let{ai,analytics,app,auth,realtime,cache,cloud,cli,dashboard,database,dns,docs,email,errors,featureFlags,git,hashing,library,logging,notification,payment,ports,queue,security,saas,searchEngine,server,services,filesystems,team,ui}=config;overridesReady.then(()=>{ai=config.ai;analytics=config.analytics;app=config.app;auth=config.auth;realtime=config.realtime;cache=config.cache;cloud=config.cloud;cli=config.cli;dashboard=config.dashboard;database=config.database;dns=config.dns;docs=config.docs;email=config.email;errors=config.errors;featureFlags=config.featureFlags;git=config.git;hashing=config.hashing;library=config.library;logging=config.logging;notification=config.notification;payment=config.payment;ports=config.ports;queue=config.queue;security=config.security;saas=config.saas;searchEngine=config.searchEngine;server=config.server;services=config.services;filesystems=config.filesystems;team=config.team;ui=config.ui}).catch(()=>{});export{defaults,overrides,overridesReady};export function determineAppEnv(){const env=config.app?.env;if(env==="local"||env==="development")return"dev";if(env==="staging")return"stage";if(env==="production")return"prod";if(!env)throw Error("Couldn't determine app environment");return env}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/config",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.50",
+  "version": "0.74.52",
   "description": "The Stacks config helper methods.",
   "author": "Chris Breuer",
   "contributors": [
@@ -55,14 +55,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/events": "0.74.50",
-    "@stacksjs/path": "0.74.50",
-    "@stacksjs/tunnel": "0.74.50",
+    "@stacksjs/events": "0.74.52",
+    "@stacksjs/path": "0.74.52",
+    "@stacksjs/tunnel": "0.74.52",
     "ts-pantry": "^0.11.35"
   },
   "devDependencies": {
-    "@stacksjs/alias": "0.74.50",
-    "@stacksjs/types": "0.74.50",
+    "@stacksjs/alias": "0.74.52",
+    "@stacksjs/types": "0.74.52",
     "better-dx": "^0.2.24"
   }
 }