@potentiajs/core 0.1.0-preview.0

package/src/kernel/form-state.js

@@ -0,0 +1,173 @@
+import { createRootIssue, normalizeIssue } from './diagnostics.js';
+
+const DEFAULT_ROOT_KEY = '_form';
+const DEFAULT_SENSITIVE_FIELDS = new Set([
+  'password',
+  'confirmpassword',
+  'currentpassword',
+  'newpassword',
+  'token',
+  'secret',
+  'apikey',
+  'authorization',
+  'auth',
+  'credential',
+  'session',
+  'cookie'
+]);
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+export function createFormState(input = {}) {
+  const normalizedInput = isPlainObject(input) ? input : {};
+  const ok = Object.prototype.hasOwnProperty.call(normalizedInput, 'ok') ? Boolean(normalizedInput.ok) : false;
+  const error = normalizeFormError(normalizedInput.error, ok);
+  const issues = normalizeFormIssues(normalizedInput.issues, ok, error);
+
+  return {
+    ok: ok,
+    kind: 'form',
+    values: preserveFormValues(normalizedInput.values),
+    errors: groupIssuesByField(issues),
+    issues: issues,
+    error: error,
+    value: Object.prototype.hasOwnProperty.call(normalizedInput, 'value') ? normalizedInput.value : null,
+    meta: Object.prototype.hasOwnProperty.call(normalizedInput, 'meta') ? normalizedInput.meta : null
+  };
+}
+
+export function preserveFormValues(input, options = {}) {
+  if (!isPlainObject(input)) return {};
+
+  const sensitiveFields = createSensitiveSet(options.sensitiveFields);
+  const result = {};
+
+  for (const key of Object.keys(input)) {
+    if (!isSafeKey(key) || isSensitiveSegment(key, sensitiveFields)) continue;
+
+    const value = preserveValue(input[key], [key], sensitiveFields, new Set());
+    if (value !== undefined) result[key] = value;
+  }
+
+  return result;
+}
+
+export function groupIssuesByField(issues, options = {}) {
+  if (!Array.isArray(issues) || issues.length === 0) return {};
+
+  const rootKey = typeof options.rootKey === 'string' && options.rootKey.length > 0 ? options.rootKey : DEFAULT_ROOT_KEY;
+  const errors = {};
+
+  for (const issue of issues) {
+    const key = issue && typeof issue === 'object' && typeof issue.field === 'string' && issue.field.length > 0 ? issue.field : rootKey;
+    if (!Array.isArray(errors[key])) errors[key] = [];
+    errors[key].push(issue);
+  }
+
+  return errors;
+}
+
+function normalizeFormIssues(issues, ok, error) {
+  if (Array.isArray(issues) && issues.length > 0) {
+    return issues.map((issue) => normalizeIssue(issue, { boundary: 'input', source: 'framework' }));
+  }
+
+  if (!ok && error) {
+    return [createRootIssue({
+      code: error.code || 'form_failed',
+      message: error.message || 'Form submission failed',
+      boundary: 'handler',
+      source: 'framework'
+    })];
+  }
+
+  return [];
+}
+
+function normalizeFormError(error, ok) {
+  if (ok && !error) return null;
+  if (!error || typeof error !== 'object') {
+    return ok ? null : { code: 'FORM_FAILED', message: 'Form submission failed' };
+  }
+
+  return {
+    code: typeof error.code === 'string' && error.code.length > 0 ? error.code : 'FORM_FAILED',
+    message: typeof error.message === 'string' && error.message.length > 0 ? error.message : 'Form submission failed'
+  };
+}
+
+function preserveValue(value, path, sensitiveFields, seen) {
+  if (isSensitivePath(path, sensitiveFields)) return undefined;
+  if (value === null) return null;
+
+  const type = typeof value;
+  if (type === 'string' || type === 'number' || type === 'boolean') return value;
+  if (type === 'function' || type === 'symbol' || type === 'bigint' || type === 'undefined') return undefined;
+
+  if (Array.isArray(value)) {
+    const preserved = [];
+    for (let index = 0; index < value.length; index += 1) {
+      const item = preserveValue(value[index], path.concat(index), sensitiveFields, seen);
+      if (item !== undefined && isSafeArrayValue(item)) preserved.push(item);
+    }
+    return preserved;
+  }
+
+  if (!isPlainObject(value)) return undefined;
+  if (seen.has(value)) return undefined;
+
+  seen.add(value);
+  const result = {};
+  for (const key of Object.keys(value)) {
+    if (!isSafeKey(key) || isSensitiveSegment(key, sensitiveFields)) continue;
+    const preserved = preserveValue(value[key], path.concat(key), sensitiveFields, seen);
+    if (preserved !== undefined) result[key] = preserved;
+  }
+  seen.delete(value);
+
+  return result;
+}
+
+function isSafeArrayValue(value) {
+  if (value === null) return true;
+  if (Array.isArray(value)) return value.every(isSafeArrayValue);
+  if (isPlainObject(value)) return true;
+  const type = typeof value;
+  return type === 'string' || type === 'number' || type === 'boolean';
+}
+
+function createSensitiveSet(extra = []) {
+  const fields = new Set(DEFAULT_SENSITIVE_FIELDS);
+  if (Array.isArray(extra)) {
+    for (const field of extra) {
+      if (typeof field === 'string' && field.length > 0) fields.add(normalizeFieldName(field));
+    }
+  }
+  return fields;
+}
+
+function isSensitivePath(path, sensitiveFields) {
+  return path.some((segment) => typeof segment === 'string' && isSensitiveSegment(segment, sensitiveFields));
+}
+
+function isSensitiveSegment(segment, sensitiveFields) {
+  const normalized = normalizeFieldName(segment);
+  if (sensitiveFields.has(normalized)) return true;
+  for (const field of sensitiveFields) {
+    if (normalized.includes(field)) return true;
+  }
+  return false;
+}
+
+function normalizeFieldName(value) {
+  return String(value).replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+}
+
+function isSafeKey(key) {
+  return typeof key === 'string' && key.length > 0 && !DANGEROUS_KEYS.has(key);
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/kernel/plugin.js

@@ -0,0 +1,46 @@
+import { createRoutes, normalizeHooks } from './route-collection.js';
+
+export function createPlugin(options = {}) {
+  return {
+    kind: 'plugin',
+    name: typeof options.name === 'string' ? options.name : 'anonymous',
+    routes: Array.isArray(options.routes) ? options.routes.slice() : [],
+    hooks: normalizeHooks(options.hooks),
+    contracts: normalizeContracts(options.contracts),
+    setup: typeof options.setup === 'function' ? options.setup : null,
+    meta: Object.prototype.hasOwnProperty.call(options, 'meta') ? options.meta : null
+  };
+}
+
+export function pluginRoutes(plugins = [], appContext = {}) {
+  if (!Array.isArray(plugins)) return [];
+
+  const routes = [];
+  for (const plugin of plugins) {
+    const normalized = plugin && plugin.kind === 'plugin' ? plugin : createPlugin(plugin);
+    runSetup(normalized, appContext);
+    routes.push(createRoutes({
+      routes: normalized.routes,
+      hooks: normalized.hooks,
+      contracts: normalized.contracts,
+      meta: { plugin: normalized.name }
+    }));
+  }
+
+  return routes;
+}
+
+function runSetup(plugin, appContext) {
+  if (!plugin.setup) return;
+
+  plugin.setup(Object.freeze({
+    name: plugin.name,
+    state: Object.prototype.hasOwnProperty.call(appContext, 'state') ? appContext.state : null,
+    meta: plugin.meta
+  }));
+}
+
+function normalizeContracts(contracts = {}) {
+  if (!contracts || typeof contracts !== 'object') return {};
+  return { ...contracts };
+}

package/src/kernel/response.js

@@ -0,0 +1,187 @@
+import { fail, normalizeError } from './result.js';
+
+export function json(value, init = {}) {
+  return createResponseDescriptor('json', value, init);
+}
+
+export function text(value, init = {}) {
+  return createResponseDescriptor('text', String(value), init);
+}
+
+export function redirect(location, status = 302) {
+  return createResponseDescriptor('redirect', null, {
+    status: status,
+    headers: { location: location }
+  });
+}
+
+export function toResponse(value) {
+  if (value instanceof Response) return value;
+
+  if (isResult(value)) {
+    if (value.ok) return toResponse(value.value);
+    return errorResponse(value.error);
+  }
+
+  if (isResponseDescriptor(value)) {
+    return descriptorToResponse(value);
+  }
+
+  if (value instanceof Error) {
+    return errorResponse(normalizeError(value));
+  }
+
+  if (value && typeof value === 'object' && value.name === 'PotentiaError') {
+    return errorResponse(normalizeError(value));
+  }
+
+  if (value === undefined) {
+    return new Response(null, { status: 204 });
+  }
+
+  if (value === null) {
+    return new Response(null, { status: 204 });
+  }
+
+  if (typeof value === 'string') {
+    return descriptorToResponse(text(value));
+  }
+
+  return descriptorToResponse(json(value));
+}
+
+export function errorResponse(error) {
+  const normalized = normalizeError(error);
+
+  if (normalized.details && typeof normalized.details === 'object' && normalized.details.kind === 'form') {
+    return descriptorToResponse(json(normalized.details, { status: normalized.status }));
+  }
+
+  const diagnosticShaped = hasDiagnosticDetails(normalized) || isActionOrDomainCode(normalized.code);
+  const body = diagnosticShaped ? {
+    ok: false,
+    error: {
+      code: normalized.code,
+      message: normalized.message
+    },
+    boundary: null,
+    issues: []
+  } : {
+    error: {
+      code: normalized.code,
+      message: normalized.message
+    }
+  };
+
+  if (normalized.details && typeof normalized.details === 'object') {
+    if (typeof normalized.details.boundary === 'string') {
+      if (diagnosticShaped) body.boundary = normalized.details.boundary;
+      body.error.boundary = normalized.details.boundary;
+    }
+    if (Array.isArray(normalized.details.issues)) {
+      if (diagnosticShaped) body.issues = normalized.details.issues;
+      body.error.issues = normalized.details.issues;
+    }
+  }
+
+  return descriptorToResponse(json(body, { status: normalized.status }));
+}
+
+function hasDiagnosticDetails(error) {
+  return Boolean(error && error.details && typeof error.details === 'object' && (typeof error.details.boundary === 'string' || Array.isArray(error.details.issues)));
+}
+
+function isActionOrDomainCode(code) {
+  return typeof code === 'string' && (code.startsWith('POTENTIA_ACTION_') || !code.startsWith('POTENTIA_'));
+}
+
+export function internalFailure(error) {
+  return fail(normalizeError(error));
+}
+
+export function isResponseDescriptor(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'response');
+}
+
+export function responseBody(value) {
+  if (isResult(value)) return responseBody(value.value);
+  if (isResponseDescriptor(value)) return value.body;
+  return value;
+}
+
+export function replaceResponseBody(value, body) {
+  if (isResult(value)) {
+    return {
+      ok: value.ok,
+      value: replaceResponseBody(value.value, body),
+      error: value.error,
+      meta: value.meta
+    };
+  }
+
+  if (isResponseDescriptor(value)) {
+    return {
+      kind: value.kind,
+      type: value.type,
+      body: body,
+      status: value.status,
+      headers: value.headers
+    };
+  }
+
+  return body;
+}
+
+export function isRedirectResponse(value) {
+  if (isResult(value)) return value.ok && isRedirectResponse(value.value);
+  return isResponseDescriptor(value) && value.type === 'redirect';
+}
+
+function createResponseDescriptor(type, body, init) {
+  const headers = new Headers(init.headers || {});
+  const status = init.status || (type === 'redirect' ? 302 : 200);
+
+  return {
+    kind: 'response',
+    type: type,
+    body: body,
+    status: status,
+    headers: headers
+  };
+}
+
+function descriptorToResponse(descriptor) {
+  const headers = new Headers(descriptor.headers);
+
+  if (descriptor.type === 'json') {
+    if (!headers.has('content-type')) headers.set('content-type', 'application/json');
+    return new Response(JSON.stringify(descriptor.body), {
+      status: descriptor.status,
+      headers: headers
+    });
+  }
+
+  if (descriptor.type === 'text') {
+    if (!headers.has('content-type')) headers.set('content-type', 'text/plain; charset=utf-8');
+    return new Response(descriptor.body, {
+      status: descriptor.status,
+      headers: headers
+    });
+  }
+
+  if (descriptor.type === 'redirect') {
+    return new Response(null, {
+      status: descriptor.status,
+      headers: headers
+    });
+  }
+
+  return new Response(String(descriptor.body), {
+    status: descriptor.status,
+    headers: headers
+  });
+}
+
+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/result.js

@@ -0,0 +1,45 @@
+import { normalizeFrameworkError } from './error.js';
+
+export function ok(value, meta = null) {
+  return {
+    ok: true,
+    value: value,
+    error: null,
+    meta: meta
+  };
+}
+
+export function fail(error, meta = null) {
+  const normalizedInput = typeof meta === 'number' && error && typeof error === 'object' ? { ...error, status: meta } : error;
+
+  return {
+    ok: false,
+    value: null,
+    error: normalizeError(normalizedInput),
+    meta: typeof meta === 'number' ? null : meta
+  };
+}
+
+export function normalizeError(error) {
+  if (isFormState(error)) {
+    return {
+      code: error.error.code,
+      message: error.error.message,
+      status: Number.isInteger(error.status) ? error.status : 400,
+      details: error
+    };
+  }
+
+  const normalized = normalizeFrameworkError(error);
+
+  return {
+    code: normalized.code,
+    message: normalized.message,
+    status: normalized.status,
+    details: normalized.detail
+  };
+}
+
+function isFormState(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'form' && typeof value.ok === 'boolean' && value.error && typeof value.error === 'object' && typeof value.error.code === 'string');
+}

package/src/kernel/route-collection.js

@@ -0,0 +1,148 @@
+import { route } from './route.js';
+
+export function createRoutes(options = {}) {
+  return {
+    kind: 'routes',
+    prefix: normalizePrefix(options.prefix || ''),
+    routes: Array.isArray(options.routes) ? options.routes.slice() : [],
+    hooks: normalizeHooks(options.hooks),
+    contracts: normalizeContracts(options.contracts),
+    meta: Object.prototype.hasOwnProperty.call(options, 'meta') ? options.meta : null
+  };
+}
+
+export function mount(source, options = {}) {
+  return {
+    kind: 'mount',
+    source: source,
+    prefix: normalizePrefix(options.prefix || ''),
+    hooks: normalizeHooks(options.hooks),
+    contracts: normalizeContracts(options.contracts),
+    meta: Object.prototype.hasOwnProperty.call(options, 'meta') ? options.meta : null
+  };
+}
+
+export function composeRoutes(entries = []) {
+  const routes = Array.isArray(entries) ? entries : [];
+  return flattenRoutes(routes, emptyScope());
+}
+
+function flattenRoutes(entries, scope) {
+  const flattened = [];
+
+  for (const entry of entries) {
+    if (isMount(entry)) {
+      flattened.push(...flattenMounted(entry, scope));
+      continue;
+    }
+
+    if (isRouteCollection(entry)) {
+      flattened.push(...flattenCollection(entry, scope));
+      continue;
+    }
+
+    if (isRoute(entry)) {
+      flattened.push(cloneRoute(entry, scope));
+    }
+  }
+
+  return flattened;
+}
+
+function flattenMounted(entry, scope) {
+  const nextScope = mergeScope(scope, {
+    prefix: entry.prefix,
+    contracts: entry.contracts,
+    hooks: entry.hooks
+  });
+
+  if (isRoute(entry.source)) return [cloneRoute(entry.source, nextScope)];
+  if (isRouteCollection(entry.source)) return flattenCollection(entry.source, nextScope);
+  if (Array.isArray(entry.source)) return flattenRoutes(entry.source, nextScope);
+  return [];
+}
+
+function flattenCollection(collection, scope) {
+  const nextScope = mergeScope(scope, {
+    prefix: collection.prefix,
+    contracts: collection.contracts,
+    hooks: collection.hooks
+  });
+
+  return flattenRoutes(collection.routes, nextScope);
+}
+
+function cloneRoute(source, scope) {
+  const cloned = route(source.method, composePath(scope.prefix, source.path), source.handler, {
+    ...scope.contracts,
+    ...(source.options || {})
+  });
+  cloned.hooks = normalizeHooks(scope.hooks);
+  return cloned;
+}
+
+function emptyScope() {
+  return {
+    prefix: '',
+    contracts: {},
+    hooks: normalizeHooks()
+  };
+}
+
+function mergeScope(parent, child) {
+  const childHooks = normalizeHooks(child.hooks);
+  return {
+    prefix: composePath(parent.prefix, child.prefix || ''),
+    contracts: {
+      ...parent.contracts,
+      ...normalizeContracts(child.contracts)
+    },
+    hooks: {
+      beforeRequest: parent.hooks.beforeRequest.concat(childHooks.beforeRequest),
+      afterResponse: childHooks.afterResponse.concat(parent.hooks.afterResponse),
+      onError: childHooks.onError.concat(parent.hooks.onError)
+    }
+  };
+}
+
+export function normalizeHooks(hooks = {}) {
+  return {
+    beforeRequest: Array.isArray(hooks.beforeRequest) ? hooks.beforeRequest.slice() : [],
+    afterResponse: Array.isArray(hooks.afterResponse) ? hooks.afterResponse.slice() : [],
+    onError: Array.isArray(hooks.onError) ? hooks.onError.slice() : []
+  };
+}
+
+function normalizeContracts(contracts = {}) {
+  if (!contracts || typeof contracts !== 'object') return {};
+  return { ...contracts };
+}
+
+function normalizePrefix(prefix) {
+  if (!prefix) return '';
+  const normalized = `/${String(prefix).split('/').filter(Boolean).join('/')}`;
+  return normalized === '/' ? '' : normalized;
+}
+
+function composePath(prefix, path) {
+  const parts = [];
+  for (const value of [prefix, path]) {
+    const segment = String(value || '').split('/').filter(Boolean).join('/');
+    if (segment) parts.push(segment);
+  }
+
+  if (parts.length === 0) return '/';
+  return `/${parts.join('/')}`;
+}
+
+function isMount(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'mount');
+}
+
+function isRouteCollection(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'routes' && Array.isArray(value.routes));
+}
+
+function isRoute(value) {
+  return Boolean(value && typeof value === 'object' && typeof value.method === 'string' && typeof value.path === 'string' && Object.prototype.hasOwnProperty.call(value, 'handler'));
+}

package/src/kernel/route-id.js

@@ -0,0 +1,11 @@
+export function createRouteId(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (typeof value.method !== 'string' || typeof value.path !== 'string') return null;
+
+  return `${String(value.method).toUpperCase()} ${normalizeRoutePath(value.path)}`;
+}
+
+export function normalizeRoutePath(path) {
+  const normalized = `/${String(path || '').split('/').filter(Boolean).join('/')}`;
+  return normalized === '' ? '/' : normalized;
+}