statikapi 0.1.0

package/src/loader/serializeGuard.js

@@ -0,0 +1,51 @@
+import { SerializationError } from './errors.js';
+
+const PLAIN_TAG = '[object Object]';
+
+export function assertSerializable(value, atPath = '$', seen = new WeakSet()) {
+  const t = typeof value;
+
+  if (value === null || t === 'string' || t === 'boolean') return;
+  if (t === 'number') {
+    if (!Number.isFinite(value)) throw new SerializationError('Number must be finite', atPath);
+    return;
+  }
+  if (t === 'bigint') throw new SerializationError('BigInt is not JSON-serializable', atPath);
+  if (t === 'symbol') throw new SerializationError('Symbol is not JSON-serializable', atPath);
+  if (t === 'function') throw new SerializationError('Function is not JSON-serializable', atPath);
+
+  // Objects / Arrays
+  if (typeof value === 'object') {
+    if (seen.has(value)) throw new SerializationError('Circular structure detected', atPath);
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        assertSerializable(value[i], `${atPath}[${i}]`, seen);
+      }
+      return;
+    }
+
+    // Plain objects only
+    const tag = Object.prototype.toString.call(value);
+    const proto = Object.getPrototypeOf(value);
+    const isPlain = tag === PLAIN_TAG && (proto === Object.prototype || proto === null);
+    if (!isPlain) {
+      const name = (value && value.constructor && value.constructor.name) || tag;
+      throw new SerializationError(`Only plain objects/arrays allowed (got ${name})`, atPath);
+    }
+
+    // No symbol keys
+    if (Object.getOwnPropertySymbols(value).length) {
+      throw new SerializationError('Symbol keys are not JSON-serializable', atPath);
+    }
+
+    for (const k of Object.keys(value)) {
+      assertSerializable(value[k], `${atPath}.${k}`, seen);
+    }
+    return;
+  }
+
+  // Anything else falls through as unsupported
+  throw new SerializationError(`Unsupported type: ${t}`, atPath);
+}

package/src/router/mapRoutes.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const VALID_EXT = new Set(['.js', '.mjs', '.cjs']);
+
+export async function mapRoutes({ srcAbs }) {
+  const entries = await walk(srcAbs);
+  const routes = [];
+
+  for (const fileAbs of entries) {
+    const info = fileToRoute({ srcAbs, fileAbs });
+    if (!info) continue;
+    const { route, type, normSegments } = info;
+
+    routes.push({
+      file: fileAbs,
+      route,
+      type, // 'static' | 'dynamic' | 'catchall'
+      segments: normSegments, // normalized tokens for sorting (static or :param or *catch)
+    });
+  }
+
+  // Deterministic sort
+  routes.sort(compareRoutes);
+
+  return routes;
+}
+
+async function walk(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    const items = await fs.readdir(cur, { withFileTypes: true });
+    for (const it of items) {
+      const a = path.join(cur, it.name);
+      if (it.isDirectory()) {
+        stack.push(a);
+      } else if (it.isFile()) {
+        out.push(a);
+      }
+    }
+  }
+  return out;
+}
+
+/** Map a single file to route metadata, or null if ignored. */
+export function fileToRoute({ srcAbs, fileAbs }) {
+  const rel = path.posix.normalize(fileAbs.replaceAll(path.sep, '/').slice(srcAbs.length + 1));
+  if (!rel || rel.startsWith('_')) return null; // ignore underscore roots
+  const ext = path.extname(rel);
+  if (!VALID_EXT.has(ext)) return null;
+
+  const relNoExt = rel.slice(0, -ext.length);
+  const segments = relNoExt
+    .split('/')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (segments.some((s) => s.startsWith('_'))) return null;
+
+  const { route, type, normSegments } = toRoute(segments);
+  return { route, type, normSegments };
+}
+
+function toRoute(segments) {
+  // Handle index collapsing: foo/index -> /foo
+  const last = segments[segments.length - 1];
+  const isIndex = last === 'index';
+  const segs = isIndex ? segments.slice(0, -1) : segments;
+
+  // Normalize tokens:
+  //  - static: 'users' stays 'users'
+  //  - dynamic: '[id]' => ':id'
+  //  - catch-all: '[...all]' => '*all'
+  let type = 'static';
+  const normSegments = segs.map((s) => {
+    if (isCatchAll(s)) {
+      type = 'catchall';
+      return '*' + s.slice(4, -1); // [...all] -> *all
+    }
+    if (isDynamic(s)) {
+      if (type !== 'catchall') type = 'dynamic';
+      return ':' + s.slice(1, -1); // [id] -> :id
+    }
+    return s;
+  });
+
+  const route = '/' + normSegments.filter(Boolean).join('/');
+
+  // special case: empty means root (/)
+  const finalRoute = route === '/' ? '/' : route;
+
+  return { route: finalRoute, type, normSegments };
+}
+
+function isDynamic(seg) {
+  return seg.startsWith('[') && seg.endsWith(']') && !seg.startsWith('[...');
+}
+
+function isCatchAll(seg) {
+  return seg.startsWith('[...') && seg.endsWith(']');
+}
+
+// Deterministic sort:
+// 1) static < dynamic < catchall
+// 2) lexicographic by route (so /blog/archive comes before /users)
+// 3) fewer segments as a final tiebreaker
+function compareRoutes(a, b) {
+  const rank = { static: 0, dynamic: 1, catchall: 2 };
+  if (rank[a.type] !== rank[b.type]) return rank[a.type] - rank[b.type];
+  const byRoute = a.route.localeCompare(b.route);
+  if (byRoute !== 0) return byRoute;
+  return a.segments.length - b.segments.length;
+}

package/src/util/bytes.js

@@ -0,0 +1,10 @@
+export function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let u = -1;
+  do {
+    n /= 1024;
+    u++;
+  } while (n >= 1024 && u < units.length - 1);
+  return `${n.toFixed(n >= 10 ? 0 : 1)} ${units[u]}`;
+}

package/src/util/fsx.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+export async function writeFileEnsured(fileAbs, data) {
+  await ensureDir(path.dirname(fileAbs));
+  await fs.writeFile(fileAbs, data);
+}
+export async function emptyDir(dirAbs) {
+  // non-destructive: create if missing, else clean
+  await ensureDir(dirAbs);
+  const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (e) => {
+      const p = path.join(dirAbs, e.name);
+      if (e.isDirectory()) await fs.rm(p, { recursive: true, force: true });
+      else await fs.rm(p, { force: true });
+    })
+  );
+}

package/src/util/readFlags.js

@@ -0,0 +1,28 @@
+export function readFlags(argv = []) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (!t.startsWith('-')) continue;
+
+    if (t.startsWith('--')) {
+      const [k, v] = t.slice(2).split('=', 2);
+      // allow any flag, we’ll read only the ones we need in commands
+      if (v !== undefined) out[k] = coerce(v);
+      else {
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-')) {
+          out[k] = coerce(next);
+          i++;
+        } else out[k] = true; // <- bare flag now boolean true
+      }
+    }
+  }
+  return out;
+}
+
+function coerce(v) {
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : v;
+}