@molecule/api-mock-server 1.0.0

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-mock-server` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-mock-server is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,oGAAoG;QAClG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI entrypoint for the mock API server.
+ *
+ * Usage:
+ *   npx \@molecule/api-mock-server --app personal-finance --port 4000
+ *   npx \@molecule/api-mock-server --fixtures-path ./fixtures --port 4000
+ *   npx \@molecule/api-mock-server --app online-store --port 4015 --state success
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/dist/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * CLI entrypoint for the mock API server.
+ *
+ * Usage:
+ *   npx \@molecule/api-mock-server --app personal-finance --port 4000
+ *   npx \@molecule/api-mock-server --fixtures-path ./fixtures --port 4000
+ *   npx \@molecule/api-mock-server --app online-store --port 4015 --state success
+ */
+import { createMockServer } from './server/server.js';
+/**
+ *
+ * @param argv
+ */
+function parseArgs(argv) {
+    const args = {
+        app: '',
+        port: 4000,
+        state: 'success',
+        delay: 0,
+        help: false,
+    };
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        switch (arg) {
+            case '--app':
+            case '-a':
+                args.app = next ?? '';
+                i++;
+                break;
+            case '--fixtures-path':
+            case '--fixtures':
+                args.fixturesPath = next;
+                i++;
+                break;
+            case '--port':
+            case '-p': {
+                // Number(next) || 4000 would coerce a valid `--port 0` (ephemeral
+                // port) to 4000 — only fall back when the value isn't a port at all.
+                const port = Number(next);
+                if (Number.isInteger(port) && port >= 0 && port <= 65535) {
+                    args.port = port;
+                }
+                else {
+                    // Same disambiguation as --state: a silent fallback reads as
+                    // "the flag was applied" while the server listens elsewhere.
+                    console.warn(`Warning: invalid --port "${next ?? ''}" (expected 0-65535) — using 4000.`);
+                }
+                i++;
+                break;
+            }
+            case '--state':
+            case '-s':
+                if (next && ['success', 'empty', 'error', 'unauthorized'].includes(next)) {
+                    args.state = next;
+                }
+                else {
+                    // A typo'd state silently serving 'success' is a debugging trap.
+                    console.warn(`Warning: invalid --state "${next ?? ''}" (expected success|empty|error|unauthorized) — using "success".`);
+                }
+                i++;
+                break;
+            case '--delay':
+            case '-d': {
+                const delay = Number(next);
+                if (Number.isFinite(delay) && delay >= 0) {
+                    args.delay = delay;
+                }
+                else {
+                    console.warn(`Warning: invalid --delay "${next ?? ''}" (expected milliseconds >= 0) — using 0.`);
+                }
+                i++;
+                break;
+            }
+            case '--handlers-path':
+                args.handlersPath = next;
+                i++;
+                break;
+            case '--help':
+            case '-h':
+                args.help = true;
+                break;
+        }
+    }
+    return args;
+}
+/**
+ *
+ */
+function printHelp() {
+    console.log(`
+  @molecule/api-mock-server - Mock API server with fixture data from JSON files
+
+  Usage:
+    npx @molecule/api-mock-server --app <app-type> [options]
+    npx @molecule/api-mock-server --fixtures-path <path> [options]
+
+  Options:
+    --app, -a <type>           App type to serve (resolves fixtures from mlcl/templates/apps/{type}/api/fixtures/)
+    --fixtures-path <path>     Explicit path to a directory of JSON fixture files
+    --port, -p <port>          Port to listen on (default: 4000)
+    --state, -s <state>        Default response state: success|empty|error|unauthorized (default: success)
+    --delay, -d <ms>           Default response delay in milliseconds (default: 0)
+    --handlers-path <path>     Custom path to handler template files
+    --help, -h                 Show this help message
+
+  Examples:
+    npx @molecule/api-mock-server --app personal-finance --port 4000
+    npx @molecule/api-mock-server --fixtures-path ./my-app/api/fixtures --port 4000
+    npx @molecule/api-mock-server --app online-store --state empty
+    npx @molecule/api-mock-server --app personal-finance --delay 500
+`);
+}
+/**
+ *
+ */
+async function main() {
+    const args = parseArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(0);
+    }
+    if (!args.app && !args.fixturesPath) {
+        console.error('Error: --app or --fixtures-path is required. Use --help for usage.');
+        process.exit(1);
+    }
+    try {
+        const server = await createMockServer({
+            appType: args.app || 'custom',
+            fixturesPath: args.fixturesPath,
+            port: args.port,
+            defaultState: args.state,
+            defaultDelay: args.delay,
+            handlersPath: args.handlersPath,
+        });
+        // Handle graceful shutdown
+        const shutdown = async () => {
+            console.log('\nShutting down mock server...');
+            await server.close();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    catch (error) {
+        console.error('Failed to start mock server:', error.message);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/fixtures/app-fixtures.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Fixture loading from JSON files in a directory.
+ * Each JSON file becomes a resource or endpoint group.
+ * No hardcoded app-specific data — all data lives in template fixture directories.
+ */
+import type { AppDataPool, AppFixtureSet, EndpointDefinition } from '../types.js';
+/**
+ * Load an AppDataPool from a directory of JSON fixture files.
+ *
+ * File naming conventions:
+ * - Array files (e.g. `products.json` containing `[...]`) become CRUD resources
+ * - Object files (e.g. `reports.json` containing `{key: ...}`) become sub-endpoint groups
+ *   where each key maps to a GET endpoint
+ *
+ * Special filenames are treated as report/sub-endpoint groups (object shape expected):
+ *   `reports.json`, `storefront.json`, `admin.json`
+ *
+ * All other files are treated as array resources by default.
+ *
+ * @param fixturesDir - Absolute path to the fixtures directory
+ * @param appType - App type label (for the returned pool metadata)
+ * @returns An AppDataPool, or undefined if the directory doesn't exist or is empty
+ */
+export declare function loadFixturesFromDirectory(fixturesDir: string, appType: string): AppDataPool | undefined;
+/**
+ * Get an AppDataPool for a fixtures directory, with fingerprint-validated
+ * caching: editing/adding/removing a `*.json` fixture file (mtime or size
+ * change) invalidates the cached pool, so a mock server re-created in the
+ * same process serves the fresh data instead of the first load.
+ * @param fixturesDir - Absolute path to the fixtures directory
+ * @param appType - App type label
+ * @returns The loaded pool, or undefined if directory missing/empty
+ */
+export declare function getAppDataPool(fixturesDir: string, appType: string): AppDataPool | undefined;
+/**
+ * Build a complete fixture set for an app type by combining
+ * data pool records with endpoint definitions.
+ * @param appType - The app type
+ * @param endpoints - The discovered endpoints from scanning
+ * @param fixturesDir - Path to the fixtures directory
+ * @returns A complete fixture set, or undefined if no data available
+ */
+export declare function buildFixtureSet(appType: string, endpoints: EndpointDefinition[], fixturesDir?: string): AppFixtureSet | undefined;
+/**
+ * Generate fixtures from a directory of JSON files without scanning handlers.
+ * Builds standard CRUD endpoints for each resource file and custom endpoints
+ * for each sub-endpoint group.
+ *
+ * @param fixturesDir - Absolute path to the fixtures directory
+ * @param appType - App type label (default: derived from directory name)
+ * @returns A fixture set with standard CRUD endpoints, or undefined if no data
+ */
+export declare function generateFixtures(fixturesDir: string, appType?: string): AppFixtureSet | undefined;
+//# sourceMappingURL=app-fixtures.d.ts.map

package/dist/fixtures/app-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-fixtures.d.ts","sourceRoot":"","sources":["../../src/fixtures/app-fixtures.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAGnB,MAAM,aAAa,CAAA;AAsIpB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,WAAW,GAAG,SAAS,CAyDzB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAU5F;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kBAAkB,EAAE,EAC/B,WAAW,CAAC,EAAE,MAAM,GACnB,aAAa,GAAG,SAAS,CAc3B;AAoID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CA0NjG"}