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

package/src/core/platform/manifest/custom-objects/register.ts

@@ -1,555 +0,0 @@
-import {
-  BooleanField,
-  Category,
-  CurrencyField,
-  CustomObject,
-  CustomObjectFieldSection,
-  DateField,
-  DatetimeField,
-  EmailField,
-  FileField,
-  FormulaField,
-  LongTextField,
-  LookupField,
-  NumberField,
-  ParentChildField,
-  PercentageField,
-  PhoneField,
-  RadioField,
-  SelectField,
-  TextField,
-  TimeField,
-  UrlField,
-  type ManifestScope,
-} from '../../../../lib/manifest';
-import type { AnyCustomObjectDefinition, AnyFieldDefinition } from '../../custom-objects/types';
-import type { ManifestFieldForDefinition, ManifestRegistration } from './types';
-
-/**
- * Options for {@link registerManifestCustomObject}.
- *
- * @typeParam TDefinition - Object definition being materialized into manifest classes.
- */
-export interface RegisterManifestCustomObjectOptions<TDefinition extends AnyCustomObjectDefinition> {
-  /** Custom-object definition authored through the typed schema layer. */
-  readonly definition: TDefinition;
-  /** Category instance already registered in the manifest. */
-  readonly category: Category;
-  /**
-   * Optional fallback section used by fields that omit an explicit section key.
-   *
-   * Manifest field classes require a concrete `CustomObjectFieldSection`. The
-   * typed definition layer keeps sections optional so teams can reuse schemas in
-   * contexts that do not care about page-layout concerns. When materializing the
-   * schema into manifest components, use this fallback to place section-less
-   * fields somewhere deterministic.
-   */
-  readonly defaultSection?: {
-    readonly name: string;
-    readonly sectionId?: string;
-  };
-  /**
-   * Resolver used for relationship fields that target another custom object.
-   *
-   * Lookup fields can compile from the target api name alone, but parent-child
-   * fields need the concrete manifest {@link CustomObject} instance.
-   */
-  readonly resolveCustomObjectTarget?: (apiName: string) => CustomObject;
-}
-
-/**
- * Options for {@link registerManifestCustomObjects}.
- *
- * @typeParam TDefinitions - Ordered tuple of object definitions being materialized.
- */
-export interface RegisterManifestCustomObjectsOptions<
-  TDefinitions extends readonly AnyCustomObjectDefinition[],
-> {
-  /** Ordered tuple of typed custom-object definitions to register. */
-  readonly definitions: TDefinitions;
-  /** Category instance already registered in the manifest. */
-  readonly category: Category;
-  /** Shared fallback section applied to any definition field that omits `section`. */
-  readonly defaultSection?: {
-    readonly name: string;
-    readonly sectionId?: string;
-  };
-}
-
-interface ManifestRegistrationScaffold<TDefinition extends AnyCustomObjectDefinition> {
-  readonly definition: TDefinition;
-  readonly category: Category;
-  readonly object: CustomObject;
-  readonly sections: ManifestRegistration<TDefinition>['sections'];
-  readonly defaultSection: CustomObjectFieldSection | undefined;
-}
-
-/**
- * Registration tuple returned by {@link registerManifestCustomObjects}.
- *
- * @typeParam TDefinitions - Ordered tuple of object definitions that were registered.
- */
-export type ManifestRegistrationTuple<TDefinitions extends readonly AnyCustomObjectDefinition[]> = {
-  readonly [TIndex in keyof TDefinitions]: TDefinitions[TIndex] extends AnyCustomObjectDefinition ?
-    ManifestRegistration<TDefinitions[TIndex]>
-  : never;
-};
-
-/**
- * Throws when the provided manifest category does not match the typed definition.
- *
- * @param definition - Typed object definition being materialized.
- * @param category - Concrete manifest category provided by the caller.
- */
-function assertMatchingCategory(definition: AnyCustomObjectDefinition, category: Category): void {
-  if (category.getApiName() !== definition.categoryApiName) {
-    throw new Error(
-      `Category mismatch while registering "${definition.name}": ` +
-        `definition expects "${
-          definition.categoryApiName
-        }", but the provided Category is "${category.getApiName()}".`,
-    );
-  }
-}
-
-/**
- * Creates the manifest object instance and concrete sections for one typed definition.
- *
- * Field registration is intentionally deferred so multi-object registration can
- * create every manifest object up front and then resolve parent-child targets in
- * a second pass.
- *
- * @param scope - Manifest scope that should own the created manifest components.
- * @param options - Typed object definition plus manifest-specific registration options.
- * @returns Scaffold containing the object instance, concrete sections, and fallback section.
- * @typeParam TDefinition - Object definition being materialized into manifest classes.
- */
-function createRegistrationScaffold<TDefinition extends AnyCustomObjectDefinition>(
-  scope: ManifestScope,
-  options: Pick<
-    RegisterManifestCustomObjectOptions<TDefinition>,
-    'definition' | 'category' | 'defaultSection'
-  >,
-): ManifestRegistrationScaffold<TDefinition> {
-  const { definition } = options;
-
-  assertMatchingCategory(definition, options.category);
-
-  const objectInstance = new CustomObject(scope, {
-    apiName: definition.apiName,
-    name: definition.displayName,
-    ...(definition.pluralLabel != null ? { pluralLabel: definition.pluralLabel } : {}),
-    category: options.category,
-    description: definition.description,
-    ...(definition.icon != null ? { icon: definition.icon } : {}),
-    ...(definition.nameField.kind === 'autonumber' ?
-      {
-        nameFieldDetails: {
-          is_autonumber_field: true,
-          autonumber_format: definition.nameField.format,
-          ...(definition.nameField.startingNumber != null ?
-            { starting_number: definition.nameField.startingNumber }
-          : {}),
-        },
-      }
-    : {}),
-  });
-
-  const sectionMap = Object.fromEntries(
-    Object.entries(definition.sections).map(([key, sectionDef]) => [
-      key,
-      new CustomObjectFieldSection(objectInstance, {
-        name: sectionDef.name,
-        ...(sectionDef.sectionId != null ? { sectionId: sectionDef.sectionId } : {}),
-      }),
-    ]),
-  ) as ManifestRegistration<TDefinition>['sections'];
-
-  const defaultSection =
-    options.defaultSection == null ?
-      undefined
-    : new CustomObjectFieldSection(objectInstance, {
-        name: options.defaultSection.name,
-        ...(options.defaultSection.sectionId != null ? { sectionId: options.defaultSection.sectionId } : {}),
-      });
-
-  return {
-    definition,
-    category: options.category,
-    object: objectInstance,
-    sections: sectionMap,
-    defaultSection,
-  };
-}
-
-/**
- * Registers the concrete manifest fields for one typed definition.
- *
- * @param scaffold - Previously created registration scaffold.
- * @param resolveCustomObjectTarget - Optional resolver for parent-child targets that need manifest objects.
- * @returns Concrete manifest fields keyed by logical field name.
- * @typeParam TDefinition - Object definition whose fields should be materialized.
- */
-function registerFieldsForScaffold<TDefinition extends AnyCustomObjectDefinition>(
-  scaffold: ManifestRegistrationScaffold<TDefinition>,
-  resolveCustomObjectTarget: ((apiName: string) => CustomObject) | undefined,
-): ManifestRegistration<TDefinition>['fields'] {
-  return Object.fromEntries(
-    Object.entries(scaffold.definition.fields).map(([fieldLogicalName, field]) => [
-      fieldLogicalName,
-      registerField(
-        scaffold.object,
-        fieldLogicalName,
-        field as unknown as AnyFieldDefinition,
-        scaffold.sections,
-        scaffold.defaultSection,
-        resolveCustomObjectTarget,
-      ),
-    ]),
-  ) as ManifestRegistration<TDefinition>['fields'];
-}
-
-/**
- * Translates one typed formula-field discriminant into the low-level manifest formula output type.
- *
- * @param kind - Typed field-kind discriminant already known to be a formula variant.
- * @returns Manifest formula output-type token.
- */
-function formulaFieldType(
-  kind: AnyFieldDefinition['kind'],
-): 'TEXT' | 'NUMBER' | 'BOOLEAN' | 'CURRENCY' | 'PERCENTAGE' | 'DATE' | 'URL' {
-  switch (kind) {
-    case 'formula-text':
-      return 'TEXT';
-    case 'formula-number':
-      return 'NUMBER';
-    case 'formula-boolean':
-      return 'BOOLEAN';
-    case 'formula-currency':
-      return 'CURRENCY';
-    case 'formula-percentage':
-      return 'PERCENTAGE';
-    case 'formula-date':
-      return 'DATE';
-    case 'formula-url':
-      return 'URL';
-    default:
-      throw new Error(`Unsupported formula field kind: ${String(kind)}.`);
-  }
-}
-
-/**
- * Resolves the concrete manifest section instance for one field definition.
- *
- * @param objectInstance - Manifest custom-object instance that owns the field.
- * @param sectionKey - Optional typed section key referenced by the field definition.
- * @param sections - Concrete manifest sections keyed by typed section aliases.
- * @param defaultSection - Optional fallback section for fields that omit `section`.
- * @param fieldLogicalName - Logical field name used for error messages.
- * @returns Concrete manifest section instance.
- * @throws Error when the field has no resolvable section.
- */
-function resolveSection(
-  objectInstance: CustomObject,
-  sectionKey: string | undefined,
-  sections: Readonly<Record<string, CustomObjectFieldSection>>,
-  defaultSection: CustomObjectFieldSection | undefined,
-  fieldLogicalName: string,
-): CustomObjectFieldSection {
-  if (sectionKey != null) {
-    const found = sections[sectionKey];
-    if (found != null) return found;
-    throw new Error(`Unknown section key "${sectionKey}" while registering field "${fieldLogicalName}".`);
-  }
-  if (defaultSection != null) return defaultSection;
-  throw new Error(
-    `Field "${fieldLogicalName}" on "${objectInstance.getApiName()}" has no section. ` +
-      'Either assign a section key in the definition or provide defaultSection when registering the manifest object.',
-  );
-}
-
-/**
- * Instantiates the concrete manifest field class for one typed field definition.
- *
- * @param objectInstance - Manifest custom-object instance that will own the field.
- * @param fieldLogicalName - Logical field name used for error messages.
- * @param field - Typed field definition to materialize.
- * @param sections - Concrete manifest sections keyed by typed section aliases.
- * @param defaultSection - Optional fallback section for fields that omit `section`.
- * @param resolveCustomObjectTarget - Optional resolver for parent-child targets that need manifest objects.
- * @returns Concrete manifest field instance matching the typed field definition.
- */
-function registerField(
-  objectInstance: CustomObject,
-  fieldLogicalName: string,
-  field: AnyFieldDefinition,
-  sections: Readonly<Record<string, CustomObjectFieldSection>>,
-  defaultSection: CustomObjectFieldSection | undefined,
-  resolveCustomObjectTarget: ((apiName: string) => CustomObject) | undefined,
-): ManifestFieldForDefinition<AnyFieldDefinition> {
-  const section = resolveSection(objectInstance, field.section, sections, defaultSection, fieldLogicalName);
-  const apiName = field.apiName ?? `${fieldLogicalName}__c`;
-
-  switch (field.kind) {
-    case 'text':
-      return new TextField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        ...(field.unique != null ? { unique: field.unique } : {}),
-        ...(field.maxLength != null ? { maxLength: field.maxLength } : {}),
-        section,
-      });
-    case 'long-text':
-      return new LongTextField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        ...(field.maxLength != null ? { maxLength: field.maxLength } : {}),
-        section,
-      });
-    case 'email':
-      return new EmailField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        ...(field.unique != null ? { unique: field.unique } : {}),
-        section,
-      });
-    case 'url':
-      return new UrlField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'phone':
-      return new PhoneField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'number':
-      return new NumberField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        ...(field.unique != null ? { unique: field.unique } : {}),
-        ...(field.decimalPlaces != null ? { decimalPlaces: field.decimalPlaces } : {}),
-        section,
-      });
-    case 'currency':
-      return new CurrencyField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        ...(field.currency != null ? { currency: field.currency } : {}),
-        ...(field.decimalPlaces != null ? { decimalPlaces: field.decimalPlaces } : {}),
-        section,
-      });
-    case 'percentage':
-      return new PercentageField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'date':
-      return new DateField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'datetime':
-      return new DatetimeField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'time':
-      return new TimeField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'select':
-      return new SelectField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        options: [...field.options],
-        section,
-      });
-    case 'radio':
-      return new RadioField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        options: [...field.options],
-        section,
-      });
-    case 'boolean':
-      return new BooleanField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        section,
-      });
-    case 'file':
-      return new FileField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        required: field.required,
-        allowedType: field.allowedType,
-        section,
-      });
-    case 'lookup':
-      return new LookupField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        target: field.target.apiName,
-        ...(field.relatedDataLabel != null ? { relatedDataLabel: field.relatedDataLabel } : {}),
-        ...(field.lookupFilterRqlCondition != null ?
-          { lookup_filter_rql_condition: field.lookupFilterRqlCondition }
-        : {}),
-        required: field.required,
-        section,
-      });
-    case 'parent-child': {
-      const target =
-        field.target.apiName === objectInstance.getApiName() ?
-          objectInstance
-        : resolveCustomObjectTarget?.(field.target.apiName);
-      if (target == null) {
-        throw new Error(
-          `Parent-child field "${fieldLogicalName}" targets "${field.target.apiName}", but no manifest CustomObject resolver was provided.`,
-        );
-      }
-      return new ParentChildField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        target,
-        ...(field.relatedDataLabel != null ? { relatedDataLabel: field.relatedDataLabel } : {}),
-        ...(field.parentChildType != null ? { parentChildType: field.parentChildType } : {}),
-        ...(field.enableParentOwnerInheritance != null ?
-          { enableParentOwnerInheritance: field.enableParentOwnerInheritance }
-        : {}),
-        section,
-      });
-    }
-    case 'formula-text':
-    case 'formula-number':
-    case 'formula-boolean':
-    case 'formula-currency':
-    case 'formula-percentage':
-    case 'formula-date':
-    case 'formula-url':
-      return new FormulaField(objectInstance, {
-        apiName,
-        displayName: field.displayName,
-        description: field.description,
-        formula: field.formula,
-        fieldType: formulaFieldType(field.kind),
-        ...(field.kind === 'formula-text' ? { maxLength: field.maxLength } : {}),
-        section,
-      });
-  }
-}
-
-/**
- * Materializes a typed custom-object definition into the existing manifest API.
- *
- * The returned value preserves logical field keys, but each field becomes a
- * concrete manifest class instance (`TextField`, `LookupField`, ...). This lets
- * existing page-layout, list-view, and rule APIs keep working while authors use
- * a cleaner logical-name authoring model.
- *
- * @param scope - Manifest scope that should own the created manifest components.
- * @param options - Typed object definition plus manifest-specific registration options.
- * @returns Frozen manifest registration preserving both typed logical keys and concrete manifest instances.
- * @typeParam TDefinition - Object definition being materialized into manifest classes.
- */
-export function registerManifestCustomObject<TDefinition extends AnyCustomObjectDefinition>(
-  scope: ManifestScope,
-  options: RegisterManifestCustomObjectOptions<TDefinition>,
-): ManifestRegistration<TDefinition> {
-  const scaffold = createRegistrationScaffold(scope, options);
-  const registeredFields = registerFieldsForScaffold(scaffold, options.resolveCustomObjectTarget);
-
-  return Object.freeze({
-    definition: scaffold.definition,
-    category: scaffold.category,
-    object: scaffold.object,
-    sections: Object.freeze(scaffold.sections),
-    fields: Object.freeze(registeredFields),
-  });
-}
-
-/**
- * Materializes multiple typed custom-object definitions into manifest classes in one pass.
- *
- * This helper is the higher-level golden path for multi-object examples: it
- * creates every manifest object and section first, then registers fields in a
- * second pass so parent-child relationships can target objects declared earlier
- * or later in the input tuple.
- *
- * @param scope - Manifest scope that should own the created manifest components.
- * @param options - Ordered tuple of typed object definitions plus shared manifest registration options.
- * @returns Ordered tuple of manifest registrations matching the input definition order.
- * @typeParam TDefinitions - Ordered tuple of object definitions being materialized.
- */
-export function registerManifestCustomObjects<TDefinitions extends readonly AnyCustomObjectDefinition[]>(
-  scope: ManifestScope,
-  options: RegisterManifestCustomObjectsOptions<TDefinitions>,
-): ManifestRegistrationTuple<TDefinitions> {
-  const scaffolds = options.definitions.map((definition) =>
-    createRegistrationScaffold(scope, {
-      definition,
-      category: options.category,
-      ...(options.defaultSection != null ? { defaultSection: options.defaultSection } : {}),
-    }),
-  );
-
-  const objectsByApiName = new Map<string, CustomObject>(
-    scaffolds.map((scaffold) => [scaffold.definition.apiName, scaffold.object]),
-  );
-  const resolveCustomObjectTarget = (apiName: string) => {
-    const objectInstance = objectsByApiName.get(apiName);
-    if (objectInstance == null) {
-      throw new Error(`Missing manifest registration for custom-object target "${apiName}".`);
-    }
-    return objectInstance;
-  };
-
-  return scaffolds.map((scaffold) => {
-    const registeredFields = registerFieldsForScaffold(scaffold, resolveCustomObjectTarget);
-    return Object.freeze({
-      definition: scaffold.definition,
-      category: scaffold.category,
-      object: scaffold.object,
-      sections: Object.freeze(scaffold.sections),
-      fields: Object.freeze(registeredFields),
-    });
-  }) as ManifestRegistrationTuple<TDefinitions>;
-}