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

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

@@ -1,373 +0,0 @@
-import type { CustomObjectCategoryDefinition } from './category';
-import type {
-  AnyCustomObjectDefinition,
-  AnyFieldDefinition,
-  CategoryApiName,
-  CustomObjectApiName,
-  CustomObjectDefinition,
-  FieldDefinitions,
-  FieldNames,
-  LogicalCategoryName,
-  LogicalCustomFieldName,
-  LogicalCustomObjectName,
-  NameFieldDefinition,
-  ResolvedFieldDefinition,
-  SectionDefinitions,
-} from './types';
-import {
-  validateCustomObjectDefinition,
-  validateLogicalCategoryName,
-  validateLogicalCustomFieldName,
-  validateLogicalCustomObjectName,
-} from './validation';
-
-/**
- * Internal input shape accepted by {@link defineCustomObject} before normalization.
- *
- * @typeParam TObjectName - Logical custom-object name for the definition.
- * @typeParam TCategoryName - Logical category name associated with the object.
- * @typeParam TSections - Section map available to field definitions.
- * @typeParam TFields - Field map keyed by logical custom-field names.
- * @typeParam TNameField - Optional name-field behavior supplied by the caller.
- */
-type CategoryInput<TCategoryName extends string> =
-  | LogicalCategoryName<TCategoryName>
-  | CustomObjectCategoryDefinition<LogicalCategoryName<TCategoryName>>;
-
-/**
- * Internal input shape accepted by {@link defineCustomObject} before normalization.
- *
- * @typeParam TObjectName - Logical custom-object name for the definition.
- * @typeParam TCategoryName - Logical category name associated with the object.
- * @typeParam TSections - Section map available to field definitions.
- * @typeParam TFields - Field map keyed by logical custom-field names.
- * @typeParam TNameField - Optional name-field behavior supplied by the caller.
- */
-interface CustomObjectDefinitionInput<
-  TObjectName extends string,
-  TCategoryName extends string,
-  TSections extends SectionDefinitions,
-  TFields extends FieldDefinitions,
-  TNameField extends NameFieldDefinition,
-> {
-  readonly name: LogicalCustomObjectName<TObjectName>;
-  readonly displayName: string;
-  readonly pluralLabel?: string;
-  readonly category: CategoryInput<TCategoryName>;
-  readonly ownerRole?: string;
-  readonly enableHistory?: boolean;
-  readonly description: string;
-  readonly icon?: {
-    readonly emoji?: string | null;
-    readonly ripplingIcon?: string | null;
-    readonly s3Bucket?: string;
-    readonly s3Key?: string;
-  };
-  readonly nameField?: TNameField;
-  readonly sections?: TSections;
-  readonly fields: ValidateFieldMap<TFields>;
-}
-
-/**
- * Rejects extension objects that try to redefine keys already present on the base definition.
- *
- * @typeParam TExisting - Existing key set on the base definition.
- * @typeParam TAdded - Proposed extension object.
- */
-type NoOverlappingKeys<TExisting extends object, TAdded extends object> = Extract<
-  keyof TExisting,
-  keyof TAdded
-> extends never ?
-  TAdded
-: never;
-
-/**
- * Converts a logical field map into a version whose keys must all satisfy the
- * logical custom-field name contract.
- *
- * @typeParam TFields - Candidate logical field map supplied by callers.
- */
-type ValidateFieldMap<TFields extends FieldDefinitions> = {
-  readonly [K in keyof TFields]: K extends string ?
-    LogicalCustomFieldName<K> extends never ?
-      never
-    : TFields[K]
-  : never;
-};
-
-/**
- * Recursively freezes author-authored schema definitions.
- *
- * The schema layer is intended to act like durable configuration data rather
- * than mutable runtime state, so this helper aggressively removes mutation as a
- * failure mode after validation succeeds.
- *
- * @typeParam T - Value being frozen.
- */
-/**
- * Deeply freezes a schema fragment after validation succeeds.
- *
- * @param value - Value to recursively freeze in place.
- * @returns The same value, now deeply frozen where applicable.
- * @typeParam T - Value being frozen.
- */
-function deepFreeze<T>(value: T): T {
-  if (value == null || typeof value !== 'object') return value;
-
-  for (const child of Object.values(value as Record<string, unknown>)) {
-    deepFreeze(child);
-  }
-
-  return Object.freeze(value);
-}
-
-/**
- * Appends the platform-required `__c` suffix to a logical custom-object name.
- *
- * @param name - Logical unsuffixed custom-object name.
- * @returns Wire-level custom-object API name with the required `__c` suffix.
- * @typeParam TObjectName - Logical custom-object name to compile.
- */
-export function toCustomObjectApiName<TObjectName extends string>(
-  name: LogicalCustomObjectName<TObjectName>,
-): CustomObjectApiName<TObjectName> {
-  return `${name}__c` as CustomObjectApiName<TObjectName>;
-}
-
-/**
- * Appends the platform-required `__c` suffix to a logical custom-field name.
- *
- * @param name - Logical unsuffixed custom-field name.
- * @returns Wire-level custom-field API name with the required `__c` suffix.
- * @typeParam TFieldName - Logical custom-field name to compile.
- */
-export function toCustomFieldApiName<TFieldName extends string>(
-  name: LogicalCustomFieldName<TFieldName>,
-): `${TFieldName}__c` {
-  return `${name}__c`;
-}
-
-/**
- * Appends the platform-required `__c` suffix to a logical category name.
- *
- * @param name - Logical unsuffixed category name.
- * @returns Wire-level category API name with the required `__c` suffix.
- * @typeParam TCategoryName - Logical category name to compile.
- */
-export function toCustomCategoryApiName<TCategoryName extends string>(
-  name: LogicalCategoryName<TCategoryName>,
-): CategoryApiName<TCategoryName> {
-  return `${name}__c` as CategoryApiName<TCategoryName>;
-}
-
-/**
- * Defines an immutable, strongly typed custom-object schema.
- *
- * Callers author only logical snake_case names. The returned value includes the
- * derived wire-level api names so downstream tooling can emit valid manifest
- * payloads without requiring authors to know about the `__c` suffix contract.
- *
- * @typeParam TObjectName - Logical custom-object name for the definition.
- * @typeParam TCategoryName - Logical category name associated with the object.
- * @typeParam TSections - Section map available to field definitions.
- * @typeParam TFields - Field map keyed by logical custom-field names.
- * @param definition - Author-facing typed schema definition to normalize, validate, and freeze.
- * @returns Immutable normalized custom-object definition with compiled field and object API names.
- * @typeParam TNameField - Name-field behavior for the object.
- */
-export function defineCustomObject<
-  TObjectName extends string,
-  TCategoryName extends string,
-  TSections extends SectionDefinitions = {},
-  TFields extends FieldDefinitions = FieldDefinitions,
-  TNameField extends NameFieldDefinition = { kind: 'text' },
->(
-  definition: CustomObjectDefinitionInput<TObjectName, TCategoryName, TSections, TFields, TNameField>,
-): Readonly<
-  CustomObjectDefinition<
-    LogicalCustomObjectName<TObjectName>,
-    LogicalCategoryName<TCategoryName>,
-    TSections,
-    TFields,
-    TNameField
-  >
-> {
-  validateLogicalCustomObjectName(definition.name);
-
-  const categoryDefinition = typeof definition.category === 'string' ? undefined : definition.category;
-  const categoryName =
-    typeof definition.category === 'string' ? definition.category : definition.category.name;
-  const categoryApiName =
-    typeof definition.category === 'string' ?
-      toCustomCategoryApiName(definition.category)
-    : definition.category.apiName;
-
-  validateLogicalCategoryName(categoryName);
-
-  const resolvedFields = Object.fromEntries(
-    Object.entries(definition.fields).map(([logicalName, field]) => {
-      validateLogicalCustomFieldName(logicalName);
-      return [
-        logicalName,
-        {
-          ...field,
-          logicalName,
-          apiName: toCustomFieldApiName(logicalName),
-        },
-      ];
-    }),
-  ) as unknown as {
-    readonly [K in Extract<keyof TFields, string>]: ResolvedFieldDefinition<K, TFields[K]>;
-  };
-
-  const normalized = {
-    name: definition.name,
-    apiName: toCustomObjectApiName(definition.name) as CustomObjectApiName<
-      LogicalCustomObjectName<TObjectName>
-    >,
-    displayName: definition.displayName,
-    ...(definition.pluralLabel != null ? { pluralLabel: definition.pluralLabel } : {}),
-    category: categoryName,
-    ...(categoryDefinition != null ? { categoryDefinition } : {}),
-    ...(definition.ownerRole != null ? { ownerRole: definition.ownerRole } : {}),
-    ...(definition.enableHistory != null ? { enableHistory: definition.enableHistory } : {}),
-    categoryApiName: categoryApiName as CategoryApiName<LogicalCategoryName<TCategoryName>>,
-    description: definition.description,
-    ...(definition.icon != null ? { icon: definition.icon } : {}),
-    nameField: (definition.nameField ?? { kind: 'text' }) as TNameField,
-    sections: (definition.sections ?? ({} as TSections)) as TSections,
-    fields: resolvedFields,
-  };
-
-  const issues = validateCustomObjectDefinition(normalized as unknown as AnyCustomObjectDefinition);
-  if (issues.length > 0) {
-    throw new Error(
-      `Invalid custom object definition for "${definition.name}":\n` +
-        issues.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n'),
-    );
-  }
-
-  return deepFreeze(normalized) as Readonly<
-    CustomObjectDefinition<
-      LogicalCustomObjectName<TObjectName>,
-      LogicalCategoryName<TCategoryName>,
-      TSections,
-      TFields,
-      TNameField
-    >
-  >;
-}
-
-/**
- * Extends an existing object definition without losing type information.
- *
- * This helper is useful when a platform package wants to publish a base schema
- * and another package wants to add fields or sections in a type-safe way.
- *
- * @typeParam TBase - Existing object definition being extended.
- * @typeParam TAddedSections - New section definitions merged into the base object.
- * @param base - Existing typed object definition to extend.
- * @param extension - Additional metadata, sections, and fields to merge into the base definition.
- * @returns New immutable custom-object definition preserving the combined type information.
- * @typeParam TAddedFields - New field definitions merged into the base object.
- */
-export function extendCustomObject<
-  TBase extends AnyCustomObjectDefinition,
-  TAddedSections extends SectionDefinitions = {},
-  TAddedFields extends FieldDefinitions = {},
->(
-  base: TBase,
-  extension: {
-    readonly displayName?: string;
-    readonly pluralLabel?: string;
-    readonly ownerRole?: string;
-    readonly enableHistory?: boolean;
-    readonly description?: string;
-    readonly icon?: TBase['icon'];
-    readonly sections?: NoOverlappingKeys<TBase['sections'], TAddedSections>;
-    readonly fields?: NoOverlappingKeys<TBase['fields'], ValidateFieldMap<TAddedFields>>;
-  },
-): Readonly<
-  CustomObjectDefinition<
-    TBase['name'],
-    TBase['category'],
-    TBase['sections'] & TAddedSections,
-    Omit<TBase['fields'], never> & TAddedFields,
-    TBase['nameField']
-  >
-> {
-  const mergedSections = {
-    ...base.sections,
-    ...(extension.sections ?? {}),
-  } as TBase['sections'] & TAddedSections;
-
-  const mergedFields = Object.fromEntries(
-    Object.entries({ ...base.fields, ...(extension.fields ?? {}) }).map(([logicalName, field]) => [
-      logicalName,
-      {
-        ...field,
-        logicalName,
-        apiName: toCustomFieldApiName(logicalName as LogicalCustomFieldName<string>),
-      },
-    ]),
-  ) as unknown as Omit<TBase['fields'], never> & TAddedFields;
-
-  return defineCustomObject({
-    name: base.name,
-    displayName: extension.displayName ?? base.displayName,
-    ...(extension.pluralLabel != null || base.pluralLabel != null ?
-      { pluralLabel: extension.pluralLabel ?? base.pluralLabel }
-    : {}),
-    ...(extension.ownerRole != null || base.ownerRole != null ?
-      { ownerRole: extension.ownerRole ?? base.ownerRole }
-    : {}),
-    ...(extension.enableHistory != null || base.enableHistory != null ?
-      { enableHistory: extension.enableHistory ?? base.enableHistory }
-    : {}),
-    category: base.categoryDefinition ?? base.category,
-    description: extension.description ?? base.description,
-    ...((extension.icon ?? base.icon) != null ? { icon: extension.icon ?? base.icon } : {}),
-    nameField: base.nameField,
-    sections: mergedSections,
-    fields: mergedFields as ValidateFieldMap<Omit<TBase['fields'], never> & TAddedFields>,
-  });
-}
-
-/**
- * Returns the logical custom field names defined on an object.
- *
- * @param definition - Object definition whose logical field names should be returned.
- * @returns Frozen array of logical field names from the definition.
- * @typeParam TDefinition - Object definition whose field names should be returned.
- */
-export function fieldNames<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-): ReadonlyArray<FieldNames<TDefinition>> {
-  return Object.freeze(Object.keys(definition.fields) as FieldNames<TDefinition>[]);
-}
-
-/**
- * Retrieves a field definition by logical field name with precise typing.
- *
- * @param definition - Object definition that owns the field.
- * @param fieldName - Logical field name to retrieve.
- * @returns Precisely typed field definition for the requested logical field name.
- * @typeParam TDefinition - Object definition that owns the field.
- * @typeParam TFieldName - Logical field name being retrieved.
- */
-export function getFieldDefinition<
-  TDefinition extends AnyCustomObjectDefinition,
-  TFieldName extends FieldNames<TDefinition>,
->(definition: TDefinition, fieldName: TFieldName): TDefinition['fields'][TFieldName] {
-  return (definition.fields as Record<string, unknown>)[fieldName] as TDefinition['fields'][TFieldName];
-}
-
-/**
- * Returns whether one typed field definition is writable by record create/update helpers.
- *
- * @param field - Typed field definition to inspect.
- * @returns Whether the field may be written by callers.
- */
-export function isWritableField(field: AnyFieldDefinition): boolean {
-  return field.writable;
-}