@arkstack/common 0.14.19 → 0.14.21

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,6 +170,9 @@ 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 {}
 /**
@@ -192,6 +195,11 @@ interface EnvRegistry {
   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;
@@ -200,6 +208,8 @@ interface EnvRegistry {
   OUTPUT_DIR_DEV: string;
   CONFIG_PATH: string;
   TUNNEL: boolean;
+  NGROK_AUTHTOKEN: string;
+  NGROK_DOMAIN: string;
   FILESYSTEM_DISK: string;
   CACHE_STORE: string;
   CACHE_PREFIX: string;
@@ -237,7 +247,26 @@ interface EnvRegistry {
   AWS_URL: string;
   AWS_ENDPOINT: string;
 }
-/** Known environment variable names. */
+/**
+ * App Confifuration
+ */
+interface AppConfig {
+  [key: string]: any;
+  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;
@@ -274,7 +303,7 @@ interface LoggerLog {
  */
 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 = never, D = undefined, K extends string = string>(env: K, defaultValue?: D): EnvReturn<X, K, D>;
+  <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 {
@@ -742,4 +771,4 @@ declare class ConfigLoader {
  */
 declare const configLoader: ConfigLoader;
 //#endregion
-export { AbstractModelConstructor, 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 };
+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,4 +1,5 @@
-import { A as resolveRuntimeModule, C as env, D as outputDir, E as nodeEnv, F as ConfigLoader, I as configLoader, M as EnvLoader, N as envLoader, O as rebuildOutput, P as CONFIG_KEY, S as discoverCommands, T as interopDefault, _ as Hash, b as appUrl, c as abortIf, d as initializeGlobalContext, f as isClass, g as Exception, h as AppException, j as toOutputPath, k as resolveRuntimeDir, l as assertFound, m as RequestException, p as perPage, s as abort, u as getModel, v as Encryption, w as importFile, x as config, y as appKey } from "./utils-DEflBOXp.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 { Arkstack } from "@arkstack/contract";
 import { str } from "@h3ravel/support";

package/dist/{utils-DEflBOXp.js → system-DUaI4u99.js}

@@ -1,4 +1,3 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { createJiti } from "jiti";
 import { existsSync, readdirSync } from "fs";
 import { Arkstack } from "@arkstack/contract";
@@ -10,9 +9,6 @@ import { config } from "dotenv";
 import { pathToFileURL } from "node:url";
 import { rm } from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { Secret, TOTP } from "otpauth";
-import { compare, genSalt, hash } from "bcryptjs";
-import { getUserConfig } from "arkormx";
 //#region src/ConfigLoader.ts
 const CONFIG_KEY = Symbol("globalConfig");
 globalThis[CONFIG_KEY] = {};
@@ -476,433 +472,4 @@ const interopDefault = (imp) => {
 	return typeof imp === "function" ? imp : imp.default;
 };
 //#endregion
-//#region src/utils/encryption.ts
-var Encryption = class {
-	static algorithm = "aes-256-gcm";
-	static getKey() {
-		const secret = appKey("TWO_FACTOR_ENCRYPTION_KEY");
-		if (!secret) throw new Error("APP_KEY is required to use two-factor authentication. Run `ark key:generate`.");
-		return createHash("sha256").update(secret).digest();
-	}
-	static encrypt(value) {
-		const iv = randomBytes(12);
-		const cipher = createCipheriv(this.algorithm, this.getKey(), iv);
-		const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
-		return [
-			iv,
-			cipher.getAuthTag(),
-			ciphertext
-		].map((part) => part.toString("base64url")).join(":");
-	}
-	static decrypt(payload) {
-		const [iv, authTag, ciphertext] = payload.split(":");
-		if (!iv || !authTag || !ciphertext) throw new Error("Invalid encrypted payload format");
-		const decipher = createDecipheriv(this.algorithm, this.getKey(), Buffer.from(iv, "base64url"));
-		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
-		return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64url")), decipher.final()]).toString("utf8");
-	}
-};
-//#endregion
-//#region src/utils/hash.ts
-var Hash = class {
-	/**
-	* Hash a value using bcrypt
-	* 
-	* @param value 
-	* @returns 
-	*/
-	static async make(value) {
-		return await hash(value, await genSalt(10));
-	}
-	/**
-	* Verify a value against a hashed value
-	* 
-	* @param value 
-	* @param hashedValue 
-	* @returns 
-	*/
-	static async verify(value, hashedValue) {
-		return await compare(value, hashedValue);
-	}
-	/**
-	* Generate a one-time password (OTP) using TOTP algorithm
-	* 
-	* @param digits    The number of digits for the OTP, default is 6.
-	* @param label     A label to identify the OTP, can be an email or phone number.
-	* @param period    Interval of time for which a token is valid, in seconds.
-	* @returns 
-	*/
-	static otp(digits = 6, label = "Alice", period = 30) {
-		return new TOTP({
-			label,
-			digits,
-			issuer: env$1("APP_NAME", "Roseed"),
-			algorithm: "SHA1",
-			period,
-			secret: "US3WHSG7X5KAPV27VANWKQHF3SH3HULL"
-		});
-	}
-	static totp(secret, label, issuer = env$1("APP_NAME", "Roseed"), period = 30) {
-		return new TOTP({
-			issuer,
-			label,
-			algorithm: "SHA1",
-			digits: 6,
-			period,
-			secret: Secret.fromBase32(secret)
-		});
-	}
-};
-//#endregion
-//#region src/Exceptions/Exception.ts
-var Exception = class extends Error {
-	name;
-	constructor(message, options) {
-		super(message, options);
-		this.name = "Exception";
-	}
-};
-//#endregion
-//#region src/Exceptions/AppException.ts
-var AppException = class extends Exception {
-	errors = void 0;
-	statusCode;
-	constructor(message, statusCode = 400, options) {
-		super(message, options);
-		this.statusCode = statusCode;
-	}
-};
-//#endregion
-//#region src/Exceptions/RequestException.ts
-var RequestException = class RequestException extends AppException {
-	statusCode;
-	constructor(message, statusCode = 400, options) {
-		super(message, statusCode, options);
-		this.statusCode = statusCode;
-	}
-	/**
-	* 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(value, message, code = 404) {
-		if (!value) throw new RequestException(message, code);
-	}
-	/**
-	* 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(value, message, code = 404) {
-		return this.assertFound(value, message, code);
-	}
-	/**
-	* Asserts that a boolean condition is true. 
-	* 
-	* @param boolean 
-	* @param message 
-	* @param code 
-	* @throws {RequestException} Throws if the boolean condition is true.
-	*/
-	static abortIf(boolean, message, code) {
-		if (boolean) throw new RequestException(message, code);
-	}
-};
-//#endregion
-//#region src/utils/helpers.ts
-/**
-* Checks and asserts if target is a class
-* 
-* @param target 
-* @returns 
-*/
-const isClass = (target) => {
-	return typeof target === "function" && /^class\s/.test(Function.prototype.toString.call(target));
-};
-/**
-* Determine the number of items to return per page based on the provided query parameters.
-* 
-* @param query 
-* @returns 
-*/
-const perPage = (query) => {
-	const requestedPerPage = Number(query.limit ?? query.perPage ?? 15);
-	return Number.isFinite(requestedPerPage) && requestedPerPage > 0 ? Math.min(requestedPerPage, 50) : 15;
-};
-async function getModel(modelName) {
-	const resolveModelExport = (module, modelName) => {
-		if (!isModelModule(module)) return module;
-		return module.default ?? module[modelName] ?? module;
-	};
-	const isModelModule = (value) => typeof value === "object" && value !== null;
-	const modelPath = getUserConfig().paths?.models || "./src/models";
-	const model = resolveModelExport(await importFile(resolveRuntimeModule(path.join(path.isAbsolute(modelPath) ? modelPath : path.join(Arkstack.rootDir(), modelPath), modelName))), path.basename(modelName, path.extname(modelName)));
-	if (typeof model !== "function") throw new Error(`Model "${modelName}" not found`);
-	return model;
-}
-const initializeGlobalContext = async ({ Request, Response, Session } = {}) => {
-	try {
-		const { Request: Req, Response: Res, Session: Ses } = await import("@arkstack/http");
-		Session ??= new Ses();
-		Request ??= new Req();
-		Response ??= new Res();
-	} catch {
-		Session ??= new class {}();
-		Request ??= new class {}();
-		Response ??= new class {}();
-	}
-	globalThis.session ??= () => Session;
-	globalThis.request ??= () => Request;
-	globalThis.response ??= () => Response;
-};
-/**
-* Thows to abort the current request
-* 
-* @param message 
-* @param code 
-* @throws {RequestException}
-*/
-const abort = (message = "Request Aborted", code = 404) => {
-	RequestException.abortIf(true, message, code);
-};
-/**
-* Asserts that a boolean condition is true. 
-* 
-* @param boolean 
-* @param message 
-* @param code 
-* @throws {RequestException} Throws if the boolean condition is true.
-*/
-const abortIf = (boolean, message = "Request Aborted", code = 404) => {
-	RequestException.abortIf(boolean, message, code);
-};
-/**
-* 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.
-*/
-const assertFound = (value, message, code = 404) => {
-	if (!value) throw new RequestException(message, code);
-};
-//#endregion
-//#region src/utils/traits.ts
-/**
-* CRC32 implementation in TypeScript, adapted from https://stackoverflow.com/a/18639999
-* Note: This implementation is not cryptographically secure and is only used for generating 
-* unique identifiers for traits based on their factory function's string representation. 
-*/
-const crcTable = [];
-for (let n = 0; n < 256; n++) {
-	let c = n;
-	for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
-	crcTable[n] = c;
-}
-const crc32 = (str) => {
-	let crc = -1;
-	for (let i = 0; i < str.length; i++) crc = crc >>> 8 ^ crcTable[(crc ^ str.charCodeAt(i)) & 255];
-	return (crc ^ -1) >>> 0;
-};
-const isCons = (fn) => typeof fn === "function" && !!fn.prototype && !!fn.prototype.constructor;
-const isArkormModelInstance = (value) => typeof value === "object" && value !== null && typeof value.constructor === "function" && typeof value.getAttribute === "function" && typeof value.setAttribute === "function";
-const isTypeFactory = (fn) => typeof fn === "function" && !fn.prototype && fn.length === 0;
-/**
-* API: generate trait (technical implementation)
-* 
-* @param args 
-*/
-function trait(...args) {
-	const factory = args.length === 2 ? args[1] : args[0];
-	const superTraits = args.length === 2 ? args[0] : void 0;
-	return {
-		id: crc32(factory.toString()),
-		symbol: Symbol("trait"),
-		factory,
-		superTraits
-	};
-}
-/**
-* utility function: add an additional invisible property to an object
-* 
-* @param cons 
-* @param field 
-* @param value 
-* @returns 
-*/
-const extendProperties = (cons, field, value) => Object.defineProperty(cons, field, {
-	value,
-	enumerable: false,
-	writable: false
-});
-const traitMethodRegistry = Symbol("trait-method-registry");
-const cloneMethodRegistry = (target) => {
-	const registry = target[traitMethodRegistry];
-	return new Map([...registry?.entries() ?? []].map(([name, methods]) => [name, [...methods]]));
-};
-const registerMethodScope = (target, base, ignored) => {
-	const registry = cloneMethodRegistry(base);
-	for (const name of Reflect.ownKeys(target)) {
-		if (ignored.has(name)) continue;
-		const method = Object.getOwnPropertyDescriptor(target, name)?.value;
-		if (typeof method !== "function") continue;
-		const methods = registry.get(name);
-		const previous = base?.[name];
-		if (methods) {
-			if (methods.at(-1) !== method) methods.push(method);
-			registry.set(name, methods);
-		} else if (typeof previous === "function" && previous !== method) registry.set(name, [previous, method]);
-	}
-	Object.defineProperty(target, traitMethodRegistry, {
-		configurable: false,
-		enumerable: false,
-		value: registry,
-		writable: false
-	});
-};
-/**
-* Registers conflicting trait methods
-* 
-* @param classInstance 
-* @param baseClass 
-*/
-const registerTraitMethods = (classInstance, baseClass) => {
-	registerMethodScope(classInstance.prototype, baseClass.prototype, new Set(["constructor"]));
-	registerMethodScope(classInstance, baseClass, new Set([
-		"length",
-		"name",
-		"prototype",
-		"arguments",
-		"caller"
-	]));
-};
-/**
-* Return every trait implementation for a method, bound to the supplied
-* instance or class. Methods are ordered from the base implementation to the
-* currently active trait implementation.
-* 
-* @param target 
-* @param name 
-* @returns 
-*/
-const getTraitMethods = (target, name) => {
-	return (((typeof target === "function" ? target : Object.getPrototypeOf(target))?.[traitMethodRegistry])?.get(name) ?? []).map((method) => method.bind(target));
-};
-/**
-* Invoke every trait implementation for a method in registration order.
-* 
-* @param target 
-* @param name 
-* @param args 
-* @returns 
-*/
-const callTraitMethods = (target, name, ...args) => {
-	const methods = getTraitMethods(target, name);
-	if (methods.length === 0) {
-		console.warn(`No conflicting trait methods found for "${String(name)}".`);
-		return [];
-	}
-	return methods.map((method) => method(...args));
-};
-/**
-* utility function: get raw trait
-* 
-* @param x 
-* @returns 
-*/
-const rawTrait = (x) => isTypeFactory(x) ? x() : x;
-/**
-* utility function: derive a trait
-* 
-* @param trait$ 
-* @param baseClass 
-* @param derived 
-* @returns 
-*/
-const deriveTrait = (trait$, baseClass, derived) => {
-	const trait = rawTrait(trait$);
-	if (trait === void 0 || trait === null || typeof trait.id !== "number") throw new Error("use(): received an undefined or invalid trait. This usually means a circular import — the trait module had not finished initializing when use() ran. Avoid importing models at the top level of trait modules, or break the import cycle.");
-	let classInstance = baseClass;
-	if (!derived.has(trait.id)) {
-		derived.set(trait.id, true);
-		if (trait.superTraits !== void 0) for (const superTrait of reverseTraitList(trait.superTraits)) classInstance = deriveTrait(superTrait, classInstance, derived);
-		const base = classInstance;
-		classInstance = trait.factory(classInstance);
-		registerTraitMethods(classInstance, base);
-		extendProperties(classInstance, "id", crc32(trait.factory.toString()));
-		extendProperties(classInstance, trait.symbol, true);
-	}
-	return classInstance;
-};
-/**
-* utility function: get reversed trait list
-* 
-* @param traits 
-* @returns 
-*/
-const reverseTraitList = (traits) => traits.slice().reverse();
-function use(...args) {
-	const withMethodHelpers = args[0] === true;
-	const traits = withMethodHelpers ? args.slice(1) : args;
-	if (traits.length === 0) throw new Error("invalid number of parameters (expected one or more traits)");
-	let classInstance;
-	let lot;
-	const last = traits[traits.length - 1];
-	if (isCons(last) && !isTypeFactory(last)) {
-		classInstance = last;
-		lot = traits.slice(0, -1);
-	} else if (isArkormModelInstance(last)) {
-		classInstance = last.constructor;
-		lot = traits.slice(0, -1);
-	} else {
-		classInstance = class ROOT {};
-		lot = traits;
-	}
-	const derived = /* @__PURE__ */ new Map();
-	for (const trait of reverseTraitList(lot)) classInstance = deriveTrait(trait, classInstance, derived);
-	if (withMethodHelpers) classInstance = class TraitMethodEnabled extends classInstance {
-		getTraitMethods(name) {
-			return getTraitMethods(this, name);
-		}
-		callTraitMethods(name, ...args) {
-			return callTraitMethods(this, name, ...args);
-		}
-		static getTraitMethods(name) {
-			return getTraitMethods(this, name);
-		}
-		static callTraitMethods(name, ...args) {
-			return callTraitMethods(this, name, ...args);
-		}
-	};
-	return classInstance;
-}
-/**
-* API: type guard for checking whether class instance is derived from a trait
-* 
-* @param instance 
-* @param trait 
-* @returns 
-*/
-function uses(instance, trait) {
-	if (typeof instance !== "object" || instance === null) return false;
-	let obj = instance;
-	if (isCons(trait) && !isTypeFactory(trait)) return instance instanceof trait;
-	const idTrait = (isTypeFactory(trait) ? trait() : trait)["id"];
-	while (obj) {
-		if (Object.hasOwn(obj, "constructor")) {
-			if ((obj.constructor["id"] ?? 0) === idTrait) return true;
-		}
-		obj = Object.getPrototypeOf(obj);
-	}
-	return false;
-}
-//#endregion
-export { resolveRuntimeModule as A, env$1 as C, outputDir as D, nodeEnv as E, ConfigLoader as F, configLoader as I, EnvLoader as M, envLoader as N, rebuildOutput as O, CONFIG_KEY as P, discoverCommands as S, interopDefault as T, Hash as _, use as a, appUrl as b, abortIf as c, initializeGlobalContext as d, isClass as f, Exception as g, AppException as h, trait as i, toOutputPath as j, resolveRuntimeDir as k, assertFound as l, RequestException as m, crc32 as n, uses as o, perPage as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, Encryption as v, importFile as w, config$1 as x, appKey as y };
+export { ConfigLoader as _, env$1 as a, nodeEnv as c, resolveRuntimeDir as d, resolveRuntimeModule as f, CONFIG_KEY as g, envLoader as h, discoverCommands as i, outputDir as l, EnvLoader as m, appUrl as n, importFile as o, toOutputPath as p, config$1 as r, interopDefault as s, appKey as t, rebuildOutput as u, configLoader as v };

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-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 { Model } from "arkormx";
 
 //#region src/utils/traits.d.ts

package/dist/utils/index.js

@@ -1,2 +1,2 @@
-import { _ as Hash, a as use, c as abortIf, d as initializeGlobalContext, f as isClass, i as trait, l as assertFound, n as crc32, o as uses, p as perPage, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, v as Encryption } from "../utils-DEflBOXp.js";
+import { _ as Hash, a as use, c as abortIf, d as initializeGlobalContext, f as isClass, i as trait, l as assertFound, n as crc32, o as uses, p as perPage, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, v as Encryption } from "../utils-Df3nH1sG.js";
 export { Encryption, Hash, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getTraitMethods, initializeGlobalContext, isClass, perPage, trait, use, uses };

package/dist/utils-Df3nH1sG.js

@@ -0,0 +1,437 @@
+import { a as env, f as resolveRuntimeModule, o as importFile, t as appKey } from "./system-DUaI4u99.js";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { Arkstack } from "@arkstack/contract";
+import path from "node:path";
+import { Secret, TOTP } from "otpauth";
+import { compare, genSalt, hash } from "bcryptjs";
+import { getUserConfig } from "arkormx";
+//#region src/utils/encryption.ts
+var Encryption = class {
+	static algorithm = "aes-256-gcm";
+	static getKey() {
+		const secret = appKey("TWO_FACTOR_ENCRYPTION_KEY");
+		if (!secret) throw new Error("APP_KEY is required to use two-factor authentication. Run `ark key:generate`.");
+		return createHash("sha256").update(secret).digest();
+	}
+	static encrypt(value) {
+		const iv = randomBytes(12);
+		const cipher = createCipheriv(this.algorithm, this.getKey(), iv);
+		const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+		return [
+			iv,
+			cipher.getAuthTag(),
+			ciphertext
+		].map((part) => part.toString("base64url")).join(":");
+	}
+	static decrypt(payload) {
+		const [iv, authTag, ciphertext] = payload.split(":");
+		if (!iv || !authTag || !ciphertext) throw new Error("Invalid encrypted payload format");
+		const decipher = createDecipheriv(this.algorithm, this.getKey(), Buffer.from(iv, "base64url"));
+		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
+		return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64url")), decipher.final()]).toString("utf8");
+	}
+};
+//#endregion
+//#region src/utils/hash.ts
+var Hash = class {
+	/**
+	* Hash a value using bcrypt
+	* 
+	* @param value 
+	* @returns 
+	*/
+	static async make(value) {
+		return await hash(value, await genSalt(10));
+	}
+	/**
+	* Verify a value against a hashed value
+	* 
+	* @param value 
+	* @param hashedValue 
+	* @returns 
+	*/
+	static async verify(value, hashedValue) {
+		return await compare(value, hashedValue);
+	}
+	/**
+	* Generate a one-time password (OTP) using TOTP algorithm
+	* 
+	* @param digits    The number of digits for the OTP, default is 6.
+	* @param label     A label to identify the OTP, can be an email or phone number.
+	* @param period    Interval of time for which a token is valid, in seconds.
+	* @returns 
+	*/
+	static otp(digits = 6, label = "Alice", period = 30) {
+		return new TOTP({
+			label,
+			digits,
+			issuer: env("APP_NAME", "Roseed"),
+			algorithm: "SHA1",
+			period,
+			secret: "US3WHSG7X5KAPV27VANWKQHF3SH3HULL"
+		});
+	}
+	static totp(secret, label, issuer = env("APP_NAME", "Roseed"), period = 30) {
+		return new TOTP({
+			issuer,
+			label,
+			algorithm: "SHA1",
+			digits: 6,
+			period,
+			secret: Secret.fromBase32(secret)
+		});
+	}
+};
+//#endregion
+//#region src/Exceptions/Exception.ts
+var Exception = class extends Error {
+	name;
+	constructor(message, options) {
+		super(message, options);
+		this.name = "Exception";
+	}
+};
+//#endregion
+//#region src/Exceptions/AppException.ts
+var AppException = class extends Exception {
+	errors = void 0;
+	statusCode;
+	constructor(message, statusCode = 400, options) {
+		super(message, options);
+		this.statusCode = statusCode;
+	}
+};
+//#endregion
+//#region src/Exceptions/RequestException.ts
+var RequestException = class RequestException extends AppException {
+	statusCode;
+	constructor(message, statusCode = 400, options) {
+		super(message, statusCode, options);
+		this.statusCode = statusCode;
+	}
+	/**
+	* 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(value, message, code = 404) {
+		if (!value) throw new RequestException(message, code);
+	}
+	/**
+	* 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(value, message, code = 404) {
+		return this.assertFound(value, message, code);
+	}
+	/**
+	* Asserts that a boolean condition is true. 
+	* 
+	* @param boolean 
+	* @param message 
+	* @param code 
+	* @throws {RequestException} Throws if the boolean condition is true.
+	*/
+	static abortIf(boolean, message, code) {
+		if (boolean) throw new RequestException(message, code);
+	}
+};
+//#endregion
+//#region src/utils/helpers.ts
+/**
+* Checks and asserts if target is a class
+* 
+* @param target 
+* @returns 
+*/
+const isClass = (target) => {
+	return typeof target === "function" && /^class\s/.test(Function.prototype.toString.call(target));
+};
+/**
+* Determine the number of items to return per page based on the provided query parameters.
+* 
+* @param query 
+* @returns 
+*/
+const perPage = (query) => {
+	const requestedPerPage = Number(query.limit ?? query.perPage ?? 15);
+	return Number.isFinite(requestedPerPage) && requestedPerPage > 0 ? Math.min(requestedPerPage, 50) : 15;
+};
+async function getModel(modelName) {
+	const resolveModelExport = (module, modelName) => {
+		if (!isModelModule(module)) return module;
+		return module.default ?? module[modelName] ?? module;
+	};
+	const isModelModule = (value) => typeof value === "object" && value !== null;
+	const modelPath = getUserConfig().paths?.models || "./src/models";
+	const model = resolveModelExport(await importFile(resolveRuntimeModule(path.join(path.isAbsolute(modelPath) ? modelPath : path.join(Arkstack.rootDir(), modelPath), modelName))), path.basename(modelName, path.extname(modelName)));
+	if (typeof model !== "function") throw new Error(`Model "${modelName}" not found`);
+	return model;
+}
+const initializeGlobalContext = async ({ Request, Response, Session } = {}) => {
+	try {
+		const { Request: Req, Response: Res, Session: Ses } = await import("@arkstack/http");
+		Session ??= new Ses();
+		Request ??= new Req();
+		Response ??= new Res();
+	} catch {
+		Session ??= new class {}();
+		Request ??= new class {}();
+		Response ??= new class {}();
+	}
+	globalThis.session ??= () => Session;
+	globalThis.request ??= () => Request;
+	globalThis.response ??= () => Response;
+};
+/**
+* Thows to abort the current request
+* 
+* @param message 
+* @param code 
+* @throws {RequestException}
+*/
+const abort = (message = "Request Aborted", code = 404) => {
+	RequestException.abortIf(true, message, code);
+};
+/**
+* Asserts that a boolean condition is true. 
+* 
+* @param boolean 
+* @param message 
+* @param code 
+* @throws {RequestException} Throws if the boolean condition is true.
+*/
+const abortIf = (boolean, message = "Request Aborted", code = 404) => {
+	RequestException.abortIf(boolean, message, code);
+};
+/**
+* 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.
+*/
+const assertFound = (value, message, code = 404) => {
+	if (!value) throw new RequestException(message, code);
+};
+//#endregion
+//#region src/utils/traits.ts
+/**
+* CRC32 implementation in TypeScript, adapted from https://stackoverflow.com/a/18639999
+* Note: This implementation is not cryptographically secure and is only used for generating 
+* unique identifiers for traits based on their factory function's string representation. 
+*/
+const crcTable = [];
+for (let n = 0; n < 256; n++) {
+	let c = n;
+	for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+	crcTable[n] = c;
+}
+const crc32 = (str) => {
+	let crc = -1;
+	for (let i = 0; i < str.length; i++) crc = crc >>> 8 ^ crcTable[(crc ^ str.charCodeAt(i)) & 255];
+	return (crc ^ -1) >>> 0;
+};
+const isCons = (fn) => typeof fn === "function" && !!fn.prototype && !!fn.prototype.constructor;
+const isArkormModelInstance = (value) => typeof value === "object" && value !== null && typeof value.constructor === "function" && typeof value.getAttribute === "function" && typeof value.setAttribute === "function";
+const isTypeFactory = (fn) => typeof fn === "function" && !fn.prototype && fn.length === 0;
+/**
+* API: generate trait (technical implementation)
+* 
+* @param args 
+*/
+function trait(...args) {
+	const factory = args.length === 2 ? args[1] : args[0];
+	const superTraits = args.length === 2 ? args[0] : void 0;
+	return {
+		id: crc32(factory.toString()),
+		symbol: Symbol("trait"),
+		factory,
+		superTraits
+	};
+}
+/**
+* utility function: add an additional invisible property to an object
+* 
+* @param cons 
+* @param field 
+* @param value 
+* @returns 
+*/
+const extendProperties = (cons, field, value) => Object.defineProperty(cons, field, {
+	value,
+	enumerable: false,
+	writable: false
+});
+const traitMethodRegistry = Symbol("trait-method-registry");
+const cloneMethodRegistry = (target) => {
+	const registry = target[traitMethodRegistry];
+	return new Map([...registry?.entries() ?? []].map(([name, methods]) => [name, [...methods]]));
+};
+const registerMethodScope = (target, base, ignored) => {
+	const registry = cloneMethodRegistry(base);
+	for (const name of Reflect.ownKeys(target)) {
+		if (ignored.has(name)) continue;
+		const method = Object.getOwnPropertyDescriptor(target, name)?.value;
+		if (typeof method !== "function") continue;
+		const methods = registry.get(name);
+		const previous = base?.[name];
+		if (methods) {
+			if (methods.at(-1) !== method) methods.push(method);
+			registry.set(name, methods);
+		} else if (typeof previous === "function" && previous !== method) registry.set(name, [previous, method]);
+	}
+	Object.defineProperty(target, traitMethodRegistry, {
+		configurable: false,
+		enumerable: false,
+		value: registry,
+		writable: false
+	});
+};
+/**
+* Registers conflicting trait methods
+* 
+* @param classInstance 
+* @param baseClass 
+*/
+const registerTraitMethods = (classInstance, baseClass) => {
+	registerMethodScope(classInstance.prototype, baseClass.prototype, new Set(["constructor"]));
+	registerMethodScope(classInstance, baseClass, new Set([
+		"length",
+		"name",
+		"prototype",
+		"arguments",
+		"caller"
+	]));
+};
+/**
+* Return every trait implementation for a method, bound to the supplied
+* instance or class. Methods are ordered from the base implementation to the
+* currently active trait implementation.
+* 
+* @param target 
+* @param name 
+* @returns 
+*/
+const getTraitMethods = (target, name) => {
+	return (((typeof target === "function" ? target : Object.getPrototypeOf(target))?.[traitMethodRegistry])?.get(name) ?? []).map((method) => method.bind(target));
+};
+/**
+* Invoke every trait implementation for a method in registration order.
+* 
+* @param target 
+* @param name 
+* @param args 
+* @returns 
+*/
+const callTraitMethods = (target, name, ...args) => {
+	const methods = getTraitMethods(target, name);
+	if (methods.length === 0) {
+		console.warn(`No conflicting trait methods found for "${String(name)}".`);
+		return [];
+	}
+	return methods.map((method) => method(...args));
+};
+/**
+* utility function: get raw trait
+* 
+* @param x 
+* @returns 
+*/
+const rawTrait = (x) => isTypeFactory(x) ? x() : x;
+/**
+* utility function: derive a trait
+* 
+* @param trait$ 
+* @param baseClass 
+* @param derived 
+* @returns 
+*/
+const deriveTrait = (trait$, baseClass, derived) => {
+	const trait = rawTrait(trait$);
+	if (trait === void 0 || trait === null || typeof trait.id !== "number") throw new Error("use(): received an undefined or invalid trait. This usually means a circular import — the trait module had not finished initializing when use() ran. Avoid importing models at the top level of trait modules, or break the import cycle.");
+	let classInstance = baseClass;
+	if (!derived.has(trait.id)) {
+		derived.set(trait.id, true);
+		if (trait.superTraits !== void 0) for (const superTrait of reverseTraitList(trait.superTraits)) classInstance = deriveTrait(superTrait, classInstance, derived);
+		const base = classInstance;
+		classInstance = trait.factory(classInstance);
+		registerTraitMethods(classInstance, base);
+		extendProperties(classInstance, "id", crc32(trait.factory.toString()));
+		extendProperties(classInstance, trait.symbol, true);
+	}
+	return classInstance;
+};
+/**
+* utility function: get reversed trait list
+* 
+* @param traits 
+* @returns 
+*/
+const reverseTraitList = (traits) => traits.slice().reverse();
+function use(...args) {
+	const withMethodHelpers = args[0] === true;
+	const traits = withMethodHelpers ? args.slice(1) : args;
+	if (traits.length === 0) throw new Error("invalid number of parameters (expected one or more traits)");
+	let classInstance;
+	let lot;
+	const last = traits[traits.length - 1];
+	if (isCons(last) && !isTypeFactory(last)) {
+		classInstance = last;
+		lot = traits.slice(0, -1);
+	} else if (isArkormModelInstance(last)) {
+		classInstance = last.constructor;
+		lot = traits.slice(0, -1);
+	} else {
+		classInstance = class ROOT {};
+		lot = traits;
+	}
+	const derived = /* @__PURE__ */ new Map();
+	for (const trait of reverseTraitList(lot)) classInstance = deriveTrait(trait, classInstance, derived);
+	if (withMethodHelpers) classInstance = class TraitMethodEnabled extends classInstance {
+		getTraitMethods(name) {
+			return getTraitMethods(this, name);
+		}
+		callTraitMethods(name, ...args) {
+			return callTraitMethods(this, name, ...args);
+		}
+		static getTraitMethods(name) {
+			return getTraitMethods(this, name);
+		}
+		static callTraitMethods(name, ...args) {
+			return callTraitMethods(this, name, ...args);
+		}
+	};
+	return classInstance;
+}
+/**
+* API: type guard for checking whether class instance is derived from a trait
+* 
+* @param instance 
+* @param trait 
+* @returns 
+*/
+function uses(instance, trait) {
+	if (typeof instance !== "object" || instance === null) return false;
+	let obj = instance;
+	if (isCons(trait) && !isTypeFactory(trait)) return instance instanceof trait;
+	const idTrait = (isTypeFactory(trait) ? trait() : trait)["id"];
+	while (obj) {
+		if (Object.hasOwn(obj, "constructor")) {
+			if ((obj.constructor["id"] ?? 0) === idTrait) return true;
+		}
+		obj = Object.getPrototypeOf(obj);
+	}
+	return false;
+}
+//#endregion
+export { Hash as _, use as a, abortIf as c, initializeGlobalContext as d, isClass as f, Exception as g, AppException as h, trait as i, assertFound as l, RequestException as m, crc32 as n, uses as o, perPage as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, Encryption as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.14.19",
+  "version": "0.14.21",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -28,23 +28,28 @@
   },
   "exports": {
     ".": "./dist/index.js",
+    "./faker": "./dist/faker.js",
     "./utils": "./dist/utils/index.js",
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "jiti": "^2.7.0",
+    "@pictwo/faker": "^1.1.0",
     "bcryptjs": "^3.0.3",
     "chalk": "^5.6.2",
     "detect-port": "^2.1.0",
     "dotenv": "^17.4.2",
+    "jiti": "^2.7.0",
     "otpauth": "^9.5.1",
     "pino": "^10.3.1"
   },
   "peerDependencies": {
     "@h3ravel/support": "^2.2.0",
     "arkormx": "^2.10.1",
-    "@arkstack/foundry": "^0.14.19",
-    "@arkstack/contract": "^0.14.19"
+    "@arkstack/contract": "^0.14.21",
+    "@arkstack/foundry": "^0.14.21"
+  },
+  "optionalDependencies": {
+    "@faker-js/faker": "^10.4.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",