@amityco/ts-sdk 0.0.1-003998f.0

package/src/core/microtasks.ts

@@ -0,0 +1,28 @@
+/* eslint-disable @typescript-eslint/ban-types */
+let tasks: Function[] = [];
+let timer: NodeJS.Timeout;
+
+/**
+ * Add a function to run just before the next tick
+ *
+ * @param task function to schedule for later execution
+ */
+export const scheduleTask = (task: Function) => {
+  clearTimeout(timer);
+  tasks.push(task);
+
+  timer = setTimeout(() => {
+    tasks.forEach(fn => fn());
+    tasks = [];
+  }, 0);
+};
+
+/**
+ * Cancel the scheduling operation
+ *
+ * @param task function to be removed from later execution
+ */
+export const cancelTask = (task: Function) => {
+  tasks = tasks.filter(fn => fn !== task);
+  if (!tasks.length) clearTimeout(timer);
+};

package/src/core/model/idResolvers.ts

@@ -0,0 +1,41 @@
+/**
+ * Manually computed type which links each key with a function
+ * used to return the object's unique id. The type is computed
+ * to avoid using any and give some typing security at the
+ * resolver's level.
+ */
+type Resolvers<T extends Amity.Domain[] = Amity.Domain[]> = {
+  [K in T[number]]: (model: Amity.Minimal[K]) => string;
+};
+
+/** @hidden */
+const idResolvers: Resolvers = {
+  user: ({ userId }) => userId,
+  file: ({ fileId }) => fileId,
+  role: ({ roleId }) => roleId,
+
+  channel: ({ channelId }) => channelId,
+  channelUsers: ({ channelId, userId }) => `${channelId}#${userId}`,
+  message: ({ messageId }) => messageId,
+
+  community: ({ communityId }) => communityId,
+  category: ({ categoryId }) => categoryId,
+  communityUsers: ({ communityId, userId }) => `${communityId}#${userId}`,
+  post: ({ postId }) => postId,
+  comment: ({ commentId }) => commentId,
+  poll: ({ pollId }) => pollId,
+  reaction: ({ reactionId }) => reactionId,
+
+  stream: ({ streamId }) => streamId,
+
+  follow: ({ from, to }) => `${from}#${to}`,
+  followCount: ({ userId }) => userId,
+};
+
+/**
+ * Retrieve the id resolver matching a domain name
+ *
+ * @param name the domain name for the resolve
+ * @returns an idResolver function for the given domain name
+ */
+export const getResolver = <T extends Amity.Domain>(name: T) => idResolvers[name];

package/src/core/model/identifyModel.ts

@@ -0,0 +1,77 @@
+/**
+ * Manually computed type which links each key with array
+ * of matching keys as values. The type is computed rather
+ * than letting string[] to help identifying mistakes while
+ * adding new models.
+ * @hidden
+ */
+type Criterias<T extends Amity.Domain[] = Amity.Domain[]> = {
+  [K in T[number]]: (keyof Amity.Model[K])[];
+};
+
+/**
+ * Identification criterias
+ *
+ * As key, the name of the identified model ;
+ * As value, the list of properties to consider a given model as of type
+ *
+ * Used as source of truth for {@link identifyModel}
+ *
+ * @hidden
+ */
+const CRITERIAS: Criterias = {
+  file: ['fileId', 'attributes'],
+  user: ['userId', 'avatarFileId'],
+  role: ['roleId'],
+  channel: ['channelId', 'rateLimit'],
+  channelUsers: ['channelId', 'userId', 'membership'],
+  message: ['messageId'],
+  community: ['communityId', 'postSetting'],
+  category: ['categoryId'],
+  communityUsers: ['userId', 'communityId', 'communityMembership'],
+  post: ['postId', 'feedId'],
+  comment: ['commentId', 'referenceId'],
+  poll: ['pollId'],
+  reaction: ['reactionId'],
+  stream: ['streamId'],
+  follow: ['from', 'to'],
+  followCount: ['userId', 'followerCount'],
+};
+
+/** @hidden */
+const hasKeys = (object: Record<string, unknown>, needles: string[]) => {
+  const haystack = Object.keys(object);
+  return needles.every(needle => haystack.includes(needle));
+};
+
+/**
+ * Finds the name of the store for a given unknown model
+ *
+ * @param model one of the {@link Amity.Model} to identify
+ * @returns the name of the corresponding store
+ */
+export const identifyModel = (model: Record<string, unknown>) => {
+  // we cannot avoid "as" in here because Object.entries does not
+  // allow anything else than "string" as key in the iterator type
+  const criterias = Object.entries(CRITERIAS) as [Amity.Domain, string[]][];
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  return criterias.find(([_, keys]) => hasKeys(model, keys))?.[0];
+};
+
+/*
+ * Identify the modal key for a model
+ * Used to get args for optimistic updates
+ * Example: createMessage: get messageId on optimistic message creation
+ *
+ * @param model to be recognized
+ * @returns model key array if one if found or undefined
+ */
+export const identifyModelKey = (model: Record<string, unknown>): string | undefined => {
+  const modalKey = identifyModel(model);
+
+  if (!modalKey) {
+    return undefined;
+  }
+
+  return CRITERIAS[modalKey]?.[0];
+};

package/src/core/model/index.ts

@@ -0,0 +1,29 @@
+export * from './idResolvers';
+export * from './identifyModel';
+
+/**
+ * A map of v3 response keys to a store name.
+ * @hidden
+ */
+export const PAYLOAD2MODEL: Record<string, Amity.Domain> = {
+  users: 'user',
+  files: 'file',
+  roles: 'role',
+
+  channels: 'channel',
+  channelUsers: 'channelUsers',
+  messages: 'message',
+
+  communities: 'community',
+  categories: 'category',
+  communityUsers: 'communityUsers',
+  posts: 'post',
+  postChildren: 'post',
+  comments: 'comment',
+  polls: 'poll',
+  reactions: 'reaction',
+  videoStreamings: 'stream',
+
+  follows: 'follow',
+  followCounts: 'followCount',
+};

package/src/core/query/filtering.ts

@@ -0,0 +1,74 @@
+import { getResolver } from '~/core/model';
+import { pullFromCache } from '~/cache/api';
+// Note:
+// this file should contain a suite of filtering utilities to help the
+// local version of the query functions.
+
+/**
+ * Filter a given collection with strict equality against a param
+ *
+ * @param collection the collection to filter
+ * @param key the key of the collection's items to challenge
+ * @param value the expected value
+ * @returns a filtered collection with items only matching the criteria
+ *
+ * @hidden
+ */
+export const filterByPropEquality = <T = Record<string, unknown>>(
+  collection: T[],
+  key: keyof T,
+  value: any,
+) => (value !== undefined ? collection.filter(item => item[key] === value) : collection);
+
+export const filterByPropInclusion = <T = Record<string, unknown>>(
+  collection: T[],
+  key: keyof T,
+  value: any[] | undefined,
+) => (value !== undefined ? collection.filter(item => value.includes(item[key])) : collection);
+
+/**
+ * Filter a channel collection by membership of the userId
+ *
+ * @param collection the channel collection to filter
+ * @param membership the membership to be filtered by
+ * @param userId user id to be filtered by
+ * @returns a filtered collection with items only matching the criteria
+ *
+ * @hidden
+ */
+export const filterByChannelMembership = (
+  collection: Amity.Channel[],
+  membership: Amity.ChannelLiveCollection['membership'],
+  userId: Amity.Membership<'channel'>['userId'],
+): Amity.Channel[] => {
+  if (membership === 'all') {
+    return collection;
+  }
+
+  return collection.filter(c => {
+    // get resolver for the channel by user
+    const channelUserCacheKey = getResolver('channelUsers')({
+      channelId: c.channelId,
+      userId,
+    });
+
+    const channelUser = pullFromCache<Amity.Membership<'channel'>>([
+      'channelUsers',
+      'get',
+      channelUserCacheKey,
+    ])?.data;
+
+    // if channel user is defined for user, user is a member
+    if (membership === 'member' && channelUser) {
+      return true;
+    }
+
+    // if channel user by user id not found, user is not a member of that
+    // channel
+    if (membership === 'notMember' && !channelUser) {
+      return true;
+    }
+
+    return false;
+  });
+};

package/src/core/query/index.ts

@@ -0,0 +1,4 @@
+export * from './query';
+export * from './filtering';
+export * from './sorting';
+export * from './paging';

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,275 @@
+/* eslint-disable no-use-before-define */
+import { isPaged } from './paging';
+import { identifyModelKey } from '~/core/model';
+
+import { CACHE_LIFESPAN } from '~/cache/utils';
+
+/**
+ * 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,
+      }),
+    );
+  }
+
+  let optimisticArgs = args;
+  /* get args for optimistic method calls
+   *
+   * On optimistic updates, the modal key for the update needs to be passed to
+   * the server so as to avoid duplicate modal creation
+   *
+   * ex: on creating a new message pass the modalKey is messageId, pass this
+   * id onto the server so that a duplicate with seperate messageId is not
+   * created.
+   */
+  if (isMutator(func)) {
+    // @ts-ignore
+    const modelKey = local && local.data && identifyModelKey(local.data);
+    if (modelKey) {
+      /*
+       * modal key is only required for create as update and delete queries pass
+       * the modal key in the param itself
+       * For update & delete the first argument is always an id which is of type
+       * string, whereas for create the first and only argument is the param object
+       *
+       * When creating an AmityObject optimistically we need to pass the modal key
+       * on to the server. ex: for create message modal key will be 'messageId`
+       */
+      if (typeof args[0] !== 'string') {
+        // @ts-ignore
+        optimisticArgs = [{ ...args[0], [modelKey]: local.data[modelKey] }];
+      }
+    }
+  }
+
+  func(...optimisticArgs)
+    .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 };
+}