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

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

@@ -0,0 +1,192 @@
+import { Rule, type RuleAction, type RuleProps } from '../../../../lib/manifest';
+import type { Field } from '../../../../lib/manifest/field';
+import type {
+  AnyCustomObjectDefinition,
+  FieldNames,
+  FieldValue,
+  LookupReference,
+} from '../../custom-objects/types';
+import type { ManifestConditionInput } from './conditions';
+import { resolveManifestConditionInput } from './conditions';
+import type {
+  StandardManifestFieldName,
+  TypedManifestFieldInput,
+  TypedManifestFieldName,
+} from './field-resolution';
+import { resolveTypedManifestField } from './field-resolution';
+import type { ManifestRegistration } from './types';
+
+type StandardRuleFieldValue<TFieldName extends string> =
+  TFieldName extends 'owner_role' | 'created_by' | 'last_modified_by' ? string | LookupReference : string;
+
+type CustomRuleFieldValue<
+  TDefinition extends AnyCustomObjectDefinition,
+  TFieldName extends FieldNames<TDefinition>,
+> = TDefinition['fields'][TFieldName] extends infer TField ?
+  FieldValue<TField> extends readonly (infer TElement)[] ?
+    FieldValue<TField> | TElement
+  : FieldValue<TField>
+: never;
+
+/**
+ * Fixed value accepted by a typed rule action for one field name.
+ *
+ * @typeParam TDefinition - Typed custom-object definition that owns the field namespace.
+ * @typeParam TFieldName - Standard or logical field name that should receive the fixed value.
+ */
+export type TypedRuleFixedValue<
+  TDefinition extends AnyCustomObjectDefinition,
+  TFieldName extends TypedManifestFieldName<TDefinition>,
+> = TFieldName extends FieldNames<TDefinition> ? CustomRuleFieldValue<TDefinition, TFieldName>
+: TFieldName extends StandardManifestFieldName<TDefinition> ? StandardRuleFieldValue<TFieldName>
+: never;
+
+/**
+ * Typed rule action emitted by the typed rule helper family.
+ *
+ * The runtime shape is intentionally identical to the low-level {@link RuleAction}
+ * type so the helper composes cleanly with the existing manifest class.
+ *
+ * @typeParam TDefinition - Typed custom-object definition that owns the field namespace.
+ */
+export type TypedRuleAction<TDefinition extends AnyCustomObjectDefinition> = RuleAction & {
+  readonly __typedRuleActionDefinition__?: TDefinition;
+};
+
+/**
+ * Field setter returned by {@link TypedRuleHelpers.setField}.
+ *
+ * @typeParam TDefinition - Typed custom-object definition that owns the field namespace.
+ * @typeParam TFieldName - Standard or logical field name being targeted.
+ */
+export interface TypedRuleFieldSetter<
+  TDefinition extends AnyCustomObjectDefinition,
+  TFieldName extends TypedManifestFieldName<TDefinition>,
+> {
+  /**
+   * Creates one fixed-value rule action for the selected field.
+   *
+   * For select fields, the value may be either one option string or the full
+   * array shape used by the underlying typed record model.
+   */
+  toValue(value: TypedRuleFixedValue<TDefinition, TFieldName>): TypedRuleAction<TDefinition>;
+  /**
+   * Creates one formula-backed rule action for the selected field.
+   *
+   * Use this as the explicit escape hatch when the default fixed-value path is
+   * too restrictive and you need to compute the assigned value through the
+   * low-level rule-formula string surface.
+   */
+  toFormula(formula: string): TypedRuleAction<TDefinition>;
+}
+
+/**
+ * Helper family for typed rule actions.
+ *
+ * @typeParam TDefinition - Typed custom-object definition that owns the field namespace.
+ */
+export interface TypedRuleHelpers<TDefinition extends AnyCustomObjectDefinition> {
+  /** Returns a typed field setter for the selected field name. */
+  setField<TFieldName extends TypedManifestFieldName<TDefinition>>(
+    field: TFieldName,
+  ): TypedRuleFieldSetter<TDefinition, TFieldName>;
+  /** Returns a passthrough field setter for raw manifest fields such as summary fields. */
+  setField(field: Field): {
+    toValue(value: unknown): TypedRuleAction<TDefinition>;
+    toFormula(formula: string): TypedRuleAction<TDefinition>;
+  };
+}
+
+/**
+ * Initialization properties for {@link defineTypedRule}.
+ *
+ * @typeParam TDefinition - Typed custom-object definition whose field namespace should be enforced.
+ */
+type TypedRuleActionInput<TDefinition extends AnyCustomObjectDefinition> =
+  | readonly (TypedRuleAction<TDefinition> | RuleAction)[]
+  | ((helpers: TypedRuleHelpers<TDefinition>) => readonly (TypedRuleAction<TDefinition> | RuleAction)[]);
+
+type TypedRuleBaseProps<TDefinition extends AnyCustomObjectDefinition> = Omit<
+  RuleProps,
+  'actions' | 'rqlCondition' | 'triggerType' | 'updateTriggerType'
+> & {
+  /** Optional condition that must be truthy for the rule to fire. */
+  readonly when?: ManifestConditionInput<TDefinition>;
+  /**
+   * Rule actions created via {@link createTypedRuleHelpers}, authored directly
+   * as low-level actions, or produced lazily from one typed helper callback.
+   */
+  readonly actions?: TypedRuleActionInput<TDefinition>;
+};
+
+/**
+ * Initialization properties for {@link defineTypedRule}.
+ *
+ * `triggerType` and `updateTriggerType` intentionally form a discriminated
+ * union so the common CREATE-vs-UPDATE rule invariants are enforced at compile
+ * time instead of only by the low-level manifest class at runtime.
+ *
+ * @typeParam TDefinition - Typed custom-object definition whose field namespace should be enforced.
+ */
+export type TypedRuleProps<TDefinition extends AnyCustomObjectDefinition> =
+  | (TypedRuleBaseProps<TDefinition> & {
+      readonly triggerType: 'CREATE';
+      readonly updateTriggerType?: never;
+    })
+  | (TypedRuleBaseProps<TDefinition> & {
+      readonly triggerType: Exclude<RuleProps['triggerType'], 'CREATE'>;
+      readonly updateTriggerType: NonNullable<RuleProps['updateTriggerType']>;
+    });
+
+/**
+ * Creates typed rule-action helpers for one manifest registration.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @returns Immutable rule-action helper family.
+ * @typeParam TDefinition - Typed custom-object definition whose field namespace should be enforced.
+ */
+export function createTypedRuleHelpers<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+): TypedRuleHelpers<TDefinition> {
+  function createSetter(field: Field) {
+    return Object.freeze({
+      toValue(value: unknown): TypedRuleAction<TDefinition> {
+        return Object.freeze({ targetField: field, fixedValue: value }) as TypedRuleAction<TDefinition>;
+      },
+      toFormula(formula: string): TypedRuleAction<TDefinition> {
+        return Object.freeze({ targetField: field, rqlFormula: formula }) as TypedRuleAction<TDefinition>;
+      },
+    });
+  }
+
+  return Object.freeze({
+    setField(field: TypedManifestFieldInput<TDefinition> | Field) {
+      return createSetter(
+        resolveTypedManifestField(registration, field as TypedManifestFieldInput<TDefinition>),
+      );
+    },
+  }) as TypedRuleHelpers<TDefinition>;
+}
+
+/**
+ * Defines a record-triggered rule using typed field names and manifest-condition fragments.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param props - Typed rule properties.
+ * @returns Low-level rule manifest instance.
+ * @typeParam TDefinition - Typed custom-object definition whose field namespace should be enforced.
+ */
+export function defineTypedRule<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  props: TypedRuleProps<TDefinition>,
+): Rule {
+  const { when, actions, ...rest } = props;
+  const resolvedActions =
+    typeof actions === 'function' ? actions(createTypedRuleHelpers(registration)) : actions;
+
+  return new Rule(registration.object, {
+    ...rest,
+    ...(when != null ? { rqlCondition: resolveManifestConditionInput(registration, when) } : {}),
+    ...(resolvedActions != null ? { actions: [...resolvedActions] } : {}),
+  });
+}