@potentiajs/core 0.1.0-preview.0

package/src/kernel/action.js

@@ -0,0 +1,172 @@
+import { applyContract, createContractFailure } from './contract.js';
+import { createRootIssue } from './diagnostics.js';
+import { createFrameworkError, ERROR_CODES } from './error.js';
+import { runEffect } from './effect.js';
+import { fail } from './result.js';
+import { normalizeSource } from './route.js';
+import { isRedirectResponse, replaceResponseBody, responseBody } from './response.js';
+
+export function action(id, handler, options = {}) {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new TypeError('Action id must be a non-empty string');
+  }
+
+  if (!isRunnableHandler(handler)) {
+    throw new TypeError('Action handler must be a function or effect descriptor');
+  }
+
+  return {
+    kind: 'action',
+    id: id,
+    handler: handler,
+    input: Object.prototype.hasOwnProperty.call(options, 'input') ? options.input : null,
+    output: Object.prototype.hasOwnProperty.call(options, 'output') ? options.output : null,
+    meta: Object.prototype.hasOwnProperty.call(options, 'meta') ? options.meta : null,
+    source: normalizeSource(options.source)
+  };
+}
+
+export function isAction(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'action' && typeof value.id === 'string' && Object.prototype.hasOwnProperty.call(value, 'handler'));
+}
+
+export async function runAction(actionValue, context, options = {}) {
+  const input = await parseActionInput(context.request);
+
+  if (options.routeOptions && options.routeOptions.body) {
+    context.body = applyActionContract(options.routeOptions.body, input, 'body', 'Request body failed contract validation', ERROR_CODES.CONTRACT_FAILED, 400);
+  }
+
+  context.input = actionValue.input ? applyActionContract(actionValue.input, input, 'input', 'Action input contract failed.', ERROR_CODES.ACTION_INPUT_FAILED, 400) : input;
+
+  let value;
+  try {
+    value = await runEffect(actionValue.handler, context);
+  } catch (error) {
+    throw createFrameworkError(ERROR_CODES.ACTION_HANDLER_FAILED, 'Internal server error', {
+      status: 500,
+      detail: { boundary: 'handler', issues: [createRootIssue({ code: 'handler_failed', message: 'Handler failed', boundary: 'handler', source: 'framework' })] },
+      cause: error,
+      expose: false
+    });
+  }
+
+  if (!actionValue.output || value instanceof Response || isRedirectResponse(value) || isFailureResult(value)) return value;
+
+  try {
+    const body = responseBody(value);
+    const output = applyContract(actionValue.output, body, { boundary: 'output' });
+    return replaceResponseBody(value, output);
+  } catch (error) {
+    return fail(createContractFailure('output', 'Action output contract failed.', error, {
+      code: ERROR_CODES.ACTION_OUTPUT_FAILED,
+      status: 500
+    }));
+  }
+}
+
+async function parseActionInput(request) {
+  let text;
+  try {
+    text = await request.text();
+  } catch (error) {
+    throw createActionInputFailure('Action input could not be read.', error);
+  }
+
+  if (text.length === 0) return null;
+
+  const contentType = detectActionContentType(request.headers.get('content-type'));
+
+  if (contentType === 'form-urlencoded') {
+    return parseUrlEncodedActionInput(text);
+  }
+
+  if (contentType === 'unsupported') {
+    throw createActionInputFailure('Action input content type is unsupported.', null);
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw createActionInputFailure('Action input JSON was malformed.', error);
+  }
+}
+
+export function detectActionContentType(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) return 'missing';
+
+  const mediaType = value.toLowerCase().split(';')[0].trim();
+  if (mediaType === 'application/json') return 'json';
+  if (mediaType === 'application/x-www-form-urlencoded') return 'form-urlencoded';
+  return 'unsupported';
+}
+
+export function parseUrlEncodedActionInput(text) {
+  const result = {};
+
+  for (const pair of text.split('&')) {
+    if (pair.length === 0) continue;
+
+    const separator = pair.indexOf('=');
+    const rawKey = separator === -1 ? pair : pair.slice(0, separator);
+    const rawValue = separator === -1 ? '' : pair.slice(separator + 1);
+    const key = decodeUrlEncodedPart(rawKey);
+    const value = decodeUrlEncodedPart(rawValue);
+
+    if (isDangerousFormKey(key)) {
+      throw createActionInputFailure('Action form input contained an unsafe field name.', null);
+    }
+
+    if (Object.prototype.hasOwnProperty.call(result, key)) {
+      const current = result[key];
+      result[key] = Array.isArray(current) ? current.concat(value) : [current, value];
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+function decodeUrlEncodedPart(value) {
+  try {
+    return decodeURIComponent(value.replace(/\+/g, ' '));
+  } catch (error) {
+    throw createActionInputFailure('Action form input was malformed.', error);
+  }
+}
+
+function isDangerousFormKey(key) {
+  return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+
+function isFailureResult(value) {
+  return Boolean(value && typeof value === 'object' && value.ok === false && 'value' in value && 'error' in value && 'meta' in value);
+}
+
+function applyActionContract(contract, value, boundary, message, code, status) {
+  try {
+    return applyContract(contract, value, { boundary: boundary });
+  } catch (error) {
+    throw createContractFailure(boundary, message, error, { code: code, status: status });
+  }
+}
+
+function createActionInputFailure(message, cause) {
+  return createFrameworkError(ERROR_CODES.ACTION_INPUT_FAILED, message, {
+    status: 400,
+    detail: { boundary: 'input', issues: [createRootIssue({ code: actionInputIssueCode(message), message: message, boundary: 'input', source: 'framework' })] },
+    cause: cause,
+    expose: true
+  });
+}
+
+function actionInputIssueCode(message) {
+  if (message.includes('malformed')) return 'malformed_input';
+  if (message.includes('unsupported')) return 'unsupported_content_type';
+  return 'input_failed';
+}
+
+function isRunnableHandler(handler) {
+  return typeof handler === 'function' || Boolean(handler && typeof handler === 'object' && handler.type === 'effect' && typeof handler.run === 'function');
+}

package/src/kernel/app.js

@@ -0,0 +1,144 @@
+import { isAction, runAction } from './action.js';
+import { applyContract, applyNamedRequestContract, createContractFailure, parseContractBody } from './contract.js';
+import { createRequestContext } from './context.js';
+import { createFrameworkError, ERROR_CODES, normalizeFrameworkError } from './error.js';
+import { runEffect } from './effect.js';
+import { pluginRoutes } from './plugin.js';
+import { fail } from './result.js';
+import { composeRoutes, normalizeHooks } from './route-collection.js';
+import { matchRoute } from './route.js';
+import { isRedirectResponse, isResponseDescriptor, replaceResponseBody, responseBody, toResponse } from './response.js';
+
+export function createApp(options = {}) {
+  const state = Object.prototype.hasOwnProperty.call(options, 'state') ? options.state : null;
+  const pluginRouteCollections = pluginRoutes(options.plugins, { state: state });
+  const routes = composeRoutes((Array.isArray(options.routes) ? options.routes : []).concat(pluginRouteCollections));
+  const hooks = normalizeHooks(options.hooks);
+
+  return {
+    routes: routes,
+    state: state,
+    hooks: hooks,
+    fetch: async function fetch(request) {
+      return handleRequest(request, routes, state, hooks);
+    }
+  };
+}
+
+async function handleRequest(request, routes, state, hooks) {
+  const url = new URL(request.url);
+  const match = matchRoute(routes, request.method, url.pathname);
+
+  if (match.error) {
+    return toResponse(fail(match.error));
+  }
+
+  if (!match.found) {
+    if (!match.methodAllowed) {
+      return methodNotAllowedResponse(match.allowed);
+    }
+    return toResponse(fail(createFrameworkError(ERROR_CODES.NOT_FOUND, 'No route matched the request path', { status: 404, expose: true })));
+  }
+
+  const context = createRequestContext(request, match, state);
+  const routeHooks = normalizeHooks(match.route.hooks);
+  const beforeHooks = hooks.beforeRequest.concat(routeHooks.beforeRequest);
+  const afterHooks = routeHooks.afterResponse.concat(hooks.afterResponse);
+  const errorHooks = routeHooks.onError.concat(hooks.onError);
+
+  try {
+    const before = await runBeforeRequestHooks(beforeHooks, context);
+    if (before !== undefined) {
+      return await projectAndRunAfterHooks(before, afterHooks, context);
+    }
+
+    const actionRoute = isAction(match.route.handler);
+    await applyRequestContracts(context, match.route.options, { body: !actionRoute });
+
+    const value = actionRoute ? await runAction(match.route.handler, context, { routeOptions: match.route.options }) : await runEffect(match.route.handler, context);
+    const contracted = applyResponseContract(value, match.route.options);
+    return await projectAndRunAfterHooks(contracted, afterHooks, context);
+  } catch (error) {
+    return handleError(error, errorHooks, context);
+  }
+}
+
+async function applyRequestContracts(context, options, config = {}) {
+  context.params = applyNamedRequestContract('Params', options.params, context.params);
+  context.query = applyNamedRequestContract('Query', options.query, context.query);
+  context.headers = applyNamedRequestContract('Headers', options.headers, context.headers);
+
+  if (options.body && config.body !== false) {
+    try {
+      context.body = await parseContractBody(context.request, options.body);
+    } catch (error) {
+      throw error;
+    }
+  }
+}
+
+function applyResponseContract(value, options) {
+  if (!options.response) return value;
+  if (value instanceof Response) return value;
+  if (isRedirectResponse(value)) return value;
+
+  try {
+    const body = responseBody(value);
+    const contractedBody = applyContract(options.response, body);
+    return replaceResponseBody(value, contractedBody);
+  } catch (error) {
+    return fail(createContractFailure('response', 'Response failed contract validation', error, {
+      code: ERROR_CODES.RESPONSE_CONTRACT_FAILED,
+      status: 500
+    }));
+  }
+}
+
+async function runBeforeRequestHooks(hooks, context) {
+  for (const hook of hooks) {
+    const value = await runEffect(hook, context);
+    if (isHookResponse(value)) return value;
+  }
+
+  return undefined;
+}
+
+async function projectAndRunAfterHooks(value, hooks, context) {
+  let response = toResponse(value);
+
+  for (const hook of hooks) {
+    const replacement = await runEffect(hook, context, response);
+    if (isHookResponse(replacement)) response = toResponse(replacement);
+  }
+
+  return response;
+}
+
+async function handleError(error, hooks, context) {
+  const normalized = normalizeFrameworkError(error);
+
+  for (const hook of hooks) {
+    try {
+      const replacement = await runEffect(hook, context, normalized);
+      if (isHookResponse(replacement)) return toResponse(replacement);
+    } catch (hookError) {
+      return toResponse(hookError);
+    }
+  }
+
+  return toResponse(fail(normalized));
+}
+
+function methodNotAllowedResponse(allowed) {
+  const response = toResponse(fail(createFrameworkError(ERROR_CODES.METHOD_NOT_ALLOWED, 'Route matched the path, but not the request method', { status: 405, expose: true })));
+  response.headers.set('allow', allowed.join(', '));
+  return response;
+}
+
+function isHookResponse(value) {
+  return value instanceof Response || isResponseDescriptor(value) || isResult(value);
+}
+
+function isResult(value) {
+  return Boolean(value && typeof value === 'object' && typeof value.ok === 'boolean' && 'value' in value && 'error' in value && 'meta' in value);
+}

package/src/kernel/context.js

@@ -0,0 +1,37 @@
+export function createRequestContext(request, match, appState = null) {
+  const url = new URL(request.url);
+
+  return {
+    request: request,
+    method: request.method,
+    url: url,
+    path: url.pathname,
+    params: match.params || {},
+    query: queryObject(url.searchParams),
+    headers: headersObject(request.headers),
+    body: null,
+    route: match.route,
+    state: appState
+  };
+}
+
+function queryObject(searchParams) {
+  const grouped = {};
+
+  for (const key of Array.from(searchParams.keys()).sort()) {
+    const values = searchParams.getAll(key);
+    grouped[key] = values.length > 1 ? values : values[0];
+  }
+
+  return grouped;
+}
+
+function headersObject(headers) {
+  const plain = {};
+
+  for (const [key, value] of Array.from(headers.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+    plain[key.toLowerCase()] = value;
+  }
+
+  return plain;
+}

package/src/kernel/contract-projection.js

@@ -0,0 +1,129 @@
+import { normalizeContract } from './contract.js';
+
+export function projectContract(contract) {
+  const adapter = normalizeContract(contract);
+  const rawProjection = adapter.project();
+  const kind = normalizeKind(rawProjection.kind);
+  const capabilities = normalizeCapabilities(rawProjection.capabilities);
+  const schema = projectSchema(adapter.source, kind);
+  const fields = projectFields(adapter.source, kind, schema);
+  const required = projectRequired(adapter.source, kind, schema, fields);
+  const optional = fields && required ? fields.map((field) => field.name).filter((field) => !required.includes(field)) : null;
+
+  return {
+    kind: kind,
+    capabilities: capabilities,
+    capability: capabilityObject(capabilities),
+    opaque: kind !== 'sigil',
+    schema: schema,
+    fields: fields,
+    required: required,
+    optional: optional,
+    meta: null
+  };
+}
+
+function normalizeKind(kind) {
+  if (kind === 'generic-function') return 'function';
+  if (kind === 'generic-parse') return 'parse';
+  if (kind === 'generic-check') return 'check';
+  if (kind === 'sigil') return 'sigil';
+  if (kind === 'none') return 'none';
+  return 'unknown';
+}
+
+function normalizeCapabilities(capabilities) {
+  return Array.isArray(capabilities) ? capabilities.map(normalizeCapability).filter(Boolean) : [];
+}
+
+function normalizeCapability(capability) {
+  if (capability === 'safeParse' || capability === 'describe') return null;
+  if (capability === 'project') return 'project';
+  if (capability === 'parse') return 'parse';
+  if (capability === 'check') return 'check';
+  return String(capability || '') || null;
+}
+
+function capabilityObject(capabilities) {
+  return {
+    parse: capabilities.includes('parse'),
+    check: capabilities.includes('check'),
+    project: capabilities.includes('project')
+  };
+}
+
+function projectSchema(contract, kind) {
+  if (kind !== 'sigil') return null;
+
+  if (contract && typeof contract.toJSONSchema === 'function') {
+    return contract.toJSONSchema();
+  }
+
+  return null;
+}
+
+function projectFields(contract, kind, schema) {
+  if (kind !== 'sigil') return null;
+
+  const described = describeContract(contract);
+  if (described && Array.isArray(described.properties)) {
+    return described.properties.map(projectDescribedProperty).filter(Boolean);
+  }
+
+  if (schema && schema.properties && typeof schema.properties === 'object') {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    return Object.keys(schema.properties).map((name) => ({
+      name: name,
+      required: required.includes(name),
+      kind: typeof schema.properties[name]?.type === 'string' ? schema.properties[name].type : 'unknown',
+      fields: null
+    }));
+  }
+
+  return null;
+}
+
+function projectRequired(contract, kind, schema, fields) {
+  if (kind !== 'sigil') return null;
+
+  const described = describeContract(contract);
+  if (described && Array.isArray(described.properties)) {
+    return described.properties.filter((property) => property.required === true).map((property) => property.key).filter((key) => typeof key === 'string');
+  }
+
+  if (schema && Array.isArray(schema.required)) {
+    return schema.required.slice();
+  }
+
+  return fields ? fields.filter((field) => field.required).map((field) => field.name) : null;
+}
+
+function projectDescribedProperty(property) {
+  if (!property || typeof property.key !== 'string') return null;
+
+  return {
+    name: property.key,
+    required: property.required === true,
+    kind: describedKind(property.contract),
+    fields: describedFields(property.contract)
+  };
+}
+
+function describedFields(contract) {
+  if (!contract || !Array.isArray(contract.properties)) return null;
+  return contract.properties.map(projectDescribedProperty).filter(Boolean);
+}
+
+function describedKind(contract) {
+  if (!contract || typeof contract.kind !== 'string') return 'unknown';
+  return contract.kind;
+}
+
+function describeContract(contract) {
+  if (!contract || typeof contract.describe !== 'function') return null;
+  try {
+    return contract.describe();
+  } catch {
+    return null;
+  }
+}

package/src/kernel/contract.js

@@ -0,0 +1,135 @@
+import { createFrameworkError, ERROR_CODES } from './error.js';
+import { createRootIssue, sigilIssueFromError } from './diagnostics.js';
+
+export function normalizeContract(contract) {
+  if (!contract) {
+    return createAdapter('none', contract, (value) => value, () => ({ kind: 'none', capabilities: [] }));
+  }
+
+  if (typeof contract === 'function') {
+    return createAdapter('generic-function', contract, contract, () => ({ kind: 'generic-function', capabilities: ['parse'] }));
+  }
+
+  if (isSigilContract(contract)) {
+    return createAdapter('sigil', contract, (value) => contract.parse(value), () => projectSigilContract(contract));
+  }
+
+  if (contract && typeof contract.parse === 'function') {
+    const capabilities = ['parse'];
+    if (typeof contract.check === 'function') capabilities.push('check');
+    return createAdapter('generic-parse', contract, (value, context) => contract.parse(value, context), () => ({ kind: 'generic-parse', capabilities: capabilities }));
+  }
+
+  if (contract && typeof contract.check === 'function') {
+    return createAdapter('generic-check', contract, (value, context) => {
+      if (!contract.check(value, context)) {
+        const error = new Error('Contract check returned false');
+        error.code = 'POTENTIA_CONTRACT_CHECK_FALSE';
+        throw error;
+      }
+      return value;
+    }, () => ({ kind: 'generic-check', capabilities: ['check'] }));
+  }
+
+  return createAdapter('unknown', contract, (value) => value, () => ({ kind: 'unknown', capabilities: [] }));
+}
+
+export function applyContract(contract, value, context = {}) {
+  const adapter = normalizeContract(contract);
+  return adapter.parse(value, context);
+}
+
+export function applyContractResult(contract, value, context = {}) {
+  try {
+    return {
+      ok: true,
+      value: applyContract(contract, value, context),
+      error: null
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      value: null,
+      error: createContractFailure(context.boundary || 'contract', 'Contract failed', error)
+    };
+  }
+}
+
+export async function parseContractBody(request, contract) {
+  if (!contract) return null;
+
+  const value = await request.json();
+  try {
+    return applyContract(contract, value, { boundary: 'body' });
+  } catch (error) {
+    throw createContractFailure('body', 'Request body failed contract validation', error);
+  }
+}
+
+export function applyNamedRequestContract(name, contract, value) {
+  if (!contract) return value;
+
+  const boundary = name.toLowerCase();
+  try {
+    return applyContract(contract, value, { boundary: boundary });
+  } catch (error) {
+    throw createContractFailure(boundary, `${name} failed contract validation`, error);
+  }
+}
+
+export function createContractFailure(boundary, message, cause, options = {}) {
+  return createFrameworkError(options.code || ERROR_CODES.CONTRACT_FAILED, message, {
+    status: options.status || 400,
+    detail: {
+      boundary: boundary,
+      issues: safeContractIssues(cause, boundary)
+    },
+    cause: cause,
+    expose: true
+  });
+}
+
+export function isSigilContract(contract) {
+  return Boolean(
+    contract &&
+    typeof contract === 'object' &&
+    typeof contract.parse === 'function' &&
+    typeof contract.safeParse === 'function' &&
+    typeof contract.toJSONSchema === 'function' &&
+    typeof contract.describe === 'function' &&
+    Object.prototype.hasOwnProperty.call(contract, 'ast')
+  );
+}
+
+function createAdapter(kind, source, parse, project) {
+  return {
+    kind: kind,
+    source: source,
+    parse: parse,
+    project: project,
+    describe: function describe() {
+      return project();
+    }
+  };
+}
+
+function projectSigilContract(contract) {
+  return {
+    kind: 'sigil',
+    capabilities: ['parse', 'check', 'safeParse', 'describe', 'project'],
+    name: typeof contract.name === 'string' ? contract.name : null,
+    source: typeof contract.source === 'string' ? contract.source : null
+  };
+}
+
+function safeContractIssues(cause, boundary) {
+  if (cause && typeof cause === 'object' && cause.code === 'SIGIL_VALIDATION_FAILED') {
+    return [sigilIssueFromError(cause, boundary)];
+  }
+
+  if (cause && typeof cause === 'object' && cause.code === 'POTENTIA_CONTRACT_CHECK_FALSE') {
+    return [createRootIssue({ code: 'check_failed', message: 'Contract check returned false', boundary: boundary, source: 'generic' })];
+  }
+
+  return [createRootIssue({ code: 'parse_failed', message: 'Contract parser rejected value', boundary: boundary, source: 'generic' })];
+}