@tgify/tgify 0.1.0

package/src/core/helpers/args.ts

@@ -0,0 +1,63 @@
+interface Entity {
+  /** Type of the entity. Currently, can be “mention” (@username), “hashtag” (#hashtag), “cashtag” ($USD), “bot_command” (/start@jobs_bot), “url” (https://telegram.org), “email” (do-not-reply@telegram.org), “phone_number” (+1-212-555-0123), “bold” (bold text), “italic” (italic text), “underline” (underlined text), “strikethrough” (strikethrough text), “spoiler” (spoiler message), “code” (monowidth string), “pre” (monowidth block), “text_link” (for clickable text URLs), “text_mention” (for users without usernames), “custom_emoji” (for inline custom emoji stickers) */
+  type: string
+  /** Offset in UTF-16 code units to the start of the entity */
+  offset: number
+  /** Length of the entity in UTF-16 code units */
+  length: number
+}
+
+const SINGLE_QUOTE = "'"
+const DOUBLE_QUOTE = '"'
+
+export function argsParser(
+  str: string,
+  entities: Entity[] = [],
+  entityOffset = 0
+) {
+  const mentions: { [offset: string]: number } = {}
+  for (const entity of entities) // extract all text_mentions into an { offset: length } map
+    if (entity.type === 'text_mention' || entity.type === 'text_link')
+      mentions[entity.offset - entityOffset] = entity.length
+
+  const args: string[] = []
+  let done = 0
+  let inside: `'` | `"` | undefined = undefined
+  let buf = ''
+
+  function flush(to: number) {
+    if (done !== to) args.push(buf + str.slice(done, to)), (inside = undefined)
+    buf = ''
+    done = to + 1
+  }
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i]
+    // quick lookup length of mention starting at i
+    const mention = mentions[i]
+    if (mention) {
+      // if we're inside a quote, eagerly flush existing state
+      flush(i)
+      // this also consumes current index, so decrement
+      done--
+      // fast forward to end of mention
+      i += mention
+      flush(i)
+    } else if (char === SINGLE_QUOTE || char === DOUBLE_QUOTE)
+      if (inside)
+        if (inside === char) flush(i)
+        else continue
+      else flush(i), (inside = char)
+    else if (char === ' ')
+      if (inside) continue
+      else flush(i)
+    else if (char === '\n') flush(i)
+    else if (char === '\\')
+      (buf += str.slice(done, i)), (done = ++i) // skip parsing the next char
+    else continue
+  }
+
+  if (done < str.length) flush(str.length)
+
+  return args
+}

package/src/core/helpers/check.ts

@@ -0,0 +1,71 @@
+interface Mapping {
+  string: string
+  number: number
+  bigint: bigint
+  boolean: boolean
+  symbol: symbol
+  undefined: undefined
+  object: Record<string, unknown>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function: (...props: any[]) => any
+}
+
+/**
+ * Checks if a given object has a property with a given name.
+ *
+ * Example invocation:
+ * ```js
+ * let obj = { 'foo': 'bar', 'baz': () => {} }
+ * hasProp(obj, 'foo') // true
+ * hasProp(obj, 'baz') // true
+ * hasProp(obj, 'abc') // false
+ * ```
+ *
+ * @param obj An object to test
+ * @param prop The name of the property
+ */
+export function hasProp<O extends object, K extends PropertyKey>(
+  obj: O | undefined,
+  prop: K
+): obj is O & Record<K, unknown> {
+  return obj !== undefined && prop in obj
+}
+/**
+ * Checks if a given object has a property with a given name.
+ * Furthermore performs a `typeof` check on the property if it exists.
+ *
+ * Example invocation:
+ * ```js
+ * let obj = { 'foo': 'bar', 'baz': () => {} }
+ * hasPropType(obj, 'foo', 'string') // true
+ * hasPropType(obj, 'baz', 'function') // true
+ * hasPropType(obj, 'abc', 'number') // false
+ * ```
+ *
+ * @param obj An object to test
+ * @param prop The name of the property
+ * @param type The type the property is expected to have
+ */
+export function hasPropType<
+  O extends object,
+  K extends PropertyKey,
+  T extends keyof Mapping,
+  V extends Mapping[T],
+>(obj: O | undefined, prop: K, type: T): obj is O & Record<K, V> {
+  return hasProp(obj, prop) && type === typeof obj[prop]
+}
+
+/**
+ * Checks if the supplied array has two dimensions or not.
+ *
+ * Example invocations:
+ * is2D([]) // false
+ * is2D([[]]) // true
+ * is2D([[], []]) // true
+ * is2D([42]) // false
+ *
+ * @param arr an array with one or two dimensions
+ */
+export function is2D<E>(arr: E[] | E[][]): arr is E[][] {
+  return Array.isArray(arr[0])
+}

package/src/core/helpers/compact.ts

@@ -0,0 +1,18 @@
+export function compactOptions<T extends { [key: string]: unknown }>(
+  options?: T
+): T | undefined {
+  if (!options) {
+    return options
+  }
+
+  const compacted: Partial<T> = {}
+  for (const key in options)
+    if (
+      // todo(mkr): replace with Object.hasOwn in v5 (Node 16+)
+      Object.prototype.hasOwnProperty.call(options, key) &&
+      options[key] !== undefined
+    )
+      compacted[key] = options[key]
+
+  return compacted as T | undefined
+}

package/src/core/helpers/deunionize.ts

@@ -0,0 +1,26 @@
+export type PropOr<
+  T extends object | undefined,
+  P extends string | symbol | number,
+  D = undefined,
+> = T extends Partial<Record<P, unknown>> ? T[P] : D
+
+export type UnionKeys<T> = T extends unknown ? keyof T : never
+
+type AddOptionalKeys<K extends PropertyKey> = { readonly [P in K]?: never }
+
+/**
+ * @see https://millsp.github.io/ts-toolbelt/modules/union_strict.html
+ */
+export type Deunionize<B extends object | undefined, T = B> = T extends object
+  ? T & AddOptionalKeys<Exclude<UnionKeys<B>, keyof T>>
+  : T
+
+/**
+ * Expose properties from all union variants.
+ * @deprectated
+ * @see https://github.com/telegraf/telegraf/issues/1388#issuecomment-791573609
+ * @see https://millsp.github.io/ts-toolbelt/modules/union_strict.html
+ */
+export function deunionize<T extends object | undefined>(t: T) {
+  return t as Deunionize<T>
+}

package/src/core/helpers/formatting.ts

@@ -0,0 +1,119 @@
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+import { MessageEntity, User } from '@telegraf/types'
+import { Any, zip } from './util'
+
+export type Nestable<Kind extends string> =
+  | string
+  | number
+  | boolean
+  | FmtString<Kind>
+export type MaybeNestableList<Kind extends string> =
+  | Nestable<Kind>
+  | readonly Nestable<Kind>[]
+
+export interface FmtString<Brand extends string> {
+  text: string
+  entities?: MessageEntity[]
+  parse_mode?: undefined
+  __to_nest: Brand
+}
+
+export class FmtString<Brand extends string = string>
+  implements FmtString<Brand>
+{
+  constructor(
+    public text: string,
+    entities?: MessageEntity[]
+  ) {
+    if (entities) {
+      this.entities = entities
+      // force parse_mode to undefined if entities are present
+      this.parse_mode = undefined
+    }
+  }
+  static normalise(content: Nestable<string>) {
+    if (content instanceof FmtString) return content
+    return new FmtString(String(content))
+  }
+}
+
+const isArray: <T>(xs: T | readonly T[]) => xs is readonly T[] = Array.isArray
+
+/** Given a base FmtString and something to append to it, mutates the base */
+const _add = (base: FmtString, next: FmtString | Any) => {
+  const len = base.text.length
+  if (next instanceof FmtString) {
+    base.text = `${base.text}${next.text}`
+    // next.entities could be undefined and condition will fail
+    for (let i = 0; i < (next.entities?.length || 0); i++) {
+      // because of the above condition, next.entities[i] cannot be undefined
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const entity = next.entities![i]!
+      // base.entities is ensured by caller
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      base.entities!.push({ ...entity, offset: entity.offset + len })
+    }
+  } else base.text = `${base.text}${next}`
+}
+
+/**
+ * Given an `Iterable<FmtString | string | Any>` and a separator, flattens the list into a single FmtString.
+ * Analogous to Array#join -> string, but for FmtString
+ */
+export const join = (
+  fragments: Iterable<FmtString | string | Any>,
+  separator?: string | FmtString
+) => {
+  const result = new FmtString('')
+  // ensure entities array so loop doesn't need to check
+  result.entities = []
+
+  const iter = fragments[Symbol.iterator]()
+
+  let curr = iter.next()
+  while (!curr.done) {
+    _add(result, curr.value)
+    curr = iter.next()
+    if (separator && !curr.done) _add(result, separator)
+  }
+
+  // set parse_mode: undefined if entities are present
+  if (result.entities.length) result.parse_mode = undefined
+  // remove entities array if not relevant
+  else delete result.entities
+
+  return result
+}
+
+/** Internal constructor for all fmt helpers */
+export function createFmt(kind?: MessageEntity['type'], opts?: object) {
+  return function fmt(
+    parts: MaybeNestableList<string>,
+    ...items: Nestable<string>[]
+  ) {
+    parts = isArray(parts) ? parts : [parts]
+    const result = join(zip(parts, items))
+    if (kind) {
+      result.entities ??= []
+      result.entities.unshift({
+        type: kind,
+        offset: 0,
+        length: result.text.length,
+        ...opts,
+      } as MessageEntity)
+      result.parse_mode = undefined
+    }
+    return result
+  }
+}
+
+export const linkOrMention = (
+  content: Nestable<string>,
+  data:
+    | { type: 'text_link'; url: string }
+    | { type: 'text_mention'; user: User }
+) => {
+  const { text, entities = [] } = FmtString.normalise(content)
+  entities.unshift(Object.assign(data, { offset: 0, length: text.length }))
+  return new FmtString(text, entities)
+}

package/src/core/helpers/util.ts

@@ -0,0 +1,96 @@
+import { FmtString } from './formatting'
+import { Deunionize, UnionKeys } from './deunionize'
+
+export const env = process.env
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type Any = {} | undefined | null
+
+export type Expand<T> = T extends object
+  ? T extends infer O
+    ? { [K in keyof O]: O[K] }
+    : never
+  : T
+
+export type MaybeArray<T> = T | T[]
+export type MaybePromise<T> = T | Promise<T>
+export type NonemptyReadonlyArray<T> = readonly [T, ...T[]]
+
+// prettier-ignore
+export type ExclusiveKeys<A extends object, B extends object> = keyof Omit<A, keyof B>
+
+export function fmtCaption<
+  Extra extends { caption?: string | FmtString } | undefined,
+>(
+  extra?: Extra
+): Extra extends undefined
+  ? undefined
+  : Omit<Extra, 'caption'> & { caption?: string }
+
+export function fmtCaption(extra?: { caption?: string | FmtString }) {
+  if (!extra) return
+  const caption = extra.caption
+  if (!caption || typeof caption === 'string') return extra
+  const { text, entities } = caption
+  return {
+    ...extra,
+    caption: text,
+    ...(entities && {
+      caption_entities: entities,
+      parse_mode: undefined,
+    }),
+  }
+}
+
+export type DistinctKeys<T extends object> = Exclude<UnionKeys<T>, keyof T>
+
+// prettier-ignore
+/* eslint-disable-next-line @typescript-eslint/ban-types */
+export type KeyedDistinct<T extends object, K extends DistinctKeys<T>> = Record<K, {}> & Deunionize<Record<K, {}>, T>
+
+// prettier-ignore
+/* eslint-disable-next-line @typescript-eslint/ban-types */
+export type Keyed<T extends object, K extends UnionKeys<T>> = Record<K, {}> & Deunionize<Record<K, {}>, T>
+
+/** Construct a generic type guard */
+export type Guard<X = unknown, Y extends X = X> = (x: X) => x is Y
+
+/** Extract the guarded type from a type guard, defaults to never. */
+export type Guarded<F> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  F extends (x: any) => x is infer T ? T : never
+
+export function* zip<X, Y>(xs: Iterable<X>, ys: Iterable<Y>): Iterable<X | Y> {
+  const x = xs[Symbol.iterator]()
+  const y = ys[Symbol.iterator]()
+  let x1 = x.next()
+  let y1 = y.next()
+
+  while (!x1.done) {
+    yield x1.value
+    if (!y1.done) yield y1.value
+    x1 = x.next()
+    y1 = y.next()
+  }
+
+  while (!y1.done) {
+    yield y1.value
+    y1 = y.next()
+  }
+}
+
+export function indexed<T extends object, U>(
+  target: T,
+  indexer: (index: number) => U
+) {
+  return new Proxy(target, {
+    get: function (target, prop, receiver) {
+      if (
+        (typeof prop === 'string' || typeof prop === 'number') &&
+        !isNaN(+prop)
+      )
+        return indexer.call(target, +prop)
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+}