@ethlete/query 5.16.0 → 5.16.1

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

@@ -1,526 +0,0 @@
-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

@@ -1,169 +0,0 @@
-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;
-}