-
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathllms.txt
More file actions
244 lines (159 loc) · 40.4 KB
/
Copy pathllms.txt
File metadata and controls
244 lines (159 loc) · 40.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# bQuery.js
> The full-stack web framework that speaks jQuery.
> Compact repo summary for context-limited LLMs. If this file drifts, trust `package.json`, `src/*/index.ts`, and `AGENT.md` in that order.
bQuery.js is a batteries-included TypeScript framework for the modern web — reactive signals, zero-build worker tasks, Web Components, routing, state, forms, SSR, server helpers, and more — with a jQuery-inspired API, security-by-default HTML sanitization, and zero mandatory build step — or your preferred bundler.
## Package
- npm: `@bquery/bquery`
- Version: 1.17.2
- License: MIT
- Repository: https://github.com/bQuery/bQuery
- Homepage: https://bquery.js.org
- Runtime: Browser (ESM, UMD, IIFE) · Node.js >=24.0.0 · Bun >=1.4.0 · Deno (SSR adapters)
- Build: Bun + Vite + TypeScript (strict)
- Tests: Bun test runner with happy-dom
- Supported engines: Node.js `>=24.0.0`, Bun `>=1.4.0`
## Version 1.17.2 Highlights
- Security patch that closes cookie tossing for the CSRF and session cookies. No API removals, no module status transitions. `csrf()` names its cookie `__Host-bq.csrf` whenever the attributes allow it (`Secure`, `Path=/`, no `Domain`: the defaults), so a sibling subdomain or a network attacker can no longer plant or overwrite it; with `secure: false`, a custom `path` or a `domain` it stays `bq.csrf`, and an explicit `__Host-` `cookieName` with incompatible attributes throws at startup. `session()` likewise names its cookie `__Host-bq.sid` (fallback `bq.sid`), and both throw at startup for a `__Host-`/`__Secure-` `cookieName` that its attributes violate, or whose prefix is mis-cased (older browsers only enforce the exact spelling). Behaviour changes: client code that reads the CSRF cookie directly must use `__Host-bq.csrf` or pass `cookieName: 'bq.csrf'`; users are logged out once because the session cookie name changes (pass `cookieName: 'bq.sid'` to keep existing sessions for a transition period; like the `bq.sid` fallback, that name has no `__Host-` protection, so a sibling subdomain can plant a session id again).
## Version 1.17.1 Highlights
- Security-and-correctness patch closing a full-codebase audit of 1.17.0. No API removals, no module status transitions. Security: `serveStatic({ precompressed: true })` applies the `realpath` containment check to `.br`/`.gz` sidecars; the Node adapter (`createNodeHandler`, `listen({ runtime: 'node' })`) answers handler errors with `500` instead of crashing the process via an unhandled rejection, aborts `request.signal` and cancels the response stream on client disconnect; signed `csrf({ secret })` tokens live in the server-side session when `session()` runs first, bound to the session id and rotated on `$regenerate()` (`bindToSession: false` opts out).
- Fixes: `deepEqual`/`isEqual` no longer equate different built-in kinds; router `route.params` are percent-decoded and encoded static segments match (client and server); `css()` accepts camelCase names; `toggle()` shows `[hidden]` elements and `hide()`/`show()` keep the inline `display`; `http` honours an already-aborted `signal` with `timeout` and `listen({ signal })` rejects when aborted; `email()` is linear-time; component render, `createTemplate()` and the DOM sanitizer work under an enforced Trusted Types CSP; `memoryStore()` sweeps expired sessions, evicts LRU, and the default session store is capped at 10 000 entries.
## Version 1.17.0 Highlights
- Feature release for `server` and `security`, plus the packaging fixes that make the published tarball resolve correctly. One path break: `dist/full.umd.js` is now `dist/full.umd.cjs` and the CDN fields point at `dist/full.iife.js`, so a pinned `full.umd.js` URL 404s. Package specifiers are unaffected.
- `@bquery/bquery/server` — `serveStatic({ root, prefix, maxAge, immutable, index })` serves files from disk with weak `ETag`/`Last-Modified` and `304`, `Range` with `206`/`416`, directory indexes, content-type mapping, optional `.br`/`.gz` sidecars, and traversal rejection that re-checks the `realpath` so a symlink out of `root` cannot escape. `rateLimit({ window, max, keyBy, store })` does fixed-window throttling over the same `SessionStore` sessions use, with `RateLimit-*` headers and `429` + `Retry-After`. `keyBy` is **required**: `ServerContext` exposes no peer address, so the only "client address" available is `X-Forwarded-For`, which the client sets unless a proxy overwrites it — `trustProxy: true` opts into that explicitly.
- `@bquery/bquery/security` — `sanitizeHtml()` and `stripTags()` work without a DOM; they previously threw `ReferenceError: document is not defined` on Bun, Node and Deno. A string backend is selected automatically when no DOM is present, and `configureSanitizer({ backend: 'auto' | 'dom' | 'string' })` / `getSanitizerConfig()` pin it. Both backends share one policy module, so allow lists and URL checks cannot drift; they can differ on malformed input, where the string backend escapes rather than guesses. `./security` grows from 2.8 kB to 4.5 kB gzipped because both backends ship — the choice is made at runtime, so bundling cannot drop the unused one.
- `@bquery/bquery/reactive` — `configureReactive({ scheduler: 'sync' | 'batched' })`, `getReactiveConfig()` and `flushSync()`; `'sync'` stays the default for all of 1.x. A flush now settles every derived value before running any effect, which fixes effects observing a fresh computed beside a stale one. **This ordering change applies to explicit `batch()` under the default scheduler too.**
- `@bquery/bquery/server` — global middleware registered with `app.use()` now runs for requests that match no route, with `notFound` as the end of the chain. Previously an unmatched path returned 404 before the middleware stack ran at all, so CORS, logging, security headers and static-asset serving were skipped on exactly those responses.
## Version 1.16.1 Highlights
- Toolchain-and-build maintenance patch. Nothing under `src/` changed: no API changes, no breaking changes, no module status transitions — every 1.16.0 API behaves identically.
- Supported Bun floor moves from `1.3.13` to `1.4.0` (`engines.bun`), mirrored in `mise.toml`, the runtime support matrix, the AI guidance files, and the bug-report template. Node.js stays at `>=24.0.0`. CI installs `bun-version: 'latest'`; the SSR cross-runtime matrix leg `bun-1.3` is now `bun-1.4`.
- Build: `vite.config.ts` and `vite.umd.config.ts` use `import.meta.dirname` instead of `__dirname` (compatible with Vite's `configLoader: 'native'`), and the UMD/IIFE build stubs `node:*` with a throwing module so the unreachable `node:http` import in `createServer().listen()` no longer triggers Vite's browser-externalized warning. Bundle contents unchanged.
- Dev dependencies refreshed: Storybook `10.5.10`, `@typescript-eslint/*` `8.68.0`, `bun-types` `1.4.0`, `eslint` `10.9.1`, `globals` `17.11.0`, `happy-dom` `20.11.6`, `vite` `8.2.2`. Still zero runtime dependencies.
## Version 1.16.0 Highlights
- Quality-and-performance release driven by a full audit of the reactive core, DOM core, and view layer. No breaking changes, no module status transitions; the only new API is the additive `trailing` option on `watchThrottle` (`WatchThrottleOptions`).
- `@bquery/bquery/reactive` — `batch()` coalesces transitive updates (diamond dependencies trigger their effect once per batch); computeds re-validate and notify subscribers only when their value actually changes; hot-path allocation cuts on signal writes and dependency tracking; a throwing `computed` stays dirty and retries instead of serving a stale cache.
- `@bquery/bquery/core` — `undelegate()` works across wrapper instances (module-level delegation registry; `delegate()` is idempotent per handler tuple); `wrap()` no longer clones previously wrapped elements into later wrappers; `replaceWith(string)` sanitizes once per call; `empty()` uses `replaceChildren()`; `children()`/`siblings()`/`index()`/`unwrap()`/`css(object)`/`data()` shed per-element allocations.
- `@bquery/bquery/view` — per-update work moved to bind time (object-expression parsing, transition resolution, memoized directive parsing, sandbox proxies cached per context); unchanged DOM writes are skipped (fixes the `bq-model` caret reset); `bq-for` is dispatched before other directives on the same element; `bq-once`/`bq-memo`/`bq-init` evaluate untracked; `bq-html` children are no longer directive-bound. The `with`-scope evaluator hardening closes a residual member-access escape via `hasDangerousMemberAccess()`, and the compiler rejects legacy leading-zero numeric literals.
- `@bquery/bquery/motion` — `onReducedMotionChange` re-binds to the current `window.matchMedia` on subscribe and flushes preference changes that happened without a `change` event. `@bquery/bquery/store` — `deepClone` special-cases only the dangerous `__proto__` key; properties merely named `constructor`/`prototype` are copied normally again.
- Local validation and publish checks target Node.js `>=24.0.0` and Bun `>=1.4.0`; whenever release metadata or AI guidance changes, `bun run check:ai-guidance` should pass before you stop.
## Version 1.15.1 Highlights
- Security-and-correctness patch closing a full-codebase audit — no breaking changes, no module status transitions. XSS hardening across every HTML sink (mutation-XSS fallback escaped, `bq-text` raw-text escaping in SSR, shared `bq-bind` attribute guard), evaluator code-execution paths closed (client `with`-scope denylist, CSP-safe SSR parser), Trusted Types wired in via the new `trustedHtmlForSink()` (`@bquery/bquery/security`), secure-by-default session/CSRF cookies.
- Additive APIs introduced by the fixes: `effectScope(detached?)` (`@bquery/bquery/reactive`) and a `dispose()` method on `deferred()`'s handle.
## Version 1.15.0 Highlights
- Thirteen modules graduate to **Stable** — `@bquery/bquery/view`, `@bquery/bquery/forms`, `@bquery/bquery/i18n`, `@bquery/bquery/a11y`, `@bquery/bquery/dnd`, `@bquery/bquery/media`, `@bquery/bquery/plugin`, `@bquery/bquery/devtools`, `@bquery/bquery/testing`, `@bquery/bquery/storybook`, `@bquery/bquery/concurrency`, `@bquery/bquery/ssr`, and `@bquery/bquery/server`. Every bQuery module is now Stable (the Beta and Experimental tiers are empty); the canonical record is `STABILITY.md`, enforced by `bun run check:stability`.
- `@bquery/bquery/view` — declarative enter/leave/move transitions (`bq-transition`, `bq-in`, `bq-out`, `bq-transition-duration`, `bq-transition-easing`, `bq-animate="flip"`) plus an optional `@bquery/bquery/view/compiler` (`compileViews`, `compileToModule`, `compileExpression`, `emitModule`, the `bquery-view-compile` CLI, and `registerCompiledExpressions`/`clearCompiledExpressions` runtime hooks) that precompiles `bq-*` expressions into `with`-free functions, so the runtime can skip the `new Function()` evaluator and run under a strict CSP without `'unsafe-eval'`. Un-compilable expressions fall back to the runtime evaluator.
- `@bquery/bquery/forms` — progressive-enhancement actions (`formAction`, `useFormStatus`, `enhance`, `FormActionError`) and an `optimistic(base, reducer)` update primitive; `createFieldArray()` gains `getKey` plus `keys()`/`keyAt(index)`. Composes with the `server` module's `csrf()`.
- `@bquery/bquery/i18n` — ICU MessageFormat (`plural`, `selectordinal`, `select`, nested arguments, `offset:`, `=N`, `#`) via `Intl.PluralRules`; new `defineMessages`/`formatMessage`; and an optional, dependency-free `@bquery/bquery/i18n/extract` toolkit + `bquery-i18n` CLI that scans source and merges catalogs without overwriting translations.
- `@bquery/bquery/router` + `@bquery/bquery/server` — an opt-in, bundler-agnostic file-route convention with typed `load`/`action`: `createFileRoutes`, `parseFilePath`, `filePathToRoutePattern`, `sortEntriesBySpecificity`, `createRouteData`/`useRouteData`, plus `mountFileRoutes`/`createFileRouteServerRoutes`. `routes/users/[id]/+page.ts` → `/users/:id`, `[...rest]` → `*`, `(group)` dropped. Programmatic routing is unchanged; no bundler is shipped.
- `@bquery/bquery/server` — first-party `session`/`memoryStore`, `csrf`/`csrfToken`, `guard`, `basicAuth`/`bearerAuth`, and the Web-Crypto signing utilities they build on (`signValue`, `unsignValue`, `timingSafeEqual`, `randomToken`, `randomId`); `app.listen()` supports Node, Bun, and Deno.
- `@bquery/bquery/ssr` — production hydration (`hydrate`, `detectHydrationMismatches`), interactive directive parity (`directives: 'full'`, `onUnsupportedDirective`), and resumable boundaries (`createResumableBoundary`, `createResumableGraph`, `resume`). `renderToStringAsync()` and the rest of the SSR surface are unchanged.
- `@bquery/bquery/devtools` — a stable, versioned bridge protocol (`connectDevtoolsBridge`, `createBridgeServer`, `serializeComponentTree`, `BRIDGE_PROTOCOL_VERSION`/`BRIDGE_SOURCE`/`BRIDGE_CAPABILITIES`) and a Manifest V3 browser extension (component tree, signal/store inspection, timeline) released separately from <https://github.com/bQuery/devtools-extension>. `@bquery/bquery/a11y` stamps each `AuditFinding` with a `wcag` criterion and exports the `auditRules` catalog; `@bquery/bquery/plugin` adds the `definePlugin()` authoring helper.
- All graduations are additive — there are no breaking changes. Local validation and publish checks target Node.js `>=24.0.0` and Bun `>=1.4.0`; whenever release metadata or AI guidance changes, `bun run check:ai-guidance` should pass before you stop.
## Version 1.14.2 Highlights
- Dev-dependency maintenance release — no public API changes. Toolchain packages (TypeScript-ESLint, ESLint, Vite, globals) and the Bun runtime were updated to their latest versions; Dependabot was added for automated future dependency updates.
## Version 1.14.1 Highlights
- Motion: `prefersReducedMotion()` and `reducedMotionSignal()` now refresh their cached reduced-motion media query when `window.matchMedia` changes, preventing stale preference reads in tests and other runtimes that swap the media-query implementation.
## Version 1.14.0 Highlights
- Media: `@bquery/bquery/media` becomes batteries-included with 25+ new reactive composables — preferences (`usePreferredColorScheme`, `usePreferredContrast`, `usePreferredReducedTransparency`, `usePreferredLanguage`, `usePreferredLanguages`); page state (`useOnlineStatus`, `usePageVisibility`, `useDocumentFocus`, `useWindowFocus`, `useIdle`); element observers (`useElementSize`, `useElementBounding`, `useElementVisibility`, `useHover`, `useFocus`, `useFocusWithin`, `useActiveElement`); pointer/scroll (`usePointer`, `useScroll`); platform (`usePermission`, `useWakeLock`, `useShare`, `useShareSupported`, `useBroadcastChannel`, `useEventListener`, `useMediaDevices`, `useStorage`); plus clipboard upgrades (`isSupported`, `isImageSupported`, `readImage`, `writeImage`, `clipboardText`). All accept optional `{ signal: AbortSignal }` for auto-teardown.
- Plugin: `@bquery/bquery/plugin` gains a hook bus and DI — `addFilter`/`applyFilters`/`removeFilter`/`listFilters`, `addAction`/`doAction`/`removeAction`/`listActions`, `createInjectionKey`/`provide`/`inject`/`hasProvided`/`resetDi`, and `ctx.onCleanup` for plugin-scoped teardown. New `unuse(name)`/`uninstall(name)` detach plugin-owned directives, hooks, and DI bindings; `install()` may now return `void | Promise<void>` (concurrent installs of the same plugin are serialised). Plugin metadata (`version`, `description`, `dependencies`, `dependencyMode: 'error' | 'warn'`), `getPluginInfo(name)`, `getInstalledPlugins({ withMetadata: true })`, directive lifecycle objects (`{ mounted, unmounted }`), and namespaced directive names (`tooltip:arrow`).
- Devtools: `@bquery/bquery/devtools` gains ring-buffered timelines (`maxTimelineEntries`, default 1000), an expanded `TimelineEntry` with optional `payload`/`source`/`duration`, new event types (`signal:create`/`signal:dispose`/`effect:dispose`/`component:mount`/`component:unmount`/`component:render`/`route:guard`/`error:caught`/`measure`/`mark`), `filterTimeline({ types, since, until, search })`, `subscribeTimeline(listener)`, privacy-aware `inspectSignals({ includeValues: false })`, structural `diffSignals`/`diffStores`, `traceSignal`/`untraceSignal`, `inspectEffects`, snapshot import/export, `installBrowserBridge()`, and performance helpers (`time`, `measureRender`, `getPerformanceSummary`).
- Testing: `@bquery/bquery/testing` becomes batteries-included — auto cleanup (`cleanup`, `autoCleanup`), `fireEvent.click`/`.input`/`.change`/`.submit`/`.focus`/`.blur`/`.dblClick`/`.keyDown`/`.keyUp` shortcuts, a `userEvent` namespace (`click`, `dblClick`, `hover`, `unhover`, `type`, `clear`, `selectOptions`, `tab`, `paste`), shadow-DOM-aware screen queries via `screen`/`within(el)` with `getByRole`/`getByText`/`getByLabelText`/`getByPlaceholderText`/`getByTestId` + their `query*` and `find*` variants, reactive harnesses (`mockComputed`, `mockEffect`, `tick`, `nextTick`, `flushPromises`, `runScheduled`), module mocks (`mockStore`, `mockI18n`, `mockForm`, `mockFetch`, `mockWebSocket`), and snapshot/a11y helpers (`prettyDOM`, `getReactiveSummary`, `expectAccessible`).
- Additive 1.14.0 module expansions: `@bquery/bquery/router` (`NavigationResult`, `pushResult`/`replaceResult`, `beforeResolve`, `resolveRoute`, dynamic `addRoute`/`removeRoute`/`hasRoute`, `isReady()`, `lastNavigation`, `useNavigation()`); `@bquery/bquery/view` (`parseDirective`, `ParsedDirective`, new `bq-once`/`bq-init`/`bq-pre`/`bq-cloak`/`bq-html-safe`/`bq-memo`, full `bq-on` modifier system); `@bquery/bquery/a11y` (`createLiveRegion`, `keyboardUserSignal`, `focusVisible`, `prefersReducedTransparency`/`prefersReducedData`/`forcedColors`, `inert`/`scrollLock`/`autoFocus`); `@bquery/bquery/i18n` (`negotiateLocale`, `detectLocale`, `isRTL`, `formatRelativeTime`/`formatList`/`formatDisplayName`/`segment`); `@bquery/bquery/dnd` (programmatic handle APIs, `grid`/`delay`/`touchStartThreshold`/`keyboard`/`keyboardStep`, `'viewport'` bounds, reactive `useDraggable`/`useDroppable`/`useSortable`); `@bquery/bquery/storybook` (`classMap`/`styleMap`/`ifDefined`/`repeat`/`storyText`/`unsafeHtml`/`storySvg`); `@bquery/bquery/concurrency` (`withTransferables`, `createSharedBuffer`, RPC `maxInFlight`, pool priorities, `pause`/`resume`/`onIdle`, rolling reactive metrics); `@bquery/bquery/ssr` (`flushBoundary`, `createSSRCache`, `createSSRMetrics`, `createEdgeHandler`, cache-aware `renderToResponse`, multi-chunk `renderToStream`); `@bquery/bquery/server` (`ServerHttpError`, `ctx.body`/`ctx.cookies`/`ctx.setCookie`/`ctx.accepts`/`ctx.stream`/`ctx.sse`/`ctx.renderStream`/`ctx.renderResponse`, `app.listen()`).
- All earlier 1.13.0 / 1.12.0 / 1.11.0 / 1.10.0 / 1.9.0 public surface remains stable.
- Repo AI guidance stays aligned through `bun run check:ai-guidance`.
## Version 1.13.0 Highlights
- Forms: `@bquery/bquery/forms` is now batteries-included — many new validators (`integer`, `numeric`, `between`, `length`, `oneOf`, `notOneOf`, `arrayOf`, `requiredIf`, `requiredUnless`, `dateAfter`, `dateBefore`, `validDate`, `fileSize`, `fileType`) and combinators (`compose`, `all`, `not`, `withMessage`); enriched field/form state (`isValidating`, `isFocused`, `dirtySince`, `disabled`, `setValue`/`setError`/`clearError`, `submitCount`, `submitError`, `isPristine`, `touchAll`/`untouchAll`, `resetField`, `resetErrors`, `getDirtyValues`, `subscribe`, `validationStrategy`, `mode`); dynamic field arrays (`createFieldArray`); fluent `schema()` declaration; two-way DOM bindings (`bindField`, `bindForm`); scope-aware composables (`useForm`, `useField`, `useFieldArray`); and SSR helpers (`serializeFormState`, `readSerializedFormState`, `hydrateForm`).
- Component: `@bquery/bquery/component` adds `useSlot` / `hasSlot` / `slotText`, `useRef`, `useAsync`, `whenIdle`, `provide` / `inject` / `formContextKey`, additive `beforeUnmount` and `errorBoundary` hooks, instance-level `setProp` / `getProp` for non-string props, delegated event helpers (`on`, `onClick`, `onInput`, `onChange`, `onSubmit`, `bindDelegatedEvents`), a `css` tagged template with adoptable stylesheet support, and `keyedList` / `reconcileKeyed` for keyed list rendering.
- Motion: `@bquery/bquery/motion` adds the full Penner easing family plus `cubicBezier()`, `steps()`, `mix()`, `chain()`; `tween()` interpolation with full transport controls and `AbortSignal` support plus Promise-based `animateValue()`; `animate()` gains `signal` + `playbackRate`, and `animateTo()` builds keyframes from CSS records; `spring()` gains `.velocity()` / `.set()` plus `springVector()` and `wobbly`/`slow`/`molasses` presets; timelines gain labels, `reverse()`, `playbackRate()`, `repeat()`, `yoyo()`, `onUpdate()`, `progress()`; new `scrollProgress()`, `inView()`, `magnetic()`, `tilt()`, `shake()`, `pulse()`, `countUp()` primitives; richer `stagger()` (grid, axis, deterministic random); `onReducedMotionChange()` + `reducedMotionSignal()`.
- Core utilities: `@bquery/bquery/core` exposes a major `utils/` expansion — array helpers (`groupBy`, `keyBy`, `partition`, `zip`, `range`, `take`, `drop`, `sample`, `shuffle`, `uniqueBy`, `sortBy`, `intersection`, `difference`, `flattenDeep`, `move`, `chunkBy`), function helpers (`memoize`, `compose`, `pipe`, `curry`, `partial`, `retry`, plus richer `debounce`/`throttle` options + `.flush()`), object helpers (deep `get`/`set`/`has`, `mapValues`, `mapKeys`, `invert`, `deepEqual`/`isEqual`, deep `freeze`, `defaults`, typed `entriesTyped`/`keysTyped`), string helpers (`toSnakeCase`, `toPascalCase`, `toTitleCase`, `pad`/`padStart`/`padEnd`, `wordCount`, safe `template`, `stripHtml`, `randomString`, `lines`), number helpers (`round`, `roundTo`, `lerp`, `inverseLerp`, `mapRange`, `formatBytes`, `randomFloat`, `sum`, `average`, `median`, `degToRad`, `radToDeg`), misc helpers (`uuid`, `tryCatch`, `times`, `pollUntil`, `nextFrame`, `nextTick`), and extra type guards (`isError`, `isMap`, `isSet`, `isRegExp`, `isSymbol`, `isBigInt`, `isAsyncFunction`, `isIterable`, `isAsyncIterable`, `isNullish`, `isDefined`).
- All earlier 1.12.0 / 1.11.0 / 1.10.0 / 1.9.0 public surface remains stable.
- Repo AI guidance stays aligned through `bun run check:ai-guidance`.
## Version 1.12.0 Highlights
- Store: `@bquery/bquery/store` now includes `unregisterPlugin()` and `clearPlugins()` for plugin teardown, test isolation, and runtime plugin reloads while preserving already-created stores.
- Reactive: `WebSocketSendData` is now a public type-only export from `@bquery/bquery/reactive`, matching native WebSocket payloads and the server-side `ServerWebSocketData` union.
- Full bundle / tooling: `/full` now mirrors public platform, a11y, and media type-only exports, and `bun run check:full-bundle` validates runtime + type export drift statically.
- Existing `1.11.0`, `1.10.0`, and `1.9.0` additions — server/SSR runtime helpers, concurrency RPC/pool helpers, `watchDebounce()` / `watchThrottle()`, `bq-error` / `bq-aria`, and media observer composables — remain part of the current public surface.
- Repo AI guidance stays aligned through `bun run check:ai-guidance`, which validates the release/version metadata across the shared AI-facing files.
## Maturity
- **Stable**: Core, Reactive, Security, Component, Motion, Platform, Router, Store
- **Stable (graduated in 1.15.0)**: View, Forms, i18n, A11y, DnD, Media, Plugin, Devtools, Testing, Storybook, Concurrency, SSR, Server
- **Beta / Experimental**: none — every module is Stable as of 1.15.0
## Modules
bQuery is a batteries-included framework with modular entry points — import only what you need, or use the full bundle:
### Core (`@bquery/bquery/core`)
DOM selection, manipulation, events, utilities. `$()` selects one element (throws if missing), `$$()` selects multiple (never throws). Both return chainable wrapper objects (`BQueryElement` / `BQueryCollection`) with jQuery-style methods: `addClass`, `removeClass`, `css`, `attr`, `text`, `html`, `on`, `off`, `trigger`, `find`, `closest`, `append`, `prepend`, `wrap`, `unwrap`, `delegate`, `serialize`, `scrollTo`. Also exports a deep utility surface under `utils/`: array (`chunk`, `groupBy`, `keyBy`, `partition`, `zip`, `range`, `take`, `drop`, `sample`, `shuffle`, `uniqueBy`, `sortBy`, `intersection`, `difference`, `flattenDeep`, `move`, `chunkBy`, …); function (`debounce`, `throttle` with `{ leading, trailing, maxWait }` + `.flush()`, `once`, `memoize`, `compose`, `pipe`, `curry`, `partial`, `retry`); object (`merge`, `clone`, `pick`, `omit`, deep `get`/`set`/`has`, `mapValues`, `mapKeys`, `invert`, `deepEqual`/`isEqual`, deep `freeze`, `defaults`, `entriesTyped`, `keysTyped`); string (`slugify`, `toCamelCase`, `toKebabCase`, `toSnakeCase`, `toPascalCase`, `toTitleCase`, `pad`/`padStart`/`padEnd`, `wordCount`, safe `template`, `stripHtml`, `randomString`, `lines`); number (`clamp`, `round`, `roundTo`, `lerp`, `inverseLerp`, `mapRange`, `formatBytes`, `randomFloat`, `sum`, `average`, `median`, `degToRad`, `radToDeg`); misc (`uid`, `uuid`, `sleep`, `tryCatch`, `times`, `pollUntil`, `nextFrame`, `nextTick`); and an extensive type-guard set (`isArray`, `isString`, `isElement`, `isError`, `isMap`, `isSet`, `isRegExp`, `isSymbol`, `isBigInt`, `isAsyncFunction`, `isIterable`, `isAsyncIterable`, `isNullish`, `isDefined`, …).
### Reactive (`@bquery/bquery/reactive`)
Fine-grained reactivity system plus a transport-ready data layer. `signal(value)` creates a reactive value. `computed(fn)` derives values with auto-tracking. `effect(fn)` runs side effects. `batch(fn)` groups updates. `watch(signal, callback)` observes changes, while `watchDebounce(signal, callback, ms)` and `watchThrottle(signal, callback, ms)` tame bursty updates. `linkedSignal(get, set)` creates writable computed values. `persistedSignal(key, init)` syncs to localStorage. `useAsyncData(handler)` wraps arbitrary async work in signal-driven `data` / `error` / `status` state. `useFetch(input, options)` adds query/header/body helpers and response parsing. `createUseFetch(defaults)` creates preconfigured fetch composables. `createHttp()` / `http` expose interceptable imperative HTTP clients. `usePolling()`, `usePaginatedFetch()`, and `useInfiniteFetch()` cover interval, page, and cursor workflows. `useWebSocket()`, `useWebSocketChannel()`, and `useEventSource()` handle realtime streams; `WebSocketSendData` is the public raw-frame payload union for custom serializers and `sendRaw()`. `useResource()`, `useResourceList()`, `useSubmit()`, `createRestClient()`, `createRequestQueue()`, and `deduplicateRequest()` cover CRUD and request coordination. `readonly(signal)` creates a read-only wrapper. Access via `.value` (tracks), `.peek()` (no tracking).
### Concurrency (`@bquery/bquery/concurrency`)
Zero-build browser worker helpers. `runTask(handler, input, options)` executes one isolated task in a fresh worker. `createTaskWorker(handler, options)` creates a reusable worker handle with explicit `run()` / `terminate()` lifecycle. `createTaskPool(handler, options)` adds bounded parallelism plus FIFO queueing for repeated task execution. `createRpcWorker(handlers, options)` adds explicit named request/response dispatch for RPC-style worker calls, `callWorkerMethod()` provides the one-off variant, and `createRpcPool()` extends that explicit model to multiple workers with queueing/backpressure. Optional reactive wrappers `createReactiveTaskWorker()`, `createReactiveRpcWorker()`, `createReactiveTaskPool()`, and `createReactiveRpcPool()` mirror worker and pool getters into readonly signals such as `state$`, `busy$`, `pending$`, `size$`, and `concurrency$` for dashboards and UI bindings. High-level helpers include `parallel(tasks, options)`, `batchTasks(tasks, batchSize?, options)`, `map(values, mapper, options)`, `filter(values, predicate, options)`, `some(values, predicate, options)`, `every(values, predicate, options)`, `find(values, predicate, options)`, `reduce(values, reducer, initialValue, options)`, and `pipeline(values, options)` as thin, explicit layers over the same worker primitives. `pipeline()` is just an optional immutable fluent wrapper around the existing collection helpers; it does not add proxies, decorators, or hidden worker runtimes. `getConcurrencySupport()` and `isConcurrencySupported()` expose browser capability checks. Timeout, abort, serialization, unsupported-environment, lifecycle, missing-method, queue-full, and queue-cleared failures are surfaced through structured worker errors.
### Component (`@bquery/bquery/component`)
Lightweight Web Components helper. `component(tag, definition)` creates and auto-registers a custom element with typed props, typed optional state, declared `signals`, configurable `shadow` mode (`true`, `false`, `'open'`, `'closed'`), lifecycle hooks (`beforeMount`, `connected`, `disconnected`, `onAdopted`, `onAttributeChanged`, `beforeUpdate`, `updated`, `onError`), and automatic HTML sanitization of rendered output. `defineComponent()` returns the class without registering. `registerDefaultComponents()` registers a dependency-free default component library (`button`, `card`, `input`, `textarea`, `checkbox`). `html`, `safeHtml`, and `bool()` help author safe templates and boolean attributes. `useSignal()`, `useComputed()`, and `useEffect()` create component-scoped reactive resources that auto-dispose on disconnect.
### Motion (`@bquery/bquery/motion`)
Animation utilities. `animate()` wraps the Web Animations API and now accepts an `AbortSignal` and `playbackRate`; `animateTo()` builds keyframes from CSS property records or `[from, to]` tuples. `transition()` uses View Transitions API with fallback and supports classes, transition types, reduced-motion skipping, and ready/finish callbacks. `flip()` / `flipElements()` for FLIP animations. `morphElement()` animates between two elements. `parallax()` adds scroll-linked motion. `typewriter()` animates text content character by character. `tween()` interpolates numbers, number arrays, or `Record<string, number>` with `pause`/`resume`/`reverse`/`seek`/`stop`/`progress`/`finished` controls and `AbortSignal` support; `animateValue()` is the Promise-based convenience helper. `spring()` provides spring physics with `.velocity()` / `.set()`, plus `springVector()` for multi-dimensional motion and `springPresets` (`gentle`, `wobbly`, `slow`, `molasses`, …). `timeline()` and `sequence()` choreograph animations with labels, `reverse()`, `playbackRate()`, `repeat()`, `yoyo()`, `onUpdate()`, and `progress()`. `stagger()` handles staggered timing with `grid` 2D origins, `axis`, and deterministic `random` / `randomSeed`. `scrollAnimate()`, `scrollProgress()`, and `inView()` cover scroll-driven motion. Micro-interaction primitives `magnetic()`, `tilt()`, `shake()`, `pulse()`, and `countUp()` round out the toolkit. The full Penner easing family is exported (`easeIn`/`easeOut`/`easeInOut` of `Quad`, `Cubic`, `Quart`, `Quint`, `Sine`, `Expo`, `Circ`, `Back`, `Elastic`, `Bounce`) plus `cubicBezier()`, `steps()`, `mix()`, and `chain()` composers, and `keyframePresets` / `easingPresets`. Reduced-motion is respected throughout and observable via `prefersReducedMotion()`, `setReducedMotion()`, `onReducedMotionChange()`, and `reducedMotionSignal()`.
### Security (`@bquery/bquery/security`)
HTML sanitization enabled by default across the library. `sanitizeHtml(html)` strips dangerous elements (script, iframe, svg, etc.), blocks DOM clobbering (reserved IDs), protects against Unicode URL bypasses, adds `rel="noopener noreferrer"` to external links. Also: `escapeHtml()`, `stripTags()`, `trusted()` for safe fragment composition, `generateNonce()`, Trusted Types support, CSP helpers.
### Storybook (`@bquery/bquery/storybook`)
String-template helpers for component stories. `storyHtml` sanitizes interpolated story markup, preserves authored custom elements/attributes, and supports Storybook-style boolean attribute shorthand such as `?disabled=${true}`. `when()` conditionally renders fragments or callbacks.
### Platform (`@bquery/bquery/platform`)
Browser API wrappers and shared runtime configuration. `storage` provides unified localStorage/sessionStorage/IndexedDB access. `cache` for TTL-based caching. `notifications` wraps the Notifications API. `buckets` for rate limiting. `defineBqueryConfig()` / `getBqueryConfig()` manage shared defaults for fetch, cookies, transitions, announcers, page metadata, and default component prefixes. `useCookie()` provides reactive cookie state. `definePageMeta()` manages document title/meta/link tags and temporary `html` / `body` attributes. `useAnnouncer()` manages accessible ARIA live-region announcements.
### Router (`@bquery/bquery/router`)
SPA routing. `createRouter(options)` sets up routes with path matching, wildcard support, repeated query params, regex-constrained params (`/user/:id(\d+)`), `redirectTo`, per-route `beforeEnter`, optional `scrollRestoration`, hash mode, and base path. `navigate(path)` is for programmatic navigation. `currentRoute` exposes the active route as a reactive signal. `useRoute()` returns focused readonly signals (`path`, `params`, `query`, `hash`, `matched`). `interceptLinks()` auto-handles `<a>` clicks, and `registerBqLink()` / `BqLinkElement` provide declarative SPA navigation via `<bq-link>`.
### Store (`@bquery/bquery/store`)
Signal-based state management. `createStore(definition)` creates a store with state, getters, and actions. Stores expose `$reset`, `$patch`, `$patchDeep`, `$subscribe`, `$state`, and `$onAction()` for action lifecycle observation. `defineStore()` provides factory-style (Pinia-like) stores. `createPersistedStore()` supports legacy string keys and richer options (`key`, `storage`, `serializer`, `version`, `migrate`). Helpers: `mapActions`, `mapGetters`, `mapState`, `watchStore`. Store plugins can be registered with `registerPlugin()`, removed one at a time with `unregisterPlugin()`, or fully reset with `clearPlugins()` for test teardown and plugin reloads.
### View (`@bquery/bquery/view`)
Declarative DOM bindings. `mount(selector, context)` binds reactive state to DOM using directives: `bq-text`, `bq-html`, `bq-if`, `bq-for`, `bq-model` (two-way), `bq-class`, `bq-style`, `bq-show`, `bq-bind`, `bq-error`, `bq-aria`, `bq-on:event`. `bq-error` is intended for reactive inline error output, while `bq-aria` maps object expressions or evaluated state into ARIA attributes. Uses `new Function()` internally (requires CSP `unsafe-eval`).
### Forms (`@bquery/bquery/forms`)
Reactive form handling. `createForm()` manages field values, errors, touched/dirty state, validation, submission, and `isSubmitting`. Built-in validators: `required`, `minLength`, `maxLength`, `pattern`, `email`, `url`, `min`, `max`, `custom`, and `customAsync`. Supports cross-field validation.
### i18n (`@bquery/bquery/i18n`)
Internationalization helpers. `createI18n()` manages reactive locale state, translations, interpolation, pluralization, lazy locale loading, and Intl-based formatting. `formatDate()` and `formatNumber()` are available standalone.
### A11y (`@bquery/bquery/a11y`)
Accessibility helpers. Includes `trapFocus()`, `releaseFocus()`, `getFocusableElements()`, `announceToScreenReader()`, `clearAnnouncements()`, `rovingTabIndex()`, `skipLink()`, `auditA11y()`, and reactive media-preference signals such as `prefersColorScheme()` and `prefersContrast()`.
### DnD (`@bquery/bquery/dnd`)
Drag-and-drop utilities. `draggable()` adds pointer-based dragging with bounds and handles. `droppable()` manages drop zones with accept filters and callbacks. `sortable()` adds list reordering with placeholders and sort events.
### Media (`@bquery/bquery/media`)
Reactive browser and device APIs. Includes `mediaQuery()`, `breakpoints()` (with collection cleanup via `destroyAll()`), `useViewport()`, `useNetworkStatus()`, `useBattery()`, `useGeolocation()`, `useDeviceMotion()`, `useDeviceOrientation()`, `useIntersectionObserver()`, `useResizeObserver()`, `useMutationObserver()`, and async clipboard helpers via `clipboard.read()` / `clipboard.write()`. The observer composables expose cleanup-friendly signal wrappers around DOM observer APIs.
### Plugin (`@bquery/bquery/plugin`)
Global extension system. `use(plugin)` installs a plugin once by name. Plugins receive a `PluginInstallContext` that can register custom view directives and Web Components. Introspection helpers include `isInstalled()`, `getInstalledPlugins()`, `getCustomDirective()`, `getCustomDirectives()`, and `resetPlugins()`.
### Devtools (`@bquery/bquery/devtools`)
Runtime inspection utilities. `enableDevtools()` toggles collection. `inspectSignals()`, `inspectStores()`, and `inspectComponents()` snapshot runtime state. `recordEvent()`, `getTimeline()`, and `clearTimeline()` manage an event timeline. Console-oriented helpers such as `logSignals()` and `logTimeline()` are included.
### Testing (`@bquery/bquery/testing`)
Testing helpers. `renderComponent()` mounts custom elements, `flushEffects()` flushes pending reactive work, `mockSignal()` creates controllable signals, `mockRouter()` creates a lightweight reactive router, `fireEvent()` dispatches synthetic events, and `waitFor()` polls async conditions.
### SSR (`@bquery/bquery/ssr`)
Runtime-agnostic SSR pipeline that works on Node.js ≥ 24, Deno and Bun ≥ 1.4.0 with zero external dependencies. `renderToString()` renders directive-aware templates synchronously; the new `renderToStringAsync()` resolves Promise / `defer()` values in the binding context. `renderToStream()` returns a Web `ReadableStream<Uint8Array>` and `renderToResponse()` produces a ready-to-return `Response` with `Content-Type`, optional weak ETag, head/asset/store-state injection. A DOM-free renderer (own HTML tokenizer + Pratt-parser expression evaluator, no `eval`/`new Function()`) takes over automatically when no `DOMParser` is available, making SSR work natively on every server runtime; configure explicitly via `configureSSR({ backend, documentImpl })`. `createSSRContext()` builds the request/response context (URL, headers, cookies, locale, nonce, AbortSignal, head + asset managers). `createHeadManager()`/`createAssetManager()` collect `<title>`/`<meta>`/`<link>`/`<script>` entries with CSP-nonce propagation. Progressive hydration: `hydrateMount()`, `hydrateOnVisible()`, `hydrateOnIdle()`, `hydrateOnInteraction()`, `hydrateOnMedia()`, `hydrateIsland()`. Hydration mismatch dev-warnings via `RenderOptions.annotateHydration` + `verifyHydration()`. Suspense streaming with `renderToStreamSuspense()` (out-of-order patches per resolved promise, CSP-nonce aware). Router/SSR bridge with `resolveSSRRoute()` / `runRouteLoaders()` / `createSSRRouterContext()` (recognises `meta.loader`). Versioned store snapshots with `serializeStoreSnapshot()` / `hydrateStoreSnapshot()` / `readStoreSnapshot()`. Resumability hooks via `createResumableState()` / `resumeState()`. Runtime adapters `createWebHandler()` / `createBunHandler()` / `createDenoHandler()` / `createNodeHandler()` (with auto-detect `createSSRHandler()`) wrap a single fetch-style handler for any host. `serializeStoreState()`, `deserializeStoreState()`, `hydrateStore()` and `hydrateStores()` bridge store state between server and client. `detectRuntime()` / `getSSRRuntimeFeatures()` expose runtime introspection. Cross-runtime CI matrix runs on Node 24 + latest Bun + Deno 2; runnable examples live in `examples/ssr-{node,bun,deno}/`.
### Server (`@bquery/bquery/server`)
Express-inspired backend helpers. `createServer()` creates a dependency-free request pipeline with `use()`, `get()` / `post()` / `put()` / `patch()` / `delete()` / `all()`, `ws()`, route params, repeated-query parsing, safe `text()` / `html()` / `json()` helpers, redirects, SSR-aware `render()` responses, and runtime-agnostic WebSocket handling through `handleWebSocket()`, `isWebSocketRequest()`, and `isServerWebSocketSession()`.
## Installation
```bash
bun add @bquery/bquery # or npm/pnpm
```
CDN (zero-build):
```html
<script type="module">
import { $, signal } from 'https://unpkg.com/@bquery/bquery@1/dist/full.es.mjs';
</script>
```
## Development
```bash
bun install # Install dependencies
bun test # Run tests
bun run build # Build library
bun run lint # Lint with auto-fix
bun run check:ai-guidance # Verify AI guidance + release metadata sync
bun run dev # Docs dev server
bun run storybook # Storybook dev server
```
## Key Design Decisions
- Security by default: all DOM HTML writes are sanitized
- Chainable API: mutating methods return `this`
- Shared runtime defaults via `defineBqueryConfig()`
- Zero runtime dependencies
- Tree-shakeable with separate entry points per module
- Strict TypeScript throughout
- Tests use Bun runner (not Node)
- Keep `src/full.ts` in sync with public runtime exports for the `/full` / CDN bundle
- Keep AI-facing repo guidance aligned with `package.json` via `bun run check:ai-guidance`
## Documentation
- Full guide: https://bquery.js.org
- Agent guide: AGENT.md
- API reference: docs/guide/api-core.md
- Changelog: CHANGELOG.md
- Component previews: Storybook via `bun run storybook`