@arkstack/common 0.14.18 → 0.14.20

package/dist/faker.d.ts

@@ -0,0 +1,9 @@
+import { Faker, ImageModule } from "@faker-js/faker";
+import { PictwoFakerImage } from "@pictwo/faker";
+
+//#region src/faker.d.ts
+declare const faker: Faker & {
+  image: ImageModule & PictwoFakerImage;
+};
+//#endregion
+export { faker };

package/dist/faker.js

@@ -0,0 +1,20 @@
+import { v as configLoader } from "./system-DUaI4u99.js";
+import * as fakerLocales from "@faker-js/faker";
+import { Faker } from "@faker-js/faker";
+import { pictwoImage } from "@pictwo/faker";
+//#region src/faker.ts
+const config = globalThis.config ?? ((key, def) => configLoader.resolve(key, def));
+const fallbackLocale = "en";
+const resolveLocale = () => {
+	const locale = config("app.locale", fallbackLocale);
+	if (typeof locale === "string" && locale in fakerLocales && typeof fakerLocales[locale] === "object") return fakerLocales[locale];
+	return fakerLocales[fallbackLocale];
+};
+const fakerInstance = new Faker({ locale: [resolveLocale()].filter(Boolean) });
+const { faker: _, ...image } = fakerInstance.image;
+const faker = {
+	...fakerInstance,
+	image: Object.assign({}, image, pictwoImage())
+};
+//#endregion
+export { faker };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /// <reference path="./app.d.ts" />
-import { a as abortIf, c as initializeGlobalContext, d as Hash, f as Encryption, i as abort, l as isClass, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as perPage } from "./helpers-CfQxt_q2.js";
+import { a as abortIf, c as initializeGlobalContext, d as Hash, f as Encryption, i as abort, l as isClass, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as perPage } from "./helpers-BrQ0B-EX.js";
 import { JitiOptions, JitiResolveOptions } from "jiti";
 import { Arkstack } from "@arkstack/contract";
 import pino from "pino";
@@ -170,9 +170,105 @@ declare class Logger {
   static console(): typeof Console;
 }
 //#endregion
+//#region src/locales.d.ts
+declare const locales: readonly ["af_ZA", "ar", "az", "bn_BD", "cs_CZ", "cy", "da", "de", "de_AT", "de_CH", "dv", "el", "en", "en_AU", "en_AU_ocker", "en_BORK", "en_CA", "en_GB", "en_GH", "en_HK", "en_IE", "en_IN", "en_NG", "en_US", "en_ZA", "eo", "es", "es_MX", "fa", "fi", "fr", "fr_BE", "fr_CA", "fr_CH", "fr_LU", "fr_SN", "he", "hr", "hu", "hy", "id_ID", "it", "ja", "ka_GE", "ko", "ku_ckb", "ku_kmr_latin", "lv", "mk", "mn_MN_cyrl", "nb_NO", "ne", "nl", "nl_BE", "pl", "pt_BR", "pt_PT", "ro", "ro_MD", "ru", "sk", "sl_SI", "sr_RS_latin", "sv", "ta_IN", "th", "tr", "uk", "ur", "uz_UZ_latin", "vi", "yo_NG", "zh_CN", "zh_TW", "zu_ZA"];
+//#endregion
 //#region src/types.d.ts
 interface ConfigRegistry {}
-interface EnvRegistry {}
+/**
+ * Map of known environment variables to their (coerced) value types.
+ *
+ * Used to give {@link GlobalEnv | env()} precise return types. Unknown keys fall
+ * back to `string`. Augment this interface (declaration merging) to register
+ * application-specific variables:
+ *
+ * ```ts
+ * declare module '@arkstack/common' {
+ *   interface EnvRegistry { MY_FLAG: boolean }
+ * }
+ * ```
+ */
+interface EnvRegistry {
+  APP_NAME: string;
+  APP_ENV: 'development' | 'production' | 'staging' | 'local';
+  APP_KEY: string;
+  APP_URL: string;
+  APP_HOST: string;
+  APP_PORT: number;
+  APP_DEBUG: boolean;
+  APP_TIMEZONE: string;
+  APP_LOCALE: typeof locales[number];
+  APP_FALLBACK_LOCALE: typeof locales[number];
+  APP_FAKER_LOCALE: typeof locales[number];
+  NODE_ENV: 'development' | 'production' | 'test';
+  PORT: number;
+  HOST: string;
+  FRONTEND_URL: string;
+  OUTPUT_DIR: string;
+  OUTPUT_DIR_DEV: string;
+  CONFIG_PATH: string;
+  TUNNEL: boolean;
+  NGROK_AUTHTOKEN: string;
+  NGROK_DOMAIN: string;
+  FILESYSTEM_DISK: string;
+  CACHE_STORE: string;
+  CACHE_PREFIX: string;
+  CACHE_TABLE: string;
+  QUEUE_CONNECTION: string;
+  QUEUE_TABLE: string;
+  QUEUE_NAME: string;
+  QUEUE_RETRY_AFTER: number;
+  REDIS_HOST: string;
+  REDIS_PORT: number;
+  REDIS_PASSWORD: string;
+  REDIS_CACHE_DB: number;
+  REDIS_QUEUE_DB: number;
+  JWT_EXPIRES_IN: string;
+  SESSION_LIFETIME: number;
+  TWO_FACTOR_SMS_TTL_MINUTES: number;
+  DATABASE_URL: string;
+  DB_CONNECTION: string;
+  DB_HOST: string;
+  DB_PORT: number;
+  DB_DATABASE: string;
+  DB_USERNAME: string;
+  DB_PASSWORD: string;
+  MAIL_HOST: string;
+  MAIL_PORT: number;
+  MAIL_SECURE: boolean;
+  MAIL_USERNAME: string;
+  MAIL_PASSWORD: string;
+  MAIL_FROM_ADDRESS: string;
+  MAIL_TEST_ADDRESS: string;
+  AWS_ACCESS_KEY_ID: string;
+  AWS_SECRET_ACCESS_KEY: string;
+  AWS_DEFAULT_REGION: string;
+  AWS_BUCKET: string;
+  AWS_URL: string;
+  AWS_ENDPOINT: string;
+}
+/**
+ * App Confifuration
+ */
+interface AppConfig {
+  env: string;
+  key: string;
+  url: string;
+  host: string;
+  name: string;
+  frontend_url: string;
+  debug: boolean;
+  timezone: string;
+  locale: typeof locales[number];
+  fallback_locale: typeof locales[number];
+  faker_locale: typeof locales[number];
+}
+/**
+ * Known environment variable names.
+ */
+type EnvKey = keyof EnvRegistry & string;
+/** The registered type for a known key, or `string` for an unknown one. */
+type EnvLookup<K extends string> = [K] extends [EnvKey] ? EnvRegistry[K] : string;
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
 type MergedConfig<X> = UnionToIntersection<X>;
 type Primitive = string | number | boolean | null | undefined | Function;
@@ -196,8 +292,17 @@ interface LoggerLog {
   <L extends boolean>(config: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string;
   <L extends boolean>(config?: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string | Logger;
 }
+/**
+ * Return type of {@link GlobalEnv | env()}.
+ *
+ * When an explicit value type `X` is given it wins (backward compatible with
+ * `env<boolean>('FLAG')`). Otherwise the type registered for the key `K` is used
+ * — falling back to `string` for unknown keys. A provided default `D` is unioned
+ * into the result.
+ */
+type EnvReturn<X, K extends string, D> = [X] extends [never] ? [D] extends [undefined] ? EnvLookup<K> : EnvLookup<K> | D : [D] extends [undefined] ? X : X | D;
 interface GlobalEnv {
-  <X = string, Y = undefined | X>(env: string, defaultValue?: Y): Y extends undefined ? X : Y;
+  <X = never, D = undefined, K extends (keyof EnvRegistry | (string & {})) = keyof EnvRegistry>(env: K, defaultValue?: D): EnvReturn<X, K, D>;
 }
 type ConfigShape = keyof ConfigRegistry extends never ? Record<string, any> : ConfigRegistry;
 interface GlobalConfig {
@@ -285,7 +390,6 @@ declare const env: GlobalEnv;
  * @returns
  */
 declare const appUrl: (link?: string) => string;
-declare const CONFIG_KEY: unique symbol;
 /**
  * Gets the application configuration.
  *
@@ -589,4 +693,81 @@ declare class Hook {
   static clear: () => void;
 }
 //#endregion
-export { AbstractModelConstructor, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvRegistry, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, Primitive, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, discoverCommands, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+//#region src/EnvLoader.d.ts
+/**
+ * Loads environment variables, reading the `.env` file on first access.
+ *
+ * The `.env` file is loaded lazily the first time a variable is read, so
+ * environment access never depends on a side-effect `import 'dotenv/config'`
+ * running first. Import ordering — which linters and bundlers may rewrite —
+ * could otherwise place an env-reading module before dotenv has populated
+ * `process.env`, leaving that module with default/stale values.
+ * `dotenv.config()` never overrides variables already set, so the lazy load is
+ * safe alongside other loaders.
+ */
+declare class EnvLoader {
+  private loaded;
+  /**
+   * Load the `.env` file once.
+   *
+   * @returns
+   */
+  private ensureLoaded;
+  /**
+   * Read an environment variable, coercing booleans, numbers and `null`, and
+   * falling back to `defaultValue` when it is unset.
+   *
+   * @param name          The variable name.
+   * @param defaultValue  Returned when the variable is unset.
+   */
+  get<X = never, D = undefined, K extends string = string>(name: K, defaultValue?: D): EnvReturn<X, K, D>;
+}
+/**
+ * Shared environment loader backing {@link env}.
+ */
+declare const envLoader: EnvLoader;
+//#endregion
+//#region src/ConfigLoader.d.ts
+declare const CONFIG_KEY: unique symbol;
+/**
+ * Loads and resolves application configuration from the config directory.
+ *
+ * Config modules are read once (lazily) from the output directory and cached on
+ * a global symbol, then queried by dot-path. A partial config object can also be
+ * merged in at runtime.
+ */
+declare class ConfigLoader {
+  /**
+   * The cached config store, shared across instances via a global symbol.
+   */
+  private get store();
+  private set store(value);
+  /**
+   * Read and cache config modules from the config directory on first use.
+   */
+  private load;
+  /**
+   * Resolve the directory to load config modules from.
+   *
+   * Prefers an explicit `CONFIG_PATH`, then the environment-selected output
+   * directory. Falls back to the other build output (`dist` ⇄
+   * `.arkstack/build`) so config still loads if the selected directory is
+   * missing or transiently emptied — e.g. a concurrent rebuild (`clean: true`)
+   * during a test run.
+   */
+  private resolveConfigDir;
+  /**
+   * Resolve configuration: read a dot-path value, merge a partial config
+   * object, or return the whole config.
+   *
+   * @param key           Dot-path to read, or an object to merge in.
+   * @param defaultValue  Returned when a string key is not found.
+   */
+  resolve<X extends ConfigRegistry | unknown = unknown, P extends DotPath<X> | undefined = undefined>(key?: P, defaultValue?: any): any;
+}
+/**
+ * Shared config loader backing {@link config}.
+ */
+declare const configLoader: ConfigLoader;
+//#endregion
+export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, ConfigLoader, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, Primitive, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, discoverCommands, env, envLoader, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/index.js

@@ -1,7 +1,8 @@
-import { A as resolveRuntimeDir, C as discoverCommands, D as nodeEnv, E as interopDefault, M as toOutputPath, O as outputDir, S as config, T as importFile, _ as Hash, b as appKey, c as abortIf, d as initializeGlobalContext, f as isClass, g as Exception, h as AppException, j as resolveRuntimeModule, k as rebuildOutput, l as assertFound, m as RequestException, p as perPage, s as abort, u as getModel, v as Encryption, w as env, x as appUrl, y as CONFIG_KEY } from "./utils-DJQAOLbx.js";
+import { _ as ConfigLoader, a as env, c as nodeEnv, d as resolveRuntimeDir, f as resolveRuntimeModule, g as CONFIG_KEY, h as envLoader, i as discoverCommands, l as outputDir, m as EnvLoader, n as appUrl, o as importFile, p as toOutputPath, r as config, s as interopDefault, t as appKey, u as rebuildOutput, v as configLoader } from "./system-DUaI4u99.js";
+import { _ as Hash, c as abortIf, d as initializeGlobalContext, f as isClass, g as Exception, h as AppException, l as assertFound, m as RequestException, p as perPage, s as abort, u as getModel, v as Encryption } from "./utils-Df3nH1sG.js";
 import { Hook as Hook$1 } from "@arkstack/foundry";
-import { str } from "@h3ravel/support";
 import { Arkstack } from "@arkstack/contract";
+import { str } from "@h3ravel/support";
 import path from "node:path";
 import { ModelNotFoundException } from "arkormx";
 import { detect } from "detect-port";
@@ -529,4 +530,4 @@ var Hook = class {
 	};
 };
 //#endregion
-export { AppException, CONFIG_KEY, Encryption, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, discoverCommands, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+export { AppException, CONFIG_KEY, ConfigLoader, Encryption, EnvLoader, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, discoverCommands, env, envLoader, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };