@amityco/ts-sdk 0.0.1-beta.2 → 0.0.1-beta.22

package/src/core/query/paging.ts

@@ -0,0 +1,166 @@
+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: Record<string, unknown>): 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: 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> => {
+  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 (!Number.isNaN(Number(paging?.before!))) {
+      payload = {
+        before: paging.before,
+        last: paging.limit,
+      };
+    } 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;
+
+  // 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 (isSkipLimit(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,242 @@
+/* eslint-disable no-use-before-define */
+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 = 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 };
+  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
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  if (isPaged(local) && isEmpty(local.data)) {
+    return true;
+  }
+
+  // if it's a item collection, it'd have no keys
+  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>) => 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<Returned>(local, {
+        origin: 'local',
+        loading: !(isFetcher(func) && shouldAbort),
+      }),
+    );
+
+    if (shouldAbort) return;
+  } else {
+    callback?.(
+      createSnapshot<Returned>(undefined, {
+        origin: 'local',
+        loading: true,
+      }),
+    );
+  }
+
+  func(...args)
+    .then(fresh => {
+      // @ts-ignore i know.
+      // isLocal(local) && syncInCache(local, 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,56 @@
+// 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 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,104 @@
+import { getActiveClient } from '~/client/api/activeClient';
+import { ASCError } from '~/core/errors';
+import { proxyMqttEvents } from '~/core/events';
+import { getActiveUser } from '~/client/api/activeUser';
+
+export enum SubscriptionLevels {
+  COMMUNITY = 'community',
+  POST = 'post',
+  COMMENT = 'comment',
+  POST_AND_COMMENT = 'post_and_comment',
+  USER = 'user',
+}
+
+const getCommunityUserTopic = (
+  path: Amity.Subscribable['path'],
+  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(
+    level === SubscriptionLevels.USER ? path : path.replace(/^(\w*)/, '$1/social'),
+    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;
+};
+
+export const getMyFollowersTopic = (): string => {
+  const user = getActiveUser();
+
+  const [networkId] = user.path.split('/user/');
+
+  return `${networkId}/membership/${user._id}/+/+`;
+};
+
+export const getMyFollowingsTopic = (): string => {
+  const user = getActiveUser();
+
+  const [networkId] = user.path.split('/user/');
+
+  return `${networkId}/membership/+/${user._id}/+`;
+};
+
+/** @hidden */
+export const getNetworkTopic = (): string => {
+  const user = getActiveUser();
+
+  const [networkId] = user.path.split('/user/');
+
+  return networkId;
+};
+
+let mqttAccessToken: string;
+let mqttUserId: string;
+
+export function subscribeTopic(
+  topic: string,
+  callback?: Amity.Listener<ASCError | void>,
+): Amity.Unsubscriber {
+  const { mqtt, emitter, accessToken } = getActiveClient();
+  const user = getActiveUser();
+
+  if (mqttAccessToken !== accessToken || mqttUserId !== user._id) {
+    mqttAccessToken = accessToken!;
+    mqttUserId = user._id!;
+
+    mqtt.connect({ accessToken: mqttAccessToken, userId: mqttUserId });
+    proxyMqttEvents(mqtt, emitter);
+  }
+
+  return mqtt.subscribe(topic, callback);
+}

package/src/core/transports/http.ts

@@ -0,0 +1,65 @@
+import axios from 'axios';
+import HttpAgent, { HttpsAgent } from 'agentkeepalive';
+
+import { unwrapPayload } from './utils';
+
+/**
+ * Axios param serializer (for querystring)
+ * @hidden
+ */
+const stringify = (params: Record<string, unknown>, 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('&');
+      }
+      if (typeof value !== 'object') {
+        return `${key}=${value}`;
+      }
+
+      // @ts-ignore
+      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;
+      // eslint-disable-next-line no-console
+      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';