arkos 2.0.0-next.2 → 2.0.0-next.21

package/README.md

@@ -1,4 +1,4 @@
-![Header Image](https://www.arkosjs.com/img/arkos-readme-header.webp?v=2)
+![Header Image](https://www.arkosjs.com/img/arkos-readme-header.webp?v=4)
 
 <div align="center">
 
@@ -15,50 +15,45 @@
 <p>A tool for backend developers and teams who ship software with complex business logic under tight deadlines</p>
 </div>
 
----
-
 <div align="center">
 
 **[Installation](https://www.arkosjs.com/docs/getting-started/installation)** •
-**[Documentation](https://arkosjs.com/docs/intro)** •
+**[Documentation](https://arkosjs.com/docs)** •
 **[Website](https://arkosjs.com)** •
+**[Tutorial](https://arkosjs.com/learn)** •
 **[GitHub](https://github.com/uanela/arkos)** •
 **[Blog](https://www.arkosjs.com/blog)** •
 **[Npm](https://www.npmjs.com/package/arkos)**
 
 </div>
 
----
+## Quick Start
 
-## Why Arkos?
+```bash
+npm create arkos@latest my-project
+```
 
-Every line of boilerplate code is a missed opportunity for innovation. Arkos.js gives developers back their time so they can focus on building what truly matters—**the core business logic**.
+Your new project already has JWT auth, customizable CRUD routes, Swagger docs at `/api/docs`, file uploads, validation, and a full security middleware stack. Understand the generated [Project Structure](https://www.arkosjs.com/docs/getting-started/project-structure).
 
-**Perfect for:**
+## Your Entry Point
 
-- Backend developers shipping complex features under tight deadlines
-- Teams who want to scale fast without reinventing standard patterns
-- Projects that need production-ready auth, validation, and docs from day one
+```typescript
+// src/app.ts
+import arkos from "arkos";
+import postRouter from "@/src/modules/post/post.router"; // custom router
 
-## Quick Start
+const app = arkos();
 
-Get started with Arkos.js in seconds:
+app.use(postRouter);
 
-```bash
-pnpm create arkos@latest my-project
+app.listen();
 ```
 
-**That's it!** You now have:
+Arkos replaces the Express `app` — but it _is_ Express under the hood. You can still use `app.use()`, custom middleware, and raw Express code wherever you need it.
 
-- Production-ready REST API
-- JWT authentication
-- Auto-generated Swagger docs at `/api/docs`
-- File upload handling
-- Input validation
+## Automatic CRUD: One Model, Full REST Endpoints
 
-## See It In Action
-
-**1. Define your Prisma model:**
+**Define The Prisma model:**
 
 ```prisma
 model Post {
@@ -66,162 +61,145 @@ model Post {
   title     String
   content   String
   authorId  String
-  author    User   @relation(fields: [authorId], references: [id])
+  author    User     @relation(fields: [authorId], references: [id])
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 }
 ```
 
-**2. Get instant REST endpoints:**
+**Get a full REST API — instantly:**
 
 ```
-POST   /api/posts           Create a new post
-GET    /api/posts           List all posts
-GET    /api/posts/:id       Get a specific post
-PATCH  /api/posts/:id       Update a post
-DELETE /api/posts/:id       Delete a post
+POST   /api/posts        Create a post
+GET    /api/posts        List all posts
+GET    /api/posts/:id    Get a post
+PATCH  /api/posts/:id    Update a post
+DELETE /api/posts/:id    Delete a post
 ```
 
-All with built-in **authentication**, **validation**, and **documentation**. **Zero boilerplate.**
+Authenticated, validated, and documented. Zero boilerplate.
 
-**3. Add custom business logic with interceptors:**
+## Creating a Router Beyond Express
 
 ```typescript
-import { ArkosRequest, ArkosResponse, ArkosNextFunction } from "arkos";
-import { AppError } from "arkos/error-handler";
-
-export const beforeCreateOne = [
-    async (req: ArkosRequest, res: ArkosResponse, next: ArkosNextFunction) => {
-        // Add custom validation
-        if (req.body.title.length < 5) {
-            throw new AppErr("Title is too short", 400, "TitleTooShort");
-        }
-
-        // Enrich data
-        req.body.slug = req.body.title.toLowerCase().replace(/\s/g, "-");
-        req.body.authorId = req.user.id;
-
-        next();
-    },
-];
+// src/modules/post/post.router.ts
+import { ArkosRouter } from "arkos";
+import CreatePostSchema from "@/src/modules/post/schemas/create-post.schema";
+import postService from "@/src/modules/post/post.service";
+import postPolicy from "@/src/modules/post/post.policy"; // Authorization component
+
+const postRouter = ArkosRouter({ prefix: "/api/posts" });
+
+postRouter.post(
+  {
+    path: "/", // auto registered into openapi
+    authentication: postPolicy.Create, // Authentication and authorization with RBAC
+    validation: { body: CreatePostSchema }, // auto documented into openapi requestBody
+  },
+  async (req, res) => {
+    const post = await postService.createOne(req.body); // no error handling need, arkos already handles it
+    res.json({ data: post });
+  }
+);
+
+export default postRouter;
 ```
 
-## What You Get Out of the Box
-
-### **Enterprise-Ready Authentication**
-
-- JWT token management with secure refresh tokens
-- Password hashing with bcrypt
-- Role-based access control (RBAC)
-- Production-ready from day one
+See more about the enhanced express-based router (ArkosRouter) at [ArkosRouter Guide](https://www.arkosjs.com/docs/core-concepts/components/routers).
 
-### **Smart Data Validation**
+## Define Permissions Once, Guard Everywhere
 
-- Automatic validation from Prisma models
-- Zod schema integration
-- Class-validator support
-- Zero configuration required
-
-### **Bulletproof Security Stack**
-
-- Rate limiting to prevent abuse
-- CORS configuration
-- Input sanitization with helmet.js
-- Comprehensive error handling
-
-### **Self-Documenting APIs**
-
-- Auto-generated OpenAPI/Swagger specifications
-- Beautiful interactive Scalar UI
-- Auto-sync with your routes
-- JSON schemas from Zod or Prisma models
-
-### **Intelligent File Processing**
-
-- Multer-powered file uploads
-- Automatic image and video optimization
-- Smart type validation
-- Easy local storage configuration
-
-### **Effortless Email Integration**
-
-- Built-in Nodemailer service
-- Template support
-- Clean, simple API
-- Just focus on your content
-
-### **Powerful Interceptors**
+```typescript
+// src/modules/post/post.policy.ts
+import { ArkosPolicy } from "arkos";
 
-- Before/after request hooks
-- Custom validation logic
-- Data transformation
-- Flexible middleware system
+const postPolicy: ArkosPolicy<"post"> = ArkosPolicy("post");
 
-### **Unmatched Prisma Integration**
+postPolicy.rule("Create", ["Writer", "Admin"]);
+postPolicy.rule("View", ["Writer", "Admin", "User"]);
 
-- Seamless ORM integration
-- Automatic relation handling
-- Write less Prisma, build more data
-- Built on Prisma's rock-solid foundation
+export default postPolicy;
+```
 
-## Arkos vs Traditional Setup
+Define who can do what, once, per resource. Arkos enforces it across every route that references the policy — no scattered middleware, no repeated role checks.
 
-| Task                     | Traditional Approach        | With Arkos             |
-| ------------------------ | --------------------------- | ---------------------- |
-| Setup JWT authentication | 2-3 hours of config         | ✅ Built-in & ready    |
-| Create CRUD routes       | 30 min per model            | ✅ Auto-generated      |
-| Add input validation     | Manual for each endpoint    | ✅ Zod/Class-validator |
-| Setup API documentation  | Install + configure Swagger | ✅ Auto-generated      |
-| Configure file uploads   | Multer setup + validation   | ✅ Ready to use        |
-| Add security middleware  | Research + implement        | ✅ Pre-configured      |
-| **Total setup time**     | **~8-12 hours**             | **~5 minutes**         |
+**Customize CRUD Routes just like normal router:**
 
-## Features
+```typescript
+// src/modules/post/post.router.ts
+import { ArkosRouter, RouteHook } from "arkos";
+import postPolicy from "@/src/modules/post/post.policy";
+import UpdatePostSchema from "@/src/modules/post/post.schema";
+
+export const hook: RouteHook<"prisma"> = {
+  findMany: { authentication: false }, // Making GET /api/posts public
+  createOne: { authentication: postPolicy.Create },
+  updateOne: {
+    authentication: postPolicy.Update,
+    validation: { body: UpdatePostSchema },
+  },
+  deleteOne: { authentication: postPolicy.Delete },
+};
+
+const postRouter = ArkosRouter({ prefix: "/api/posts" });
+
+export default postRouter;
+```
 
-- **Automatic API Generation** - Instantly create RESTful routes from Prisma models
-- **Built-in Authentication** - JWT-based authentication with minimal setup
-- **Express Middlewares** - Pre-configured security, parsing, and error handling
-- **Data Validation** - Input validation and transformation capabilities
-- **Prisma Integration** - Seamless database management with relation fields support
-- **File Upload & Optimization** - Efficient handling of images, videos, and documents
-- **Interceptors Middlewares** - Customize request/response flow with hooks
-- **Nodemailer Integration** - Easy email sending functionality
-- **Swagger API Documentation** - Automatically generate API documentation
+Your auto-generated CRUD routes accept the same config as any ArkosRouter route — authentication, validation, rate limiting, all in one place.
 
-**BETA VERSION**
+**Add business logic exactly where you need it:**
 
-## Trusted By Developers Building Daily
+```typescript
+// src/modules/post/post.interceptor.ts
+import { ArkosRequest, ArkosResponse, ArkosNextFunction } from "arkos";
+import { BadRequestError } from "arkos/error-handler";
 
-> "Arkos.js changed how I work on the backend: with a Prisma model I already get CRUD routes, auth, and validation out-of-the-box — I saved a lot of time and could focus on business logic."  
-> **— Gelson Matavela, Founder / Grupo Vergui**
+export const beforeCreateOne = [
+  async (req: ArkosRequest, res: ArkosResponse, next: ArkosNextFunction) => {
+    if (req.body.title.length < 5)
+      throw new BadRequestError("Title is too short", "TitleTooShort");
+
+    req.body.slug = req.body.title.toLowerCase().replace(/\s/g, "-");
+    req.body.authorId = req.user.id;
+    next();
+  },
+];
+```
 
-> "It removes boilerplate and provides a clean structure to build products. Built-in auth is powerful and ready. Automatic CRUD and docs save time, while interceptors allow flexible business logic."  
-> **— Augusto Domingos, Tech Lead / DSAI For Moz**
+Name the file, export the hook, and Arkos picks it up automatically. No registration needed.
 
-> "With Arkos.js, I can build backends in just a few minutes. It removes the boilerplate and lets me focus entirely on the core logic. Fast, simple, and incredibly productive."  
-> **— Niuro Langa, Software Developer / SparkTech**
+## What You Stop Building From Scratch
 
-[See more testimonials →](https://arkosjs.com)
+| What you'd normally write                | What Arkos gives you              |
+| ---------------------------------------- | --------------------------------- |
+| JWT setup, refresh tokens, bcrypt        | ✅ Built-in auth system           |
+| 5 route handlers per Prisma model        | ✅ Auto-generated CRUD            |
+| Zod/CV schemas per endpoint              | ✅ Auto generate from your models |
+| Swagger config + schema upkeep           | ✅ Auto-generated OpenAPI docs    |
+| Multer setup + file type validation      | ✅ File upload system             |
+| Rate limiting, CORS, Helmet, compression | ✅ Pre-configured security stack  |
+| **Total setup time**                     | **~5 minutes vs ~8–12 hours**     |
 
 ## Documentation
 
-For comprehensive guides, API reference, and examples, visit our [official documentation](https://arkosjs.com/docs/intro).
+For comprehensive guides, API reference, and examples, visit our [official documentation](https://arkosjs.com/docs).
 
 **Quick Links:**
 
-- [Getting Started Guide](https://arkosjs.com/docs/intro)
-- [Authentication Setup](https://arkosjs.com/docs/core-concepts/authentication-system)
-- [Using Interceptors](https://arkosjs.com/docs/core-concepts/interceptors)
-- [File Uploads](https://arkosjs.com/docs/core-concepts/file-uploads)
-- [Validation](https://arkosjs.com/docs/core-concepts/request-data-validation)
-- [Email Service](https://arkosjs.com/docs/core-concepts/sending-emails)
+- [Getting Started Guide](https://arkosjs.com/docs)
+- [Authentication Setup](https://arkosjs.com/docs/core-concepts/authentication/setup)
+- [Using Interceptors](https://arkosjs.com/docs/core-concepts/components/interceptors)
+- [File Uploads](https://arkosjs.com/docs/guides/file-handling/file-uploads/setup)
+- [Validation](https://arkosjs.com/docs/guides/validation/setup)
+- [Email Service](https://arkosjs.com/docs/guides/email-service)
 
 ## Getting Nightly Updates
 
 You can get the latest features we're testing before releasing them:
 
 ```bash
-pnpm create arkos@canary my-project
+pnpm create arkos@next my-project
 ```
 
 ## Built With
@@ -234,32 +212,55 @@ Arkos.js is built on top of industry-leading tools:
 
 ## Support & Contributing
 
-- **Documentation:** [arkosjs.com/docs](https://arkosjs.com/docs/intro)
+- **Documentation:** [arkosjs.com/docs](https://arkosjs.com/docs)
 - **Bug Reports:** [GitHub Issues](https://github.com/uanela/arkos/issues)
 - **Feature Requests:** Open a GitHub issue
 - **Contact:** [uanelaluiswayne@gmail.com](mailto:uanelaluiswayne@gmail.com)
 
 Contributions are welcome! We appreciate all contributions, from bug fixes to new features.
 
+## What Developers Say
+
+> "Arkos.js changed how I work on the backend: with a Prisma model I already get CRUD routes, auth, and validation out-of-the-box — I saved a lot of time and could focus on business logic."
+>
+> **— Gelson Matavela, Founder / Grupo Vergui**
+
+> "It removes boilerplate and provides a clean structure to build products. Built-in auth is powerful and ready. Automatic CRUD and docs save time, while interceptors allow flexible business logic."
+>
+> **— Augusto Domingos, Tech Lead / DSAI For Moz**
+
+> "With Arkos.js, I can build backends in just a few minutes. It removes the boilerplate and lets me focus entirely on the core logic. Fast, simple, and incredibly productive."
+>
+> **— Niuro Langa, Software Developer / SparkTech**
+
+[See more testimonials →](https://arkosjs.com)
+
+## Philosophy
+
+Arkos sits between minimal frameworks like Express/Fastify and opinionated ones like NestJS/AdonisJS. It doesn't ask you to learn a new paradigm — it enhances the one most Node.js developers already use, by automating everything that's standardized and staying out of the way everywhere else.
+
+Inspired by how Django and Laravel work in their ecosystems: batteries included, nothing forced on you.
+
+> The name "Arkos" comes from the Greek word **ἀρχή** _(Arkhē)_, meaning "beginning" or "foundation".
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
----
-
 <div align="center">
 
 **[Installation](https://www.arkosjs.com/docs/getting-started/installation)** •
-**[Documentation](https://arkosjs.com/docs/intro)** •
+**[Documentation](https://arkosjs.com/docs)** •
 **[Website](https://arkosjs.com)** •
+**[Tutorial](https://arkosjs.com/learn)** •
 **[GitHub](https://github.com/uanela/arkos)** •
 **[Blog](https://www.arkosjs.com/blog)** •
 **[Npm](https://www.npmjs.com/package/arkos)**
 
 Built with ❤️ by [Uanela Como](https://github.com/uanela) and contributors
 
----
-
 _The name "Arkos" comes from the Greek word "ἀρχή" (Arkhē), meaning "beginning" or "foundation", reflecting our goal of providing a solid foundation for backend development._
 
 </div>
+
+

package/cli.js

@@ -1,42 +1,40 @@
 #!/usr/bin/env node
 (async () => {
-  const { join } = await import("path");
+  const { join, dirname } = await import("path");
   const { existsSync, readFileSync } = await import("fs");
   const { spawn } = await import("child_process");
+  const { fileURLToPath } = await import("node:url");
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
 
   const pkgPath = join(process.cwd(), "package.json");
   let useEsm = false;
-
   if (existsSync(pkgPath)) {
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
     useEsm = pkg.type === "module";
   }
-
-  const tsSrc = join(process.cwd(), "tsconfig.json");
   const entryPoint = join(
     __dirname,
     `dist/${useEsm ? "esm" : "cjs"}/utils/cli/index.js`
   );
-  const useTs = existsSync(tsSrc);
-
   const args = [
-    ...(useTs ? ["--experimental-strip-types"] : []),
+    ...["--import", "tsx"],
     entryPoint,
     ...process.argv.slice(2),
   ];
-
   process.env.NO_CLI = "true";
+  process.env.FORCE_COLOR = "3";
+  process.env.__ARKOS_CLI = "true";
   const child = spawn(process.execPath, args, {
     stdio: ["inherit", "inherit", "pipe"],
   });
   child.stderr.on("data", (data) => {
     const str = data.toString();
-    if (
-      !str.includes("DeprecationWarning") &&
-      !str.includes("npm warn") &&
-      !str.includes("ExperimentalWarning")
-    )
+    if (!str.includes("ExperimentalWarning: Type Stripping is an experimental"))
       process.stderr.write(data);
   });
   child.on("exit", (code) => process.exit(code ?? 0));
 })();
+
+

package/dist/esm/app.js

@@ -1,33 +1,29 @@
 import "./utils/helpers/arkos-config.helpers.js";
 import express from "express";
 import setupApp from "./utils/setup-app.js";
-import initializeApp from "./utils/initialize-app.js";
+import initializeApp, { addGlobalErrorHandler } from "./utils/initialize-app.js";
 import { logAppStartup } from "./server.js";
 import runtimeCliCommander from "./utils/cli/utils/runtime-cli-commander.js";
 import { Server } from "http";
 import ExitError from "./utils/helpers/exit-error.js";
-import loadableRegistry from "./components/arkos-loadable-registry/index.js";
+import { applyArkosRouterProxy } from "./utils/arkos-router/utils/helpers/apply-arkos-router-proxy.js";
+import { isProduction, validateArkosConfig, } from "./utils/helpers/arkos-config.helpers.js";
+export const app = express();
 let appServer;
-const docsLink = "https://www.arkosjs.com/docs/core-concepts/routing/setup#setting-up-your-app";
+export const docsLink = "https://www.arkosjs.com/docs/core-concepts/routing/setup#setting-up-your-app";
 let instanciated = false;
-export function arkos() {
+export let state = "idle";
+export default function arkos() {
+    if (process.env.__ARKOS_CLI !== "true")
+        throw ExitError(`Arkos.js application must be started the built-in cli ${isProduction() ? "'arkos start' in production" : `'arkos dev' in development`} see https://www.arkosjs.com/docs/getting-started/installation#7-set-up-packagejson-scripts`);
     if (instanciated)
         throw ExitError(`arkos() must be called only once, see ${docsLink}`);
-    const app = express();
+    const app = applyArkosRouterProxy(express(), {}, "app");
     setupApp(app);
     instanciated = true;
-    let state = "idle";
-    app.load = (...items) => {
-        if (state !== "idle")
-            throw ExitError(`app.load() must be called before app.${state === "listening" ? "listen" : "build"}(), see ${docsLink}`);
-        if (Array.isArray(items[0]))
-            items = items[0];
-        items = Array.isArray(items) ? items : [items];
-        items.forEach((item) => loadableRegistry.register(item));
-        return app;
-    };
     function loadApp() {
-        const _app = initializeApp(app);
+        let _app = initializeApp(app);
+        _app = addGlobalErrorHandler(_app);
         if (process.env.CLI_COMMAND)
             runtimeCliCommander.handle();
         return _app;
@@ -48,6 +44,7 @@ export function arkos() {
         return cb || function () { };
     };
     app.listen = async function (...args) {
+        process.env.__ARKOS_SERVER_LISTENER = "arkos";
         if (state === "listening")
             throw ExitError(`app.listen() must only be called once, see ${docsLink}`);
         if (state === "building")
@@ -56,8 +53,12 @@ export function arkos() {
             state = "listening";
             loadApp();
         }
+        validateArkosConfig();
         const port = Number(process.env.__PORT || process.env.PORT || "8000");
         const host = process.env.__HOST || process.env.HOST || "0.0.0.0";
+        process.send?.({ started: true });
+        if (process.env.__SKIP_LISTEN == "true")
+            return appServer;
         if (args?.length === 0 || typeof args[0] === "function")
             appServer = originalListen(port, host, defaultCb(port, host, args[0]));
         else if (args[0] instanceof Server || typeof args[0] === "object")

package/dist/esm/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"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","sourcesContent":["import \"./utils/helpers/arkos-config.helpers\";\nimport express, { Express } from \"express\";\nimport setupApp from \"./utils/setup-app\";\nimport { Arkos, ArkosLoadable } from \"./types/arkos\";\nimport initializeApp from \"./utils/initialize-app\";\nimport { logAppStartup } from \"./server\";\nimport runtimeCliCommander from \"./utils/cli/utils/runtime-cli-commander\";\nimport { IncomingMessage, Server, ServerResponse } from \"http\";\nimport ExitError from \"./utils/helpers/exit-error\";\nimport loadableRegistry from \"./components/arkos-loadable-registry\";\n\nlet appServer: Server<typeof IncomingMessage, typeof ServerResponse>;\nconst docsLink =\n  \"https://www.arkosjs.com/docs/core-concepts/routing/setup#setting-up-your-app\";\nlet instanciated = false;\n\n/**\n * Creates and configures an Arkos application instance.\n *\n * Arkos extends Express with a small set of methods for registering routers,\n * loading route/service hooks, and booting the application. All Arkos-specific\n * setup (`app.build()`) must happen before the app starts\n * accepting requests.\n *\n * @example\n * ```ts\n * // Simple setup\n * import arkos from \"arkos\";\n *\n * const app = arkos();\n *\n * app.use(reportsRouter);\n *\n * app.listen();\n * ```\n *\n * @example\n * ```ts\n * // Custom HTTP server (e.g. for WebSockets)\n * import arkos from \"arkos\";\n * import http from \"http\";\n *\n * const app = arkos();\n *\n * app.use(reportsRouter);\n *\n * async function start() {\n *  await app.build();\n *\n *  const server = http.createServer(app);\n *  app.listen(server)\n * }\n * main()\n * ```\n *\n * @see {@link https://www.arkosjs.com/docs/core-concepts/routing/setup}\n */\nexport function arkos(): Arkos {\n  if (instanciated)\n    throw ExitError(`arkos() must be called only once, see ${docsLink}`);\n\n  const app = express() as any as Arkos;\n  setupApp(app);\n  instanciated = true;\n\n  type AppState = \"idle\" | \"building\" | \"built\" | \"listening\";\n  let state: AppState = \"idle\";\n\n  app.load = (...items: ArkosLoadable[]) => {\n    if (state !== \"idle\")\n      throw ExitError(\n        `app.load() must be called before app.${state === \"listening\" ? \"listen\" : \"build\"}(), see ${docsLink}`\n      );\n\n    if (Array.isArray(items[0])) items = items[0];\n    items = Array.isArray(items) ? items : [items];\n\n    items.forEach((item) => loadableRegistry.register(item));\n    return app;\n  };\n\n  function loadApp() {\n    const _app = initializeApp(app);\n    if (process.env.CLI_COMMAND) runtimeCliCommander.handle();\n    return _app;\n  }\n\n  app.build = function () {\n    if (state === \"built\" || state === \"building\")\n      throw ExitError(`app.build() must only be called once, see ${docsLink}`);\n    if (state === \"listening\")\n      throw ExitError(\n        `app.build() must be called before app.listen(), see ${docsLink}`\n      );\n\n    state = \"building\";\n    const _app = loadApp();\n    state = \"built\";\n    return _app;\n  };\n\n  const originalListen = app.listen.bind(app) as any as Express[\"listen\"];\n  type UserCallback = (err?: Error) => void;\n\n  const defaultCb = (\n    port: number | string,\n    host: string,\n    cb?: UserCallback\n  ) => {\n    logAppStartup(port, host);\n    return cb || function () {};\n  };\n\n  app.listen = async function (...args): Promise<Server> {\n    if (state === \"listening\")\n      throw ExitError(`app.listen() must only be called once, see ${docsLink}`);\n    if (state === \"building\")\n      throw ExitError(\n        `app.build() must be awaited before calling app.listen(), see ${docsLink}`\n      );\n\n    if (state === \"idle\") {\n      state = \"listening\";\n      loadApp();\n    }\n\n    const port = Number(process.env.__PORT || process.env.PORT || \"8000\");\n    const host = process.env.__HOST! || process.env.HOST || \"0.0.0.0\";\n\n    if ((args as any)?.length === 0 || typeof args[0] === \"function\")\n      appServer = originalListen(\n        port,\n        host,\n        defaultCb(port, host, args[0] as UserCallback)\n      );\n    else if (args[0] instanceof Server || typeof args[0] === \"object\")\n      appServer = args[0].listen(\n        port,\n        host,\n        defaultCb(port, host, args[1] as UserCallback)\n      );\n\n    return appServer;\n  };\n\n  return app;\n}\n\nexport function getAppServer() {\n  return appServer;\n}\n"]}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"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","sourcesContent":["import \"./utils/helpers/arkos-config.helpers\";\nimport express, { Express } from \"express\";\nimport setupApp from \"./utils/setup-app\";\nimport { Arkos } from \"./types/arkos\";\nimport initializeApp, { addGlobalErrorHandler } from \"./utils/initialize-app\";\nimport { logAppStartup } from \"./server\";\nimport runtimeCliCommander from \"./utils/cli/utils/runtime-cli-commander\";\nimport { IncomingMessage, Server, ServerResponse } from \"http\";\nimport ExitError from \"./utils/helpers/exit-error\";\nimport { applyArkosRouterProxy } from \"./utils/arkos-router/utils/helpers/apply-arkos-router-proxy\";\nimport {\n  isProduction,\n  validateArkosConfig,\n} from \"./utils/helpers/arkos-config.helpers\";\nexport const app: express.Express = express();\n\nlet appServer: Server<typeof IncomingMessage, typeof ServerResponse>;\nexport const docsLink =\n  \"https://www.arkosjs.com/docs/core-concepts/routing/setup#setting-up-your-app\";\nlet instanciated = false;\ntype AppState = \"idle\" | \"building\" | \"built\" | \"listening\";\nexport let state: AppState = \"idle\";\n\n/**\n * Creates and configures an Arkos application instance.\n *\n * Arkos extends Express with a small set of methods for registering routers,\n * loading route/service hooks, and booting the application. All Arkos-specific\n * setup (`app.build()`) must happen before the app starts\n * accepting requests.\n *\n * @example\n * ```ts\n * // Simple setup\n * import arkos from \"arkos\";\n *\n * const app = arkos();\n *\n * app.use(reportsRouter);\n *\n * app.listen();\n * ```\n *\n * @example\n * ```ts\n * // Custom HTTP server (e.g. for WebSockets)\n * import arkos from \"arkos\";\n * import http from \"http\";\n *\n * const app = arkos();\n *\n * app.use(reportsRouter);\n *\n * await app.build();\n *\n * const server = http.createServer(app);\n * app.listen(server)\n * ```\n *\n * @see {@link https://www.arkosjs.com/docs/core-concepts/routing/setup}\n */\nexport default function arkos(): Arkos {\n  if (process.env.__ARKOS_CLI !== \"true\")\n    throw ExitError(\n      `Arkos.js application must be started the built-in cli ${isProduction() ? \"'arkos start' in production\" : `'arkos dev' in development`} see https://www.arkosjs.com/docs/getting-started/installation#7-set-up-packagejson-scripts`\n    );\n\n  if (instanciated)\n    throw ExitError(`arkos() must be called only once, see ${docsLink}`);\n\n  const app = applyArkosRouterProxy(express(), {}, \"app\") as any as Arkos;\n  setupApp(app);\n  instanciated = true;\n\n\n\n  function loadApp() {\n    let _app = initializeApp(app);\n    _app = addGlobalErrorHandler(_app);\n    if (process.env.CLI_COMMAND) runtimeCliCommander.handle();\n    return _app;\n  }\n\n  app.build = function() {\n    if (state === \"built\" || state === \"building\")\n      throw ExitError(`app.build() must only be called once, see ${docsLink}`);\n    if (state === \"listening\")\n      throw ExitError(\n        `app.build() must be called before app.listen(), see ${docsLink}`\n      );\n\n    state = \"building\";\n    const _app = loadApp();\n    state = \"built\";\n    return _app;\n  };\n\n  const originalListen = app.listen.bind(app) as any as Express[\"listen\"];\n  type UserCallback = (err?: Error) => void;\n\n  const defaultCb = (\n    port: number | string,\n    host: string,\n    cb?: UserCallback\n  ) => {\n    logAppStartup(port, host);\n    return cb || function() { };\n  };\n\n  app.listen = async function(...args: any[]): Promise<Server> {\n    process.env.__ARKOS_SERVER_LISTENER = \"arkos\";\n\n    if (state === \"listening\")\n      throw ExitError(`app.listen() must only be called once, see ${docsLink}`);\n    if (state === \"building\")\n      throw ExitError(\n        `app.build() must be awaited before calling app.listen(), see ${docsLink}`\n      );\n\n    if (state === \"idle\") {\n      state = \"listening\";\n      loadApp();\n    }\n\n    validateArkosConfig();\n\n    const port = Number(process.env.__PORT || process.env.PORT || \"8000\");\n    const host = process.env.__HOST! || process.env.HOST || \"0.0.0.0\";\n\n    process.send?.({ started: true });\n    if (process.env.__SKIP_LISTEN == \"true\") return appServer;\n\n    if ((args as any)?.length === 0 || typeof args[0] === \"function\")\n      appServer = originalListen(\n        port,\n        host,\n        defaultCb(port, host, args[0] as UserCallback)\n      );\n    else if (args[0] instanceof Server || typeof args[0] === \"object\")\n      appServer = args[0].listen(\n        port,\n        host,\n        defaultCb(port, host, args[1] as UserCallback)\n      );\n\n    return appServer;\n  };\n\n  return app;\n}\n\nexport function getAppServer() {\n  return appServer;\n}\n"]}