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

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

@@ -1,375 +0,0 @@
-import type { AnyCustomObjectDefinition, FieldNames, FieldValue, LookupReference } from './types';
-
-const STANDARD_RQL_FIELD_NAMES = [
-  'id',
-  'name',
-  'created_at',
-  'updated_at',
-  'system_updated_at',
-  'external_id',
-  'owner_role',
-  'created_by',
-  'last_modified_by',
-] as const;
-
-type StandardRqlFieldValueByName = {
-  id: string;
-  name: string;
-  created_at: string | null;
-  updated_at: string | null;
-  system_updated_at: string | null;
-  external_id: string | null;
-  owner_role: LookupReference<'Employee'> | null;
-  created_by: LookupReference<'Employee'> | null;
-  last_modified_by: LookupReference<'Employee'> | null;
-};
-
-/**
- * Standard field-name strings exposed by the typed RQL helper.
- *
- * @typeParam TDefinition - Object definition whose standard fields should be exposed.
- */
-export type StandardRqlFieldName<TDefinition extends AnyCustomObjectDefinition> =
-  (typeof STANDARD_RQL_FIELD_NAMES)[number];
-
-/**
- * Field-name strings accepted by the typed RQL helper.
- *
- * @typeParam TDefinition - Object definition whose field-name union should be exposed.
- */
-export type RqlFieldName<TDefinition extends AnyCustomObjectDefinition> =
-  | StandardRqlFieldName<TDefinition>
-  | FieldNames<TDefinition>;
-
-/**
- * Field token used by the RQL helper to preserve type information across string compilation.
- *
- * @typeParam TValue - Runtime value type stored in the field.
- * @typeParam TApiName - Wire-level field api name used when rendering RQL.
- */
-export interface RqlFieldToken<TValue = unknown, TApiName extends string = string> {
-  readonly kind: 'rql-field-token';
-  readonly apiName: TApiName;
-  readonly logicalName: string;
-  readonly __valueType__?: TValue;
-}
-
-/**
- * Opaque RQL fragment that can be interpolated into {@link CustomObjectRqlHelpers.rql}.
- */
-export interface RqlFragment {
-  readonly kind: 'rql-fragment';
-  readonly text: string;
-}
-
-/**
- * Scope object whose properties autocomplete to the standard and custom fields available on one object definition.
- *
- * @typeParam TDefinition - Object definition whose field tokens should be exposed.
- */
-export type RqlFieldScope<TDefinition extends AnyCustomObjectDefinition> = {
-  readonly [K in StandardRqlFieldName<TDefinition>]: RqlFieldToken<StandardRqlFieldValueByName[K], K>;
-} & {
-  readonly [K in FieldNames<TDefinition>]: RqlFieldToken<
-    FieldValue<TDefinition['fields'][K]>,
-    TDefinition['fields'][K] extends { apiName: infer TApiName extends string } ? TApiName : string
-  >;
-};
-
-/**
- * Input that the RQL helper knows how to encode as a literal value.
- */
-export type RqlValue = string | number | boolean | null | LookupReference<string> | readonly RqlValue[];
-
-/**
- * Runtime surface returned by {@link createRqlHelpers}.
- *
- * @typeParam TDefinition - Object definition whose field tokens should be exposed.
- */
-export interface CustomObjectRqlHelpers<TDefinition extends AnyCustomObjectDefinition> {
-  /** Object-scoped field tokens used for IntelliSense-friendly property access. */
-  readonly fields: RqlFieldScope<TDefinition>;
-  /** Converts a field-name string into a typed field token. */
-  field<TFieldName extends RqlFieldName<TDefinition>>(
-    fieldName: TFieldName,
-  ): RqlFieldScope<TDefinition>[TFieldName];
-  /** Renders a tagged template into a backend-ready RQL string. */
-  rql(strings: TemplateStringsArray, ...values: readonly RqlInterpolation[]): string;
-  /** Renders a fragment built by helper functions into a string. */
-  render(fragment: RqlFragment): string;
-  /** Wraps a raw RQL snippet as a fragment. Use sparingly. */
-  raw(text: string): RqlFragment;
-  /** Builds an equality comparison fragment. */
-  eq<TValue>(field: RqlFieldToken<TValue>, value: RqlComparableValue<TValue> | null): RqlFragment;
-  /** Builds an inequality comparison fragment. */
-  ne<TValue>(field: RqlFieldToken<TValue>, value: RqlComparableValue<TValue> | null): RqlFragment;
-  /** Builds a less-than comparison fragment. */
-  lt<TValue extends string | number>(field: RqlFieldToken<TValue>, value: TValue): RqlFragment;
-  /** Builds a less-than-or-equal comparison fragment. */
-  lte<TValue extends string | number>(field: RqlFieldToken<TValue>, value: TValue): RqlFragment;
-  /** Builds a greater-than comparison fragment. */
-  gt<TValue extends string | number>(field: RqlFieldToken<TValue>, value: TValue): RqlFragment;
-  /** Builds a greater-than-or-equal comparison fragment. */
-  gte<TValue extends string | number>(field: RqlFieldToken<TValue>, value: TValue): RqlFragment;
-  /** Builds an `IN` comparison fragment. */
-  in<TValue>(field: RqlFieldToken<TValue>, values: readonly RqlComparableValue<TValue>[]): RqlFragment;
-  /** Builds a `NOT_IN` comparison fragment. */
-  notIn<TValue>(field: RqlFieldToken<TValue>, values: readonly RqlComparableValue<TValue>[]): RqlFragment;
-  /** Builds an `IS NULL`-style equality fragment. */
-  isNull<TValue>(field: RqlFieldToken<TValue>): RqlFragment;
-  /** Builds an `IS NOT NULL`-style inequality fragment. */
-  isNotNull<TValue>(field: RqlFieldToken<TValue>): RqlFragment;
-  /** Builds a parenthesized `AND` fragment. */
-  and(...fragments: readonly RqlFragment[]): RqlFragment;
-  /** Builds a parenthesized `OR` fragment. */
-  or(...fragments: readonly RqlFragment[]): RqlFragment;
-  /** Builds a parenthesized `NOT` fragment. */
-  not(fragment: RqlFragment): RqlFragment;
-}
-
-/** Allowed comparison inputs for one field token. */
-export type RqlComparableValue<TValue> = TValue extends LookupReference<string> ? TValue | string : TValue;
-
-/** Interpolation values accepted by the tagged-template compiler. */
-export type RqlInterpolation = RqlFieldToken | RqlFragment | RqlValue;
-
-/**
- * Builds one immutable field token used by the typed RQL helper surface.
- *
- * @param logicalName - Author-facing logical field name.
- * @param apiName - Wire-level field API name used in rendered RQL.
- * @returns Immutable field token carrying value and API-name type information.
- * @typeParam TValue - Runtime value type represented by the field.
- * @typeParam TApiName - Wire-level field API name.
- */
-function createFieldToken<TValue, TApiName extends string>(
-  logicalName: string,
-  apiName: TApiName,
-): RqlFieldToken<TValue, TApiName> {
-  return Object.freeze({ kind: 'rql-field-token', logicalName, apiName });
-}
-
-/**
- * Wraps raw RQL text as an opaque fragment object.
- *
- * @param text - Backend-ready RQL snippet.
- * @returns Immutable fragment wrapper.
- */
-function createFragment(text: string): RqlFragment {
-  return Object.freeze({ kind: 'rql-fragment', text });
-}
-
-/**
- * Returns whether one interpolation value looks like a lookup reference object.
- *
- * @param value - Candidate interpolation value.
- * @returns Whether the value is a lookup reference accepted by the helper.
- */
-function isLookupReference(value: unknown): value is LookupReference<string> {
-  return (
-    value != null &&
-    typeof value === 'object' &&
-    !Array.isArray(value) &&
-    typeof (value as { id?: unknown }).id === 'string'
-  );
-}
-
-/**
- * Returns whether one interpolation value is a typed field token.
- *
- * @param value - Candidate interpolation value.
- * @returns Whether the value is a field token produced by {@link createRqlHelpers}.
- */
-function isFieldToken(value: unknown): value is RqlFieldToken {
-  return (
-    value != null &&
-    typeof value === 'object' &&
-    (value as { kind?: unknown }).kind === 'rql-field-token' &&
-    typeof (value as { apiName?: unknown }).apiName === 'string'
-  );
-}
-
-/**
- * Returns whether one interpolation value is an opaque RQL fragment.
- *
- * @param value - Candidate interpolation value.
- * @returns Whether the value is an RQL fragment wrapper.
- */
-function isFragment(value: unknown): value is RqlFragment {
-  return (
-    value != null &&
-    typeof value === 'object' &&
-    (value as { kind?: unknown }).kind === 'rql-fragment' &&
-    typeof (value as { text?: unknown }).text === 'string'
-  );
-}
-
-/**
- * Escapes one string literal into backend-ready single-quoted RQL syntax.
- *
- * @param value - Raw string value to encode.
- * @returns Escaped RQL string literal.
- */
-function encodeString(value: string): string {
-  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
-/**
- * Encodes one supported interpolation value into backend-ready RQL text.
- *
- * @param value - Interpolation value to encode.
- * @returns Backend-ready RQL text for the supplied value.
- * @throws Error when the value cannot be encoded as a supported RQL literal.
- */
-function encodeRqlValue(value: RqlInterpolation): string {
-  if (isFieldToken(value)) return value.apiName;
-  if (isFragment(value)) return value.text;
-  if (value === null) return 'null';
-  if (typeof value === 'string') return encodeString(value);
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value)) {
-      throw new Error(`RQL numeric literals must be finite. Received ${String(value)}.`);
-    }
-    return String(value);
-  }
-  if (typeof value === 'boolean') return value ? 'True' : 'False';
-  if (Array.isArray(value)) return `[${value.map((entry) => encodeRqlValue(entry)).join(', ')}]`;
-  if (isLookupReference(value)) return encodeString(value.id);
-  throw new Error(`Unsupported RQL interpolation value: ${String(value)}.`);
-}
-
-/**
- * Renders the `rql` tagged-template inputs into one backend-ready RQL string.
- *
- * @param strings - Static template-string segments.
- * @param values - Dynamic interpolation values to encode and insert.
- * @returns Backend-ready RQL string.
- */
-function renderTemplate(strings: TemplateStringsArray, values: readonly RqlInterpolation[]): string {
-  let rendered = strings[0] ?? '';
-  for (let index = 0; index < values.length; index += 1) {
-    rendered += encodeRqlValue(values[index] as RqlInterpolation);
-    rendered += strings[index + 1] ?? '';
-  }
-  return rendered;
-}
-
-/**
- * Joins one or more fragments under a logical operator and wraps the result in parentheses.
- *
- * @param operator - Logical operator to place between fragments.
- * @param fragments - Fragments to join.
- * @returns Parenthesized logical fragment.
- * @throws Error when no fragments are supplied.
- */
-function joinFragments(operator: 'AND' | 'OR', fragments: readonly RqlFragment[]): RqlFragment {
-  if (fragments.length === 0) {
-    throw new Error(`RQL ${operator} requires at least one fragment.`);
-  }
-  return createFragment(`(${fragments.map((fragment) => fragment.text).join(` ${operator} `)})`);
-}
-
-/**
- * Creates a typed RQL helper surface for one custom-object definition.
- *
- * The helper keeps authoring close to raw RQL by combining a tagged-template
- * compiler with IntelliSense-friendly field tokens. Callers write normal RQL in
- * string segments and interpolate typed field references or JavaScript literal
- * values where they want compiler assistance.
- *
- * @param definition - Typed object definition whose field tokens should be exposed.
- * @returns Typed RQL helper surface bound to the supplied object definition.
- * @typeParam TDefinition - Object definition whose field tokens should be exposed.
- */
-export function createRqlHelpers<TDefinition extends AnyCustomObjectDefinition>(
-  definition: TDefinition,
-): CustomObjectRqlHelpers<TDefinition> {
-  const tokens: Record<string, RqlFieldToken> = {};
-
-  for (const fieldName of STANDARD_RQL_FIELD_NAMES) {
-    tokens[fieldName] = createFieldToken(fieldName, fieldName);
-  }
-  for (const [fieldName, field] of Object.entries(definition.fields)) {
-    if (tokens[fieldName] != null) {
-      throw new Error(
-        `Custom field name "${fieldName}" on "${definition.apiName}" conflicts with a standard RQL field token.`,
-      );
-    }
-    tokens[fieldName] = createFieldToken(fieldName, field.apiName);
-  }
-
-  const fields = Object.freeze(tokens) as RqlFieldScope<TDefinition>;
-  const field = <TFieldName extends RqlFieldName<TDefinition>>(
-    fieldName: TFieldName,
-  ): RqlFieldScope<TDefinition>[TFieldName] => {
-    const resolved = fields[fieldName];
-    if (resolved == null) {
-      throw new Error(
-        `Unknown RQL field "${String(fieldName)}" for "${definition.apiName}". ` +
-          `Valid fields: ${Object.keys(fields).sort().join(', ')}.`,
-      );
-    }
-    return resolved;
-  };
-
-  return Object.freeze({
-    fields,
-    field,
-    rql(strings: TemplateStringsArray, ...values: readonly RqlInterpolation[]): string {
-      return renderTemplate(strings, values);
-    },
-    render(fragment: RqlFragment): string {
-      return fragment.text;
-    },
-    raw(text: string): RqlFragment {
-      return createFragment(text);
-    },
-    eq<TValue>(currentField: RqlFieldToken<TValue>, value: RqlComparableValue<TValue> | null): RqlFragment {
-      return createFragment(`(${currentField.apiName} == ${encodeRqlValue(value as RqlInterpolation)})`);
-    },
-    ne<TValue>(currentField: RqlFieldToken<TValue>, value: RqlComparableValue<TValue> | null): RqlFragment {
-      return createFragment(`(${currentField.apiName} != ${encodeRqlValue(value as RqlInterpolation)})`);
-    },
-    lt<TValue extends string | number>(currentField: RqlFieldToken<TValue>, value: TValue): RqlFragment {
-      return createFragment(`(${currentField.apiName} < ${encodeRqlValue(value)})`);
-    },
-    lte<TValue extends string | number>(currentField: RqlFieldToken<TValue>, value: TValue): RqlFragment {
-      return createFragment(`(${currentField.apiName} <= ${encodeRqlValue(value)})`);
-    },
-    gt<TValue extends string | number>(currentField: RqlFieldToken<TValue>, value: TValue): RqlFragment {
-      return createFragment(`(${currentField.apiName} > ${encodeRqlValue(value)})`);
-    },
-    gte<TValue extends string | number>(currentField: RqlFieldToken<TValue>, value: TValue): RqlFragment {
-      return createFragment(`(${currentField.apiName} >= ${encodeRqlValue(value)})`);
-    },
-    in<TValue>(
-      currentField: RqlFieldToken<TValue>,
-      values: readonly RqlComparableValue<TValue>[],
-    ): RqlFragment {
-      return createFragment(`(${currentField.apiName} IN ${encodeRqlValue(values as readonly RqlValue[])})`);
-    },
-    notIn<TValue>(
-      currentField: RqlFieldToken<TValue>,
-      values: readonly RqlComparableValue<TValue>[],
-    ): RqlFragment {
-      return createFragment(
-        `(${currentField.apiName} NOT_IN ${encodeRqlValue(values as readonly RqlValue[])})`,
-      );
-    },
-    isNull<TValue>(currentField: RqlFieldToken<TValue>): RqlFragment {
-      return createFragment(`(${currentField.apiName} == null)`);
-    },
-    isNotNull<TValue>(currentField: RqlFieldToken<TValue>): RqlFragment {
-      return createFragment(`(${currentField.apiName} != null)`);
-    },
-    and(...fragments: readonly RqlFragment[]): RqlFragment {
-      return joinFragments('AND', fragments);
-    },
-    or(...fragments: readonly RqlFragment[]): RqlFragment {
-      return joinFragments('OR', fragments);
-    },
-    not(fragment: RqlFragment): RqlFragment {
-      return createFragment(`(NOT ${fragment.text})`);
-    },
-  });
-}