@isrd-isi-edu/ermrestjs 2.6.1 → 2.8.0

package/src/models/active-list-condition.ts

@@ -16,11 +16,22 @@ import { _processWaitForList } from '@isrd-isi-edu/ermrestjs/js/utils/pseudocolu
 
 /**
  * Encapsulates condition evaluation logic for conditionally visible
- * columns and related entities in the record page.
+ * columns and related entities.
+ *
+ * Two forms:
+ * - **With source**: `condDef.source` or `condDef.sourcekey` drives a fetch
+ *   whose data feeds the condition. Only honored in `detailed` context.
+ *   `column` is a PseudoColumn used by chaise's record-page flow.
+ * - **No source**: only `condDef.condition_pattern` is set. Evaluated
+ *   synchronously against template globals (`$session`, `$catalog`,
+ *   `isUserInAcl`, etc.). Honored in every context. `column` is `null`.
  */
 export default class ActiveListCondition {
-  /** The PseudoColumn for fetching condition data */
-  column: VisibleColumn;
+  /**
+   * The PseudoColumn for fetching condition data.
+   * `null` for no-source conditions (pattern-only).
+   */
+  column: VisibleColumn | null;
 
   /** Whether the condition source requires a secondary request (has inbound path or aggregate) */
   isAsync: boolean;
@@ -47,10 +58,25 @@ export default class ActiveListCondition {
 
     const wm = _warningMessages;
 
-    if (typeof condDef !== 'object' || (!condDef.source && !isStringAndNotEmpty(condDef.sourcekey))) {
+    if (typeof condDef !== 'object' || condDef === null) {
       throw new Error(wm.CONDITION.INVALID_SOURCE);
     }
 
+    const hasSource = !!condDef.source || isStringAndNotEmpty(condDef.sourcekey);
+
+    // no-source branch: pattern-only, evaluated synchronously against template globals
+    if (!hasSource) {
+      if (!isStringAndNotEmpty(condDef.condition_pattern)) {
+        throw new Error(wm.CONDITION.MISSING_PATTERN);
+      }
+      if (condDef.wait_for !== undefined) {
+        throw new Error(wm.CONDITION.NO_SOURCE_WAIT_FOR);
+      }
+      this.column = null;
+      this.isAsync = false;
+      return;
+    }
+
     let condSourceWrapper: SourceObjectWrapper;
     try {
       const sds = this._reference.table.sourceDefinitions;
@@ -101,10 +127,17 @@ export default class ActiveListCondition {
    */
   get waitFor(): ReferenceColumn[] {
     if (this._waitFor === undefined) {
-      const res = _processWaitForList(this._condDef.wait_for, this._reference, this._reference.table, null, this._tuple, 'condition');
-      this._waitFor = res.waitForList;
-      this._hasWaitFor = res.hasWaitFor;
-      this._hasWaitForAggregate = res.hasWaitForAggregate;
+      // no-source conditions don't have a source fetch to wait on
+      if (this.column === null) {
+        this._waitFor = [];
+        this._hasWaitFor = false;
+        this._hasWaitForAggregate = false;
+      } else {
+        const res = _processWaitForList(this._condDef.wait_for, this._reference, this._reference.table, null, this._tuple, 'condition');
+        this._waitFor = res.waitForList;
+        this._hasWaitFor = res.hasWaitFor;
+        this._hasWaitForAggregate = res.hasWaitForAggregate;
+      }
     }
     return this._waitFor!;
   }
@@ -112,25 +145,29 @@ export default class ActiveListCondition {
   /**
    * Decide whether the conditioned content should be shown.
    *
-   * Three internal paths, dispatched on `condition_pattern` and `this.isAsync`:
+   * Four internal paths, dispatched on `this.column`, `condition_pattern`, and `this.isAsync`:
    *
-   * 1. **`condition_pattern` set.** Render the pattern. `$self` / `$_self` come
-   *    from {@link buildSelfTemplateVariables}, which sources from `mainTuple`
-   *    for sync sources and from `conditionValue` for async sources. Blank
-   *    rendered output ⇒ empty.
-   * 2. **No pattern + `isAsync === true`.** Caller already fetched the data;
-   *    emptiness is computed from `conditionValue` by {@link _isConditionValueEmpty}.
-   * 3. **No pattern + `isAsync === false`.** `conditionValue` is ignored (sync
-   *    sources have no fetched value). The raw value is pulled from `mainTuple`
-   *    via {@link buildSelfTemplateVariables}: scalar sources are empty when
-   *    `$_self` is `null`/`undefined`/`''`; entity-mode sources are empty when
-   *    `$self` is undefined (the joined row didn't load).
+   * 0. **No-source (`this.column === null`).** `condition_pattern` is rendered
+   *    against the caller's `templateVariables` plus the catalog's global
+   *    template environment (`$session`, `$catalog`, `isUserInAcl`, etc.).
+   *    `conditionValue` and `mainTuple` are unused.
+   * 1. **With-source, `condition_pattern` set.** Render the pattern. `$self` /
+   *    `$_self` come from {@link buildSelfTemplateVariables}, which sources from
+   *    `mainTuple` for sync sources and from `conditionValue` for async sources.
+   *    Blank rendered output ⇒ empty.
+   * 2. **With-source, no pattern + `isAsync === true`.** Caller already fetched
+   *    the data; emptiness is computed from `conditionValue` by {@link _isConditionValueEmpty}.
+   * 3. **With-source, no pattern + `isAsync === false`.** `conditionValue` is
+   *    ignored (sync sources have no fetched value). The raw value is pulled
+   *    from `mainTuple` via {@link buildSelfTemplateVariables}: scalar sources
+   *    are empty when `$_self` is `null`/`undefined`/`''`; entity-mode sources
+   *    are empty when `$self` is undefined (the joined row didn't load).
    *
    * The `on_empty` flag then maps `isEmpty` to "show": `"hide"` (default) shows
    * when not empty; `"show"` shows when empty.
    *
    * @param templateVariables - accumulated `$x`/`$_x` template variables for
-   *   every other source (only consulted by the pattern branch).
+   *   every other source (consulted by the pattern branches).
    * @param conditionValue - the fetched value for an async source.
    *   - **entityset** (Reference.read result): a {@link Page} object — has
    *     `length` (used by `_isConditionValueEmpty`) and `templateVariables`
@@ -140,18 +177,24 @@ export default class ActiveListCondition {
    *     scalar; `templateVariables` carries `$self`/`$_self`.
    *   - **null** if the request failed or there's no fetched value (treated
    *     as empty).
-   *   Ignored entirely for sync sources (path 3).
-   * @param mainTuple - the main record tuple. Always required: the pattern
-   *   branch and the sync no-pattern branch both look up `$self`/`$_self`
-   *   from it.
+   *   Ignored for no-source (path 0) and sync sources (path 3).
+   * @param mainTuple - the main record tuple. Required for paths 1 and 3
+   *   (both look up `$self`/`$_self` from it). Unused for paths 0 and 2.
    * @returns whether the conditioned content should be shown.
    */
-  evaluateCondition(templateVariables: any, conditionValue: any, mainTuple: Tuple): { shouldShow: boolean } {
+  evaluateCondition(templateVariables: any, conditionValue: any, mainTuple?: Tuple): { shouldShow: boolean } {
     let isEmpty: boolean;
     const condDef = this._condDef;
 
-    if (condDef.condition_pattern) {
-      const selfTemplateVariables = buildSelfTemplateVariables(this.column as ReferenceColumn, mainTuple, conditionValue);
+    if (this.column === null) {
+      // no-source: pattern-only, evaluated against caller's templateVariables
+      // plus the catalog's global template environment ($session, $catalog, etc.)
+      const rendered = _renderTemplate(condDef.condition_pattern as string, templateVariables ?? {}, this._reference.table.schema.catalog, {
+        templateEngine: condDef.template_engine,
+      });
+      isEmpty = !rendered || rendered.trim() === '';
+    } else if (condDef.condition_pattern) {
+      const selfTemplateVariables = buildSelfTemplateVariables(this.column as ReferenceColumn, mainTuple!, conditionValue);
       const keyValues: any = {};
       Object.assign(keyValues, templateVariables, selfTemplateVariables);
 
@@ -166,7 +209,7 @@ export default class ActiveListCondition {
     } else {
       // no pattern, sync: derive the raw value from the tuple via the same
       // helper sourceFormatPresentation uses, then decide emptiness directly.
-      const selfVars = buildSelfTemplateVariables(this.column as ReferenceColumn, mainTuple, null);
+      const selfVars = buildSelfTemplateVariables(this.column as ReferenceColumn, mainTuple!, null);
       if ('$_self' in selfVars) {
         // scalar source (local column or all-outbound scalar)
         const v = selfVars.$_self;

package/src/models/reference/reference.ts

@@ -49,6 +49,7 @@ import {
   computeReferenceDisplay,
   type ReferenceDisplay,
   generateColumnsList,
+  applyNoSourceConditions,
 } from '@isrd-isi-edu/ermrestjs/src/utils/reference-utils';
 import { isObject, isObjectAndNotNull, isStringAndNotEmpty, verify } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
 import { fixedEncodeURIComponent, simpleDeepCopy } from '@isrd-isi-edu/ermrestjs/src/utils/value-utils';
@@ -817,7 +818,7 @@ export class Reference {
     }
 
     if (notSorted && this._related.length !== 0) {
-      return this._related.sort((a, b) => {
+      this._related.sort((a, b) => {
         // displayname
         if (a.displayname.value !== b.displayname.value) {
           return (a.displayname.value as string).localeCompare(b.displayname.value as string);
@@ -835,6 +836,8 @@ export class Reference {
       });
     }
 
+    applyNoSourceConditions(this._related, (rel) => rel.pseudoColumn?.resolvedCondition);
+
     return this._related;
   }
 
@@ -888,7 +891,10 @@ export class Reference {
       conditionedItem: { column?: boolean; inline?: boolean; related?: boolean; index: number },
       addToDeps: (deps: Array<ActiveListRequest | ActiveListRelatedEntityRequest>) => void,
     ): boolean => {
-      if (!isDetailed || !condition) return false;
+      // !condition.column is the no-source marker: those should already be
+      // filtered out by generateColumnsList / generateRelatedList, but this is
+      // a safety net since ActiveList's processConditionedItem assumes a column.
+      if (!isDetailed || !condition || !condition.column) return false;
       builder.processConditionedItem(condition, conditionedItem, addToDeps);
       return true;
     };

package/src/models/reference/tuple.ts

@@ -4,7 +4,7 @@ import { DisplayName } from '@isrd-isi-edu/ermrestjs/src/models/display-name';
 
 // utils
 import { fixedEncodeURIComponent, shallowCopy, simpleDeepCopy } from '@isrd-isi-edu/ermrestjs/src/utils/value-utils';
-import { isObjectAndNotNull } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
+import { isObjectAndNotNull, isStringAndNotEmpty } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
 import { _ERMrestACLs, _contexts, _permissionMessages } from '@isrd-isi-edu/ermrestjs/src/utils/constants';
 
 import { isAllOutboundColumn } from '@isrd-isi-edu/ermrestjs/src/utils/column-utils';
@@ -154,6 +154,13 @@ export class Tuple {
     return this._data;
   }
 
+  /**
+   *
+   * @param permission the ermrest permission that should be checked (refer to _ERMrestACLs constant for more details)
+   * @param colName the name of the column for which the permission should be checked
+   * @param isAssoc whether the permission check is for an association
+   * @returns a boolean indicating whether the permission is granted
+   */
   checkPermissions(permission: string, colName?: string, isAssoc = false): boolean {
     let sum = this._rightsSummary[permission];
     if (isAssoc) {
@@ -161,6 +168,12 @@ export class Tuple {
     }
 
     if (permission === _ERMrestACLs.COLUMN_UPDATE) {
+      // if the column is passed but doesn't exist in the table, return false
+      if (isStringAndNotEmpty(colName) && !this._pageRef.table.columns.has(colName!)) {
+        return false;
+      }
+
+      // if there aren't any column-level permissions, then allow it
       if (!isObjectAndNotNull(sum) || typeof sum[colName!] !== 'boolean') return true;
       return sum[colName!];
     }

package/src/models/reference-column/reference-column.ts

@@ -461,6 +461,8 @@ export class ReferenceColumn {
 
   /**
    * The resolved condition for this column, or null if no condition or not applicable.
+   * Note: no-source conditions are returned here even after `applyNoSourceConditions`
+   * has already handled them. Downstream consumers guard via `!condition.column`.
    */
   get resolvedCondition(): ActiveListCondition | null {
     if (this._resolvedCondition === undefined) {
@@ -472,13 +474,13 @@ export class ReferenceColumn {
 
   /**
    * Resolve the condition definition and source for this column.
+   *
+   * With-source conditions (drive a secondary fetch tied to the main entity)
+   * are only honored in `detailed` context. No-source conditions (pattern-only)
+   * are honored in every context — they're evaluated synchronously against
+   * the catalog's global template environment.
    */
   protected _resolveCondition(): ActiveListCondition | null {
-    // only applicable in detailed context
-    if (this._context !== _contexts.DETAILED) {
-      return null;
-    }
-
     if (!this.sourceObjectWrapper) {
       return null;
     }
@@ -499,6 +501,13 @@ export class ReferenceColumn {
       return null;
     }
 
+    // gate with-source conditions to detailed context (no-source falls through)
+    const hasSource = !!condDef.source || isStringAndNotEmpty(condDef.sourcekey as string | undefined);
+    if (hasSource && this._context !== _contexts.DETAILED) {
+      $log.info('condition with `source`/`sourcekey` only honored in `detailed` context; ignoring on column `' + this.name + '`.');
+      return null;
+    }
+
     let condition: ActiveListCondition;
     try {
       condition = new ActiveListCondition(condDef, this._baseReference, this._mainTuple, condKey);

package/src/models/source-object-wrapper.ts

@@ -693,12 +693,12 @@ export class FacetObjectGroupWrapper {
    * Will throw an error if there was any issues in processing the source object.
    *
    * @param sourceObject The source object representing the facet group.
-   * @param table The table to which the facet group belongs.
+   * @param reference The reference to which the facet group belongs.
    * @param hasFilterOrFacet Indicates if the group has any filters or facets.
    *
    * @throws Will throw an error if the source object is invalid or has no valid children.
    */
-  constructor(sourceObject: Record<string, unknown>, table: Table, hasFilterOrFacet: boolean) {
+  constructor(sourceObject: Record<string, unknown>, reference: Reference, hasFilterOrFacet: boolean) {
     if (!Array.isArray(sourceObject.and) || sourceObject.and.length === 0) {
       throw new Error('valid array of children is required');
     }
@@ -727,10 +727,10 @@ export class FacetObjectGroupWrapper {
     const children: SourceObjectWrapper[] = [];
     for (const child of sourceObject.and) {
       try {
-        const wrapper = _facetColumnHelpers.sourceDefToFacetObjectWrapper(child, table, hasFilterOrFacet);
+        const wrapper = _facetColumnHelpers.sourceDefToFacetObjectWrapper(child, reference, hasFilterOrFacet);
         children.push(wrapper);
       } catch (exp: unknown) {
-        $log.info(`child of facet group "${sourceObject.markdown_name}", index: ${children.length} is invalid:`);
+        $log.info(`child of facet group "${sourceObject.markdown_name}", index: ${children.length} is invalid/ignored:`);
         $log.info((exp as Error).message);
       }
     }

package/src/services/active-list.ts

@@ -379,6 +379,11 @@ export class ActiveListBuilder {
     conditionedItem: ActiveListConditionedItem,
     addToDependent: (dependentRequests: Array<ActiveListRequest | ActiveListRelatedEntityRequest>) => void,
   ): void {
+    // Defense: no-source conditions (column === null) are evaluated synchronously
+    // at column-build time and should never reach the ActiveList. Caller
+    // (`tryCondition`) already guards this; bail safely if something slipped past.
+    if (!condition.column) return;
+
     // dedup: if this condition was already grouped (via condition_key), reuse
     // that group's dependent list and add this item to its conditionedItems list.
     if (condition.conditionKey) {
@@ -396,7 +401,7 @@ export class ActiveListBuilder {
     // this populates `requests` (with `condition: true, index: conditionIndex`
     // so chaise routes the completion to evaluateCondition); for sync sources
     // it's a no-op on `requests` but still populates `allOutBounds` / `selfLinks`.
-    this.addCol(condition.column, false, ActiveListRequestTypes.CONDITION, conditionIndex);
+    this.addCol(condition.column!, false, ActiveListRequestTypes.CONDITION, conditionIndex);
     condition.waitFor.forEach((wf) => {
       this.addCol(wf, true, ActiveListRequestTypes.CONDITION, conditionIndex);
     });

package/src/services/handlebars.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-useless-escape */
 import Handlebars from 'handlebars';
+import { map as lodashMap } from 'lodash-es';
 import moment from 'moment-timezone';
 
 import $log from '@isrd-isi-edu/ermrestjs/src/services/logger';
@@ -11,11 +12,11 @@ import {
   _addErmrestVarsToTemplate,
   _addTemplateVars,
   _escapeMarkdownCharacters,
-  _formatUtils,
   _getPath,
   encodeFacet,
   encodeFacetString,
 } from '@isrd-isi-edu/ermrestjs/js/utils/helpers';
+import { _formatUtils } from '@isrd-isi-edu/ermrestjs/src/utils/format-utils';
 import AuthnService from '@isrd-isi-edu/ermrestjs/src/services/authn';
 import { isObjectAndNotNull } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
 import { fixedEncodeURIComponent } from '@isrd-isi-edu/ermrestjs/src/utils/value-utils';
@@ -402,6 +403,28 @@ export default class HandlebarsService {
         return _formatUtils.humanizeBytes(value, mode, precision, tooltip);
       },
 
+      /**
+       * {{datetimeDuration start end}}
+       * {{datetimeDuration start end unit="month"}}
+       * {{datetimeDuration start end unit="auto" fraction=2}}
+       * {{datetimeDuration start end unit="multi"}}
+       * {{datetimeDuration start end unit="calendar"}}
+       * {{datetimeDuration start end direction="before/after"}}
+       * {{datetimeDuration start end unit="month" tooltip=true}}
+       * @ignore
+       * @returns human-readable duration between `start` and `end`
+       */
+      datetimeDuration: function (start: any, end: any, options: Handlebars.HelperOptions) {
+        let unit, fraction, direction, tooltip;
+        if (options && isObjectAndNotNull(options.hash)) {
+          unit = options.hash.unit;
+          fraction = options.hash.fraction;
+          direction = options.hash.direction;
+          tooltip = options.hash.tooltip;
+        }
+        return _formatUtils.datetimeDuration(start, end, unit, fraction, direction, tooltip);
+      },
+
       /**
        * {{stringLength value }}
        * @ignore
@@ -419,15 +442,7 @@ export default class HandlebarsService {
        * @returns a boolean indicating if the user is in any of the given groups
        */
       isUserInAcl: function (...args) {
-        const groups = args.reduce((acc, arg) => {
-          if (Array.isArray(arg)) {
-            return acc.concat(arg);
-          } else if (typeof arg === 'string') {
-            return acc.concat([arg]);
-          }
-          return acc;
-        }, []);
-
+        const groups = flattenVariadicArgs(args).filter((g): g is string => typeof g === 'string');
         return AuthnService.isUserInAcl(groups);
       },
 
@@ -591,6 +606,40 @@ export default class HandlebarsService {
         return Number(arg1) - Number(arg2);
       },
     });
+
+    // list/array helpers
+    Handlebars.registerHelper({
+      /**
+       * {{#if (memberOf scalarCol "a" "b" "c")}}
+       * {{#if (memberOf scalarCol someArray)}}
+       * {{#if (memberOf scalarCol (pluck $self "values.type"))}}
+       *
+       * Variadic args; any array argument is flattened one level.
+       * @returns true if `value` equals any of the given args
+       */
+      memberOf: function (value: unknown, ...args: unknown[]) {
+        return flattenVariadicArgs(args).includes(value);
+      },
+
+      /**
+       * {{#if (hasMember arrayCol "non-polymer")}}
+       * @returns true if `array` is an array containing `value`
+       */
+      hasMember: function (array: unknown, value: unknown) {
+        return Array.isArray(array) && array.includes(value);
+      },
+
+      /**
+       * {{pluck $self "values.type"}}
+       *
+       * Preserves length and order; missing paths resolve to undefined.
+       * @returns array of values from `array` at the given lodash path
+       */
+      pluck: function (array: unknown, path: string): unknown[] {
+        if (!Array.isArray(array) || typeof path !== 'string' || !path) return [];
+        return lodashMap(array, path);
+      },
+    });
   }
 }
 
@@ -602,6 +651,16 @@ const reduceOp = function (args: any[], reducer: (a: boolean, b: boolean) => boo
   return args.reduce(reducer, first);
 };
 
+/**
+ * Drops the trailing Handlebars `options` arg, then flattens any array args
+ * one level into a single list. Used by variadic helpers that accept either
+ * loose values or arrays (e.g. `(memberOf col "a" "b")` vs `(memberOf col arr)`).
+ */
+const flattenVariadicArgs = function (args: unknown[]): unknown[] {
+  const rest = args.slice(0, -1); // drop options
+  return rest.reduce<unknown[]>((acc, a) => acc.concat(Array.isArray(a) ? a : [a]), []);
+};
+
 const regexpFindAll = function (value: string, regexp: string, flags: string) {
   const regexpObj = new RegExp(regexp, flags);
   const matches = value.match(regexpObj);

package/src/utils/column-utils.ts

@@ -18,12 +18,12 @@ import { isDefinedAndNotNull } from '@isrd-isi-edu/ermrestjs/src/utils/type-util
 
 // legacy
 import {
-  _formatUtils,
   _generateRowPresentation,
   _getRowTemplateVariables,
   _processColumnOrderList,
   _renderTemplate,
 } from '@isrd-isi-edu/ermrestjs/js/utils/helpers';
+import { _formatUtils } from '@isrd-isi-edu/ermrestjs/src/utils/format-utils';
 
 /**
  * Convert the raw value of an aggregate column to a formatted value.

package/src/utils/constants.ts

@@ -286,6 +286,7 @@ export const _handlebarsHelpersList = [
   'toTitleCase',
   'replace',
   'humanizeBytes',
+  'datetimeDuration',
   'printf',
   'stringLength',
   'isUserInAcl',
@@ -294,6 +295,10 @@ export const _handlebarsHelpersList = [
   // math helpers
   'add',
   'subtract',
+  // list/array helpers
+  'memberOf',
+  'hasMember',
+  'pluck',
 ];
 
 export const _operationsFlag = Object.freeze({
@@ -407,6 +412,8 @@ export const _warningMessages = Object.freeze({
   USED_IN_IFRAME_INPUT: 'the column already used in another column mapping.',
   CONDITION: {
     INVALID_SOURCE: 'condition definition is invalid. `source` or `sourcekey` is required and must be valid.',
+    MISSING_PATTERN: 'condition without `source`/`sourcekey` must define `condition_pattern`.',
+    NO_SOURCE_WAIT_FOR: 'condition without `source`/`sourcekey` cannot use `wait_for`.',
   },
 });
 
@@ -523,6 +530,83 @@ export const _sourceProperties = Object.freeze({
 
 export const _exportKnownAPIs = ['entity', 'attribute', 'attributegroup', 'aggregate'];
 
+/**
+ * Named constants for the `unit` argument of `datetimeDuration`. Source of
+ * truth for valid unit values — `_datetimeDuration.VALID_UNITS` and
+ * `UNIT_ORDER` are derived from this object below.
+ *
+ * Includes the three pseudo-units (`AUTO`, `MULTI`, `CALENDAR`) alongside the
+ * seven real time units. Use `DurationRealUnit` for the real-unit subset.
+ */
+export const DURATION_UNIT = Object.freeze({
+  AUTO: 'auto',
+  MULTI: 'multi',
+  CALENDAR: 'calendar',
+  YEAR: 'year',
+  MONTH: 'month',
+  DAY: 'day',
+  HOUR: 'hour',
+  MINUTE: 'minute',
+  SECOND: 'second',
+  MILLISECOND: 'millisecond',
+} as const);
+export type DurationUnit = (typeof DURATION_UNIT)[keyof typeof DURATION_UNIT];
+
+/**
+ * Named constants for the `direction` argument of `datetimeDuration`. Source
+ * of truth for valid direction values — `_datetimeDuration.VALID_DIRECTIONS`
+ * is derived from this object below.
+ */
+export const DURATION_DIRECTION = Object.freeze({
+  SIGN: 'sign',
+  BEFORE_AFTER: 'before/after',
+  EARLIER_LATER: 'earlier/later',
+  UNSIGNED: 'unsigned',
+} as const);
+export type DurationDirection = (typeof DURATION_DIRECTION)[keyof typeof DURATION_DIRECTION];
+
+export const _datetimeDuration = Object.freeze({
+  // Real units in walking order (largest first). The source of truth for what
+  // counts as a "real" (non-pseudo) duration unit.
+  UNIT_ORDER: [
+    DURATION_UNIT.YEAR,
+    DURATION_UNIT.MONTH,
+    DURATION_UNIT.DAY,
+    DURATION_UNIT.HOUR,
+    DURATION_UNIT.MINUTE,
+    DURATION_UNIT.SECOND,
+    DURATION_UNIT.MILLISECOND,
+  ] as const,
+  ABBREVIATIONS: {
+    [DURATION_UNIT.YEAR]: 'Y',
+    [DURATION_UNIT.MONTH]: 'M',
+    [DURATION_UNIT.DAY]: 'D',
+    [DURATION_UNIT.HOUR]: 'h',
+    [DURATION_UNIT.MINUTE]: 'm',
+    [DURATION_UNIT.SECOND]: 's',
+    [DURATION_UNIT.MILLISECOND]: 'ms',
+  },
+  // Julian fixed-math constants (1Y = 365.25d, 1M = 365.25/12d).
+  // Self-consistent (12 * MONTH === YEAR), matches moment.js / date-fns / astronomy.
+  CONVERSION_RATES: {
+    [DURATION_UNIT.MILLISECOND]: 1,
+    [DURATION_UNIT.SECOND]: 1000,
+    [DURATION_UNIT.MINUTE]: 60 * 1000,
+    [DURATION_UNIT.HOUR]: 60 * 60 * 1000,
+    [DURATION_UNIT.DAY]: 24 * 60 * 60 * 1000,
+    [DURATION_UNIT.MONTH]: (365.25 / 12) * 24 * 60 * 60 * 1000, // 2,629,800,000
+    [DURATION_UNIT.YEAR]: 365.25 * 24 * 60 * 60 * 1000, // 31,557,600,000
+  },
+  VALID_UNITS: Object.values(DURATION_UNIT) as readonly DurationUnit[],
+  VALID_DIRECTIONS: Object.values(DURATION_DIRECTION) as readonly DurationDirection[],
+});
+
+/**
+ * The real (non-pseudo) subset of `DurationUnit`, derived from `UNIT_ORDER`
+ * so it stays in sync automatically.
+ */
+export type DurationRealUnit = (typeof _datetimeDuration.UNIT_ORDER)[number];
+
 export const FILTER_TYPES = Object.freeze({
   BINARYPREDICATE: 'BinaryPredicate',
   CONJUNCTION: 'Conjunction',