Skip to content

Commit 0b43903

Browse files
committed
Share jsdom adapter configuration per document (#213)
* Add document-scoped jsdom engine configuration * Group repository tests and development scripts * Test shared adapter setup and verify relocated runners * Compile escaped identifiers without changing class token boundaries
1 parent 3526e0c commit 0b43903

85 files changed

Lines changed: 1036 additions & 359 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.config/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# Code style
22

33
Run `pnpm format`, `pnpm lint`, and `pnpm type` before submitting changes.
4-
Formatting and linting share their file list in `scripts/lib/tooling-scope.mts`.
4+
Formatting and linting share their file list in `scripts/repo/lib/tooling-scope.mts`.
55
Generated JavaScript and upstream fixtures are excluded.
66

77
Use two spaces, single quotes, no semicolons, and regex literals for static
88
patterns. Lint checks correctness, suspicious code, imports, and TypeScript.
99
Use default imports for `node:path`, `node:crypto`, and `node:os`.
1010

11-
Package scripts use `scripts/run.mts` to share an OS-temporary Node compile cache
11+
Package scripts use `scripts/repo/run.mts` to share an OS-temporary Node compile cache
1212
with child processes. Existing cache settings and opt-outs are preserved.
1313
Coverage runs disable the cache for accurate measurements.
1414
The launcher permits pnpm, aube, and direct Node runs. Other package managers

‎.config/generated.d.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,22 @@ declare module '*/src/nwsapi.js' {
44
const factory: (host: { document: Document }) => typeof NW.Dom
55
export default factory
66
}
7+
8+
declare module '*/src/dom-selector.js' {
9+
export default class DOMSelector {
10+
constructor(window: unknown, document?: unknown, options?: unknown)
11+
static configure(window: unknown, options: Record<string, boolean>): void
12+
static use(window: unknown, engine: unknown): unknown
13+
engine: unknown
14+
selectors: Map<string, unknown>
15+
matches(
16+
selector: string,
17+
node: unknown,
18+
options?: { noexcept?: boolean },
19+
): boolean
20+
closest(selector: string, node: unknown): unknown
21+
querySelector(selector: string, node: unknown): unknown
22+
querySelectorAll(selector: string, node: unknown): unknown[]
23+
clear(clearAll?: boolean): void
24+
}
25+
}

‎.config/playwright.config.mts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
import process from 'node:process'
22
import { fileURLToPath } from 'node:url'
33
import { defineConfig } from '@playwright/test'
4-
import { isAgent } from '../scripts/lib/is-agent.mts'
4+
import { isAgent } from '../scripts/repo/lib/is-agent.mts'
55

66
// Vitest runs Node tests; this configuration only runs WPT in Chromium.
77
export default defineConfig({
8-
testDir: '../test/upstream',
8+
testDir: '../test/repo/e2e/upstream',
99
outputDir: '../test-results',
1010
testMatch: 'wpt.spec.mts',
1111
fullyParallel: true,
@@ -15,7 +15,7 @@ export default defineConfig({
1515
use: { baseURL: 'http://127.0.0.1:8000', browserName: 'chromium' },
1616
webServer: {
1717
cwd: fileURLToPath(new URL('../', import.meta.url)),
18-
command: 'node scripts/serve.mts',
18+
command: 'node scripts/repo/serve.mts',
1919
url: 'http://127.0.0.1:8000/resources/testharness.js',
2020
reuseExistingServer: false,
2121
env: { ...process.env, PORT: '8000' },

‎.config/tsconfig.check.json‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,8 @@
1616
},
1717
"include": [
1818
"../src/**/*.mts",
19-
"../scripts/**/*.mts",
20-
"../test/*.mts",
21-
"../test/upstream/*.mts",
19+
"../scripts/repo/**/*.mts",
20+
"../test/repo/**/*.mts",
2221
"./*.mts",
2322
"./*.d.ts"
2423
]

‎.config/vitest.config.mts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { defineConfig } from 'vitest/config'
22
import { fileURLToPath } from 'node:url'
3-
import { isAgent } from '../scripts/lib/is-agent.mts'
3+
import { isAgent } from '../scripts/repo/lib/is-agent.mts'
44

55
process.env.TZ ??= 'UTC'
66

@@ -16,11 +16,13 @@ export default defineConfig({
1616
]
1717
: undefined,
1818
watch: process.argv.includes('--watch'),
19-
include: ['test/*.test.mts'],
19+
include: ['test/repo/**/*.test.mts'],
2020
globalSetup: ['.config/vitest.setup.mts'],
21-
forceRerunTriggers: ['../src/**/*.mts', '../scripts/build.mts', './**'].map(
22-
path => fileURLToPath(new URL(path, import.meta.url)),
23-
),
21+
forceRerunTriggers: [
22+
'../src/**/*.mts',
23+
'../scripts/repo/build.mts',
24+
'./**',
25+
].map(path => fileURLToPath(new URL(path, import.meta.url))),
2426
environment: 'node',
2527
pool: 'forks',
2628
isolate: true,

‎.config/vitest.setup.mts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import type { TestProject } from 'vitest/node'
44

55
export default function setup(project: TestProject) {
66
const build = () => {
7-
execFileSync(process.execPath, ['scripts/build.mts'], {
7+
execFileSync(process.execPath, ['scripts/repo/build.mts'], {
88
cwd: new URL('../', import.meta.url),
99
stdio: 'inherit',
1010
})

‎.github/workflows/node.js.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ jobs:
1212
steps:
1313
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 (2026-07-20)
1414
- id: tools
15-
run: node scripts/external-tools.mts --github-output
15+
run: node scripts/repo/external-tools.mts --github-output
1616
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 (2026-07-14)
1717
with:
1818
node-version: ${{ steps.tools.outputs.node }}

‎assets/repo/coverage.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎docs/api.md‎

Lines changed: 62 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,21 @@ Query contexts default to the factory document when omitted. `closest()`, `first
1111

1212
| Method | Result |
1313
| --- | --- |
14-
| [`byClass(cls, context)`](../src/nwsapi.mts#L3003) | Returns elements with the class name. |
15-
| [`byId(id, context)`](../src/nwsapi.mts#L3001) | Returns elements with the ID. Duplicate IDs are allowed by default. |
16-
| [`byTag(tag, context)`](../src/nwsapi.mts#L3002) | Returns elements with the tag name. Use `*` for all elements. |
17-
| [`closest(selectors, element, callback)`](../src/nwsapi.mts#L3009) | Returns the nearest match, starting with the element, or `null`. |
18-
| [`compile(selector, mode, callback)`](../src/nwsapi.mts#L3011) | Compiles a selector into a resolver function. This is an advanced API. |
19-
| [`configure(option, clear)`](../src/nwsapi.mts#L3012) | Reads or changes options. Pass `true` as the second argument to clear compiled selectors. |
20-
| [`emit(message, proto)`](../src/nwsapi.mts#L3014) | Reports an error using the configured error policy. |
21-
| [`first(selectors, context, callback)`](../src/nwsapi.mts#L3005) | Returns the first matching descendant, or `null`. |
22-
| [`install(all)`](../src/nwsapi.mts#L3020) | Replaces native selector methods. Pass `true` to also replace collection methods. |
23-
| [`match(selectors, element, callback)`](../src/nwsapi.mts#L3006) | Returns whether the element matches. |
24-
| [`registerCombinator(combinator, resolver)`](../src/nwsapi.mts#L3027) | Adds a relationship between elements using trusted resolver code. |
25-
| [`registerOperator(operator, resolver)`](../src/nwsapi.mts#L3052) | Adds an attribute operator using a resolver with `p1`, `p2`, and `p3` fields. |
26-
| [`registerSelector(name, rexp, func)`](../src/nwsapi.mts#L3074) | Adds a selector pattern and a compiler callback that returns `source` and `status`. |
27-
| [`select(selectors, context, callback)`](../src/nwsapi.mts#L3007) | Returns an array of matching descendants, or an empty array. |
28-
| [`uninstall()`](../src/nwsapi.mts#L3021) | Restores the native methods saved by `install()`. |
14+
| [`byClass(cls, context)`](../src/nwsapi.mts#L3014) | Returns elements with the class name. |
15+
| [`byId(id, context)`](../src/nwsapi.mts#L3012) | Returns elements with the ID. Duplicate IDs are allowed by default. |
16+
| [`byTag(tag, context)`](../src/nwsapi.mts#L3013) | Returns elements with the tag name. Use `*` for all elements. |
17+
| [`closest(selectors, element, callback)`](../src/nwsapi.mts#L3020) | Returns the nearest match, starting with the element, or `null`. |
18+
| [`compile(selector, mode, callback)`](../src/nwsapi.mts#L3022) | Compiles a selector into a resolver function. This is an advanced API. |
19+
| [`configure(option, clear)`](../src/nwsapi.mts#L3023) | Reads or changes options. Pass `true` as the second argument to clear compiled selectors. |
20+
| [`emit(message, proto)`](../src/nwsapi.mts#L3025) | Reports an error using the configured error policy. |
21+
| [`first(selectors, context, callback)`](../src/nwsapi.mts#L3016) | Returns the first matching descendant, or `null`. |
22+
| [`install(all)`](../src/nwsapi.mts#L3031) | Replaces native selector methods. Pass `true` to also replace collection methods. |
23+
| [`match(selectors, element, callback)`](../src/nwsapi.mts#L3017) | Returns whether the element matches. |
24+
| [`registerCombinator(combinator, resolver)`](../src/nwsapi.mts#L3038) | Adds a relationship between elements using trusted resolver code. |
25+
| [`registerOperator(operator, resolver)`](../src/nwsapi.mts#L3063) | Adds an attribute operator using a resolver with `p1`, `p2`, and `p3` fields. |
26+
| [`registerSelector(name, rexp, func)`](../src/nwsapi.mts#L3085) | Adds a selector pattern and a compiler callback that returns `source` and `status`. |
27+
| [`select(selectors, context, callback)`](../src/nwsapi.mts#L3018) | Returns an array of matching descendants, or an empty array. |
28+
| [`uninstall()`](../src/nwsapi.mts#L3032) | Restores the native methods saved by `install()`. |
2929

3030
<details>
3131
<summary>Configuration</summary>
@@ -60,22 +60,22 @@ These exports support extensions and debugging. Prefer query methods and `config
6060

6161
| Member | Purpose |
6262
| --- | --- |
63-
| [`CFG`](../src/nwsapi.mts#L2989) | Contains the compiler syntax settings. |
64-
| [`Config`](../src/nwsapi.mts#L3015) | Contains the active options. Use `configure()` to change them. |
65-
| [`M_BODY`](../src/nwsapi.mts#L2992) | Contains the matching resolver body template. |
66-
| [`M_TEST`](../src/nwsapi.mts#L2996) | Contains the matching resolver test template. |
67-
| [`matchLambdas`](../src/nwsapi.mts#L2981) | Caches compiled matching functions, not DOM results. |
68-
| [`matchResolvers`](../src/nwsapi.mts#L2984) | Caches matching plans, not DOM results. |
69-
| [`N_BODY`](../src/nwsapi.mts#L2993) | Exposes the matching resolver body template. |
70-
| [`N_TEST`](../src/nwsapi.mts#L2997) | Contains the alternate resolver test template. |
71-
| [`Operators`](../src/nwsapi.mts#L3023) | Contains registered attribute operators. |
72-
| [`S_BODY`](../src/nwsapi.mts#L2991) | Contains the selection resolver body template. |
73-
| [`S_TEST`](../src/nwsapi.mts#L2995) | Contains the selection resolver test template. |
74-
| [`selectLambdas`](../src/nwsapi.mts#L2982) | Caches compiled selection functions, not DOM results. |
75-
| [`Selectors`](../src/nwsapi.mts#L3024) | Contains registered selector extensions. |
76-
| [`selectResolvers`](../src/nwsapi.mts#L2985) | Caches selection plans, not DOM results. |
77-
| [`Snapshot`](../src/nwsapi.mts#L3016) | Contains the document state and helpers used by compiled selectors. |
78-
| [`Version`](../src/nwsapi.mts#L3018) | Contains the engine version string. |
63+
| [`CFG`](../src/nwsapi.mts#L3000) | Contains the compiler syntax settings. |
64+
| [`Config`](../src/nwsapi.mts#L3026) | Contains the active options. Use `configure()` to change them. |
65+
| [`M_BODY`](../src/nwsapi.mts#L3003) | Contains the matching resolver body template. |
66+
| [`M_TEST`](../src/nwsapi.mts#L3007) | Contains the matching resolver test template. |
67+
| [`matchLambdas`](../src/nwsapi.mts#L2992) | Caches compiled matching functions, not DOM results. |
68+
| [`matchResolvers`](../src/nwsapi.mts#L2995) | Caches matching plans, not DOM results. |
69+
| [`N_BODY`](../src/nwsapi.mts#L3004) | Exposes the matching resolver body template. |
70+
| [`N_TEST`](../src/nwsapi.mts#L3008) | Contains the alternate resolver test template. |
71+
| [`Operators`](../src/nwsapi.mts#L3034) | Contains registered attribute operators. |
72+
| [`S_BODY`](../src/nwsapi.mts#L3002) | Contains the selection resolver body template. |
73+
| [`S_TEST`](../src/nwsapi.mts#L3006) | Contains the selection resolver test template. |
74+
| [`selectLambdas`](../src/nwsapi.mts#L2993) | Caches compiled selection functions, not DOM results. |
75+
| [`Selectors`](../src/nwsapi.mts#L3035) | Contains registered selector extensions. |
76+
| [`selectResolvers`](../src/nwsapi.mts#L2996) | Caches selection plans, not DOM results. |
77+
| [`Snapshot`](../src/nwsapi.mts#L3027) | Contains the document state and helpers used by compiled selectors. |
78+
| [`Version`](../src/nwsapi.mts#L3029) | Contains the engine version string. |
7979

8080
</details>
8181

@@ -87,20 +87,39 @@ These exports support extensions and debugging. Prefer query methods and `config
8787
Access the adapter as `require("nwsapi").DOMSelector` or `require("nwsapi/src/dom-selector.js")`.
8888
jsdom calls these methods through the package override. Query options can set `noexcept: true` to suppress selector errors.
8989

90+
Configure before parsing, because styles and scripts can use selectors during document creation:
91+
92+
```js
93+
const { DOMSelector } = require("nwsapi")
94+
const { JSDOM } = require("jsdom")
95+
const dom = new JSDOM(html, {
96+
beforeParse(window) {
97+
DOMSelector.configure(window, { LEGACY: true })
98+
}
99+
})
100+
```
101+
102+
To reuse an engine, create a document without styles, then call `DOMSelector.use(window, engine)` before adding styles or running queries. The engine must belong to that document and have `VERBOSITY: true`. DOM queries throw for invalid selectors; stylesheet checks return no match.
103+
104+
Setup locks on the first query, selector support check, or stylesheet match. Do not change the shared engine configuration directly after setup: jsdom can cache computed styles. Separate factory calls remain independent. Compatible adapter copies share setup even when the package override loads a second copy.
105+
90106
| Method | Result |
91107
| --- | --- |
92-
| [`check(selector, node)`](../src/dom-selector.mts#L151) | Returns matching stylesheet branches and their syntax tree. Loads `css-tree` on first use. |
93-
| [`clear(clearAll = false)`](../src/dom-selector.mts#L87) | Clears compiled selectors and parsed stylesheet selectors when `clearAll` is `true`. |
94-
| [`closest(selector, node, options)`](../src/dom-selector.mts#L75) | Returns the nearest matching element, or `null`. |
95-
| [`constructor(window, document = window.document, options = {})`](../src/dom-selector.mts#L26) | Creates the adapter. `options.idlUtils` supports jsdom implementation nodes. |
96-
| [`extractSubjects()`](../src/dom-selector.mts#L98) | Returns a wildcard candidate description for stylesheet matching. |
97-
| [`matches(selector, node, options)`](../src/dom-selector.mts#L71) | Returns whether an element matches. |
98-
| [`parse(selector)`](../src/dom-selector.mts#L116) | Internal helper that caches stylesheet syntax after `css-tree` is loaded. |
99-
| [`querySelector(selector, node, options)`](../src/dom-selector.mts#L79) | Returns the first matching descendant, or `null`. |
100-
| [`querySelectorAll(selector, node, options)`](../src/dom-selector.mts#L83) | Returns matching descendants as an array. |
101-
| [`run(method, selector, node, options, fallback, elementOnly = false)`](../src/dom-selector.mts#L45) | Internal helper that checks nodes and applies the query error policy. |
102-
| [`supports(selector)`](../src/dom-selector.mts#L104) | Returns whether the engine accepts a selector. |
103-
| [`wrap(node)`](../src/dom-selector.mts#L41) | Internal helper that converts jsdom implementation nodes to public nodes. |
108+
| [`check(selector, node)`](../src/dom-selector.mts#L258) | Returns matching stylesheet branches and their syntax tree. Loads `css-tree` on first use. |
109+
| [`clear(clearAll = false)`](../src/dom-selector.mts#L194) | Clears compiled selectors and parsed stylesheet selectors when `clearAll` is `true`. |
110+
| [`closest(selector, node, options)`](../src/dom-selector.mts#L182) | Returns the nearest matching element, or `null`. |
111+
| [`DOMSelector.configure(window, options)`](../src/dom-selector.mts#L68) | Configures the shared engine before the first query or stylesheet match. |
112+
| [`constructor(window, document = window.document, options = {})`](../src/dom-selector.mts#L120) | Creates the adapter. `options.idlUtils` supports jsdom implementation nodes. |
113+
| [`engine`](../src/dom-selector.mts#L131) | Returns the shared engine, creating it on first access. |
114+
| [`extractSubjects()`](../src/dom-selector.mts#L205) | Returns a wildcard candidate description for stylesheet matching. |
115+
| [`matches(selector, node, options)`](../src/dom-selector.mts#L178) | Returns whether an element matches. |
116+
| [`parse(selector)`](../src/dom-selector.mts#L223) | Internal helper that caches stylesheet syntax after `css-tree` is loaded. |
117+
| [`querySelector(selector, node, options)`](../src/dom-selector.mts#L186) | Returns the first matching descendant, or `null`. |
118+
| [`querySelectorAll(selector, node, options)`](../src/dom-selector.mts#L190) | Returns matching descendants as an array. |
119+
| [`run(method, selector, node, options, fallback, elementOnly = false)`](../src/dom-selector.mts#L152) | Internal helper that checks nodes and applies the query error policy. |
120+
| [`supports(selector)`](../src/dom-selector.mts#L211) | Returns whether the engine accepts a selector. |
121+
| [`DOMSelector.use(window, engine)`](../src/dom-selector.mts#L90) | Binds an existing engine before jsdom first uses the adapter. Returns the engine. |
122+
| [`wrap(node)`](../src/dom-selector.mts#L148) | Internal helper that converts jsdom implementation nodes to public nodes. |
104123

105124
</details>
106125

‎docs/legacy-runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,5 +31,5 @@ fallbacks to avoid retaining unused documents.
3131
Use Node.js 18 or newer:
3232

3333
```sh
34-
pnpm run test:node test/legacy-runtime.test.mts
34+
pnpm run test:node test/repo/unit/legacy-runtime.test.mts
3535
```

0 commit comments

Comments
 (0)