fexapi 0.1.0 → 0.1.2

package/README.md

@@ -3,15 +3,156 @@
 Frontend Experience API - Mock API generation CLI tool for local development and testing.
 
 ## Installation
+
 ```bash
 npm install -g fexapi
 ```
 
 ## Usage
+
 ```bash
 fexapi [options]
 ```
 
+## Prisma-like Flow (Dynamic)
+
+### 1) Initialize
+
+```bash
+pnpm dlx fexapi init
+```
+
+`fexapi init` runs an interactive setup wizard and asks:
+
+- What port? (default: 3000)
+- Enable CORS? (Y/n)
+- Generate sample schemas? (Y/n)
+
+Creates:
+
+- `fexapi/schema.fexapi`
+- `fexapi.config.json`
+- `fexapi.config.js`
+- `schemas/user.yaml` and `schemas/post.yaml` (if sample schemas are enabled)
+
+### 2) Edit schema file
+
+`fexapi/schema.fexapi` uses a simple DSL with only `:` and `,` (no semicolons):
+
+```txt
+# Server
+port: 4100
+
+# Routes
+GET /users: id:uuid,name:name,email:email,age:number,phone:phone,pic:url,courseName:string
+GET /courses: id:uuid,courseName:string,mentor:name
+```
+
+### 3) Generate artifacts (updates migration)
+
+```bash
+npx fexapi generate
+```
+
+Generates:
+
+- `fexapi/generated.api.json`
+- `fexapi/migrations/schema.json`
+
+### 4) Start server
+
+```bash
+npx fexapi run
+# or
+npx fexapi serve
+# request/response logging
+npx fexapi serve --log
+# or dev watch mode (nodemon-like)
+npx fexapi dev --watch
+# watch mode + request logs
+npx fexapi dev --watch --log
+# or (inside local workspace package)
+npm run serve
+```
+
+Server port is read from `schema.fexapi` unless overridden by CLI `--port`.
+
+`fexapi dev --watch` auto-reloads when these files change:
+
+- `fexapi/schema.fexapi`
+- `fexapi/generated.api.json`
+- `fexapi.config.js`
+- `fexapi.config.json`
+- `schemas/*.yaml`
+
+`fexapi serve --log` prints request logs like:
+
+- `[GET] /users/1 → 200 (45ms)`
+- `[POST] /posts → 201 (12ms)`
+
+## Configuration File Support
+
+Create a `fexapi.config.js` in your project root:
+
+```js
+// fexapi.config.js
+module.exports = {
+  port: 3000,
+  routes: {
+    "/users": { count: 50, schema: "user" },
+    "/posts": { count: 100, schema: "post" },
+  },
+  cors: true,
+  delay: 200,
+};
+```
+
+Then run:
+
+```bash
+fexapi serve
+```
+
+Notes:
+
+- `port` sets the default server port (CLI `--port` still has priority).
+- `routes` maps endpoint paths to generated payload settings.
+- `schema` maps to files under `schemas/` (for example `schema: "user"` -> `schemas/user.yaml`); unknown names fall back to a generic record.
+- `cors: true` enables CORS headers and OPTIONS preflight handling.
+- `delay` adds response latency in milliseconds.
+
+## Custom Schema Definitions
+
+You can define custom schemas in YAML files under `schemas/`.
+
+```yaml
+# schemas/user.yaml
+name:
+  type: string
+  faker: person.fullName
+email:
+  type: string
+  faker: internet.email
+age:
+  type: number
+  min: 18
+  max: 80
+```
+
+Then reference it in `fexapi.config.js`:
+
+```js
+routes: {
+  "/users": { count: 50, schema: "user" }
+}
+```
+
+Notes:
+
+- Supported file extensions: `.yaml`, `.yml`
+- Schema name is taken from filename (for example `schemas/user.yaml` -> `schema: "user"`)
+- `faker` values map to Faker paths like `person.fullName`, `internet.email`
+
 ## Features
 
 - Schema-based mock API generation
@@ -21,4 +162,4 @@ fexapi [options]
 
 ## License
 
-MIT
+MIT

package/dist/cli/args.d.ts

@@ -0,0 +1,24 @@
+export declare const parseInitOptions: (initArgs: string[]) => {
+    force: boolean;
+} | {
+    error: string;
+};
+export declare const parseGenerateOptions: (generateArgs: string[]) => {
+    error?: string;
+};
+export declare const parseServeOptions: (serveArgs: string[]) => {
+    host: string;
+    port?: number;
+    logEnabled: boolean;
+} | {
+    error: string;
+};
+export declare const parseDevOptions: (devArgs: string[]) => {
+    host: string;
+    port?: number;
+    watchEnabled: boolean;
+    logEnabled: boolean;
+} | {
+    error: string;
+};
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,GAC3B,UAAU,MAAM,EAAE,KACjB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAWtC,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,cAAc,MAAM,EAAE,KACrB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAQlB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,WAAW,MAAM,EAAE,KAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAkDxE,CAAC;AAEF,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,EAAE,KAEf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAC3E;IAAE,KAAK,EAAE,MAAM,CAAA;CAwDlB,CAAC"}

package/dist/cli/args.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDevOptions = exports.parseServeOptions = exports.parseGenerateOptions = exports.parseInitOptions = void 0;
+const parseInitOptions = (initArgs) => {
+    const validFlags = new Set(["--force"]);
+    const invalidFlags = initArgs.filter((value) => value.startsWith("-") && !validFlags.has(value));
+    if (invalidFlags.length > 0) {
+        return { error: `Unknown option(s): ${invalidFlags.join(", ")}` };
+    }
+    return { force: initArgs.includes("--force") };
+};
+exports.parseInitOptions = parseInitOptions;
+const parseGenerateOptions = (generateArgs) => {
+    const invalidFlags = generateArgs.filter((value) => value.startsWith("-"));
+    if (invalidFlags.length > 0) {
+        return { error: `Unknown option(s): ${invalidFlags.join(", ")}` };
+    }
+    return {};
+};
+exports.parseGenerateOptions = parseGenerateOptions;
+const parseServeOptions = (serveArgs) => {
+    const getFlagValue = (flagName) => {
+        const index = serveArgs.indexOf(flagName);
+        if (index === -1) {
+            return undefined;
+        }
+        const value = serveArgs[index + 1];
+        if (!value || value.startsWith("-")) {
+            return { error: `Missing value for ${flagName}` };
+        }
+        return value;
+    };
+    const unknownFlags = serveArgs.filter((value) => value.startsWith("-") &&
+        value !== "--host" &&
+        value !== "--port" &&
+        value !== "--log");
+    if (unknownFlags.length > 0) {
+        return { error: `Unknown option(s): ${unknownFlags.join(", ")}` };
+    }
+    const hostValue = getFlagValue("--host");
+    if (hostValue && typeof hostValue !== "string") {
+        return hostValue;
+    }
+    const portValue = getFlagValue("--port");
+    if (portValue && typeof portValue !== "string") {
+        return portValue;
+    }
+    const host = hostValue ?? "127.0.0.1";
+    const port = portValue ? Number(portValue) : undefined;
+    if (port !== undefined &&
+        (!Number.isInteger(port) || port < 1 || port > 65535)) {
+        return { error: `Invalid port: ${portValue ?? ""}`.trim() };
+    }
+    return { host, port, logEnabled: serveArgs.includes("--log") };
+};
+exports.parseServeOptions = parseServeOptions;
+const parseDevOptions = (devArgs) => {
+    const getFlagValue = (flagName) => {
+        const index = devArgs.indexOf(flagName);
+        if (index === -1) {
+            return undefined;
+        }
+        const value = devArgs[index + 1];
+        if (!value || value.startsWith("-")) {
+            return { error: `Missing value for ${flagName}` };
+        }
+        return value;
+    };
+    const unknownFlags = devArgs.filter((value) => value.startsWith("-") &&
+        value !== "--host" &&
+        value !== "--port" &&
+        value !== "--watch" &&
+        value !== "--log");
+    if (unknownFlags.length > 0) {
+        return { error: `Unknown option(s): ${unknownFlags.join(", ")}` };
+    }
+    const hostValue = getFlagValue("--host");
+    if (hostValue && typeof hostValue !== "string") {
+        return hostValue;
+    }
+    const portValue = getFlagValue("--port");
+    if (portValue && typeof portValue !== "string") {
+        return portValue;
+    }
+    const host = hostValue ?? "127.0.0.1";
+    const port = portValue ? Number(portValue) : undefined;
+    if (port !== undefined &&
+        (!Number.isInteger(port) || port < 1 || port > 65535)) {
+        return { error: `Invalid port: ${portValue ?? ""}`.trim() };
+    }
+    return {
+        host,
+        port,
+        watchEnabled: devArgs.includes("--watch"),
+        logEnabled: devArgs.includes("--log"),
+    };
+};
+exports.parseDevOptions = parseDevOptions;

package/dist/cli/help.d.ts

@@ -0,0 +1,2 @@
+export declare const printHelp: () => void;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,YAgDrB,CAAC"}

package/dist/cli/help.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printHelp = void 0;
+const printHelp = () => {
+    console.log("fexapi-cli");
+    console.log("");
+    console.log("Usage:");
+    console.log("  fexapi init [--force]");
+    console.log("  fexapi generate");
+    console.log("  fexapi dev [--watch] [--host <host>] [--port <number>] [--log]");
+    console.log("  fexapi serve [--host <host>] [--port <number>] [--log]");
+    console.log("  fexapi run [--host <host>] [--port <number>] [--log]");
+    console.log("  fexapi [--host <host>] [--port <number>] [--log]");
+    console.log("  fexapi --help");
+    console.log("");
+    console.log("Examples:");
+    console.log("  fexapi init");
+    console.log("  fexapi init --force");
+    console.log("  fexapi generate");
+    console.log("  fexapi dev --watch");
+    console.log("  fexapi dev --watch --log");
+    console.log("  fexapi serve --log");
+    console.log("  fexapi serve --host 127.0.0.1 --port 5000");
+    console.log("  fexapi --port 4000");
+    console.log("");
+    console.log("Package manager usage:");
+    console.log("  npx fexapi init");
+    console.log("  pnpm dlx fexapi init");
+    console.log("  yarn dlx fexapi init");
+    console.log("");
+    console.log("`fexapi init` creates:");
+    console.log("  fexapi.config.json");
+    console.log("  fexapi.config.js");
+    console.log("  fexapi/schema.fexapi");
+    console.log("  schemas/*.yaml (optional, via wizard)");
+    console.log("");
+    console.log("Init wizard asks:");
+    console.log("  What port? (default: 3000)");
+    console.log("  Enable CORS? (Y/n)");
+    console.log("  Generate sample schemas? (Y/n)");
+    console.log("");
+    console.log("Then run:");
+    console.log("  # edit fexapi/schema.fexapi");
+    console.log("  fexapi generate");
+    console.log("  fexapi run");
+    console.log("");
+    console.log("Generate output:");
+    console.log("  fexapi/generated.api.json");
+    console.log("  fexapi/migrations/schema.json");
+};
+exports.printHelp = printHelp;

package/dist/commands/dev.d.ts

@@ -0,0 +1,7 @@
+export declare const runDevCommand: ({ host, port, watchEnabled, logEnabled, }: {
+    host: string;
+    port?: number;
+    watchEnabled: boolean;
+    logEnabled: boolean;
+}) => number;
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,aAAa,GAAI,2CAK3B;IACD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;CACrB,KAAG,MAuHH,CAAC"}

package/dist/commands/dev.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDevCommand = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_1 = require("../project/paths");
+const serve_1 = require("./serve");
+const WATCH_DEBOUNCE_MS = 150;
+const normalizePath = (pathValue) => {
+    return pathValue.replace(/\\/g, "/").toLowerCase();
+};
+const isWatchedPath = (projectRoot, changedPath) => {
+    const relativePath = normalizePath((0, node_path_1.relative)(projectRoot, changedPath));
+    if (relativePath === "fexapi.config.js" ||
+        relativePath === "fexapi.config.json") {
+        return true;
+    }
+    if (relativePath.startsWith("fexapi/")) {
+        return true;
+    }
+    return (relativePath.startsWith("schemas/") &&
+        (relativePath.endsWith(".yaml") || relativePath.endsWith(".yml")));
+};
+const runDevCommand = ({ host, port, watchEnabled, logEnabled, }) => {
+    if (!watchEnabled) {
+        return (0, serve_1.serveProject)({ host, port, logEnabled });
+    }
+    const projectRoot = (0, paths_1.resolveProjectRoot)();
+    if (!projectRoot) {
+        console.error("Could not find package.json in this directory or parent directories.");
+        return 1;
+    }
+    let currentServer = (0, serve_1.createProjectServer)({ host, port, logEnabled });
+    if (!currentServer) {
+        return 1;
+    }
+    console.log("Watch mode enabled. Restarting on config/schema changes...");
+    let restartTimer;
+    let restartQueued = false;
+    let restartInProgress = false;
+    const restartServer = async (reason) => {
+        if (!currentServer) {
+            return;
+        }
+        if (restartInProgress) {
+            restartQueued = true;
+            return;
+        }
+        restartInProgress = true;
+        console.log(`\n[watch] change detected (${reason})`);
+        await new Promise((resolve) => {
+            currentServer?.close(() => {
+                resolve();
+            });
+        });
+        currentServer = (0, serve_1.createProjectServer)({ host, port, logEnabled });
+        restartInProgress = false;
+        if (restartQueued) {
+            restartQueued = false;
+            await restartServer("queued changes");
+        }
+    };
+    const scheduleRestart = (reason) => {
+        if (restartTimer) {
+            clearTimeout(restartTimer);
+        }
+        restartTimer = setTimeout(() => {
+            void restartServer(reason);
+        }, WATCH_DEBOUNCE_MS);
+    };
+    const activeWatchers = [];
+    const watchTargets = [
+        (0, node_path_1.join)(projectRoot, "fexapi"),
+        (0, node_path_1.join)(projectRoot, "schemas"),
+        projectRoot,
+    ];
+    for (const watchTarget of watchTargets) {
+        if (!(0, node_fs_1.existsSync)(watchTarget)) {
+            continue;
+        }
+        const watcher = (0, node_fs_1.watch)(watchTarget, { recursive: true }, (_event, file) => {
+            if (!file) {
+                scheduleRestart("unknown file");
+                return;
+            }
+            const changedPath = (0, node_path_1.join)(watchTarget, file.toString());
+            if (isWatchedPath(projectRoot, changedPath)) {
+                scheduleRestart((0, node_path_1.relative)(projectRoot, changedPath));
+            }
+        });
+        activeWatchers.push(watcher);
+    }
+    const cleanupAndExit = async () => {
+        if (restartTimer) {
+            clearTimeout(restartTimer);
+            restartTimer = undefined;
+        }
+        for (const watcher of activeWatchers) {
+            watcher.close();
+        }
+        await new Promise((resolve) => {
+            currentServer?.close(() => resolve());
+        });
+        process.exit(0);
+    };
+    process.on("SIGINT", () => {
+        void cleanupAndExit();
+    });
+    process.on("SIGTERM", () => {
+        void cleanupAndExit();
+    });
+    return 0;
+};
+exports.runDevCommand = runDevCommand;

package/dist/commands/generate.d.ts

@@ -0,0 +1,2 @@
+export declare const generateFromSchema: () => number;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,kBAAkB,QAAO,MAyGrC,CAAC"}

package/dist/commands/generate.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFromSchema = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const constants_1 = require("../constants");
+const paths_1 = require("../project/paths");
+const schema_1 = require("../schema");
+const generateFromSchema = () => {
+    const projectRoot = (0, paths_1.resolveProjectRoot)();
+    if (!projectRoot) {
+        console.error("Could not find package.json in this directory or parent directories.");
+        return 1;
+    }
+    const schemaPath = (0, node_path_1.join)(projectRoot, "fexapi", "schema.fexapi");
+    const generatedPath = (0, node_path_1.join)(projectRoot, "fexapi", "generated.api.json");
+    const migrationsDirectoryPath = (0, node_path_1.join)(projectRoot, "fexapi", "migrations");
+    const configPath = (0, node_path_1.join)(projectRoot, "fexapi.config.json");
+    if (!(0, node_fs_1.existsSync)(schemaPath)) {
+        console.error(`Schema file not found: ${schemaPath}`);
+        console.error("Run `fexapi init` first.");
+        return 1;
+    }
+    const schemaText = (0, node_fs_1.readFileSync)(schemaPath, "utf-8");
+    const parsed = (0, schema_1.parseFexapiSchema)(schemaText);
+    if (parsed.errors.length > 0 || !parsed.schema) {
+        console.error("Failed to generate API from schema.fexapi");
+        for (const error of parsed.errors) {
+            console.error(`- ${error}`);
+        }
+        return 1;
+    }
+    const generated = {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        port: parsed.schema.port,
+        routes: parsed.schema.routes,
+    };
+    (0, node_fs_1.mkdirSync)(migrationsDirectoryPath, { recursive: true });
+    const existingMigrationFiles = (0, node_fs_1.readdirSync)(migrationsDirectoryPath, {
+        withFileTypes: true,
+    })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => (0, node_path_1.join)(migrationsDirectoryPath, entry.name));
+    for (const migrationFilePath of existingMigrationFiles) {
+        (0, node_fs_1.unlinkSync)(migrationFilePath);
+    }
+    const migrationId = new Date().toISOString().replace(/[.:]/g, "-");
+    const migrationPath = (0, node_path_1.join)(migrationsDirectoryPath, "schema.json");
+    const migration = {
+        migrationId,
+        sourceSchema: "fexapi/schema.fexapi",
+        createdAt: generated.generatedAt,
+        port: parsed.schema.port,
+        routes: parsed.schema.routes,
+    };
+    (0, node_fs_1.writeFileSync)(generatedPath, `${JSON.stringify(generated, null, 2)}\n`, "utf-8");
+    (0, node_fs_1.writeFileSync)(migrationPath, `${JSON.stringify(migration, null, 2)}\n`, "utf-8");
+    let existingConfig = {};
+    if ((0, node_fs_1.existsSync)(configPath)) {
+        try {
+            existingConfig = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        }
+        catch {
+            existingConfig = {};
+        }
+    }
+    const updatedConfig = {
+        ...existingConfig,
+        schemaPath: "fexapi/schema.fexapi",
+        generatedPath: constants_1.GENERATED_SPEC_RELATIVE_PATH,
+        lastGeneratedAt: new Date().toISOString(),
+    };
+    (0, node_fs_1.writeFileSync)(configPath, `${JSON.stringify(updatedConfig, null, 2)}\n`, "utf-8");
+    console.log(`Generated API spec at ${generatedPath}`);
+    console.log(`Migration updated at ${migrationPath}`);
+    console.log(`Routes generated: ${parsed.schema.routes.length}`);
+    console.log(`Configured server port: ${parsed.schema.port}`);
+    return 0;
+};
+exports.generateFromSchema = generateFromSchema;

package/dist/commands/init.d.ts

@@ -0,0 +1,4 @@
+export declare const initializeProject: ({ force, }: {
+    force: boolean;
+}) => Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAwKA,eAAO,MAAM,iBAAiB,GAAU,YAErC;IACD,KAAK,EAAE,OAAO,CAAC;CAChB,KAAG,OAAO,CAAC,MAAM,CAmJjB,CAAC"}