@amityco/ts-sdk 0.0.1-e5fb0d2.0 → 0.0.1-e643f6f.0

package/src/core/query/paging.ts

@@ -1,17 +1,15 @@
-// @ts-ignore
-import { encode, decode } from 'js-base64'
+import { encode, decode } from 'js-base64';
 
 /**
- * Type guard to find if the a given decoded backend token uses "skip/limit" pagination style
+ * 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 isSkipLimit = (json: Object): json is Amity.SkipLimitPagination => (
-  ['skip', 'limit'].some(prop => prop in json)
-)
+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
@@ -21,25 +19,36 @@ export const isSkipLimit = (json: Object): json is Amity.SkipLimitPagination =>
  *
  * @hidden
  */
-export const isAfterBefore = (json: Object): json is Amity.AfterBeforePagination => (
-  ['after', 'before', 'first', 'last'].some(prop => prop in json)
-)
+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 array shaped as [Record<string, Amity.Syncable>, Amity.Pages]
+ * @returns success boolean if the object is an object shaped as { data: T[] } & Amity.Pages
  *
  * @hidden
  */
-export const isPaged = (payload: any): payload is Amity.Paged<any> => {
+export const isPaged = <T extends unknown>(payload: any): payload is Amity.Paged<T, any> => {
   return (
-     payload?.hasOwnProperty('data')
-  && payload?.hasOwnProperty('nextPage')
-  && payload?.hasOwnProperty('prevPage')
-  )
-}
+    payload?.hasOwnProperty('data') &&
+    payload?.hasOwnProperty('nextPage') &&
+    payload?.hasOwnProperty('prevPage')
+  );
+};
 
 /**
  * Converts a paging object into a b64 string token
@@ -51,49 +60,51 @@ export const isPaged = (payload: any): payload is Amity.Paged<any> => {
  * @hidden
  */
 export const toToken = (
-  paging: Amity.Page | undefined,
-  style: 'skiplimit' | 'afterbefore',
-
+  paging: Amity.Page | Amity.PageRaw | undefined,
+  style: Amity.PaginationStyles,
 ): Amity.Token | undefined => {
-  if (!paging || !Object.keys(paging).length)
-    return
+  if (!paging || !Object.keys(paging).length) return;
 
-  let payload = {}
+  let payload = {};
 
   // TODO: refactor this clean
   if (style === 'skiplimit') {
     payload = {
       skip: paging.after ?? 0,
       limit: paging.limit,
-    }
-  }
-  else if (style === 'afterbefore') {
+    };
+  } 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 (!isNaN(paging?.before!)) {
+    if (!Number.isNaN(Number(paging?.before!))) {
       payload = {
         before: paging.before,
         last: paging.limit,
-      }
-    } else if (!isNaN(paging?.after!)) {
+      };
+    } else if (!Number.isNaN(Number(paging?.after!))) {
       payload = {
         after: paging.after,
         first: paging.limit,
-      }
+      };
+    } else if (!Number.isNaN(Number(paging?.limit!))) {
+      payload = {
+        last: paging.limit,
+      };
     }
+  } else if (style === 'afterbeforeraw') {
+    payload = paging;
   }
 
   // avoid sending {} as it seems backend flips when we do
-  if (!Object.keys(payload).length)
-    return
+  if (!Object.keys(payload).length) return;
 
   // don't try catch, let it throw
-  return encode(JSON.stringify(payload))
-}
+  return encode(JSON.stringify(payload));
+};
 
 /**
  * Converts a b64 string token into a paging object
@@ -103,64 +114,54 @@ export const toToken = (
  *
  * @hidden
  */
-export const toPage = (token?: Amity.Token): Amity.Page | null => {
-  if (!token) return null
+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))
+  const json = JSON.parse(decode(token));
 
-  if (isSkipLimit(json)) {
+  if (isSkip(json)) {
     return {
       after: json.skip,
       limit: json.limit!,
-    } as Amity.NextPage
-  } else if (isAfterBefore(json)) {
+    } as Amity.NextPage<number>;
+  }
+  if (isAfterBefore(json)) {
     if ('before' in json) {
       return {
         before: json.before,
         limit: json.last,
-      } as Amity.PrevPage
-    } else if ('after' in json) {
+      } as Amity.PrevPage<number>;
+    }
+
+    if ('after' in json) {
       return {
         after: json.after,
         limit: json.first,
-      } as Amity.NextPage
+      } as Amity.NextPage<number>;
     }
   }
 
-  return null
-}
+  return undefined;
+};
 
 /**
- * Slices a collection according to its paging
+ * Converts a b64 string token into a paging object
  *
- * @param type the type of collection (for unique id identification with after/before)
- * @param collection the collection to slice
- * @param paging the paging object
- * @returns the sliced collection according to the paging definition
+ * @param token the backend's b64 encoded token
+ * @returns a sdk-friendly paging object
  *
  * @hidden
  */
-export const sliceByPaging = <K extends Amity.Domain, T extends Amity.Model[K]>(
-  type: K, collection: T[], page?: Amity.Page
-) => {
-  console.log('slice by paging', page)
-  if (!page) return collection.slice()
-
-  let start: number | undefined = 0
-  let end: number | undefined = undefined
-
-  // next page behavior
-  if (page.after) {
-    start = page.after
-    end = start + page.limit
-  // prev page behavior
-  } else if (page.before) {
-    end = page.before + 1
-    start = end > page.limit ? end - page.limit : 0
-  }
+export const toPageRaw = (token?: Amity.Token): Amity.PageRaw | undefined => {
+  if (!token) return undefined;
 
-  const paged = collection.slice(start, end)
+  // don't try catch, let it throw
+  const json = JSON.parse(decode(token));
+
+  if (isAfterBeforeRaw(json)) {
+    return json as Amity.PageRaw;
+  }
 
-  return paged.length === page.limit ? paged : undefined
-}
+  return undefined;
+};

package/src/core/query/query.ts

@@ -1,6 +1,6 @@
-import { syncInCache } from '../cache'
-
-import { isPaged } from './paging'
+/* 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
@@ -11,10 +11,8 @@ import { isPaged } from './paging'
  * @hidden
  */
 export const isFetcher = <Args extends any[], Returned extends any>(
-  func: Amity.AsyncFunc<Args, Returned>
-): func is Amity.FetcherFunc<Args, Returned> => (
-  'locally' in func
-)
+  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
@@ -25,10 +23,8 @@ export const isFetcher = <Args extends any[], Returned extends any>(
  * @hidden
  */
 export const isMutator = <Args extends any[], Returned extends any>(
-  func: Amity.AsyncFunc<Args, Returned>
-): func is Amity.MutatorFunc<Args, Returned> => (
-  'optimistically' in func
-)
+  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
@@ -40,58 +36,44 @@ export const isMutator = <Args extends any[], Returned extends any>(
  * @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)
+  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 "syncedAt" property
+ * 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 "syncedAt"
+ * @returns success boolean if the object has property "cachedAt"
  *
  * @hidden
  */
-export const isSyncable = (model: any): model is Amity.Syncable => (
-  model?.hasOwnProperty('syncedAt')
-)
+export const isCachable = (model: any): model is Amity.Cachable =>
+  model?.hasOwnProperty('cachedAt');
 
 /**
- * Checks if a model is considered local (syncedAt === -1)
+ * Checks if a model is considered local (cachedAt === -1)
  *
- * @param model any syncable object to check
+ * @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.Syncable => {
-  return isSyncable(model) && model?.syncedAt === -1
-}
+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 syncable object to check
+ * @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.Syncable, lifeSpan: number = 0) => {
-  return Date.now() - (model?.syncedAt ?? 0) <= lifeSpan
-}
-
-/**
- * Checks if a model is considered synced
- *
- * @param model any syncable object to check
- * @param lifeSpan the supposedly duration for which the object is considered synced
- * @returns success boolean if the object is local or below the given lifespan
- *
- * @hidden
- */
-export const isSynced = (model?: any, lifeSpan: number = 0) => {
-  return isLocal(model) || isFresh(model, lifeSpan)
-}
+export const isFresh = (model?: Amity.Cachable, lifeSpan = CACHE_LIFESPAN) => {
+  return Date.now() - (model?.cachedAt ?? 0) <= lifeSpan;
+};
 
 /**
  * ```js
@@ -103,7 +85,7 @@ export const isSynced = (model?: any, lifeSpan: number = 0) => {
  * This wrapper is necessary to create for optimistically calls
  *
  *
- * @param fn A compatible API function from the ts sdk
+ * @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
  *
@@ -112,8 +94,7 @@ export const isSynced = (model?: any, lifeSpan: number = 0) => {
 export const createQuery = <Args extends any[], Returned extends any>(
   func: Amity.AsyncFunc<Args, Returned> | Amity.OfflineFunc<Args, Returned>,
   ...args: Args
-) => ({ func, args })
-
+) => ({ func, args });
 
 /**
  * ```js
@@ -129,15 +110,13 @@ export const createQuery = <Args extends any[], Returned extends any>(
  * @category Query
  */
 export const queryOptions = (
-  policy: Amity.QueryPolicy, lifeSpan: number = 2 * 60 * 1000, // 2mn
+  policy: Amity.QueryPolicy,
+  lifeSpan: number = CACHE_LIFESPAN, // 1mn
 ): Amity.QueryOptions => {
-  if (policy === 'cache_only')
-    return { lifeSpan: Infinity }
-  else if (policy === 'server_only')
-    return { lifeSpan: 0 }
+  if (policy === 'cache_only') return { lifeSpan: Infinity };
 
-  return { lifeSpan }
-}
+  return { lifeSpan: lifeSpan < CACHE_LIFESPAN ? CACHE_LIFESPAN : lifeSpan };
+};
 
 /**
  * Checks if an unknown shaped payload is considered empty or not.
@@ -149,61 +128,20 @@ export const queryOptions = (
  *
  * @hidden
  */
-const isEmpty = (local: any) => {
+const isEmpty = (local: unknown) => {
   // if it's supposed to be a single object, it'd be undefined
-  if (!local)
-    return true
+  if (!local) return true;
 
   // it's a paged query, the 1st cell of the array would be empty
-  else if (isPaged(local) && isEmpty(local.data)) {
-    return true
+  if (isPaged(local) && isEmpty(local.data)) {
+    return true;
   }
 
   // if it's a item collection, it'd have no keys
-  else if (!Object.keys(local).length)
-    return true
+  if (typeof local === 'object' && !Object.keys(local).length) return true;
 
-  return false
-}
-
-/**
- * Checks if an unknown shaped payload is considered synced or not.
- * The object will first be identified by 3 types of shapes:
- *
- * 1. Amity.Paged<Amity.Syncable>
- * 2. Amity.Syncable
- * 3. Record<string, Amity.Syncable>
- *
- * then the "Syncable" component will be extracted and evaluated against
- * the query options' lifeSpan value.
- *
- * @param local the unknown object to check for freshness
- * @param options query options (for lifeSpan checking)
- * @returns true if the mixed-shape "local" content is considered fresh
- *
- * @hidden
- */
-const shouldAbort = (local: any, options: Amity.QueryOptions) => {
-  // it's a paged query
-  if (isPaged(local) && shouldAbort(local.data, options)) {
-    return true
-  }
-
-  // if it's object let's try to see if it's Amity.Syncable first
-  else if (isSynced(local, options.lifeSpan)) {
-    return true
-  }
-
-  // otherwise consider as Record<string, Amity.Syncable>
-  else if (
-    Object.values(local).length > 0 &&
-    Object.values(local).every(item => isSynced(item, options.lifeSpan))
-  ) {
-    return true
-  }
-
-  return false
-}
+  return false;
+};
 
 /**
  * ```js
@@ -224,77 +162,89 @@ const shouldAbort = (local: any, options: Amity.QueryOptions) => {
  */
 export const runQuery = <Args extends any[], Returned extends any>(
   { func, args }: Amity.Query<Args, Returned>,
-  callback?: (args: Amity.QueryResult<Returned | undefined>) => void,
-  options: Amity.QueryOptions = queryOptions('cache_then_server')
+  callback?: (args: Amity.Snapshot<Returned>) => void,
+  options: Amity.QueryOptions = queryOptions('cache_then_server'),
 ) => {
-  if (!isOffline(func) || options.lifeSpan === 0) {
-    callback?.(wrap(undefined, {
-      origin: 'server',
-      loading: true
-    }))
-
-    func(...args)
-      .then(fresh => {
-        callback?.(wrap(fresh, {
-          origin: 'server',
+  console.warn(
+    'Deprecation Notice: After 1 April 2023, CreateQuery/RunQuery will no longer be supported. You will be able to use the API without either methods. Check https://docs.amity.co/ for details',
+  );
+  console.warn(
+    'Deprecation Notice: After 1 March 2023, individual module imoprts will no longer be supported. All public APIs will need to be imported from their respective repositories. Ex: CommunityRepository, UserRepository, etc. Check https://docs.amity.co/ for detailed info.',
+  );
+
+  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,
-        }))
-      })
-      .catch(error => {
-        callback?.(wrap(undefined, {
           error,
-          loading: false,
-        }))
-      })
-
-    return
-  }
-
-  const local = isMutator(func)
-    ? func.optimistically(...args)
-    : func.locally(...args)
-
-  if (!isEmpty(local)) {
-    callback?.(wrap(local, { origin: 'local' }))
+        }),
+      );
+    }
+
+    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,
+      }),
+    );
   }
 
-  if (local && isFetcher(func) && shouldAbort(local, options)) return
-
-  callback?.(wrap(local, {
-    origin: 'local',
-    loading: true,
-  }))
-
   func(...args)
     .then(fresh => {
       // @ts-ignore i know.
-      isLocal(local) && syncInCache(local, fresh)
+      // isLocal(local) && syncInCache(local, fresh)
 
-      callback?.(wrap(fresh, {
-        origin: 'server',
-        loading: false
-      }))
+      callback?.(
+        createSnapshot<Returned>(fresh, {
+          origin: 'server',
+          loading: false,
+        }),
+      );
     })
     .catch(error => {
-      callback?.(wrap(local, {
-        error,
-        loading: false,
-      }))
-    })
-}
+      callback?.(
+        createSnapshot<Returned>(undefined, {
+          origin: 'server',
+          loading: false,
+          error,
+        }),
+      );
+    });
+};
 
 /**
+ * This is a TS hack around types
  *
  * @param data
- * @param meta
- * @returns
+ * @param options
+ *
+ * @category Query API
+ * @hidden
  */
-const wrap = <T extends any>(data: T, meta: Amity.QueryMetadata = {}) => {
-  if (isPaged(data))
-    return {
-      ...meta,
-      ...data as Amity.Paged<T>,
-    } as Amity.QueryResult<T>
+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 { ...meta, data } as Amity.QueryResult<T>
+  return { ...options, data };
 }

package/src/core/query/sorting.ts

@@ -2,49 +2,63 @@
 // this file should contain a suite of sorting utilities to help the
 // local version of the query functions.
 
-type SortingFunc<T = Object> = (a: T, b: T) => number
+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 }
+  { displayName: a },
+  { displayName: b },
 ) => {
-  if (a === b) return 0
-  return a < b ? -1 : 1
-}
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+};
+
+/**
+ * Alphabetic sorting of objects having a name
+ */
+export const sortByName: SortingFunc<{ name: string }> = ({ name: a }, { name: b }) => {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+};
 
 /**
  * Sorting a collection by their apparition order (oldest first)
  */
 export const sortByChannelSegment: SortingFunc<{ channelSegment: number }> = (
-  { channelSegment: a }, { channelSegment: b }
-) => a - b
+  { 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
+  { 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()
+  { createdAt: a },
+  { createdAt: b },
+) => new Date(a).valueOf() - new Date(b).valueOf();
 
 /**
  * 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()
+  { createdAt: a },
+  { createdAt: b },
+) => 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()
+  { lastActivity: a },
+  { lastActivity: b },
+) => new Date(b).valueOf() - new Date(a).valueOf();