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

package/src/core/cache/ingest.ts

@@ -0,0 +1,24 @@
+import { pushToCache } from './push'
+
+import { storeInterests } from '../model/idResolvers'
+
+/**
+ * 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
+ */
+export const ingestInCache = (
+  payload: Record<string, any[]> = {},
+  order = Object.keys(payload),
+) => {
+  order
+    .forEach(key => {
+      const name = storeInterests[key]
+      if (!name) return
+
+      pushToCache(name, ...payload[key])
+    })
+}

package/src/core/cache/merge.ts

@@ -0,0 +1,19 @@
+import { getResolver } from '../model/idResolvers'
+
+import { mutateCache } from './mutate'
+
+/**
+ * Apply partial mutation to objects in the cache
+ *
+ * @param name The name of the store to query
+ * @param mutation A partial view of the object to update
+ *
+ * @category Cache
+ */
+export const mergeInCache = <T extends Amity.Domain>(
+  name: T,
+  mutation: Amity.Minimal[T] & Partial<Amity.Model[T]>
+) => {
+  const key = getResolver(name)(mutation)
+  mutateCache(name, key, model => ({ ...model, ...mutation }))
+}

package/src/core/cache/mutate.ts

@@ -0,0 +1,25 @@
+import { pullFromCache } from './pull'
+import { pushToCache } from './push'
+
+/**
+ * Apply partial mutation to objects in the cache
+ *
+ * @param name The name of the store to query
+ * @param mutation A partial view of the object to update
+ *
+ * @category Cache
+ */
+export const mutateCache = <T extends Amity.Domain>(
+  name: T,
+  key: string,
+  mutator: (model: Amity.Model[T]) => Amity.Model[T] | undefined
+) => {
+  const [model] = pullFromCache(name, key) ?? []
+
+  if (!model) return
+
+  const mutation = mutator(model)
+  mutation && pushToCache(name, { ...model, ...mutation })
+
+  return mutation
+}

package/src/core/cache/pull.ts

@@ -0,0 +1,31 @@
+import { getActiveClient } from '~/client/api/activeClient'
+
+/**
+ * Pull objects from the cache layer
+ *
+ * @param name The name of the store to query
+ * @param keys A collection of unique keys for the store
+ * @returns The collection of objects matching the keys. Keys which don't match object will be omitted
+ *
+ * @category Cache
+ */
+export const pullFromCache = <K extends Amity.Domain>(name: K, ...keys: string[]) => {
+  const { cache } = getActiveClient()
+  const store = cache?.[name] as unknown as Amity.Store<Amity.Model[K]>
+
+  if (!cache || !store) return
+
+  const state = store.read() ?? {}
+
+  // return all
+  if (!keys?.length)
+    return Object.values(state)
+
+  // return some
+  return keys
+    .map(key => {
+      const localId = cache.lookup[`${name}#${key}`]
+      return state[localId]
+    })
+    .filter(Boolean)
+}

package/src/core/cache/push.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api/activeClient'
+
+import { getResolver } from '../model/idResolvers'
+
+/**
+ * Pull objects from the cache layer
+ *
+ * @param name The name of the store to query
+ * @param models A collection of models t store
+ *
+ * @category Cache
+ */
+export const pushToCache = <T extends Amity.Domain>(
+  name: T,
+  ...models: (Amity.Model[T])[]
+) => {
+  const { cache } = getActiveClient()
+
+  const store = cache?.[name] as unknown as Amity.Store<Amity.Model[T]>
+  if (!cache || !store) return
+
+  const filtered = models.filter(Boolean)
+  if (!filtered.length) return
+
+  const synced = Object.fromEntries(
+    filtered.map(model => {
+      const modelId = getResolver(name)(model)
+      const localId = (cache.lookup[`${name}#${modelId}`] ??= model.localId)
+
+      // WARNING: shallow immutable
+      return [localId, {
+        // @ts-ignore: syncedAt is before "...model" so it can be manually overridden
+        syncedAt: Date.now(),
+        ...model,
+        localId,
+      }]
+    })
+  )
+
+  store.write(synced)
+}

package/src/core/cache/sync.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api/activeClient'
+
+import { identifyModel } from '../model/identifyModel'
+
+import { dropFromCache } from './drop'
+import { pushToCache } from './push'
+
+/**
+ * Sync-up local ids of objects in the cache
+ *
+ * @param original The object holding the localId to keep
+ * @param replacement The object holding the localId to discard
+ *
+ * @category Cache
+ */
+export const syncInCache = <T extends Amity.Domain>(
+  original: Amity.Model[T],
+  replacement: Amity.Model[T],
+) => {
+  const { cache, log } = getActiveClient()
+
+  const name = identifyModel(original) ?? identifyModel(replacement)
+
+  if (!name) {
+    log('syncInCache', 'could not identify the models', { original, replacement })
+    return
+  }
+
+  const store = cache?.[name] as unknown as Amity.Store<Amity.Model[T]>
+  if (!cache || !store) return
+
+  // remove the object from cache (it's cleaner this way)
+  dropFromCache(name, original)
+  dropFromCache(name, replacement)
+
+  // glue the localIds together
+  replacement.localId = original.localId
+
+  // put back the replacement after (again, it's cleaner this way)
+  pushToCache(name, replacement)
+}

package/src/core/debug.ts

@@ -0,0 +1,26 @@
+import debug from 'debug'
+
+/**
+ * Creates a pre-configured logger instance
+ *
+ * @param session The name of the debug session
+ * @returns A pre-configured logger function
+ *
+ * @category Debug
+ * @hidden
+ */
+export const createLogger = (session?: string) => {
+  const active = (
+      `${session?.trim()}`.length > 0
+    && process.env.NODE_ENV !== 'production'
+  )
+
+  const logger = debug(session!)
+
+  const print = (topic: string, ...args: any[]) => {
+    active && logger(topic, args)
+  }
+
+  print.__instance__ = logger
+  return print
+}

package/src/core/device.ts

@@ -0,0 +1,38 @@
+// TODO: find a way to uniquely identify the device
+// import { getStorage } from './storage'
+
+/** @hidden */
+const VERSION = '11.0.0'
+
+/** @hidden */
+export const getDeviceId = () => {
+  // here maybe put some auto detection of the device id based on if it's react or not?
+  // anyhow we let consumer branch out if they want, but it doesn't mean we shouldn't try to be nice
+  // and do things automatically
+  // https://www.npmjs.com/package/react-native-device-info#getuniqueid
+  // how to make sure that the react native package will not be included when build is for web
+  return `ascWebSdk#${Math.random().toString(16)}`
+}
+
+/** @hidden */
+export const getDeviceModel = () => {
+  if (process?.versions?.node)
+    return process.versions.node
+
+  if (navigator)
+    return `${navigator.product.toLowerCase()}#${navigator.userAgent ?? 'unknown_agent'}`
+
+  return 'unknown_model'
+}
+
+/** @hidden */
+export const getDeviceInfo = (): Amity.Device['deviceInfo'] => {
+  const model = getDeviceModel()
+
+  return {
+    version: VERSION,
+    // TODO: replace with: kind: process.versions ? 'node' : 'web', when backend has fixed this
+    kind: 'web',
+    model,
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,85 @@
+/**
+ * Generic ASC error
+ * @category Errors
+ */
+export class ASCError extends Error {
+  readonly type: string = 'ASC'
+  readonly timestamp: number = Date.now()
+
+  /**
+   * @param message A custom error message
+   * @param code A normalized error code
+   * @param level A normalized failure level descriptor
+   */
+  constructor(
+    message: string,
+    public readonly code: Amity.ClientError,
+    public readonly level: Amity.ErrorLevel,
+  ) {
+    super(`Amity SDK (${code}): ${message}`)
+
+    if (Error.captureStackTrace)
+      Error.captureStackTrace(this, ASCError)
+  }
+}
+
+/**
+ * API level error
+ * @category Errors
+ */
+export class ASCApiError extends ASCError {
+  /**
+   * @param code A normalized error code
+   * @param level A normalized failure level descriptor
+   */
+  constructor(
+    message: string,
+    code: Amity.ClientError,
+    level: Amity.ErrorLevel,
+  ) {
+    super(message, code, level)
+  }
+}
+
+/**
+ * Unexpected error
+ * @category Errors
+ */
+export class ASCUnknownError extends ASCError {
+  /**
+   * @param code A normalized error code
+   * @param level A normalized failure level descriptor
+   */
+  constructor(
+    code: Amity.ClientError = Amity.ClientError.UNKNOWN_ERROR,
+    level: Amity.ErrorLevel = Amity.ErrorLevel.FATAL,
+  ) {
+    super('Unexpected error', code, level)
+  }
+}
+
+/**
+ * Network related error
+ * @category Errors
+ */
+export class ASCConnectionError extends ASCError {
+  /**
+   * @param message A custom error message
+   */
+  constructor(message: string = 'SDK client is having connection issues') {
+    super(message, Amity.ClientError.CONNECTION_ERROR, Amity.ErrorLevel.ERROR)
+  }
+}
+
+/**
+ * Input sanitization related error
+ * @category Errors
+ */
+export class ASCInvalidParameterError extends ASCError {
+  /**
+   * @param message A custom error message
+   */
+  constructor(message: string) {
+    super(message, Amity.ClientError.INVALID_PARAMETERS, Amity.ErrorLevel.ERROR)
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,93 @@
+import mitt from 'mitt'
+
+import { getActiveClient } from '~/client/api/activeClient'
+
+// need to sync up the list
+const EVENTS = [
+  'disconnected',
+
+  'v3.user.didUpdate',
+
+  'v3.channel.didUpdate',
+  'v3.channel.didUpdate',
+  'v3.channel.didJoin',
+  'v3.channel.didLeave',
+  'v3.channel.didAddUsers',
+  'v3.channel.didRemoveUsers',
+  'v3.channel.didBan',
+  'v3.channel.didUnban',
+
+  'v3.message.didCreate',
+  'v3.message.didUpdate',
+  'v3.message.didDelete',
+] as const
+
+/** @hidden */
+export const createEventEmitter = () => {
+  return mitt<Amity.Events>()
+}
+
+/**
+ * Wraps the websocket events into the client's event emitter for
+ * abstraction of transport.
+ *
+ * @param ws A websocket connection to listen from
+ * @param emitter An event emitter to wire the events to
+ *
+ * @category Transport
+ * @hidden
+ */
+export const proxyWebsocketEvents = (ws: Amity.Client['ws'], emitter: Amity.Client['emitter']) => {
+  EVENTS.forEach(event => {
+    ws.on(event, (param: Amity.Events[typeof event]) => emitter.emit(event, param))
+  })
+}
+
+/**
+ * Standardize the subscription of SSE through web sockets
+ *
+ * @param client The current client for which to subscribe the event to
+ * @param namespace A unique name for the logger
+ * @param event The websocket event name
+ * @param fn A wrapper for the callback.
+ * @returns A dispose function to unsubscribe to the event
+ *
+ * @category Transport
+ * @hidden
+ */
+export const createEventSubscriber = <T extends keyof Amity.Events>(
+  client: Amity.Client,
+  namespace: string,
+  event: T,
+  fn: Amity.Listener<Amity.Events[T]>,
+): Amity.Unsubscriber => {
+  const { log, emitter } = client
+
+  const timestamp = Date.now()
+  log(`${namespace}(tmpid: ${timestamp}) > listen`)
+
+  const handler = (...payload: Parameters<typeof fn>) => {
+    log(`${namespace}(tmpid: ${timestamp}) > trigger`, payload)
+    fn(...payload)
+  }
+
+  emitter.on(event, handler)
+
+  return () => {
+    log(`${namespace}(tmpid: ${timestamp}) > dispose`)
+    emitter.off(event, handler)
+  }
+}
+
+/**
+ * Wrapper around dispatch event
+ *
+ * @hidden
+ */
+export const fireEvent = <T extends keyof Amity.Events>(
+  event: T,
+  payload: Amity.Events[T],
+) => {
+  const { emitter } = getActiveClient()
+  setTimeout(() => { emitter.emit(event, payload) }, 0)
+}

package/src/core/model/idResolvers.ts

@@ -0,0 +1,66 @@
+/**
+ * A resolver function is a function which, given a minimal version of a model T
+ * can compute a string which is capable of identifying the given model uniquely
+ * @hidden
+ */
+type Resolver<T extends Amity.Domain> = (model: Amity.Minimal[T]) => string
+
+/**
+ * Manually computed type to output a dictionary of { Domain: Amity.Resolver<Model> }
+ * with proper typing based on T
+ * @hidden
+ */
+type Resolvers<T extends Amity.Domain[] = Amity.Domain[]> = {
+  [K in T[number]]: Resolver<K>
+}
+
+/**
+ * Dictionary of resolver functions for each model
+ * @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,
+  communityUsers: ({ communityId, userId }) => `${communityId}#${userId}`,
+  post: ({ postId }) => postId,
+  comment: ({ commentId }) => commentId,
+
+  stream: ({ streamId }) => streamId,
+}
+
+/**
+ * Retrieve the id resolver matching a domain name
+ *
+ * @param name the domain name for the resolve
+ * @returns an idResolver for the given domain name
+ */
+export const getResolver = <T extends Amity.Domain>(name: T) => (
+  idResolvers[name] as Resolver<T>
+)
+
+/**
+ * A map of v3 response keys to a store name.
+ * @hidden
+ */
+export const storeInterests: Record<string, Amity.Domain> = {
+  users: 'user',
+  files: 'file',
+  roles: 'role',
+
+  channels: 'channel',
+  channelUsers: 'channelUsers',
+  messages: 'message',
+
+  communities: 'community',
+  communityUsers: 'communityUsers',
+  posts: 'post',
+  postChildren: 'post',
+  comments: 'comment',
+}

package/src/core/model/identifyModel.ts

@@ -0,0 +1,32 @@
+/** hidden */
+/** @hidden */
+const CRITERIAS: Record<Amity.Domain, string[]>  = {
+  'file': ['fileId', 'attributes'],
+  'user': ['userId', 'avatarFileId'],
+  'role': ['roleId'],
+  'channel': ['channelId', 'rateLimit'],
+  'channelUsers': ['channelId', 'userId', 'membership'],
+  'message': ['messageId'],
+  'community': ['communityId', 'onlyAdminCanPost'],
+  'communityUsers': ['userId', 'communityId', 'communityMembership'],
+  'post': ['postId', 'feedId'],
+  'comment': ['commentId', 'referenceId'],
+  'stream': ['streamId'],
+}
+
+/** @hidden */
+const hasKeys = (object: { [k: string]: any }, 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: Amity.Model[Amity.Domain]) => {
+  const criterias = Object.entries(CRITERIAS) as [Amity.Domain, string[]][]
+  return criterias.find(([_, keys]) => hasKeys(model, keys))?.[0]
+}

package/src/core/model/index.ts

@@ -0,0 +1,3 @@
+export * from './identifyModel'
+export * from './idResolvers'
+export * from './toRecord'

package/src/core/model/toRecord.ts

@@ -0,0 +1,11 @@
+/**
+ * converts an array looking collection to an object collection, grouped by localId
+ *
+ * @param array array of {@link Amity.Syncable}
+ * @returns array converted to object, grouped by localId
+ *
+ * @hidden
+ */
+export const toRecord = <T extends Amity.Syncable>(array: T[]): Record<string, T> => (
+  array.reduce((acc, item) => ({ ...acc, [item.localId]: item }), {})
+)

package/src/core/query/decorate.ts

@@ -0,0 +1,64 @@
+import { uuid } from '~/core/uuid'
+
+import { getActiveClient } from '~/client/api'
+
+import {
+  getResolver,
+  identifyModel,
+  storeInterests,
+} from '../model'
+
+/**
+ * Set the model's syncedAt property and localId
+ *
+ * @param model the model to decorate
+ * @param timestamp the given timestamp
+ */
+export const decoratePayload = (
+  payload: Record<string, object[]>,
+  timestamp: number = Date.now(),
+  keyMapping: Record<string, Amity.Domain> = storeInterests,
+) => {
+  Object.fromEntries(
+    Object.entries(payload)
+      .map(([key, models]) => ([
+        key, decorateModels(models as any[], timestamp, keyMapping[key])
+      ]))
+  )
+}
+
+/**
+ * Set the model's syncedAt property and localId
+ *
+ * @param model the model to decorate
+ * @param timestamp the given timestamp
+ */
+export const decorateModels = <T extends Amity.Model[Amity.Domain]>(
+  models: T[],
+  timestamp: number = Date.now(),
+  type?: Amity.Domain
+) => {
+  models.forEach(model => decorateModel(model, timestamp, type))
+}
+
+/**
+ * Set the model's syncedAt property and localId
+ *
+ * @param model the model to decorate
+ * @param syncedAt the given timestamp
+ * @param type An opportunity to manually pass the type. If undefined, it will be smartly computed
+ */
+export const decorateModel = <T extends Amity.Model[Amity.Domain]>(
+  model: T,
+  timestamp: number = Date.now(),
+  type = identifyModel(model)
+) => {
+  model.syncedAt ??= timestamp
+
+  const { cache } = getActiveClient()
+
+  if (type) {
+    const modelId = getResolver(type)(model)
+    model.localId = cache?.lookup[`${type}#${modelId}`] ?? uuid()
+  }
+}

package/src/core/query/filtering.ts

@@ -0,0 +1,17 @@
+// 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 = {}>(collection: T[], key: keyof T, value: any) => (
+  value !== undefined ? collection.filter(item => item[key] === value) : collection
+)

package/src/core/query/index.ts

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