@dxtmisha/functional-basic 0.1.0 → 0.1.1

package/src/classes/Meta.ts

@@ -0,0 +1,284 @@
+import { isDomRuntime } from '../functions/isDomRuntime'
+import { isFilled } from '../functions/isFilled'
+import { toArray } from '../functions/toArray'
+
+import { MetaManager } from './MetaManager'
+import { MetaOg } from './MetaOg'
+import { MetaTwitter } from './MetaTwitter'
+
+import { MetaRobots, MetaTag } from '../types/metaTypes'
+
+/**
+ * Unified class for managing all types of meta tags (standard HTML, Open Graph, Twitter Card).
+ *
+ * Унифицированный класс для управления всеми типами мета-тегов (стандартные HTML, Open Graph, Twitter Card).
+ */
+export class Meta extends MetaManager<MetaTag[]> {
+  protected suffix?: string
+
+  protected og: MetaOg
+  protected twitter: MetaTwitter
+
+  /**
+   * Creates an instance of Meta with integrated Open Graph and Twitter Card support.
+   *
+   * Создает экземпляр Meta с интегрированной поддержкой Open Graph и Twitter Card.
+   */
+  constructor() {
+    super(Object.values(MetaTag))
+
+    this.og = new MetaOg()
+    this.twitter = new MetaTwitter()
+  }
+
+  /**
+   * Gets the MetaOg instance for advanced Open Graph operations.
+   *
+   * Получает экземпляр MetaOg для расширенных операций с Open Graph.
+   */
+  getOg(): MetaOg {
+    return this.og
+  }
+
+  /**
+   * Gets the MetaTwitter instance for advanced Twitter Card operations.
+   *
+   * Получает экземпляр MetaTwitter для расширенных операций с Twitter Card.
+   */
+  getTwitter(): MetaTwitter {
+    return this.twitter
+  }
+
+  /**
+   * Gets the page title without suffix.
+   *
+   * Получает заголовок страницы без суффикса.
+   */
+  getTitle(): string {
+    if (!isDomRuntime()) {
+      return ''
+    }
+
+    return document.title
+      .replace(this.getSuffix(), '')
+      .trim()
+  }
+
+  /**
+   * Gets the keywords meta tag.
+   *
+   * Получает мета-тег keywords.
+   */
+  getKeywords(): string {
+    return this.get(MetaTag.keywords)
+  }
+
+  /**
+   * Gets the description meta tag.
+   *
+   * Получает мета-тег description.
+   */
+  getDescription(): string {
+    return this.get(MetaTag.description)
+  }
+
+  /**
+   * Gets the Open Graph image URL.
+   *
+   * Получает URL изображения Open Graph.
+   */
+  getImage(): string {
+    return this.og.getImage()
+  }
+
+  /**
+   * Gets the canonical URL.
+   *
+   * Получает канонический URL.
+   */
+  getCanonical(): string {
+    return this.get(MetaTag.canonical)
+  }
+
+  /**
+   * Gets the robots meta tag value.
+   *
+   * Получает значение мета-тега robots.
+   */
+  getRobots(): MetaRobots {
+    return this.get(MetaTag.robots) as MetaRobots
+  }
+
+  /**
+   * Gets the author meta tag.
+   *
+   * Получает мета-тег author.
+   */
+  getAuthor(): string {
+    return this.get(MetaTag.author)
+  }
+
+  /**
+   * Gets the Open Graph site name.
+   *
+   * Получает название сайта Open Graph.
+   */
+  getSiteName(): string {
+    return this.og.getSiteName()
+  }
+
+  /**
+   * Gets the Open Graph locale.
+   *
+   * Получает локаль Open Graph.
+   */
+  getLocale(): string {
+    return this.og.getLocale()
+  }
+
+  /**
+   * Sets the page title (with suffix) and updates Open Graph and Twitter Card titles.
+   *
+   * Устанавливает заголовок страницы (с суффиксом) и обновляет заголовки Open Graph и Twitter Card.
+   * @param title page title / заголовок страницы
+   */
+  setTitle(title: string): this {
+    if (isDomRuntime()) {
+      const fullTitle = isFilled(title)
+        ? `${title}${this.getSuffix()}`
+        : this.suffix
+          ? this.suffix
+          : ''
+
+      document.title = fullTitle
+      this.og.setTitle(fullTitle)
+      this.twitter.setTitle(fullTitle)
+    }
+
+    return this
+  }
+
+  /**
+   * Sets the keywords meta tag.
+   *
+   * Устанавливает мета-тег keywords.
+   * @param keywords keywords as string or array / ключевые слова в виде строки или массива
+   */
+  setKeywords(keywords: string | string[]): this {
+    this.set(MetaTag.keywords, toArray(keywords).join(', '))
+    return this
+  }
+
+  /**
+   * Sets the description meta tag.
+   *
+   * Устанавливает мета-тег description.
+   * @param description page description / описание страницы
+   */
+  setDescription(description: string): this {
+    this.set(MetaTag.description, description)
+    return this
+  }
+
+  /**
+   * Sets the image for Open Graph and Twitter Card.
+   *
+   * Устанавливает изображение для Open Graph и Twitter Card.
+   * @param image image URL / URL изображения
+   */
+  setImage(image: string): this {
+    this.og.setImage(image)
+    this.twitter.setImage(image)
+    return this
+  }
+
+  /**
+   * Sets the canonical URL and updates Open Graph and Twitter Card URLs.
+   *
+   * Устанавливает канонический URL и обновляет URL для Open Graph и Twitter Card.
+   * @param canonical canonical URL / канонический URL
+   */
+  setCanonical(canonical: string): this {
+    this.set(MetaTag.canonical, canonical)
+    this.og.setUrl(canonical)
+    this.twitter.setUrl(canonical)
+    return this
+  }
+
+  /**
+   * Sets the robots meta tag.
+   *
+   * Устанавливает мета-тег robots.
+   * @param robots robots directive / директива robots
+   */
+  setRobots(robots: MetaRobots): this {
+    this.set(MetaTag.robots, robots)
+    return this
+  }
+
+  /**
+   * Sets the author meta tag.
+   *
+   * Устанавливает мета-тег author.
+   * @param author author name / имя автора
+   */
+  setAuthor(author: string): this {
+    this.set(MetaTag.author, author)
+    return this
+  }
+
+  /**
+   * Sets the site name for Open Graph and Twitter Card.
+   *
+   * Устанавливает название сайта для Open Graph и Twitter Card.
+   * @param siteName site name / название сайта
+   */
+  setSiteName(siteName: string): this {
+    this.og.setSiteName(siteName)
+    this.twitter.setSite(siteName)
+    return this
+  }
+
+  /**
+   * Sets the locale for Open Graph.
+   *
+   * Устанавливает локаль для Open Graph.
+   * @param locale locale (e.g. 'en_US', 'ru_RU') / локаль (например, 'en_US', 'ru_RU')
+   */
+  setLocale(locale: string): this {
+    this.og.setLocale(locale)
+    return this
+  }
+
+  /**
+   * Sets the suffix to append to page title.
+   *
+   * Устанавливает суффикс для добавления к заголовку страницы.
+   * @param suffix title suffix (e.g. 'My Site') / суффикс заголовка (например, 'Мой Сайт')
+   */
+  setSuffix(suffix?: string) {
+    this.suffix = suffix
+  }
+
+  /**
+   * Generates the complete HTML for all meta-tags including Open Graph and Twitter Card.
+   *
+   * Генерирует полный HTML для всех мета-тегов, включая Open Graph и Twitter Card.
+   */
+  html(): string {
+    return `${super.html()}${this.og.html()}${this.twitter.html()}`
+  }
+
+  /**
+   * Gets the formatted suffix with separator.
+   *
+   * Получает отформатированный суффикс с разделителем.
+   */
+  protected getSuffix(): string {
+    if (isFilled(this.suffix)) {
+      return ` - ${this.suffix}`
+    }
+
+    return ''
+  }
+}

package/src/classes/MetaManager.ts

@@ -0,0 +1,200 @@
+import { createElement } from '../functions/createElement'
+import { encodeAttribute } from '../functions/encodeAttribute'
+import { forEach } from '../functions/forEach'
+import { isDomRuntime } from '../functions/isDomRuntime'
+
+type MetaList<T extends readonly string[]> = {
+  [K in T[number]]?: string
+}
+
+/**
+ * Class for working with meta tags.
+ *
+ * Класс для управления мета-тегами.
+ */
+export class MetaManager<
+  T extends readonly string[],
+  Key extends keyof MetaList<T> = keyof MetaList<T>
+> {
+  protected readonly items: MetaList<T> = {}
+
+  /**
+   * Creates an instance of MetaManager.
+   *
+   * Создает экземпляр MetaManager.
+   * @param listMeta list of meta-tag names to manage / список имен мета-тегов для управления
+   * @param isProperty use 'property' attribute instead of 'name' / использовать атрибут 'property' вместо 'name'
+   */
+  constructor(
+    protected readonly listMeta: T,
+    protected readonly isProperty: boolean = false
+  ) {
+    this.update()
+  }
+
+  /**
+   * Returns the list of meta tag names.
+   *
+   * Возвращает список имен мета-тегов.
+   */
+  getListMeta(): T {
+    return this.listMeta
+  }
+
+  /**
+   * Get the content of a meta tag by name.
+   *
+   * Получает содержимое мета-тега по имени.
+   * @param name meta tag name / имя мета-тега
+   */
+  get(name: Key): string {
+    return this.items[name] ?? ''
+  }
+
+  /**
+   * Returns all meta tags.
+   *
+   * Возвращает все мета-теги.
+   */
+  getItems(): MetaList<T> {
+    return this.items
+  }
+
+  /**
+   * Returns all meta tags as HTML string.
+   *
+   * Возвращает все мета-теги в виде HTML-строки.
+   */
+  html(): string {
+    const code = forEach(
+      this.listMeta as any,
+      name => this.toHtmlString(name as any as Key)
+    )
+
+    return code.join('')
+  }
+
+  /**
+   * Sets the content of a meta tag.
+   *
+   * Устанавливает содержимое мета-тега.
+   * @param name meta tag name / имя мета-тега
+   * @param content meta tag content / содержимое мета-тега
+   */
+  set(name: Key, content: string): this {
+    this
+      .setItem(name, content)
+      .setMeta(name)
+
+    return this
+  }
+
+  /**
+   * Sets multiple meta tags from an object.
+   *
+   * Устанавливает несколько мета-тегов из объекта.
+   * @param metaList object with meta tag names and content / объект с именами и содержимым мета-тегов
+   */
+  setByList(metaList: MetaList<T>): this {
+    forEach(
+      metaList,
+      (content, name) =>
+        this.set(name as any as Key, String(content))
+    )
+
+    return this
+  }
+
+  /**
+   * Returns the attribute name for meta tags.
+   *
+   * Возвращает имя атрибута для мета-тегов.
+   */
+  protected getAttributeName(): string {
+    return this.isProperty ? 'property' : 'name'
+  }
+
+  /**
+   * Finds a meta element in the DOM.
+   *
+   * Находит мета-элемент в DOM.
+   * @param name meta tag name / имя мета-тега
+   */
+  protected findMetaElement(name: string): HTMLMetaElement | undefined {
+    if (!isDomRuntime()) {
+      return undefined
+    }
+
+    const selector = `meta[${this.getAttributeName()}="${name}"]`
+
+    return document.querySelector<HTMLMetaElement>(selector) || undefined
+  }
+
+  /**
+   * Sets the content of a meta tag in internal storage.
+   *
+   * Устанавливает содержимое мета-тега во внутреннем хранилище.
+   * @param name meta tag name / имя мета-тега
+   * @param content meta tag content / содержимое мета-тега
+   */
+  protected setItem(name: Key, content: string): this {
+    this.items[name] = content
+    return this
+  }
+
+  /**
+   * Sets or creates a meta tag in the DOM.
+   *
+   * Устанавливает или создает мета-тег в DOM.
+   * @param name meta tag name / имя мета-тега
+   */
+  protected setMeta(name: Key): this {
+    const element = this.findMetaElement(name)
+    const content = this.items[name] ?? ''
+
+    if (element) {
+      element.content = content
+    } else if (isDomRuntime()) {
+      const options: Record<string, string> = { content }
+
+      if (this.isProperty) {
+        options.property = name
+      } else {
+        options.name = name
+      }
+
+      createElement(document.head, 'meta', options)
+    }
+
+    return this
+  }
+
+  /**
+   * Converts meta tag to HTML string.
+   *
+   * Преобразует мета-тег в HTML-строку.
+   * @param name meta tag name / имя мета-тега
+   */
+  protected toHtmlString(name: Key): string {
+    const content = encodeAttribute(this.items[name] ?? '')
+
+    if (content) {
+      return `<meta ${this.getAttributeName()}="${name}" content="${content}">`
+    }
+
+    return ''
+  }
+
+  /**
+   * Updates meta tags data from the DOM.
+   *
+   * Обновляет данные мета-тегов из DOM.
+   */
+  protected update(): this {
+    this.listMeta.forEach((name) => {
+      this.items[name as any as Key] = this.findMetaElement(name)?.content ?? ''
+    })
+
+    return this
+  }
+}

package/src/classes/MetaOg.ts

@@ -0,0 +1,147 @@
+import { MetaManager } from './MetaManager'
+
+import { MetaOpenGraphTag, MetaOpenGraphType } from '../types/metaTypes'
+
+/**
+ * Class for working with Open Graph meta tags.
+ *
+ * Класс для управления мета-тегами Open Graph.
+ */
+export class MetaOg extends MetaManager<MetaOpenGraphTag[]> {
+  constructor() {
+    super(Object.values(MetaOpenGraphTag), true)
+  }
+
+  /**
+   * Gets the Open Graph title.
+   *
+   * Получает заголовок Open Graph.
+   */
+  getTitle(): string {
+    return this.get(MetaOpenGraphTag.title)
+  }
+
+  /**
+   * Gets the Open Graph type.
+   *
+   * Получает тип Open Graph.
+   */
+  getType(): MetaOpenGraphType {
+    return this.get(MetaOpenGraphTag.type) as MetaOpenGraphType
+  }
+
+  /**
+   * Gets the Open Graph URL.
+   *
+   * Получает URL Open Graph.
+   */
+  getUrl(): string {
+    return this.get(MetaOpenGraphTag.url)
+  }
+
+  /**
+   * Gets the Open Graph image URL.
+   *
+   * Получает URL изображения Open Graph.
+   */
+  getImage(): string {
+    return this.get(MetaOpenGraphTag.image)
+  }
+
+  /**
+   * Gets the Open Graph description.
+   *
+   * Получает описание Open Graph.
+   */
+  getDescription(): string {
+    return this.get(MetaOpenGraphTag.description)
+  }
+
+  /**
+   * Gets the Open Graph locale.
+   *
+   * Получает локаль Open Graph.
+   */
+  getLocale(): string {
+    return this.get(MetaOpenGraphTag.locale)
+  }
+
+  /**
+   * Gets the Open Graph site name.
+   *
+   * Получает название сайта Open Graph.
+   */
+  getSiteName(): string {
+    return this.get(MetaOpenGraphTag.siteName)
+  }
+
+  /**
+   * Sets the Open Graph title.
+   *
+   * Устанавливает заголовок Open Graph.
+   * @param title title / заголовок
+   */
+  setTitle(title: string): this {
+    return this.set(MetaOpenGraphTag.title, title)
+  }
+
+  /**
+   * Sets the Open Graph type.
+   *
+   * Устанавливает тип Open Graph.
+   * @param type type / тип
+   */
+  setType(type: MetaOpenGraphType): this {
+    return this.set(MetaOpenGraphTag.type, type)
+  }
+
+  /**
+   * Sets the Open Graph URL.
+   *
+   * Устанавливает URL Open Graph.
+   * @param url URL / URL
+   */
+  setUrl(url: string): this {
+    return this.set(MetaOpenGraphTag.url, url)
+  }
+
+  /**
+   * Sets the Open Graph image URL.
+   *
+   * Устанавливает URL изображения Open Graph.
+   * @param url image URL / URL изображения
+   */
+  setImage(url: string): this {
+    return this.set(MetaOpenGraphTag.image, url)
+  }
+
+  /**
+   * Sets the Open Graph description.
+   *
+   * Устанавливает описание Open Graph.
+   * @param description description / описание
+   */
+  setDescription(description: string): this {
+    return this.set(MetaOpenGraphTag.description, description)
+  }
+
+  /**
+   * Sets the Open Graph locale.
+   *
+   * Устанавливает локаль Open Graph.
+   * @param locale locale (e.g. 'en_US', 'ru_RU') / локаль (например, 'en_US', 'ru_RU')
+   */
+  setLocale(locale: string): this {
+    return this.set(MetaOpenGraphTag.locale, locale)
+  }
+
+  /**
+   * Sets the Open Graph site name.
+   *
+   * Устанавливает название сайта Open Graph.
+   * @param siteName site name / название сайта
+   */
+  setSiteName(siteName: string) {
+    return this.set(MetaOpenGraphTag.siteName, siteName)
+  }
+}