@barqjs/compiler 0.0.0-stage → 0.2.0-next.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +225 -2
- package/docs/BARQ001.md +55 -0
- package/docs/BARQ002.md +53 -0
- package/docs/BARQ003.md +58 -0
- package/docs/BARQ004.md +116 -0
- package/docs/BARQ005.md +92 -0
- package/docs/BARQ006.md +23 -0
- package/docs/BARQ008.md +43 -0
- package/docs/BARQ009.md +48 -0
- package/docs/BARQ010.md +76 -0
- package/docs/BARQ011.md +88 -0
- package/docs/BARQ012.md +81 -0
- package/docs/BARQ013.md +63 -0
- package/docs/BARQ014.md +61 -0
- package/docs/BARQ015.md +64 -0
- package/docs/BARQ016.md +52 -0
- package/docs/BARQ017.md +63 -0
- package/docs/BARQ018.md +116 -0
- package/docs/BARQ019.md +109 -0
- package/docs/BARQ020.md +78 -0
- package/docs/BARQ021.md +79 -0
- package/docs/BARQ022.md +57 -0
- package/docs/BARQ023.md +55 -0
- package/docs/BARQ024.md +58 -0
- package/docs/BARQ025.md +74 -0
- package/docs/BARQ026.md +68 -0
- package/docs/BARQ027.md +53 -0
- package/docs/BARQ028.md +56 -0
- package/docs/BARQ029.md +57 -0
- package/docs/README.md +129 -0
- package/index.d.ts +563 -0
- package/index.js +89 -0
- package/package.json +86 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Salama Ashoush
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,226 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @barqjs/compiler
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The barq JSX compiler, written in Rust on [oxc](https://oxc.rs) and loaded into
|
|
4
|
+
Node or Bun through napi-rs. It turns JSX into templates that are cloned once
|
|
5
|
+
and runtime calls from `@barqjs/web` that update only the holes that read a
|
|
6
|
+
signal, with the reactive calls from `@barqjs/core`. With `ssr: true` the same
|
|
7
|
+
analysis emits a string renderer that imports `@barqjs/server` instead, and
|
|
8
|
+
with `target: "universal"` it builds every element through a custom renderer
|
|
9
|
+
made with `@barqjs/universal`.
|
|
10
|
+
|
|
11
|
+
It also generates the file route table, splits route and middleware modules into
|
|
12
|
+
their client and server halves, compiles `@barqjs/css` blocks to a stylesheet,
|
|
13
|
+
and reports mistakes before the code runs: 26 [diagnostics](./docs/README.md),
|
|
14
|
+
each with a stable `BARQ` code, a page that shows the fix, and a required reason
|
|
15
|
+
to silence it.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
Applications do not call this package. `@barqjs/vite` depends on it and runs it
|
|
20
|
+
on every `.jsx` and `.tsx` file:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
bun add -d @barqjs/vite
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import barq from "@barqjs/vite";
|
|
28
|
+
import { defineConfig } from "vite";
|
|
29
|
+
|
|
30
|
+
export default defineConfig({
|
|
31
|
+
plugins: [barq()],
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
There is one pipeline. If the native binary cannot be loaded, the plugin throws
|
|
36
|
+
rather than compiling the file some other way.
|
|
37
|
+
|
|
38
|
+
The binary is built per platform. The targets are listed under `napi.targets` in
|
|
39
|
+
`package.json`: Linux x64 and arm64 (glibc), macOS x64 and arm64, and Windows
|
|
40
|
+
x64 and arm64.
|
|
41
|
+
|
|
42
|
+
## Coming from Solid
|
|
43
|
+
|
|
44
|
+
The output has the shape Solid 2.0's `@solidjs/compiler` produces: a static
|
|
45
|
+
template per element tree, cloned, then one binding per dynamic hole, with
|
|
46
|
+
delegated events.
|
|
47
|
+
|
|
48
|
+
Where it differs:
|
|
49
|
+
|
|
50
|
+
- A prop crosses a component boundary as a Cell, a function the component calls:
|
|
51
|
+
`props.name()`. Solid passes a getter on the props object and the component
|
|
52
|
+
reads `props.name`.
|
|
53
|
+
- What is reactive is decided from the binding a name resolves to (oxc's
|
|
54
|
+
`SymbolId`), never from how it is spelled. `createSignal` imported under
|
|
55
|
+
another name is still a signal.
|
|
56
|
+
- The checks run in the compiler, one file at a time, and print a code with a
|
|
57
|
+
docs page. See [docs/README.md](./docs/README.md).
|
|
58
|
+
|
|
59
|
+
## Writing code the compiler understands
|
|
60
|
+
|
|
61
|
+
Call an accessor where you want its value. The compiler wraps each JSX
|
|
62
|
+
expression in its own tracked scope, so `{count() * 2}` updates when `count`
|
|
63
|
+
changes. Code outside JSX is left as written, so a derived value there is a
|
|
64
|
+
function or a memo:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
import { createMemo, createSignal } from "@barqjs/core";
|
|
68
|
+
|
|
69
|
+
const [count, setCount] = createSignal(0);
|
|
70
|
+
const doubled = createMemo(() => count() * 2);
|
|
71
|
+
|
|
72
|
+
export const Counter = () => (
|
|
73
|
+
<button type="button" onClick={() => setCount(count() + 1)}>
|
|
74
|
+
{count()} doubled is {doubled()}
|
|
75
|
+
</button>
|
|
76
|
+
);
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Passing the accessor itself, `{count}`, is also live. Using it as a value,
|
|
80
|
+
`count * 2` or `` `${count}` ``, is a bug that
|
|
81
|
+
[BARQ001](./docs/BARQ001.md) reports.
|
|
82
|
+
|
|
83
|
+
## API
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import { transform } from "@barqjs/compiler";
|
|
87
|
+
|
|
88
|
+
const { code, map, warnings, diagnostics } = transform(source, {
|
|
89
|
+
filename: "App.tsx",
|
|
90
|
+
sourcemap: true,
|
|
91
|
+
dev: false,
|
|
92
|
+
ssr: false,
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`transform(code, options)` compiles one module. The options a caller sets:
|
|
97
|
+
|
|
98
|
+
- `filename`: used in diagnostics and source maps. The accessor and props checks
|
|
99
|
+
run only when it ends in `.jsx` or `.tsx`.
|
|
100
|
+
- `sourcemap`: return `map`. Without it `map` is absent, not `null`.
|
|
101
|
+
- `ssr`: emit the string backend for the server. In Vite this is per module, so
|
|
102
|
+
the plugin reads it from the transform hook rather than from its own options.
|
|
103
|
+
- `hydratable`: emit the markers a server-rendered page hydrates against. Off by
|
|
104
|
+
default, so a page that is never hydrated does not pay for them.
|
|
105
|
+
- `dev`: the development build. Turns on the dev-only diagnostics, template
|
|
106
|
+
labels and source locations.
|
|
107
|
+
- `diagnostics`: run the source-level checks. Defaults to `dev`; set it in CI to
|
|
108
|
+
run them on a production build.
|
|
109
|
+
- `checks`, `defaultCategory`, `strictCss`: change the level of a code. See
|
|
110
|
+
[docs/README.md](./docs/README.md#changing-a-level-for-the-whole-project).
|
|
111
|
+
- `routes`: the route patterns [BARQ013](./docs/BARQ013.md) checks `<Link to>`
|
|
112
|
+
against. Absent turns the check off.
|
|
113
|
+
- `moduleSource`: where the emitted code imports the renderer from. Defaults
|
|
114
|
+
to `@barqjs/web`.
|
|
115
|
+
- `coreSource`: where the emitted code imports the reactive calls (`props`,
|
|
116
|
+
`cell`, `block`, `bindEffect`, `createComponent`) and the components an
|
|
117
|
+
author imports from. Defaults to `@barqjs/core`.
|
|
118
|
+
- `target`: `"dom"` (the default) or `"universal"`. A universal module creates
|
|
119
|
+
each node with `createElement` or `createTextNode`, places it with
|
|
120
|
+
`insertNode`, and writes every attribute, property and event with one
|
|
121
|
+
`setProp` call under the name the author wrote, all imported from
|
|
122
|
+
`moduleSource`, which is then a module that exports what
|
|
123
|
+
`@barqjs/universal`'s `createRenderer` returned. `bind:` and a form `action`
|
|
124
|
+
are errors there ([BARQ027](./docs/BARQ027.md)), as are `ssr`, `hydratable`
|
|
125
|
+
and `interp` ([BARQ028](./docs/BARQ028.md)).
|
|
126
|
+
- `renderers`: per-file renderer selection, a list of
|
|
127
|
+
`{ include, target, moduleSource }`. A file whose name matches one of an
|
|
128
|
+
entry's `include` globs compiles for that entry's `target` (`"universal"` by
|
|
129
|
+
default) and `moduleSource`, and the first entry that matches wins. A file
|
|
130
|
+
an entry gives to the universal target is compiled without `ssr` and
|
|
131
|
+
`hydratable`, which keep describing the build's document files.
|
|
132
|
+
- `boundaries`: components whose children compile for another renderer than
|
|
133
|
+
the JSX around them, a list of `{ source, name, target, moduleSource }`. An
|
|
134
|
+
element whose tag resolves to the import `name` from `source` (a named
|
|
135
|
+
import, a renamed one, or a member of a namespace import, and never a local
|
|
136
|
+
binding of the same name) compiles for the module's renderer, and its JSX
|
|
137
|
+
children and `children` prop compile for the entry's `target` and
|
|
138
|
+
`moduleSource`. Boundaries nest. The children stay lazy, so the component
|
|
139
|
+
creates them where it reads `props.children`, inside its own renderer's
|
|
140
|
+
root. A module that writes no boundary compiles exactly as it would without
|
|
141
|
+
the option. Under `ssr` the boundary renders and a universal boundary's
|
|
142
|
+
children are left out of the server module; `@barqjs/vite` also reads
|
|
143
|
+
`"barq": { "boundaries": [...] }` from a dependency's `package.json`.
|
|
144
|
+
[DESIGN.md](./DESIGN.md#8-renderer-boundaries-and-claimed-intrinsics) has the emission.
|
|
145
|
+
- `intrinsics`: tags a renderer claims, a list of
|
|
146
|
+
`{ tags, claimUnknown, target, moduleSource }`. Outside every boundary, a
|
|
147
|
+
tree of intrinsic elements whose root tag one entry claims, and the
|
|
148
|
+
document does not have, compiles for that entry's renderer wherever it is
|
|
149
|
+
written, so `function Box() { return <mesh /> }` is a scene object in a page
|
|
150
|
+
file. A tag the document also has (`line`, `audio`, `path`, `source`) is the
|
|
151
|
+
renderer's only when the tree under it holds a tag that renderer alone
|
|
152
|
+
claims, and never under an `<svg>`. With `claimUnknown`, an entry also takes
|
|
153
|
+
any lowercase tag without a hyphen that no entry names and the document does
|
|
154
|
+
not have. A tag with a hyphen is always the document's. JSX written inside a
|
|
155
|
+
claimed tree follows it, and so does a component such as `<Show>` whose JSX
|
|
156
|
+
all went to one renderer. Two entries claiming one tag is
|
|
157
|
+
[BARQ029](./docs/BARQ029.md), and the tree stays the document's.
|
|
158
|
+
- `templates`: `false` emits `element()` calls instead of cloned templates.
|
|
159
|
+
- `optimize`: `0` turns every optimisation off. The output is larger and slower
|
|
160
|
+
and never behaves differently.
|
|
161
|
+
|
|
162
|
+
The rest (`env`, `root`, `serverFns`, the other `*Source` names, `cssExports`,
|
|
163
|
+
`cssImports`, `ownership`, `addresses`, `interp`, `passes`) are set by
|
|
164
|
+
`@barqjs/vite` and documented in `index.d.ts`. An option the compiler does not
|
|
165
|
+
know throws, and the message names the closest one, so `sourceMap` is reported
|
|
166
|
+
as a misspelling of `sourcemap`.
|
|
167
|
+
|
|
168
|
+
The result:
|
|
169
|
+
|
|
170
|
+
- `code`: the compiled module.
|
|
171
|
+
- `map`: the source map, when asked for.
|
|
172
|
+
- `diagnostics`: structured records with `code`, `severity`, `message`, the
|
|
173
|
+
span (`line`, `column`, `endLine`, `endColumn`, `pos`, `end`) and `docs`, a
|
|
174
|
+
link to the page for the code.
|
|
175
|
+
- `warnings`: the same set as `file:line:col: CODE level: message` strings.
|
|
176
|
+
- `labels`, `css` and the side outputs the options above ask for.
|
|
177
|
+
|
|
178
|
+
A syntax error throws instead of returning.
|
|
179
|
+
|
|
180
|
+
The package also exports the pieces `@barqjs/vite` builds on:
|
|
181
|
+
|
|
182
|
+
- `diagnosticCodes()`: every code, with its level, summary and docs URL.
|
|
183
|
+
- `routeTree(root, dir, outFile?, writeIds?)`: scans a routes directory and
|
|
184
|
+
returns the source of `routeTree.gen.ts`, the route patterns and any warnings.
|
|
185
|
+
- `routeSplit(source, filename, specifier, forClient?, splitComponents?)`: splits
|
|
186
|
+
a route module so its components load lazily, and deletes its `server`
|
|
187
|
+
handlers from the client half.
|
|
188
|
+
- `middlewareSplit(source, filename, startSource?)`: the client half of a module
|
|
189
|
+
that declares middleware, with `.server(...)` removed.
|
|
190
|
+
- `orderCss(css, layers?)` and `layerOrder(sheets)`: order the atoms and cascade
|
|
191
|
+
layers of a bundled stylesheet.
|
|
192
|
+
|
|
193
|
+
### Deeply nested input
|
|
194
|
+
|
|
195
|
+
oxc's parser and code generator recurse without a depth limit. `transform()`
|
|
196
|
+
estimates the nesting depth with a byte scan and compiles a file that could
|
|
197
|
+
overflow the caller's stack on a thread sized for it. A file nested past the
|
|
198
|
+
limit fails with an error that names the depth, instead of crashing the process.
|
|
199
|
+
Ordinary files never leave the calling thread. The per-level stack costs the
|
|
200
|
+
sizing uses are measured and recorded in `src/compile.rs`.
|
|
201
|
+
|
|
202
|
+
### Bundling
|
|
203
|
+
|
|
204
|
+
The generated `index.js` holds one guarded `require()` per platform napi-rs
|
|
205
|
+
knows. `@barqjs/vite` loads it with `createRequire`, so an application bundle
|
|
206
|
+
never includes it. A tool that bundles code importing this package directly
|
|
207
|
+
should mark it external.
|
|
208
|
+
|
|
209
|
+
## Building from source
|
|
210
|
+
|
|
211
|
+
A Rust toolchain is required. `@napi-rs/cli` needs Node on `PATH`
|
|
212
|
+
(`^20.17.0 || ^22.13.0 || >= 23.5.0`) even when it is run through Bun.
|
|
213
|
+
|
|
214
|
+
```sh
|
|
215
|
+
bun run build # napi build --platform --release
|
|
216
|
+
bun run build:debug # napi build --platform, much faster, same file names
|
|
217
|
+
bun test # the differential harness, needs the binding built first
|
|
218
|
+
bun run test # cargo fmt --check, clippy, cargo test, then bun test
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`index.js`, `index.d.ts` and `barq-compiler.<triple>.node` are build output and
|
|
222
|
+
are not committed. Until one of the build commands has run, the test harness
|
|
223
|
+
fails with a message saying so, and `@barqjs/vite` throws naming the command.
|
|
224
|
+
|
|
225
|
+
The fixture corpus the harness runs is described in
|
|
226
|
+
[fixtures/README.md](./fixtures/README.md).
|
package/docs/BARQ001.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# BARQ001: An accessor is used as a value without being called
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `count` is an accessor, and here the function itself is used as the value. In a string
|
|
8
|
+
> it prints its own source text and in arithmetic it gives `NaN`. Call it: `count()`.
|
|
9
|
+
|
|
10
|
+
## Failing example
|
|
11
|
+
|
|
12
|
+
```tsx
|
|
13
|
+
import { createSignal } from "@barqjs/core";
|
|
14
|
+
|
|
15
|
+
const [count] = createSignal(0);
|
|
16
|
+
|
|
17
|
+
export const Total = () => <p>{`total: ${count}`}</p>;
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Fixed example
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { createSignal } from "@barqjs/core";
|
|
24
|
+
|
|
25
|
+
const [count] = createSignal(0);
|
|
26
|
+
|
|
27
|
+
export const Total = () => <p>{`total: ${count()}`}</p>;
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Why this rule exists
|
|
31
|
+
|
|
32
|
+
An accessor is a function, and JavaScript turns a function into a string or a number
|
|
33
|
+
without complaint: `` `${count}` `` puts the accessor's source text on the page and
|
|
34
|
+
`count * 2` is `NaN`. Neither throws, and TypeScript accepts the string forms. The same
|
|
35
|
+
applies to a prop, which is a Cell: write `props.count()`, not `props.count`, inside a
|
|
36
|
+
string or a calculation.
|
|
37
|
+
|
|
38
|
+
Passing the accessor itself to JSX is correct and is not reported: `<p>{count}</p>` and
|
|
39
|
+
`<div id={count}>` both stay up to date.
|
|
40
|
+
|
|
41
|
+
## Silencing one line
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
import { createSignal } from "@barqjs/core";
|
|
45
|
+
|
|
46
|
+
const [count] = createSignal(0);
|
|
47
|
+
|
|
48
|
+
// barq-ignore-next-line BARQ001 (the debug panel shows the source text)
|
|
49
|
+
export const source = `${count}`;
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
53
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ001 (reason) */}` on the line
|
|
54
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
55
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ002.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# BARQ002: An accessor is used as a condition, which is always true
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `loading` is an accessor, and a function is always truthy, so this condition is always
|
|
8
|
+
> true and its other branch never runs. Call it: `loading()`.
|
|
9
|
+
|
|
10
|
+
## Failing example
|
|
11
|
+
|
|
12
|
+
```tsx
|
|
13
|
+
import { createSignal } from "@barqjs/core";
|
|
14
|
+
|
|
15
|
+
const [loading] = createSignal(true);
|
|
16
|
+
|
|
17
|
+
export const Status = () => <p>{loading ? "Loading" : "Ready"}</p>;
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Fixed example
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { createSignal } from "@barqjs/core";
|
|
24
|
+
|
|
25
|
+
const [loading] = createSignal(true);
|
|
26
|
+
|
|
27
|
+
export const Status = () => <p>{loading() ? "Loading" : "Ready"}</p>;
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Why this rule exists
|
|
31
|
+
|
|
32
|
+
A function is always truthy. `if (loading)`, `loading ? a : b`, `loading && x`, `!loading`
|
|
33
|
+
and a loop that tests an accessor therefore never change with the signal: one branch is
|
|
34
|
+
dead from the start, and a `while (loading)` never ends.
|
|
35
|
+
|
|
36
|
+
A prop is not reported here, because `props.label ? a : b` is how a component asks whether
|
|
37
|
+
an optional prop was passed at all.
|
|
38
|
+
|
|
39
|
+
## Silencing one line
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
import { createSignal } from "@barqjs/core";
|
|
43
|
+
|
|
44
|
+
const [loading] = createSignal(true);
|
|
45
|
+
|
|
46
|
+
// barq-ignore-next-line BARQ002 (checking that the accessor exists)
|
|
47
|
+
export const present = loading ? "yes" : "no";
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
51
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ002 (reason) */}` on the line
|
|
52
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
53
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ003.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# BARQ003: A property is read from an accessor instead of from its value
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `user` is an accessor, so `.email` is read from the function and not from the value it
|
|
8
|
+
> returns, and the result is `undefined`. Call it first: `user().email`.
|
|
9
|
+
|
|
10
|
+
## Failing example
|
|
11
|
+
|
|
12
|
+
```tsx
|
|
13
|
+
import { createSignal } from "@barqjs/core";
|
|
14
|
+
|
|
15
|
+
const [user] = createSignal({ email: "salama@example.com" });
|
|
16
|
+
|
|
17
|
+
export const Email = () => <p>{user.email}</p>;
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Fixed example
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { createSignal } from "@barqjs/core";
|
|
24
|
+
|
|
25
|
+
const [user] = createSignal({ email: "salama@example.com" });
|
|
26
|
+
|
|
27
|
+
export const Email = () => <p>{user().email}</p>;
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Why this rule exists
|
|
31
|
+
|
|
32
|
+
The value is behind the call, so `user.email` asks the function for a property it does
|
|
33
|
+
not have and the page shows nothing. Habits from other libraries land here too: an
|
|
34
|
+
accessor has no `.value`, `.set` or `.peek`, and writing goes through the setter that
|
|
35
|
+
`createSignal` returns beside it. A prop works the same way: `props.user.email` has to be
|
|
36
|
+
`props.user().email`.
|
|
37
|
+
|
|
38
|
+
`items.length` is reported too, with its own message. Every function has a `length`, so it
|
|
39
|
+
never comes back `undefined`: it is the accessor's parameter count, `0`, and a list that
|
|
40
|
+
shows `0` items has nothing else wrong with it. Write `items().length`. `user.name` is not
|
|
41
|
+
reported, because a function's own `name` is sometimes read on purpose; write
|
|
42
|
+
`user().name` for the value's.
|
|
43
|
+
|
|
44
|
+
## Silencing one line
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
import { createSignal } from "@barqjs/core";
|
|
48
|
+
|
|
49
|
+
const [user] = createSignal({ email: "salama@example.com" });
|
|
50
|
+
|
|
51
|
+
// barq-ignore-next-line BARQ003 (reading a label attached to the function)
|
|
52
|
+
export const label = user.label;
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
56
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ003 (reason) */}` on the line
|
|
57
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
58
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ004.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# BARQ004: A `<For>` row reads a field once, which goes stale if `each` holds store objects
|
|
2
|
+
|
|
3
|
+
**Level:** note · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `<For>` reads a field of this row once, when the row is built, and the compiler cannot
|
|
8
|
+
> tell where the items in `each` come from. If they are store objects, changing that field
|
|
9
|
+
> in place leaves the row showing the old value. Read the field where it is shown, as
|
|
10
|
+
> `{row.name}` in the row callback's JSX, or key the list and read the row by calling it:
|
|
11
|
+
> `keyed={(row) => row.id}` with `row().name`.
|
|
12
|
+
|
|
13
|
+
## Failing example
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { For, createStore } from "@barqjs/core";
|
|
17
|
+
|
|
18
|
+
const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
|
|
19
|
+
|
|
20
|
+
export const List = () => (
|
|
21
|
+
<ul>
|
|
22
|
+
<For each={state.rows}>{({ name }) => <li>{name}</li>}</For>
|
|
23
|
+
</ul>
|
|
24
|
+
);
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
import { For, createStore } from "@barqjs/core";
|
|
29
|
+
|
|
30
|
+
const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
|
|
31
|
+
|
|
32
|
+
export const List = () => (
|
|
33
|
+
<ul>
|
|
34
|
+
<For each={state.rows}>
|
|
35
|
+
{(row) => {
|
|
36
|
+
const label = row.name.toUpperCase();
|
|
37
|
+
return <li>{label}</li>;
|
|
38
|
+
}}
|
|
39
|
+
</For>
|
|
40
|
+
</ul>
|
|
41
|
+
);
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Fixed example
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
import { For, createStore } from "@barqjs/core";
|
|
48
|
+
|
|
49
|
+
const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
|
|
50
|
+
|
|
51
|
+
export const List = () => (
|
|
52
|
+
<ul>
|
|
53
|
+
<For each={state.rows}>{(row) => <li>{row.name}</li>}</For>
|
|
54
|
+
</ul>
|
|
55
|
+
);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
import { For, createStore } from "@barqjs/core";
|
|
60
|
+
|
|
61
|
+
const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
|
|
62
|
+
|
|
63
|
+
export const List = () => (
|
|
64
|
+
<ul>
|
|
65
|
+
<For each={state.rows} keyed={(row) => row.id}>
|
|
66
|
+
{(row) => <li>{row().name}</li>}
|
|
67
|
+
</For>
|
|
68
|
+
</ul>
|
|
69
|
+
);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Why this rule exists
|
|
73
|
+
|
|
74
|
+
Without `keyed`, a row is identified by the item itself and receives it as a plain value.
|
|
75
|
+
A store changes fields in place: the item stays the same object, so the row is kept rather
|
|
76
|
+
than built again. What the row shows is then up to where each field is read.
|
|
77
|
+
|
|
78
|
+
A field read in a hole of the row callback, a child like `{row.name}`, an attribute like
|
|
79
|
+
`title={row.name}`, or a component prop, is compiled as a read that runs again when the
|
|
80
|
+
field changes, so that row follows the store and nothing is reported. That holds for a
|
|
81
|
+
callback written inline and for one passed by name, `{renderRow}`, alike. A field read
|
|
82
|
+
anywhere the row reads it only while it is built is reported:
|
|
83
|
+
|
|
84
|
+
- a destructured parameter, `({ name }) => …`, or `const { name } = row`;
|
|
85
|
+
- a read outside the JSX, `const name = row.name`, or a row handed to a function there;
|
|
86
|
+
- a read that picks the JSX, `row.done ? <s/> : <li/>`, or the tag, `<row.Icon />`;
|
|
87
|
+
- a callback the module does not show, such as an import, whose reads cannot be seen.
|
|
88
|
+
|
|
89
|
+
Handlers, `ref`, `bind:` and a form's `action` are handed over once whatever their
|
|
90
|
+
source, a signal's included, so a row field read there is not reported.
|
|
91
|
+
|
|
92
|
+
The note needs both halves: a callback that reads a field once, and rows the compiler
|
|
93
|
+
cannot prove are plain values. Rows written as an array literal are plain, and a `<For>`
|
|
94
|
+
over them is not reported. With `keyed={(row) => row.id}` or `keyed={false}` the row
|
|
95
|
+
receives an accessor, `row().name` is read again when the field changes, and nothing is
|
|
96
|
+
reported.
|
|
97
|
+
|
|
98
|
+
## Silencing one line
|
|
99
|
+
|
|
100
|
+
```tsx
|
|
101
|
+
import { For, createStore } from "@barqjs/core";
|
|
102
|
+
|
|
103
|
+
const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
|
|
104
|
+
|
|
105
|
+
export const List = () => (
|
|
106
|
+
<ul>
|
|
107
|
+
{/* barq-ignore-next-line BARQ004 (rows are replaced, never changed in place) */}
|
|
108
|
+
<For each={state.rows}>{({ name }) => <li>{name}</li>}</For>
|
|
109
|
+
</ul>
|
|
110
|
+
);
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
114
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ004 (reason) */}` on the line
|
|
115
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
116
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ005.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# BARQ005: A destructured prop is used as a value, or called where it may not be a function
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `text` comes from destructuring the props, so it is the prop's Cell, a function you call,
|
|
8
|
+
> and here the function itself is used as the value. In a string it prints its own source
|
|
9
|
+
> text and in arithmetic it gives `NaN`. Call it: `text()`.
|
|
10
|
+
|
|
11
|
+
The rule reports at the misuse, and the message names what goes wrong there:
|
|
12
|
+
|
|
13
|
+
- A destructured name used as a value: in a template literal, with an arithmetic,
|
|
14
|
+
concatenating or relational operator, with unary `-`, `+` or `~`, or with a property read
|
|
15
|
+
from it (`text.length`). These are the positions where `props.text` gets
|
|
16
|
+
[BARQ001](BARQ001.md) or [BARQ003](BARQ003.md).
|
|
17
|
+
- A name with a default that is a literal and not a function, `{ tone = "warm" }`, used as
|
|
18
|
+
a value: it is the default when the prop is missing and a function when it is passed, so
|
|
19
|
+
the use is wrong whenever the prop is passed.
|
|
20
|
+
- The same name called, `tone()`: it throws when the prop is missing, because the default
|
|
21
|
+
is not a function.
|
|
22
|
+
- A pattern under a prop's key, `{ user: { name } }` or `{ items: [first] }`: it takes the
|
|
23
|
+
prop's function apart, which is wrong whether the prop is passed or not.
|
|
24
|
+
|
|
25
|
+
## Failing example
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
export function Chip({ text }) {
|
|
29
|
+
return <span>{`#${text}`}</span>;
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Fixed example
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
export function Chip({ text }) {
|
|
37
|
+
return <span>{`#${text()}`}</span>;
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Writing a destructured name where a function is accepted is correct and is not reported:
|
|
42
|
+
`{text}` as a JSX child or attribute, `text` passed to another function, `text()` anywhere.
|
|
43
|
+
A truthiness test such as `text ? … : …` asks whether the prop was passed, as it does for
|
|
44
|
+
`props.text`, and is not reported either.
|
|
45
|
+
|
|
46
|
+
To pass the remaining props on, leave out the ones the component reads with `omit`:
|
|
47
|
+
|
|
48
|
+
```tsx
|
|
49
|
+
import { omit } from "@barqjs/core";
|
|
50
|
+
|
|
51
|
+
export function Chip(props) {
|
|
52
|
+
const rest = omit(props, "tone");
|
|
53
|
+
return <span data-tone={props.tone?.() ?? "warm"} {...rest} />;
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Why this rule exists
|
|
58
|
+
|
|
59
|
+
A component receives each prop as a Cell: a function it calls to read the current value.
|
|
60
|
+
Destructuring copies those functions into local names, so `text` is a function. That is
|
|
61
|
+
what JSX wants, and it gives the function's source text or `NaN` everywhere a value is
|
|
62
|
+
needed. The checks for `props.name` ([BARQ001](BARQ001.md), [BARQ003](BARQ003.md)) cannot
|
|
63
|
+
follow the copies, so this rule reports the same positions for a destructured name.
|
|
64
|
+
|
|
65
|
+
A default in the pattern, `{ tone = "warm" }`, gives the name two kinds: the string
|
|
66
|
+
`"warm"` when the prop is missing and a function when it is passed. Calling it fails in the
|
|
67
|
+
first case and using it as a value fails in the second. Read such a prop with its default
|
|
68
|
+
where it is used instead:
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
export function Chip({ tone }) {
|
|
72
|
+
return <span data-tone={tone?.() ?? "warm"} />;
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A default that is itself a function, or a name the rule cannot see the value of, is not
|
|
77
|
+
reported, and neither is a name the component tests with `typeof` or reassigns.
|
|
78
|
+
|
|
79
|
+
## Silencing one line
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
export function Chip({ text }) {
|
|
83
|
+
// barq-ignore-next-line BARQ005 (the debug panel shows the source text)
|
|
84
|
+
const label = `${text}`;
|
|
85
|
+
return <span>{label}</span>;
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
90
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ005 (reason) */}` on the line
|
|
91
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
92
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ006.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# BARQ006: removed
|
|
2
|
+
|
|
3
|
+
The compiler does not report this code. [All codes](README.md)
|
|
4
|
+
|
|
5
|
+
BARQ006 warned that `<Dynamic>` read every prop once and handed the component it rendered
|
|
6
|
+
values that never updated. barq no longer exports `<Dynamic>` (see [BARQ025](BARQ025.md)).
|
|
7
|
+
The component the `dynamic` factory returns passes each prop through as the same Cell it
|
|
8
|
+
received, so what it renders reads current values and there is nothing to warn about:
|
|
9
|
+
|
|
10
|
+
```tsx
|
|
11
|
+
import { createSignal } from "@barqjs/core";
|
|
12
|
+
import { dynamic } from "@barqjs/web";
|
|
13
|
+
|
|
14
|
+
const [total] = createSignal(0);
|
|
15
|
+
const Output = dynamic(() => "output");
|
|
16
|
+
|
|
17
|
+
export const Total = () => <Output value={total()} />;
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## If a comment still names it
|
|
21
|
+
|
|
22
|
+
`BARQ006` is not a code the compiler knows, so a comment that names it is reported as
|
|
23
|
+
[BARQ009](BARQ009.md) and silences nothing. Delete the comment.
|