@amityco/ts-sdk 0.0.1-beta.1 → 0.0.1-beta.13

package/src/core/query/paging.ts

@@ -0,0 +1,206 @@
+// @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 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: Object): json is Amity.AfterBeforeRawPagination => (
+  ['after', 'before'].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 object shaped as { data: T[] } & Amity.Pages
+ *
+ * @hidden
+ */
+export const isPaged = <T extends unknown>(payload: any): payload is Amity.Paged<T> => {
+  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' | 'afterbeforeraw',
+
+): 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,
+      }
+    } else if (!isNaN(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
+
+  // 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
+}
+
+/**
+ * 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 | null => {
+  if (!token) return null
+
+  // don't try catch, let it throw
+  const json = JSON.parse(decode(token))
+
+  if (isAfterBeforeRaw(json)) {
+    return json as Amity.PageRaw
+  }
+
+  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,248 @@
+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: number = 0) => {
+  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 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
+}
+
+/**
+ * ```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 | undefined>) => void,
+  options: Amity.QueryOptions = queryOptions('cache_then_server')
+) => {
+  let local: Returned | undefined
+
+  // offline first
+  if (isOffline(func) && options.lifeSpan !== 0) {
+    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, options.lifeSpan)
+
+    callback?.(createSnapshot(local , {
+      origin: 'local',
+      loading: !(isFetcher(func) && shouldAbort)
+    }))
+
+    if (shouldAbort)
+      return
+  } else {
+    callback?.(createSnapshot(undefined, {
+      origin: 'local',
+      loading: true
+    }))
+  }
+
+  func(...args)
+    .then(fresh => {
+      // @ts-ignore i know.
+//      isLocal(local) && syncInCache(local, fresh)
+
+      callback?.(
+        createSnapshot(fresh, {
+          origin: 'server',
+          loading: false,
+        })
+      )
+    })
+    .catch(error => {
+      callback?.(
+        createSnapshot(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>;
+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,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/subscription.ts

@@ -0,0 +1,75 @@
+import { getActiveClient } from '~/client/api'
+import { ASCError } from '~/core/errors'
+import { proxyMqttEvents } from '~/core/events'
+
+export enum SubscriptionLevels {
+  COMMUNITY = 'community',
+  POST = 'post',
+  COMMENT = 'comment',
+  POST_AND_COMMENT = 'post_and_comment',
+  USER = 'user',
+}
+
+const getCommunityUserTopic = (
+  { path }: Amity.Subscribable,
+  level?: SubscriptionLevels,
+): string => {
+  switch (level) {
+    case 'post':
+      return `${path}/post/+`;
+    case 'comment':
+      return `${path}/post/+/comment/+`;
+    case 'post_and_comment':
+      return `${path}/post/#`;
+    default:
+      return path;
+  }
+};
+
+export const getCommunityTopic = (
+  { path }: Amity.Subscribable,
+  level: Exclude<SubscriptionLevels, SubscriptionLevels.USER> = SubscriptionLevels.COMMUNITY,
+): string =>
+  getCommunityUserTopic({ path }, level)
+
+export const getUserTopic = (
+  { path }: Amity.Subscribable,
+  level: Exclude<SubscriptionLevels, SubscriptionLevels.COMMUNITY> = SubscriptionLevels.USER,
+): string =>
+  getCommunityUserTopic({ path }, level)
+
+export const getPostTopic = (
+  { path }: Amity.Subscribable,
+  level: SubscriptionLevels.POST | SubscriptionLevels.COMMENT = SubscriptionLevels.POST
+): string => {
+  switch (level) {
+    case 'comment':
+      return `${path}/comment/+`;
+    default:
+      return path;
+  }
+};
+
+export const getCommentTopic = ({ path }: Amity.Subscribable): string => {
+  return path;
+};
+
+let mqttAccessToken: string;
+let mqttUserId: string;
+
+export function subscribeTopic(
+  topic: string,
+  callback?: Amity.Listener<ASCError | void>
+): Amity.Unsubscriber {
+  const { mqtt, emitter, accessToken, _internalUserId } = getActiveClient()
+
+  if (mqttAccessToken !== accessToken || mqttUserId !== _internalUserId) {
+    mqttAccessToken = accessToken!
+    mqttUserId = _internalUserId!
+
+    mqtt.connect({ accessToken: mqttAccessToken, userId: mqttUserId })
+    proxyMqttEvents(mqtt, emitter)
+  }
+
+  return mqtt.subscribe(topic, callback)
+}

package/src/core/transports/http.ts

@@ -0,0 +1,63 @@
+import axios from 'axios'
+import HttpAgent, { HttpsAgent } from 'agentkeepalive'
+
+import { unwrapPayload } from './utils'
+
+/**
+ * Axios param serializer (for querystring)
+ * @hidden
+ */
+const stringify = (params: object, prefix?: string): string => {
+  return Object.entries(params)
+    .filter(([, value]) => value !== undefined)
+    .map(([name, value]) => {
+      const key = prefix ? `${prefix}[${name}]` : name
+
+      if (Array.isArray(value)) {
+        return value.map(item => `${key}[]=${item}`).join('&')
+      } else if (typeof value !== 'object') {
+        return `${key}=${value}`
+      }
+
+      return stringify(value, prefix ?? name)
+    })
+    .join('&')
+}
+
+/**
+ * Creates a pre-configured axios instance
+ *
+ * @param endpoint The ASC rest api server's URL
+ * @returns A pre-configured axios instance
+ *
+ * @category Transport
+ * @hidden
+ */
+export const createHttpTransport = (endpoint: string) => {
+  const options = {
+    maxSockets: 100,
+    maxFreeSockets: 10,
+    timeout: 60000,
+    freeSocketTimeout: 30000,
+  }
+
+  const instance = axios.create({
+    baseURL: endpoint,
+    httpAgent: new HttpAgent(options),
+    httpsAgent: new HttpsAgent(options),
+    paramsSerializer: stringify,
+  })
+
+  instance.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      const { response } = error
+      console.error(response?.data ?? error)
+
+      if (response)
+        unwrapPayload(response.data)
+    }
+  )
+
+  return instance
+}

package/src/core/transports/index.ts

@@ -0,0 +1,3 @@
+export * from './http';
+export * from './ws';
+export * from './mqtt';