@potentiajs/core 0.1.0-preview.0

package/src/kernel/route-manifest.js

@@ -0,0 +1,129 @@
+import { createRouteId, normalizeRoutePath } from './route-id.js';
+import { projectRoutes } from './route-projection.js';
+
+export { createRouteId, normalizeRoutePath };
+
+export function createRouteManifest(input, options = {}) {
+  const projected = projectRoutes(input);
+  const diagnostics = [];
+
+  if (projected.kind !== 'routes') {
+    diagnostics.push(createDiagnostic('POTENTIA_MANIFEST_INVALID_ROUTE', 'Manifest input could not be projected as routes', { index: null, routeId: null, routeName: null }));
+  }
+
+  const routes = projected.routes.map((route, index) => manifestRoute(route, index));
+  const actions = projected.routes.map((route, index) => manifestAction(route, index)).filter(Boolean);
+  const lookupResult = buildLookups(routes);
+  diagnostics.push(...lookupResult.diagnostics);
+
+  return {
+    kind: 'potentia-route-manifest',
+    version: 1,
+    package: {
+      name: typeof options.packageName === 'string' ? options.packageName : null,
+      version: typeof options.packageVersion === 'string' ? options.packageVersion : null
+    },
+    routes: routes,
+    actions: actions,
+    lookups: lookupResult.lookups,
+    diagnostics: diagnostics,
+    meta: Object.prototype.hasOwnProperty.call(options, 'meta') ? options.meta : null
+  };
+}
+
+function manifestAction(route, index) {
+  if (!route.action) return null;
+
+  return {
+    kind: 'action',
+    id: route.action.id,
+    routeId: route.id || createRouteId(route),
+    method: route.method,
+    path: normalizeRoutePath(route.path),
+    input: route.action.input,
+    output: route.action.output,
+    result: route.action.result,
+    contentTypes: ['application/json', 'application/x-www-form-urlencoded'],
+    enhancement: {
+      plainForm: true,
+      fetch: true,
+      clientValidation: 'projection-only'
+    },
+    source: route.action.source || null,
+    meta: route.action.meta || null,
+    index: index
+  };
+}
+
+function manifestRoute(route, index) {
+  return {
+    id: route.id || createRouteId(route),
+    name: route.name || null,
+    method: route.method,
+    path: normalizeRoutePath(route.path),
+    contracts: route.contracts,
+    hooks: route.hooks,
+    source: route.source || null,
+    meta: route.meta || null,
+    index: index
+  };
+}
+
+function buildLookups(routes) {
+  const lookups = emptyLookups();
+  const diagnostics = [];
+
+  for (const route of routes) {
+    if (!route.id || !route.method || !route.path) {
+      diagnostics.push(createDiagnostic('POTENTIA_MANIFEST_INVALID_ROUTE', 'Manifest route is missing method, path, or id', diagnosticDetail(route)));
+      continue;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(lookups.byId, route.id)) {
+      diagnostics.push(createDiagnostic('POTENTIA_MANIFEST_DUPLICATE_ROUTE_ID', `Duplicate route id: ${route.id}`, diagnosticDetail(route)));
+    } else {
+      lookups.byId[route.id] = route.index;
+    }
+
+    if (route.name) {
+      if (Object.prototype.hasOwnProperty.call(lookups.byName, route.name)) {
+        diagnostics.push(createDiagnostic('POTENTIA_MANIFEST_DUPLICATE_ROUTE_NAME', `Duplicate route name: ${route.name}`, diagnosticDetail(route)));
+      } else {
+        lookups.byName[route.name] = route.id;
+      }
+    }
+
+    const methodPath = `${route.method} ${route.path}`;
+    if (Object.prototype.hasOwnProperty.call(lookups.byMethodPath, methodPath)) {
+      diagnostics.push(createDiagnostic('POTENTIA_MANIFEST_DUPLICATE_ROUTE_ID', `Duplicate route method/path: ${methodPath}`, diagnosticDetail(route)));
+    } else {
+      lookups.byMethodPath[methodPath] = route.id;
+    }
+  }
+
+  return { lookups: lookups, diagnostics: diagnostics };
+}
+
+function emptyLookups() {
+  return {
+    byId: {},
+    byName: {},
+    byMethodPath: {}
+  };
+}
+
+function createDiagnostic(code, message, detail) {
+  return {
+    code: code,
+    message: message,
+    detail: detail || null
+  };
+}
+
+function diagnosticDetail(route) {
+  return {
+    index: Number.isInteger(route.index) ? route.index : null,
+    routeId: route.id || null,
+    routeName: route.name || null
+  };
+}

package/src/kernel/route-projection.js

@@ -0,0 +1,139 @@
+import { projectContract } from './contract-projection.js';
+import { isAction } from './action.js';
+import { projectAction } from './action-projection.js';
+import { createRouteId } from './route-id.js';
+import { composeRoutes } from './route-collection.js';
+
+const CONTRACT_BOUNDARIES = ['params', 'query', 'headers', 'body', 'response'];
+
+export function projectRoute(value) {
+  if (!isRoute(value)) {
+    return {
+      kind: 'unknown-route',
+      id: null,
+      name: null,
+      method: null,
+      path: null,
+      contracts: emptyProjectedContracts(),
+      hooks: emptyHookSummary(),
+      action: null,
+      source: null,
+      meta: null
+    };
+  }
+
+  return {
+    kind: 'route',
+    id: createRouteId(value),
+    name: typeof value.name === 'string' ? value.name : null,
+    method: value.method,
+    path: value.path,
+    contracts: projectContractBoundaries(value.options),
+    hooks: summarizeHooks(value.hooks),
+    action: isAction(value.handler) ? projectAction(value.handler) : null,
+    source: value.source || null,
+    meta: Object.prototype.hasOwnProperty.call(value, 'meta') ? value.meta : null
+  };
+}
+
+export function projectRoutes(value) {
+  if (Array.isArray(value)) {
+    return projectRouteSet({
+      prefix: null,
+      routes: composeRoutes(value),
+      hooks: {},
+      contracts: {},
+      meta: null
+    });
+  }
+
+  if (isRouteCollection(value) || isMount(value)) {
+    return projectRouteSet({
+      prefix: value.prefix,
+      routes: composeRoutes([value]),
+      hooks: value.hooks,
+      contracts: value.contracts,
+      meta: Object.prototype.hasOwnProperty.call(value, 'meta') ? value.meta : null
+    });
+  }
+
+  if (isApp(value)) {
+    return projectRouteSet({
+      prefix: null,
+      routes: value.routes,
+      hooks: value.hooks,
+      contracts: {},
+      meta: null
+    });
+  }
+
+  return {
+    kind: 'unknown-routes',
+    prefix: null,
+    routes: [],
+    hooks: emptyHookSummary(),
+    contracts: emptyProjectedContracts(),
+    meta: null
+  };
+}
+
+export function projectContractBoundaries(contracts = {}) {
+  const projected = {};
+  for (const boundary of CONTRACT_BOUNDARIES) {
+    projected[boundary] = contracts && Object.prototype.hasOwnProperty.call(contracts, boundary) ? projectContract(contracts[boundary]) : null;
+  }
+  return projected;
+}
+
+export function summarizeHooks(hooks = {}) {
+  return {
+    beforeRequest: Array.isArray(hooks.beforeRequest) ? hooks.beforeRequest.length : 0,
+    afterResponse: Array.isArray(hooks.afterResponse) ? hooks.afterResponse.length : 0,
+    onError: Array.isArray(hooks.onError) ? hooks.onError.length : 0
+  };
+}
+
+function projectRouteSet(value) {
+  return {
+    kind: 'routes',
+    prefix: value.prefix,
+    routes: value.routes.map(projectRoute),
+    hooks: summarizeHooks(value.hooks),
+    contracts: projectContractBoundaries(value.contracts),
+    meta: value.meta
+  };
+}
+
+function emptyProjectedContracts() {
+  return {
+    params: null,
+    query: null,
+    headers: null,
+    body: null,
+    response: null
+  };
+}
+
+function emptyHookSummary() {
+  return {
+    beforeRequest: 0,
+    afterResponse: 0,
+    onError: 0
+  };
+}
+
+function isRoute(value) {
+  return Boolean(value && typeof value === 'object' && typeof value.method === 'string' && typeof value.path === 'string' && Object.prototype.hasOwnProperty.call(value, 'handler'));
+}
+
+function isRouteCollection(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'routes' && Array.isArray(value.routes));
+}
+
+function isMount(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'mount');
+}
+
+function isApp(value) {
+  return Boolean(value && typeof value === 'object' && Array.isArray(value.routes) && typeof value.fetch === 'function');
+}

package/src/kernel/route.js

@@ -0,0 +1,156 @@
+import { createFrameworkError, ERROR_CODES } from './error.js';
+
+export function route(method, path, handler, options = {}) {
+  const normalizedSource = normalizeSource(options.source);
+
+  return {
+    method: String(method).toUpperCase(),
+    path: path,
+    handler: handler,
+    options: options,
+    name: typeof options.name === 'string' ? options.name : null,
+    source: normalizedSource,
+    meta: Object.prototype.hasOwnProperty.call(options, 'meta') ? options.meta : null,
+    pattern: parsePathPattern(path)
+  };
+}
+
+export function normalizeSource(source) {
+  if (!source || typeof source !== 'object') return null;
+
+  return {
+    file: typeof source.file === 'string' ? source.file : null,
+    line: Number.isInteger(source.line) ? source.line : null,
+    column: Number.isInteger(source.column) ? source.column : null
+  };
+}
+
+export function matchRoute(routes, method, path) {
+  const normalizedMethod = String(method).toUpperCase();
+  const matches = [];
+  const allowed = [];
+  let error = null;
+
+  for (let index = 0; index < routes.length; index += 1) {
+    const candidate = routes[index];
+    const pathMatch = matchPath(candidate.pattern, path);
+
+    if (pathMatch.error) {
+      error = pathMatch.error;
+      continue;
+    }
+
+    if (!pathMatch.matched) continue;
+
+    allowed.push(candidate.method);
+    matches.push({
+      route: candidate,
+      params: pathMatch.params,
+      score: candidate.pattern.score,
+      index: index
+    });
+  }
+
+  if (matches.length === 0) {
+    return {
+      found: false,
+      methodAllowed: true,
+      route: null,
+      params: {},
+      allowed: [],
+      error: error
+    };
+  }
+
+  matches.sort(compareMatches);
+
+  for (const match of matches) {
+    if (match.route.method === normalizedMethod) {
+      return {
+        found: true,
+        methodAllowed: true,
+        route: match.route,
+        params: match.params,
+        allowed: allowed,
+        error: null
+      };
+    }
+  }
+
+  return {
+    found: false,
+    methodAllowed: false,
+    route: null,
+    params: {},
+    allowed: unique(allowed),
+    error: null
+  };
+}
+
+export function parsePathPattern(path) {
+  const segments = splitPath(path);
+  let staticCount = 0;
+  let dynamicCount = 0;
+
+  const parsedSegments = segments.map((segment) => {
+    if (segment.startsWith(':') && segment.length > 1) {
+      dynamicCount += 1;
+      return { type: 'param', value: segment.slice(1) };
+    }
+
+    staticCount += 1;
+    return { type: 'static', value: segment };
+  });
+
+  return {
+    path: path,
+    segments: parsedSegments,
+    score: staticCount * 10 - dynamicCount
+  };
+}
+
+function matchPath(pattern, path) {
+  const pathSegments = splitPath(path);
+
+  if (pattern.segments.length !== pathSegments.length) {
+    return { matched: false, params: {}, error: null };
+  }
+
+  const params = {};
+
+  for (let index = 0; index < pattern.segments.length; index += 1) {
+    const patternSegment = pattern.segments[index];
+    const pathSegment = pathSegments[index];
+
+    if (patternSegment.type === 'static') {
+      if (patternSegment.value !== pathSegment) return { matched: false, params: {}, error: null };
+      continue;
+    }
+
+    try {
+      params[patternSegment.value] = decodeURIComponent(pathSegment);
+    } catch (error) {
+      return {
+        matched: false,
+        params: {},
+        error: createFrameworkError(ERROR_CODES.BAD_REQUEST, 'Invalid route parameter encoding', { status: 400, cause: error, expose: true })
+      };
+    }
+  }
+
+  return { matched: true, params: params, error: null };
+}
+
+function splitPath(path) {
+  if (path === '/') return [];
+  return String(path).split('/').filter(Boolean);
+}
+
+function compareMatches(a, b) {
+  if (a.score !== b.score) return b.score - a.score;
+  return a.index - b.index;
+}
+
+function unique(values) {
+  return Array.from(new Set(values));
+}