Brazen Framework - Tag Query Engine

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

Script này sẽ không được không được cài đặt trực tiếp. Nó là một thư viện cho các script khác để bao gồm các chỉ thị meta // @require https://update.greasyfork.org/scripts/583965/1880215/Brazen%20Framework%20-%20Tag%20Query%20Engine.js

Đặt câu hỏi, đăng đánh giá, hoặc báo cáo tập lệnh.

Tác giả: brazenvoid
Phiên bản: 1.1.0
Đã tạo: 22-06-2026
Đã cập nhật: 19-07-2026
Kích thước: 7 KB
Giấy phép: 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