@barefootjs/jsx 0.38.0 → 0.39.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.
Files changed (87) hide show
  1. package/dist/action-accessor.d.ts +159 -0
  2. package/dist/action-accessor.d.ts.map +1 -0
  3. package/dist/adapters/jsx-adapter.d.ts.map +1 -1
  4. package/dist/analyzer.d.ts +30 -1
  5. package/dist/analyzer.d.ts.map +1 -1
  6. package/dist/async-action-refusal.d.ts +45 -0
  7. package/dist/async-action-refusal.d.ts.map +1 -0
  8. package/dist/compiler.d.ts.map +1 -1
  9. package/dist/debug.d.ts +61 -5
  10. package/dist/debug.d.ts.map +1 -1
  11. package/dist/errors.d.ts +4 -0
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/format-date-refusal.d.ts +2 -6
  14. package/dist/format-date-refusal.d.ts.map +1 -1
  15. package/dist/index.d.ts +2 -2
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1056 -344
  18. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  19. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  20. package/dist/ir-to-client-js/compute-inlinability.d.ts.map +1 -1
  21. package/dist/ir-to-client-js/compute-scope.d.ts.map +1 -1
  22. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts +2 -0
  23. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts.map +1 -1
  24. package/dist/ir-to-client-js/csr-substitute.d.ts.map +1 -1
  25. package/dist/ir-to-client-js/declaration-sort.d.ts +2 -1
  26. package/dist/ir-to-client-js/declaration-sort.d.ts.map +1 -1
  27. package/dist/ir-to-client-js/emit-module-level.d.ts.map +1 -1
  28. package/dist/ir-to-client-js/emit-registration.d.ts.map +1 -1
  29. package/dist/ir-to-client-js/plan/declaration-emit.d.ts +7 -5
  30. package/dist/ir-to-client-js/plan/declaration-emit.d.ts.map +1 -1
  31. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  33. package/dist/ir-to-client-js/types.d.ts +4 -0
  34. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  35. package/dist/ir-to-client-js/utils.d.ts +41 -2
  36. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  37. package/dist/jsx-to-ir.d.ts.map +1 -1
  38. package/dist/signal-initializer.d.ts +24 -0
  39. package/dist/signal-initializer.d.ts.map +1 -0
  40. package/dist/template-position-walk.d.ts +68 -0
  41. package/dist/template-position-walk.d.ts.map +1 -0
  42. package/dist/types.d.ts +51 -0
  43. package/dist/types.d.ts.map +1 -1
  44. package/package.json +2 -2
  45. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +191 -1
  46. package/src/__tests__/action-accessor.test.ts +166 -0
  47. package/src/__tests__/create-mutation.test.ts +220 -0
  48. package/src/__tests__/create-query.test.ts +644 -0
  49. package/src/__tests__/csr-fragment-root-scope-shape.test.ts +156 -0
  50. package/src/__tests__/debug.test.ts +222 -0
  51. package/src/__tests__/doc-examples.test.ts +66 -3
  52. package/src/__tests__/props-destructuring.test.ts +79 -4
  53. package/src/__tests__/reactive-factory-arity.test.ts +311 -0
  54. package/src/__tests__/ssr-portal-ref-callback.test.ts +5 -3
  55. package/src/action-accessor.ts +289 -0
  56. package/src/adapters/jsx-adapter.ts +17 -0
  57. package/src/analyzer.ts +558 -33
  58. package/src/async-action-refusal.ts +254 -0
  59. package/src/compiler.ts +3 -0
  60. package/src/debug.ts +318 -103
  61. package/src/errors.ts +39 -0
  62. package/src/format-date-refusal.ts +6 -125
  63. package/src/index.ts +2 -1
  64. package/src/ir-to-client-js/build-references.ts +6 -2
  65. package/src/ir-to-client-js/collect-elements.ts +1 -0
  66. package/src/ir-to-client-js/compute-inlinability.ts +2 -1
  67. package/src/ir-to-client-js/compute-scope.ts +3 -1
  68. package/src/ir-to-client-js/control-flow/plan/build-insert.ts +1 -0
  69. package/src/ir-to-client-js/control-flow/plan/insert.ts +2 -0
  70. package/src/ir-to-client-js/control-flow/stringify/insert.ts +1 -1
  71. package/src/ir-to-client-js/csr-substitute.ts +11 -3
  72. package/src/ir-to-client-js/declaration-sort.ts +7 -3
  73. package/src/ir-to-client-js/emit-module-level.ts +7 -4
  74. package/src/ir-to-client-js/emit-registration.ts +5 -10
  75. package/src/ir-to-client-js/index.ts +7 -2
  76. package/src/ir-to-client-js/phases/ref-callbacks.ts +1 -1
  77. package/src/ir-to-client-js/plan/build-declaration-emit.ts +16 -15
  78. package/src/ir-to-client-js/plan/declaration-emit.ts +7 -5
  79. package/src/ir-to-client-js/prop-handling.ts +4 -0
  80. package/src/ir-to-client-js/reactivity.ts +1 -0
  81. package/src/ir-to-client-js/stringify/declaration-emit.ts +14 -7
  82. package/src/ir-to-client-js/types.ts +4 -0
  83. package/src/ir-to-client-js/utils.ts +55 -7
  84. package/src/jsx-to-ir.ts +36 -2
  85. package/src/signal-initializer.ts +36 -0
  86. package/src/template-position-walk.ts +203 -0
  87. package/src/types.ts +52 -0
@@ -0,0 +1,254 @@
1
+ /**
2
+ * `checkAsyncActionReads` (#3165, BF117): a read of a query action in a
3
+ * template-lowered position is refused at compile time, uniformly across every
4
+ * adapter including Hono.
5
+ *
6
+ * `const [posts, fetchPosts] = createQuery(fn, options)` seeds `posts()` from
7
+ * `options.initial`. Since #3166, `fetchPosts.isPending()` / `fetchPosts.error()`
8
+ * are ALSO seeded (`false` / `undefined`, spec/async.md §7.3) when read as the
9
+ * WHOLE expression of a position where the seed renders like Hono: a
10
+ * condition (either accessor), or an ARIA boolean-state attribute
11
+ * (`isPending()` only). `action-accessor.ts`'s `seedableActionAccessorRead` is
12
+ * the one gate deciding that, for both this lift and the seed itself. Any
13
+ * other direct accessor read — a text child (`{fetchPosts.error()}`),
14
+ * `error()` in any attribute, `isPending()` in a non-ARIA-boolean attribute,
15
+ * a structured template attribute's ternary — has no sound seed and refuses
16
+ * here as before. Everything else is unchanged too: calling the action itself
17
+ * (`fetchPosts()`) still sends a request during render, and a compound or
18
+ * nested accessor read (`!fetchPosts.isPending()`, buried inside a memo) has
19
+ * no seed substitution yet, so a template position may still not:
20
+ *
21
+ * - read an accessor outside the positions above,
22
+ * - call the action (`fetchPosts()`),
23
+ * - read a memo or a component-local constant that reads the action, since
24
+ * every backend evaluates a memo or constant it renders, or
25
+ * - call a local function that reads the action.
26
+ *
27
+ * "Reads the action" is transitive through memos, constants and functions
28
+ * (a constant reading a memo reading the action counts). Passing the action,
29
+ * or a local function that reads it, as a value (`<Retry onRetry={fetchPosts} />`,
30
+ * `run={reload}`) is fine: nothing runs until the client calls it. A constant
31
+ * that only aliases one of them (`const run = fetchPosts`) is treated like its
32
+ * target. Any read inside an event handler or effect is fine too, since those
33
+ * only run on the client. A `/* @client *\/`-marked position is skipped by
34
+ * `walkTemplatePositions`: the read is deferred to the client.
35
+ *
36
+ * Other function-valued expressions that read the action are refused even when
37
+ * they are only passed on, because the walk cannot tell passing from calling
38
+ * during render (an array-method callback runs then): an inline arrow outside
39
+ * an `on*` prop (`run={() => fetchPosts()}`), and a constant holding arrows in an object or
40
+ * array literal (`const h = { run: () => fetchPosts() }`, `run={h.run}`). Name
41
+ * the function as a local instead, or mark the position `/* @client *\/`.
42
+ */
43
+
44
+ import type { IRNode, IRMetadata, CompilerError, SourceLocation } from './types.ts'
45
+ import type { ParsedExpr } from './expression-parser.ts'
46
+ import { ErrorCodes } from './errors.ts'
47
+ import { isEventHandlerName } from './event-handler-name.ts'
48
+ import { walkTemplatePositions } from './template-position-walk.ts'
49
+ import { seedableActionAccessorRead, collectActionNames, ACTION_ACCESSOR_NAMES, parsedExprChildren } from './action-accessor.ts'
50
+
51
+ /** What a template position read, for the diagnostic. */
52
+ type ActionRead =
53
+ | { kind: 'accessor'; action: string; accessor: string }
54
+ | { kind: 'call'; action: string }
55
+ | { kind: 'local'; name: string; declaration: 'memo' | 'constant' | 'function'; action: string }
56
+
57
+ /** A component-local declaration that reads a query action, and the action it reaches. */
58
+ interface ActionReader {
59
+ declaration: 'memo' | 'constant' | 'function'
60
+ action: string
61
+ }
62
+
63
+ /**
64
+ * The component-local declarations that read a query action, split by how a
65
+ * template position evaluates them: `values` (memos and constants whose value
66
+ * is computed when rendered, so a reference is a read) and `callables`
67
+ * (functions, and constants whose value is a function, whose body runs only
68
+ * when called).
69
+ */
70
+ interface ActionReaders {
71
+ values: ReadonlyMap<string, ActionReader>
72
+ callables: ReadonlyMap<string, ActionReader>
73
+ }
74
+
75
+ export function checkAsyncActionReads(root: IRNode, metadata: IRMetadata, errors: CompilerError[]): void {
76
+ // The action bindings a recognised factory produced DIRECTLY — the same
77
+ // set the seed pass (`seedActionAccessorReads`) recognises.
78
+ // Kept separate from `actions` below (which also grows through aliases):
79
+ // the seed substitution only ever rewrites a read of a DIRECT binding, so
80
+ // the "no longer refused" check here must match exactly that, not a wider
81
+ // alias-grown set — an aliased read (`const run = fetchPosts;
82
+ // run.isPending()`) stays refused below exactly as before #3166, since
83
+ // nothing seeds it structurally.
84
+ const directActions = collectActionNames(metadata.signals)
85
+ if (directActions.size === 0) return
86
+ const actions = new Set(directActions)
87
+ // `const run = fetchPosts` is the action under another name.
88
+ for (let grew = true; grew; ) {
89
+ grew = false
90
+ for (const constant of metadata.localConstants) {
91
+ const target = aliasTarget(constant)
92
+ if (target !== undefined && actions.has(target) && !actions.has(constant.name)) {
93
+ actions.add(constant.name)
94
+ grew = true
95
+ }
96
+ }
97
+ }
98
+ const readers = localsReadingActions(metadata, actions)
99
+ const seen = new Set<string>()
100
+ walkTemplatePositions(root, (position) => {
101
+ const { expr, loc, attrName } = position
102
+ if (attrName !== undefined && isEventHandlerName(attrName)) return
103
+ // #3166: a direct accessor read the shared gate admits is an ordinary
104
+ // seeded value (`seedActionAccessorReads` has usually already replaced
105
+ // it with its seed literal by now) — no refusal. The gate is the same
106
+ // function the seed pass calls, over the same walk, so the two cannot
107
+ // disagree. Anything it does not admit — a compound/nested use, or a
108
+ // direct read at a position where the seed would not render like Hono
109
+ // (a text child, `error()` in an attribute, …) — falls through to
110
+ // `findActionRead` below, refused exactly as before.
111
+ if (seedableActionAccessorRead(position, directActions)) return
112
+ const read = findActionRead(expr, actions, readers, new Set())
113
+ if (read) pushDiagnostic(errors, seen, loc, read)
114
+ })
115
+ }
116
+
117
+ /**
118
+ * The component-local memos, constants and functions that read a query
119
+ * action, directly or through another such declaration (a fixpoint). Uses each
120
+ * declaration's free identifiers, so a block-bodied memo or function is
121
+ * covered too: mentioning the action, or a declaration that reads it, is
122
+ * enough, since the only things a body can do with the action are read an
123
+ * accessor, send a request, or pass it on. JSX-valued constants and functions
124
+ * are skipped: they are inlined into the IR, where the walk sees their reads
125
+ * directly. `isModule` is not consulted: for a function it only marks a
126
+ * candidate for hoisting (`compute-scope.ts` decides), and a declaration that
127
+ * really lives at module scope cannot name a component's action anyway.
128
+ */
129
+ function localsReadingActions(metadata: IRMetadata, actions: ReadonlySet<string>): ActionReaders {
130
+ const values = new Map<string, ActionReader>()
131
+ const callables = new Map<string, ActionReader>()
132
+ const candidates: Array<{
133
+ name: string
134
+ declaration: ActionReader['declaration']
135
+ callable: boolean
136
+ freeIds: Iterable<string>
137
+ aliasOf?: string
138
+ }> = []
139
+ for (const memo of metadata.memos) {
140
+ candidates.push({ name: memo.name, declaration: 'memo', callable: false, freeIds: memo.computationFreeIdentifiers ?? [] })
141
+ }
142
+ for (const constant of metadata.localConstants) {
143
+ if (constant.isJsx || constant.isJsxFunction || actions.has(constant.name)) continue
144
+ candidates.push({
145
+ name: constant.name,
146
+ declaration: 'constant',
147
+ callable: constant.isFunctionValue === true,
148
+ freeIds: constant.freeIdentifiers ?? [],
149
+ aliasOf: aliasTarget(constant),
150
+ })
151
+ }
152
+ for (const fn of metadata.localFunctions) {
153
+ if (fn.isJsxFunction) continue
154
+ candidates.push({ name: fn.name, declaration: 'function', callable: true, freeIds: fn.freeIdentifiers ?? [] })
155
+ }
156
+
157
+ let changed = true
158
+ while (changed) {
159
+ changed = false
160
+ for (const candidate of candidates) {
161
+ if (values.has(candidate.name) || callables.has(candidate.name)) continue
162
+ if (candidate.aliasOf !== undefined) {
163
+ // An alias reads the action only if its target does, and is called or
164
+ // referenced the same way.
165
+ const target = values.get(candidate.aliasOf) ?? callables.get(candidate.aliasOf)
166
+ if (target === undefined) continue
167
+ const reader = { declaration: candidate.declaration, action: target.action }
168
+ if (callables.has(candidate.aliasOf)) callables.set(candidate.name, reader)
169
+ else values.set(candidate.name, reader)
170
+ changed = true
171
+ continue
172
+ }
173
+ for (const id of candidate.freeIds) {
174
+ if (id === candidate.name) continue
175
+ const action = actions.has(id) ? id : (values.get(id) ?? callables.get(id))?.action
176
+ if (action === undefined) continue
177
+ const reader = { declaration: candidate.declaration, action }
178
+ if (candidate.callable) callables.set(candidate.name, reader)
179
+ else values.set(candidate.name, reader)
180
+ changed = true
181
+ break
182
+ }
183
+ }
184
+ }
185
+ return { values, callables }
186
+ }
187
+
188
+ /** The name a constant only aliases (`const run = fetchPosts`), if it is one. */
189
+ function aliasTarget(constant: IRMetadata['localConstants'][number]): string | undefined {
190
+ return constant.parsed?.kind === 'identifier' ? constant.parsed.name : undefined
191
+ }
192
+
193
+ function findActionRead(
194
+ expr: ParsedExpr,
195
+ actions: ReadonlySet<string>,
196
+ readers: ActionReaders,
197
+ bound: ReadonlySet<string>,
198
+ ): ActionRead | null {
199
+ switch (expr.kind) {
200
+ case 'identifier': {
201
+ if (bound.has(expr.name)) return null
202
+ const reader = readers.values.get(expr.name)
203
+ return reader ? { kind: 'local', name: expr.name, ...reader } : null
204
+ }
205
+ case 'member':
206
+ if (
207
+ expr.object.kind === 'identifier' &&
208
+ actions.has(expr.object.name) &&
209
+ !bound.has(expr.object.name) &&
210
+ ACTION_ACCESSOR_NAMES.has(expr.property)
211
+ ) {
212
+ return { kind: 'accessor', action: expr.object.name, accessor: expr.property }
213
+ }
214
+ break
215
+ case 'call':
216
+ if (expr.callee.kind === 'identifier' && !bound.has(expr.callee.name)) {
217
+ if (actions.has(expr.callee.name)) return { kind: 'call', action: expr.callee.name }
218
+ const reader = readers.callables.get(expr.callee.name)
219
+ if (reader) return { kind: 'local', name: expr.callee.name, ...reader }
220
+ }
221
+ break
222
+ }
223
+ for (const child of parsedExprChildren(expr)) {
224
+ const read = findActionRead(child.expr, actions, readers, child.params ? new Set([...bound, ...child.params]) : bound)
225
+ if (read) return read
226
+ }
227
+ return null
228
+ }
229
+
230
+ function pushDiagnostic(errors: CompilerError[], seen: Set<string>, loc: SourceLocation, read: ActionRead): void {
231
+ const key = `${loc.start.line}:${loc.start.column}`
232
+ if (seen.has(key)) return
233
+ seen.add(key)
234
+ const what =
235
+ read.kind === 'accessor'
236
+ ? `'${read.action}.${read.accessor}' reads an async action's accessor`
237
+ : read.kind === 'call'
238
+ ? `'${read.action}()' calls an async action, which sends a request,`
239
+ : `${read.declaration} '${read.name}' reads the async action '${read.action}' and is used`
240
+ errors.push({
241
+ code: ErrorCodes.ASYNC_ACTION_READ_IN_TEMPLATE,
242
+ severity: 'error',
243
+ message:
244
+ `${what} in a template position. The request function never runs on the server, so ` +
245
+ `'${read.action}.isPending()' and '${read.action}.error()' have no value to render there yet.`,
246
+ loc,
247
+ suggestion: {
248
+ message:
249
+ 'Defer the read to the client with /* @client */, or read it inside an event handler or ' +
250
+ 'effect, which only run on the client.',
251
+ escape: [{ kind: 'client-directive' }],
252
+ },
253
+ })
254
+ }
package/src/compiler.ts CHANGED
@@ -29,6 +29,7 @@ import { extractSsrDefaults } from './ssr-defaults.ts'
29
29
  import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
30
30
  import { checkRichTypeMethodCalls, checkRichTypePropSerialization } from './rich-type-refusal.ts'
31
31
  import { checkAuthoredFormatDateCalls } from './format-date-refusal.ts'
32
+ import { checkAsyncActionReads } from './async-action-refusal.ts'
32
33
  import { ErrorCodes, createError } from './errors.ts'
33
34
  import { collectComponentNamesFromIR } from './ir-to-client-js/child-components.ts'
34
35
 
@@ -212,6 +213,7 @@ function compileMultipleComponents(
212
213
  checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
213
214
  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc)
214
215
  checkAuthoredFormatDateCalls(componentIR.root, componentIR.metadata, errors)
216
+ checkAsyncActionReads(componentIR.root, componentIR.metadata, errors)
215
217
 
216
218
  // #3141: decide once whether a component-call render root needs the
217
219
  // comment-based scope marker pair, same "right after clientAnalysis"
@@ -788,6 +790,7 @@ export function compileJSX(
788
790
  checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
789
791
  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc)
790
792
  checkAuthoredFormatDateCalls(componentIR.root, componentIR.metadata, errors)
793
+ checkAsyncActionReads(componentIR.root, componentIR.metadata, errors)
791
794
 
792
795
  // #3141: decide once whether a component-call render root needs the
793
796
  // comment-based scope marker pair, same "right after clientAnalysis"