@arkstack/common 0.12.12 → 0.12.13

package/dist/index.d.ts

@@ -1 +1,435 @@
 /// <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 { JitiOptions, JitiResolveOptions } from "jiti";
+import { Arkstack } from "@arkstack/contract";
+import pino from "pino";
+import { ChalkInstance } from "chalk";
+
+//#region src/lifecycle.d.ts
+declare const bindGracefulShutdown: (shutdown: () => Promise<void> | void, defer?: boolean) => void;
+//#endregion
+//#region src/network.d.ts
+/**
+ * Boots the app using an available port close to the requested port
+ *when requested port is not available
+ *
+ * @param boot
+ * @param preferredPort
+ * @param app
+ * @param defer
+ */
+declare const bootWithDetectedPort: <TApp, TRoutes = unknown, THandler = unknown>(boot: (port: number) => Promise<void>, preferredPort?: number, app?: Arkstack<TApp, TRoutes, THandler>, defer?: boolean) => Promise<void>;
+declare const renderError: ({
+  message,
+  stack,
+  title,
+  code
+}: {
+  message?: string;
+  stack?: string;
+  code?: number;
+  title?: string;
+}) => any;
+//#endregion
+//#region src/prototypes.d.ts
+declare const loadPrototypes: () => void;
+//#endregion
+//#region src/Logger.d.ts
+declare class Console {
+  static log: (...args: any[]) => string | void;
+  static debug: (...args: any[]) => void;
+  static warn: (...args: any[]) => void[];
+  static info: (...args: any[]) => void[];
+  static error: (...args: any[]) => void[];
+}
+declare class Logger {
+  /**
+   * Global verbosity configuration
+   */
+  private static verbosity;
+  private static isQuiet;
+  private static isSilent;
+  /**
+   * Configure global verbosity levels
+   */
+  static configure(options?: {
+    verbosity?: number;
+    quiet?: boolean;
+    silent?: boolean;
+  }): void;
+  /**
+   * Check if output should be suppressed
+   */
+  private static shouldSuppressOutput;
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param value
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
+  static twoColumnDetail(name: string, value: string, log?: true, spacer?: string): void;
+  static twoColumnDetail(name: string, value: string, log?: false, spacer?: string): [string, string, string];
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param desc
+   * @param width
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
+  static describe(name: string, desc: string, width?: number, log?: true): void;
+  static describe(name: string, desc: string, width?: number, log?: false): [string, string, string];
+  /**
+   * Logs the message in two columns but allways passing status
+   *
+   * @param name
+   * @param value
+   * @param status
+   * @param exit
+   * @param preserveCol
+   */
+  static split(name: string, value: string, status?: 'success' | 'info' | 'error', exit?: boolean, preserveCol?: boolean, spacer?: string): void;
+  /**
+   * Wraps text with chalk
+   *
+   * @param txt
+   * @param color
+   * @param preserveCol
+   * @returns
+   */
+  static textFormat(txt: unknown | unknown[], color: (...text: unknown[]) => string, preserveCol?: boolean): string;
+  /**
+   * Logs a success message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static success(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an informational message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static info(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an error message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static error(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a warning message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static warn(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a debug message (only shown with verbosity >= 3)
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static debug<M = any>(msg: M | M[], exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Terminates the process
+   */
+  static quiet(): void;
+  static chalker(styles: LoggerChalk[]): (input: any) => string;
+  /**
+   * Parse an array formated message and logs it
+   *
+   * @param config
+   * @param joiner
+   * @param log If set to false, string output will be returned and not logged
+   * @param sc color to use ue on split text if : is found
+   */
+  static parse(config: LoggerParseSignature, joiner?: string, log?: true, sc?: LoggerChalk): void;
+  static parse(config: LoggerParseSignature, joiner?: string, log?: false, sc?: LoggerChalk): string;
+  /**
+   * Ouput formater object or format the output
+   *
+   * @returns
+   */
+  static log: LoggerLog;
+  /**
+   * A simple console like output logger
+   *
+   * @returns
+   */
+  static console(): typeof Console;
+}
+//#endregion
+//#region src/types.d.ts
+interface ConfigRegistry {}
+interface EnvRegistry {}
+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;
+type LoggerChalk = keyof ChalkInstance | ChalkInstance | (keyof ChalkInstance)[];
+type LoggerParseSignature = [string, LoggerChalk][];
+type DotPathValue<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? DotPathValue<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
+type DotPath<T> = T extends Primitive ? never : T extends any[] ? never : { [K in keyof T & string]: T[K] extends Primitive ? `${K}` : T[K] extends any[] ? `${K}` : `${K}` | `${K}.${DotPath<T[K]>}` }[keyof T & string];
+/**
+ * Ouput formater object or format the output
+ *
+ * @param config
+ * @param joiner
+ * @param log If set to false, string output will be returned and not logged
+ * @param sc color to use ue on split text if : is found
+ *
+ * @returns
+ */
+interface LoggerLog {
+  (): typeof Logger;
+  <L extends boolean>(config: string, joiner: LoggerChalk, 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;
+  <L extends boolean>(config?: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string | Logger;
+}
+interface GlobalEnv {
+  <X = string, Y = undefined | X>(env: string, defaultValue?: Y): Y extends undefined ? X : Y;
+}
+type ConfigShape = keyof ConfigRegistry extends never ? Record<string, any> : ConfigRegistry;
+interface GlobalConfig {
+  <X extends ConfigShape>(): X;
+  <X extends ConfigShape, P extends DotPath<X>>(key: P): DotPathValue<X, P>;
+  <X extends ConfigShape, P extends DotPath<X>>(key: Record<P, Partial<DotPathValue<X, P>>>): void;
+  <X extends ConfigShape, P extends DotPath<X>, D>(key: P, defaultValue: D): DotPathValue<X, P> | D;
+}
+interface FileImporter {
+  <T = unknown>(filePath: string): Promise<T>;
+  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined): Promise<T>;
+  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined, resolveOptions?: (JitiResolveOptions & {
+    default?: true;
+  })): Promise<T>;
+}
+type ArkstackErrorShape = Error & {
+  cause?: unknown;
+  code?: number | string;
+  errors?: unknown;
+  getModelName?: () => string;
+  status?: number;
+  statusCode?: number;
+};
+interface ArkstackErrorPayload {
+  status: 'error';
+  code: number;
+  message: string;
+  errors?: unknown;
+  stack?: string;
+}
+interface HookRegistry {}
+type Position = 'before' | 'after' | (string & {});
+type IHook = { [P in Position]?: (...args: any[]) => void };
+type HookName = keyof HookRegistry extends never ? string : keyof HookRegistry | (string & {});
+type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N] : IHook;
+type HookPos<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] : (...args: any[]) => void : (...args: any[]) => void;
+type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof HookRegistry[N] : Position;
+type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
+//#endregion
+//#region src/system.d.ts
+/**
+ * Read the .env file
+ *
+ * @param env
+ * @param def
+ * @returns
+ */
+declare const env: GlobalEnv;
+/**
+ * Build the app url
+ *
+ * @param link
+ * @returns
+ */
+declare const appUrl: (link?: string) => string;
+declare const CONFIG_KEY: unique symbol;
+/**
+ * Gets the application configuration.
+ *
+ * @param key             The configuration key to retrieve.
+ * @param defaultValue    The default value to return if the key is not found.
+ * @returns               The configuration value.
+ */
+declare const config: GlobalConfig;
+/**
+ * Gets the current Node environment (development or production).
+ *
+ * @returns
+ */
+declare const nodeEnv: () => "prod" | "dev";
+/**
+ * Gets the output directory for the application based on the current environment.
+ *
+ * @param cwd  The current working directory (optional, defaults to Arkstack.rootDir()).
+ * @returns
+ */
+declare const outputDir: (cwd?: string) => string;
+/**
+ *
+ * Dynamically imports a file at the given path with full TypeScript support,
+ * including `tsconfig.json` path aliases.
+ *
+ * @param filePath - The path to the file to import.
+ * @returns The imported module typed as `T`.
+ *
+ * @example
+ * const config = await importFile<AppConfig>('./config/app.ts')
+ */
+declare const importFile: FileImporter;
+/**
+ * Resolves the default export from a module, handling both CJS and ESM interop.
+ * In CJS modules, the default export is often the module itself (a function or object),
+ * while in ESM the default is nested under the `default` property.
+ *
+ * @param imp - The imported module
+ * @returns The resolved default export
+ */
+declare const interopDefault: <T>(imp: T | {
+  default: T;
+}) => T;
+//#endregion
+//#region src/Exceptions/Exception.d.ts
+declare class Exception extends Error {
+  name: string;
+  constructor(message?: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/Exceptions/AppException.d.ts
+declare class AppException extends Exception {
+  errors?: {
+    [key: string]: string[] | string;
+  } | undefined;
+  statusCode: number;
+  constructor(message?: string, statusCode?: number, options?: ErrorOptions);
+}
+//#endregion
+//#region src/Exceptions/RequestException.d.ts
+declare class RequestException extends AppException {
+  statusCode: number;
+  constructor(message?: string, statusCode?: number, options?: ErrorOptions);
+  /**
+   * Asserts that a value is not null or undefined.
+   *
+   * @param value
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the value is null or undefined.
+   */
+  static assertFound<T>(value: T | null | undefined, message: string, code?: number): asserts value is T;
+  /**
+   * Asserts that a value is not null or undefined.
+   *
+   * @param value
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the value is null or undefined.
+   * @deprecated Use assertFound instead
+   */
+  static assertNotEmpty<T>(value: T | null | undefined, message: string, code?: number): asserts value is T;
+  /**
+   * Asserts that a boolean condition is true.
+   *
+   * @param boolean
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the boolean condition is true.
+   */
+  static abortIf<T>(boolean: T, message: string, code?: number): asserts boolean is T;
+}
+//#endregion
+//#region src/ErrorHandler.d.ts
+declare class ErrorHandler {
+  private static loggerCache;
+  private static isRecord;
+  static toErrorShape(value: unknown): ArkstackErrorShape | undefined;
+  static normalizeStatusCode(value: unknown, fallback?: number): number;
+  static getErrorLogger(): pino.Logger;
+  static serializeError(value: unknown, seen?: WeakSet<object>): unknown;
+  static getPrimaryError(error: ArkstackErrorShape | string): string | ArkstackErrorShape;
+  static getValidationErrors(error: ArkstackErrorShape): any;
+  static isValidationError(error: unknown): error is ArkstackErrorShape;
+  static isModelNotFoundError(error: unknown): error is ArkstackErrorShape;
+  static shouldHideStack(): boolean;
+  static shouldLogError(error: unknown): boolean;
+  static createErrorPayload(err: ArkstackErrorShape | string, fallbackMessage?: string): ArkstackErrorPayload;
+  static logUnhandledError(err: unknown, request: Record<string, unknown>, message: string): void;
+}
+declare const toErrorShape: typeof ErrorHandler.toErrorShape;
+declare const normalizeStatusCode: typeof ErrorHandler.normalizeStatusCode;
+declare const getErrorLogger: typeof ErrorHandler.getErrorLogger;
+declare const serializeError: typeof ErrorHandler.serializeError;
+declare const getPrimaryError: typeof ErrorHandler.getPrimaryError;
+declare const getValidationErrors: typeof ErrorHandler.getValidationErrors;
+declare const isValidationError: typeof ErrorHandler.isValidationError;
+declare const isModelNotFoundError: typeof ErrorHandler.isModelNotFoundError;
+declare const shouldHideStack: typeof ErrorHandler.shouldHideStack;
+declare const shouldLogError: typeof ErrorHandler.shouldLogError;
+declare const createErrorPayload: typeof ErrorHandler.createErrorPayload;
+declare const logUnhandledError: typeof ErrorHandler.logUnhandledError;
+//#endregion
+//#region src/Hook.d.ts
+declare class Hook {
+  private static hooks;
+  /**
+   * Hooks define code that should run within defined boundaries to add extra functionalities.
+   *
+   * @param name
+   * @param value
+   */
+  static set<N extends HookName>(name: N | (string & {}), hook: HookFor<N>): void;
+  /**
+   * Check if a hook is defined by name
+   *
+   * @param name
+   */
+  static has<N extends HookName, P extends HookPositions<N>>(name: N | (string & {}), pos?: P): boolean;
+  /**
+   * Retrieve a defined hook by name
+   *
+   * @param name
+   */
+  static get<N extends HookName>(name: N): HookFor<N> | undefined;
+  /**
+   * Retrieve a defined hook by name and position
+   *
+   * @param name
+   * @param pos
+   */
+  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P): HookPos<N, P> | undefined;
+  /**
+   * Retrieve a defined hook by name and position the set args for callback
+   *
+   * @param name
+   * @param pos
+   */
+  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P>): void;
+  /**
+   * Retrieve all defined hooks
+   *
+   * @param name
+   */
+  static getAll: () => Record<string, IHook> & HookRegistry;
+  /**
+   * Remove the defined hook
+   *
+   * @param name
+   */
+  static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
+  /**
+   * Clear all the defined hooks
+   */
+  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, RequestException, UnionToIntersection, abort, abortIf, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, renderError, serializeError, shouldHideStack, shouldLogError, toErrorShape };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -42,8 +42,8 @@
   "peerDependencies": {
     "@h3ravel/support": "^0.15.11",
     "arkormx": "^ 2.4.1",
-    "@arkstack/foundry": "^0.12.12",
-    "@arkstack/contract": "^0.12.12"
+    "@arkstack/foundry": "^0.12.13",
+    "@arkstack/contract": "^0.12.13"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",