fluxion-ts 0.0.4 → 0.0.6

package/README.md

@@ -9,3 +9,176 @@
     <img src="https://raw.githubusercontent.com/baendlorel/fluxion/refs/heads/main/assets/fluxion.svg" width="240px" alt="fluxion logo" />
   </a>
 </p>
+
+Fluxion is a filesystem-routing dynamic server for Node.js.
+
+- Use `.mjs` files directly as route handlers
+- Run handlers inside worker runtime isolation
+- Inject any npm module into handler `context` via `modules`
+- If a handler returns a value, Fluxion auto-responds with `200 + JSON`
+
+## Install
+
+```bash
+npm install fluxion
+```
+
+## Quick Start
+
+### 1) Start the server
+
+Create `server.mjs`:
+
+```js
+import { fluxion } from 'fluxion';
+
+fluxion({
+  dir: './dynamicDirectory',
+  host: '127.0.0.1',
+  port: 3000,
+});
+```
+
+### 2) Create a route handler
+
+Create `dynamicDirectory/hello.mjs`:
+
+```js
+export default function handler(_req, _res, context) {
+  return {
+    message: 'hello fluxion',
+    workerId: context.worker.id,
+  };
+}
+```
+
+Run:
+
+```bash
+node server.mjs
+```
+
+Test:
+
+```bash
+curl http://127.0.0.1:3000/hello
+```
+
+You will get a JSON response with status `200`.
+
+## Routing Rules
+
+- `dynamicDirectory/index.mjs` -> `/`
+- `dynamicDirectory/user.mjs` -> `/user`
+- `dynamicDirectory/user/index.mjs` -> `/user`
+- Non-`.mjs` files are served as static files (`GET/HEAD`)
+- Directories/files starting with `_` are private and not routable
+
+## Handler Styles
+
+### Function export
+
+```js
+export default function handler(req, res, context) {
+  return { ok: true };
+}
+```
+
+### Object export (with modules)
+
+```js
+export default {
+  modules: [
+    {
+      module: 'node:crypto',
+      injectKey: 'crypto',
+      factory: (cryptoModule) => cryptoModule,
+    },
+  ],
+  handler(_req, _res, context) {
+    return {
+      hash: context.crypto.createHash('sha1').update('abc').digest('hex'),
+    };
+  },
+};
+```
+
+## Automatic JSON Response
+
+If a handler return value is not `undefined` and you do not manually call `res.end()`, Fluxion will automatically:
+
+- set status to `200`
+- set `content-type` to `application/json; charset=utf-8` (if missing)
+- serialize the return value with `JSON.stringify(...)`
+
+Recommended pattern per handler:
+
+1. Return data directly (recommended)
+2. Or fully control `res` manually (streaming, file download, etc.)
+
+## Module Injection (Recommended)
+
+Fluxion does not bundle database drivers. Install app dependencies yourself.
+
+For example, to use MySQL in handlers:
+
+```bash
+npm install mysql2
+```
+
+```js
+export default {
+  modules: [
+    {
+      module: 'mysql2/promise',
+      injectKey: 'mydb',
+      options: {
+        host: '127.0.0.1',
+        user: 'root',
+        password: '***',
+        database: 'demo',
+      },
+      factory: (mysql2, options) => mysql2.createPool(options),
+    },
+  ],
+  async handler(_req, _res, context) {
+    const [rows] = await context.mydb.query('select 1 as ok');
+    return rows;
+  },
+};
+```
+
+### `modules` fields
+
+- `module`: module id used by dynamic `import()`
+- `injectKey`: target key in `context[injectKey]`
+- `options`: custom config passed into `factory`
+- `factory`: `(importedModule, options, runtime) => injectedValue`
+
+`factory` runs inside the worker and is restored from source text. Keep it self-contained (do not depend on outer closures).
+
+Each worker keeps its own module instances. On worker shutdown, Fluxion will attempt `dispose/close/end/destroy` if present.
+
+## Common Options
+
+Main `fluxion({...})` options:
+
+- `dir`: dynamic directory (handler root)
+- `host`: listen host
+- `port`: listen port
+- `maxRequestBytes`: max request body size (returns 413 when exceeded)
+- `logger`: `one-line` / `json-line` / custom function
+
+## Important
+
+Legacy handler-level `db` declarations are removed:
+
+```js
+export default {
+  // db: ['main'] // no longer supported
+  modules: [],
+  handler() {},
+};
+```
+
+Use `modules` for dependency injection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluxion-ts",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "author": {
     "name": "Kasukabe Tsumugi",
     "email": "futami16237@gmail.com"

package/src/core/server.ts

@@ -131,11 +131,7 @@ function normalizeDatabaseRuntimeConfigItem(
   }
 
   const rawDriver =
-    typeof input.driver === 'string'
-      ? input.driver
-      : typeof input.type === 'string'
-        ? input.type
-        : undefined;
+    typeof input.driver === 'string' ? input.driver : typeof input.type === 'string' ? input.type : undefined;
 
   if (rawDriver === undefined) {
     throw new Error(`Missing db driver for "${dbName}" in ${source}`);
@@ -209,11 +205,7 @@ function normalizeDatabaseConfigMap(input: unknown, source: string): protocol.Wo
       throw new Error(`Invalid db config for "${name}" in "${source}"`);
     }
 
-    normalized[name] = normalizeDatabaseRuntimeConfigItem(
-      name,
-      rawConfig as FluxionDatabaseRuntimeConfigInput,
-      source,
-    );
+    normalized[name] = normalizeDatabaseRuntimeConfigItem(name, rawConfig as FluxionDatabaseRuntimeConfigInput, source);
   }
 
   return normalized;
@@ -372,7 +364,7 @@ export function fluxion(options: FluxionOptions): http.Server {
 
     const bodyCapture = createBodyPreviewCapture(req);
 
-    logger.write('INFO', 'RequestReceived', { method, ip, path: url.pathname });
+    logger.write('INFO', 'Req', { method, ip, path: url.pathname });
 
     const start = performance.now();
     res.once('finish', () => {
@@ -395,7 +387,7 @@ export function fluxion(options: FluxionOptions): http.Server {
         fields.bodyTruncated = bodyPreview.truncated;
       }
 
-      logger.write('INFO', 'RequestCompleted', fields);
+      logger.write('INFO', 'Res', fields);
     });
 
     void metaApi

package/src/workers/file-runtime.ts

@@ -532,6 +532,25 @@ function buildHandlerCandidates(dynamicDirectory: string, segments: readonly str
   return [path.resolve(routePath, 'index.mjs'), `${routePath}.mjs`];
 }
 
+/**
+ * Builds ordered static file candidates for one route.
+ */
+function buildStaticCandidates(dynamicDirectory: string, segments: readonly string[]): string[] {
+  if (segments.length === 0) {
+    return [path.resolve(dynamicDirectory, 'index.html')];
+  }
+
+  const routePath = path.resolve(dynamicDirectory, ...segments);
+  const candidates = [routePath];
+  const lastSegment = segments[segments.length - 1];
+
+  if (path.extname(lastSegment).length === 0) {
+    candidates.push(path.resolve(routePath, 'index.html'));
+  }
+
+  return candidates;
+}
+
 /**
  * Streams static file to response.
  */
@@ -893,38 +912,40 @@ export function createFileRuntime(dir: string, options: FileRuntimeOptions = {})
       return HandlerResult.NotFound;
     }
 
-    if (parsedPath.segments.length === 0) {
-      return HandlerResult.NotFound;
-    }
+    const candidates = buildStaticCandidates(dir, parsedPath.segments);
 
-    const filePath = path.resolve(dir, ...parsedPath.segments);
+    for (let i = 0; i < candidates.length; i++) {
+      const filePath = candidates[i];
 
-    if (!isUnderDirectory(filePath, dir)) {
-      return HandlerResult.NotFound;
-    }
+      if (!isUnderDirectory(filePath, dir)) {
+        continue;
+      }
 
-    if (path.extname(filePath).toLowerCase() === '.mjs') {
-      return HandlerResult.NotFound;
-    }
+      if (path.extname(filePath).toLowerCase() === '.mjs') {
+        continue;
+      }
 
-    try {
-      const stat = await fs.promises.stat(filePath);
+      try {
+        const stat = await fs.promises.stat(filePath);
 
-      if (!stat.isFile()) {
-        return HandlerResult.NotFound;
-      }
+        if (!stat.isFile()) {
+          continue;
+        }
 
-      await streamStaticFile(filePath, stat, method, res);
-      return HandlerResult.Handled;
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
+        await streamStaticFile(filePath, stat, method, res);
+        return HandlerResult.Handled;
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
 
-      if (code === 'ENOENT' || code === 'ENOTDIR') {
-        return HandlerResult.NotFound;
-      }
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+          continue;
+        }
 
-      throw error;
+        throw error;
+      }
     }
+
+    return HandlerResult.NotFound;
   };
 
   /**

package/tests/core/file-runtime.test.ts

@@ -169,6 +169,33 @@ describe('file-runtime', () => {
     expect(await hiddenStaticResponse.text()).toBe('not_found');
   });
 
+  it('falls back to route index.html when direct file is not matched', async () => {
+    const dynamicDirectory = await createTempDirectory('fluxion-runtime-static-index-');
+    tempDirectories.push(dynamicDirectory);
+
+    await writeFile(
+      path.join(dynamicDirectory, 'docs', 'index.html'),
+      '<html><body><h1>docs-home</h1></body></html>',
+    );
+    await writeFile(
+      path.join(dynamicDirectory, 'index.html'),
+      '<html><body><h1>root-home</h1></body></html>',
+    );
+
+    const { server, baseUrl } = await startRuntimeServer(dynamicDirectory);
+    servers.push(server);
+
+    const docsResponse = await fetch(`${baseUrl}/docs`);
+    expect(docsResponse.status).toBe(200);
+    expect(docsResponse.headers.get('content-type')).toContain('text/html');
+    expect(await docsResponse.text()).toContain('docs-home');
+
+    const rootResponse = await fetch(`${baseUrl}/`);
+    expect(rootResponse.status).toBe(200);
+    expect(rootResponse.headers.get('content-type')).toContain('text/html');
+    expect(await rootResponse.text()).toContain('root-home');
+  });
+
   it('creates route snapshot from .mjs handlers and static files', async () => {
     const dynamicDirectory = await createTempDirectory('fluxion-runtime-snapshot-');
     tempDirectories.push(dynamicDirectory);