@stacksjs/config 0.70.88 → 0.70.91

package/dist/config.d.ts

@@ -0,0 +1,102 @@
+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 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/config.js

@@ -0,0 +1,109 @@
+import { defaults } from "./defaults";
+import { overrides, overridesReady } from "./overrides";
+function readMerged(prop) {
+  const o = overrides[prop];
+  if (o !== void 0 && (typeof o !== "object" || Object.keys(o).length > 0))
+    return o;
+  return defaults[prop];
+}
+const proxyTarget = function configProxyTarget() {};
+export const config = new Proxy(proxyTarget, {
+  get(_t, prop) {
+    return readMerged(prop);
+  },
+  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 \u2014 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, 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;
+  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;
+}

package/dist/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;