@potentiajs/core 0.1.0-preview.0

package/src/dev/file-routing/path-mapping.js

@@ -0,0 +1,125 @@
+import path from 'node:path';
+
+export const FILE_ROUTE_DIAGNOSTIC_CODES = Object.freeze({
+  COLLISION: 'POTENTIA_FILE_ROUTE_COLLISION',
+  UNSUPPORTED_CATCH_ALL: 'POTENTIA_FILE_ROUTE_UNSUPPORTED_CATCH_ALL',
+  UNSUPPORTED_OPTIONAL_PARAM: 'POTENTIA_FILE_ROUTE_UNSUPPORTED_OPTIONAL_PARAM',
+  UNSUPPORTED_GROUP: 'POTENTIA_FILE_ROUTE_UNSUPPORTED_GROUP',
+  INVALID_PARAM: 'POTENTIA_FILE_ROUTE_INVALID_PARAM',
+  MISSING_ROOT: 'POTENTIA_FILE_ROUTE_MISSING_ROOT'
+});
+
+export function mapRouteFile(filePath, rootDir) {
+  const normalizedFile = normalizePath(filePath);
+  const normalizedRoot = normalizePath(rootDir);
+  const relativePath = normalizeRelative(path.posix.relative(normalizedRoot, normalizedFile));
+  const parts = relativePath.split('/').filter(Boolean);
+  const fileName = parts.at(-1) || '';
+
+  if (!relativePath || relativePath.startsWith('..')) {
+    return invalid(normalizedFile, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.MISSING_ROOT, 'Route file is outside the route root');
+  }
+
+  const privateFolder = parts.slice(0, -1).find((part) => part.startsWith('_'));
+  if (privateFolder) return ignored(normalizedFile, relativePath, 'private-folder');
+
+  if (!fileName.endsWith('.js')) return ignored(normalizedFile, relativePath, 'unsupported-extension');
+  if (fileName.startsWith('_')) return ignored(normalizedFile, relativePath, 'private-file');
+
+  const routeSegments = [];
+  for (const part of parts) {
+    const segment = part === fileName ? stripExtension(part) : part;
+    if (segment === 'index' && part === fileName) continue;
+    const mapped = mapSegment(segment, normalizedFile, relativePath);
+    if (!mapped.ok) return mapped;
+    routeSegments.push(mapped.segment);
+  }
+
+  const routePath = routeSegments.length === 0 ? '/' : `/${routeSegments.join('/')}`;
+  return {
+    ok: true,
+    filePath: normalizedFile,
+    relativePath: relativePath,
+    routePath: routePath,
+    kind: 'route',
+    ignored: false,
+    reason: null,
+    error: null,
+    segments: routeSegments
+  };
+}
+
+export function normalizePath(value) {
+  return String(value || '').replaceAll('\\\\', '/').replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+}
+
+function normalizeRelative(value) {
+  return String(value || '').replaceAll('\\\\', '/').replace(/\/+/g, '/');
+}
+
+function stripExtension(fileName) {
+  return fileName.slice(0, -'.js'.length);
+}
+
+function mapSegment(segment, filePath, relativePath) {
+  if (!segment) return invalid(filePath, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.INVALID_PARAM, 'Empty route segment is not supported');
+
+  if (segment.startsWith('(') && segment.endsWith(')')) {
+    return invalid(filePath, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.UNSUPPORTED_GROUP, 'Route groups are deferred');
+  }
+
+  if (segment.startsWith('[[') && segment.endsWith(']]')) {
+    return invalid(filePath, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.UNSUPPORTED_OPTIONAL_PARAM, 'Optional route params are deferred');
+  }
+
+  if (segment.startsWith('[...') && segment.endsWith(']')) {
+    return invalid(filePath, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.UNSUPPORTED_CATCH_ALL, 'Catch-all route params are deferred');
+  }
+
+  if (segment.startsWith('[') && segment.endsWith(']')) {
+    const name = segment.slice(1, -1);
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+      return invalid(filePath, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.INVALID_PARAM, 'Dynamic route param name is invalid');
+    }
+    return { ok: true, segment: `:${name}` };
+  }
+
+  if (segment.includes('[') || segment.includes(']')) {
+    return invalid(filePath, relativePath, FILE_ROUTE_DIAGNOSTIC_CODES.INVALID_PARAM, 'Dynamic route param syntax is invalid');
+  }
+
+  return { ok: true, segment: segment };
+}
+
+function ignored(filePath, relativePath, reason) {
+  return {
+    ok: true,
+    filePath: filePath,
+    relativePath: relativePath,
+    routePath: null,
+    kind: 'ignored',
+    ignored: true,
+    reason: reason,
+    error: null,
+    segments: []
+  };
+}
+
+function invalid(filePath, relativePath, code, message) {
+  return {
+    ok: false,
+    filePath: filePath,
+    relativePath: relativePath,
+    routePath: null,
+    kind: 'invalid',
+    ignored: false,
+    reason: null,
+    error: {
+      code: code,
+      message: message,
+      filePath: filePath,
+      relativePath: relativePath
+    },
+    segments: []
+  };
+}

package/src/dev/file-routing/scanner.js

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { routeCollisionDiagnostics } from './diagnostics.js';
+import { FILE_ROUTE_DIAGNOSTIC_CODES, mapRouteFile, normalizePath } from './path-mapping.js';
+
+export function scanRouteTree(rootDir) {
+  const normalizedRoot = normalizePath(rootDir);
+
+  if (!fs.existsSync(normalizedRoot) || !fs.statSync(normalizedRoot).isDirectory()) {
+    return emptyScan(normalizedRoot, [{
+      code: FILE_ROUTE_DIAGNOSTIC_CODES.MISSING_ROOT,
+      message: 'Route root directory was not found',
+      rootDir: normalizedRoot
+    }]);
+  }
+
+  const files = listFiles(normalizedRoot);
+  const routes = [];
+  const scopes = [];
+  const ignored = [];
+  const errors = [];
+
+  for (const filePath of files) {
+    const relativePath = normalizeRelative(path.posix.relative(normalizedRoot, filePath));
+    const fileName = path.posix.basename(filePath);
+
+    if (isPrivateFolder(relativePath)) {
+      ignored.push(ignoredEntry(filePath, normalizedRoot, 'private-folder'));
+      continue;
+    }
+
+    if (fileName === '_routes.js') {
+      scopes.push(scopeEntry(filePath, normalizedRoot));
+      continue;
+    }
+
+    const mapped = mapRouteFile(filePath, normalizedRoot);
+    if (!mapped.ok) {
+      errors.push(mapped.error);
+      continue;
+    }
+
+    if (mapped.ignored) {
+      ignored.push({ ...mapped, importPath: toImportPath(relativePath) });
+      continue;
+    }
+
+    routes.push({
+      filePath: mapped.filePath,
+      importPath: toImportPath(mapped.relativePath),
+      routePath: mapped.routePath,
+      segments: mapped.segments,
+      kind: 'route'
+    });
+  }
+
+  const sortedRoutes = sortByPath(routes);
+  const allErrors = sortErrors(errors.concat(routeCollisionDiagnostics(sortedRoutes)));
+
+  return {
+    ok: allErrors.length === 0,
+    rootDir: normalizedRoot,
+    routes: sortedRoutes,
+    scopes: sortByPath(scopes),
+    ignored: sortByFile(ignored),
+    errors: allErrors
+  };
+}
+
+function emptyScan(rootDir, errors = []) {
+  return {
+    ok: errors.length === 0,
+    rootDir: rootDir,
+    routes: [],
+    scopes: [],
+    ignored: [],
+    errors: errors
+  };
+}
+
+function listFiles(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  const files = [];
+
+  for (const entry of entries) {
+    const entryPath = normalizePath(path.posix.join(dir, entry.name));
+    if (entry.isDirectory()) {
+      files.push(...listFiles(entryPath));
+      continue;
+    }
+    if (entry.isFile()) files.push(entryPath);
+  }
+
+  return files;
+}
+
+function scopeEntry(filePath, rootDir) {
+  const normalizedFile = normalizePath(filePath);
+  const relativePath = normalizeRelative(path.posix.relative(rootDir, normalizedFile));
+  const directoryRelative = normalizeRelative(path.posix.dirname(relativePath));
+  const segments = directoryRelative === '.' ? [] : directoryRelative.split('/').filter(Boolean);
+  const routePath = segments.length === 0 ? '/' : `/${segments.join('/')}`;
+
+  return {
+    filePath: normalizedFile,
+    importPath: toImportPath(relativePath),
+    routePath: routePath,
+    directoryPath: normalizePath(path.posix.dirname(normalizedFile)),
+    segments: segments,
+    kind: 'scope'
+  };
+}
+
+function ignoredEntry(filePath, rootDir, reason) {
+  const normalizedFile = normalizePath(filePath);
+  const relativePath = normalizeRelative(path.posix.relative(rootDir, normalizedFile));
+  return {
+    ok: true,
+    filePath: normalizedFile,
+    relativePath: relativePath,
+    importPath: toImportPath(relativePath),
+    routePath: null,
+    kind: 'ignored',
+    ignored: true,
+    reason: reason,
+    error: null,
+    segments: []
+  };
+}
+
+function isPrivateFolder(relativePath) {
+  return relativePath.split('/').filter(Boolean).slice(0, -1).some((part) => part.startsWith('_'));
+}
+
+function toImportPath(relativePath) {
+  return `./${normalizeRelative(relativePath)}`;
+}
+
+function normalizeRelative(value) {
+  return String(value || '').replaceAll('\\\\', '/').replace(/\/+/g, '/');
+}
+
+function sortByPath(values) {
+  return values.slice().sort((a, b) => a.routePath.localeCompare(b.routePath) || a.filePath.localeCompare(b.filePath));
+}
+
+function sortByFile(values) {
+  return values.slice().sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+
+function sortErrors(values) {
+  return values.slice().sort((a, b) => String(a.filePath || '').localeCompare(String(b.filePath || '')) || String(a.code).localeCompare(String(b.code)));
+}

package/src/dev/file-routing/writer.js

@@ -0,0 +1,100 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { generateRouteModule } from './generator.js';
+import { normalizePath } from './path-mapping.js';
+import { scanRouteTree } from './scanner.js';
+
+export async function generateFileRoutes(options = {}) {
+  const prepared = generateFileRouteSource(options);
+  if (!prepared.ok) return prepared;
+
+  const outputFile = prepared.outputFile;
+
+  const tempFile = `${outputFile}.tmp-${process.pid}-${Date.now()}`;
+
+  try {
+    await mkdir(path.posix.dirname(outputFile), { recursive: true });
+    await writeFile(tempFile, prepared.source);
+    await rename(tempFile, outputFile);
+  } catch (error) {
+    await rm(tempFile, { force: true }).catch(() => {});
+    return failureResult(prepared.rootDir, outputFile, [{
+      code: 'POTENTIA_FILE_ROUTE_WRITE_FAILED',
+      message: 'Failed to write generated route module',
+      outputFile: outputFile,
+      cause: error instanceof Error ? error.message : String(error)
+    }], prepared.routes, prepared.scopes);
+  }
+
+  return {
+    ok: true,
+    rootDir: prepared.rootDir,
+    outputFile: prepared.outputFile,
+    written: true,
+    source: prepared.source,
+    routes: prepared.routes,
+    scopes: prepared.scopes,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+export function generateFileRouteSource(options = {}) {
+  const rootDir = resolveOptionPath(options.rootDir, options.cwd);
+  const outputFile = resolveOptionPath(options.outputFile, options.cwd);
+
+  if (!rootDir || !outputFile) {
+    return failureResult(rootDir, outputFile, [{
+      code: 'POTENTIA_FILE_ROUTE_INVALID_OPTIONS',
+      message: 'rootDir and outputFile are required'
+    }]);
+  }
+
+  const scan = scanRouteTree(rootDir);
+  if (!scan.ok || scan.errors.length > 0) {
+    return failureResult(rootDir, outputFile, scan.errors, scan.routes.length, scan.scopes.length);
+  }
+
+  const generated = generateRouteModule(scan, {
+    outputPath: outputFile,
+    packageName: options.packageName
+  });
+
+  if (!generated.ok || generated.errors.length > 0) {
+    return failureResult(rootDir, outputFile, generated.errors, scan.routes.length, scan.scopes.length);
+  }
+
+  return {
+    ok: true,
+    rootDir: rootDir,
+    outputFile: outputFile,
+    written: false,
+    source: generated.source,
+    routes: scan.routes.length,
+    scopes: scan.scopes.length,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+function failureResult(rootDir, outputFile, errors, routes = 0, scopes = 0) {
+  return {
+    ok: false,
+    rootDir: rootDir || null,
+    outputFile: outputFile || null,
+    written: false,
+    source: '',
+    routes: routes,
+    scopes: scopes,
+    diagnostics: errors,
+    errors: errors
+  };
+}
+
+function resolveOptionPath(value, cwd = process.cwd()) {
+  if (!value) return null;
+  const asString = String(value);
+  if (path.posix.isAbsolute(asString)) return normalizePath(asString);
+  return normalizePath(path.posix.resolve(cwd, asString));
+}

package/src/file-routing.d.ts

@@ -0,0 +1,36 @@
+// Experimental TypeScript declarations for @potentiajs/core/file-routing.
+// File routing is a dev/build-time projection API. It does not perform runtime request-time filesystem scanning.
+
+export interface FileRouteDiagnostic {
+  code: string;
+  message: string;
+  filePath?: string;
+  relativePath?: string;
+  routePath?: string;
+  files?: string[];
+  rootDir?: string;
+  outputFile?: string;
+  cause?: string;
+  [key: string]: unknown;
+}
+
+export interface GenerateFileRoutesOptions {
+  rootDir: string;
+  outputFile: string;
+  packageName?: string;
+  cwd?: string;
+}
+
+export interface GenerateFileRoutesResult {
+  ok: boolean;
+  rootDir: string | null;
+  outputFile: string | null;
+  written: boolean;
+  source: string;
+  routes: number;
+  scopes: number;
+  diagnostics: FileRouteDiagnostic[];
+  errors: FileRouteDiagnostic[];
+}
+
+export function generateFileRoutes(options: GenerateFileRoutesOptions): Promise<GenerateFileRoutesResult>;

package/src/file-routing.js

@@ -0,0 +1 @@
+export { generateFileRoutes } from './dev/file-routing/writer.js';

package/src/forms.d.ts

@@ -0,0 +1,9 @@
+export interface RenderFormOptions {
+  action?: string;
+  method?: string;
+  state?: unknown;
+  submitLabel?: string;
+  idPrefix?: string;
+}
+
+export function renderForm(formProjection: unknown, options?: RenderFormOptions): string;