statikapi 0.6.4 → 1.0.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statikapi",
-  "version": "0.6.4",
+  "version": "1.0.0-rc.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/zonayedpca/statikapi",

package/src/build/routeOutPath.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 
-/** Map a route to an output JSON file (index.json style). Static routes only. */
+/** Map a route to an output JSON file (index.json style). */
 export function routeToOutPath({ outAbs, route }) {
   // '/' -> index.json, '/users' -> users/index.json, '/blog/archive' -> blog/archive/index.json
   const rel = route === '/' ? 'index.json' : route.slice(1) + '/index.json';

package/src/commands/build.js

@@ -5,44 +5,15 @@ import crypto from 'node:crypto';
 import { loadConfig } from '../config/loadConfig.js';
 import { ConfigError } from '../config/validate.js';
 import { loadPaths } from '../loader/loadPaths.js';
+import { loadRouteConfig } from '../loader/loadRouteConfig.js';
 import { loadModuleValue } from '../loader/loadModuleValue.js';
 import { mapRoutes } from '../router/mapRoutes.js';
+import { collectionRouteForSegments, toConcreteRoute, toParams } from '../router/routeHelpers.js';
 import { readFlags } from '../util/readFlags.js';
 import { emptyDir, writeFileEnsured } from '../util/fsx.js';
 import { formatBytes } from '../util/bytes.js';
 import { routeToOutPath } from '../build/routeOutPath.js';
 
-function toConcrete(routePattern, segTokens, segs) {
-  // segTokens: ['users', ':id'] or ['docs','*slug']
-  // segs: ['1'] or ['a','b']
-  let idx = 0;
-
-  const parts = routePattern.split('/').map((p) => {
-    if (p.startsWith(':')) return segs[idx++] ?? '';
-    if (p.startsWith('*')) return segs.slice(idx).join('/');
-    return p;
-  });
-  const concrete = parts.join('/').replace(/\/+/g, '/');
-
-  return concrete;
-}
-
-function toParams(segTokens, concreteRoute) {
-  const concreteSegs = concreteRoute.split('/').filter(Boolean);
-  const params = {};
-
-  for (let i = 0; i < segTokens.length; i++) {
-    const tok = segTokens[i];
-    if (tok.startsWith(':')) {
-      params[tok.slice(1)] = concreteSegs[i] ?? '';
-    } else if (tok.startsWith('*')) {
-      params[tok.slice(1)] = concreteSegs.slice(i);
-      break;
-    }
-  }
-  return params;
-}
-
 export default async function buildCmd(argv) {
   const t0 = Date.now();
   try {
@@ -69,6 +40,7 @@ export default async function buildCmd(argv) {
     let byteCount = 0;
     let skippedDynamic = 0;
     const manifest = []; // array of unified entries
+    const emittedByRoute = new Map(); // route -> srcFile
 
     const digest = (s) => crypto.createHash('sha1').update(s).digest('hex');
     const relSrc = (abs) => {
@@ -88,6 +60,14 @@ export default async function buildCmd(argv) {
     };
 
     async function pushManifest({ route, srcFile, outFile, json }) {
+      const owner = emittedByRoute.get(route);
+      if (owner && owner !== srcFile) {
+        throw new Error(
+          `Route collision for ${route}: ${relSrc(srcFile)} conflicts with ${relSrc(owner)}`
+        );
+      }
+      emittedByRoute.set(route, srcFile);
+
       const st = await fs.stat(outFile).catch(() => null);
       const entry = {
         // stable field order
@@ -116,7 +96,7 @@ export default async function buildCmd(argv) {
 
     // helper: materialize a concrete route from tokens + param segments
     async function emitConcreteRoute(r, segs) {
-      const concreteRoute = toConcrete(r.route, r.segments, segs);
+      const concreteRoute = toConcreteRoute(r.route, segs);
       const params = toParams(r.segments, concreteRoute);
       const val = await loadModuleValue(r.file, { params });
       const json = JSON.stringify(val, null, space) + (pretty ? '\n' : '');
@@ -126,6 +106,26 @@ export default async function buildCmd(argv) {
       byteCount += Buffer.byteLength(json);
 
       await pushManifest({ route: concreteRoute, srcFile: r.file, outFile, json });
+
+      return val;
+    }
+
+    async function emitListIndexRoute(r, listIndexCfg, items) {
+      if (!listIndexCfg.enabled) return;
+
+      const collectionRoute = collectionRouteForSegments(r.segments);
+      if (!collectionRoute) {
+        throw new Error(`config.listIndex requires a static parent route for ${r.route}`);
+      }
+
+      const payload = items.map((item) => pickItemFields(item, listIndexCfg.pick, r.route));
+      const json = JSON.stringify(payload, null, space) + (pretty ? '\n' : '');
+      const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: collectionRoute });
+      await writeFileEnsured(outFile, json);
+      fileCount++;
+      byteCount += Buffer.byteLength(json);
+
+      await pushManifest({ route: collectionRoute, srcFile: r.file, outFile, json });
     }
 
     // dynamic: expect [['val'], ...] from loadPaths()
@@ -135,13 +135,17 @@ export default async function buildCmd(argv) {
         skippedDynamic++;
         continue;
       }
+      const routeConfig = await loadRouteConfig(r.file, { fallback: config });
       const seen = new Set();
+      const listItems = [];
       for (const segs of list) {
-        const concrete = toConcrete(r.route, r.segments, segs);
+        const concrete = toConcreteRoute(r.route, segs);
         if (seen.has(concrete)) continue;
         seen.add(concrete);
-        await emitConcreteRoute(r, segs);
+        const item = await emitConcreteRoute(r, segs);
+        listItems.push(item);
       }
+      await emitListIndexRoute(r, routeConfig.listIndex, listItems);
     }
 
     // catch-all: expect [['a','b'], ['guide'], ...]
@@ -151,13 +155,17 @@ export default async function buildCmd(argv) {
         skippedDynamic++;
         continue;
       }
+      const routeConfig = await loadRouteConfig(r.file, { fallback: config });
       const seen = new Set();
+      const listItems = [];
       for (const segs of list) {
-        const concrete = toConcrete(r.route, r.segments, segs);
+        const concrete = toConcreteRoute(r.route, segs);
         if (seen.has(concrete)) continue;
         seen.add(concrete);
-        await emitConcreteRoute(r, segs);
+        const item = await emitConcreteRoute(r, segs);
+        listItems.push(item);
       }
+      await emitListIndexRoute(r, routeConfig.listIndex, listItems);
     }
 
     // Write manifest once (sorted for determinism)
@@ -189,3 +197,16 @@ export default async function buildCmd(argv) {
     return 1;
   }
 }
+
+function pickItemFields(item, pick, route) {
+  if (!pick) return item;
+  if (item == null || typeof item !== 'object' || Array.isArray(item)) {
+    throw new Error(`config.listIndex.pick requires plain-object items for ${route}`);
+  }
+
+  const out = {};
+  for (const key of pick) {
+    if (Object.hasOwn(item, key)) out[key] = item[key];
+  }
+  return out;
+}

package/src/commands/dev.js

@@ -7,9 +7,11 @@ import http from 'node:http';
 import { fileURLToPath } from 'node:url';
 
 import { loadConfig } from '../config/loadConfig.js';
+import { loadRouteConfig } from '../loader/loadRouteConfig.js';
 import { loadModuleValue } from '../loader/loadModuleValue.js';
 import { loadPaths } from '../loader/loadPaths.js';
 import { mapRoutes, fileToRoute } from '../router/mapRoutes.js';
+import { collectionRouteForSegments, toConcreteRoute, toParams } from '../router/routeHelpers.js';
 import { readFlags } from '../util/readFlags.js';
 import { writeFileEnsured } from '../util/fsx.js';
 import { routeToOutPath } from '../build/routeOutPath.js';
@@ -24,36 +26,6 @@ function clearScreen() {
   process.stdout.write('\x1Bc'); // ANSI "clear screen"
 }
 
-function toConcrete(routePattern, segTokens, segs) {
-  let idx = 0;
-
-  const parts = routePattern.split('/').map((p) => {
-    if (p.startsWith(':')) return segs[idx++] ?? '';
-    if (p.startsWith('*')) return segs.slice(idx).join('/');
-    return p;
-  });
-
-  return parts.join('/').replace(/\/+/g, '/');
-}
-
-function toParams(segTokens, concreteRoute) {
-  const concreteSegs = concreteRoute.split('/').filter(Boolean);
-  const params = {};
-
-  for (let i = 0; i < segTokens.length; i++) {
-    const tok = segTokens[i];
-
-    if (tok.startsWith(':')) params[tok.slice(1)] = concreteSegs[i] ?? '';
-    else if (tok.startsWith('*')) {
-      params[tok.slice(1)] = concreteSegs.slice(i);
-
-      break;
-    }
-  }
-
-  return params;
-}
-
 export default async function devCmd(argv) {
   const flags = readFlags(argv);
 
@@ -98,6 +70,7 @@ export default async function devCmd(argv) {
 
   // Manifest state
   const manifestByRoute = new Map(); // route -> entry
+  const routeOwners = new Map(); // route -> srcFile
 
   const digest = (s) => crypto.createHash('sha1').update(s).digest('hex');
   const relSrc = (abs) => {
@@ -122,6 +95,14 @@ export default async function devCmd(argv) {
     await writeFileEnsured(path.join(config.paths.outAbs, '.statikapi', 'manifest.json'), json);
   }
   async function upsertManifest({ route, srcFile, outFile, json }) {
+    const owner = routeOwners.get(route);
+    if (owner && owner !== srcFile) {
+      throw new Error(
+        `Route collision for ${route}: ${relSrc(srcFile)} conflicts with ${relSrc(owner)}`
+      );
+    }
+    routeOwners.set(route, srcFile);
+
     const st = await fs.stat(outFile).catch(() => null);
 
     const entry = {
@@ -138,6 +119,7 @@ export default async function devCmd(argv) {
   }
   function deleteFromManifest(route) {
     manifestByRoute.delete(route);
+    routeOwners.delete(route);
   }
 
   async function emitStatic(r, { fresh = false } = {}) {
@@ -158,11 +140,13 @@ export default async function devCmd(argv) {
       lastEmitted.set(r.file, new Set());
       return { written: 0, skipped: 1 };
     }
+    const routeConfig = await loadRouteConfig(r.file, { fresh, fallback: config });
     const seen = new Set();
     const emittedRoutes = new Set();
+    const listItems = [];
     let written = 0;
     for (const segs of list) {
-      const concrete = toConcrete(r.route, r.segments, segs);
+      const concrete = toConcreteRoute(r.route, segs);
       if (seen.has(concrete)) continue;
       seen.add(concrete);
       const params = toParams(r.segments, concrete);
@@ -171,10 +155,27 @@ export default async function devCmd(argv) {
       const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: concrete });
       await writeFileEnsured(outFile, json);
       emittedRoutes.add(concrete);
+      listItems.push(val);
       await upsertManifest({ route: concrete, srcFile: r.file, outFile, json });
       written++;
     }
 
+    if (routeConfig.listIndex.enabled) {
+      const collectionRoute = collectionRouteForSegments(r.segments);
+      if (!collectionRoute) {
+        throw new Error(`config.listIndex requires a static parent route for ${r.route}`);
+      }
+      const payload = listItems.map((item) =>
+        pickItemFields(item, routeConfig.listIndex.pick, r.route)
+      );
+      const json = JSON.stringify(payload, null, 2) + '\n';
+      const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: collectionRoute });
+      await writeFileEnsured(outFile, json);
+      emittedRoutes.add(collectionRoute);
+      await upsertManifest({ route: collectionRoute, srcFile: r.file, outFile, json });
+      written++;
+    }
+
     // Delete stale outputs from this file (not present anymore)
     const prev = lastEmitted.get(r.file) || new Set();
     for (const oldRoute of prev) {
@@ -479,3 +480,16 @@ async function openInBrowser(url) {
     process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
   exec(`${cmd} "${url}"`);
 }
+
+function pickItemFields(item, pick, route) {
+  if (!pick) return item;
+  if (item == null || typeof item !== 'object' || Array.isArray(item)) {
+    throw new Error(`config.listIndex.pick requires plain-object items for ${route}`);
+  }
+
+  const out = {};
+  for (const key of pick) {
+    if (Object.hasOwn(item, key)) out[key] = item[key];
+  }
+  return out;
+}

package/src/config/defaults.js

@@ -1,4 +1,7 @@
+import { cloneListIndexConfig } from './listIndex.js';
+
 export const DEFAULT_CONFIG = {
   srcDir: 'src-api',
   outDir: 'api-out',
+  listIndex: cloneListIndexConfig(),
 };

package/src/config/listIndex.js

@@ -0,0 +1,88 @@
+export const DEFAULT_LIST_INDEX_CONFIG = Object.freeze({
+  enabled: false,
+  pick: null,
+});
+
+export function cloneListIndexConfig(cfg = DEFAULT_LIST_INDEX_CONFIG) {
+  return {
+    enabled: cfg.enabled,
+    pick: cfg.pick ? [...cfg.pick] : null,
+  };
+}
+
+export function normalizeListIndexValue(raw, { label = 'listIndex' } = {}) {
+  const base = cloneListIndexConfig();
+
+  if (raw == null || raw === false) return base;
+  if (raw === true) {
+    base.enabled = true;
+    return base;
+  }
+
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${label} must be true, false, or an object`);
+  }
+
+  const enabled = raw.enabled == null ? true : raw.enabled;
+  if (typeof enabled !== 'boolean') {
+    throw new Error(`${label}.enabled must be a boolean`);
+  }
+
+  let pick = null;
+  if ('pick' in raw) {
+    if (raw.pick != null) {
+      pick = normalizePick(raw.pick, { label: `${label}.pick` });
+    }
+  }
+
+  return { enabled, pick };
+}
+
+export function applyListIndexFlagOverrides(baseCfg, flags = {}) {
+  const next = cloneListIndexConfig(baseCfg);
+  const hasEnabled = flags.listIndex != null;
+  const hasPick = flags.listIndexPick != null;
+
+  if (!hasEnabled && !hasPick) return next;
+
+  if (hasEnabled) {
+    const raw = flags.listIndex;
+    if (typeof raw !== 'boolean') {
+      throw new Error(`listIndex flag must be true or false`);
+    }
+    next.enabled = raw;
+    if (raw === false && !hasPick) next.pick = null;
+  }
+
+  if (hasPick) {
+    next.pick = normalizePick(flags.listIndexPick, { label: 'listIndexPick flag' });
+    if (!hasEnabled) next.enabled = true;
+  }
+
+  return next;
+}
+
+function normalizePick(raw, { label }) {
+  if (Array.isArray(raw)) {
+    return dedupePick(raw, { label });
+  }
+  if (typeof raw === 'string') {
+    return dedupePick(
+      raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean),
+      { label }
+    );
+  }
+  throw new Error(`${label} must be an array of strings`);
+}
+
+function dedupePick(list, { label }) {
+  for (const key of list) {
+    if (typeof key !== 'string' || !key) {
+      throw new Error(`${label} must contain non-empty strings`);
+    }
+  }
+  return Array.from(new Set(list));
+}

package/src/config/loadConfig.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 
 import { DEFAULT_CONFIG } from './defaults.js';
 import { validateAndNormalize, ConfigError } from './validate.js';
+import { applyListIndexFlagOverrides } from './listIndex.js';
 
 export async function loadConfig({ cwd = process.cwd(), flags = {} } = {}) {
   const file = path.join(cwd, 'statikapi.config.js');
@@ -34,6 +35,10 @@ export async function loadConfig({ cwd = process.cwd(), flags = {} } = {}) {
     ...pickFlags(flags),
   };
 
+  if (flags.listIndex != null || flags.listIndexPick != null) {
+    merged.listIndex = applyListIndexFlagOverrides(merged.listIndex, flags);
+  }
+
   // Validate & expand absolute paths
   const finalCfg = validateAndNormalize(merged, { cwd });
   return { config: finalCfg, source: { fromFile, filePath: file } };

package/src/config/validate.js

@@ -1,5 +1,7 @@
 import path from 'node:path';
 
+import { cloneListIndexConfig, normalizeListIndexValue } from './listIndex.js';
+
 export class ConfigError extends Error {
   constructor(message) {
     super(message);
@@ -29,8 +31,15 @@ export function validateAndNormalize(userCfg, { cwd = process.cwd() } = {}) {
     throw new ConfigError(`"srcDir" and "outDir" must differ (both "${cfg.srcDir}")`);
   }
 
+  try {
+    cfg.listIndex = normalizeListIndexValue(cfg.listIndex, { label: 'listIndex' });
+  } catch (err) {
+    throw new ConfigError(err.message);
+  }
+
   return {
     ...cfg,
+    listIndex: cloneListIndexConfig(cfg.listIndex),
     paths: {
       srcAbs: path.join(cwd, cfg.srcDir),
       outAbs: path.join(cwd, cfg.outDir),

package/src/loader/loadRouteConfig.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+
+import { cloneListIndexConfig, normalizeListIndexValue } from '../config/listIndex.js';
+import { LoaderError } from './errors.js';
+import { importModule } from './importModule.js';
+
+export async function loadRouteConfig(fileAbs, { fresh = false, fallback = null } = {}) {
+  const fileInfo = short(fileAbs);
+  let mod;
+
+  try {
+    mod = await importModule(fileAbs, { fresh });
+  } catch (e) {
+    throw new LoaderError(fileInfo, `Failed to import for config: ${e.message}`);
+  }
+
+  return normalizeConfig(mod?.config, fileInfo, fallback);
+}
+
+function normalizeConfig(raw, fileInfo, fallback) {
+  const base = { listIndex: cloneListIndexConfig(fallback?.listIndex) };
+
+  if (raw == null) return base;
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new LoaderError(fileInfo, `config must be an object when exported`);
+  }
+
+  if (!Object.hasOwn(raw, 'listIndex')) return base;
+
+  const listIndex = raw.listIndex;
+  try {
+    return {
+      listIndex: normalizeListIndexValue(listIndex, { label: 'config.listIndex' }),
+    };
+  } catch (err) {
+    if (err instanceof LoaderError) throw err;
+    throw new LoaderError(fileInfo, err.message);
+  }
+}
+
+function short(p) {
+  try {
+    return path.relative(process.cwd(), p) || p;
+  } catch {
+    return p;
+  }
+}

package/src/router/routeHelpers.js

@@ -0,0 +1,38 @@
+export function toConcreteRoute(routePattern, segs) {
+  let idx = 0;
+
+  const parts = routePattern.split('/').map((p) => {
+    if (p.startsWith(':')) return segs[idx++] ?? '';
+    if (p.startsWith('*')) return segs.slice(idx).join('/');
+    return p;
+  });
+
+  return parts.join('/').replace(/\/+/g, '/');
+}
+
+export function toParams(segTokens, concreteRoute) {
+  const concreteSegs = concreteRoute.split('/').filter(Boolean);
+  const params = {};
+
+  for (let i = 0; i < segTokens.length; i++) {
+    const tok = segTokens[i];
+    if (tok.startsWith(':')) {
+      params[tok.slice(1)] = concreteSegs[i] ?? '';
+    } else if (tok.startsWith('*')) {
+      params[tok.slice(1)] = concreteSegs.slice(i);
+      break;
+    }
+  }
+
+  return params;
+}
+
+export function collectionRouteForSegments(segTokens) {
+  const last = segTokens[segTokens.length - 1];
+  if (!last || (!last.startsWith(':') && !last.startsWith('*'))) return null;
+
+  const parent = segTokens.slice(0, -1);
+  if (parent.some((tok) => tok.startsWith(':') || tok.startsWith('*'))) return null;
+
+  return parent.length ? '/' + parent.join('/') : '/';
+}