@stacksjs/config 0.70.23 → 0.70.25

package/dist/src/config.d.ts

@@ -0,0 +1,101 @@
+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 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 services: StacksOptions['services'];
+export declare let filesystems: StacksOptions['filesystems'];
+export declare let team: StacksOptions['team'];
+export declare let ui: StacksOptions['ui'];
+declare type AppEnv = 'dev' | 'stage' | 'prod' | string;
+export * from './helpers';
+export { defaults, overrides, overridesReady };

package/dist/src/defaults.d.ts

@@ -0,0 +1,20 @@
+import type { StacksOptions } from '@stacksjs/types';
+/**
+ * Framework-wide default scalars. Defining these as named constants
+ * (rather than re-spelling the literal in each config section) keeps
+ * "where do I change the default region?" answerable from a single
+ * line — the previous shape had `'us-east-1'` typed in 4+ places that
+ * could drift when a multi-region future lands.
+ */
+export declare const FRAMEWORK_DEFAULTS: {
+  /** Default AWS region for SES, S3, DynamoDB, CloudFront origin shield. */
+  awsRegion: 'us-east-1';
+  /** Default scheduler / job timezone. UTC keeps cron predictable across hosts. */
+  timezone: 'UTC';
+  /** No-reply address for transactional email (override via config.email.from). */
+  noReplyEmail: 'no-reply@stacksjs.com';
+  /** Default project domain shape for new scaffolds. */
+  fallbackDomain: 'stacks.localhost'
+};
+export declare const defaults: StacksOptions;
+export default defaults;

package/dist/src/features.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Truthy when the named feature is enabled in the current environment.
+ *
+ * Resolution order (first match wins):
+ *   1. Runtime override via `enableFeature` / `disableFeature`
+ *   2. Object form `{ enabled: true, env: ['production'] }` — env list
+ *      gates the flag to specific deploy targets (matched against
+ *      `config.app.env`)
+ *   3. Boolean form `true` / `false`
+ *   4. Missing → `false`
+ *
+ * @example
+ * ```ts
+ * if (feature('experimental-streaming')) {
+ *   return response.stream(producer)
+ * }
+ * ```
+ */
+export declare function feature(name: string): boolean;
+/**
+ * Force-enable a feature in the running process. Intended for tests and
+ * staged rollouts; production code should prefer config-file overrides.
+ */
+export declare function enableFeature(name: string): void;
+/**
+ * Force-disable a feature in the running process.
+ */
+export declare function disableFeature(name: string): void;
+/**
+ * Drop a runtime override and fall back to the config-driven value.
+ */
+export declare function resetFeature(name: string): void;
+/**
+ * Snapshot of the live flag set — useful for `/__features` debug
+ * endpoints and CLI commands that print the active configuration.
+ */
+export declare function listFeatures(): Record<string, boolean>;
+declare type FlagValue = boolean | { enabled?: boolean, env?: string[] }

package/dist/src/helpers.d.ts

@@ -0,0 +1,44 @@
+import { config } from '.';
+import type { AppConfig, CacheConfig, CdnConfig, ChatConfig, CliConfig, DatabaseConfig, DependenciesConfig, DnsConfig, EmailConfig, Events, FilesystemsConfig, GitConfig, HashingConfig, LibraryConfig, Model, NotificationConfig, PaymentConfig, QueueConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, StacksConfig, StorageConfig, UiConfig } from '@stacksjs/types';
+export declare function localUrl(options?: {
+  domain?: string
+  type?: LocalUrlType
+  network?: boolean
+  localhost?: boolean
+  https?: boolean
+}): Promise<string>;
+export declare function defineStacksConfig(config: StacksConfig): StacksConfig;
+export declare function defineApp(config: AppConfig): AppConfig;
+export declare function defineCache(config: CacheConfig): CacheConfig;
+export declare function defineCdn(config: CdnConfig): CdnConfig;
+export declare function defineChat(config: ChatConfig): ChatConfig;
+export declare function defineCli(config: CliConfig): CliConfig;
+export declare function defineDatabase(config: DatabaseConfig): DatabaseConfig;
+export declare function defineDependencies(config: DependenciesConfig): DependenciesConfig;
+export declare function defineDns(config: DnsConfig): DnsConfig;
+export declare function defineEmailConfig(config: EmailConfig): EmailConfig;
+export declare function defineEmail(config: EmailConfig): EmailConfig;
+export declare function defineGit(config: GitConfig): GitConfig;
+export declare function defineHashing(config: HashingConfig): HashingConfig;
+export declare function defineLibrary(config: LibraryConfig): LibraryConfig;
+export declare function defineNotification(config: NotificationConfig): NotificationConfig;
+export declare function definePayment(config: PaymentConfig): PaymentConfig;
+export declare function defineQueue(config: QueueConfig): QueueConfig;
+export declare function defineSearchEngine(config: SearchEngineConfig): SearchEngineConfig;
+export declare function defineSecurity(config: SecurityConfig): SecurityConfig;
+export declare function defineServices(config: ServicesConfig): ServicesConfig;
+export declare function defineSms(config: any): any;
+export declare function defineStorage(config: StorageConfig): StorageConfig;
+export declare function defineFilesystems(config: FilesystemsConfig): FilesystemsConfig;
+export declare function defineUi(config: UiConfig): UiConfig;
+export declare function defineModel(config: Model): Model;
+export declare function defineEvents(config: Events): Events;
+export type LocalUrlType = | 'frontend'
+  | 'backend'
+  | 'api'
+  | 'admin'
+  | 'library'
+  | 'email'
+  | 'docs'
+  | 'inspect'
+  | 'desktop';

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+// IMPORTANT: do NOT re-add `export * as config from './config'` here.
+// That line creates a module-namespace object named `config` whose
+// properties are non-configurable per the ESM spec (namespaces are sealed).
+// Because `export *` is also exporting the real `config` proxy from
+// `./config`, the namespace object would shadow the proxy under the
+// `config` name — and consumers that did `import { config }` would get
+// the sealed namespace, not the live proxy. The visible symptom: every
+// `config.X` read returns whatever value the proxy's get trap produced
+// the *first* time (typically defaults), and later mutations from
+// `overridesReady` are silently ignored.
+export * from './config';
+export { FRAMEWORK_DEFAULTS } from './defaults';
+export { validateConfig, reportConfigIssues, type ConfigValidationIssue } from './validators';
+export { feature, enableFeature, disableFeature, resetFeature, listFeatures } from './features';

package/dist/src/validators.d.ts

@@ -0,0 +1,19 @@
+import type { StacksConfig } from '@stacksjs/types';
+/**
+ * Validate a config snapshot. Returns the list of issues — caller decides
+ * whether to throw, log, or just print a summary. Returns an empty array
+ * when everything checks out.
+ */
+export declare function validateConfig(config: Partial<StacksConfig>): ConfigValidationIssue[];
+/**
+ * Convenience: validate and pretty-print to stderr. Returns true when
+ * the config is clean. Used by the boot path so users see issues
+ * immediately on startup rather than digging into a stack trace later.
+ */
+export declare function reportConfigIssues(config: Partial<StacksConfig>): boolean;
+export declare interface ConfigValidationIssue {
+  path: string
+  message: string
+}
+// eslint-disable-next-line pickier/no-unused-vars
+declare type Check = (value: unknown, path: string) => ConfigValidationIssue[];

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/config",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.25",
   "description": "The Stacks config helper methods.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/config#readme",
@@ -16,24 +18,38 @@
   "bugs": {
     "url": "https://github.com/stacksjs/stacks/issues"
   },
-  "keywords": ["config", "utilities", "functions", "stacks"],
+  "keywords": [
+    "config",
+    "utilities",
+    "functions",
+    "stacks"
+  ],
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./*": {
       "bun": "./*"
     }
   },
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "ts-pantry": "^0.8.16"
+  },
   "devDependencies": {
-    "@stacksjs/alias": "0.70.22",
-    "@stacksjs/development": "0.70.22",
-    "@stacksjs/types": "0.70.22"
+    "@stacksjs/alias": "0.70.23",
+    "better-dx": "^0.2.12",
+    "@stacksjs/types": "0.70.23",
+    "bunfig": "^0.15.11"
   }
 }

package/dist/config.d.ts

@@ -1,26 +0,0 @@
-import type { StacksOptions } from '@stacksjs/types';
-import { defaults } from './defaults';
-import { overrides } from './overrides';
-
-export declare const config: StacksOptions;
-export declare function getConfig(): StacksOptions;
-export declare const ai: StacksOptions['ai'];
-export declare const app: StacksOptions['app'];
-export declare const cloud: StacksOptions['cloud'];
-export declare const database: StacksOptions['database'];
-export declare const docs: StacksOptions['docs'];
-export declare const errors: StacksOptions['errors'];
-export declare const hashing: StacksOptions['hashing'];
-export declare const logging: StacksOptions['logging'];
-export declare const payment: StacksOptions['payment'];
-export declare const queue: StacksOptions['queue'];
-export declare const saas: StacksOptions['saas'];
-export declare const services: StacksOptions['services'];
-export declare const team: StacksOptions['team'];
-export declare function determineAppEnv(): AppEnv;
-
-export { defaults, overrides }
-
-export * from './helpers'
-
-type AppEnv = 'dev' | 'stage' | 'prod' | string

package/dist/defaults.d.ts

@@ -1,5 +0,0 @@
-import type { StacksOptions } from '@stacksjs/types';
-
-export declare const defaults: StacksOptions;
-
-export default defaults;

package/dist/helpers.d.ts

@@ -1,116 +0,0 @@
-export declare type LocalUrlType =
-  | 'frontend'
-  | 'backend'
-  | 'api'
-  | 'admin'
-  | 'library'
-  | 'email'
-  | 'docs'
-  | 'inspect'
-  | 'desktop'
-
-export async function localUrl({
-  domain = config.app.url || 'stacks',
-  type = 'frontend' as LocalUrlType,
-  localhost = false,
-  https = undefined as boolean | undefined,
-  network = undefined as boolean | undefined,
-}: {
-  domain?: string
-  type?: LocalUrlType
-  network?: boolean
-  localhost?: boolean
-  https?: boolean
-} = {}): Promise<string> {
-  let url = domain.replace(/\.[^.]+$/, '.localhost')
-
-  switch (type) {
-    case 'frontend':
-      if (network)
-        return await createLocalTunnel(config.ports?.frontend || 3000)
-      if (localhost)
-        return `http:
-      break
-    case 'backend':
-      if (network)
-        return await createLocalTunnel(config.ports?.backend || 3001)
-      if (localhost)
-        return `http:
-      url = `api.${url}`
-      break
-    case 'admin':
-      if (network)
-        return await createLocalTunnel(config.ports?.admin || 3002)
-      if (localhost)
-        return `http:
-      url = `admin.${url}`
-      break
-    case 'library':
-      if (network)
-        return await createLocalTunnel(config.ports?.library || 3003)
-      if (localhost)
-        return `http:
-      url = `libs.${url}`
-      break
-    case 'email':
-      if (network)
-        return await createLocalTunnel(config.ports?.email || 3005)
-      if (localhost)
-        return `http:
-      url = `email.${url}`
-      break
-    case 'desktop':
-      if (network)
-        return await createLocalTunnel(config.ports?.desktop || 3004)
-      if (localhost)
-        return `http:
-      url = `desktop.${url}`
-      break
-    case 'docs':
-      if (network)
-        return await createLocalTunnel(config.ports?.docs || 3006)
-      if (localhost)
-        return `http:
-      url = `docs.${url}`
-      break
-    case 'inspect':
-      if (network)
-        return await createLocalTunnel(config.ports?.inspect || 3007)
-      if (localhost)
-        return `http:
-      url = `inspect.${url}`
-      break
-    default:
-      if (localhost)
-        return `http:
-  }
-
-  if (https)
-    return `https:
-  return `http:
-}
-export declare function defineStacksConfig(config: StacksConfig): StacksConfig;
-export declare function defineApp(config: AppConfig): AppConfig;
-export declare function defineCache(config: CacheConfig): CacheConfig;
-export declare function defineCdn(config: CdnConfig): CdnConfig;
-export declare function defineChat(config: ChatConfig): ChatConfig;
-export declare function defineCli(config: CliConfig): CliConfig;
-export declare function defineDatabase(config: DatabaseConfig): DatabaseConfig;
-export declare function defineDependencies(config: DependenciesConfig): DependenciesConfig;
-export declare function defineDns(config: DnsConfig): DnsConfig;
-export declare function defineEmailConfig(config: EmailConfig): EmailConfig;
-export declare function defineEmail(config: EmailConfig): EmailConfig;
-export declare function defineGit(config: GitConfig): GitConfig;
-export declare function defineHashing(config: HashingConfig): HashingConfig;
-export declare function defineLibrary(config: LibraryConfig): LibraryConfig;
-export declare function defineNotification(config: NotificationConfig): NotificationConfig;
-export declare function definePayment(config: PaymentConfig): PaymentConfig;
-export declare function defineQueue(config: QueueConfig): QueueConfig;
-export declare function defineSearchEngine(config: SearchEngineConfig): SearchEngineConfig;
-export declare function defineSecurity(config: SecurityConfig): SecurityConfig;
-export declare function defineServices(config: ServicesConfig): ServicesConfig;
-export declare function defineSms(config: any): any;
-export declare function defineStorage(config: StorageConfig): StorageConfig;
-export declare function defineUi(config: UiConfig): UiConfig;
-export declare function defineModel(config: Model): Model;
-export declare function defineEvents(config: Events): Events;

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export * as config from './config'
-export * from './config'

package/dist/overrides.d.ts

@@ -1,5 +0,0 @@
-import type { StacksConfig } from '@stacksjs/types';
-
-export declare const overrides: StacksConfig;
-
-export default overrides;