Brazen Framework - Tag Query Engine

Tokenize, merge, and subtract space-separated booru tag queries

このスクリプトは単体で利用できません。右のようなメタデータを含むスクリプトから、ライブラリとして読み込まれます: // @require https://update.greasyfork.org/scripts/583965/1880215/Brazen%20Framework%20-%20Tag%20Query%20Engine.js

このスクリプトの質問や評価の投稿はこちら、通報はこちらへお寄せください

作者: brazenvoid
バージョン: 1.1.0
作成日: 2026/06/22
更新日: 2026/07/19
大きさ: 7.33KB
ライセンス: GPL-3.0-only

Brazen Framework — Tag Query Engine (developer guide)

Optional. Core algorithms for sites where the whole search query is one space-separated string (Gelbooru-style tags=, Shimmie path segments, etc.): tokenize with parenthesis-aware OR-groups, merge default filters idempotently, subtract defaults for display.

Also includes site-family adapters as separate classes in the same Greasy Fork script (today: GelbooruFamilySearchAdapter). Future API drivers stay as separate classes here — do not fold them into the engine.

Greasy Fork: 583965 · Requires: Utilities · @require after Configuration Manager (and other required core modules), before Framework core.

When to use / when not to use

Idiom	Example	This module
Single param / path carries full query	`?tags=catgirl -gore sort:score:desc`	Yes — `tokenize` / `merge` / `subtract` + a family adapter
Distinct form params per filter	e-hentai `f_srdd`, `f_spf`	No — use framework togglable-operation helpers only

Pair the engine with a search adapter that implements read/write/serialize for your site's wire format. See the workspace search-augmentation and search-defaults-injection pattern specs.

Quick start (defaults injection loop guard)

const adapter = new GelbooruFamilySearchAdapter()
const defaults = ['sort:score:desc', 'rating:explicit']

const current = adapter.readQuery()
const mergedTokens = adapter.engine.merge(current, defaults)
const merged = mergedTokens.join(' ')

if (merged !== adapter.engine.tokenize(current).join(' ')) {
  location.href = adapter.buildListUrl(merged)
}

Or use the engine alone:

const engine = new BrazenTagQueryEngine({
  singleInstanceKeys: new Set(['sort', 'rating', 'width', 'height']),
})

Features

Tokenization (parenthesis-aware OR groups)

What it does: Splits a query string on whitespace, but treats balanced parenthesis groups ( ... ) as a single token.

Idempotent merging (default injection)

What it does: merge(userQuery, defaultTokens) appends default tokens after user tokens while skipping exact duplicates, respecting singleInstanceKeys, and remaining idempotent.

Subtraction (displaying the user-only query)

What it does: subtract(tokens, defaultTokens) removes exact default tokens for “display mode”.

Class: `BrazenTagQueryEngine`

Constructor: new BrazenTagQueryEngine(options?)

Option	Default	Role
`singleInstanceKeys`	`new Set()`	Metatag keys that accept at most one token per query
`metatagKey`	`BrazenTagQueryEngine.defaultMetatagKey`	`(token) => string \

Static: `defaultMetatagKey(token)`

Returns the substring before the first : for metatag tokens; ignores a leading -. Returns null when the token is a plain tag or starts with (.

Instance methods

Method	Returns	Description
`tokenize(query)`	`string[]`	Split on whitespace; keep `( … )` groups as single tokens
`metatagKey(token)`	`string \	null`
`merge(userQuery, defaultTokens)`	`string[]`	Append defaults; skip single-instance conflicts and duplicates. Idempotent
`subtract(tokens, defaultTokens)`	`string[]`	Remove exact default tokens

Adapters

Site-specific URL shapes, empty-query sentinels, and atom normalization live in adapter classes in this module (not in the engine). Add future drivers (e.g. Shimmie) as additional classes here.

Module constant: `GELBOORU_SINGLE_INSTANCE_METATAGS`

Default Set for Gelbooru-family: sort, rating, user, md5, parent, aspectratio, aspectratiof, sourcedomains, width, height.

Class: `GelbooruFamilySearchAdapter`

Gelbooru 0.2 HTML list search adapter. Per-host variants override constructor options.

Constructor: new GelbooruFamilySearchAdapter(options?)

Option	Default	Role
`queryParam`	`'tags'`	URL search param name
`emptySentinels`	`['all']`	Token sequences treated as empty user query
`listPath`	`'/index.php?page=post&s=list'`	Path before `&{queryParam}=`
`singleInstanceKeys`	`GELBOORU_SINGLE_INSTANCE_METATAGS`	Passed to internal `BrazenTagQueryEngine`

Property: engine — BrazenTagQueryEngine sharing singleInstanceKeys.

Method	Returns	Description
`readQuery(locationRef?)`	`string`	Normalized `queryParam` from location
`normalizeQueryParam(tags)`	`string`	`''` for empty sentinels; else original
`serializeQuery(tokens)`	`string`	`tokens.join(' ')`
`buildListUrl(serialized, origin?)`	`string`	List URL with encoded query
`normalizeAtom(tag)`	`string`	Spaces → `_`; preserve metatags; recurse OR-groups; honor `-`

Design notes

OR-groups — ( a ~ b ) is one token; never split on spaces inside balanced parentheses.
Single-instance keys — adapters supply keys per site family.
Subtract edge — exact-token match.

Public API reference (index)

Engine: new BrazenTagQueryEngine(options?), defaultMetatagKey, tokenize, metatagKey, merge, subtract
Gelbooru adapter: GELBOORU_SINGLE_INSTANCE_METATAGS, new GelbooruFamilySearchAdapter(options?), readQuery, normalizeQueryParam, serializeQuery, buildListUrl, normalizeAtom

Grants and load order

This module declares no Tampermonkey grants.

@run-at document-end

Next in stack: optional Paginator / Subscriptions Loader → Framework core