Utilities and helpers for Brazen user scripts framework
This script should not be not be installed directly. It is a library for other scripts to include with the meta directive // @require https://update.greasyfork.org/scripts/375557/1875053/Brazen%20Framework%20-%20Utilities.js
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 framework modules (after jQuery).
sleep.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)
ChildObserverWhat it does: A fluent wrapper over MutationObserver for childList add/remove events on a single target node.
Typical use cases:
How it works (developer-relevant):
observe(node)).APIs:
ChildObserver.create() → factoryobserve(node) → attach to a NodeonNodesAdded(handler) / onNodesRemoved(handler) → (nodes, previousSibling, nextSibling, target) => voidpauseObservation() / resumeObservation()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.
LocalStore (localStorage)What it does: A localStorage wrapper for JSON blobs with default values, change callbacks, and a nested-object serialization mode used by some parts of the stack.
Typical use cases:
Quick recipe:
const store = new LocalStore('myapp-cache', { seen: [] })
const data = store.get()
data.seen.push('abc')
store.save(data)
APIs:
new LocalStore(key, defaultsObject)get() → object; if missing/empty, writes defaults via restoreDefaults()save(data) / delete()restoreDefaults() / wereDefaultsSet()onChange(handler) → (storeObject) => voidNested-object mode: If stored JSON includes top-level arrays, objects, and properties keys, get() uses Utilities.objectFromJSON to round-trip nested arrays/objects in a stable way. Plain JSON objects are returned as-is.
StorageDriver, LocalStorageDriver, GmStorageDriver, DriverStoreWhat it does: A small driver interface used by the Configuration Manager to persist settings to either localStorage (local) or Tampermonkey GM value storage (gm).
Typical use cases:
field.attachStorage('gm')).Concepts:
LocalStore, but backend-agnostic).Constants:
STORAGE_DRIVER_LOCAL = 'local'STORAGE_DRIVER_GM = 'gm'APIs (mostly framework-internal):
StorageDriver (abstract): read, write, remove, readStore, writeStoreLocalStorageDriver / GmStorageDriverDriverStore (aggregate settings wrapper)SelectorGeneratorWhat 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:
APIs:
new SelectorGenerator(selectorPrefix) (typically your scriptPrefix)getSelector(selector) → prefix + selectorgetSettingsInputSelector(settingName) → {prefix}{kebab-name}-settinggetSettingsRangeInputSelector(name, getMin) → {prefix}{kebab-name}-min-setting / -max-settinggetStatLabelSelector(statisticType) → element id used by stat labelsStatisticsRecorderWhat it does: Tracks how many items were removed (failed validation) per filter and updates matching DOM stat labels.
Typical use cases:
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()ComplianceRuleRecorderWhat 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 }] }]Utilities (static)What it does: A grab-bag of small utilities the framework stack depends on.
Commonly used APIs:
sleep(ms) → Promise-based delaytoKebabCase(text) → used for tab ids and config keystrimAndKeepNonEmptyStrings(strings[])buildWholeWordMatchingRegex(words[]) → used by blacklist filterscallEventHandler, callEventHandlerOrFail, processEventHandlerQueuegenerateId(prefix?)objectToJSON(object) / objectFromJSON(json)Example:
await Utilities.sleep(500)
const pattern = Utilities.buildWholeWordMatchingRegex(['foo', 'bar'])
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)doesChildExist, isChildMissingsanitizeTextNode, sanitizeNodeOfSelectoriFramesRemover() → injects iframe { display: none !important; } (requires style injection grant)REGEX_LINE_BREAK, REGEX_PRESERVE_NUMBERS, STORAGE_DRIVER_LOCAL, STORAGE_DRIVER_GMChildObserver, LocalStore, StorageDriver, LocalStorageDriver, GmStorageDriver, DriverStore, SelectorGenerator, StatisticsRecorder, ComplianceRuleRecorderUtilities.*, Validator.*GM_addStyle, GM_download, GM_getValue, GM_setValue, etc. on the application script as needed.