@amityco/ts-sdk 7.10.1-86aa7706.0 → 7.10.1-9fe9d33d.0

package/src/core/query/paging.ts

@@ -0,0 +1,172 @@
+import { decode, encode } from 'js-base64';
+
+/**
+ * Type guard to find if the a given decoded backend token uses "skip" pagination style
+ *
+ * @param json any json object as extracted from the backend
+ * @returns success boolean if the token has either "skip" or "limit" props
+ *
+ * @hidden
+ */
+export const isSkip = (json: Record<string, unknown>): json is Amity.SkipLimitPagination =>
+  ['skip'].some(prop => prop in json);
+
+/**
+ * Type guard to find if the a given decoded backend token uses "after/before" pagination style
+ *
+ * @param json any json object as extracted from the backend
+ * @returns success boolean if the token has either "after" or "before" props
+ *
+ * @hidden
+ */
+export const isAfterBefore = (json: Record<string, unknown>): json is Amity.AfterBeforePagination =>
+  ['after', 'before', 'first', 'last', 'limit'].some(prop => prop in json);
+
+/**
+ * Type guard to find if the a given decoded backend token uses v4 or newer "after/before" pagination style
+ *
+ * @param json any json object as extracted from the backend
+ * @returns success boolean if the token has either "after" or "before" props
+ *
+ * @hidden
+ */
+export const isAfterBeforeRaw = (
+  json: Record<string, unknown>,
+): json is Amity.AfterBeforeRawPagination => 'limit' in json;
+
+/**
+ * Type guard to find if the a given object is wrapped around Amity.Paged<>
+ *
+ * @param payload any object as passed from query functions
+ * @returns success boolean if the object is an object shaped as { data: T[] } & Amity.Pages
+ *
+ * @hidden
+ */
+export const isPaged = <T extends unknown>(
+  payload: any,
+): payload is Amity.Paged<T, any> & { paging?: Amity.Pagination['paging'] } => {
+  return (
+    payload?.hasOwnProperty('data') &&
+    payload?.hasOwnProperty('nextPage') &&
+    payload?.hasOwnProperty('prevPage')
+  );
+};
+
+/**
+ * Converts a paging object into a b64 string token
+ *
+ * @param paging the sdk-friendly paging object
+ * @param style the style of token to produce
+ * @returns a backend's b64 encoded token
+ *
+ * @hidden
+ */
+export const toToken = (
+  paging: Amity.Page | Amity.PageRaw | undefined,
+  style: Amity.PaginationStyles,
+): Amity.Token | undefined => {
+  if (!paging || !Object.keys(paging).length) return;
+
+  let payload = {};
+
+  // TODO: refactor this clean
+  if (style === 'skiplimit') {
+    payload = {
+      skip: paging.after ?? 0,
+      limit: paging.limit,
+    };
+  } else if (style === 'afterbefore' && isAfterBefore(paging)) {
+    /*
+      Caution: this testing style is only valid because
+      our backend expects nothing else than a number as
+      "before" or "after" value. if that would change,
+      we'd need to move toward a more simple: `!paging.before`
+    */
+    if (paging?.before) {
+      payload = {
+        ...payload,
+        before: paging.before,
+      };
+    }
+    if (paging?.after) {
+      payload = {
+        ...payload,
+        after: paging.after,
+      };
+    }
+    if (!Number.isNaN(Number(paging?.limit))) {
+      payload = {
+        ...payload,
+        limit: paging.limit,
+      };
+    }
+  } else if (style === 'afterbeforeraw') {
+    payload = paging;
+  }
+
+  // avoid sending {} as it seems backend flips when we do
+  if (!Object.keys(payload).length) return;
+
+  // don't try catch, let it throw
+  return encode(JSON.stringify(payload));
+};
+
+/**
+ * Converts a b64 string token into a paging object
+ *
+ * @param token the backend's b64 encoded token
+ * @returns a sdk-friendly paging object
+ *
+ * @hidden
+ */
+export const toPage = (token?: Amity.Token): Amity.Page | undefined => {
+  if (!token) return undefined;
+
+  // don't try catch, let it throw
+  const json = JSON.parse(decode(token));
+
+  if (isSkip(json)) {
+    return {
+      after: json.skip,
+      limit: json.limit!,
+    } as Amity.NextPage<number>;
+  }
+  if (isAfterBefore(json)) {
+    if ('before' in json) {
+      return {
+        before: json.before,
+        limit: json.last,
+      } as Amity.PrevPage<number>;
+    }
+
+    if ('after' in json) {
+      return {
+        after: json.after,
+        limit: json.first,
+      } as Amity.NextPage<number>;
+    }
+  }
+
+  return undefined;
+};
+
+/**
+ * Converts a b64 string token into a paging object
+ *
+ * @param token the backend's b64 encoded token
+ * @returns a sdk-friendly paging object
+ *
+ * @hidden
+ */
+export const toPageRaw = (token?: Amity.Token): Amity.PageRaw | undefined => {
+  if (!token) return undefined;
+
+  // don't try catch, let it throw
+  const json = JSON.parse(decode(token));
+
+  if (isAfterBeforeRaw(json)) {
+    return json as Amity.PageRaw;
+  }
+
+  return undefined;
+};

package/src/core/query/query.ts

@@ -0,0 +1,240 @@
+/* eslint-disable no-use-before-define */
+import { CACHE_LIFESPAN } from '~/cache/utils';
+import { isPaged } from './paging';
+
+/**
+ * Type guard to check and cast that a given async function is has the ".locally" property
+ *
+ * @param func any SDK APi function
+ * @returns success boolean if the function has a 'locally' twin
+ *
+ * @hidden
+ */
+export const isFetcher = <Args extends any[], Returned extends any>(
+  func: Amity.AsyncFunc<Args, Returned>,
+): func is Amity.FetcherFunc<Args, Returned> => 'locally' in func;
+
+/**
+ * Type guard to check and cast that a given async function is has the ".optimistically" property
+ *
+ * @param func any SDK APi function
+ * @returns success boolean if the function has an 'optimistically' twin
+ *
+ * @hidden
+ */
+export const isMutator = <Args extends any[], Returned extends any>(
+  func: Amity.AsyncFunc<Args, Returned>,
+): func is Amity.MutatorFunc<Args, Returned> => 'optimistically' in func;
+
+/**
+ * Type guard to check and cast that a given async function is has
+ * the ".locally" or ".optimistically" property
+ *
+ * @param func any SDK APi function
+ * @returns success boolean if the function has an offline twin
+ *
+ * @hidden
+ */
+export const isOffline = <Args extends any[], Returned extends any>(
+  func: Amity.AsyncFunc<Args, Returned>,
+): func is Amity.OfflineFunc<Args, Returned> => isFetcher(func) || isMutator(func);
+
+/**
+ * Type guard to check and cast that a given object has the "cachedAt" property
+ *
+ * @param model any object to check on
+ * @returns success boolean if the object has property "cachedAt"
+ *
+ * @hidden
+ */
+export const isCachable = (model: any): model is Amity.Cachable =>
+  model?.hasOwnProperty('cachedAt');
+
+/**
+ * Checks if a model is considered local (cachedAt === -1)
+ *
+ * @param model any cachable object to check
+ * @returns success boolean if the object is marked as local
+ *
+ * @hidden
+ */
+export const isLocal = (model?: any): model is Amity.Local => {
+  return isCachable(model) && model?.cachedAt === -1;
+};
+
+/**
+ * Checks if a model is considered fresh
+ *
+ * @param model any cachable object to check
+ * @param lifeSpan the supposedly duration for which the object is considered synced
+ * @returns success boolean if the object is below the given lifespan
+ *
+ * @hidden
+ */
+export const isFresh = (model?: Amity.Cachable, lifeSpan = CACHE_LIFESPAN) => {
+  return Date.now() - (model?.cachedAt ?? 0) <= lifeSpan;
+};
+
+/**
+ * ```js
+ * import { createQuery, getUser } from '@amityco/ts-sdk'
+ * const query = createQuery(getUser, 'foobar')
+ * ```
+ *
+ * Creates a wrapper for the API call you wish to call.
+ * This wrapper is necessary to create for optimistically calls
+ *
+ *
+ * @param func A compatible API function from the ts sdk
+ * @param args The arguments to pass to the function passed as `fn`
+ * @returns A wrapper containing both the function and its future arguments
+ *
+ * @category Query
+ */
+export const createQuery = <Args extends any[], Returned extends any>(
+  func: Amity.AsyncFunc<Args, Returned> | Amity.OfflineFunc<Args, Returned>,
+  ...args: Args
+) => ({ func, args });
+
+/**
+ * ```js
+ * import { queryOptions } from '@amityco/ts-sdk'
+ * const options = queryOptions('no_fetch', lifeSpan)
+ * ```
+ *
+ * Creates a query options object based on the query policy passed
+ *
+ * @param policy The policy to apply to a query
+ * @returns A properly set query options object
+ *
+ * @category Query
+ */
+export const queryOptions = (
+  policy: Amity.QueryPolicy,
+  lifeSpan: number = CACHE_LIFESPAN, // 1mn
+): Amity.QueryOptions => {
+  if (policy === 'cache_only') return { lifeSpan: Infinity };
+
+  return { lifeSpan: lifeSpan < CACHE_LIFESPAN ? CACHE_LIFESPAN : lifeSpan };
+};
+
+/**
+ * Checks if an unknown shaped payload is considered empty or not.
+ * Since the payload can be wrapped around [] or {} (query or get many),
+ * we need a smarter definition of what's considered "empty".
+ *
+ * @param local the unknown object to check for emptiness
+ * @returns true if the mixed-shape "local" content is considered empty
+ *
+ * @hidden
+ */
+const isEmpty = (local: unknown) => {
+  // if it's supposed to be a single object, it'd be undefined
+  if (!local) return true;
+
+  // it's a paged query, the 1st cell of the array would be empty
+  if (isPaged(local) && isEmpty(local.data)) {
+    return true;
+  }
+
+  // if it's a item collection, it'd have no keys
+  if (typeof local === 'object' && !Object.keys(local).length) return true;
+
+  return false;
+};
+
+/**
+ * ```js
+ * import { createQuery, getUser, runQuery } from '@amityco/ts-sdk'
+ * const query = createQuery(getUser, client, 'foobar')
+ * runQuery(query,  user => console.log(user))
+ * ```
+ *
+ * Calls an API function wrapped around a Amity.Query, and executes the callback whenever
+ * a value is available. The value can be picked either from the local cache and/or
+ * from the server afterwards depending on the query options passed
+ *
+ * @param query A query object wrapping the call to be made
+ * @param callback A function to execute when a value is available
+ * @param options the query options
+ *
+ * @category Query
+ */
+export const runQuery = <Args extends any[], Returned extends any>(
+  { func, args }: Amity.Query<Args, Returned>,
+  callback?: (args: Amity.Snapshot<Returned>) => void,
+  options: Amity.QueryOptions = queryOptions('cache_then_server'),
+) => {
+  let local: Returned | undefined;
+
+  const { lifeSpan } = queryOptions('cache_then_server', options.lifeSpan);
+
+  // offline first
+  if (isOffline(func)) {
+    try {
+      local = isMutator(func) ? func.optimistically(...args) : func.locally(...args);
+    } catch (error) {
+      callback?.(
+        createSnapshot<Returned>(undefined, {
+          origin: 'local',
+          loading: false,
+          error,
+        }),
+      );
+    }
+
+    const shouldAbort = isCachable(local) && isFresh(local, lifeSpan);
+
+    callback?.(
+      createSnapshot<Returned>(local, {
+        origin: 'local',
+        loading: !(isFetcher(func) && shouldAbort),
+      }),
+    );
+
+    if (shouldAbort) return;
+  } else {
+    callback?.(
+      createSnapshot<Returned>(undefined, {
+        origin: 'local',
+        loading: true,
+      }),
+    );
+  }
+
+  func(...args)
+    .then(fresh => {
+      callback?.(
+        createSnapshot<Returned>(fresh, {
+          origin: 'server',
+          loading: false,
+        }),
+      );
+    })
+    .catch(error => {
+      callback?.(
+        createSnapshot<Returned>(undefined, {
+          origin: 'server',
+          loading: false,
+          error,
+        }),
+      );
+    });
+};
+
+/**
+ * This is a TS hack around types
+ *
+ * @param data
+ * @param options
+ *
+ * @category Query API
+ * @hidden
+ */
+function createSnapshot<T>(data: T | undefined, options?: Amity.SnapshotOptions): Amity.Snapshot<T>;
+// eslint-disable-next-line no-redeclare
+function createSnapshot(data: unknown, options?: Amity.SnapshotOptions): unknown {
+  if (isPaged(data) || isCachable(data)) return { ...options, ...data };
+
+  return { ...options, data };
+}

package/src/core/query/sorting.ts

@@ -0,0 +1,90 @@
+// Note:
+// this file should contain a suite of sorting utilities to help the
+// local version of the query functions.
+
+type SortingFunc<T = Record<string, unknown>> = (a: T, b: T) => number;
+
+/**
+ * Alphabetic sorting of objects having a displayName
+ */
+export const sortByDisplayName: SortingFunc<{ displayName?: string }> = (
+  { displayName: a },
+  { displayName: b },
+) => {
+  if (a && b) return a.localeCompare(b);
+  return a ? -1 : 1;
+};
+
+/**
+ * Alphabetic sorting of objects having a name
+ */
+export const sortByName: SortingFunc<{ name?: string }> = ({ name: a }, { name: b }) => {
+  if (a && b) return a.localeCompare(b);
+  return a ? -1 : 1;
+};
+
+/**
+ * Sorting a collection by their apparition order (oldest first)
+ */
+export const sortByChannelSegment: SortingFunc<{ channelSegment: number }> = (
+  { channelSegment: a },
+  { channelSegment: b },
+) => a - b;
+
+/**
+ * Sorting a collection by their apparition order (oldest first)
+ */
+export const sortBySegmentNumber: SortingFunc<{ segmentNumber: number }> = (
+  { segmentNumber: a },
+  { segmentNumber: b },
+) => a - b;
+
+/**
+ * Sorting a collection by its oldest items
+ */
+export const sortByFirstCreated: SortingFunc<{ createdAt: Date | number | string }> = (
+  { createdAt: a },
+  { createdAt: b },
+) => new Date(a).valueOf() - new Date(b).valueOf();
+
+/**
+ * Sorting a story-collection by its localSortingDate
+ */
+export const sortByLocalSortingDate: SortingFunc<{
+  localSortingDate: Date | number | string;
+}> = ({ localSortingDate: a }, { localSortingDate: b }) =>
+  new Date(b).getTime() - new Date(a).getTime();
+
+/**
+ * Sorting a collection by its newest items
+ */
+export const sortByLastCreated: SortingFunc<{ createdAt: Date | number | string }> = (
+  { createdAt: a },
+  { createdAt: b },
+) => new Date(b).valueOf() - new Date(a).valueOf();
+
+/**
+ * Sorting a collection by its oldest items
+ * -- Due to Amity.UpdatedAt is an optional type, we need to define a default value to 0 to prevent error
+ */
+export const sortByFirstUpdated: SortingFunc<{ updatedAt?: Date | number | string }> = (
+  { updatedAt: a = 0 },
+  { updatedAt: b = 0 },
+) => new Date(a).valueOf() - new Date(b).valueOf();
+
+/**
+ * Sorting a collection by its newest items
+ * -- Due to Amity.UpdatedAt is an optional type, we need to define a default value to 0 to prevent error
+ */
+export const sortByLastUpdated: SortingFunc<{ updatedAt?: Date | number | string }> = (
+  { updatedAt: a = 0 },
+  { updatedAt: b = 0 },
+) => new Date(b).valueOf() - new Date(a).valueOf();
+
+/**
+ * Sorting a collection by the items with most recent activity
+ */
+export const sortByLastActivity: SortingFunc<{ lastActivity: Date | number | string }> = (
+  { lastActivity: a },
+  { lastActivity: b },
+) => new Date(b).valueOf() - new Date(a).valueOf();

package/src/core/query/tests/filtering.test.ts

@@ -0,0 +1,58 @@
+import { filterByPropEquality, filterBySearchTerm, filterByStringComparePartially } from '..';
+
+const searchTermCollection = [
+  { userId: 'userId', user: { displayName: 'displayName' } as Amity.InternalUser },
+  { userId: 'notSearched', user: { displayName: 'do-not-return' } as Amity.InternalUser },
+];
+
+describe('filtering:', () => {
+  describe('> filterBySearchTerm', () => {
+    test('it should return items that match userId', () => {
+      expect(filterBySearchTerm(searchTermCollection, 'user')).toStrictEqual([
+        searchTermCollection[0],
+      ]);
+    });
+
+    test('it should ignore search term case', () => {
+      expect(filterBySearchTerm(searchTermCollection, 'USER')).toStrictEqual([
+        searchTermCollection[0],
+      ]);
+    });
+
+    test('it should return items that match displayName', () => {
+      expect(filterBySearchTerm(searchTermCollection, 'displ')).toStrictEqual([
+        searchTermCollection[0],
+      ]);
+    });
+
+    test('it should return empty collection when no items match', () => {
+      expect(filterBySearchTerm(searchTermCollection, 'non-existent')).toStrictEqual([]);
+    });
+  });
+
+  describe('> filterByPropEquality', () => {
+    test('it should filter by prop equality', () => {
+      const prop = 'prop';
+      const collection = [{ [prop]: 'value' }];
+
+      expect(filterByPropEquality(collection, prop, 'value')).toStrictEqual(collection);
+      expect(filterByPropEquality(collection, prop, 'otherValue')).toStrictEqual([]);
+    });
+  });
+
+  describe('string match partially', () => {
+    const collection = [{ displayName: 'Test' }, { displayName: 'test' }, { displayName: 'admin' }];
+    test('it should return 2 items which match with search string', () => {
+      expect(filterByStringComparePartially(collection, 'displayName', 'te')).toStrictEqual([
+        collection[0],
+        collection[1],
+      ]);
+    });
+
+    test('it should return 1 items which match with search string', () => {
+      expect(filterByStringComparePartially(collection, 'displayName', 'admin')).toStrictEqual([
+        collection[2],
+      ]);
+    });
+  });
+});

package/src/core/query/tests/paging.test.ts

@@ -0,0 +1,66 @@
+import { toPage, isSkip, isAfterBefore } from '../paging';
+
+describe('paging', () => {
+  const skipToken = 'eyJza2lwIjoiMTAiLCJsaW1pdCI6IjEwIn0=';
+  const afterToken = 'eyJhZnRlciI6InRlc3QtdG9rZW4iLCJsaW1pdCI6Mn0=';
+  const beforeToken =
+    'eyJiZWZvcmUiOiI2M2Y0NzFjZmI2MTQzOTExZjFkMWUwNmYiLCJsaW1pdCI6Miwic2VnbWVudCI6Nn0=';
+
+  describe('toPage', () => {
+    test('it should return expected response for skip paging token', () => {
+      const expected = { after: '10', limit: '10' };
+
+      expect(toPage(skipToken)).toStrictEqual(expected);
+    });
+
+    test('it should return appropriate response for "before" paging token', () => {
+      const expected = {
+        before: '63f471cfb6143911f1d1e06f',
+        limit: undefined,
+      };
+
+      expect(toPage(beforeToken)).toStrictEqual(expected);
+    });
+
+    test('it should return appropriate response for "after" paging token', () => {
+      const expected = {
+        after: 'test-token',
+        limit: undefined,
+      };
+
+      expect(toPage(afterToken)).toStrictEqual(expected);
+    });
+  });
+
+  describe('isSkip', () => {
+    test('it should return true if skip prop in object', () => {
+      expect(isSkip({ skip: 10 })).toBe(true);
+    });
+
+    test('it should return true if skip prop not in object', () => {
+      expect(isSkip({ limit: 10 })).toBe(false);
+    });
+  });
+
+  describe('isAfterBefore', () => {
+    test('it should return true if after prop in object', () => {
+      expect(isAfterBefore({ after: '' })).toBe(true);
+    });
+
+    test('it should return true if before prop in object', () => {
+      expect(isAfterBefore({ before: '' })).toBe(true);
+    });
+
+    test('it should return true if first prop in object', () => {
+      expect(isAfterBefore({ first: '' })).toBe(true);
+    });
+
+    test('it should return true if last prop in object', () => {
+      expect(isAfterBefore({ last: '' })).toBe(true);
+    });
+
+    test('it should return false if skip prop in object', () => {
+      expect(isAfterBefore({ skip: '' })).toBe(false);
+    });
+  });
+});