@rippling/rippling-sdk 0.2.0-alpha.83 → 0.2.0-alpha.85

package/src/core/platform/custom-objects/validation.ts

@@ -1,573 +0,0 @@
-import type {
-  AnyCustomObjectDefinition,
-  AnyFieldDefinition,
-  CreateInput,
-  FieldNames,
-  LookupReference,
-  LogicalCategoryName,
-  LogicalCustomFieldName,
-  LogicalCustomObjectName,
-  RecordShape,
-  UpdateInput,
-} from './types';
-
-/** Single validation failure returned by schema or record validators. */
-export interface ValidationIssue {
-  readonly path: string;
-  readonly message: string;
-}
-
-/** Aggregate validation result returned by runtime validation helpers. */
-export interface ValidationResult {
-  readonly valid: boolean;
-  readonly issues: readonly ValidationIssue[];
-}
-
-/** Exact runtime regex used to validate logical snake_case names. */
-const LOGICAL_NAME_PATTERN = /^[a-z](?:[a-z0-9_]*[a-z0-9])?$/;
-
-/**
- * Builds a single validation issue object.
- *
- * @param path - Logical path identifying the invalid field or property.
- * @param message - Human-readable validation failure message.
- * @returns Structured validation issue object.
- */
-function issue(path: string, message: string): ValidationIssue {
-  return { path, message };
-}
-
-const AUTONUMBER_PLACEHOLDER_PATTERN = /\{(0+)\}/g;
-const AUTONUMBER_DATE_TOKENS = ['{YYYY}', '{MM}', '{DD}'] as const;
-
-/**
- * Validates autonumber metadata against the live backend rules.
- *
- * @param format - Autonumber format string to validate.
- * @param startingNumber - Optional starting number supplied by the caller.
- * @param pathPrefix - Validation path prefix used in returned issues.
- * @returns Validation issues describing any invalid autonumber metadata.
- */
-function validateAutonumberNameField(
-  format: string,
-  startingNumber: number | undefined,
-  pathPrefix: string,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const trimmedFormat = format.trim();
-  if (trimmedFormat.length === 0) {
-    issues.push(issue(`${pathPrefix}.format`, 'Autonumber format cannot be empty.'));
-    return issues;
-  }
-
-  const placeholders = Array.from(trimmedFormat.matchAll(AUTONUMBER_PLACEHOLDER_PATTERN));
-  if (placeholders.length !== 1) {
-    issues.push(
-      issue(`${pathPrefix}.format`, 'Autonumber format must contain exactly one {0...} placeholder.'),
-    );
-  }
-
-  const placeholderDigits = placeholders[0]?.[1];
-  const placeholderWidth = placeholderDigits?.length;
-  if (placeholderWidth != null && (placeholderWidth < 1 || placeholderWidth > 10)) {
-    issues.push(
-      issue(`${pathPrefix}.format`, 'Autonumber placeholder width must be between 1 and 10 digits.'),
-    );
-  }
-
-  if (startingNumber == null) {
-    issues.push(
-      issue(`${pathPrefix}.startingNumber`, 'startingNumber is required for autonumber name fields.'),
-    );
-  } else if (!Number.isInteger(startingNumber) || startingNumber < 0) {
-    issues.push(issue(`${pathPrefix}.startingNumber`, 'startingNumber must be a non-negative integer.'));
-  }
-
-  for (const token of AUTONUMBER_DATE_TOKENS) {
-    const occurrences = trimmedFormat.split(token).length - 1;
-    if (occurrences > 1) {
-      issues.push(issue(`${pathPrefix}.format`, `${token} may appear at most once in autonumber format.`));
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Returns whether one value is a plain object-like record.
- *
- * @param value - Candidate value to inspect.
- * @returns Whether the value is a non-array object.
- */
-function isObject(value: unknown): value is Record<string, unknown> {
-  return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-
-/**
- * Validates a logical snake_case name at runtime.
- *
- * Assumptions enforced by this helper:
- * - the name must be lowercase snake_case
- * - the name must not already include the platform-managed `__c` suffix
- * - the name must not contain consecutive underscores
- */
-/**
- * Validates one logical snake_case name at runtime.
- *
- * @param value - Candidate logical name to validate.
- * @param path - Validation path to use in returned issues.
- * @returns Validation issues describing any logical-name contract violations.
- */
-function validateLogicalName(value: string, path: string): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  if (value.endsWith('__c')) {
-    issues.push(issue(path, 'Logical names must be unsuffixed; do not include __c.'));
-  }
-  if (!LOGICAL_NAME_PATTERN.test(value)) {
-    issues.push(issue(path, 'Logical names must be snake_case and start with a lowercase letter.'));
-  }
-  if (value.includes('__')) {
-    issues.push(issue(path, 'Logical names must not contain consecutive underscores.'));
-  }
-  return issues;
-}
-
-/**
- * Throws when a logical custom-object name is invalid.
- *
- * @param value - Candidate logical custom-object name to validate.
- * @typeParam TObjectName - Candidate logical custom-object name.
- */
-export function validateLogicalCustomObjectName<TObjectName extends string>(
-  value: LogicalCustomObjectName<TObjectName> | string,
-): asserts value is LogicalCustomObjectName<TObjectName> {
-  const issues = validateLogicalName(value, 'name');
-  if (issues.length === 0) return;
-  throw new Error(issues.map((current) => `${current.path}: ${current.message}`).join('\n'));
-}
-
-/**
- * Throws when a logical category name is invalid.
- *
- * @param value - Candidate logical category name to validate.
- * @typeParam TCategoryName - Candidate logical category name.
- */
-export function validateLogicalCategoryName<TCategoryName extends string>(
-  value: LogicalCategoryName<TCategoryName> | string,
-): asserts value is LogicalCategoryName<TCategoryName> {
-  const issues = validateLogicalName(value, 'category');
-  if (issues.length === 0) return;
-  throw new Error(issues.map((current) => `${current.path}: ${current.message}`).join('\n'));
-}
-
-/**
- * Throws when a logical custom-field name is invalid.
- *
- * @param value - Candidate logical custom-field name to validate.
- * @typeParam TFieldName - Candidate logical custom-field name.
- */
-export function validateLogicalCustomFieldName<TFieldName extends string>(
-  value: LogicalCustomFieldName<TFieldName> | string,
-): asserts value is LogicalCustomFieldName<TFieldName> {
-  const issues = validateLogicalName(value, 'field');
-  if (issues.length === 0) return;
-  throw new Error(issues.map((current) => `${current.path}: ${current.message}`).join('\n'));
-}
-
-/**
- * Recognizes lookup values accepted by the typed helpers.
- *
- * Assumption: callers either pass a bare id string or a small `{ id, apiName? }`
- * object. The validator does not attempt to resolve the referenced record.
- */
-/**
- * Recognizes lookup references accepted by the typed helpers.
- *
- * @param value - Candidate field value.
- * @returns Whether the value is a string id or `{ id, apiName? }` lookup reference.
- */
-function isLookupReference(value: unknown): value is LookupReference<string> {
-  return (
-    typeof value === 'string' ||
-    (isObject(value) &&
-      typeof value['id'] === 'string' &&
-      (value['apiName'] == null || typeof value['apiName'] === 'string'))
-  );
-}
-
-/**
- * Recognizes file references accepted by the typed helpers.
- *
- * @param value - Candidate field value.
- * @returns Whether the value is a file id string or `{ id }` object.
- */
-function isFileReference(value: unknown): boolean {
-  return typeof value === 'string' || (isObject(value) && typeof value['id'] === 'string');
-}
-
-/**
- * Returns the number of decimal places represented by a finite JavaScript number.
- *
- * @param value - Numeric value to inspect.
- * @returns Decimal-place count after accounting for exponent notation.
- */
-function countDecimalPlaces(value: number): number {
-  if (!Number.isFinite(value)) return 0;
-  const normalized = value.toString().toLowerCase();
-  if (!normalized.includes('e')) {
-    const fraction = normalized.split('.')[1];
-    return fraction?.length ?? 0;
-  }
-
-  const [coefficient, exponentText] = normalized.split('e');
-  const exponent = Number(exponentText);
-  const coefficientFractionLength = coefficient?.split('.')[1]?.length ?? 0;
-  return Math.max(0, coefficientFractionLength - exponent);
-}
-
-/**
- * Validates one field value against the field-definition kind metadata.
- *
- * Assumption: this helper intentionally performs shape and primitive checks only.
- * It does not attempt to execute formulas, validate RQL, or verify that lookup
- * ids point at existing records.
- */
-/**
- * Validates one field value against the field-definition kind metadata.
- *
- * @param field - Typed field definition that owns the value.
- * @param value - Candidate runtime value to validate.
- * @param path - Validation path to use in returned issues.
- * @returns Validation issues describing any mismatches.
- */
-function validateFieldValue(field: AnyFieldDefinition, value: unknown, path: string): ValidationIssue[] {
-  switch (field.kind) {
-    case 'text':
-    case 'long-text':
-    case 'formula-text': {
-      if (typeof value !== 'string') return [issue(path, 'Expected a string.')];
-      return field.maxLength != null && value.length > field.maxLength ?
-          [issue(path, `Expected at most ${field.maxLength} characters.`)]
-        : [];
-    }
-    case 'email':
-    case 'url':
-    case 'phone':
-    case 'radio':
-    case 'formula-url':
-      if (typeof value !== 'string') return [issue(path, 'Expected a string.')];
-      if (field.kind === 'radio' && !field.options.includes(value)) {
-        return [issue(path, `Expected one of: ${field.options.join(', ')}.`)];
-      }
-      return [];
-    case 'number':
-    case 'currency':
-    case 'percentage':
-    case 'formula-number':
-    case 'formula-currency':
-    case 'formula-percentage': {
-      if (typeof value !== 'number') return [issue(path, 'Expected a number.')];
-      if (!Number.isFinite(value)) return [issue(path, 'Expected a finite number.')];
-      if ('decimalPlaces' in field && typeof field.decimalPlaces === 'number') {
-        return countDecimalPlaces(value) > field.decimalPlaces ?
-            [issue(path, `Expected at most ${field.decimalPlaces} decimal places.`)]
-          : [];
-      }
-      return [];
-    }
-    case 'date':
-    case 'datetime':
-    case 'time':
-    case 'formula-date':
-      return typeof value === 'string' ? [] : [issue(path, 'Expected an ISO-like date/time string.')];
-    case 'boolean':
-    case 'formula-boolean':
-      return typeof value === 'boolean' ? [] : [issue(path, 'Expected a boolean.')];
-    case 'select':
-      if (!(Array.isArray(value) && value.every((entry) => typeof entry === 'string'))) {
-        return [issue(path, 'Expected an array of strings.')];
-      }
-      return value.every((entry) => field.options.includes(entry)) ?
-          []
-        : [issue(path, `Expected each value to be one of: ${field.options.join(', ')}.`)];
-    case 'file':
-      return isFileReference(value) ? [] : [issue(path, 'Expected a file id string or { id } object.')];
-    case 'lookup':
-    case 'parent-child':
-      return isLookupReference(value) ? [] : [issue(path, 'Expected a record id string or { id } object.')];
-  }
-}
-
-/**
- * Returns the logical field names defined on a schema object.
- *
- * @typeParam TDefinition - Object definition whose field names should be listed.
- */
-/**
- * Returns the logical field names defined on one schema object.
- *
- * @param definition - Object definition whose field names should be listed.
- * @returns Logical field names from the supplied definition.
- * @typeParam TDefinition - Object definition whose field names should be listed.
- */
-function definedFieldNames<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-): FieldNames<TDefinition>[] {
-  return Object.keys(definition.fields) as FieldNames<TDefinition>[];
-}
-
-/**
- * Validates a schema definition after the type system has done its part.
- *
- * @param definition - Typed object definition to validate at runtime.
- * @returns Validation issues describing any remaining runtime-level problems.
- */
-export function validateCustomObjectDefinition(definition: AnyCustomObjectDefinition): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  issues.push(...validateLogicalName(definition.name, 'name'));
-  issues.push(...validateLogicalName(definition.category, 'category'));
-
-  if (!definition.apiName.endsWith('__c')) {
-    issues.push(issue('apiName', 'Compiled custom-object api names must end with __c.'));
-  }
-  if (!definition.categoryApiName.endsWith('__c')) {
-    issues.push(issue('categoryApiName', 'Compiled category api names must end with __c.'));
-  }
-  if (definition.categoryDefinition != null) {
-    if (definition.categoryDefinition.name !== definition.category) {
-      issues.push(issue('categoryDefinition.name', 'categoryDefinition.name must match category.'));
-    }
-    if (definition.categoryDefinition.apiName !== definition.categoryApiName) {
-      issues.push(
-        issue('categoryDefinition.apiName', 'categoryDefinition.apiName must match categoryApiName.'),
-      );
-    }
-  }
-  if (definition.ownerRole != null && typeof definition.ownerRole !== 'string') {
-    issues.push(issue('ownerRole', 'ownerRole must be a role id string.'));
-  }
-  if (definition.enableHistory != null && typeof definition.enableHistory !== 'boolean') {
-    issues.push(issue('enableHistory', 'enableHistory must be a boolean when provided.'));
-  }
-  if (definition.nameField.kind === 'autonumber') {
-    issues.push(
-      ...validateAutonumberNameField(
-        definition.nameField.format,
-        definition.nameField.startingNumber,
-        'nameField',
-      ),
-    );
-  }
-
-  const knownSections = new Set(Object.keys(definition.sections));
-  for (const [logicalFieldName, rawField] of Object.entries(definition.fields)) {
-    const field = rawField as AnyFieldDefinition & { apiName?: string; logicalName?: string };
-    issues.push(...validateLogicalName(logicalFieldName, `fields.${logicalFieldName}`));
-    if (field.apiName == null || !field.apiName.endsWith('__c')) {
-      issues.push(
-        issue(`fields.${logicalFieldName}.apiName`, 'Compiled custom-field api names must end with __c.'),
-      );
-    }
-    if (field.logicalName !== logicalFieldName) {
-      issues.push(
-        issue(`fields.${logicalFieldName}.logicalName`, 'Field logicalName must match the field map key.'),
-      );
-    }
-    if (field.section != null && !knownSections.has(field.section)) {
-      issues.push(issue(`fields.${logicalFieldName}.section`, `Unknown section key "${field.section}".`));
-    }
-    if (field.enableHistory != null && typeof field.enableHistory !== 'boolean') {
-      issues.push(
-        issue(`fields.${logicalFieldName}.enableHistory`, 'enableHistory must be a boolean when provided.'),
-      );
-    }
-    if ((field.kind === 'select' || field.kind === 'radio') && field.options.length === 0) {
-      issues.push(
-        issue(`fields.${logicalFieldName}.options`, 'Choice fields must define at least one option.'),
-      );
-    }
-    if (field.kind === 'formula-text' && (field.maxLength == null || field.maxLength <= 0)) {
-      issues.push(
-        issue(`fields.${logicalFieldName}.maxLength`, 'Text formula fields require a positive maxLength.'),
-      );
-    }
-    if ('maxLength' in field && typeof field.maxLength === 'number' && field.maxLength <= 0) {
-      issues.push(issue(`fields.${logicalFieldName}.maxLength`, 'maxLength must be positive.'));
-    }
-    if ('decimalPlaces' in field && typeof field.decimalPlaces === 'number' && field.decimalPlaces < 0) {
-      issues.push(issue(`fields.${logicalFieldName}.decimalPlaces`, 'decimalPlaces cannot be negative.'));
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Shared implementation for create and update validation.
- *
- * @typeParam TDefinition - Object definition whose record payload is being validated.
- */
-/**
- * Shared implementation for create and update payload validation.
- *
- * @param definition - Object definition whose payload is being validated.
- * @param input - Candidate logical payload to validate.
- * @param mode - Validation mode determining create-vs-update requirements.
- * @returns Validation issues describing any payload problems.
- * @typeParam TDefinition - Object definition whose record payload is being validated.
- */
-function validateRecordInputInternal<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-  input: Record<string, unknown>,
-  mode: 'create' | 'update',
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const fields = definition.fields as Record<string, AnyFieldDefinition>;
-  const names = definedFieldNames(definition);
-  const knownFieldNames = new Set(names);
-  const writableFieldNames = new Set(names.filter((name) => fields[name]!.writable) as readonly string[]);
-
-  if (mode === 'create' && definition.nameField.kind !== 'autonumber' && typeof input['name'] !== 'string') {
-    issues.push(issue('name', 'name is required when the object does not use an autonumber name field.'));
-  }
-  if (input['name'] != null && typeof input['name'] !== 'string') {
-    issues.push(issue('name', 'Expected a string.'));
-  }
-  if (input['external_id'] != null && typeof input['external_id'] !== 'string') {
-    issues.push(issue('external_id', 'Expected a string.'));
-  }
-  if (input['owner_role'] != null && !isLookupReference(input['owner_role'])) {
-    issues.push(issue('owner_role', 'Expected a record id string or { id } object.'));
-  }
-
-  for (const name of names) {
-    const field = fields[name]!;
-    const hasValue = Object.prototype.hasOwnProperty.call(input, name);
-
-    if (mode === 'create' && field.writable && field.required && !hasValue) {
-      issues.push(issue(name, 'Missing required field.'));
-      continue;
-    }
-    if (!hasValue) continue;
-
-    const value = input[name];
-    if (!field.writable) {
-      issues.push(issue(name, 'Read-only fields cannot be written.'));
-      continue;
-    }
-    issues.push(...validateFieldValue(field, value, name));
-  }
-
-  for (const key of Object.keys(input)) {
-    if (key === 'name' || key === 'external_id' || key === 'owner_role') continue;
-    if (!knownFieldNames.has(key as FieldNames<TDefinition>)) {
-      issues.push(issue(key, 'Unknown field.'));
-      continue;
-    }
-    if (!writableFieldNames.has(key)) {
-      issues.push(issue(key, 'Read-only fields cannot be written.'));
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Runtime validator for create payloads derived from a schema definition.
- *
- * @param definition - Object definition whose create payload is being validated.
- * @param input - Candidate create payload expressed with logical field names.
- * @returns Aggregate validation result for the supplied create payload.
- * @typeParam TDefinition - Object definition whose create payload is being validated.
- */
-export function validateCreateInput<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-  input: Record<string, unknown>,
-): ValidationResult {
-  const issues = validateRecordInputInternal(definition, input, 'create');
-  return { valid: issues.length === 0, issues };
-}
-
-/**
- * Runtime validator for update payloads derived from a schema definition.
- *
- * @param definition - Object definition whose update payload is being validated.
- * @param input - Candidate update payload expressed with logical field names.
- * @returns Aggregate validation result for the supplied update payload.
- * @typeParam TDefinition - Object definition whose update payload is being validated.
- */
-export function validateUpdateInput<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-  input: Record<string, unknown>,
-): ValidationResult {
-  const issues = validateRecordInputInternal(definition, input, 'update');
-  return { valid: issues.length === 0, issues };
-}
-
-/**
- * Throws a detailed error when a create payload is invalid.
- *
- * @param definition - Object definition whose create payload is being asserted.
- * @param input - Candidate create payload expressed with logical field names.
- * @typeParam TDefinition - Object definition whose create payload is being asserted.
- */
-export function assertValidCreateInput<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-  input: Record<string, unknown>,
-): asserts input is CreateInput<TDefinition> {
-  const result = validateCreateInput(definition, input);
-  if (result.valid) return;
-  throw new Error(result.issues.map((current) => `${current.path}: ${current.message}`).join('\n'));
-}
-
-/**
- * Throws a detailed error when an update payload is invalid.
- *
- * @param definition - Object definition whose update payload is being asserted.
- * @param input - Candidate update payload expressed with logical field names.
- * @typeParam TDefinition - Object definition whose update payload is being asserted.
- */
-export function assertValidUpdateInput<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-  input: Record<string, unknown>,
-): asserts input is UpdateInput<TDefinition> {
-  const result = validateUpdateInput(definition, input);
-  if (result.valid) return;
-  throw new Error(result.issues.map((current) => `${current.path}: ${current.message}`).join('\n'));
-}
-
-/**
- * Casts a generic record object into the strongly typed shape derived from the
- * schema.
- *
- * This helper does not perform runtime validation by itself; pair it with a
- * schema-aware check when the source data is not trusted.
- *
- * @param _definition - Object definition whose record shape should be applied.
- * @param record - Generic record object to cast into the typed record shape.
- * @returns Record cast to the schema-derived typed record shape.
- * @typeParam TDefinition - Object definition whose record shape should be applied.
- */
-export function asTypedRecord<TDefinition extends AnyCustomObjectDefinition>(
-  _definition: TDefinition,
-  record: Record<string, unknown>,
-): RecordShape<TDefinition> {
-  return record as RecordShape<TDefinition>;
-}
-
-/**
- * Convenience helper for pulling a known field value out of a typed record.
- *
- * @param record - Typed record to read from.
- * @param fieldName - Logical field name to read.
- * @returns Typed value stored at the requested field name.
- * @typeParam TDefinition - Object definition that produced the record shape.
- * @typeParam TFieldName - Logical field name being read from the record.
- */
-export function getRecordValue<
-  TDefinition extends AnyCustomObjectDefinition,
-  TFieldName extends FieldNames<TDefinition>,
->(record: RecordShape<TDefinition>, fieldName: TFieldName): RecordShape<TDefinition>[TFieldName] {
-  return record[fieldName];
-}