@potentiajs/core 0.1.0-preview.0

package/src/kernel/diagnostics.js

@@ -0,0 +1,147 @@
+const KNOWN_SOURCES = new Set(['sigil', 'generic', 'framework', 'unknown']);
+const KNOWN_BOUNDARIES = new Set(['params', 'query', 'headers', 'body', 'response', 'input', 'output', 'handler', 'contract']);
+const SAFE_TYPE_DESCRIPTORS = new Set(['string', 'number', 'boolean', 'null', 'undefined', 'array', 'object', 'function', 'symbol', 'bigint']);
+
+export function normalizeIssue(input = null, options = {}) {
+  if (!input || typeof input !== 'object') {
+    return createRootIssue(options);
+  }
+
+  const path = normalizePath(input.path);
+
+  return {
+    code: safeString(input.code) || safeString(options.code) || 'contract_failed',
+    message: safeString(input.message) || safeString(options.message) || 'Contract rejected value',
+    path: path,
+    field: deriveField(path),
+    boundary: normalizeBoundary(input.boundary, options.boundary),
+    source: normalizeSource(input.source, options.source),
+    expected: safeExpected(Object.prototype.hasOwnProperty.call(input, 'expected') ? input.expected : options.expected),
+    received: safeReceived(Object.prototype.hasOwnProperty.call(input, 'received') ? input.received : options.received),
+    meta: null
+  };
+}
+
+export function normalizeIssues(input = null, options = {}) {
+  const rawIssues = Array.isArray(input) && input.length > 0 ? input : [input];
+  return rawIssues.map((issue) => normalizeIssue(issue, options)).sort(compareIssues);
+}
+
+export function createRootIssue(options = {}) {
+  return {
+    code: safeString(options.code) || 'contract_failed',
+    message: safeString(options.message) || 'Contract rejected value',
+    path: [],
+    field: null,
+    boundary: normalizeBoundary(options.boundary),
+    source: normalizeSource(options.source),
+    expected: safeExpected(options.expected),
+    received: safeReceived(options.received),
+    meta: null
+  };
+}
+
+export function deriveField(path) {
+  const normalized = normalizePath(path);
+  if (normalized.length === 0) return null;
+
+  let field = '';
+  for (const segment of normalized) {
+    if (typeof segment === 'number') {
+      field += `[${segment}]`;
+      continue;
+    }
+
+    field += field.length === 0 ? segment : `.${segment}`;
+  }
+
+  return field || null;
+}
+
+export function normalizePath(path) {
+  if (!Array.isArray(path)) return [];
+
+  return path.filter((segment) => {
+    if (typeof segment === 'string') return segment.length > 0;
+    if (typeof segment === 'number') return Number.isInteger(segment) && segment >= 0;
+    return false;
+  });
+}
+
+export function safeReceived(value) {
+  if (value === undefined) return null;
+  if (value === null) return 'null';
+
+  if (typeof value === 'string') {
+    return SAFE_TYPE_DESCRIPTORS.has(value) ? value : primitiveType(value);
+  }
+
+  return primitiveType(value);
+}
+
+export function safeExpected(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'string') return value.length > 0 && value.length <= 80 ? value : null;
+  if (typeof value === 'function' && typeof value.name === 'string' && value.name.length > 0) return value.name.toLowerCase();
+  return SAFE_TYPE_DESCRIPTORS.has(primitiveType(value)) ? primitiveType(value) : null;
+}
+
+export function sigilIssueFromError(error, boundary) {
+  if (!error || typeof error !== 'object' || error.code !== 'SIGIL_VALIDATION_FAILED') {
+    return createRootIssue({ boundary: boundary, source: 'sigil' });
+  }
+
+  const received = Object.prototype.hasOwnProperty.call(error, 'actual') ? safeReceived(error.actual) : null;
+  const expected = safeExpected(error.expected);
+  const code = expected && received === 'undefined' ? 'missing_required' : expected && received ? 'invalid_type' : 'contract_failed';
+
+  return normalizeIssue({
+    code: code,
+    message: 'SigilJS contract rejected value',
+    path: error.path,
+    boundary: boundary,
+    source: 'sigil',
+    expected: expected,
+    ...(received === null ? {} : { received: received })
+  }, { boundary: boundary, source: 'sigil' });
+}
+
+function normalizeBoundary(value, fallback = null) {
+  const boundary = safeString(value) || safeString(fallback) || 'contract';
+  return KNOWN_BOUNDARIES.has(boundary) ? boundary : 'contract';
+}
+
+function normalizeSource(value, fallback = null) {
+  const source = safeString(value) || safeString(fallback) || 'generic';
+  return KNOWN_SOURCES.has(source) ? source : 'unknown';
+}
+
+function safeString(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function primitiveType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function compareIssues(left, right) {
+  const path = comparePaths(left.path, right.path);
+  if (path !== 0) return path;
+  const code = left.code.localeCompare(right.code);
+  if (code !== 0) return code;
+  return left.message.localeCompare(right.message);
+}
+
+function comparePaths(left, right) {
+  if (left.length !== right.length) return left.length - right.length;
+  for (let index = 0; index < left.length; index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (typeof a === 'number' && typeof b === 'number' && a !== b) return a - b;
+    const compared = String(a).localeCompare(String(b));
+    if (compared !== 0) return compared;
+  }
+  return 0;
+}

package/src/kernel/effect.js

@@ -0,0 +1,119 @@
+export function effect(generatorOrFunction) {
+  return {
+    type: 'effect',
+    run: generatorOrFunction
+  };
+}
+
+export function call(fn, ...args) {
+  return {
+    type: 'call',
+    fn: fn,
+    args: args,
+    meta: null
+  };
+}
+
+export function value(value) {
+  return {
+    type: 'value',
+    value: value,
+    meta: null
+  };
+}
+
+export function context(key) {
+  return {
+    type: 'context',
+    key: key,
+    meta: null
+  };
+}
+
+export async function runEffect(effectValue, context = null, ...args) {
+  if (isEffectDescriptor(effectValue)) {
+    return runEffectFunction(effectValue.run, context, args);
+  }
+
+  if (typeof effectValue === 'function') {
+    return runEffectFunction(effectValue, context, args);
+  }
+
+  return effectValue;
+}
+
+async function runEffectFunction(fn, context, args) {
+  const value = fn(context, ...args);
+
+  if (isIterator(value)) {
+    return runIterator(value, context);
+  }
+
+  return await value;
+}
+
+async function runIterator(iterator, context) {
+  let input = undefined;
+
+  while (true) {
+    const next = iterator.next(input);
+    if (next.done) return await next.value;
+    input = await runCommand(next.value, context);
+  }
+}
+
+async function runCommand(command, context) {
+  if (!command || typeof command !== 'object') return command;
+
+  validateCommand(command);
+
+  if (command.type === 'value') return command.value;
+
+  if (command.type === 'call') {
+    const args = Object.prototype.hasOwnProperty.call(command, 'args') ? command.args : [];
+    return await command.fn(...args);
+  }
+
+  if (command.type === 'context') {
+    return context ? context[command.key] : undefined;
+  }
+
+  throw new Error(`Unsupported effect command type: ${command.type}`);
+}
+
+function validateCommand(command) {
+  if (!Object.prototype.hasOwnProperty.call(command, 'type')) {
+    throw new Error('Invalid effect command: type must be a string');
+  }
+
+  if (typeof command.type !== 'string' || command.type.length === 0) {
+    throw new Error('Invalid effect command: type must be a string');
+  }
+
+  if (command.type === 'value') return;
+
+  if (command.type === 'call') {
+    if (typeof command.fn !== 'function') {
+      throw new Error('Invalid effect call command: fn must be a function');
+    }
+    if (Object.prototype.hasOwnProperty.call(command, 'args') && !Array.isArray(command.args)) {
+      throw new Error('Invalid effect call command: args must be an array when provided');
+    }
+    return;
+  }
+
+  if (command.type === 'context') {
+    if (typeof command.key !== 'string' || command.key.length === 0) {
+      throw new Error('Invalid effect context command: key must be a non-empty string');
+    }
+    return;
+  }
+}
+
+function isEffectDescriptor(value) {
+  return Boolean(value && typeof value === 'object' && value.type === 'effect' && typeof value.run === 'function');
+}
+
+function isIterator(value) {
+  return Boolean(value && typeof value === 'object' && typeof value.next === 'function');
+}

package/src/kernel/error.js

@@ -0,0 +1,93 @@
+export const ERROR_CODES = {
+  NOT_FOUND: 'POTENTIA_NOT_FOUND',
+  METHOD_NOT_ALLOWED: 'POTENTIA_METHOD_NOT_ALLOWED',
+  CONTRACT_FAILED: 'POTENTIA_CONTRACT_FAILED',
+  RESPONSE_CONTRACT_FAILED: 'POTENTIA_RESPONSE_CONTRACT_FAILED',
+  ACTION_INPUT_FAILED: 'POTENTIA_ACTION_INPUT_FAILED',
+  ACTION_OUTPUT_FAILED: 'POTENTIA_ACTION_OUTPUT_FAILED',
+  ACTION_HANDLER_FAILED: 'POTENTIA_ACTION_HANDLER_FAILED',
+  HANDLER_FAILED: 'POTENTIA_HANDLER_FAILED',
+  BAD_REQUEST: 'POTENTIA_BAD_REQUEST'
+};
+
+export function createFrameworkError(code, message, options = {}) {
+  return {
+    name: 'PotentiaError',
+    code: code,
+    message: message,
+    status: Number.isInteger(options.status) ? options.status : statusForCode(code),
+    detail: Object.prototype.hasOwnProperty.call(options, 'detail') ? options.detail : null,
+    cause: Object.prototype.hasOwnProperty.call(options, 'cause') ? options.cause : null,
+    expose: Object.prototype.hasOwnProperty.call(options, 'expose') ? Boolean(options.expose) : defaultExpose(code)
+  };
+}
+
+export function normalizeFrameworkError(error) {
+  if (isFrameworkError(error)) {
+    return createFrameworkError(error.code, visibleMessage(error), {
+      status: error.status,
+      detail: error.detail,
+      cause: error.cause,
+      expose: error.expose
+    });
+  }
+
+  if (error && typeof error === 'object' && typeof error.code === 'string') {
+    const mapped = mapLegacyCode(error.code);
+    return createFrameworkError(mapped, error.message || defaultMessage(mapped), {
+      status: Number.isInteger(error.status) ? error.status : statusForCode(mapped),
+      detail: error.detail ?? error.details ?? null,
+      cause: error.cause ?? null,
+      expose: error.expose ?? defaultExpose(mapped)
+    });
+  }
+
+  return createFrameworkError(ERROR_CODES.HANDLER_FAILED, 'Internal server error', {
+    status: 500,
+    detail: null,
+    cause: error,
+    expose: false
+  });
+}
+
+export function isFrameworkError(error) {
+  return Boolean(error && typeof error === 'object' && error.name === 'PotentiaError' && typeof error.code === 'string');
+}
+
+function visibleMessage(error) {
+  return error.expose ? error.message : defaultMessage(error.code);
+}
+
+function mapLegacyCode(code) {
+  if (code === 'NOT_FOUND') return ERROR_CODES.NOT_FOUND;
+  if (code === 'METHOD_NOT_ALLOWED') return ERROR_CODES.METHOD_NOT_ALLOWED;
+  if (code === 'BAD_REQUEST') return ERROR_CODES.CONTRACT_FAILED;
+  if (code === 'RESPONSE_CONTRACT_FAILED') return ERROR_CODES.RESPONSE_CONTRACT_FAILED;
+  if (code === 'ERROR') return ERROR_CODES.HANDLER_FAILED;
+  return code;
+}
+
+function statusForCode(code) {
+  if (code === ERROR_CODES.NOT_FOUND) return 404;
+  if (code === ERROR_CODES.METHOD_NOT_ALLOWED) return 405;
+  if (code === ERROR_CODES.CONTRACT_FAILED) return 400;
+  if (code === ERROR_CODES.ACTION_INPUT_FAILED) return 400;
+  if (code === ERROR_CODES.BAD_REQUEST) return 400;
+  return 500;
+}
+
+function defaultExpose(code) {
+  return code !== ERROR_CODES.HANDLER_FAILED;
+}
+
+function defaultMessage(code) {
+  if (code === ERROR_CODES.NOT_FOUND) return 'No route matched the request path';
+  if (code === ERROR_CODES.METHOD_NOT_ALLOWED) return 'Route matched the path, but not the request method';
+  if (code === ERROR_CODES.CONTRACT_FAILED) return 'Request failed contract validation';
+  if (code === ERROR_CODES.RESPONSE_CONTRACT_FAILED) return 'Response failed contract validation';
+  if (code === ERROR_CODES.ACTION_INPUT_FAILED) return 'Action input contract failed.';
+  if (code === ERROR_CODES.ACTION_OUTPUT_FAILED) return 'Action output contract failed.';
+  if (code === ERROR_CODES.ACTION_HANDLER_FAILED) return 'Internal server error';
+  if (code === ERROR_CODES.BAD_REQUEST) return 'Bad request';
+  return 'Internal server error';
+}

package/src/kernel/form-projection.js

@@ -0,0 +1,251 @@
+import { isAction } from './action.js';
+import { projectContract } from './contract-projection.js';
+
+const ROOT_ERROR_KEY = '_form';
+const DEFAULT_METHOD = 'POST';
+const DEFAULT_ENCTYPE = 'application/x-www-form-urlencoded';
+const SENSITIVE_SEGMENTS = new Set([
+  'password',
+  'confirmpassword',
+  'currentpassword',
+  'newpassword',
+  'token',
+  'secret',
+  'apikey',
+  'authorization',
+  'auth',
+  'credential',
+  'session',
+  'cookie'
+]);
+
+export function projectForm(value, options = {}) {
+  if (!isAction(value)) {
+    return createFormProjection({
+      id: optionString(options.id, null),
+      actionId: null,
+      method: optionString(options.method, DEFAULT_METHOD),
+      encType: optionString(options.encType, DEFAULT_ENCTYPE),
+      opaque: true,
+      fields: null,
+      reason: 'Input is not an action',
+      meta: null
+    });
+  }
+
+  const contractProjection = value.input ? projectContract(value.input) : null;
+  const fieldResult = projectFieldsFromContractProjection(contractProjection);
+
+  return createFormProjection({
+    id: optionString(options.id, value.id),
+    actionId: value.id,
+    method: optionString(options.method, DEFAULT_METHOD),
+    encType: optionString(options.encType, DEFAULT_ENCTYPE),
+    opaque: fieldResult.opaque,
+    fields: fieldResult.fields,
+    reason: fieldResult.reason,
+    meta: value.meta || null
+  });
+}
+
+export function createFieldProjection(options = {}) {
+  const path = Array.isArray(options.path) ? options.path.slice() : fieldPath(options.name || options.field || '');
+  const field = typeof options.field === 'string' && options.field.length > 0 ? options.field : pathToField(path);
+  const kind = typeof options.kind === 'string' && options.kind.length > 0 ? options.kind : 'unknown';
+  const multiple = Object.prototype.hasOwnProperty.call(options, 'multiple') ? Boolean(options.multiple) : kind === 'array';
+  const sensitive = isSensitiveField(path.length > 0 ? path : field);
+  const input = deriveInputHint({ field: field, path: path, kind: kind, multiple: multiple, sensitive: sensitive });
+
+  return {
+    kind: 'field',
+    name: typeof options.name === 'string' && options.name.length > 0 ? options.name : field,
+    path: path,
+    field: field,
+    label: typeof options.label === 'string' && options.label.length > 0 ? options.label : deriveLabel(field),
+    help: null,
+    placeholder: null,
+    input: input,
+    required: Object.prototype.hasOwnProperty.call(options, 'required') ? Boolean(options.required) : null,
+    multiple: multiple,
+    sensitive: sensitive,
+    options: Array.isArray(options.options) ? options.options : null,
+    defaultValue: null,
+    contract: {
+      kind: typeof options.contractKind === 'string' && options.contractKind.length > 0 ? options.contractKind : 'unknown',
+      expected: kind
+    },
+    meta: null
+  };
+}
+
+export function deriveLabel(field) {
+  if (typeof field !== 'string' || field.length === 0) return '';
+  const leaf = field.replace(/\[[0-9]+\]/g, '').split('.').filter(Boolean).join(' ');
+  return leaf
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+export function deriveInputHint(field, contractSummary = {}) {
+  const normalized = normalizeFieldName(field && field.field ? field.field : '');
+  const kind = field && typeof field.kind === 'string' ? field.kind : contractSummary.expected;
+  const sensitive = Boolean(field && field.sensitive);
+  let type = primitiveInputType(kind);
+  let autocomplete = null;
+
+  if (normalized === 'email') {
+    type = 'email';
+    autocomplete = 'email';
+  } else if (normalized === 'url' || normalized === 'website') {
+    type = 'url';
+  } else if (normalized === 'phone' || normalized === 'tel') {
+    type = 'tel';
+    autocomplete = 'tel';
+  } else if (isPasswordLike(normalized)) {
+    type = 'password';
+    autocomplete = normalized === 'currentpassword' ? 'current-password' : null;
+  } else if (normalized === 'name') {
+    autocomplete = 'name';
+  } else if (normalized === 'username') {
+    autocomplete = 'username';
+  }
+
+  if (sensitive && isPasswordLike(normalized)) type = 'password';
+
+  return {
+    type: type,
+    mode: null,
+    autocomplete: autocomplete
+  };
+}
+
+export function isSensitiveField(pathOrField) {
+  const segments = Array.isArray(pathOrField) ? pathOrField : fieldPath(pathOrField);
+  return segments.some((segment) => typeof segment === 'string' && isSensitiveSegment(segment));
+}
+
+export function projectFieldsFromContractProjection(projection) {
+  if (!projection) return opaqueFields('Action input contract is missing');
+  if (projection.opaque) return opaqueFields('Action input contract is opaque');
+  if (projection.kind !== 'sigil') return opaqueFields('Action input contract is unsupported');
+  if (!Array.isArray(projection.fields)) return opaqueFields('Action input contract fields are unavailable');
+
+  const fields = flattenProjectedFields(projection.fields, [], projection.kind);
+  if (fields.length === 0) return opaqueFields('Action input contract fields are unavailable');
+
+  return { opaque: false, fields: fields, reason: null };
+}
+
+function flattenProjectedFields(fields, parentPath, contractKind) {
+  const result = [];
+  const ordered = Array.isArray(fields) ? fields.slice() : [];
+
+  for (const field of ordered) {
+    if (!field || typeof field.name !== 'string') continue;
+    const path = parentPath.concat(field.name);
+    const kind = typeof field.kind === 'string' ? field.kind : 'unknown';
+
+    if (kind === 'object' && Array.isArray(field.fields) && field.fields.length > 0) {
+      result.push(...flattenProjectedFields(field.fields, path, contractKind));
+      continue;
+    }
+
+    result.push(createFieldProjection({
+      name: pathToField(path),
+      path: path,
+      field: pathToField(path),
+      kind: kind,
+      required: field.required === true,
+      multiple: kind === 'array',
+      contractKind: contractKind
+    }));
+  }
+
+  return result;
+}
+
+function createFormProjection(input) {
+  return {
+    kind: 'form',
+    id: input.id,
+    actionId: input.actionId,
+    method: input.method,
+    encType: input.encType,
+    opaque: input.opaque,
+    fields: input.fields,
+    reason: input.reason,
+    errors: { rootKey: ROOT_ERROR_KEY },
+    values: { preservation: 'safe-parsed-values' },
+    validation: {
+      server: 'authoritative',
+      client: 'projection-only'
+    },
+    redirect: { afterPost: 'explicit-303-recommended' },
+    meta: input.meta
+  };
+}
+
+function opaqueFields(reason) {
+  return { opaque: true, fields: null, reason: reason };
+}
+
+function optionString(value, fallback) {
+  return typeof value === 'string' && value.length > 0 ? value : fallback;
+}
+
+function primitiveInputType(kind) {
+  if (kind === 'number' || kind === 'integer') return 'number';
+  if (kind === 'boolean') return 'checkbox';
+  return 'text';
+}
+
+function isPasswordLike(normalized) {
+  return normalized === 'password' || normalized === 'confirmpassword' || normalized === 'currentpassword' || normalized === 'newpassword';
+}
+
+function isSensitiveSegment(segment) {
+  const normalized = normalizeFieldName(segment);
+  if (SENSITIVE_SEGMENTS.has(normalized)) return true;
+  for (const sensitive of SENSITIVE_SEGMENTS) {
+    if (normalized.includes(sensitive)) return true;
+  }
+  return false;
+}
+
+function fieldPath(field) {
+  if (typeof field !== 'string' || field.length === 0) return [];
+  const path = [];
+  for (const part of field.split('.')) {
+    const match = /^([^\[]+)(?:\[([0-9]+)\])?$/.exec(part);
+    if (!match) {
+      path.push(part);
+      continue;
+    }
+    path.push(match[1]);
+    if (match[2] !== undefined) path.push(Number(match[2]));
+  }
+  return path;
+}
+
+function pathToField(path) {
+  if (!Array.isArray(path) || path.length === 0) return '';
+  let field = '';
+  for (const segment of path) {
+    if (typeof segment === 'number') {
+      field += `[${segment}]`;
+    } else if (field.length === 0) {
+      field = segment;
+    } else {
+      field += `.${segment}`;
+    }
+  }
+  return field;
+}
+
+function normalizeFieldName(value) {
+  return String(value).replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+}