☰

Brazen Framework - Utilities

Utilities and helpers for Brazen user scripts framework

이 스크립트는 직접 설치하는 용도가 아닙니다. 다른 스크립트에서 메타 지시문 // @require https://update.greasyfork.org/scripts/375557/1884361/Brazen%20Framework%20-%20Utilities.js을(를) 사용하여 포함하는 라이브러리입니다.

설치 방법

이 스크립트를 설치하려면 Tampermonkey, Greasemonkey 또는 Violentmonkey와 같은 확장 프로그램이 필요합니다.

이 스크립트를 설치하려면 Tampermonkey와 같은 확장 프로그램을 설치해야 합니다.

이 스크립트를 설치하려면 Tampermonkey 또는 Violentmonkey와 같은 확장 프로그램이 필요합니다.

이 스크립트를 설치하려면 Tampermonkey 또는 Userscripts와 같은 확장 프로그램이 필요합니다.

이 스크립트를 설치하려면 Tampermonkey와 같은 확장 프로그램이 필요합니다.

이 스크립트를 설치하려면 유저 스크립트 관리자 확장 프로그램이 필요합니다.

(이미 유저 스크립트 관리자가 설치되어 있습니다. 설치를 진행합니다!)

설치 방법

이 스타일을 설치하려면 Stylus와 같은 확장 프로그램이 필요합니다.

이 스타일을 설치하려면 Stylus와 같은 확장 프로그램이 필요합니다.

이 스타일을 설치하려면 Stylus와 같은 확장 프로그램이 필요합니다.

이 스타일을 설치하려면 유저 스타일 관리자 확장 프로그램이 필요합니다.

이 스타일을 설치하려면 유저 스타일 관리자 확장 프로그램이 필요합니다.

이 스타일을 설치하려면 유저 스타일 관리자 확장 프로그램이 필요합니다.

(이미 유저 스타일 관리자가 설치되어 있습니다. 설치를 진행합니다!)

작성자
brazenvoid
버전
5.1.1
생성일
2018-12-15
갱신일
2026-07-24
크기
18.5KB
라이선스
GPL-3.0-only

Brazen Framework — Utilities (developer guide)

Foundation module: small, site-agnostic building blocks used by the Brazen Framework stack. As a script author, you’ll mostly touch these through BrazenFramework helpers and through other modules (Configuration Manager, View Layer), not by treating Utilities as a standalone layer.

Greasy Fork: Utilities · Loads first among Brazen Framework modules.

When to use / when not to use

  • Use this module when you need one of the framework’s shared primitives: DOM mutation watching, storage wrappers, selector/id generation, statistics labels, validation helpers, or tiny async helpers like sleep.
  • Don’t use this module to build UI or settings schemas — that belongs to the View Layer and Configuration Manager.

Quick start

These are the two most common “surface-level” utilities you’ll see in app code that extends BrazenFramework:

// Watch a list for new nodes (useful outside the main compliance pipeline).
ChildObserver.create()
  .onNodesAdded((nodes) => {
    // nodes: Node[]
  })
  .observe(document.querySelector('#results'))

// Throttle or delay between operations.
await Utilities.sleep(250)

Features

DOM observation: ChildObserver

What it does: A fluent wrapper over MutationObserver for childList add/remove events on a single target node.

Typical use cases:

  • Watching a site widget that’s unrelated to item compliance (e.g. a sidebar that updates via AJAX).
  • Running a one-off enhancement when new rows/cards are appended.

How it works (developer-relevant):

  • Observes one node at a time (observe(node)); re-observe disconnects any prior MutationObserver first.
  • Provides separate callbacks for added vs removed nodes.
  • You can pause/resume without rebuilding the observer.

APIs:

  • ChildObserver.create() → factory
  • observe(node) → attach to a Node
  • onNodesAdded(handler) / onNodesRemoved(handler) → (nodes, previousSibling, nextSibling, target) => void
  • pauseObservation() / resumeObservation()
  • disconnect() — permanent teardown (drops the MutationObserver handle)

Notes: The framework itself uses ChildObserver on each itemListSelectors entry so infinite scroll and AJAX lists get compliance automatically. Use it directly only when you’re doing DOM work outside that pipeline.

Stable ids/selectors: SelectorGenerator

What it does: Generates prefixed element ids/selectors from human-readable names. The rest of the stack uses this to keep UI ids stable and script-scoped.

Typical use cases:

  • When you need to create your own DOM nodes but still want to align with the stack’s id conventions.

APIs:

  • new SelectorGenerator(selectorPrefix) (typically your scriptPrefix)
  • getSelector(selector) → prefix + selector
  • getSettingsInputSelector(settingName) → {prefix}{kebab-name}-setting
  • getSettingsRangeInputSelector(name, getMin) → {prefix}{kebab-name}-min-setting / -max-setting
  • getStatLabelSelector(statisticType) → element id used by stat labels

Filter removal counts: StatisticsRecorder

What it does: Tracks how many items were removed (failed validation) per filter and updates matching DOM stat labels.

Typical use cases:

  • You usually get this via the framework, but direct use is straightforward when building custom hide/show logic.

Key behavior: record(type, validationResult) increments counters only when validationResult is falsy (i.e. the item failed a filter).

APIs:

  • new StatisticsRecorder(selectorPrefix)
  • record(statisticType, validationResult, value = 1)
  • getTotal(), reset(), updateUI()

Per-rule hide diagnostics: ComplianceRuleRecorder

What it does: When enabled (via framework trackComplianceRules: true), records “which rule caused hides” so the UI can display a breakdown.

APIs:

  • record(configKey, ruleLabel, count = 1)
  • reset()
  • getReport(resolveFilterLabel?) → [{ filterKey, filterLabel, rules: [{ label, count }] }]

Small general helpers: Utilities (static)

What it does: A grab-bag of small utilities the framework stack depends on.

Commonly used APIs:

  • makeEl(tag, opts?) → HTMLElement factory (class, attrs, text/html, dataset, on, children, hidden)
  • appendChildren(parent, children) → append a node or array (skips nullish); prefer over Element.append when children may be an array
  • setHidden(el, hidden) → toggles .bv-hidden + hidden (survives CSS display:!important)
  • sleep(ms) → Promise-based delay
  • toKebabCase(text) → used for tab ids and config keys
  • decodeHtmlEntities(text) → shared HTML-entity decode for path/tag strings from the DOM
  • trimAndKeepNonEmptyStrings(strings[])
  • buildWholeWordMatchingRegex(words[]) → used by blacklist filters
  • callEventHandler, callEventHandlerOrFail, processEventHandlerQueue
  • generateId(prefix?)
  • objectFromJSON(json) — revive Tampermonkey clone trees ({arrays, objects, properties}) during legacy GM import

Example:

await Utilities.sleep(500)
const pattern = Utilities.buildWholeWordMatchingRegex(['foo', 'bar'])
const row = Utilities.makeEl('div', {
  class: 'bv-group',
  children: [Utilities.makeEl('span', {text: 'Label'})],
})
Utilities.setHidden(row, true)

Validation & sanitization helpers: Validator (static)

What it does: Common validation and sanitization helpers used by range filters, tag/text rules, and text normalization.

Commonly used APIs:

  • isInRange(value, lower, upper) → inclusive bounds; supports “only min” or “only max”
  • sanitize(text, rules) → apply regex replacements then trim()
  • regexMatches(text, rules) / validateTextDoesNotContain(text, rules)
  • DOM helpers: doesChildExist(parent, selector), isChildMissing(parent, selector) — parent is HTMLElement / ParentNode (native querySelector)
  • Title/text helpers: sanitizeTextNode(textNode, rules), sanitizeNodeOfSelector(selector, rules) — sanitizeNodeOfSelector uses document.querySelector
  • iFramesRemover() → injects iframe { display: none !important; } (requires style injection grant)

Public API reference (index)

  • Constants: REGEX_LINE_BREAK, REGEX_PRESERVE_NUMBERS
  • Classes: ChildObserver, SelectorGenerator, StatisticsRecorder, ComplianceRuleRecorder
  • Statics: Utilities.makeEl, Utilities.appendChildren, Utilities.setHidden, Utilities.*, Validator.*

Removed in v5.0.0: LocalStore, storage drivers — persistence is IndexedDB via Configuration Manager; legacy import helpers are in IndexedDB Storage.

Integration notes (grants, load order, pitfalls)

  • Grants: this module declares no Tampermonkey grants. Put GM_addStyle, GM_download, GM_getValue, GM_setValue, etc. on the application script as needed.
  • Load order: load first among Brazen modules (before View Layer and the rest of the stack).
  • Next in stack: View Layer