@ethlete/query 5.15.0 → 5.16.0

package/src/lib/query-form/query-form.ts

@@ -0,0 +1,526 @@
+import { NgZone, assertInInjectionContext, inject, isDevMode } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormGroup } from '@angular/forms';
+import { ActivatedRoute, Router } from '@angular/router';
+import { ET_PROPERTY_REMOVED, RouterStateService, clone, createDestroy, equal } from '@ethlete/core';
+import { BehaviorSubject, Subject, debounceTime, map, merge, of, switchMap, takeUntil, tap, timer } from 'rxjs';
+import {
+  QueryFieldOptions,
+  QueryFormGroup,
+  QueryFormGroupControls,
+  QueryFormObserveOptions,
+  QueryFormValue,
+  QueryFormValueEvent,
+  QueryFormWriteOptions,
+} from './query-form.types';
+import { transformToBoolean, transformToNumber } from './query-form.utils';
+
+const ET_ARR_PREFIX = 'ET_ARR__';
+
+export class QueryField<T> {
+  get control() {
+    return this.data.control;
+  }
+
+  constructor(public data: QueryFieldOptions<T>) {}
+}
+
+const IGNORED_FILTER_COUNT_FIELDS = ['page', 'skip', 'take', 'limit', 'sort', 'sortBy', 'sortOrder', 'query', 'search'];
+
+export interface QueryFormOptions {
+  /**
+   * A prefix to use for the query parameters. This is useful when you have multiple query forms on the same page.
+   */
+  queryParamPrefix?: string | (() => string);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyQueryForm = QueryForm<any>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class QueryForm<T extends Record<string, QueryField<any>>> {
+  private readonly _destroy$ = createDestroy();
+  private readonly _unobserveTrigger$ = new Subject<boolean>();
+  private readonly _router = inject(Router);
+  private readonly _activatedRoute = inject(ActivatedRoute);
+  private readonly _defaultValues = this._extractDefaultValues();
+  private readonly _routerStateService = inject(RouterStateService);
+  private readonly _zone = inject(NgZone);
+  private readonly _didValueChanges$ = new Subject<boolean>();
+
+  private _isObserving = false;
+  private _skipNextResets = false;
+
+  /**
+   * The angular form group that contains all the fields.
+   *
+   * **Do not** use any of the following methods on this form group:
+   * - `setValue`: Use `QueryForm.setValue` instead.
+   * - `patchValue`: Use `QueryForm.patchValue` instead.
+   * - `valueChanges`: Use `QueryForm.changes$` instead.
+   * - `value`: Use `QueryForm.value` instead.
+   * - `controls`: Use `QueryForm.controls` instead.
+   */
+  readonly form = this._setupFormGroup();
+
+  private readonly _lastFormValue$ = new BehaviorSubject<QueryFormValue<T> | null>(null);
+  private readonly _currentFormValue$ = new BehaviorSubject<QueryFormValue<T>>(this._formValue);
+
+  private get _formValue() {
+    return this.form.getRawValue() as QueryFormValue<T>;
+  }
+
+  private get _form() {
+    return this.form as unknown as QueryFormGroup;
+  }
+
+  private readonly _changes$ = new BehaviorSubject<QueryFormValueEvent<T>>({
+    previousValue: null,
+    currentValue: this.form.getRawValue() as QueryFormValue<T>,
+  });
+
+  readonly changes$ = this._changes$.asObservable();
+  readonly currentValue$ = this._changes$.pipe(map(({ currentValue }) => currentValue));
+  readonly previousValue$ = this._changes$.pipe(map(({ previousValue }) => previousValue));
+
+  readonly changes = toSignal(this.changes$);
+  readonly currentValue = toSignal(this.currentValue$);
+  readonly previousValue = toSignal(this.previousValue$);
+
+  /**
+   * The number of active filters.
+   *
+   * Excludes the following fields by default:
+   * - `page`
+   * - `skip`
+   * - `take`
+   * - `limit`
+   * - `sort`
+   * - `sortBy`
+   * - `sortOrder`
+   * - `query`
+   * - `search`
+   */
+  readonly activeFilterCount$ = this.changes$.pipe(
+    map(
+      ({ currentValue }) =>
+        Object.entries(currentValue)
+          .map(([key, value]) => {
+            if (IGNORED_FILTER_COUNT_FIELDS.includes(key) || this._fields[key]?.data.skipInFilterCount) {
+              return true;
+            }
+
+            return this._isDefaultValue(key, value);
+          })
+          .filter((v) => v === false).length,
+    ),
+  );
+
+  get controls() {
+    return this.form.controls;
+  }
+
+  get value() {
+    return this._changes$.value.currentValue;
+  }
+
+  get defaultFormValue() {
+    return Object.entries(this._defaultValues).reduce((acc, [key]) => {
+      acc[key as keyof QueryFormValue<T>] = this._getDefaultValue(key);
+
+      return acc;
+    }, {} as QueryFormValue<T>);
+  }
+
+  // with prefix eg. page should become ${prefix}-page
+  constructor(
+    private _fields: T,
+    private _options?: QueryFormOptions,
+  ) {
+    assertInInjectionContext(QueryForm);
+  }
+
+  observe(options?: QueryFormObserveOptions) {
+    if (this._isObserving) {
+      if (isDevMode()) {
+        console.warn('QueryForm.observe() was called multiple times. This is not supported.');
+      }
+      return this;
+    }
+
+    this._isObserving = true;
+
+    if (options?.syncOnNavigation !== false) {
+      const didChanges = this.setFormValueFromUrlQueryParams({
+        queryParams: this._routerStateService.queryParams,
+      });
+
+      if (didChanges) {
+        this._handleFormChange(true);
+      }
+    }
+
+    merge(...Object.values(this._fields).map((field) => field.control.valueChanges), this._didValueChanges$)
+      .pipe(
+        debounceTime(0),
+        tap(() => {
+          this._handleFormChange();
+        }),
+        takeUntil(this._destroy$),
+        takeUntil(this._unobserveTrigger$),
+      )
+      .subscribe();
+
+    let changedFieldsInLastResetLoop: string[] = [];
+    let currentUniqueChangedFields: string[] = [];
+
+    this._currentFormValue$
+      .pipe(
+        map((currentValue) => {
+          return {
+            previousValue: clone(this._lastFormValue$.value),
+            currentValue: clone(currentValue),
+          };
+        }),
+        tap(({ currentValue, previousValue }) => {
+          if (options?.writeToQueryParams !== false) {
+            this._syncViaUrlQueryParams(currentValue, options?.replaceUrl);
+          }
+
+          const didResetValues = this._skipNextResets
+            ? false
+            : this._handleQueryFormResets(previousValue ?? null, currentValue);
+
+          this._skipNextResets = false;
+
+          const changedFields = Object.keys(currentValue).filter(
+            (key) => !equal(previousValue?.[key], currentValue[key]),
+          );
+
+          if (changedFieldsInLastResetLoop.length) {
+            changedFields.push(...changedFieldsInLastResetLoop);
+            changedFieldsInLastResetLoop = [];
+          }
+
+          if (didResetValues) {
+            this._didValueChanges$.next(true);
+            changedFieldsInLastResetLoop = changedFields;
+          }
+
+          currentUniqueChangedFields = [...new Set(changedFields)];
+        }),
+        switchMap(({ currentValue, previousValue }) => {
+          if (changedFieldsInLastResetLoop.length) return of(null).pipe(map(() => ({ currentValue, previousValue })));
+
+          const debounceValues = currentUniqueChangedFields.map((key) => {
+            const field = this._fields[key];
+
+            if (!field) return null;
+
+            if (field.data.disableDebounceIfFalsy === true && !currentValue[key]) {
+              return null;
+            }
+
+            return field.data.debounce ?? null;
+          });
+
+          currentUniqueChangedFields = [];
+
+          if (debounceValues.some((v) => v === null) || !debounceValues.length) {
+            return of(null).pipe(map(() => ({ currentValue, previousValue })));
+          }
+
+          const shortestDebounceTime = Math.min(...debounceValues.filter((v): v is number => v !== null));
+
+          return timer(shortestDebounceTime).pipe(map(() => ({ currentValue, previousValue })));
+        }),
+        tap(({ currentValue, previousValue }) => {
+          if (changedFieldsInLastResetLoop.length) return;
+
+          this._changes$.next({
+            previousValue: previousValue ?? null,
+            currentValue: currentValue,
+          });
+        }),
+        takeUntil(this._destroy$),
+        takeUntil(this._unobserveTrigger$),
+      )
+      .subscribe();
+
+    if (options?.syncOnNavigation !== false) {
+      this._routerStateService.queryParamChanges$
+        .pipe(
+          takeUntil(this._destroy$),
+          takeUntil(this._unobserveTrigger$),
+          tap((changes) => {
+            const didValueChanges = this.setFormValueFromUrlQueryParams({ queryParams: changes });
+
+            if (didValueChanges) {
+              this._didValueChanges$.next(true);
+            }
+          }),
+        )
+        .subscribe();
+    }
+
+    return this;
+  }
+
+  private _handleQueryFormResets(previousValue: QueryFormValue<T> | null, currentValue: QueryFormValue<T>) {
+    let didResetValues = false;
+
+    for (const formFieldKey in this._fields) {
+      const field = this._fields[formFieldKey];
+
+      if (!field) continue;
+
+      const resets = field.data.isResetBy;
+
+      if (!resets) continue;
+
+      const resetConditionKeys = Array.isArray(resets) ? resets : [resets];
+
+      for (const resetConditionKey of resetConditionKeys) {
+        if (!(resetConditionKey in this._fields)) {
+          if (isDevMode()) {
+            console.warn(`The field "${resetConditionKey}" is not defined in the QueryForm. Is it a typo?`, this);
+          }
+
+          continue;
+        }
+
+        if (
+          previousValue &&
+          currentValue &&
+          !equal(previousValue[resetConditionKey], currentValue[resetConditionKey])
+        ) {
+          const defaultValueForKeyToReset = this._getDefaultValue(formFieldKey);
+          const currentValueForKeyToReset = currentValue[formFieldKey];
+
+          if (equal(defaultValueForKeyToReset, currentValueForKeyToReset)) {
+            continue;
+          }
+
+          this.form.controls[formFieldKey].setValue(defaultValueForKeyToReset);
+
+          didResetValues = true;
+
+          break;
+        }
+      }
+    }
+
+    return didResetValues;
+  }
+
+  unobserve() {
+    this._unobserveTrigger$.next(true);
+  }
+
+  setFormValueFromUrlQueryParams(options: { queryParams: Record<string, unknown> }) {
+    let didValueChanges = false;
+
+    for (const [key, field] of Object.entries(this._fields)) {
+      const value = options.queryParams[this._transformKeyToQueryParam(key)];
+
+      const valueDoesNotExist = value === undefined;
+
+      if (valueDoesNotExist) continue;
+
+      const valueGotRemoved = value === ET_PROPERTY_REMOVED;
+
+      if (valueGotRemoved) {
+        field.control.setValue(this._getDefaultValue(key), { emitEvent: false });
+        didValueChanges = true;
+
+        continue;
+      }
+      let deserializedValue = value;
+
+      if (field.data.queryParamToValueTransformFn) {
+        deserializedValue = field.data.queryParamToValueTransformFn(value);
+      } else if (typeof this._getDefaultValue(key) === 'number' || !isNaN(Number(value))) {
+        deserializedValue = transformToNumber(value);
+      } else if (typeof this._getDefaultValue(key) === 'boolean' || value === 'true' || value === 'false') {
+        deserializedValue = transformToBoolean(value);
+      }
+
+      const valueIsEqualToCurrent = equal(deserializedValue, field.control.value);
+
+      if (valueIsEqualToCurrent) continue;
+
+      field.control.setValue(deserializedValue, { emitEvent: false });
+      didValueChanges = true;
+    }
+
+    return didValueChanges;
+  }
+
+  setValue(value: QueryFormValue<T>, options?: QueryFormWriteOptions) {
+    this._form._setValue(value, options);
+
+    if (options?.skipResets) {
+      this._skipNextResets = true;
+    }
+  }
+
+  patchValue(value: Partial<QueryFormValue<T>>, options?: QueryFormWriteOptions) {
+    this._form._patchValue(value, options);
+
+    if (options?.skipResets) {
+      this._skipNextResets = true;
+    }
+  }
+
+  resetFieldToDefault(key: keyof QueryFormValue<T>, options?: QueryFormWriteOptions) {
+    const defaultValue = this._getDefaultValue(key as string);
+
+    this.form.controls[key].setValue(defaultValue);
+
+    if (options?.skipResets) {
+      this._skipNextResets = true;
+    }
+  }
+
+  resetFieldsToDefault(keys: (keyof QueryFormValue<T>)[], options?: QueryFormWriteOptions) {
+    const defaults = keys.reduce(
+      (acc, key) => {
+        acc[key] = this._getDefaultValue(key as string);
+
+        return acc;
+      },
+      {} as Partial<QueryFormValue<T>>,
+    );
+
+    this.patchValue(defaults);
+
+    if (options?.skipResets) {
+      this._skipNextResets = true;
+    }
+  }
+
+  resetAllFieldsToDefault(options?: QueryFormWriteOptions & { skipFields?: (keyof QueryFormValue<T>)[] }) {
+    const keys = Object.keys(this._fields) as (keyof QueryFormValue<T>)[];
+
+    if (options?.skipFields) {
+      for (const key of options.skipFields) {
+        const index = keys.indexOf(key);
+
+        if (index !== -1) {
+          keys.splice(index, 1);
+        }
+      }
+    }
+
+    this.resetFieldsToDefault(keys, options);
+  }
+
+  private _getDefaultValue(key: string) {
+    const val = this._defaultValues[key];
+
+    if (typeof val === 'string' && val.startsWith(ET_ARR_PREFIX)) {
+      return JSON.parse(val.slice(ET_ARR_PREFIX.length));
+    }
+
+    return val ?? null;
+  }
+
+  private _transformKeyToQueryParam(key: string) {
+    if (!this._options?.queryParamPrefix) return key;
+
+    const prefix =
+      typeof this._options?.queryParamPrefix === 'string'
+        ? this._options.queryParamPrefix
+        : this._options.queryParamPrefix();
+
+    return `${prefix}-${key}`;
+  }
+
+  private _isDefaultValue(key: string, value: unknown) {
+    const normalizedValue = Array.isArray(value) ? `${ET_ARR_PREFIX}${JSON.stringify(value)}` : value;
+
+    return this._getDefaultValue(key) === normalizedValue;
+  }
+
+  private _setupFormGroup() {
+    const group = new FormGroup({} as QueryFormGroupControls<T>) as unknown as QueryFormGroup;
+
+    for (const [key, field] of Object.entries(this._fields)) {
+      group.addControl(key, field.control);
+    }
+
+    group._patchValue = group.patchValue;
+    group._setValue = group.setValue;
+
+    group.patchValue = this.patchValue.bind(this);
+    group.setValue = this.setValue.bind(this);
+
+    return group as unknown as FormGroup<QueryFormGroupControls<T>>;
+  }
+
+  private _extractDefaultValues() {
+    const defaultValues: Record<string, unknown> = {};
+
+    for (const [key, field] of Object.entries(this._fields)) {
+      const value = field.data.defaultValue !== undefined ? field.data.defaultValue : field.control.value;
+
+      if (Array.isArray(value)) {
+        defaultValues[key] = `${ET_ARR_PREFIX}${JSON.stringify(value)}`;
+      } else {
+        defaultValues[key] = value;
+      }
+    }
+
+    return defaultValues;
+  }
+
+  private _syncViaUrlQueryParams(values: QueryFormValue<T>, replaceUrl?: boolean) {
+    const queryParams = { ...clone(this._activatedRoute.snapshot.queryParams) };
+
+    for (const [key, value] of Object.entries(values)) {
+      const queryParamKey = this._transformKeyToQueryParam(key);
+      const field = this._fields[key];
+
+      if (!field) {
+        continue;
+      }
+
+      const isDefault = this._isDefaultValue(key, value);
+      const writeDefaultToUrl = field.data.appendDefaultValueToUrl === true;
+      const writeToUrl = field.data.appendToUrl !== false;
+
+      if (!writeToUrl || (isDefault && !writeDefaultToUrl)) {
+        queryParams[queryParamKey] = undefined;
+      } else {
+        queryParams[queryParamKey] = field.data.valueToQueryParamTransformFn
+          ? field.data.valueToQueryParamTransformFn?.(value)
+          : value;
+      }
+    }
+
+    this._zone.run(() => {
+      this._router.navigate([], {
+        queryParams,
+        replaceUrl,
+        queryParamsHandling: 'merge',
+      });
+    });
+  }
+
+  private _handleFormChange(forceOverwrite = false) {
+    const currentVal = clone(this._currentFormValue$.value);
+    const newVal = clone(this._formValue);
+
+    if (equal(currentVal, newVal)) {
+      return;
+    }
+
+    if (forceOverwrite) {
+      this._lastFormValue$.next(newVal);
+    } else {
+      this._lastFormValue$.next(currentVal);
+    }
+
+    this._currentFormValue$.next(newVal);
+  }
+}

package/src/lib/query-form/query-form.types.ts

@@ -0,0 +1,169 @@
+import { FormControl, FormGroup } from '@angular/forms';
+import { QueryField } from './query-form';
+
+export interface QueryFieldOptions<T = unknown> {
+  /**
+   * The default value of the field.
+   * Will be set to the initial value of the form control if not specified.
+   */
+  defaultValue?: T | null;
+
+  /**
+   * Debounce time in milliseconds.
+   */
+  debounce?: number;
+
+  /**
+   *  Whether the debounce should not be applied if the value is falsy.
+   *  This is useful for fields that can be cleared like a search field.
+   *
+   *  @default false
+   */
+  disableDebounceIfFalsy?: boolean;
+
+  /**
+   * The form control for the field.
+   */
+  control: FormControl<T | null>;
+
+  /**
+   * Append the field's value to the url.
+   *
+   * The field wont be appended to the url if one of the following is true:
+   * - It is the default value and `appendDefaultValueToUrl` is `false`
+   * - It is an empty string
+   * - It is `null`
+   * - It is `undefined`
+   *
+   * @default true
+   */
+  appendToUrl?: boolean;
+
+  /**
+   * Append the field's value to the url even if it is the default value.
+   * Will be ignored if `appendToUrl` is `false`.
+   *
+   * @default false
+   */
+  appendDefaultValueToUrl?: boolean;
+
+  /**
+   * Reset the field's value to the default value if one or more of the specified fields are changed.
+   *
+   * @example
+   * // Given this field is a `page` field, the field will be reset if the `limit`, `query` or `search` fields are changed.
+   * ['limit', 'query', 'search']
+   */
+  isResetBy?: string | string[];
+
+  /**
+   * Whether the field should change the count of current active filters.
+   *
+   * Will be `true` for these common fields:
+   * - `page`
+   * - `skip`
+   * - `take`
+   * - `limit`
+   * - `sort`
+   * - `sortBy`
+   * - `sortOrder`
+   * - `query`
+   * - `search`
+   * @default false
+   */
+  skipInFilterCount?: boolean;
+
+  /**
+   * A function that transforms the the value gotten from the url query params to a value required by the field.
+   * E.g. for a number field, the value from the url query params is a string, but the field requires a number.
+   *
+   * The following common transformations are already implemented:
+   * - `transformToString`
+   * - `transformToStringArray`
+   * - `transformToNumber`
+   * - `transformToNumberArray`
+   * - `transformToBoolean`
+   * - `transformToBooleanArray`
+   * - `transformToDate` (expects a string in the default js format)
+   * - `transformToDateArray` (expects strings in the default js format)
+   * - `transformToSort` (expects a string in the format `field:direction`)
+   */
+  queryParamToValueTransformFn?: (val: unknown) => T | null;
+
+  /**
+   * A function that transforms the value of the field to a value that can be appended to the url query params.
+   *
+   * The following common transformations are already implemented:
+   * - `transformToSortQueryParam` (returns an object containing `field` and `direction` properties)
+   */
+  valueToQueryParamTransformFn?: (val: T | null) => unknown;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type QueryFormGroupControls<T extends Record<string, QueryField<any>>> = {
+  [Property in keyof T]: T[Property]['control'];
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type QueryFormValue<T extends Record<string, QueryField<any>>> = {
+  [Property in keyof T]: T[Property]['control']['value'];
+};
+
+export type QueryFormOf<T extends FormGroup> = {
+  [K in keyof T['controls']]: QueryField<T['controls'][K]['value']>;
+};
+
+export interface QueryFormGroup extends FormGroup {
+  _setValue: FormGroup['setValue'];
+  _patchValue: FormGroup['patchValue'];
+  setValue(value: unknown, options?: QueryFormWriteOptions): void;
+  patchValue(value: unknown, options?: QueryFormWriteOptions): void;
+}
+
+export interface QueryFormObserveOptions {
+  /**
+   * Whether the form value should be synced to the url query params.
+   * @default true
+   */
+  writeToQueryParams?: boolean;
+
+  /**
+   * Whether the form value should be updated when the url query params change.
+   * @default true
+   */
+  syncOnNavigation?: boolean;
+
+  /**
+   * If true, the navigation will not create a new entry in the browser's history.
+   * @default false
+   */
+  replaceUrl?: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface QueryFormValueEvent<T extends Record<string, QueryField<any>>> {
+  previousValue: QueryFormValue<T> | null;
+  currentValue: QueryFormValue<T>;
+}
+
+export interface QueryFormWriteOptions {
+  /**
+   * When true, each change only affects this control, and not its parent.
+   * @default false
+   */
+  onlySelf?: boolean;
+
+  /**
+   * When true or not supplied (the default), both the `statusChanges` and `valueChanges`
+   * observables emit events with the latest status and value when the control value is updated.
+   * When false, no events are emitted.
+   * @default true
+   */
+  emitEvent?: boolean;
+
+  /**
+   * When true, the `resetBy` conditions will be ignored for this write.
+   * @default false
+   */
+  skipResets?: boolean;
+}