@amityco/ts-sdk 0.0.1-beta.3 → 0.0.1-beta.31

package/src/cache/api/index.ts

@@ -0,0 +1,24 @@
+// on/off
+export * from './enableCache';
+export * from './disableCache';
+
+// persistency
+export * from './restoreCache';
+export * from './backupCache';
+export * from './wipeCache';
+
+// fetch
+export * from './queryCache';
+export * from './pullFromCache';
+
+// mutate
+export * from './pushToCache';
+export * from './mergeInCache';
+export * from './upsertInCache';
+export * from './dropFromCache';
+
+/*
+ * ingestInCache and syncInCache and isInTombstone
+ * and pushToTombstone are not exported ;
+ * we don't want it as part of the sdk's public api.
+ */

package/src/cache/api/ingestInCache.ts

@@ -0,0 +1,32 @@
+import { PAYLOAD2MODEL, getResolver } from '~/core/model';
+
+import { upsertInCache } from './upsertInCache';
+
+/**
+ * Ingest a payload (v3) into the cache
+ *
+ * @param payload a "backend v3" payload object
+ * @param order the order of the keys to process (in case of need)
+ *
+ * @category Cache
+ * @hidden
+ */
+export const ingestInCache = (
+  payload: Record<string, Record<string, unknown>[]> = {},
+  options?: Amity.CacheOptions,
+) => {
+  Object.entries(payload).forEach(([key, models]) => {
+    const type = PAYLOAD2MODEL[key];
+    if (!type) return;
+
+    const resolver = getResolver(type);
+    models.forEach(model => {
+      upsertInCache(
+        // eslint-disable @typescript-eslint no-explicit-any
+        [type, 'get', resolver(model as any)], // this 'any' cannot be avoided, sorry.
+        model,
+        options,
+      );
+    });
+  });
+};

package/src/cache/api/isInTombstone.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { ASCApiError } from '~/core/errors';
+import { pullFromCache } from '~/cache/api';
+import { isFresh, queryOptions } from '~/core/query';
+import { CACHE_KEY_TOMBSTONE, CACHE_LIFESPAN_TOMBSTONE } from '~/cache/utils';
+
+/**
+ * ```js
+ * import { isInTombstone } from '@amityco/ts-sdk'
+ * const user = isInTombstone(["message", "messageId"])
+ * ```
+ *
+ * Checks if the {@link Amity.TombstoneCacheOptions} exists
+ * in cache and it's not expired means it's in tombstone
+ * and we throw an Error
+ *
+ * @param model the model to check
+ * @param modelId the object id to check
+ * @returns the matching cache entry, or undefined.
+ *
+ * @category Cache API
+ */
+export const isInTombstone = (model: Amity.Domain, modelId: string) => {
+  const { log, cache } = getActiveClient();
+  const key = [model, CACHE_KEY_TOMBSTONE, modelId];
+
+  if (!cache) return;
+  log('cache/api/isInTombstone', key);
+
+  const isInTombstone = pullFromCache<Amity.TombstoneCacheOptions>(key);
+  const { lifeSpan } = queryOptions('cache_then_server', CACHE_LIFESPAN_TOMBSTONE);
+
+  if (isInTombstone && isFresh(isInTombstone.data, lifeSpan)) {
+    throw new ASCApiError(
+      'Item not found!',
+      Amity.ServerError.ITEM_NOT_FOUND,
+      Amity.ErrorLevel.ERROR,
+    );
+  }
+};

package/src/cache/api/mergeInCache.ts

@@ -0,0 +1,43 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { pullFromCache } from './pullFromCache';
+import { pushToCache } from './pushToCache';
+
+/**
+ * ```js
+ * import { mergeInCache } from '@amityco/ts-sdk'
+ *
+ * mergeInCache(
+ *   ["foo", "bar"],
+ *   (oldVal) => ({ ...oldVal, ...newVal }).
+ * )
+ * ```
+ *
+ * Merges a new {@link Amity.Cache} object to an {@link Amity.Client} instance
+ *
+ * @param key the key matching the object to retrieve from cache
+ * @param mutation either a plain object to shallow merge, or a function.
+ * @returns a success boolean if the object was updated
+ *
+ * @category Cache API
+ */
+export const mergeInCache = <T extends Record<string, unknown>>(
+  key: Amity.CacheKey,
+  mutation: Partial<T> | ((oldVal: T) => T),
+  options?: Amity.CacheOptions,
+): boolean => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/mergeInCache', { key, mutation });
+
+  const oldVal = pullFromCache<T>(key);
+
+  if (!oldVal) return false;
+
+  const newVal =
+    typeof mutation === 'function' ? mutation(oldVal.data) : { ...oldVal.data, ...mutation };
+
+  pushToCache(key, newVal, options);
+  return true;
+};

package/src/cache/api/pullFromCache.ts

@@ -0,0 +1,31 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { encodeKey } from '../utils';
+
+/**
+ * ```js
+ * import { pullFromCache } from '@amityco/ts-sdk'
+ * const user = pullFromCache<Amity.User>(["user", "foobar"])
+ * ```
+ *
+ * Retrieves a {@link Amity.CacheEntry} object matching a given
+ * {@link Amity.CacheKey}. The cache entry is not typed, so the
+ * expected returned type must be passed manually.
+ *
+ * @param key the key matching the object to retrieve from cache
+ * @returns the matching cache entry, or undefined.
+ *
+ * @category Cache API
+ */
+export const pullFromCache = <T extends unknown>(
+  key: Amity.CacheKey,
+): Amity.CacheEntry<T> | undefined => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return;
+  log('cache/api/pullFromCache', key);
+
+  const str = encodeKey(key);
+
+  return cache.data[str] ? (cache.data[str] as Amity.CacheEntry<T>) : undefined;
+};

package/src/cache/api/pushToCache.ts

@@ -0,0 +1,42 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { encodeKey } from '../utils';
+
+/**
+ * ```js
+ * import { pushToCache } from '@amityco/ts-sdk'
+ * pushToCache<Amity.User>(["user", "foobar"], user)
+ * ```
+ *
+ * Saves any provided value as {@link Amity.CacheEntry} for the matching {@link Amity.CacheKey}
+ *
+ * @param key the key to save the object to
+ * @param data the object to save
+ * @param options customisation object around cache behavior (default gives a 2mn lifespan)
+ * @returns a success boolean if the object was saved in cache
+ *
+ * @category Cache API
+ */
+export const pushToCache = (
+  key: Amity.CacheKey,
+  data: unknown,
+  options: Amity.CacheOptions = { cachedAt: Date.now() },
+): boolean => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/pushToCache', { key, data, options });
+
+  // if consumer did not pass offline but a offline policy is
+  // defined, use the fn to determine if the object needs to
+  // be saved in persistent storage or not.
+  if (!options?.hasOwnProperty('offline') && cache.persistIf) {
+    // eslint-disable-next-line no-param-reassign
+    options.offline = cache.persistIf(key, data);
+  }
+
+  const encodedKey = encodeKey(key);
+  cache.data[encodedKey] = { key, data, ...options };
+
+  return true;
+};

package/src/cache/api/pushToTombstone.ts

@@ -0,0 +1,33 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { dropFromCache, pushToCache } from '~/cache/api';
+
+import { CACHE_KEY_GET, CACHE_KEY_TOMBSTONE } from '~/cache/utils';
+
+/**
+ * ```js
+ * import { pushToTombstone } from '@amityco/ts-sdk'
+ * pushToTombstone(["message", "messageId"], { cachedAt: Date.now() })
+ * ```
+ *
+ * Removes an existing {@link Amity.CacheEntry} from the {@link Amity.Client}'s
+ * {@link Amity.Cache} from a given {@link Amity.CacheKey}
+ *
+ * @param model the model to remove and push to Tombstone
+ * @param modelId the related model id
+ *
+ * @category Cache API
+ * @hidden
+ */
+export const pushToTombstone = (model: Amity.Domain, modelId: string) => {
+  const { log, cache } = getActiveClient();
+
+  const cacheKey = [model, CACHE_KEY_TOMBSTONE, modelId];
+  const data: Pick<Amity.CacheOptions, 'cachedAt'> = { cachedAt: Date.now() };
+
+  if (!cache) return;
+  log('cache/api/pushToTombstone', { cacheKey, data });
+
+  dropFromCache([model, CACHE_KEY_GET, modelId], true);
+  pushToCache(cacheKey, data);
+};

package/src/cache/api/queryCache.ts

@@ -0,0 +1,34 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { decodeKey, partialMatch } from '../utils';
+
+/**
+ * ```js
+ * import { queryCache } from '@amityco/ts-sdk'
+ * const entries = queryCache(["user"])
+ * ```
+ *
+ * Retrieves a list of {@link Amity.CacheEntry} objects matching a
+ * partial {@link Amity.CacheKey}. The cache entries can't be typed,
+ * but the expected returned type can be passed manually.
+ *
+ * @param partialKey the partial key matching the objects to retrieve from cache
+ * @returns the matching cache entries, or empty array.
+ *
+ * @category Cache API
+ */
+export const queryCache = <T extends unknown>(
+  key: Amity.CacheKey,
+): Amity.CacheEntry<T>[] | undefined => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return;
+  log('cache/api/queryCache', { key });
+
+  return Object.keys(cache.data)
+    .filter(stringKey => {
+      const decodedKey = decodeKey(stringKey);
+      return partialMatch(key, decodedKey);
+    })
+    .map(stringKey => cache.data[stringKey]) as Amity.CacheEntry<T>[];
+};

package/src/cache/api/restoreCache.ts

@@ -0,0 +1,44 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+import { getActiveClient } from '~/client/api/activeClient';
+
+/**
+ * ```js
+ * import { restoreCache } from '@amityco/ts-sdk'
+ * const success = await restoreCache()
+ * ```
+ *
+ * Reads a previously saved {@link Amity.Cache} from a persistent storage,
+ * and inserts it into the current {@link Amity.Cache} instance.
+ *
+ * The strategy for persistent storage will depend on the runtime,
+ * which is supported by @react-native-async-storage/async-storage.
+ *
+ * The current userId will be appended to the given storageKey to ensures
+ * the cached data concerns only the current user.
+ *
+ * @param storageKey the name of the persistent storage
+ * @returns a success boolean if the cache was dumped to persistent storage
+ *
+ * @category Cache API
+ */
+export const restoreCache = async (storageKey = 'amitySdk') => {
+  const client = getActiveClient();
+
+  if (!client.cache) return false;
+  client.log('cache/api/restoreCache', { storageKey });
+
+  const serializedData = (await AsyncStorage.getItem(`${storageKey}#${client.userId}`)) ?? '{}';
+
+  let cache: Amity.Cache['data'] = {};
+
+  try {
+    cache = JSON.parse(serializedData);
+  } catch (err) {
+    //
+  }
+
+  // current cache should override. in case there's something fresher.
+  client.cache.data = { ...cache, ...client.cache.data };
+  return true;
+};

package/src/cache/api/snipeIdFromCollection.ts

@@ -0,0 +1,48 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { queryCache, mergeInCache, dropFromCache } from '.';
+
+/**
+ * ```js
+ * import { snipeFromCollection } from '@amityco/ts-sdk'
+ * const user = snipeFromCollection("user", "foobar")
+ * ```
+ *
+ * Removes a {@link Amity.Model} object from  matching a given
+ * {@link Amity.CacheKey}. The cache entry is not typed, so the
+ * expected returned type must be passed manually.
+ *
+ * @param domain the key matching the object to retrieve from cache
+ * @param id the key matching the object to retrieve from cache
+ * @returns a success boolean if the id was removed from all matching collections
+ *
+ * @category Cache API
+ */
+export const snipeIdFromCollections = (domain: Amity.Domain, id: string) => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/snipeFromCollections', { domain, id });
+
+  const entries = (queryCache<unknown[]>([domain, 'query']) ?? []).filter(entry =>
+    entry?.data.includes(id),
+  );
+
+  if (!entries.length) return false;
+
+  const toBeDeleted: Amity.CacheKey[] = [];
+
+  entries.forEach(({ key }) => {
+    // @ts-ignore
+    mergeInCache<unknown[]>(key, oldVal => {
+      const newVal = oldVal.filter(itemId => itemId !== id);
+
+      if (!newVal.length) toBeDeleted.push(key);
+
+      return newVal;
+    });
+  });
+
+  toBeDeleted.forEach(key => dropFromCache(key, true));
+  return true;
+};

package/src/cache/api/upsertInCache.ts

@@ -0,0 +1,37 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { pullFromCache } from './pullFromCache';
+import { pushToCache } from './pushToCache';
+import { mergeInCache } from './mergeInCache';
+
+/**
+ * ```js
+ * import { upsertInCache } from '@amityco/ts-sdk'
+ * upsertInCache<Amity.User>(["user", "foobar"], user)
+ * ```
+ *
+ * Insert or update any provided value as {@link Amity.CacheEntry} for
+ * the matching {@link Amity.CacheKey}
+ *
+ * @param key the key to save the object to
+ * @param data the object to save
+ * @param options customisation object around cache behavior (default gives a 2mn lifespan)
+ * @returns a success boolean if the object was saved in cache
+ *
+ * @category Cache API
+ * @hidden
+ */
+export const upsertInCache = <T extends Record<string, unknown>>(
+  key: Amity.CacheKey,
+  data: T,
+  options: Amity.CacheOptions = { cachedAt: Date.now() },
+): boolean => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/upsertInCache', { key, data, options });
+
+  const cached = pullFromCache<T>(key);
+
+  return cached ? mergeInCache<T>(key, data, options) : pushToCache(key, data, options);
+};

package/src/cache/api/wipeCache.ts

@@ -0,0 +1,34 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+import { getActiveClient } from '~/client/api/activeClient';
+
+/**
+ * ```js
+ * import { wipeCache } from '@amityco/ts-sdk'
+ * const success = await wipeCache()
+ * ```
+ *
+ * Wipes a persistent storage for the current {@link Amity.Cache} instance.
+ *
+ * The strategy for persistent storage will depend on the runtime,
+ * which is supported by @react-native-async-storage/async-storage.
+ *
+ * The current userId will be appended to the given storageKey to avoid
+ * collision between multiple client instances over time.
+ *
+ * @param storageKey the name of the persistent storage
+ * @returns a success boolean if the persistent cache was wiped.
+ *
+ * @category Cache API
+ */
+export const wipeCache = async (storageKey = 'amitySdk') => {
+  const { log, cache, userId } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/wipeCache', { storageKey });
+
+  cache.data = {};
+  await AsyncStorage.setItem(`${storageKey}#${userId}`, '{}');
+
+  return true;
+};

package/src/cache/utils/index.ts

@@ -0,0 +1,96 @@
+// cache constants
+export const CACHE_KEY_GET = 'get';
+export const CACHE_KEY_QUERY = 'query';
+export const CACHE_KEY_TOMBSTONE = 'dead';
+export const CACHE_KEY_COLLECTION = 'collection';
+
+export const CACHE_LIFESPAN = 1 * 60 * 1000; // 1 minute
+export const CACHE_LIFESPAN_TOMBSTONE = 3 * 60 * 1000; // 3 minutes
+
+/**
+ * Shallow-clones an object and sort its keys
+ *
+ * @param source a plain object to clone
+ * @returns a clone of source, with keys sorted with default javascript sorting
+ *
+ * @category Cache
+ * @hidden
+ */
+const normalize = (
+  source: Record<string, Amity.Serializable>,
+): Record<string, Amity.Serializable> =>
+  Object.keys(source)
+    .sort()
+    .reduce((acc, key) => ({ ...acc, [key]: source[key] }), {});
+
+/**
+ * Encodes a given {@link Amity.CacheKey} to a plain string
+ *
+ * @param key the key to encode
+ * @returns an encoded string
+ *
+ * @category Cache
+ * @hidden
+ */
+export const encodeKey = (key: Amity.CacheKey): string =>
+  JSON.stringify(key, (_, val) => (typeof val === 'object' ? normalize(val) : val));
+
+/**
+ * Decodes a string back into a {@link Amity.CacheKey}
+
+ *
+ * @param key the string key to decode
+ * @returns a plain Amity.CacheKey object.
+ *
+ * @category Cache
+ * @hidden
+ */
+export const decodeKey = (key: string): Amity.CacheKey => JSON.parse(key);
+
+/**
+ * Performs a recursive partial deep equal check on two objects.
+ *
+ * @param predicate the reference object containing the partial information
+ * @param candidate the object to check against
+ * @returns true if the candidate contains all the values of the predicate
+ *
+ * @category Cache
+ */
+export const partialMatch = (predicate: any, candidate: any): boolean => {
+  if (predicate === candidate) return true;
+
+  // if one or the other is nullish, there can't be equality
+  if (!predicate || !candidate) return false;
+
+  // we only perform recursive check on objects
+  if (typeof predicate !== 'object') {
+    return false;
+  }
+
+  // recursively call for partial match based on the predicate
+  return Object.keys(predicate).every(key => partialMatch(predicate[key], candidate[key]));
+};
+
+/**
+ * Type guard to check and cast that a given predicate matched {@link Amity.Cached} shape
+ *
+ * @param obj any {@link Amity.Cached}-like object
+ * @returns success boolean if the given object is of {@link Amity.Cached} shape
+ *
+ * @category Cache
+ */
+export const isCached = <T extends unknown>(obj?: any): obj is Amity.Cached<T> =>
+  ['data', 'cachedAt'].every(prop => obj?.hasOwnProperty(prop));
+
+/**
+ * checks if passed error code is included in
+ * Tombstone errors list
+ *
+ * @param errorCode as {@link Amity.ServerError}
+ * @returns success boolean if the given errorCode
+ * is included in Tombstone errors list
+ *
+ * @category Cache
+ */
+export const checkIfShouldGoesToTombstone = (errorCode: Amity.ServerError): boolean =>
+  [Amity.ServerError.ITEM_NOT_FOUND, Amity.ServerError.FORBIDDEN].includes(errorCode);

package/src/category/api/getCategory.ts

@@ -1,12 +1,12 @@
-import { getActiveClient } from '~/client/api/activeClient'
+import { getActiveClient } from '~/client/api/activeClient';
 
-import { decoratePayload } from '~/core/query'
-import { ingestInCache } from '~/core/cache'
+import { pullFromCache, dropFromCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
 
 /**
  * ```js
  * import { getCategory } from '@amityco/ts-sdk'
- * const category = await getCategory('foo')
+ * const { data: category } = await getCategory('foo')
  * ```
  *
  * Fetches a {@link Amity.Category} object
@@ -18,18 +18,53 @@ import { ingestInCache } from '~/core/cache'
  * @async
  */
 export const getCategory = async (
-  categoryId: Amity.Category['categoryId']
-) => {
-  const client = getActiveClient()
-  client.log('category/getCategory', categoryId)
+  categoryId: Amity.Category['categoryId'],
+): Promise<Amity.Cached<Amity.Category>> => {
+  const client = getActiveClient();
+  client.log('category/getCategory', categoryId);
 
   const { data } = await client.http.get<Amity.CategoryPayload>(
-    `/api/v3/community-categories/${categoryId}`
-  )
+    `/api/v3/community-categories/${encodeURIComponent(categoryId)}`,
+  );
 
-  decoratePayload(data)
-  ingestInCache(data)
+  const cachedAt = client.cache && Date.now();
+  if (client.cache) ingestInCache(data, { cachedAt });
 
-  const { categories } = data
-  return categories[0]
-}
+  const { categories } = data;
+
+  return {
+    data: categories.find(category => category.categoryId === categoryId)!,
+    cachedAt,
+  };
+};
+
+/**
+ * ```js
+ * import { getCategory } from '@amityco/ts-sdk'
+ * const { data: category } = getCategory.locally('foobar')
+ * ```
+ *
+ * Fetches a {@link Amity.Category} object from cache
+ *
+ * @param categoryId the ID of the {@link Amity.Category} to fetch
+ * @returns the associated {@link Amity.Category} object
+ *
+ * @category Category API
+ */
+getCategory.locally = (
+  categoryId: Amity.Category['categoryId'],
+): Amity.Cached<Amity.Category> | undefined => {
+  const client = getActiveClient();
+  client.log('category/getCategory.locally', categoryId);
+
+  if (!client.cache) return;
+
+  const cached = pullFromCache<Amity.Category>(['category', 'get', categoryId]);
+
+  if (!cached) return;
+
+  return {
+    data: cached.data,
+    cachedAt: cached.cachedAt,
+  };
+};

package/src/category/api/index.ts

@@ -1,2 +1,2 @@
-export * from './queryCategories'
-export * from './getCategory'
+export * from './queryCategories';
+export * from './getCategory';