sparkzen 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,294 @@
+# SparkZen — Official Documentation
+
+**SparkZen** is a high‑performance TypeScript framework focused on extreme simplicity, aggressively smooth DX, and stylish logs that make any developer smile. Designed for builders who want fast, scalable APIs with an organized architecture — *without corporate bureaucracy*.
+
+Minimal on the outside, powerful on the inside.
+
+---
+
+# 🚀 1. Overview
+
+SparkZen follows three core principles:
+
+* **Zero initial configuration** – import → use → run.
+* **Folder‑driven architecture** – routes are auto‑registered.
+* **DX first** – schemas, middlewares, and handlers fully typed.
+
+Perfect for modern REST APIs, microservices, and backends that demand clarity.
+
+---
+
+# 📦 2. Creating a New SparkZen Project
+
+Kickstart a new SparkZen application using the official CLI:
+
+```bash
+npx sparkzen init
+```
+
+The CLI will walk you through scaffolding, project structure, and essentials.
+
+---
+
+Installation
+
+```bash
+npm install sparkzen
+```
+
+or:
+
+```bash
+yarn add sparkzen
+```
+
+---
+
+# 🏗️ 3. API Initialization
+
+```ts
+import sparkzen from "sparkzen";
+
+async function spark() {
+  try {
+    const app = await sparkzen();
+    await app.listen({ port: 3000 });
+  } catch (error) {
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+spark();
+```
+
+When you run this, SparkZen automatically:
+
+* initializes the server
+* loads all routes inside `src/routes`
+* applies default middlewares
+* prints clean, structured logs
+
+---
+
+# 📂 4. Folder Structure
+
+SparkZen uses a modern, intuitive pattern:
+
+```
+src/
+ └── routes/
+      ├── users/
+      │     ├── get.ts       → GET /users
+      │     └── [id]/
+      │           └── post.ts → POST /users/:id
+      └── auth/
+            └── login/post.ts → POST /auth/login
+```
+
+📌 **Golden Rule:**
+
+* File name → HTTP method
+* Folder name → endpoint path
+* `[id]` → dynamic param
+
+Simple. Beautiful. Powerful.
+
+---
+
+# 🧩 5. Handlers
+
+Handlers are the core of each route.
+
+### Basic Example
+
+```ts
+import type { Handler } from "sparkzen";
+
+const handler: Handler = async (request, reply) => {
+  return reply.status(200).send({ message: "Hello, SparkZen!" });
+};
+
+export default handler;
+```
+
+### What you get inside a handler?
+
+* `request.params`
+* `request.body`
+* `request.query`
+* `request.headers`
+
+All fully typed.
+
+---
+
+# 🛡️ 6. Schemas (TypeBox Powered)
+
+SparkZen uses **TypeBox** for strong validation + auto‑generated TypeScript types.
+
+### Example Schema
+
+```ts
+export const schema = {
+  params: T.Object({
+    id: T.Number({ description: "User ID", examples: [1] }),
+  }),
+
+  body: T.Object({
+    name: T.String({ minLength: 2 }),
+    nick: T.Optional(T.String()),
+  }),
+
+  response: {
+    200: T.Object({
+      ok: T.Boolean(),
+      message: T.String(),
+      received: T.Object({
+        id: T.Number(),
+        name: T.String(),
+        nick: T.Optional(T.String()),
+      }),
+    }),
+  },
+};
+```
+
+Define once → SparkZen types everything.
+
+---
+
+# ⚙️ 7. Middlewares
+
+Clean, lightweight, powerful.
+
+### Example
+
+```ts
+export const middlewares: Middleware<typeof schema> = [
+  (request, _reply, done) => {
+    console.log("[SparkZen] Incoming request:", {
+      params: request.params,
+      body: request.body,
+    });
+    done();
+  },
+
+  (_request, _reply, done) => {
+    console.log("[SparkZen] Second middleware executed");
+    done();
+  },
+];
+```
+
+Each middleware receives:
+
+* `request`
+* `reply`
+* `done()`
+
+Similar to Fastify — but tighter and more TS‑integrated.
+
+---
+
+# 🔥 8. Full Route (Schema + Middleware + Handler)
+
+```ts
+import { Middleware, T, type Handler } from "sparkzen";
+
+export const schema = {
+  params: T.Object({
+    id: T.Number({ description: "User ID", examples: [1] }),
+  }),
+  body: T.Object({
+    name: T.String({ minLength: 2 }),
+    nick: T.Optional(T.String()),
+  }),
+  response: {
+    200: T.Object({
+      ok: T.Boolean(),
+      message: T.String(),
+      received: T.Object({
+        id: T.Number(),
+        name: T.String(),
+        nick: T.Optional(T.String()),
+      }),
+    }),
+  },
+};
+
+export const middlewares: Middleware<typeof schema> = [
+  (request, _reply, done) => {
+    console.log("[SparkZen] Incoming request:", {
+      params: request.params,
+      body: request.body,
+    });
+    done();
+  },
+  () => {
+    console.log("[SparkZen] Second middleware executed");
+  },
+];
+
+const handler: Handler<typeof schema> = async (request, reply) => {
+  const { id } = request.params;
+  const { name, nick } = request.body;
+
+  return reply.status(200).send({
+    ok: true,
+    message: "User processed successfully",
+    received: { id, name, nick },
+  });
+};
+
+export default handler;
+```
+
+---
+
+# 📡 9. Boot Logs
+
+On startup, SparkZen prints something like:
+
+```
+SPARKZEN   INITIALIZING API   SPARKZEN
+
+SPARKZEN   LOADING ROUTES   SPARKZEN
+
+ROUTE   GET  /api/users        .../src/routes/users/get.ts
+ROUTE   POST /api/users/:id    .../src/routes/users/[id]/post.ts
+
+SPARKZEN   STARTING SERVER   SPARKZEN
+
+SERVER  Running at: http://localhost:3000
+```
+
+Logs are designed for:
+
+* maximum clarity
+* fast debugging
+* clean aesthetics
+
+---
+
+# 🧠 10. Best Practices
+
+* Always use **schemas** for strong typing
+* Keep **handlers minimal**
+* Group middlewares by responsibility
+* Keep route folders small and focused
+* Name files after HTTP methods (SparkZen standard ❤️)
+
+---
+
+# 🔮 11. SparkZen Roadmap
+
+Planned features:
+
+* Advanced CLI
+* Official plugins
+* Simplified authentication utilities
+* Auto‑generated documentation
+* Edge‑runtime adapters
+
+SparkZen was built to scale — and you scale with it.

package/dist/cli/index.js

@@ -9,21 +9,38 @@ import { Command } from "commander";
 import degit from "degit";
 import enquirer from "enquirer";
 import fs from "fs-extra";
+import { bgBlue, blue, bold, error, logfy, success } from "logfy-x";
 import path from "path";
 var { prompt } = enquirer;
-var init = new Command().name("init").description("Initialize a new SparkZen project").action(async () => {
-  const { projectName, packageManager, installNow } = await prompt([
+var promptOptions = async () => {
+  const terminalWidth = process.stdout.columns || 80;
+  const line1 = "  \u{1F680}  Welcome to SparkZen! \u{1F680}  ";
+  const line2 = "  Let's set up your new project.   ";
+  const padFor = (text) => {
+    const available = Math.max(0, terminalWidth - text.length);
+    const half = Math.floor(available / 2);
+    const left = " ".repeat(half);
+    const right = " ".repeat(available - half);
+    return bgBlue(left) + text + bgBlue(right);
+  };
+  logfy(`
+${padFor(line1)}
+${padFor(line2)}
+`, { style: "bold blue -underline" });
+  const answers = await prompt([
     {
       type: "input",
       name: "projectName",
       message: "Project name:",
-      required: true
+      required: true,
+      validate: (v) => v && v.trim() ? true : "Please enter a project name"
     },
     {
       type: "select",
       name: "packageManager",
       message: "Package manager:",
-      choices: ["npm", "pnpm", "yarn", "bun"]
+      choices: ["npm", "pnpm", "yarn", "bun"],
+      initial: 0
     },
     {
       type: "confirm",
@@ -32,45 +49,84 @@ var init = new Command().name("init").description("Initialize a new SparkZen pro
       initial: true
     }
   ]);
-  const targetPath = path.resolve(process.cwd(), projectName);
-  console.log("\u{1F4C1} Creating project folder...");
-  await fs.mkdir(targetPath, { recursive: true });
-  console.log("\u{1F4E6} Copying template...");
+  return answers;
+};
+var cloneProjectTemplate = async (projectName, targetPath) => {
+  console.log(`
+${bgBlue(bold(" \u{1F4C1} CREATING "))} ${projectName}`);
+  await fs.mkdirp(path.dirname(targetPath));
+  console.log(`
+${bgBlue(bold(" \u{1F501} COPYING "))} Default template`);
   const template = degit("MatheusSantos360/sparkzen-templates/default", {
     cache: false,
     force: true
   });
-  await template.clone(projectName);
+  try {
+    await template.clone(targetPath);
+  } catch (err) {
+    throw new Error(`Failed to clone template: ${err.message}`);
+  }
   const pkgJsonPath = path.join(targetPath, "package.json");
-  const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, "utf-8"));
-  pkgJson.name = projectName;
-  await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+  if (!await fs.pathExists(pkgJsonPath)) {
+    error("NOT FOUND", "package.json not found in the template.");
+    return;
+  }
+  try {
+    const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, "utf-8"));
+    pkgJson.name = projectName;
+    await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+  } catch (err) {
+    error("ERROR", `Failed to update package.json: ${err.message}`);
+  }
+};
+var installDependencies = (packageManager, targetPath) => {
   console.log(`
-\u{1F680} Project "${projectName}" created successfully!`);
-  if (installNow) {
-    console.log(`\u26A1 Installing dependencies with ${packageManager}...`);
+${bgBlue(bold(" \u26A1 DEPENDENCIES "))} Installing with ${blue(packageManager)}:
+`);
+  try {
     execSync(`${packageManager} install`, {
       cwd: targetPath,
       stdio: "inherit",
       shell: process.platform === "win32" ? "cmd.exe" : "/bin/sh"
     });
+  } catch (err) {
+    throw new Error(`Dependency install failed: ${err.message}`);
+  }
+};
+var init = new Command().name("init").description("Initialize a new SparkZen project").action(async () => {
+  try {
+    const { projectName, packageManager, installNow } = await promptOptions();
+    const targetPath = path.resolve(process.cwd(), projectName);
+    await cloneProjectTemplate(projectName, targetPath);
+    if (installNow) {
+      installDependencies(packageManager, targetPath);
+    }
+    console.log();
+    success("CREATED!", `Project "${blue(projectName)}" has been created successfully.`);
+    console.log(`
+${bgBlue(bold(" \u{1F525} NEXT STEPS "))} To get started:
+`);
+    console.log(`    cd ${blue(projectName)}`);
+    console.log(`    ${blue(packageManager)} run ${blue("dev")}
+`);
+  } catch (err) {
+    error("ERROR", err.message);
+    process.exit(1);
   }
-  console.log(`\u2705 Project ${projectName} created successfully!`);
-  console.log(`
-Next steps:
-  cd ${projectName}
-  ${packageManager} run dev`);
 });
 var init_default = init;
 
 // src/cli/commands/dev.ts
 import { execSync as execSync2 } from "child_process";
 import { Command as Command2 } from "commander";
+import { bgBlue as bgBlue2, bold as bold2 } from "logfy-x";
 import path2 from "path";
 var dev = new Command2().name("dev").description("Run the project in development mode").action(() => {
   const projectPath = process.cwd();
-  const tsxPath = path2.join(projectPath, "node_modules", ".bin", "tsx");
-  console.log("\u{1F680} Starting dev server...");
+  const tsxPath = path2.join(projectPath, "node_modules", ".bin", process.platform === "win32" ? "tsx.cmd" : "tsx");
+  console.log(`
+${bgBlue2(bold2(" \u{1F680} DEV  "))} Starting development server...
+`);
   execSync2(`${tsxPath} watch src/index.ts`, {
     cwd: projectPath,
     stdio: "inherit",
@@ -82,16 +138,21 @@ var dev_default = dev;
 // src/cli/commands/build.ts
 import { execSync as execSync3 } from "child_process";
 import { Command as Command3 } from "commander";
+import { bgGreenBright, bold as bold3 } from "logfy-x";
 import path3 from "path";
 var build = new Command3().name("build").description("Build the project").action(() => {
   const projectPath = process.cwd();
-  console.log("\u{1F680} Building the project...");
+  console.log(`${bgGreenBright(bold3(" \u{1F4E6} BUILD "))} Building the project...
+`);
   const tsupPath = path3.join(process.cwd(), "node_modules", ".bin", "tsup");
-  execSync3(`${tsupPath} src/index.ts --format esm --dts --out-dir dist`, {
+  execSync3(`${tsupPath} src/index.ts --format esm --out-dir dist`, {
     cwd: projectPath,
     stdio: "inherit",
     shell: process.platform === "win32" ? "cmd.exe" : "/bin/sh"
   });
+  console.log(`
+${bgGreenBright(bold3(" \u2705 BUILD "))} Build completed successfully!
+`);
 });
 var build_default = build;
 
@@ -102,8 +163,12 @@ function registerCommands(program2) {
   program2.addCommand(build_default);
 }
 
+// package.json
+var name = "sparkzen";
+var version = "1.0.2";
+
 // src/cli/index.ts
 var program = new Command4();
-program.name("sparkzen").description("SparkZen CLI").version("1.0.0");
+program.name(name).description("SparkZen CLI").version(version);
 registerCommands(program);
 program.parse();

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/core/sparkzen.ts
 import fastify from "fastify";
+import { bgBlueBright as bgBlueBright2, bgGreenBright, blue, bold as bold3, dim as dim3, error } from "logfy-x";
 
 // src/core/routing/isValidRoute.ts
 var isValidRoute = (routeModule) => {
@@ -20,9 +21,17 @@ var getRouteUrl = (filePath) => {
 };
 
 // src/core/routing/registerRoute.ts
+import { bgBlueBright } from "logfy-x";
+import * as colors from "logfy-x";
 var registerRoute = (app, routeModule, method, finalPath) => {
   const routeURL = getRouteUrl(finalPath);
-  console.log(`Registering route: [${method.toUpperCase()}] ${routeURL}`);
+  const methodColors = {
+    get: "green",
+    post: "yellow",
+    put: "blue",
+    delete: "red",
+    patch: "magenta"
+  };
   const routeOptions = {
     ...routeModule,
     method,
@@ -31,6 +40,7 @@ var registerRoute = (app, routeModule, method, finalPath) => {
     preHandler: routeModule.middlewares
   };
   app.route(routeOptions);
+  console.log(bgBlueBright(colors.bold(` ROUTE `)) + ` ${colors[methodColors[method]](method.toUpperCase())} ${routeURL} ${colors.dim(finalPath)}`);
 };
 
 // src/core/loadRoutes.ts
@@ -44,6 +54,7 @@ var dynamicImport = async (modulePath) => {
 };
 
 // src/core/loadRoutes.ts
+import { bgRedBright, bold as bold2, dim as dim2, red } from "logfy-x";
 var loadRoutes = async (app, directory) => {
   const production = process.env.NODE_ENV === "production";
   const ext = production ? ".js" : ".ts";
@@ -63,16 +74,38 @@ var loadRoutes = async (app, directory) => {
         const method = item.name.replace(new RegExp(`${ext}$`), "").toLowerCase();
         registerRoute(app, routeModule, method, finalPath);
       } else {
-        console.warn(`Invalid route module: ${modulePath}`);
+        console.log(bgRedBright(bold2(` ROUTE `)) + ` ${red("Invalid Route (No handler exported)")} ${dim2(finalPath)}`);
       }
     }
   }
 };
 
 // src/core/sparkzen.ts
+function sparkzenBanner(message, color) {
+  const tag = color(bold3(" SPARKZEN "));
+  const line = dim3("\u2500".repeat(10 * 2 + message.length + 2));
+  console.log(`
+${tag} ${bold3(message)} ${tag}
+${line}`);
+}
 async function sparkzen() {
+  sparkzenBanner("INITIALIZING API", bgBlueBright2);
   const app = fastify().withTypeProvider();
+  sparkzenBanner("LOADING ROUTES", bgGreenBright);
   await loadRoutes(app);
+  console.log();
+  const originalListen = app.listen.bind(app);
+  app.listen = async function(opts) {
+    try {
+      sparkzenBanner("STARTING SERVER", bgGreenBright);
+      const result = await originalListen(opts);
+      console.log(`${bgGreenBright(bold3(" SERVER "))} Running at: ${blue(`http://localhost:${opts.port}`)}
+`);
+      return result;
+    } catch (err) {
+      error("ERROR", err.message);
+    }
+  };
   return app;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkzen",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "license": "MIT",
   "author": "Matheus dos Santos Paixão",
   "type": "module",
@@ -21,7 +21,8 @@
     "degit": "^2.8.4",
     "enquirer": "^2.4.1",
     "fastify": "^5.6.1",
-    "fs-extra": "^11.3.2"
+    "fs-extra": "^11.3.2",
+    "logfy-x": "^1.0.3"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",