@amityco/ts-sdk 0.0.1-02f0fa3.0

package/src/core/query/paging.ts

@@ -0,0 +1,166 @@
+// @ts-ignore
+import { encode, decode } from 'js-base64'
+
+/**
+ * Type guard to find if the a given decoded backend token uses "skip/limit" 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)
+)
+
+/**
+ * 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: Object): json is Amity.AfterBeforePagination => (
+  ['after', 'before', 'first', 'last'].some(prop => prop 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]
+ *
+ * @hidden
+ */
+export const isPaged = (payload: any): payload is Amity.Paged<any> => {
+  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 | undefined,
+  style: 'skiplimit' | 'afterbefore',
+
+): 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') {
+    /*
+      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!)) {
+      payload = {
+        before: paging.before,
+        last: paging.limit,
+      }
+    } else if (!isNaN(paging?.after!)) {
+      payload = {
+        after: paging.after,
+        first: paging.limit,
+      }
+    }
+  }
+
+  // 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 | null => {
+  if (!token) return null
+
+  // don't try catch, let it throw
+  const json = JSON.parse(decode(token))
+
+  if (isSkipLimit(json)) {
+    return {
+      after: json.skip,
+      limit: json.limit!,
+    } as Amity.NextPage
+  } else if (isAfterBefore(json)) {
+    if ('before' in json) {
+      return {
+        before: json.before,
+        limit: json.last,
+      } as Amity.PrevPage
+    } else if ('after' in json) {
+      return {
+        after: json.after,
+        limit: json.first,
+      } as Amity.NextPage
+    }
+  }
+
+  return null
+}
+
+/**
+ * Slices a collection according to its paging
+ *
+ * @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
+ *
+ * @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
+  }
+
+  const paged = collection.slice(start, end)
+
+  return paged.length === page.limit ? paged : undefined
+}

package/src/core/query/query.ts

@@ -0,0 +1,300 @@
+import { syncInCache } from '../cache'
+
+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 "syncedAt" property
+ *
+ * @param model any object to check on
+ * @returns success boolean if the object has property "syncedAt"
+ *
+ * @hidden
+ */
+export const isSyncable = (model: any): model is Amity.Syncable => (
+  model?.hasOwnProperty('syncedAt')
+)
+
+/**
+ * Checks if a model is considered local (syncedAt === -1)
+ *
+ * @param model any syncable 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
+}
+
+/**
+ * Checks if a model is considered fresh
+ *
+ * @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 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)
+}
+
+/**
+ * ```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 fn 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 = 2 * 60 * 1000, // 2mn
+): Amity.QueryOptions => {
+  if (policy === 'cache_only')
+    return { lifeSpan: Infinity }
+  else if (policy === 'server_only')
+    return { lifeSpan: 0 }
+
+  return { 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: any) => {
+  // 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
+  else 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
+
+  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
+}
+
+/**
+ * ```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.QueryResult<Returned | undefined>) => 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',
+          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' }))
+  }
+
+  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)
+
+      callback?.(wrap(fresh, {
+        origin: 'server',
+        loading: false
+      }))
+    })
+    .catch(error => {
+      callback?.(wrap(local, {
+        error,
+        loading: false,
+      }))
+    })
+}
+
+/**
+ *
+ * @param data
+ * @param meta
+ * @returns
+ */
+const wrap = <T extends any>(data: T, meta: Amity.QueryMetadata = {}) => {
+  if (isPaged(data))
+    return {
+      ...meta,
+      ...data as Amity.Paged<T>,
+    } as Amity.QueryResult<T>
+
+  return { ...meta, data } as Amity.QueryResult<T>
+}

package/src/core/query/sorting.ts

@@ -0,0 +1,50 @@
+// Note:
+// 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
+
+/**
+ * Alphabetic sorting of objects having a displayName
+ */
+export const sortByDisplayName: SortingFunc<{ displayName: string }> = (
+  { displayName: a }, { displayName: 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
+
+/**
+ * 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 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 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/stores/index.ts

@@ -0,0 +1,2 @@
+export * from './memory'
+export * from './persistent'

package/src/core/stores/memory.ts

@@ -0,0 +1,59 @@
+/**
+ * Minimal store implementation.
+ *
+ * Beware, the state is mutable! it is your responsibility
+ * handle the state's mutations correctly. We do so in
+ * order for users with mutable/observable stacks to be able
+ * to decorate the state with their favorite libraries.
+ *
+ * @param defaultValue the hydration state value of the store
+ * @returns A store instance with an "in memory" storage strategy
+ *
+ * @category Storage
+ * @hidden
+ */
+export const memoryStore = <T extends {}>(
+  defaultValue: Record<string, T> = {},
+) => {
+  const state: Record<string, T> = defaultValue
+
+  /* default read operation is just to return the state */
+  const read: Amity.StateReader<T> = () => state
+
+  /* default write operation is just to mutate the state */
+  const write: Amity.StateWriter<T> = (payload) => {
+    Object.assign(state, payload)
+  }
+
+  /* default write operation is just to mutate the state */
+  const erase: Amity.StateEraser = (...keys) => {
+    if (!keys.length)
+      keys = Object.keys(state)
+
+    keys.forEach(key => delete state[key])
+  }
+
+  return { read, write, erase } as Amity.Store<T>
+}
+
+/**
+ * ```js
+ * import { memoryStores } from '@amityco/core/cache/store/volatile'
+ * const stores = imemoryStores('user', 'file')
+ * ```
+ *
+ * Builds a collection of in memory stores based on the available store names
+ *
+ * @param names collection of store names
+ * @returns a dictionary of { storeName: storeInstance } according to the given names
+ *
+ * @category Storage
+ */
+export const memoryStores = <
+  T extends Amity.Domain[], // https://github.com/microsoft/TypeScript/issues/44155
+>(...names: T) => {
+  return names.reduce((acc, name) => {
+    const store = memoryStore<Amity.Model[typeof name]>()
+    return { ...acc, [name]: store }
+  }, {} as Amity.StoreCollection<T>)
+}

package/src/core/stores/persistent.ts

@@ -0,0 +1,63 @@
+import AsyncStorage from '@react-native-async-storage/async-storage'
+
+import { memoryStore } from './memory'
+
+const DEFAULT_DEBOUNCE_TIME = 250
+
+/**
+ * Persistent store implementation.
+ *
+ * @param persistentKey the name of the store in persistent storage
+ * @param defaultValue the hydration state value of the store
+ * @param debounceTime a delay to avoid spamming the persistent storage while writing,
+ * @returns A store instance with an "persistent" storage strategy
+ *
+ * @category Storage
+ * @hidden
+ */
+export const persistentStore = async <T extends {}>(
+  persistentKey: string,
+  defaultValue: Record<string, T> = {},
+  debounceTime = DEFAULT_DEBOUNCE_TIME,
+) => {
+  let initialValue = defaultValue
+
+  const serializedBackup = await AsyncStorage.getItem(persistentKey)
+
+  if (serializedBackup) {
+    try { initialValue = JSON.parse(serializedBackup) }
+    catch (err) {}
+  }
+
+  // create a store
+  const store = memoryStore<T>(initialValue)
+
+  let timer: number
+  let job: Promise<any> | null = null
+
+  const backup = () => {
+    if (job) {
+      job.then(() => backup())
+      return
+    }
+
+    clearTimeout(timer)
+    setTimeout(async () => {
+      job = Promise.resolve()
+        .then(() => AsyncStorage.setItem(persistentKey, JSON.stringify(store.read())))
+        .then(() => job = null)
+    }, debounceTime)
+  }
+
+  const write: typeof store.write = (payload) => {
+    store.write(payload)
+    backup()
+  }
+
+  const erase: typeof store.erase = (...keys) => {
+    store.erase(...keys)
+    backup()
+  }
+
+  return { read: store.read, write, erase } as Amity.Store<T>
+}