Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace utils

Extends ModelCollection instances with helpful functionality.

// esm
import { models } from '@paychex/core';

// cjs
const { models } = require('@paychex/core');

// iife
const { models } = window['@paychex/core'];

// amd
require(['@paychex/core'], function({ models }) { ... });
define(['@paychex/core'], function({ models }) { ... });
example
import { createRequest, fetch } from '~/path/to/data';

const getUserReports = {
  method: 'GET',
  base: 'reporting',
  path: 'reports/:user',
};

export async function getReports(user) {
  const request = createRequest(getUserReports, { user });
  const response = await fetch(request);
  const reportList = models.collection(...response.data);
  // order reports newest first and then by name
  return models.utils.withOrdering(reportList, ['date', 'name'], ['desc', 'asc']);
}

Index

Interfaces

Variables

Functions

Variables

Events

Events: models.utils.EventCollection = ...

Functions

withActive

  • Adds "active item" tracking and navigation to an existing ModelCollection instance.

    example
    const list = models.utils.withActive(models.collection(1, 2, 3));

    list.on('active-change', (current, previous) => {
      console.log('activating', current);
      console.log('deactivating', previous);
    });

    list.active(); // 1
    list.next(); // 2
    list.prev(); // 1
    list.active(3); // 3
    list.next(true); // 1

    Type parameters

    Parameters

    • list: T

      The model list to add active item tracking and navigation to.

    Returns ActiveModelCollection & T

    A ModelCollection with active item tracking and navigation.

withFiltering

  • Filters the specified ModelCollection's items.

    example
    import { getNotificationsList } from '../models/notifications';

    export async function getUnreadNotifications() {
      // wrap an existing ModelCollection
      const list = await getNotificationsList();
      return models.utils.withFiltering(list, ['unread']);
    }
    example
    const isOdd = num => num % 2;
    const list = models.utils.withFiltering(models.collection(), isOdd);

    list.add(1, 2, 3, 4, 5);
    list.items(); // [1, 3, 5]

    list.filterBy(); // reset filtering
    list.items(); // [1, 2, 3, 4, 5]

    Type parameters

    Parameters

    • list: T

      The ModelCollection instance to adapt.

    • filterer: Function = identity

      The filter logic to apply.

    Returns FilteredModelCollection & T

    A ModelCollection with added filtering logic.

withGrouping

  • Applies grouping logic to the specified ModelCollection's items.

    see

    .iteratee and .groupBy

    example
    import { getNotificationsList } from '../models/notifications';

    export async function groupNotifications() {
      // wrap an existing ModelCollection
      const list = await getNotificationsList();
      return models.utils.withGrouping(list, ['status']);
    }
    example
    import { cond, conforms, constant, stubTrue } from 'lodash';
    import { getClientList } from '../models/client';

    const lessThan = (max) => (num) => num < max;

    // function that buckets by employeeCount
    const employeeBuckets = cond([
      [ conforms({ employeeCount: lessThan(10) }), constant('small')  ],
      [ conforms({ employeeCount: lessThan(20) }), constant('medium') ],
      [ stubTrue,                                  constant('large')  ]
    ]);

    export async function getBucketedClientList() {
      const list = await getClientList();
      return models.utils.withGrouping(list, employeeBuckets);
    }

    // CONSUMER:
    const clients = await getBucketedClientList();
    clients.groups(); // { small: [...], medium: [...], large: [...] }

    clients.groupBy(['region']);
    clients.groups(); // { 'east': [...], 'north': [...], 'south': [...] }

    Type parameters

    Parameters

    • list: T

      The ModelCollection instance to adapt.

    • grouper: any = identity

      Optional arguments to pass to lodash's groupBy

    Returns GroupedModelCollection & T

    A ModelCollection with added grouping logic.

withOrdering

  • Orders the specified ModelCollection items. You can order using multiple selector functions and specify a different sort order for each selector.

    see

    .iteratee and .orderBy

    example
    import { getClientData } from '../data';

    export async function getClientList() {
      const clients = await getClientData();
      const list = models.collection(...clients);
      const date = (client) => Date.parse(client.dateModified);
      // order by branch name ascending and then date modified descending...
      // NOTE: we can use lodash iteratee shortcuts for our accessors; see
      // https://lodash.com/docs/4.17.11#iteratee for more information.
      return models.utils.withOrdering(list, ['branch', date], ['asc', 'desc']);
    }

    // CONSUMERS:
    const list = await getClientList();
    list.items(); // [...clients ordered by branch asc and date desc...]

    // modify ordering:
    list.orderBy(); // order by identity
    list.orderBy([...iteratees]); // use ascending order
    list.orderBy([...iteratees], [...orders]); // use specified orders

    Type parameters

    Parameters

    • list: T

      The ModelCollection instance to adapt.

    • Rest ...args: any[]

      Optional arguments to pass to lodash's orderBy method.

    Returns OrderedModelCollection & T

    A ModelCollection with ordering functionality.

withPaging

  • Adds paging to an existing ModelCollection instance.

    example
    // paging over a filtered list

    // order matters! filter first, then page:
    const list = models.utils.withPaging(
      models.utils.withFiltering(
        models.collection()));

    list.pageSize(2);
    list.add(1, 2, 3, 4, 5);
    console.log(list.pageCount); // 3

    const isOdd = num => num % 2;
    list.filterBy(isOdd);
    console.log(list.pageCount); // 2

    list.add(6, 7, 8, 9, 10);
    console.log(list.pageCount); // 3

    console.log(list.pageIndex()); // 0
    console.log(list.items()); // [1, 3]

    list.nextPage();
    console.log(list.items()); // [5, 7]

    Type parameters

    Parameters

    • list: T

      The model list to add paging to.

    • num: number = 50

    Returns PagedModelCollection & T

    A ModelCollection with paging capabilities.

withSelection

  • Adds selection tracking to an existing ModelCollection instance.

    example
    const list = models.utils.withSelection(models.collection(1, 2, 3));

    list.selected(); // []
    list.toggle();   // [1, 2, 3]
    list.toggle(2);  // [1, 3]
    list.selected(3) // [3]

    list.on('selection-change', (selection) => {
      console.log('selection changed', selection);
    });

    list.selected(1); // "selection changed [1]"
    list.toggle(); // "selection changed [1, 2, 3]"

    Type parameters

    Parameters

    • list: T

      The model list to add selection tracking to.

    Returns SelectionModelCollection & T

    A ModelCollection with selection capabilities.

withUnique

  • Applies a uniqueness constraint to the specified ModelCollection.

    see

    .iteratee and .uniqBy

    example
    import { getUsers } from '../data/users';

    export async function getUsersList() {
      const users = await getUsers();
      const userList = models.collection(...users);
      // NOTE: we can use lodash iteratee shortcuts for our selector; see
      // https://lodash.com/docs/4.17.11#iteratee for more information.
      return models.utils.withUnique(userList, 'username');
    }

    Type parameters

    Parameters

    • list: T

      The ModelCollection instance to apply the uniqueness constraint to.

    • selector: any = identity

    Returns UniqueModelCollection & T

    A ModelCollection with a uniqueness constraint.

withUpdating

  • Adds methods to update the underlying collection based on a new collection.

    NOTE: This wrapper uses withUnique to ensure that only 1 instance of an item is present in the underlying collection.

    see

    iteratee and uniqBy

    example
    import { getUsers } from '../data/users';

    export async function getUsersList() {
      const users = await getUsers();
      const userList = models.collection(...users);
      // NOTE: we can use lodash iteratee shortcuts for our selector; see
      // https://lodash.com/docs/4.17.11#iteratee for more information.
      return models.utils.withUpdating(userList, 'username');
    }

    // USAGE:
    const list = await getUsersList();
    const currentUsers = await getUsers(); // maybe on a poll
    list.merge(...currentUsers);

    Type parameters

    Parameters

    • list: T

      The ModelCollection to add updating functionality to.

    • selector: any = identity

      The key selector to use to uniquely identify elements in the collection.

    Returns UpdatingModelCollection & T

    A ModelCollection that has various methods you can invoke to update the underlying collection based on a new collection.