@arkstack/common 0.5.1 → 0.5.3

package/dist/utils-DLifcZWV.js

@@ -0,0 +1,452 @@
+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;
+	/**
+	* Custom properties merged into the error response payload.
+	*
+	* When set, these are merged over the standard error payload (`status`,
+	* `code`, `message`, …), letting a subclass add fields to — or reshape — the
+	* returned error body.
+	*
+	* @example
+	* ```ts
+	* class PaymentException extends AppException {
+	*   body = { error_code: 'PAYMENT_FAILED', retryable: true }
+	* }
+	* ```
+	*/
+	body;
+	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,8 +1,8 @@
 {
   "name": "@arkstack/common",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
-  "description": "Shared foundations and core utilities for Arkstack applications and packages.",
+  "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
   "repository": {
     "type": "git",
@@ -20,29 +20,41 @@
     "arkstack"
   ],
   "files": [
-    "dist"
+    "dist",
+    "resources"
   ],
   "publishConfig": {
     "access": "public"
   },
   "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"
+    "pino": "^10.3.1",
+    "selfsigned": "^2.4.1"
   },
   "peerDependencies": {
-    "@h3ravel/support": "^0.15.11",
-    "arkormx": "^2.0.11"
+    "@h3ravel/support": "^2.2.0",
+    "arkormx": "^2.10.1",
+    "@arkstack/contract": "^0.5.3",
+    "@arkstack/foundry": "^0.5.3"
+  },
+  "optionalDependencies": {
+    "@faker-js/faker": "^10.4.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",
+    "test": "vitest",
     "version:patch": "pnpm version patch"
   }
 }

package/resources/views/error.edge

@@ -0,0 +1,199 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{ code }} | {{ title }}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Syne:wght@700;800&family=DM+Mono:wght@400;500&display=swap"
+        rel="stylesheet" />
+    <style>
+        *,
+        *::before,
+        *::after {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+
+        /* ── Dark theme (default) ── */
+        :root {
+            --gold-light: #f0c040;
+            --gold-mid: #c9960c;
+            --bg: #0b0c0e;
+            --bg-card: #111317;
+            --bg-stack: #0d0f12;
+            --border: rgba(201, 150, 12, 0.18);
+            --border-err: rgba(220, 60, 60, 0.22);
+            --text: #f5f0e8;
+            --muted: #7a7567;
+            --red: #e05252;
+            --radius: 10px;
+            --pre-color: #c0a888;
+        }
+
+        /* ── Light theme ── */
+        [data-theme="light"] {
+            --gold-light: #a06800;
+            --gold-mid: #8a5a00;
+            --bg: #f5f3ef;
+            --bg-card: #ffffff;
+            --bg-stack: #faf8f5;
+            --border: rgba(160, 104, 0, 0.16);
+            --border-err: rgba(180, 40, 40, 0.18);
+            --text: #1a1714;
+            --muted: #9a9080;
+            --red: #c0392b;
+            --pre-color: #6a5040;
+        }
+
+        /* ── OS preference fallback (no JS) ── */
+        @media (prefers-color-scheme: light) {
+            :root:not([data-theme="dark"]) {
+                --gold-light: #a06800;
+                --gold-mid: #8a5a00;
+                --bg: #f5f3ef;
+                --bg-card: #ffffff;
+                --bg-stack: #faf8f5;
+                --border: rgba(160, 104, 0, 0.16);
+                --border-err: rgba(180, 40, 40, 0.18);
+                --text: #1a1714;
+                --muted: #9a9080;
+                --red: #c0392b;
+                --pre-color: #6a5040;
+            }
+        }
+
+        html,
+        body {
+            min-height: 100vh;
+            background: var(--bg);
+            color: var(--text);
+            font-family: 'DM Mono', monospace;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            padding: 2rem 1rem;
+            transition: background 0.25s, color 0.25s;
+        }
+
+        .page {
+            max-width: 620px;
+            width: 100%;
+            display: flex;
+            flex-direction: column;
+            align-items: flex-start;
+        }
+
+        /* ── Top bar ── */
+        .topbar {
+            width: 100%;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            margin-bottom: 3rem;
+        }
+
+        /* ── Error heading ── */
+        .error-code {
+            font-family: 'Syne', sans-serif;
+            font-size: 3.5rem;
+            font-weight: 800;
+            line-height: 1;
+            letter-spacing: -0.04em;
+            color: var(--red);
+            margin-bottom: 0.5rem;
+            opacity: 0.9;
+        }
+
+        .error-title {
+            font-family: 'Syne', sans-serif;
+            font-size: 1.2rem;
+            font-weight: 700;
+            color: var(--text);
+            margin-bottom: 0.6rem;
+        }
+
+        .error-message {
+            font-size: 0.78rem;
+            color: var(--muted);
+            line-height: 1.7;
+            margin-bottom: 2rem;
+        }
+
+        /* ── Divider ── */
+        .divider {
+            width: 100%;
+            height: 1px;
+            background: linear-gradient(90deg, var(--border-err), transparent);
+            margin-bottom: 2rem;
+        }
+
+        /* ── Stack trace ── */
+        .stack-label {
+            font-size: 0.65rem;
+            letter-spacing: 0.14em;
+            text-transform: uppercase;
+            color: var(--muted);
+            margin-bottom: 0.65rem;
+        }
+
+        .stack-block {
+            width: 100%;
+            background: var(--bg-stack);
+            border: 1px solid var(--border-err);
+            border-radius: var(--radius);
+            padding: 1.1rem 1.25rem;
+            position: relative;
+            overflow: hidden;
+            transition: background 0.25s, border-color 0.25s;
+        }
+
+        .stack-block::before {
+            content: '';
+            position: absolute;
+            top: 0;
+            left: 0;
+            right: 0;
+            height: 2px;
+            background: linear-gradient(90deg, var(--red), transparent);
+        }
+
+        .stack-block pre {
+            font-family: 'DM Mono', monospace;
+            font-size: 0.72rem;
+            color: var(--pre-color);
+            line-height: 1.85;
+            overflow-x: auto;
+            white-space: pre;
+        }
+    </style>
+</head>
+
+<body>
+    <div class="page">
+        <div class="error-code">{{ code }}</div>
+        <div class="error-title">{{ title }}</div>
+        <p class="error-message">{{ message }}</p>
+
+        <div class="divider"></div>
+
+        @if(stack)
+        <div class="stack-label">Stack Trace</div>
+        <div class="stack-block">
+            <pre>{{ stack }}</pre>
+        </div>
+        @end
+
+    </div>
+
+    <script>
+        const root = document.documentElement;
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        root.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
+    </script>
+</body>
+
+</html>